Cards

Card endpoints live under /developer/cards. Every request needs Authorization: Bearer <access_token> and X-On-Behalf-Of: <company_id>. See Authentication. Reading cards needs no permission beyond company membership. Issuing cards needs issue_cards. Changing cards needs manage_cards.

Endpoints

Method	Path	Purpose	Permission
`GET`	`/developer/cards`	List cards with filters and paging.	—
`GET`	`/developer/cards/{id}`	Fetch one card.	—
`POST`	`/developer/cards/virtual`	Issue a virtual card.	`issue_cards`
`POST`	`/developer/cards/physical`	Order a physical card.	`issue_cards`
`POST`	`/developer/cards/delivery-options`	Delivery methods and prices for an address.	—
`PUT`	`/developer/cards/{id}/status`	Freeze, unfreeze, activate, or terminate a card.	`manage_cards`
`POST`	`/developer/cards/{id}/replace`	Give a virtual card a new number.	`manage_cards`
`PATCH`	`/developer/cards/{id}`	Rename, move account, or change settings.	`manage_cards`
`PUT`	`/developer/cards/{id}/spending-limit`	Set or replace the spending limit.	`manage_cards`
`DELETE`	`/developer/cards/{id}/spending-limit`	Remove the spending limit.	`manage_cards`
`POST`	`/developer/cards/{id}/spending-limit/reset`	Reset spend for the current period to zero.	`manage_cards`

Card numbers, CVVs, and PINs are never returned by the Developer API.

The card object

{
  "id": "3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e",
  "token": "104857321",
  "company_id": "bebb185d-8210-4e66-ac63-397b49a1e09f",
  "account_id": "0d6c0a2a-2b08-49bc-89a9-eb936c9ff28c",
  "user_id": "29b297ca-c617-437e-9c1d-32f494fbf44d",
  "type": "virtual",
  "design_id": "c6d5ea1a-80f8-49ab-9fee-250d368b3915",
  "status": "active",
  "name": "Marketing spend",
  "last_four": "4242",
  "expiry_date": "2029-07-31",
  "auto_convert": false,
  "three_ds_biometric": false,
  "spending_limit": { "period": "monthly", "amount": "5000.00", "currency": "GBP", "used": "1249.50" },
  "card_limits": {
    "currency": "EUR",
    "max_per_purchase": { "amount": "250000.00" },
    "daily": { "amount": "500000.00" },
    "rolling_32_days": { "amount": "2500000.00" }
  },
  "created_at": "2026-07-01T08:30:00Z"
}

spending_limit is null when the card has no limit. used is what the card has spent in the current period, in the limit’s currency. It is omitted if it can’t be read or the card has ended.
card_limits are the card’s fixed limits in EUR. In list responses, daily and rolling_32_days also include used.
Amounts are decimal strings with two places.

Card status

Status	Meaning
`inactive`	Issued but not yet activated.
`active`	Usable.
`frozen`	Frozen by a team member. New authorisations are declined.
`suspended`, `locked`, `blocked`	Restricted by Incard. Contact support.
`expired`	Past its expiry date.
`terminated`	Permanently cancelled.

List cards

curl -sS "https://api.incard.com/developer/cards?status=active,frozen&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID"

{
  "cards": [ { "id": "3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e", "status": "active", "...": "..." } ],
  "next_cursor": "eyJjIjoiMjAyNi0wNy0wMVQwODozMDowMFoiLCJpIjoiM2Y4YjJjMWQifQ"
}

Cards are returned newest first. expired and terminated cards are excluded unless you ask for them in status.

Parameter	Notes
`status`	Comma-separated statuses. Defaults to every status except `expired` and `terminated`.
`type`	`virtual` or `physical`.
`user_ids`	Comma-separated user UUIDs (max 100).
`account_ids`	Comma-separated account UUIDs (max 100).
`tokens`	Comma-separated card tokens (max 100).
`q`	Case-insensitive match on card name or last four digits (max 100 characters).
`sort`	`inactive_first` lists `inactive` cards before the rest.
`limit`	Page size, 1–200. Default 50.
`cursor`	Pass `next_cursor` from the previous page, with the same `sort`. `next_cursor` is absent on the last page.
`offset`	Use instead of `cursor` for numbered pages. The response then includes `total` and `total_inactive`, and no `next_cursor`.

