Skip to main content

Documentation Index

Fetch the complete documentation index at: https://partner-docs.contro.dev/llms.txt

Use this file to discover all available pages before exploring further.

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"
  }'

​
Request fields

FieldTypeRequiredDescription
cardholderIdstringYesCardholder to issue the card to. Example: "ch_abc123"
programIdstringYesCard program to use. Example: "prog_xyz"
idempotencyKeystringNoUnique key to prevent duplicate card issuance. Example: "issue_card_user42_2026"

​
Response

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

​
Card lifecycle

Cards progress through the following states:
ActionEndpointEffect
ActivatePOST /partner/cards/{id}/activateCard becomes usable for transactions
FreezePOST /partner/cards/{id}/freezeTemporarily blocks all transactions
UnfreezePOST /partner/cards/{id}/unfreezeRe-enables transactions on a frozen card
CancelPOST /partner/cards/{id}/cancelPermanently 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"

​
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"

​
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 }
    }
  }'
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"

​
Query parameters

ParameterTypeDescription
pageintegerPage number (default 1).
limitintegerItems per page (1–100, default 20).
statusstringFilter 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"

​
Card fields

FieldTypeDescription
idstringCard ID. Example: "card_def456"
typestringCard type. One of virtual, physical
brandstringCard network brand. One of Visa, Mastercard
statusstringCurrent card status. One of created, active, frozen, cancelled
nameOnCardstring | nullName embossed on the card, or null for virtual cards. Example: "JANE DOE"
limitnumber | nullDeprecated. Mirrors spendControl.sales.allTime. Use spendControl for per-transaction-type caps. Example: 5000
spendControlobject | nullPer-transaction-type velocity caps (sales, cash) and accrued spend (spent). See Spend control.
last4string | nullLast 4 digits of the card number. Example: "0000"
programIdstring | nullCard program this card was issued from. Example: "prog_xyz"
createdAtstringISO 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"

​
Transaction fields

FieldTypeDescription
idstringTransaction ID. Example: "tx_abc123"
typestringTransaction type. One of purchase, refund, withdrawal, fee
maskedCardNostring | nullLast 4 digits of the card number used. Example: "0000"
directionstring | nullTransaction direction. C: credit, D: debit
amountnumber | nullTransaction amount in the card’s currency unit
currencystring | nullISO 4217 currency code. Example: "USD"
currencyPrecisionnumber | nullDecimal precision of the transaction currency
billingAmountnumber | nullBilling amount in the billing currency
billingCurrencyCodestring | nullISO 4217 billing currency code
billingCurrencyPrecisionnumber | nullDecimal precision of the billing currency
billingTimestampstring | nullISO 8601 billing/clearing timestamp
statusstringTransaction status. One of pending, completed, declined, reversed
merchantstring | nullMerchant name
timestampstringISO 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"

​
Card program fields

FieldTypeDescription
idstringCard program ID. Example: "prog_xyz"
namestringProgram name. Example: "US Virtual Visa"
typestringCard type. One of virtual, physical
brandstringCard network brand. One of Visa, Mastercard
activebooleanWhether 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.