API Reference

Webhooks

Receive card transaction events and verification codes.

Card webhooks notify your server about card transaction activity and, when enabled, verification codes. Register endpoints from your dashboard under Developers → Cards.

Endpoint scope

Each webhook endpoint is product-scoped. An endpoint registered under Developers → Cards receives only card events — it never receives banking or checkout events. Each endpoint has its own verification token, and you can register more than one.

Event types

Event When
card.transaction.approved A card authorization is approved.
card.transaction.denied A card authorization is declined.
card.transaction.pending An authorized spend is pending/in-flight.
card.transaction.completed A spend settles; data.amount is the final posted amount.
card.transaction.reversed A prior authorization is reversed (hold released).
card.transaction.refunded A refund is credited back to the card.
card.authentication.code A verification code for an online purchase (3-D Secure) or for adding a card to a mobile wallet. Available on request; contact support to enable it for a specific endpoint.

Payload

Every delivery uses a common envelope. For card transaction events, data has the same shape returned by GET /v1/activity?type=cards.

{
  "id": "evt_01HXR9...",
  "type": "card.transaction.approved",
  "createdAt": "2026-04-08T12:00:00.000Z",
  "livemode": true,
  "data": {
    "id": "ctxn_123",
    "cardId": "126b6996-9c99-4732-9a58-3d8721e30bc8",
    "cardLast4": "4242",
    "occurredAt": "2026-04-08T12:00:00.000Z",
    "settledAt": null,
    "description": "Northstar Media",
    "merchant": {
      "name": "Northstar Media",
      "city": "Sao Paulo",
      "country": "BR",
      "category": "Advertising",
      "enrichedName": "Northstar Media",
      "enrichedCategory": "Advertising"
    },
    "amount": "-42.50",
    "currency": "USD",
    "direction": "debit",
    "category": "purchase",
    "status": "pending",
    "declinedReason": null,
    "disputeStatus": null
  }
}

Verification codes

card.authentication.code is available on request. Contact support to enable it for an existing Cards webhook endpoint. It is not included in new endpoint subscriptions by default. The event carries a one-time code; it does not appear in card activity. Once it is enabled, Send test for this event in your dashboard delivers a sample with the code 000000.

{
  "id": "evt_0123456789abcdef",
  "type": "card.authentication.code",
  "createdAt": "2026-10-20T12:00:02.000Z",
  "livemode": true,
  "data": {
    "id": "c3ds_0123456789abcdef",
    "object": "card.authentication",
    "cardId": null,
    "cardLast4": null,
    "matchStatus": "none",
    "purpose": "purchase",
    "wallet": null,
    "code": "482731",
    "amount": "42.50",
    "currency": "USD",
    "merchant": "ACME Travel",
    "receivedAt": "2026-10-20T12:00:00.000Z",
    "expiresAt": "2026-10-20T12:10:00.000Z"
  }
}

The example code is made up. purpose is purchase for an online purchase, wallet for adding a card to a mobile wallet, or null if the purpose is unknown. wallet contains the wallet name when known; amount, currency, and merchant can also be null. cardLast4 can be null when the message does not include it.

Use cardId only when matchStatus is last4_unique. Otherwise cardId is null: none means no card lookup was possible, not_found means no card matched, and ambiguous means multiple cards matched. Do not guess a card from the merchant or amount.

expiresAt is the estimated expiry: it uses a stated validity period when present, or 10 minutes after receivedAt otherwise. Check it before using the code and ask the cardholder to request another if it has expired. Treat the code and request body as secrets: do not log them or include them in error reports. Verify the endpoint token and respond 2xx quickly. Delivery is single-attempt; a failed or timed-out code delivery is not retried or available for replay.

Verifying deliveries

Every request includes these headers:

  • X-Dolafy-Token — your per-endpoint verification token, shown once when the endpoint is created.
  • Dolafy-Event-Id — unique event id (also the body id).
  • Dolafy-Event-Type — the event type.
  • Dolafy-Delivery-Id — unique delivery id; retries of the same delivery reuse it.

Compare X-Dolafy-Token to the token you stored at creation and reject the request if it does not match. There is no HMAC signature — because the token is sent on every request, your endpoint must use HTTPS, keep the token secret, and avoid logging request headers. Rotate the token by recreating the endpoint.

Delivery semantics

  • Respond with a 2xx quickly, then process the event asynchronously.
  • Delivery is best-effort and single-attempt for card events. There is no durable retry queue or replay endpoint.
  • Make your handlers idempotent by Dolafy-Event-Id (or Dolafy-Delivery-Id). You can reconcile missed transaction events with GET /v1/activity?type=cards; verification codes are not available there.
  • Manual test deliveries sent from the dashboard include top-level "test": true. Never fulfil or move money from a test event.