Each parameter may appear once. Invalid values return 400.

Get a card

curl -sS "https://api.incard.com/developer/cards/3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID"

Returns the card object. Unknown cards, and cards on accounts the member can’t access, return 404.

Issue a virtual card

Ordering endpoints need an Idempotency-Key header containing a UUID. Retrying with the same key returns the card from the first request instead of issuing another, even if the body differs. Each company can hold a limited number of live cards (not expired or terminated), virtual and physical together. The default is 30. Ordering beyond the quota returns 422. Contact support to raise it.

curl -sS -X POST "https://api.incard.com/developer/cards/virtual" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID" \
  -H "Idempotency-Key: 5b0e2a54-6f1c-4d8e-9a3b-7c2d1e0f9a8b" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "0d6c0a2a-2b08-49bc-89a9-eb936c9ff28c",
    "design_id": "c6d5ea1a-80f8-49ab-9fee-250d368b3915",
    "name": "Marketing spend",
    "spending_limit": { "period": "monthly", "amount": "5000.00" }
  }'

Field	Notes
`account_id`	Required. The account the card spends from.
`design_id`	Required. One of the designs below.
`name`	Optional. Defaults to `Virtual <last four>`.
`auto_convert`	Optional boolean.
`spending_limit`	Optional. See Spending limits.

The card is issued to the member who owns the API key. It is active straight away. three_ds_biometric starts true if the cardholder uses the Incard app. Returns 201 with the card.

Design	`design_id`
Simply Black	`c6d5ea1a-80f8-49ab-9fee-250d368b3915`
Deep Sea	`8c0e5d7e-b5a8-4da3-a422-e87ecfa50e8c`
Lime	`7d60b161-8930-46c5-8f66-15d44edfacf9`
Baby Blue	`b3e8f2a1-5c7d-4a9b-8e6f-1d2c3b4a5e6f`
Mint	`1da11259-5d43-4839-b25b-385f10bedcea`
Blush	`d5989b9f-fcce-422d-bbb1-801cee72e7df`
Tangerine	`4f81ed86-f6d5-49d0-8e92-3d8ba0089a4d`
Cherry	`00f2d139-4864-4698-98a3-68d6369f2b37`
Bubblegum	`9ab30ddb-ee73-4d2e-b381-0d829a3441e7`
Rainbow	`7e8fa9a6-e360-4b82-9dea-292a3d8ec047`

Order a physical card

First check which delivery methods an address can use:

curl -sS -X POST "https://api.incard.com/developer/cards/delivery-options" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{ "delivery_address": { "line1": "1 Example Street", "city": "London", "post_code": "EC1A 1BB", "country_code": "GB" } }'

{
  "delivery_methods": [
    { "method": "classic", "eta": { "max_business_days": 5 }, "price": { "amount": "0.00", "currency": "GBP" } },
    { "method": "express", "eta": { "max_business_days": 3 }, "price": { "amount": "9.99", "currency": "GBP" } }
  ]
}

Addresses in the UK and most of Europe get classic (up to 5 business days, free) and express (up to 3 business days, £9.99). Other supported countries, Cyprus included, get international (3–10 business days, £49.99). Countries that can’t be served return 422. Always use the methods delivery-options returns. Then place the order:

curl -sS -X POST "https://api.incard.com/developer/cards/physical" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID" \
  -H "Idempotency-Key: 9d4c3b2a-1e0f-4a9b-8c7d-6e5f4a3b2c1d" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "0d6c0a2a-2b08-49bc-89a9-eb936c9ff28c",
    "name": "Travel card",
    "pin": "1234",
    "delivery_address": { "line1": "1 Example Street", "city": "London", "post_code": "EC1A 1BB", "country_code": "GB" },
    "delivery_method": "classic"
  }'

Field	Notes
`account_id`	Required.
`pin`	Required. Exactly four digits.
`delivery_address`	Required. `line1` (required), `line2`, `line3`, `city`, `state`, `post_code`, `country_code` (ISO 3166-1 alpha-2). Required fields depend on the country.
`delivery_method`	Required. A method returned by `delivery-options` for this address.
`name`	Optional. Defaults to `Physical <last four>`.
`auto_convert`, `spending_limit`	Optional, as for virtual cards.

