Card Issuer Webhooks

Card issuer webhooks let Yativo push event notifications to your server the moment something happens in your program — a deposit settles, a customer’s card is funded, a transaction is authorized, or a card is frozen. This guide covers every step from registering a URL to handling the complete event lifecycle.

Card issuer events and general crypto events (deposits, swaps, transactions) are delivered through the same webhook service. Register once at POST /v1/webhook/create-webhook and subscribe to any combination of event types.

How It Works

Your server exposes a public HTTPS URL. Yativo sends a signed POST request to that URL each time an event occurs in your issuer program. Your server verifies the signature, acknowledges receipt with HTTP 200, and processes the event.

Yativo event occurs
       │
       ▼
POST https://your-app.com/webhooks/yativo
       │
       ▼
Verify X-Yativo-Signature header
       │
       ▼
Return HTTP 200 immediately
       │
       ▼
Process event asynchronously

Step 1 — Build Your Webhook Endpoint

Your endpoint must:

Accept POST requests at a public HTTPS URL
Capture the raw request body before JSON-parsing it (required for signature verification)
Return HTTP 2xx within 30 seconds
Process event logic asynchronously after returning 200

TypeScript (Express)
Python (Flask)
PHP

import express from "express";
import crypto from "crypto";

const app = express();

// Use express.raw() — not express.json() — so you have the raw body for signature verification
app.post(
  "/webhooks/yativo/card-issuer",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const signature = req.headers["x-yativo-signature"] as string;
    const timestamp = req.headers["x-yativo-timestamp"] as string;
    const secret = process.env.YATIVO_WEBHOOK_SECRET!;

    if (!verifySignature(req.body, signature, timestamp, secret)) {
      return res.status(401).json({ error: "Invalid signature" });
    }

    // Acknowledge immediately — Yativo waits up to 30 seconds
    res.sendStatus(200);

    // Parse and dispatch asynchronously
    const event = JSON.parse(req.body.toString());
    setImmediate(() => handleCardIssuerEvent(event).catch(console.error));
  }
);

function verifySignature(
  rawBody: Buffer,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  if (!signature || !timestamp) return false;
  const signed = `${timestamp}.${rawBody.toString("utf8")}`;
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(signed).digest("hex");
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expected)
    );
  } catch {
    return false;
  }
}

async function handleCardIssuerEvent(event: any) {
  // Use event.id as an idempotency key — the same event may be delivered more than once
  const alreadyProcessed = await db.webhookEvents.findById(event.id);
  if (alreadyProcessed) return;

  switch (event.type) {
    case "master_wallet.deposit":
      if (event.data.status === "settled") {
        // withdrawal_id present → this credit is from a card withdrawal settling
        await handleMasterWalletDeposit(event.data);
      }
      break;
    case "customer.funded":
      await handleCustomerFunded(event.data);
      break;
    case "customer.funding.failed":
      await handleCustomerFundingFailed(event.data);
      break;
    case "transaction.authorized":
      await handleTransactionAuthorized(event.data);
      break;
    case "transaction.settled":
      await handleTransactionSettled(event.data);
      break;
    case "transaction.declined":
      await handleTransactionDeclined(event.data);
      break;
    case "card.frozen":
    case "card.unfrozen":
    case "card.voided":
      await handleCardStatusChange(event.type, event.data);
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }

  await db.webhookEvents.insert({ id: event.id, type: event.type, processedAt: new Date() });
}

from flask import Flask, request, jsonify
import hmac
import hashlib
import threading
import os

app = Flask(__name__)

@app.route("/webhooks/yativo/card-issuer", methods=["POST"])
def card_issuer_webhook():
    raw_body = request.get_data()
    signature = request.headers.get("X-Yativo-Signature", "")
    timestamp = request.headers.get("X-Yativo-Timestamp", "")
    secret = os.environ["YATIVO_WEBHOOK_SECRET"]

    if not verify_signature(raw_body, signature, timestamp, secret):
        return jsonify({"error": "Invalid signature"}), 401

    event = request.get_json(force=True)

    # Respond immediately, dispatch in background
    thread = threading.Thread(target=handle_event, args=(event,))
    thread.daemon = True
    thread.start()

    return "", 200


def verify_signature(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    if not signature or not timestamp:
        return False
    signed = f"{timestamp}.{raw_body.decode('utf-8')}"
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), signed.encode("utf-8"), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

<?php

$rawBody = file_get_contents("php://input");
$signature = $_SERVER["HTTP_X_YATIVO_SIGNATURE"] ?? "";
$timestamp  = $_SERVER["HTTP_X_YATIVO_TIMESTAMP"] ?? "";
$secret     = getenv("YATIVO_WEBHOOK_SECRET");

if (!verifySignature($rawBody, $signature, $timestamp, $secret)) {
    http_response_code(401);
    echo json_encode(["error" => "Invalid signature"]);
    exit;
}

// Acknowledge immediately
http_response_code(200);
echo "OK";
if (function_exists("fastcgi_finish_request")) {
    fastcgi_finish_request();
}

$event = json_decode($rawBody, true);
handleEvent($event);


