Skip to main content

​
Use the Correct Authentication Scope

Choose the right OAuth scope before making any API call. POST /v0/cards, PATCH /v0/cards/{id}, and the action endpoints require card/read_write; GET /v0/cards/{id} accepts card/read or card/read_write. Use the least-privileged scope appropriate to the operation. If your integration only needs to retrieve cards, use card/read and avoid provisioning broader write access.

​
Use Idempotency Keys on POST and PATCH

Always include a unique Idempotency-Key header on every POST /v0/cards request. Use a UUID (e.g., 550e8400-e29b-41d4-a716-446655440000). Key behaviors to be aware of:
  • If a request fails with a 4xx error (except 409 Conflict), the idempotency key was not consumed. Generate a new key before retrying — the same key can only be reused for the exact same request body.
  • If a request succeeds (200), reusing the same idempotency key returns the cached response without creating a duplicate card.
  • Omitting the Idempotency-Key header results in a 400 operation_not_allowed error.

​
Sequence Resource Creation Correctly

Because the API is synchronous and per-resource, you are responsible for sequencing. Create the Entity and the Account first, capture their IDs, and use them when creating the card. The card cannot be created until both the referenced entity and account exist, and the entity must already be linked to the account as an account holder or authorized user.

​
Use replacement_for for Replacement Cards

When issuing a replacement, set details.replacement_for to the card_id of the card being replaced on the new card’s creation request. The old card must already be in a closed status. This pattern means you do not need to create the new card first just to obtain its ID and then patch the old card.

​
Treat Expiry Dates as End-of-Month

Always set expiry_date to the last calendar day of the expiration month. This keeps reported expirations consistent with how card networks treat the expiry month.

​
Use metadata for Your Own Context

The optional metadata object is the supported place to store your own key-value context on a card, and it is one of only two fields editable after creation. Avoid encoding such context into immutable fields.\

​
Correcting an Accidentally Closed Card

The action endpoints exist primarily to support normal lifecycle progression. If a card is closed in error, moving it back to active (via /activate) or inactive (via /deactivate) is intended only as an error-correction path — it may not be enabled for your program during beta. If you close a card in error, contact your Lead representative to confirm whether the reopen path is available.