Cards

Cards are issued to cardholders from a card program. Each card has a lifecycle - from issuance through activation to eventual cancellation.

Prerequisites

Before issuing a card, the cardholder must have KYC status approved. See the cardholders guide for KYC details.

Issue a card

Select a card program and issue a card to a cardholder:

curl -X POST https://api.contro.me/v1/partner/cards \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholderId": "ch_abc123",
    "programId": "prog_xyz",
    "idempotencyKey": "issue_card_123"
  }'

const card = await contro.cards.create({
  cardholderId: "ch_abc123",
  programId: "prog_xyz",
  idempotencyKey: "issue_card_123",
});

card = contro.cards.create(
    cardholder_id="ch_abc123",
    program_id="prog_xyz",
    idempotency_key="issue_card_123",
)

const card = await fetch(`${BASE_URL}/partner/cards`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    cardholderId: "ch_abc123",
    programId: "prog_xyz",
    idempotencyKey: "issue_card_123",
  }),
}).then((r) => r.json());

Request fields

Field	Type	Required	Description
`cardholderId`	string	Yes	Cardholder to issue the card to. Example: `"ch_abc123"`
`programId`	string	Yes	Card program to use. Example: `"prog_xyz"`
`idempotencyKey`	string	No	Unique key to prevent duplicate card issuance. Example: `"issue_card_user42_2026"`

Response

{
  "id": "card_def456",
  "status": "created",
  "cardholderId": "ch_abc123",
  "programId": "prog_xyz"
}

Asynchronous issuance

Some card programs provision cards asynchronously. On those programs the response returns "status": "pending" instead of "created". The card is not usable yet — provisioning typically completes within a few minutes:

Issue the card and store the returned id.
When provisioning completes, the card transitions to active and a card.issued webhook fires.
Prefer reacting to the webhook; you can also poll GET /partner/cards/{id} until status is active.

The sandbox reproduces this lifecycle: sandbox-issued cards return pending and flip to active (with the same card.issued webhook) after a short delay, so an integration built against sandbox handles the live timing unchanged.

Card lifecycle

Cards progress through the following states:

Action	Endpoint	Effect
Activate	`POST /partner/cards/{id}/activate`	Card becomes usable for transactions
Freeze	`POST /partner/cards/{id}/freeze`	Temporarily blocks all transactions
Unfreeze	`POST /partner/cards/{id}/unfreeze`	Re-enables transactions on a frozen card
Cancel	`POST /partner/cards/{id}/cancel`	Permanently deactivates the card

Cancellation is irreversible. A cancelled card cannot be reactivated - issue a new card instead.

Example: activate a card

curl -X POST https://api.contro.me/v1/partner/cards/card_def456/activate \
  -H "x-contro-api-key: $CONTRO_API_KEY"

await contro.cards.activate("card_def456");

contro.cards.activate("card_def456")

Example: freeze a card

curl -X POST https://api.contro.me/v1/partner/cards/card_def456/freeze \
  -H "x-contro-api-key: $CONTRO_API_KEY"

await contro.cards.freeze("card_def456");

contro.cards.freeze("card_def456")

Spend control

Set per-transaction-type velocity caps on a card. Each cap is optional; omit a key to leave that bucket uncapped. The endpoint accepts both the new spendControl body and the legacy { limit } body (deprecated, see below).

curl -X PATCH https://api.contro.me/v1/partner/cards/card_def456/limits \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spendControl": {
      "sales": { "perTransaction": 200, "daily": 1000, "allTime": 50000 },
      "cash": { "allTime": 0 }
    }
  }'

await contro.cards.updateLimits("card_def456", {
  spendControl: {
    sales: { perTransaction: 200, daily: 1000, allTime: 50000 },
    cash: { allTime: 0 },
  },
});

See the Spend control guide for the full cap matrix, provider capability differences, and common patterns.

The legacy { "limit": 5000 } body is still accepted and is mapped to { "spendControl": { "sales": { "allTime": 5000 }, "cash": { "allTime": 5000 } } }. It will be removed in a future release.

List cards

Retrieve all cards for your partner account:

curl "https://api.contro.me/v1/partner/cards?limit=20" \
  -H "x-contro-api-key: $CONTRO_API_KEY"

const cards = await contro.cards.list({ limit: 20 });

cards = contro.cards.list(limit=20)

Query parameters

Parameter	Type	Description
`page`	integer	Page number (default `1`).
`limit`	integer	Items per page (1–100, default `20`).
`status`	string	Filter by card status. One of `created`, `active`, `frozen`, `cancelled`.