function verifySignature(string $rawBody, string $signature, string $timestamp, string $secret): bool {
    if (empty($signature) || empty($timestamp)) return false;
    $signed   = "{$timestamp}.{$rawBody}";
    $expected = "sha256=" . hash_hmac("sha256", $signed, $secret);
    return hash_equals($expected, $signature);
}

Always use a timing-safe comparison (timingSafeEqual, hmac.compare_digest, hash_equals). A regular === check is vulnerable to timing attacks.

Step 2 — Register Your Webhook

Register your endpoint at the unified webhook endpoint. You can subscribe to card issuer events, general crypto events, or any mix.

curl -X POST 'https://crypto-api.yativo.com/api/v1/webhook/create-webhook' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://api.yourapp.com/webhooks/yativo",
    "events": [
      "master_wallet.deposit",
      "master_wallet.swap",
      "master_wallet.customer_funded",
      "master_wallet.withdrawal",
      "customer.funded",
      "customer.funding.failed",
      "customer.balance.updated",
      "wallet.deposit.confirmed",
      "card.created",
      "card.activated",
      "card.frozen",
      "card.unfrozen",
      "card.voided",
      "card.lost",
      "card.stolen",
      "card.cancelled",
      "card.deactivated",
      "transaction.authorized",
      "transaction.settled",
      "transaction.declined",
      "transaction.reversed",
      "transaction.refund.created"
    ],
    "description": "Production card issuer webhook"
  }'

const response = await fetch(
  "https://crypto-api.yativo.com/api/v1/webhook/create-webhook",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.YATIVO_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://api.yourapp.com/webhooks/yativo",
      events: ["*"], // Subscribe to all events
      description: "Production card issuer webhook",
    }),
  }
);

const { data } = await response.json();

console.log("Webhook ID:", data.webhook_id);
console.log("Secret:", data.secret); // Store securely — also retrievable via GET /v1/yativo-card/webhooks/:webhookId

Response

{
  "status": true,
  "message": "Webhook created successfully",
  "data": {
    "webhook_id": "68241abc2f3d4e5f6a7b8c9d",
    "url": "https://api.yourapp.com/webhooks/yativo",
    "events": ["master_wallet.deposit", "customer.funded", "..."],
    "secret": "whsec_a8f3c2e1d4b7f9e2c5a3b6d8f1e4c7a2b5d8e1f4c7a2b5d8",
    "created_at": "2026-05-12T14:00:00.000Z"
  }
}

The secret is included in the creation response and is also retrievable later via GET /v1/yativo-card/webhooks/:webhookId. Store it in a secure environment variable or secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault). If you need to invalidate a compromised secret, rotate it via POST /v1/yativo-card/webhooks/:webhookId/rotate-secret.

Pass "events": ["*"] to receive every event type. You can narrow the list later via PUT /v1/yativo-card/webhooks/:webhookId.

Step 3 — Verify Signatures

Every webhook POST includes four security headers:

Header	Description
`X-Yativo-Signature`	`sha256=<HMAC-SHA256 hex>` of the signed string
`X-Yativo-Timestamp`	Unix timestamp (seconds) when the event was dispatched
`X-Yativo-Event`	The event type (e.g. `customer.funded`)
`X-Yativo-Delivery-Id`	Unique delivery ID — used to retry individual deliveries

The signature is computed as:

HMAC-SHA256(secret, "<timestamp>.<raw JSON body>")

The <raw JSON body> is the exact bytes received — not re-serialized. This is why you must capture the raw body before JSON-parsing. Replay attack protection: Also check that the timestamp is within 5 minutes of your server clock. Discard requests that are older.

function verifySignature(
  rawBody: Buffer,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  if (!signature || !timestamp) return false;

  // Guard against replay attacks
  const age = Math.abs(Date.now() / 1000 - parseInt(timestamp, 10));
  if (age > 300) return false; // older than 5 minutes

  const signed = `${timestamp}.${rawBody.toString("utf8")}`;
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(signed).digest("hex");

  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expected)
    );
  } catch {
    return false;
  }
}

The Event Lifecycle

The following diagram shows the full lifecycle of a card issuer program, and where webhook events fire at each stage.

Master wallet deposit → settled

When you send funds to your master wallet deposit address, Yativo fires master_wallet.deposit events as the deposit progresses. The number of events depends on the deposit path:

Two-step deposits (funds routed through an intermediate settlement): a processing event fires first when the deposit is detected, followed by a settled event when the funds land in your spendable balance.
One-step deposits (funds that settle directly): only a single settled event fires — there is no preceding processing event.

You send funds to your deposit address
           │
           ▼  (on detection — two-step deposits only)
  ┌────────────────────────────────────┐
  │  master_wallet.deposit             │
  │  status: "processing"             │
  └────────────────────────────────────┘
           │
           ▼  (once funds are spendable)
  ┌────────────────────────────────────┐
  │  master_wallet.deposit             │
  │  status: "settled"                │
  │  settled_amount: 499.75           │
  └────────────────────────────────────┘
           │
           ▼
  Master wallet balance updated

Always act on status: "settled" — this is the authoritative confirmation that funds are available. If you receive only a settled event with no prior processing event, that is expected for one-step deposit paths.

Fund customer card

When you call POST /v1/card-issuer/fund-customer, two events fire in tandem: master_wallet.customer_funded (your master wallet was debited) and customer.funded (the customer’s card wallet was credited).

