Card

Overview

Card webhooks notify your application when a card changes state or a card transaction occurs. The current card event types are:

card.authorization
card.charges
card.contactless.activation
card.created
card.created.failed
card.freezed
card.terminated
card.transaction
card.unfreezed
card.updated

The sections below document the payloads currently covered by this guide. Treat event IDs as idempotency keys and return 2xx after the event has been accepted for processing.

Verification decision webhooks

Available for asynchronous document verification. These events do not change the synchronous Nigerian BVN flow or automatically issue a card.

Subscribe an enabled HTTPS endpoint to card.verification.approved and card.verification.rejected using the webhook create or update API. They are opt-in; an empty or omitted event list does not subscribe to these events. When updating a webhook, retain any other events you still want in the list.

Subscription

{
  "url": "https://example.com/webhooks/swerv",
  "description": "Card identity verification",
  "events": ["card.verification.approved", "card.verification.rejected"]
}

card.verification.approved

{
  "event": "card.verification.approved",
  "id": "00b67aaf-36cf-5e6b-a640-4655dbbb733a",
  "data": {
    "customer_id": "cus_example",
    "status": "APPROVED",
    "can_create_card": true,
    "occurred_at": "2026-10-13T14:00:00Z"
  }
}

A rejection uses event: "card.verification.rejected", status: "REJECTED", and can_create_card: false. These events apply to asynchronous document verification for non-Nigerian DEFAULT USD cards, not customer-tier approval. Verification can finish before a card exists, so the payload identifies the customer rather than a card. It contains no identity documents, verification tokens, or provider identifiers. Approval does not create a card or debit the wallet. Before submitting POST /cards, check the current verification status and require can_create_card: true. A delivery is a snapshot; subsequent KYC changes can invalidate eligibility. An approval snapshot can have can_create_card: false when the saved details have changed.

Verification and retries

These two events retain X-SWERV-SECRET and add:

X-SWERV-Event: event type.
X-SWERV-Event-Id: stable delivery ID for this event and webhook endpoint.
X-SWERV-Timestamp: Unix timestamp in seconds for this delivery attempt.
X-SWERV-Signature: t=<timestamp>,v1=<hex_hmac>.

Calculate HMAC-SHA256 with your webhook secret over <timestamp>.<exact raw request body>. Verify using a constant-time comparison, require the signature timestamp to match X-SWERV-Timestamp, and reject stale timestamps using a short tolerance such as five minutes. Do not reserialize JSON before checking the signature. Use the top-level id as your event idempotency key. The body and event/delivery IDs remain stable on retry; the signature timestamp is refreshed. Delivery is at-least-once: acknowledge promptly with 2xx and handle duplicate notifications without submitting duplicate card requests. Failed deliveries use the existing retry mechanism and webhook logs; polling remains a fallback if delivery is missed. Other existing webhook events keep their current authentication protocol.

Created webhook event

This event is fired when a card is created.

card.created

{
  "event": "card.created",
  "data": {
    "id": "card_123456789",
    "business_id": "bus_mviuNSMKi74vTY8yvfP6nQ",
    "status": "STATUS",
    "created_at": "2024-02-06T02:49:18Z",
    "updated_at": "2024-02-06T02:49:18Z"
  }
}

Terminated webhook event

This event is fired when a card is terminated.

card.terminated

{
  "event": "card.terminated",
  "data": {
    "id": "card_123456789",
    "business_id": "bus_mviuNSMKi74vTY8yvfP6nQ",
    "status": "STATUS",
    "created_at": "2024-02-06T02:49:18Z",
    "updated_at": "2024-02-06T02:49:18Z"
  }
}

Freeze webhook event

This event is fired when a card is frozen.

card.freezed

{
  "event": "card.freezed",
  "data": {
    "id": "card_123456789",
    "business_id": "bus_mviuNSMKi74vTY8yvfP6nQ",
    "balance": 1000,
    "status": "STATUS",
    "created_at": "2024-02-06T02:49:18Z",
    "updated_at": "2024-02-06T02:49:18Z"
  }
}

Unfreeze webhook event

This event is fired when a card is unfrozen.

card.unfreezed

{
  "event": "card.unfreezed",
  "data": {
    "id": "card_123456789",
    "business_id": "bus_mviuNSMKi74vTY8yvfP6nQ",
    "balance": 1000,
    "status": "STATUS",
    "created_at": "2024-02-06T02:49:18Z",
    "updated_at": "2024-02-06T02:49:18Z"
  }
}

Updated webhook event

This event is fired when a card is funded.

card.updated

{
  "event": "card.updated",
  "data": {
    "id": "card_123456789",
    "business_id": "bus_mviuNSMKi74vTY8yvfP6nQ",
    "balance": 1000,
    "status": "ACTIVE",
    "created_at": "2024-02-06T02:49:18Z",
    "updated_at": "2024-02-06T02:49:18Z"
  }
}

Transaction webhook event

This event is fired when a card transaction is made.

Transaction Categories

FUNDING
WITHDRAW
Transaction

Transaction Types

DEBIT
CREDIT

Transaction Status

APPROVED
DECLINED
COMPLETED
FAILED
REVERSE

