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
| 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"
}
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"
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"
Spending limits
Update spending limits on a card:
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 '{ "limit": 5000 }'
limit to null to remove the spending limit.
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"
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
| 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 | Spending limit in the card’s currency unit. null = unlimited. Example: 5000 |
provider | string | null | Underlying card provider. Example: "stripe" |
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" |
Browse card programs
List available card programs to determine which programs you can issue cards from:
curl https://api.contro.me/v1/partner/card-programs \
-H "x-contro-api-key: $CONTRO_API_KEY"
type, brand, currency, and region to help you select the right program for your use case. 
