Best Practices

​

API integration

• Retry with exponential backoff. Retry 429 (honoring Retry-After) and 5xx; never retry 4xx other than 429 — those need a code or data fix, not a retry. The official SDKs do this by default.
• Always send an Idempotency-Key. Every POST should carry one, reused across retries of the same logical operation. Without it, a timed-out-then-retried payment can settle twice. The SDKs generate one per request automatically.
• Implement a circuit breaker. If error rate on a route exceeds a threshold (say 50% over 30s), stop calling for a cool-off window instead of hammering a degraded endpoint. This keeps you inside rate limits during incidents and speeds your own recovery.
• Log settlement_tx and request_id on every transaction. The transaction hash proves settlement on-chain; the request ID lets support trace any API call in minutes. Log both at the point of the call, structured, and keep them queryable.
• Alert on error rate, not single errors. Page on sustained INSUFFICIENT_CREDIT (collateral running low), any AML_DECLINED (needs human review), rising 429s (approaching limits), and webhook delivery gaps (your receiver may be down).

// Minimal structured transaction log — enough for any support escalation
logger.info("sohopay.payment", {
  payment_id: payment.paymentId,
  order_id: payment.orderId,
  status: payment.status,
  settlement_tx: payment.settlementTx,
  request_id: payment.requestId,
});

​

Agent key management

• Rotate on a fixed cadence. Quarterly for high-volume agents, at least annually for the rest — and immediately on any suspected compromise or when a team member with rotation access leaves.
• Pause before you rotate. Pause the agent, drain in-flight payments, rotate, verify a test payment, then resume. Rotating a live agent mid-payment can fail the in-flight signature.
• Monitor agent.key_rotated webhooks. Every rotation emits one. Alert on any rotation your team didn’t schedule — an unexpected event is your earliest compromise signal.
• Restrict who can rotate and revoke. Treat rotation and revocation like production deploy rights: named individuals, dashboard roles enforced, and every rotation recorded in your change log with who and why.
• Also rotate your API keys and webhook secrets. Same cadence, same access control. Overlap old and new keys briefly during rollout so nothing 401s mid-deploy.

​

Production readiness

​

Next steps