card.transaction

{
  "event": "card.transaction",
  "data": {
    "id": "card_123456789",
    "card_id": "card_123456789",
    "business_id": "bus_mviuNSMKi74vTY8yvfP6nQ",
    "reference": "ref_mviuNSMKi74vTY8yvfP6nQ",
    "amount": 1000,
    "charges": 1000,
    "status": "APPROVED",
    "type": "DEBIT",
    "merchant_name": "Google Inc",
    "merchant_city": "",
    "merchant_country": "",
    "merchant_postal_code": "",
    "merchant_state": "",
    "merchant_mcc": "",
    "merchant_mid": "",
    "currency": "USD",
    "category": "FUNDING",
    "created_at": "2024-02-06T02:49:18Z",
    "updated_at": "2024-02-06T02:49:18Z"
  }
}

Charges webhook event

The card.charges event is fired when a card-related fee is debited from the business USD wallet. It is not emitted when the fee is successfully taken directly from the card. Use charge_type to identify the fee:

CARD_DECLINE_FEE: a declined-card fee that could not be collected from the card.
CROSS_BORDER_FEE: a pending cross-border fee passed to the business wallet.

funding_source is BUSINESS_WALLET for this event.

card.charges

{
  "event": "card.charges",
  "id": "evt_123456789",
  "data": {
    "id": "txn_123456789",
    "reference": "ref_mviuNSMKi74vTY8yvfP6nQ",
    "amount": 0.3,
    "charges": 0,
    "fiat_rate": 0,
    "detail": "Card transaction charges",
    "category": "CARD",
    "type": "DEBIT",
    "status": "COMPLETED",
    "created_at": "2026-07-20T15:30:00Z",
    "updated_at": "2026-07-20T15:30:00Z",
    "card": {
      "id": "card_123456789",
      "business_id": "bus_mviuNSMKi74vTY8yvfP6nQ",
      "status": "ACTIVE",
      "balance": 10,
      "created_at": "2026-07-01T09:00:00Z",
      "updated_at": "2026-07-20T15:30:00Z"
    },
    "charge_type": "CARD_DECLINE_FEE",
    "funding_source": "BUSINESS_WALLET"
  }
}

Contactless activation webhook event

The card.contactless.activation event contains the one-time code needed to add a contactless card to a supported wallet. This confidential event is delivered only after the business explicitly subscribes an eligible webhook.

card.contactless.activation

{
  "event": "card.contactless.activation",
  "id": "3ca42ad1-1eb9-4ee7-828b-e00fbd2234c0",
  "data": {
    "customer_id": "cus_123456789",
    "email": "[email protected]",
    "activation_code": "328893"
  }
}

Swervpay includes these headers:

Header	Description
`X-SWERV-Event`	`card.contactless.activation`
`X-SWERV-Event-Id`	Stable identifier for the activation event
`X-SWERV-Timestamp`	Unix timestamp used to sign the request
`X-SWERV-Signature`	`t=<timestamp>,v1=<hex HMAC-SHA256>`

Verify the signature against the raw request body using the webhook signing key returned when the webhook was created. The signed message is:

<timestamp>.<raw-request-body>

NodeJS

import crypto from "node:crypto";

function verifyContactlessActivation(rawBody, headers, signingKey) {
  const timestamp = headers["x-swerv-timestamp"];
  const supplied = headers["x-swerv-signature"];
  const message = `${timestamp}.${rawBody}`;
  const digest = crypto
    .createHmac("sha256", signingKey)
    .update(message)
    .digest("hex");
  const expected = `t=${timestamp},v1=${digest}`;

  const expectedBuffer = Buffer.from(expected);
  const suppliedBuffer = Buffer.from(supplied || "");
  return expectedBuffer.length === suppliedBuffer.length &&
    crypto.timingSafeEqual(expectedBuffer, suppliedBuffer);
}

Validate that the timestamp is recent, verify the signature before parsing the body, store the event ID for idempotency, and return 2xx promptly. Swervpay attempts confidential delivery up to three times. Activation payloads are redacted from webhook logs and cannot be manually retried through the webhook retry endpoint.

Get Started

Wallet

Transaction

Customer

Collection

FX

Payout

Webhook Events

Card

Overview

Verification decision webhooks

Verification and retries

Created webhook event

Terminated webhook event

Freeze webhook event

Unfreeze webhook event

Updated webhook event

Transaction webhook event

Transaction Categories

Transaction Types

Transaction Status

Charges webhook event

Contactless activation webhook event

​Overview

​Verification decision webhooks

​Verification and retries

​Created webhook event

​Terminated webhook event

​Freeze webhook event

​Unfreeze webhook event

​Updated webhook event

​Transaction webhook event

​Transaction Categories

​Transaction Types

​Transaction Status

​Charges webhook event

​Contactless activation webhook event

Overview

Verification decision webhooks

Verification and retries

Created webhook event

Terminated webhook event

Freeze webhook event

Unfreeze webhook event

Updated webhook event

Transaction webhook event

Transaction Categories

Transaction Types

Transaction Status

Charges webhook event

Contactless activation webhook event