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.

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

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

​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

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