POST /v1/card-issuer/fund-customer
           │
           ▼
  ┌────────────────────────────────────┐
  │  master_wallet.customer_funded     │
  │  Your master wallet debited       │
  └────────────────────────────────────┘
           │
  ┌────────────────────────────────────┐
  │  customer.funded                   │
  │  Customer card wallet credited    │
  └────────────────────────────────────┘
           │
  ┌────────────────────────────────────┐
  │  customer.balance.updated          │
  │  New card balance snapshot        │
  └────────────────────────────────────┘

If the funding transfer fails (e.g. network error or insufficient master wallet balance), only customer.funding.failed fires.

Card transaction lifecycle

When your customer uses their card, events fire at each stage of the authorization → settlement cycle.

Customer taps card at merchant
           │
           ▼
  ┌────────────────────────────────────┐
  │  transaction.authorized            │
  │  Funds reserved (hold placed)     │
  └────────────────────────────────────┘
           │
  ┌────────────────────────────────────┐
  │  customer.balance.updated          │
  │  available_balance reduced        │
  └────────────────────────────────────┘
           │
           ▼  (merchant batch clearing, typically same day)
  ┌────────────────────────────────────┐
  │  transaction.settled               │
  │  Hold released, charge finalized  │
  └────────────────────────────────────┘
           │
  ┌────────────────────────────────────┐
  │  customer.balance.updated          │
  │  ledger_balance reduced           │
  └────────────────────────────────────┘

A declined authorization fires transaction.declined instead of transaction.authorized. A reversal fires transaction.reversed.

Card status changes

Card lifecycle events fire whenever a card’s status changes — whether triggered by your API, by the customer, or by a compliance action.

card.created        → Virtual card issued to a customer
card.activated      → Physical card activated (physical cards only)
card.frozen         → Spending temporarily paused
card.unfrozen       → Spending re-enabled (upstream status: "active")
card.voided         → Card permanently deactivated
card.lost           → Card reported lost (new card required)
card.stolen         → Card reported stolen (new card required)
card.cancelled      → Card cancelled
card.deactivated    → Card deactivated

Event Reference

Amount fields — Every monetary amount is provided in two formats:

amount (float) — human-readable decimal, e.g. 12.50
amount_minor (integer) — minor currency units (cents), e.g. 1250

Use floats for display. Use minor units for precise arithmetic, storing in integer columns, or comparing amounts without floating-point error. Both are always present when the amount is known; both are null when the amount is unavailable.

Envelope

All events share this structure. The data object is event-specific.

{
  "id": "evt_1747058400000_abc123",
  "type": "customer.funded",
  "created_at": "2026-05-12T14:10:00.000Z",
  "data": { }
}

Field	Type	Description
`id`	string	Unique event ID — use as idempotency key
`type`	string	Event type
`created_at`	ISO 8601	When the event was generated
`data`	object	Event-specific payload (see below)

`master_wallet.deposit`

Fires when a deposit is detected or settles into your spendable balance. One-step deposits fire only settled. Two-step deposits fire processing first, then settled. All amount fields are provided as both a decimal float and an integer in minor units (cents). For example, 500.00 USD → amount: 500.00, amount_minor: 50000.

Processing

{
  "id": "evt_1747058400000_abc123",
  "type": "master_wallet.deposit",
  "created_at": "2026-05-12T14:00:00.000Z",
  "data": {
    "settlement_id": "bridge_1745123456_2ea87af00de1",
    "source_currency": "USDC_SOL",
    "source_amount": 500.00,
    "source_amount_minor": 50000,
    "tx_hash": "5KtP3MzXYZABCDE1234567890abcdef12345678901234567890abcdef1234567",
    "status": "processing"
  }
}

Settled — regular deposit

{
  "id": "evt_1747058520000_def456",
  "type": "master_wallet.deposit",
  "created_at": "2026-05-12T14:02:00.000Z",
  "data": {
    "settlement_id": "bridge_1745123456_2ea87af00de1",
    "deposit_amount": 499.75,
    "deposit_amount_minor": 49975,
    "wallet_balance": 999.50,
    "wallet_balance_minor": 99950,
    "currency": "USD",
    "tx_hash": "0xa8739436c44460738a4147055530e450f8b55694e2448875e72cd25eb29cd21f",
    "solana_tx_hash": "5KtP3MzXYZABCDE1234567890abcdef12345678901234567890abcdef1234567",
    "status": "settled"
  }
}

Settled — withdrawal credit

{
  "id": "evt_1747058520000_ghi012",
  "type": "master_wallet.deposit",
  "created_at": "2026-05-12T14:02:00.000Z",
  "data": {
    "settlement_id": "6a294844e71b09a046f28103",
    "withdrawal_id": "cwd_1748012345678_x7k2qp",
    "yativo_card_id": "yativo_card_customer_...",
    "deposit_amount": 50.0,
    "deposit_amount_minor": 5000,
    "wallet_balance": 550.0,
    "wallet_balance_minor": 55000,
    "currency": "USD",
    "tx_hash": "0xa8739436c44460738a4147055530e450f8b55694e2448875e72cd25eb29cd21f",
    "solana_tx_hash": null,
    "status": "settled"
  }
}

