API Reference

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