API Guide
Integration Best Practices
Error handling, idempotency, rate limiting, timeout configuration, and security best practices for DCMS API integration.
Error Handling
- Always check the
exceptionfield — even on HTTP 200, validate thatexceptionis null - Match on
errorCode— use machine-readable codes for branching, noterrorMessage(can change) - Retry 5xx errors — use exponential backoff with a maximum of 3 retries
- Do not retry 4xx errors — these are deterministic; retrying produces the same result
Idempotency
For critical operations (card issuance, transactions), include a unique requestId or txnId:
| Property | Detail |
|---|---|
| Purpose | Prevents duplicate processing on retry |
| Format | UUID or unique string per request |
| Behavior | Duplicate requests with the same ID return the same result |
| Scope | Applied to card issuance, transactions, PIN operations, wallet loads |
Rate Limiting
| Tier | Rate | Burst |
|---|---|---|
| Standard | 100 requests/second | 200 requests |
| High Volume | 500 requests/second | 1,000 requests |
| Custom | Negotiable | Based on traffic profile |
Rate limits are configured per tenant during onboarding. When exceeded, the API returns 429 Too Many Requests.
Timeouts
| Operation Type | Recommended Timeout |
|---|---|
| Card Status / Details | 5 seconds |
| Transaction Processing | 10 seconds |
| CBS Operations | 15 seconds |
| Report Generation | 30 seconds |
Security
Critical Security Rules
- Never log full card numbers, PINs, CVVs, or tokens
- Rotate JWT tokens — do not cache beyond expiry
- Use HTTPS only — TLS 1.2 minimum
- Validate SSL certificates — never disable verification
- Encrypt sensitive fields per the encryption spec from onboarding
- IP whitelisting — available for production environments