master_wallet.deposit fires for two distinct scenarios: (1) a new deposit credited to your master wallet, and (2) funds returning to your master wallet when a card withdrawal settles. In the withdrawal case the payload includes withdrawal_id and yativo_card_id so you can correlate it with the originating card.withdrawal.settled and master_wallet.withdrawal events. When withdrawal_id is absent the event is a regular deposit.

Field	Type	Description
`source_currency`	string	Currency/chain of the incoming deposit (e.g. `USDC_SOL`, `USDC_XDC`). Present on `processing` events only.
`source_amount`	float	Amount sent by the depositor, in `source_currency` units. Present on `processing` events.
`source_amount_minor`	integer	`source_amount` in minor units (cents).
`deposit_amount`	float	Amount that arrived in your wallet after settlement. Present on `settled` events.
`deposit_amount_minor`	integer	`deposit_amount` in minor units (cents).
`wallet_balance`	float \| null	Total wallet balance after this credit. Present on `settled` events.
`wallet_balance_minor`	integer \| null	`wallet_balance` in minor units (cents).
`currency`	string	Wallet currency (e.g. `USD`, `EUR`, `GBP`). Present on `settled` events.
`settlement_id`	string \| null	Internal settlement or bridge transaction reference.
`tx_hash`	string \| null	On-chain transaction hash of the final settlement.
`solana_tx_hash`	string \| null	Original Solana deposit transaction signature. Present for `USDC_SOL` deposits; `null` for all other paths including withdrawal credits.
`withdrawal_id`	string \| null	Present only when this event is a withdrawal credit. Matches the `withdrawal_id` on the corresponding `card.withdrawal.settled` and `master_wallet.withdrawal` events.
`yativo_card_id`	string \| null	Present only when this event is a withdrawal credit. Identifies the card the funds were withdrawn from.

`master_wallet.swap`

Fired when a currency swap is submitted from your master wallet (e.g. USD → EUR).

{
  "id": "evt_1747058700000_ghi789",
  "type": "master_wallet.swap",
  "created_at": "2026-05-12T14:05:00.000Z",
  "data": {
    "swap_id": "0x4a1b2c3d...",
    "from_token": "USD",
    "to_token": "EUR",
    "amount": 1000.00,
    "amount_minor": 100000,
    "expected_output": 921.50,
    "expected_output_minor": 92150,
    "status": "submitted"
  }
}

`master_wallet.customer_funded`

Fired alongside customer.funded whenever your master wallet is debited. Includes remaining_balance when available and tx_hash with the on-chain transaction hash of the funding transfer.

{
  "id": "evt_1747059001000_mwf01",
  "type": "master_wallet.customer_funded",
  "created_at": "2026-05-12T14:10:00.000Z",
  "data": {
    "transfer_id": "tx_1745128800_9fc12ab3e4d5",
    "customer_id": "69f0bdf29a84752db9cc8ff9",
    "amount": 50.00,
    "amount_minor": 5000,
    "currency": "USD",
    "tx_hash": "0xa8739436c44460738a4147055530e450f8b55694e2448875e72cd25eb29cd21f",
    "status": "completed",
    "remaining_balance": 114.98,
    "remaining_balance_minor": 11498
  }
}

`customer.funded`

Fired when a customer’s card wallet has been successfully credited.

{
  "id": "evt_1747059000000_ghi789",
  "type": "customer.funded",
  "created_at": "2026-05-12T14:10:00.000Z",
  "data": {
    "transfer_id": "tx_1745128800_9fc12ab3e4d5",
    "customer_id": "69f0bdf29a84752db9cc8ff9",
    "amount": 50.00,
    "amount_minor": 5000,
    "currency": "USD",
    "tx_hash": "0xa8739436c44460738a4147055530e450f8b55694e2448875e72cd25eb29cd21f",
    "status": "completed"
  }
}

`customer.funding.failed`

Fired when a funding transfer to a customer’s card wallet fails.

{
  "id": "evt_1747059000000_fail01",
  "type": "customer.funding.failed",
  "created_at": "2026-05-12T14:10:00.000Z",
  "data": {
    "customer_id": "69f0bdf29a84752db9cc8ff9",
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "amount": 50.00,
    "amount_minor": 5000,
    "currency": "USD"
  }
}

`wallet.deposit.confirmed`

Fired when a customer’s account wallet balance increases — i.e. a deposit has arrived. This is the primary event for detecting incoming funds to a customer card wallet.

{
  "id": "evt_1747060100000_dep01",
  "type": "wallet.deposit.confirmed",
  "created_at": "2026-05-12T14:29:45.000Z",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "amount": 50.00,
    "amount_minor": 5000,
    "new_balance": 145.50,
    "new_balance_minor": 14550,
    "currency": "EUR",
    "timestamp": "2026-05-12T14:29:45.000Z"
  }
}

Field	Type	Description
`amount`	float	Amount deposited (balance delta)
`amount_minor`	integer	`amount` in minor units (cents)
`new_balance`	float	Customer’s new total balance after the deposit
`new_balance_minor`	integer	`new_balance` in minor units (cents)
`currency`	string \| null	Card currency (`USD`, `EUR`, `GBP`)

