Changelog

Clear 400 for over-long billing addresses on POST /cards.

A billing address exceeding the stored length limits used to fail with a generic 500 Failed to issue card. It is now rejected up front with 400 and a message naming the field. The limits are unchanged, now documented precisely: line1 + line2 together form one street line of at most 64 characters (62 when line2 is used, as they are joined with ", "), city ≤ 32, state ≤ 64, postalCode ≤ 16. Requests that previously succeeded are unaffected. See Issue Card.

KYC duplicate submissions return the existing cardholder.

POST /kyc/cardholders/form now answers a duplicate idNumber with HTTP 409 (previously 400) and returns the existing cardholderId and kycStatus in errors, so you can continue with that cardholder instead of waiting for the webhook. Concurrent submissions of the same idNumber are now serialized: only one cardholder is created, the others receive 409 with errors.reason = SUBMISSION_IN_PROGRESS. See Duplicate ID number.

KYC Form submission.

Deprecated POST /kyc/cardholders/manual in favor of POST /kyc/cardholders/form. The new endpoint accepts the user's basic information along with a third-party KYC report (e.g. Sumsub) for verification, replacing the previous manual document-only workflow.

eSIM API.

A new product line: browse a global eSIM plan catalog priced for your project, purchase with wallet balance, and deliver the install QR to your users. Endpoints: GET /esim/plans (catalog, project-specific priceUsd), POST /esim/purchase (supports X-Idempotency-Key — same semantics as funding/withdrawal), POST /esim/recharge (renews the eSIM's current plan only — plan switching is deliberately not exposed, as it would wipe remaining data), GET /esim/orders/{orderNo} (order state + QR lookup), and GET /esim/esims/{esimNo}/usage (near-real-time usage, synced at most once per minute). Fulfilment is asynchronous: three webhooks, ESIM_ISSUED, ESIM_RECHARGED, and ESIM_REFUNDED, deliver terminal order states. Three lifecycle webhooks keep you ahead of the user's data running out: ESIM_USAGE_ALERT (usage crossed a threshold), ESIM_EXPIRING (plan about to expire), and ESIM_EXPIRED (plan ended / data depleted).

Idempotent funding & withdrawal, plus operation lookup.

POST /cards/{cardId}/funding and POST /cards/{cardId}/withdrawal now accept an optional X-Idempotency-Key header — a same-key retry never moves funds twice, making network-timeout retries safe. Both responses now include an operationId when a key is supplied. A new endpoint, GET /operations/{idempotencyKey}, returns the recorded status (PROCESSING / COMPLETED / FAILED) of a funding or withdrawal so you can reconcile after a timeout. These keys are durable (no expiry); a definitively failed funding or withdrawal is terminal — retry with a new key. See Idempotency.

Non-ASCII cardholder names accepted on POST /cards.

Names containing Cyrillic, CJK, or other non-Latin letters (Иван Иванов, ثامر ثامر, …) used to be rejected with Invalid name format. They are now accepted and preserved in the response's cardholderName field. ASCII-only callers see no change. The name submitted to upstream card networks continues to be normalised to ASCII where the network requires it; that normalised value is internal and not exposed on the API response.

KYC cardholder verification endpoints.

New endpoints for identity verification before card issuance: POST /kyc/cardholders/auto (hosted flow via Didit), POST /kyc/cardholders/manual (bring-your-own documents), POST /kyc/presignedUploads (document upload), and GET /kyc/cardholders/{id} (status query). BINs that require KYC now enforce requireKycCardholder: true — cards cannot be issued until the cardholder reaches APPROVED status. A new CARDHOLDER_KYC_STATUS webhook fires on approval or rejection.