Cards

A card is issued to a cardholder against a funding account. Cards can be virtual or physical, and move through a simple lifecycle.

Lifecycle

Each transition emits a webhook (card.activated, card.frozen, card.unfrozen, card.blocked, card.closed) — but only when the status actually changes. Freezing an already-frozen card returns 200 without a duplicate event.

Issue a card

Prerequisites (in order):

Applicant status: APPROVED (poll GET /v1/applicants/{id}/kyc-status or subscribe to applicant.status_changed). The applicant needs real firstName / lastName in data — the issuer rejects cardholders with empty or non-Latin names.
Funding account created (POST /v1/accounts)
Funds in place — issuance charges an opening fee from the card’s budget. Deposit stablecoins, then a single POST /v1/accounts/{id}/transfers direction: "in" converts the deposit and fills the budget. See Card funding.
Cardholder created (POST /v1/cardholders)
Issue card with body fields below

Supports virtual and physical cards, debit (budget) and prepaid programs (product_type on the program).

cURL

curl -s -X POST 'https://sandbox.apocor.ai/v1/cards' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "program_id": "prog_abc123",
    "account_id": "acct_abc123",
    "cardholder_id": "ch_abc123",
    "form_factor": "VIRTUAL",
    "reference_id": "your-card-001",
    "spend_limit_cents": 50000
  }'

Issuance is asynchronous — you get 202 with an issuance_id:

202 Accepted

{
  "data": {
    "issuance_id": "iss_abc123",
    "status": "PENDING"
  }
}

Then either poll GET /v1/cards/issuances/{issuance_id} or wait for the webhook: card.created on success, card.issuance.failed (with error, issuance_id, reference_id) on failure.

Idempotency-Key is required — omitting it returns 400 IDEMPOTENCY_KEY_REQUIRED. Retries with the same key + body replay the original response for 72 hours; a same-key request while issuance is in flight returns 409 with the issuance_id.
reference_id is optional — your own unique id per program + environment. Look up later with GET /v1/cards?reference_id=.
budget_id is optional (debit programs) — bind the card to a specific named budget; defaults to the applicant’s default budget. See Budgets.

Physical cards are created INACTIVE until shipped and activated.

Batch issue and delete

Batch issuance is asynchronous — the issuer returns a task_id you can poll. Up to 100 cards per request.

cURL

curl -s -X POST 'https://sandbox.apocor.ai/v1/cards/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{
    "program_id": "prog_abc123",
    "account_id": "acct_abc123",
    "cardholder_id": "ch_abc123",
    "form_factor": "VIRTUAL",
    "cards": [
      { "label": "Ops card 1" },
      { "label": "Ops card 2" }
    ]
  }'

Poll batch progress:

cURL

curl -s 'https://sandbox.apocor.ai/v1/cards/batch/{task_id}?applicant_id=app_abc123' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Delete up to 100 cards at once:

cURL

curl -s -X POST 'https://sandbox.apocor.ai/v1/cards/batch-delete' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{ "card_ids": ["card_1", "card_2"] }'

Spend controls (MCC / consumption scenarios)

Configure issuer-level whitelist/blacklist rules for MCC codes, transaction scenarios, or currencies.

Action	Endpoint
List controls	`GET /v1/cards/spend-controls?applicant_id=...&usage=MCC&list_type=BLACKLIST`
Create / update	`POST /v1/cards/spend-controls`
Delete	`DELETE /v1/cards/spend-controls?id=...&applicant_id=...`
Batch upsert	`POST /v1/cards/spend-controls/batch`

usage is one of MCC, SCENARIO, or TRANSACTION_CURRENCY. For MCC rules, keywords must be a 4-digit MCC string (e.g. "7995"). Optionally scope rules to specific Apocor card_ids or issuer card_bin_ids.

cURL

curl -s -X POST 'https://sandbox.apocor.ai/v1/cards/spend-controls' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{
    "applicant_id": "app_abc123",
    "usage": "MCC",
    "keywords": "7995",
    "list_type": "BLACKLIST",
    "card_ids": ["card_abc123"]
  }'

Fund cards and accounts