A customer.balance.updated event fires for the same balance change. wallet.deposit.confirmed fires only when the balance increased; customer.balance.updated fires for all balance changes including spend and reversal.

`customer.balance.updated`

Fired after any card balance change — top-up, purchase authorization, settlement, reversal, or periodic reconciliation.

{
  "id": "evt_1747060200000_stu901",
  "type": "customer.balance.updated",
  "created_at": "2026-05-12T14:30:00.000Z",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "ledger_balance": 45.23,
    "ledger_balance_minor": 4523,
    "available_balance": 38.50,
    "available_balance_minor": 3850,
    "pending_balance": 6.73,
    "pending_balance_minor": 673,
    "currency": "EUR",
    "balance_source": "live",
    "trigger": "funding",
    "transfer_id": "bridge_1779218694580_c22259aa6951",
    "tx_hash": "0x3fbd8b6c6a1e2e6f0a1b8f6a5b4c3d2e1f0a1b8f6a5b4c3d2e1f0a1b8f6a5b4c",
    "timestamp": "2026-05-12T14:30:00.000Z"
  }
}

Field	Type	Description
`ledger_balance`	float	Total balance in the customer’s account wallet
`ledger_balance_minor`	integer	`ledger_balance` in minor units (cents)
`available_balance`	float	Spendable balance after pending authorizations
`available_balance_minor`	integer	`available_balance` in minor units (cents)
`pending_balance`	float \| null	Held for authorized but not yet settled transactions. `null` when no pending authorizations
`pending_balance_minor`	integer \| null	`pending_balance` in minor units (cents)
`currency`	string \| null	`USD`, `EUR`, or `GBP`
`balance_source`	string \| null	`"reconciliation"` when fired by the background reconciliation job; absent or `null` for live card events
`trigger`	string \| null	What we determined caused this balance change: `"funding"`, `"withdraw"`, or `"transaction"` (a card purchase). `null` if we couldn’t match it to a known operation within a 10-minute window.
`transfer_id`	string \| null	Our own reference for the underlying operation — matches the `transfer_id` you already received on `customer.funded`/`master_wallet.customer_funded` (funding), the `withdrawal_id` from the withdrawal endpoints (withdrawal), or the transaction reference (card purchase). Use this to reconcile a `customer.balance.updated` event back to the operation that caused it.
`tx_hash`	string \| null	On-chain hash for the underlying operation, when one exists (funding/withdrawal). `null` for card purchases, which don’t have a dedicated on-chain leg at this stage.

pending_balance / pending_balance_minor are always null when balance_source is "reconciliation" — the reconciliation job reads the on-chain settled balance and cannot determine pending authorizations. Use available_balance for spendable funds.

A single top-up typically produces two customer.balance.updated events a couple of minutes apart — the first when the ledger reflects the incoming funds, the second when they become spendable (available_balance catches up). Both carry the same trigger/transfer_id, since both stem from the same underlying operation — use transfer_id to recognize them as the same event rather than treating the second as a new, unrelated top-up.trigger/transfer_id/tx_hash are inferred by matching this balance change against our own records of your recent funding/withdrawal/transaction activity for this card, not supplied directly by the card network (which doesn’t include a correlator on this event type). If nothing matched within the 10-minute window, all three come back null.

`card.created`

Fired when a new virtual card is issued to a customer. card_id is the card token identifier. type and status reflect values from the upstream card provider and may be null depending on the event payload received.

{
  "id": "evt_1747057800000_abc001",
  "type": "card.created",
  "created_at": "2026-05-12T13:50:00.000Z",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "card_id": "card_token_abc123",
    "type": null,
    "status": null,
    "timestamp": "2026-05-12T13:50:00.000Z"
  }
}

`card.activated`

Fired when a physical card is activated by the cardholder. Virtual cards do not fire this event.

{
  "id": "evt_1747057900000_act01",
  "type": "card.activated",
  "created_at": "2026-05-12T13:52:00.000Z",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "card_id": "card_token_abc123",
    "timestamp": "2026-05-12T13:52:00.000Z"
  }
}

`card.frozen` / `card.unfrozen`

For card.frozen the status field reflects the upstream frozen status string. For card.unfrozen the status field is "active" — the upstream provider reports the card status returning to active when a freeze is lifted.

card.frozen

{
  "id": "evt_1747059600000_mno345",
  "type": "card.frozen",
  "created_at": "2026-05-12T14:20:00.000Z",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "card_id": "card_token_abc123",
    "status": "Frozen",
    "timestamp": "2026-05-12T14:20:00.000Z"
  }
}

card.unfrozen

{
  "id": "evt_1747059700000_unf01",
  "type": "card.unfrozen",
  "created_at": "2026-05-12T14:21:00.000Z",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "card_id": "card_token_abc123",
    "status": "active",
    "timestamp": "2026-05-12T14:21:00.000Z"
  }
}

The card_id in webhook events is the card token identifier and may differ from the card_id returned by the Get Customer API. Use yativo_card_id as the stable cross-reference between events and API responses.

`card.lost` / `card.stolen` / `card.voided` / `card.cancelled` / `card.deactivated`

Same shape as card.frozen — the envelope type identifies the event and data.status reflects the upstream status string for that change.