Get a card

Retrieve a single card by ID:

curl https://api.contro.me/v1/partner/cards/{id} \
  -H "x-contro-api-key: $CONTRO_API_KEY"

const card = await contro.cards.retrieve("card_def456");

card = contro.cards.retrieve("card_def456")

Card fields

Field	Type	Description
`id`	string	Card ID. Example: `"card_def456"`
`type`	string	Card type. One of `virtual`, `physical`
`brand`	string	Card network brand. One of `Visa`, `Mastercard`
`status`	string	Current card status. One of `created`, `active`, `frozen`, `cancelled`
`nameOnCard`	string \| null	Name embossed on the card, or `null` for virtual cards. Example: `"JANE DOE"`
`limit`	number \| null	Deprecated. Mirrors `spendControl.sales.allTime`. Use `spendControl` for per-transaction-type caps. Example: `5000`
`spendControl`	object \| null	Per-transaction-type velocity caps (`sales`, `cash`) and accrued spend (`spent`). See Spend control.
`last4`	string \| null	Last 4 digits of the card number. Example: `"0000"`
`programId`	string \| null	Card program this card was issued from. Example: `"prog_xyz"`
`createdAt`	string	ISO 8601 creation timestamp. Example: `"2026-03-20T14:30:00Z"`

Transactions

Retrieve transaction history for a card:

curl "https://api.contro.me/v1/partner/cards/{id}/transactions?limit=20" \
  -H "x-contro-api-key: $CONTRO_API_KEY"

const txns = await contro.cards.listTransactions("card_def456", { limit: 20 });

txns = contro.cards.list_transactions("card_def456", limit=20)

Transaction fields

Field	Type	Description
`id`	string	Transaction ID. Example: `"tx_abc123"`
`type`	string	Transaction type. One of `purchase`, `refund`, `withdrawal`, `fee`
`maskedCardNo`	string \| null	Last 4 digits of the card number used. Example: `"0000"`
`direction`	string \| null	Transaction direction. `C`: credit, `D`: debit
`amount`	number \| null	Transaction amount in the card’s currency unit
`currency`	string \| null	ISO 4217 currency code. Example: `"USD"`
`currencyPrecision`	number \| null	Decimal precision of the transaction currency
`billingAmount`	number \| null	Billing amount in the billing currency
`billingCurrencyCode`	string \| null	ISO 4217 billing currency code
`billingCurrencyPrecision`	number \| null	Decimal precision of the billing currency
`billingTimestamp`	string \| null	ISO 8601 billing/clearing timestamp
`status`	string	Transaction status. One of `pending`, `completed`, `declined`, `reversed`
`merchant`	string \| null	Merchant name
`timestamp`	string	ISO 8601 transaction timestamp

Card programs

Card programs define the card type and brand available to your integration. Your Contro admin assigns specific card programs to your partner account — only assigned programs can be used to issue cards.

List available card programs

Retrieve the card programs assigned to your account:

curl "https://api.contro.me/v1/partner/card-programs?limit=20" \
  -H "x-contro-api-key: $CONTRO_API_KEY"

const programs = await contro.cardPrograms.list({ limit: 20 });

programs = contro.card_programs.list(limit=20)

Card program fields

Field	Type	Description
`id`	string	Card program ID. Example: `"prog_xyz"`
`name`	string	Program name. Example: `"US Virtual Visa"`
`type`	string	Card type. One of `virtual`, `physical`
`brand`	string	Card network brand. One of `Visa`, `Mastercard`
`active`	boolean	Whether the program is currently active

Issuing a card with a program not assigned to your account will return a 403 error. Contact your Contro admin to request access to additional card programs.

Getting started

Core resources

Platform

Prerequisites

Issue a card

Request fields

Response

Asynchronous issuance

Card lifecycle

Example: activate a card

Example: freeze a card

Spend control

List cards

Query parameters

Get a card

Card fields

Transactions

Transaction fields

Card programs

List available card programs

Card program fields

​Prerequisites

​Issue a card

​Request fields

​Response

​Asynchronous issuance

​Card lifecycle

​Example: activate a card

​Example: freeze a card

​Spend control

​List cards

​Query parameters

​Get a card

​Card fields

​Transactions

​Transaction fields

​Card programs

​List available card programs

​Card program fields

Prerequisites

Issue a card

Request fields

Response

Asynchronous issuance

Card lifecycle

Example: activate a card

Example: freeze a card

Spend control

List cards

Query parameters

Get a card

Card fields

Transactions

Transaction fields

Card programs

List available card programs

Card program fields