Skip to main content
POST
Issue a card
A VIRTUAL card is issued at once; read its full number and security code with the card-details endpoint. An EMBOSSED card is a physical card linked to the wallet by the cardId read from the QR code that comes with it. Either way the card is returned ACTIVE, spending from the wallet’s balance. Send x-environment: LIVE to issue a production card. Pass cardLimits to create the card’s spending limits in the same call — the card is activated only after they are in place. You can also add limits later with the create-a-card-limit endpoint. The account must be open and the wallet active in the environment, with card payments enabled, and the account must have room in its card limit, which counts every card it issued — blocked and cancelled ones included. Organization admins can issue cards in any wallet; other users only in wallets they use as OWNER or USER. Retries: issuing a virtual card isn’t idempotent — retrying a request that failed after the card was issued issues another one. List the wallet’s cards before retrying.

Headers

x-environment
enum<string>

Environment to issue the card in: LIVE (production) or TEST (sandbox). When you omit it, the card is issued in TEST; any other value is rejected.

Available options:
LIVE,
TEST

Path Parameters

realmId
string<uuid>
required

ID of your realm.

Format: UUID

organizationId
string<uuid>
required

ID of the organization the wallet belongs to.

Format: UUID

accountId
string
required

ID of the organization's account (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$
walletId
string
required

ID of the wallet the card is issued in (24 hexadecimal characters), or default for the organization's main wallet.

Pattern: ^([0-9a-fA-F]{24}|default)$

Body

application/json
type
enum<string>
required

Kind of card: VIRTUAL issues a new card now; EMBOSSED links a physical card you already received to the wallet, identified by cardId.

Available options:
VIRTUAL,
EMBOSSED
Example:

"VIRTUAL"

cardId
string

Required for an EMBOSSED card: the identifier read from the QR code that comes with the physical card. Ignored for a VIRTUAL card.

Example:

"3f1c9a52-7d4e-4b8a-9e21-6c0d8b7a5f43"

singleUse
boolean

true issues a single-use card, blocked after its first cleared transaction. Only for VIRTUAL cards. Defaults to false.

Example:

false

name
string

Name of the card, to tell it apart in lists.

Example:

"Marketing - Ads"

customFields
object

Values of the organization's card custom fields, keyed by each field's slug. Each value must fit its field's type and options.


Example: {"cost-center":"CC-1020"}

Example:
cardLimits
object[]

Spending limits to create together with the card. Each one works like a limit created with the create-a-card-limit endpoint, for this card only.

Response

Successful response

A payment card of a wallet.

_id
string
required

ID of the card. Use it as cardId in the card endpoints.

Example:

"66f2a4b8b4d3e80012c9a0e1"

realmId
string<uuid>
required

ID of the realm the card belongs to.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId
string<uuid>
required

ID of the organization the card belongs to.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

accountId
string
required

ID of the organization's account.

Example:

"66f2a1c7b4d3e80012c9a0b4"

walletId
string
required

ID of the wallet the card spends from.

Example:

"66f2a3d1b4d3e80012c9a0d2"

environment
enum<string>
required

Environment of the card: LIVE (production) or TEST (sandbox).

Available options:
LIVE,
TEST
Example:

"LIVE"

panMasked
string
required

Card number with its middle digits masked: the first six and the last four digits. Read the full number with the card-details endpoint.

Example:

"524674******4821"

external
object
required

Identifiers of the card at the card issuer.

status
enum<string>
required

Status of the card: ACTIVE (it can be used), BLOCKED (blocked — unblock it to use it again) or CANCELLED (closed by the issuer for good).

Available options:
ACTIVE,
BLOCKED,
CANCELLED
Example:

"ACTIVE"

createdAt
string<date-time>
required

When the card record was created.

Example:

"2026-11-02T13:05:11.000Z"

updatedAt
string<date-time>
required

When the card record last changed.

Example:

"2026-11-02T13:05:12.000Z"

expiryDate
string

Expiry month and year of the card, as MM/YYYY.

Example:

"11/2031"

tokenisationPermitted
boolean

Whether the card can be added to a device wallet such as Apple Pay, Google Pay or Samsung Pay.

Example:

true

singleUse
boolean

Whether the card is single-use: blocked after its first cleared transaction. Absent on some older cards.

Example:

false

type
enum<string>

Kind of card: VIRTUAL or EMBOSSED (a physical card). Absent on a few old cancelled cards.

Available options:
VIRTUAL,
EMBOSSED
Example:

"VIRTUAL"

customFields
object

Values of the organization's card custom fields, keyed by each field's slug. Absent when the card has none.


Example: {"cost-center":"CC-1020"}

Example:
issuedAt
string<date-time>

When the card was issued, or linked to the wallet for a physical card. Absent on a few older cards.

Example:

"2026-11-02T13:05:11.000Z"

name
string

Name of the card. Absent when it was issued without one.

Example:

"Marketing - Ads"

ownerName
string

Cardholder name associated with the card: in upper case, without accents, abbreviated to about 26 characters. Absent on older cards.

Example:

"MARIANA COSTA"

isSuper
boolean

Whether the card is on the premium card product. Absent on older cards.

Example:

false

walletProduct
string

Card product of the wallet when the card was issued. Absent on older cards.

Example:

"NORMAL"

cardLimitIds
string[]

Legacy field kept on older cards: IDs of limits created with the card. It is not kept up to date — list the card's limits with the card-limits endpoint instead.


Example: ["66f2a5c2b4d3e80012c9a0f3"]

createdBy
string | null

ID of the user who issued the card. Absent, or null, on older cards.

Example:

"e3553bc1-5e20-4e17-b22a-a796fda0aa99"

updatedBy
string | null

ID of the user who last changed the card. Absent, or null, on older cards.

Example:

"e3553bc1-5e20-4e17-b22a-a796fda0aa99"

__v
number

Version of the record, incremented by some updates.

Example:

0