{
  "id": "evt_1747059900000_pqr678",
  "type": "card.lost",
  "created_at": "2026-05-12T14:25:00.000Z",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "card_id": "card_token_abc123",
    "status": "Lost",
    "timestamp": "2026-05-12T14:25:00.000Z"
  }
}

Transaction event field reference

All transaction.* events share the same data shape. Fields are populated from card network data and some may be null depending on the transaction type or network.

Field	Type	Notes
`yativo_card_id`	string	Stable card identifier — use this as the cross-reference key
`card_id`	string \| null	Card token from the card network
`transaction_id`	string \| null	Network transaction ID. Use this as the key for deduplication. Falls back to the webhook event `id` when not provided by the card network.
`blockchain_tx_hash`	string \| null	Hash of the on-chain settlement transaction that debited the card’s wallet. Populated on `transaction.authorized` (we wait for this to be available before dispatching — see note below). May be `null` on other event types where no on-chain leg exists yet (e.g. `transaction.declined`, or a reversal that never settled on-chain).
`type`	string \| null	Transaction type as reported by the card network (e.g. `"Payment"`, `"Refund"`)
`amount`	float \| null	Transaction amount as a decimal number, in the merchant’s local currency
`amount_minor`	integer \| null	`amount` in minor units (cents)
`currency`	string \| null	ISO 4217 alpha-3 currency code of `amount` — the merchant’s local currency (e.g. `"EUR"`, `"USD"`, `"BRL"`)
`billing_amount`	float \| null	The amount actually debited from the card’s own settlement currency. Present on every transaction, not only foreign-currency ones — on a same-currency purchase it simply equals `amount`.
`billing_amount_minor`	integer \| null	`billing_amount` in minor units (cents)
`billing_currency`	string \| null	ISO 4217 alpha-3 currency code of `billing_amount` — the card’s own currency. Equals `currency` when the purchase was made in the card’s native currency.
`fx_rate`	float \| null	Local-currency units per 1 unit of billing currency: `fx_rate = amount / billing_amount`. Reads as “1 = ” — e.g. `924.3827` means `1 USD = 924.3827 CLP`. Equals `1` on a same-currency purchase. Provided so you don’t have to compute it, but if you ever need to derive `billing_amount` yourself: `billing_amount = amount / fx_rate`.
`merchant`	string \| null	Merchant name — `null` for contactless/tap or when not provided by the network
`merchant_category`	string \| null	Merchant category code (MCC)
`merchant_city`	string \| null	Merchant city — `null` when not provided
`merchant_country`	string \| null	ISO 3166 alpha-2 country code (e.g. `"FR"`, `"BR"`) — `null` when not provided
`status`	string \| null	Raw status string from the card network — values vary (e.g. `"Approved"`, `"Declined"`)
`timestamp`	ISO 8601	When the card network event occurred

status and type values are passed through directly from the card network and are not normalized. Do not hard-code comparisons against specific strings — check for membership in an expected set and handle unknowns gracefully.

`transaction.authorized`

Fired once per card purchase, when the authorization clears (not at the earlier point-of-sale authorization moment — we intentionally wait for clearing so this event always carries both transaction_id and blockchain_tx_hash together, rather than firing an incomplete notification first). A customer.balance.updated event follows immediately.

Use data.transaction_id (not event.id) as your reconciliation key. If transaction_id is null, fall back to event.id.

{
  "id": "evt_1747059300000_jkl012",
  "type": "transaction.authorized",
  "created_at": "2026-05-12T14:15:00.000Z",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "card_id": "544599049",
    "transaction_id": "tx_9d8e7f6a5b4c3d2e1f",
    "blockchain_tx_hash": "0xedbca669196b14ddc4b5a8b6fd6c313a1400795cdabe686b3d4b908d8e8279bb",
    "type": "Payment",
    "amount": 12.50,
    "amount_minor": 1250,
    "currency": "EUR",
    "billing_amount": 12.50,
    "billing_amount_minor": 1250,
    "billing_currency": "EUR",
    "fx_rate": 1,
    "merchant": "Starbucks",
    "merchant_category": "5812",
    "merchant_city": "Paris",
    "merchant_country": "FR",
    "status": "Approved",
    "timestamp": "2026-05-12T14:15:00.000Z"
  }
}

This card settles in EUR and the purchase was also in EUR, so billing_amount/billing_currency simply match amount/currency and fx_rate is 1 — no conversion took place. See the transaction.settled example below for a foreign-currency purchase, where they differ.

`transaction.settled`

Fired when the merchant batch clears and the authorization is finalized.

{
  "id": "evt_1747063800000_uvw234",
  "type": "transaction.settled",
  "created_at": "2026-05-12T15:30:00.000Z",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "card_id": "544599049",
    "transaction_id": "tx_9d8e7f6a5b4c3d2e1f",
    "blockchain_tx_hash": null,
    "type": "Payment",
    "amount": 101,
    "amount_minor": 10100,
    "currency": "BRL",
    "billing_amount": 20.15,
    "billing_amount_minor": 2015,
    "billing_currency": "USD",
    "fx_rate": 5.0124,
    "merchant": "MERCADOPAGO*STORE",
    "merchant_category": "7298",
    "merchant_city": null,
    "merchant_country": "BR",
    "status": "Approved",
    "timestamp": "2026-05-12T15:30:00.000Z"
  }
}

