Skip to main content
POST
Issue a card

Authorizations

Api-Key
string
header
required

Partner API key. Must carry the cards permission.

Headers

Api-Version
string
default:2026-09.1
required

The API version this request targets. 2026-09.1. See Versioning.

Pattern: ^\d{4}-\d{2}\.\d+$
Idempotency-Key
string
required

1 to 64 characters. Use a new random value, for example a UUID, for each new operation. A repeat with the same key and body returns the first result and creates nothing new; the same key with a different body returns 409 ERRCRD_1029.

Required string length: 1 - 64

Path Parameters

cardholderId
string
required

An enrolled individual, or an active cardholder of an enrolled business (cus_).

Example:

"cus_8Qw2mZ4pL7nR1tY6vB3x"

Body

application/json
controls
object
required

The card's controls.

displayName
string

A name for the card. 1 to 26 characters: letters, digits, spaces, periods and hyphens, with at least one letter.

Required string length: 1 - 26
Pattern: ^(?=.*[A-Za-z])[A-Za-z0-9 .-]{1,26}$

Response

The card. You receive card.created.

cardId
string

The card (crd_).

Example:

"crd_4fT9kQ2wE8rT5yU1iO7p"

cardholderId
string

The cardholder (cus_).

Example:

"cus_8Qw2mZ4pL7nR1tY6vB3x"

businessId
string | null

The cardholder's business (cus_). null for an individual's card.

type
enum<string>
Available options:
virtual
kind
enum<string>
Available options:
standard,
single_use
status
enum<string>

Reserved, not sent yet: blocked, expired.

Available options:
active,
frozen,
canceled
closedReason
enum<string> | null

Set when status is canceled: canceled (you canceled it), spent (a single-use card was used) or expired.

Available options:
canceled,
spent,
expired,
null
displayName
string | null

The card's name.

last4
string

The last 4 digits of the card number.

expiryMonth
string

Two digits, 01 to 12.

expiryYear
string

Four digits.

controls
object
usage
object | null

What the card has spent in the current limit period. null for a transaction limit.

singleUse
object | null

Set only when kind is single_use; null otherwise.

createdAt
string<date-time>

When the card was issued.

updatedAt
string<date-time>

When the card last changed.