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.

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

title is the card label. If omitted, Dolafy generates a short label like API Card A1B2C3.
Spend limits are optional. Omit both spendLimitAmount and spendLimitFrequency to issue a card with no custom limit.
Supported spendLimitFrequency values: 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.

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

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.