This example shows a foreign-currency purchase: a USD-denominated card used at a Brazilian merchant. amount/currency are the merchant’s local currency (BRL, what was charged at the point of sale); billing_amount/billing_currency are what was actually debited from the card (USD). fx_rate (5.0124) reads as “1 USD = 5.0124 BRL” — check: 101 / 5.0124 ≈ 20.15, which matches billing_amount.blockchain_tx_hash on transaction.settled is not guaranteed the way it is on transaction.authorized — treat it as best-effort here.merchant and merchant_city may come back null on some networks/transaction stages even when populated on the corresponding transaction.authorized event for the same transaction_id — treat them as best-effort, not guaranteed on every event.

`transaction.declined`

Fired when a card transaction is declined.

{
  "id": "evt_1747059400000_dec01",
  "type": "transaction.declined",
  "created_at": "2026-05-12T14:16:00.000Z",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "card_id": "544599049",
    "transaction_id": "tx_9d8e7f6a5b4c3d2e1f",
    "blockchain_tx_hash": null,
    "type": "Payment",
    "amount": 200.00,
    "amount_minor": 20000,
    "currency": "EUR",
    "merchant": null,
    "merchant_category": "5411",
    "merchant_city": null,
    "merchant_country": "DE",
    "status": "Declined",
    "timestamp": "2026-05-12T14:16:00.000Z"
  }
}

`transaction.reversed`

Fired when an authorization is reversed (e.g. a cancelled hold before settlement).

{
  "id": "evt_1747060000000_rev01",
  "type": "transaction.reversed",
  "created_at": "2026-05-12T14:26:00.000Z",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "card_id": "card_token_abc123",
    "transaction_id": "tx_9d8e7f...",
    "amount": 12.50,
    "amount_minor": 1250,
    "currency": "EUR",
    "status": "REVERSED",
    "timestamp": "2026-05-12T14:26:00.000Z"
  }
}

`transaction.refund.created`

Fired when a merchant issues a refund.

{
  "id": "evt_1747064000000_ref01",
  "type": "transaction.refund.created",
  "created_at": "2026-05-12T15:32:00.000Z",
  "data": {
    "yativo_card_id": "yativo_card_customer_8f9a...",
    "card_id": "card_token_abc123",
    "transaction_id": "tx_9d8e7f...",
    "amount": 12.50,
    "amount_minor": 1250,
    "currency": "EUR",
    "status": "REFUNDED",
    "timestamp": "2026-05-12T15:32:00.000Z"
  }
}

Managing Webhooks

List all subscriptions

GET /v1/yativo-card/webhooks
Authorization: Bearer YOUR_TOKEN

Get one subscription

GET /v1/yativo-card/webhooks/:webhookId
Authorization: Bearer YOUR_TOKEN

Update URL, events, or enabled state

curl -X PUT 'https://crypto-api.yativo.com/api/v1/yativo-card/webhooks/68241abc...' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://api.yourapp.com/webhooks/yativo/v2",
    "events": ["customer.funded", "transaction.authorized", "transaction.declined"],
    "enabled": true
  }'

Rotate signing secret

POST /v1/yativo-card/webhooks/:webhookId/rotate-secret
Authorization: Bearer YOUR_TOKEN

The response returns the new secret — store it immediately, then update your environment variable.

Delete a subscription

DELETE /v1/yativo-card/webhooks/:webhookId
Authorization: Bearer YOUR_TOKEN

Delivery history

# Deliveries for one webhook
GET /v1/yativo-card/webhooks/:webhookId/deliveries

# All deliveries across webhooks
GET /v1/yativo-card/webhooks/deliveries/all

Retry a failed delivery

POST /v1/yativo-card/webhooks/deliveries/:deliveryId/retry
Authorization: Bearer YOUR_TOKEN

Retry Policy

If your endpoint returns a non-2xx response, times out (> 30 s), or is unreachable, Yativo retries using exponential backoff:

Attempt	Delay after previous attempt
1 (initial)	—
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	12 hours
7	24 hours

After 7 failed attempts the delivery is marked permanently failed — no further automatic retries. Replay it manually via POST /v1/yativo-card/webhooks/deliveries/:deliveryId/retry. If your endpoint fails 100 consecutive deliveries, Yativo automatically disables the subscription to protect your program’s event queue. Re-enable it with PUT /v1/yativo-card/webhooks/:webhookId and { "enabled": true } after resolving the issue.

Best Practices

Return 200 first, process after. Yativo waits up to 30 seconds for a response. Enqueue the event to a job queue (BullMQ, Celery, SQS) before returning — don’t block on database writes or downstream calls. Deduplicate with event.id. Yativo deduplicates deliveries server-side so the same upstream event is not queued twice, but network-level retries can still cause your endpoint to receive the same delivery more than once. Store processed event IDs in a database table with a unique constraint and skip duplicates. Do not return 200 speculatively. Only acknowledge when you have successfully enqueued the event. If your queue is unavailable, return 500 to trigger a retry. Handle unknown event types gracefully. Log and ignore event types you don’t recognise rather than throwing an error. Yativo adds new event types over time — unknown types should not break your handler. Subscribe to the events you need. Use a focused event list rather than "*" in production to reduce noise and make your handler logic explicit.