Like virtual cards, the card is issued to the member who owns the API key and is active straight away. Returns 201 with the card.

Change a card’s status

curl -sS -X PUT "https://api.incard.com/developer/cards/3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e/status" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{ "status": "frozen" }'

From	To	Action
`active`	`frozen`	Freeze
`frozen`	`active`	Unfreeze
`inactive`	`active`	Activate
Any live status	`terminated`	Terminate. Permanent.

status must be active, frozen, or terminated. Anything else returns 400. Returns 200 with the card. Setting a card to the status it already has succeeds without change. Other transitions return 409, including reactivating a card Incard has suspended, locked, or blocked.

Replace a card

Gives a virtual card a new number, token, last four, and expiry date. Its id, status, account, limits, and settings stay the same. Spend towards its spending_limit starts again at zero on the new number. Use it when a card number is lost or compromised.

curl -sS -X POST "https://api.incard.com/developer/cards/3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e/replace" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID" \
  -H "Idempotency-Key: 2f1e0d9c-8b7a-4c6d-9e5f-4a3b2c1d0e9f" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "lost" }'

reason is lost or fraud. Requires an Idempotency-Key header (a UUID). Retrying with the same key returns the replaced card. Only active or frozen virtual cards can be replaced. Physical cards return 409. Returns 200 with the card.

Update a card

curl -sS -X PATCH "https://api.incard.com/developer/cards/3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ads spend" }'

Send any of name, account_id, auto_convert, three_ds_biometric, or spending_limit. Returns 200 with the card.

Moving a card that has a spending limit to an account in another currency also needs a new spending_limit in that currency. Otherwise the request returns 409.
expired and terminated cards can only be renamed.

Spending limits

A spending limit caps what a card can spend per period: daily, weekly, monthly, or lifetime. Periods follow the UK calendar, and weeks start on Monday. The limit is always in the card’s account currency.

curl -sS -X PUT "https://api.incard.com/developer/cards/3f8b2c1d-9e4a-4b7c-8d2e-1f3a5b7c9d0e/spending-limit" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-On-Behalf-Of: YOUR_COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{ "period": "monthly", "amount": "5000.00" }'

{ "period": "monthly", "amount": "5000.00", "currency": "GBP", "created_at": "2026-07-01T08:30:00Z", "updated_at": "2026-09-02T11:15:27Z" }

amount must be more than 0 with at most two decimal places.
A daily limit can be at most card_limits.daily.amount. A weekly or monthly limit can be at most card_limits.rolling_32_days.amount. The number is compared as-is, without converting from EUR. lifetime limits have no cap.
DELETE /developer/cards/{id}/spending-limit removes the limit. It returns 204, even if the card had none, or 409 if the card has ended.
POST /developer/cards/{id}/spending-limit/reset sets spend for the current period back to zero and keeps the limit. It returns 204, or 409 if the card has no limit or has ended.

Errors

Card errors carry a single message:

{ "error": "invalid status change: card is inactive, cannot make it frozen" }

Authentication, company-access, and permission errors (401, 403, a missing X-On-Behalf-Of, and unknown routes) use the gateway format instead: { "success": false, "error": { "code": "forbidden", "message": "access denied" } }.

Status	Cause
400	Invalid body, query parameter, or `Idempotency-Key`.
403	The API key’s member lacks the required permission.
404	Card or account not found in this company.
409	The card can’t make this change in its current state, or another change to it is in progress. Retry later.
422	The card can’t be issued (quota reached, company not active, account closed, missing company or cardholder details, or the delivery country can’t be served), or the card issuer rejected the request.
502, 503	The card issuer is unavailable. Retry later.

Get started

Resources

Events

Endpoints

The card object

Card status

List cards

Get a card

Issue a virtual card

Order a physical card

Change a card’s status

Replace a card

Update a card

Spending limits

Errors

​Endpoints

​The card object

​Card status

​List cards

​Get a card

​Issue a virtual card

​Order a physical card

​Change a card’s status

​Replace a card

​Update a card

​Spending limits

​Errors

Endpoints

The card object

Card status

List cards

Get a card

Issue a virtual card

Order a physical card

Change a card’s status

Replace a card

Update a card

Spending limits

Errors