Cards
Issue and manage virtual cards — list, create, read details, freeze, set limits, and cancel.
Issue USD virtual cards for your organization and manage their lifecycle. Every card is identified by an opaque Dolafy id — treat it as a stable string and do not parse its format.
Listing cards requires the cards:read scope. Issuing, pausing, unpausing, changing the limit and cancelling require cards:write. Reading card details requires the separate cards:details scope.
List cards
GET /v1/cards
x-api-key: dlfy_live_...
Query parameters
| Parameter | Default | Description |
|---|---|---|
status |
not_cancelled |
One of active, frozen, cancelled, not_cancelled, all. |
limit |
100 |
Page size, capped at 100. |
offset |
0 |
Number of records to skip. |
Response
{
"cards": [
{
"id": "126b6996-9c99-4732-9a58-3d8721e30bc8",
"title": "Growth Ads - Meta",
"status": "active",
"type": "virtual",
"currency": "USD",
"last4": "4242",
"expiryDate": "05/29",
"spendLimit": 1000,
"spendLimitFrequency": "per30DayPeriod",
"currentSpend": 125.75
}
],
"pagination": {
"limit": 100,
"offset": 0,
"hasMore": false
}
}
Page forward by requesting the next page with offset += limit while pagination.hasMore is true.
Issue a card
POST /v1/cards
x-api-key: dlfy_live_...
Idempotency-Key: card-growth-meta-001
content-type: application/json
Returns 201 Created. Idempotency-Key is required to avoid duplicate cards on retries.
Request
{
"title": "Growth Ads - Meta",
"spendLimitAmount": 1000,
"spendLimitFrequency": "per30DayPeriod"
}
titleis the card label. If omitted, Dolafy generates a short label likeAPI Card A1B2C3.- Spend limits are optional. Omit both
spendLimitAmountandspendLimitFrequencyto issue a card with no custom limit. - Supported
spendLimitFrequencyvalues:perAuthorization,per24HourPeriod,per7DayPeriod,per30DayPeriod,perYearPeriod,allTime.
Response
{
"card": {
"id": "126b6996-9c99-4732-9a58-3d8721e30bc8",
"title": "Growth Ads - Meta",
"status": "active",
"type": "virtual",
"currency": "USD",
"last4": "4242",
"expiryDate": "05/29",
"spendLimit": 1000,
"spendLimitFrequency": "per30DayPeriod",
"currentSpend": 0
}
}
Issuance requires authorized-user terms to have been accepted in the dashboard; otherwise the call returns 409 authorized_user_terms_required. Standard issuance limits (active-card cap, minimum balance, and issuance fees) still apply. Each cardholder on your card account can be issued a limited number of cards over its lifetime. When one is full, new cards are issued under your other verified cardholders automatically, with no change to the request. If every cardholder is full, the call returns 409 card_lifetime_limit_reached and no card is issued: an owner adds a new cardholder (name and email) on the Cards page of the dashboard, the cardholder verifies their identity, and API issuance resumes under them.
Card details
Returns the sensitive card number and CVV. Call this server-side only and avoid logging or storing these values unless your compliance program permits it.
GET /v1/cards/126b6996-9c99-4732-9a58-3d8721e30bc8/details
x-api-key: dlfy_live_...
{
"card": {
"id": "126b6996-9c99-4732-9a58-3d8721e30bc8",
"title": "Growth Ads - Meta",
"status": "active",
"type": "virtual",
"currency": "USD",
"last4": "4242",
"expiryDate": "05/29",
"expiryMonth": 5,
"expiryYear": 2029,
"cardNumber": "4111111111114242",
"cvv": "123",
"spendLimit": 1000,
"spendLimitFrequency": "per30DayPeriod",
"currentSpend": 125.75
}
}
Details are only available for an active card. A frozen or cancelled card returns 409 card_not_active; unfreeze the card first.
If the card provider does not respond in time, the request returns 503 provider_unavailable within about 14 seconds. Nothing changed on the card; repeat the request after a few seconds.
Freeze and unfreeze
POST /v1/cards/:cardId/pause
POST /v1/cards/:cardId/unpause
pause freezes a card (status: "frozen"); unpause reactivates it (status: "active"). Both return the full card object.
Update the spend limit
PATCH /v1/cards/:cardId/limit
content-type: application/json
{
"spendLimitAmount": 2500,
"spendLimitFrequency": "per30DayPeriod"
}
spendLimitAmount must be a positive USD amount. spendLimitFrequency is required and accepts the same values as issuance. Returns the card with its updated limit.
Cancel a card
POST /v1/cards/:cardId/cancel
Permanently cancels the card (status: "cancelled"). Cancelling a card frees an active-card slot.