Idempotent Handler Pattern

async function handleCardIssuerEvent(event: {
  id: string;
  type: string;
  data: any;
}) {
  // 1. Deduplicate
  const exists = await db.processedEvents.findUnique({ where: { id: event.id } });
  if (exists) return;

  // 2. Process
  switch (event.type) {
    case "master_wallet.deposit":
      if (event.data.status === "settled") {
        if (event.data.withdrawal_id) {
          // Withdrawal credit — funds returned from a card withdrawal.
          // withdrawal_id links this back to the originating card.withdrawal.settled event.
          await recordWithdrawalCredit(event.data.withdrawal_id, event.data.deposit_amount, event.data.tx_hash);
        } else {
          // Regular deposit — new funds arriving from an external source.
          await updateMasterWalletBalance(event.data.deposit_amount, event.data.currency);
        }
      }
      // Ignore processing events — act only on settled
      break;

    case "master_wallet.withdrawal":
      // Companion to card.withdrawal.settled — confirms master wallet was credited.
      // Use for master wallet reconciliation; withdrawal_id is the join key.
      await recordMasterWalletWithdrawalSettled(event.data.withdrawal_id, event.data.tx_hash);
      break;

    case "customer.funded":
      await creditCustomerLedger(event.data.customer_id, event.data.amount, event.data.currency);
      break;

    case "customer.funding.failed":
      await flagFailedFunding(event.data.customer_id, event.data.amount);
      await notifyOpsTeam(event);
      break;

    case "customer.balance.updated":
      await syncCustomerBalance(event.data.yativo_card_id, {
        ledger: event.data.ledger_balance,
        available: event.data.available_balance,
        pending: event.data.pending_balance,
      });
      break;

    case "transaction.authorized":
      await recordPendingTransaction(event.data);
      break;

    case "transaction.settled":
      await finalizeTransaction(event.data.transaction_id);
      break;

    case "transaction.declined":
      await notifyCustomerOfDecline(event.data.yativo_card_id);
      break;

    case "card.frozen":
    case "card.voided":
    case "card.lost":
    case "card.stolen":
      await updateCardStatus(event.data.yativo_card_id, event.data.status);
      break;
  }

  // 3. Mark processed
  await db.processedEvents.create({ data: { id: event.id, processedAt: new Date() } });
}

Testing

Use the sandbox environment to test your webhook handler without real funds:

Sandbox base URL: https://crypto-sandbox.yativo.com/api/v1/
Register webhooks the same way as production — use the same endpoint POST /v1/webhook/create-webhook
Expose your local server using ngrok or Hookdeck during development

# Register a sandbox webhook pointing at your local ngrok tunnel
curl -X POST 'https://crypto-sandbox.yativo.com/api/v1/webhook/create-webhook' \
  -H 'Authorization: Bearer YOUR_SANDBOX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://abc123.ngrok-free.app/webhooks/yativo",
    "events": ["*"],
    "description": "Local dev webhook"
  }'

​How It Works

​Step 1 — Build Your Webhook Endpoint

​Step 2 — Register Your Webhook

​Step 3 — Verify Signatures

​The Event Lifecycle

​Master wallet deposit → settled

​Fund customer card

​Card transaction lifecycle

​Card status changes

​Event Reference

​Envelope

​master_wallet.deposit

​master_wallet.swap

​master_wallet.customer_funded

​customer.funded

​customer.funding.failed

​wallet.deposit.confirmed

​customer.balance.updated

​card.created

​card.activated

​card.frozen / card.unfrozen

​card.lost / card.stolen / card.voided / card.cancelled / card.deactivated

​Transaction event field reference

​transaction.authorized

​transaction.settled

​transaction.declined

​transaction.reversed

​transaction.refund.created

​Managing Webhooks

​List all subscriptions

​Get one subscription

​Update URL, events, or enabled state

​Rotate signing secret

​Delete a subscription

​Delivery history

​Retry a failed delivery

​Retry Policy

​Best Practices

​Idempotent Handler Pattern

​Testing

​Related

How It Works

Step 1 — Build Your Webhook Endpoint

Step 2 — Register Your Webhook

Step 3 — Verify Signatures

The Event Lifecycle

Master wallet deposit → settled

Fund customer card

Card transaction lifecycle

Card status changes

Event Reference

Envelope

`master_wallet.deposit`

`master_wallet.swap`

`master_wallet.customer_funded`

`customer.funded`

`customer.funding.failed`

`wallet.deposit.confirmed`

`customer.balance.updated`

`card.created`

`card.activated`

`card.frozen` / `card.unfrozen`

`card.lost` / `card.stolen` / `card.voided` / `card.cancelled` / `card.deactivated`

Transaction event field reference

`transaction.authorized`

`transaction.settled`

`transaction.declined`

`transaction.reversed`

`transaction.refund.created`

Managing Webhooks

List all subscriptions

Get one subscription

Update URL, events, or enabled state

Rotate signing secret

Delete a subscription

Delivery history

Retry a failed delivery

Retry Policy

Best Practices

Idempotent Handler Pattern

Testing

Related