Sign in

v1

latestOpenAPI 3.0.12026-07-26106359429.8 KB
Compliance

Create a card

Beta: This endpoint is in beta and may change before general availability.

Creates a new card.

Business Rules

  • A new card is created in the active state. status is system-managed and cannot be set on create; status changes go through the status-transition endpoints.
  • details.replacement_for references an existing card that this card replaces. When provided, the referenced card must be in closed status at the time of the write and must not already be referenced by another card.

Idempotency

The Idempotency-Key header is required. Reusing a key with a different request body will return a 422 error.

post/v0/cards

Headers

Idempotency-Keystring required

Unique key to ensure idempotent requests

Request body

account_idstring required

The ID of the Account object.

entity_idstring required

The ID of your entity.

metadataMetadata

A set of key-value pairs that can be used to store additional information related to this object.

Example request

{
  "account_id": "account_xyz123",
  "entity_id": "entity_xyz123",
  "details": {
    "last_four": "1234",
    "replacement_for": "card_xyz123"
  }
}

Response

Card created successfully.

idstring

The server-generated ID of the Card object.

client_card_idstring

Client-provided identifier for the card. Optional: present only for cards created via file upload, and omitted for cards created through the API, which are identified solely by their server-generated ID.

account_idstring

The ID of the Account object.

entity_idstring

The ID of your entity.

status'active' | 'inactive' | 'closed'

Status is system-managed and cannot be set on create; status changes go through the status-transition endpoints.

status_reasonstring

The reason for the card's current status. Empty when the card is active; otherwise populated. Set via the status-transition endpoints.

created_atstring date-time

Creation timestamp.

updated_atstring date-time

Last update timestamp.

metadataMetadata

A set of key-value pairs that can be used to store additional information related to this object.

Example response

{
  "id": "card_xyz123",
  "account_id": "account_xyz123",
  "entity_id": "entity_xyz123",
  "details": {
    "last_four": "1234",
    "replacement_for": "card_xyz123"
  }
}