Action	Endpoint
Fund prepaid card	`POST /v1/cards/{id}/fund` — body `{ "amount": "25.00" }`
Fund from stablecoin deposits	`POST /v1/cards/{id}/fund-from-wallet` — see Card funding
Withdraw from prepaid	`POST /v1/cards/{id}/defund`
Fund/deplete a budget	`POST /v1/accounts/{id}/transfers` — `{ "applicant_id", "direction": "in\|out", "amount", "budget_id?" }` (auto-converts deposits on `"in"`)
Create a named budget	`POST /v1/accounts/{id}/budgets` — `{ "applicant_id", "name" }`
List budgets with balances	`GET /v1/accounts/{id}/budgets?applicant_id=...`
Rename a budget	`PATCH /v1/budgets/{id}` — `{ "name" }`

fund, fund-from-wallet, and defund require an Idempotency-Key header. Successful funding emits card.funded; failures emit card.funding_failed.

Manage a card

Action	Endpoint
Freeze	`POST /v1/cards/{id}/freeze`
Unfreeze	`POST /v1/cards/{id}/unfreeze`
Activate	`POST /v1/cards/{id}/activate` (physical: calls issuer activate)
Close	`POST /v1/cards/{id}/close`
Update label / spend limit	`PATCH /v1/cards/{id}`
Card transactions	`GET /v1/cards/{id}/transactions` or `GET /v1/transactions?card_id=...`
Reveal (Widget.js token)	`GET /v1/cards/{id}/secure-details`
Reveal (PCI server-side, encrypted)	`POST /v1/cards/{id}/payment-details`

Physical cards

Action	Endpoint
Ship	`POST /v1/cards/{id}/physical/ship`
Shipping status	`GET /v1/cards/{id}/physical/shipping`
Set PIN	`PUT /v1/cards/{id}/pin`

Cardholders

Action	Endpoint
Create	`POST /v1/cardholders`
List	`GET /v1/cardholders`
Get	`GET /v1/cardholders/{id}`
Update	`PATCH /v1/cardholders/{id}`

Sandbox testing

POST /v1/sandbox/simulate (TEST keys / sandbox issuer only) drives fake spend through a real card so you can exercise your webhook handlers end to end.

cURL

# Authorization
curl -s -X POST 'https://sandbox.apocor.ai/v1/sandbox/simulate' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{ "type": "authorization", "card_id": "card_abc123",
        "payload": { "amount": "5.00", "currency": "USD" } }'

# Reversal — requires the issuer transaction id from the original authorization
curl -s -X POST 'https://sandbox.apocor.ai/v1/sandbox/simulate' \
  -H 'Authorization: Bearer YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{ "type": "reversal", "card_id": "card_abc123",
        "payload": { "amount": "5.00", "currency": "USD",
                     "relatedTransactionId": "TXN_ID_FROM_AUTH" } }'

`type`	What it does	Webhook emitted
`authorization`	Simulates a card swipe	`transaction.authorized` (or `.declined`)
`refund`	Merchant refund	`transaction.refunded`
`reversal`	Voids an authorization — needs `payload.relatedTransactionId`	`transaction.reversed`
`kyc_review`	Pushes an applicant KYC decision (`applicant_id` instead of `card_id`)	`applicant.status_changed`

Get relatedTransactionId from the transaction.authorized event’s data.cardTransactionId, or from GET /v1/cards/{id}/transactions.

Viewing full card details (PAN / CVV)

List and get card responses never include full PAN or CVV — only lastFour and similar safe fields. Apocor supports two reveal methods:

Method	Use when	Endpoint
1 — Widget.js (default)	Display PAN/CVV in a browser / WebView without PCI server scope	`GET /v1/cards/{id}/secure-details` + Apocor Widget.js
2 — Server-side (PCI DSS Level 1)	Your backend must process card data (`pciRevealEnabled`)	`POST /v1/cards/{id}/payment-details` (encrypted envelope)

Full walkthrough (SDK URLs, bootstrap example, RSA decrypt sample): Viewing card details (PAN / CVV). API Reference: group Cards — reveal PAN/CVV.

Get started

Core concepts

Webhooks & events

Reference

Lifecycle

Issue a card

Batch issue and delete

Spend controls (MCC / consumption scenarios)

Fund cards and accounts

Manage a card

Physical cards

Cardholders

Sandbox testing

Viewing full card details (PAN / CVV)

​Lifecycle

​Issue a card

​Batch issue and delete

​Spend controls (MCC / consumption scenarios)

​Fund cards and accounts

​Manage a card

​Physical cards

​Cardholders

​Sandbox testing

​Viewing full card details (PAN / CVV)

Lifecycle

Issue a card

Batch issue and delete

Spend controls (MCC / consumption scenarios)

Fund cards and accounts

Manage a card

Physical cards

Cardholders

Sandbox testing

Viewing full card details (PAN / CVV)