> For the complete documentation index, see [llms.txt](https://docs.cashramp.co/cashramp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cashramp.co/cashramp/introduction/webhooks.md).

# Webhooks

Webhooks let Cashramp push real-time updates to your server whenever a transaction changes state—success, cancellation, chargeback, and more.

## Event Payload

Every webhook is an HTTPS **POST** with a JSON body shaped like:

| Field        | Type     | Description                                          |
| ------------ | -------- | ---------------------------------------------------- |
| `event_type` | `string` | Machine-readable name of the event (see list below). |
| `data`       | `object` | Event-specific payload.                              |

### Common `event_type` Values

| Event                               | Trigger                                                                                   |
| ----------------------------------- | ----------------------------------------------------------------------------------------- |
| `payment_request.updated`           | Payment request moves through `created → picked_up → completed / canceled`.               |
| `onchain_tx.updated`                | On-chain withdrawal status changes.                                                       |
| `fiat_payout.updated`               | Bank withdrawal moves through `processing → completed / failed`.                          |
| `chargeback.initiated`              | A dispute or MoMo reversal is opened on a completed payment.                              |
| `virtual_card.created`              | A virtual card has been successfully issued.                                              |
| `virtual_card.creation_failed`      | Virtual card issuance failed.                                                             |
| `virtual_card.funded`               | A virtual card top-up completed.                                                          |
| `virtual_card.funding_failed`       | A virtual card top-up failed and was refunded to your balance.                            |
| `virtual_card.frozen`               | A virtual card was frozen.                                                                |
| `virtual_card.unfrozen`             | A virtual card was unfrozen.                                                              |
| `virtual_card.withdrawal_completed` | A withdrawal from a virtual card back to your balance completed.                          |
| `virtual_card.deleted`              | A virtual card was deleted and any remaining balance refunded.                            |
| `virtual_card.transaction`          | A card authorization occurred (approved, declined, reversal, or cross-border settlement). |

***

## Example Payloads

**Payment request**

```json
{
  "event_type": "payment_request.updated",
  "data": {
    "id": "VHlwZXM6OkNhc2hyYW1wOjpBUEk6Ok1lcmNoYW50UGF5bWVudFJlcXVlc3QtOGI0OTdmZTYtOTljYS00MDQwLTkzNWQtMTY2OGJhNGUyNzU2",
    "reference": "test_ref_022",
    "status": "completed",
    "customer": {
      "id": "TWVyY2hhbnRDdXN0b21lci0xZmNiYTgzNi01MDNmLTQyMjYtYjgzYy02NzIzNjMxNDM0YWI=",
      "email": "engineering@useaccrue.com",
      "country": "GH",
      "currency": "GHS"
    },
    "p2p_payment": {
      "id": "UDJQUGF5bWVudC0xOGRmNmJiNC1hNmQ2LTQyMWUtYjQ0MS04YmFiMmE2YzQ5Yjc=",
      "exchange_rate": "7.95",
      "amount": "159.0",
      "amount_usd": "20.0",
      "fee": "0.3"
    },
    "created_at": "2025-05-02T12:43:40.914Z",
    "payment_link": "https://useaccrue.com/hosted/pay/..."
  }
}
```

**Onchain Withdrawal**

```json
{
  "event_type": "onchain_tx.updated",
  "data": {
    "id": "VHlwZXM6Ok9uY2hhaW5UeC1hYzNmODk2Mi1jNzRkLTRmNWMtYTQ5ZC1kYmIzMWM1MDc5Mzc=",
    "address": "TPy5hAiyWeKoUHAnAUSoK8YuqbTx75X8xX",
    "status": "completed",
    "quantity": 1000,
    "fee": 0,
    "symbol": "USDT",
    "network": "TRX",
    "txhash": "8efb22782c0a42047266aa6c3df1cfc60cd3ead4ba31075e5d6fccf833402e24"
  }
}
```

**Onchain Deposit**

```json
{
  "event_type": "onchain_payment.received",
  "data": {
    "id": "VHlwZXM6Ok9uY2hhaW5UeC1hYzNmODk2Mi1jNzRkLTRmNWMtYTQ5ZC1kYmIzMWM1MDc5Mzc=",
    "sender_address": "0xc2DC2eF356EBE18cCdA1D5B971eaBE7261027de1",
    "recipient_address": "0x9c7DCB324c602dA446987710Df00019ac6f9af2b",
    "status": "completed",
    "amount_usd": 36.68,
    "txhash": "0x52ca34f1569ddf9bcf5fc26e95de82e5420f940432ee9ab9780fe68ac60fae98"
  }
}
```

**Chargeback**

```json
{
  "event_type": "chargeback.initiated",
  "data": {
    "id": "TWVyY2hhbnRDaGFyZ2ViYWNrLWQ2MGVjMjI3LThhNTYtNDMxNS1hNWQ4LTk3N2JhNmFhNmE3Mw==",
    "status": "pending",
    "reason": "A MoMo reversal was initiated by your customer",
    "payment_request": {
      "id": "VHlwZXM6OkNhc2hyYW1wOjpBUEk6Ok1lcmNoYW50UGF5bWVudFJlcXVlc3QtYmMxYTMzMzktNTM5YS00Y2ZkLWE3ZmEtMTM1MzllZGVhNWQw",
      "reference": "c9b1082d49185da9",
      "amount": 100,
      "currency": "usd"
    }
  }
}
```

**Virtual card lifecycle**

Delivered for `virtual_card.created`, `virtual_card.creation_failed`, `virtual_card.funded`, `virtual_card.funding_failed`, `virtual_card.frozen`, `virtual_card.unfrozen`, `virtual_card.withdrawal_completed`, and `virtual_card.deleted`. Card secrets (PAN/CVV) are never included. Monetary fields (`balance`, `available_balance`, and `transaction.amount`) are delivered as decimal **strings**.

```json
{
  "event_type": "virtual_card.created",
  "data": {
    "id": "VmlydHVhbENhcmQtOGI0OTdmZTYtOTljYS00MDQwLTkzNWQtMTY2OGJhNGUyNzU2",
    "customer_id": "TWVyY2hhbnRDdXN0b21lci0xZmNiYTgzNi01MDNmLTQyMjYtYjgzYy02NzIzNjMxNDM0YWI=",
    "label": "Groceries",
    "cardholder_name": "Jane Doe",
    "brand": "visa",
    "status": "active",
    "balance": "100.0",
    "available_balance": "100.0"
  }
}
```

`virtual_card.deleted` adds a `reason`: `failed_debit_attempts` when the card issuer terminated the card after repeated failed debits, otherwise `terminated`.

```json
{
  "event_type": "virtual_card.deleted",
  "data": {
    "id": "VmlydHVhbENhcmQtOGI0OTdmZTYtOTljYS00MDQwLTkzNWQtMTY2OGJhNGUyNzU2",
    "customer_id": "TWVyY2hhbnRDdXN0b21lci0xZmNiYTgzNi01MDNmLTQyMjYtYjgzYy02NzIzNjMxNDM0YWI=",
    "label": "Groceries",
    "cardholder_name": "Jane Doe",
    "brand": "visa",
    "status": "freezing",
    "balance": "0.0",
    "available_balance": "0.0",
    "reason": "failed_debit_attempts"
  }
}
```

`virtual_card.funding_failed` adds a `funding` object. `reference` is the one you passed to `fundVirtualCard`, and `reason` is `provider_failed` (the card issuer rejected the top-up) or `not_processed` (the card issuer never received it). The amount and fee are refunded to your balance.

```json
{
  "event_type": "virtual_card.funding_failed",
  "data": {
    "id": "VmlydHVhbENhcmQtOGI0OTdmZTYtOTljYS00MDQwLTkzNWQtMTY2OGJhNGUyNzU2",
    "customer_id": "TWVyY2hhbnRDdXN0b21lci0xZmNiYTgzNi01MDNmLTQyMjYtYjgzYy02NzIzNjMxNDM0YWI=",
    "label": "Groceries",
    "cardholder_name": "Jane Doe",
    "brand": "visa",
    "status": "active",
    "balance": "100.0",
    "available_balance": "100.0",
    "funding": {
      "amount": "50.0",
      "fee": "1.5",
      "reference": "topup-1",
      "reason": "provider_failed"
    }
  }
}
```

**Virtual card transaction**

Delivered as `virtual_card.transaction` for approvals, declines, reversals, and cross-border settlements. `transaction.type` is one of `spend`, `reversal`, `funding`, or `withdrawal`, and `transaction.payment_type` is `debit` or `credit`. `transaction.balance` is the card balance after the transaction; `original_amount` / `original_currency` are what the merchant billed before conversion to USD. Merchant fields are `null` for funding and withdrawal transactions. Declined authorizations carry a different shape (see below).

```json
{
  "event_type": "virtual_card.transaction",
  "data": {
    "id": "VmlydHVhbENhcmQtOGI0OTdmZTYtOTljYS00MDQwLTkzNWQtMTY2OGJhNGUyNzU2",
    "customer_id": "TWVyY2hhbnRDdXN0b21lci0xZmNiYTgzNi01MDNmLTQyMjYtYjgzYy02NzIzNjMxNDM0YWI=",
    "label": "Groceries",
    "cardholder_name": "Jane Doe",
    "brand": "visa",
    "status": "active",
    "balance": "76.5",
    "available_balance": "76.5",
    "transaction": {
      "id": "VmlydHVhbENhcmRUcmFuc2FjdGlvbi0xOGRmNmJiNC1hNmQ2LTQyMWUtYjQ0MS04YmFiMmE2YzQ5Yjc=",
      "amount": "23.5",
      "fee": "0.0",
      "balance": "76.5",
      "payment_type": "debit",
      "type": "spend",
      "description": "NETFLIX.COM",
      "reference": "auth_ref_8821",
      "merchant_name": "NETFLIX.COM",
      "merchant_category_code": "4899",
      "merchant_country": "USA",
      "original_amount": "23.5",
      "original_currency": "USD",
      "created_at": "2026-07-20T12:43:40.914Z"
    }
  }
}
```

A **declined** authorization is also delivered as `virtual_card.transaction`, but its `transaction` object has a distinct shape: `status` is `"declined"`, `amount` is the attempted amount in USD, `original_amount` / `original_currency` are what the merchant billed, and `decline_reason` says why. It has no `id` or `payment_type` and never appears in `transactionHistory`. Each decline is delivered once, keyed by `reference`. No balance is moved.

```json
{
  "event_type": "virtual_card.transaction",
  "data": {
    "id": "VmlydHVhbENhcmQtOGI0OTdmZTYtOTljYS00MDQwLTkzNWQtMTY2OGJhNGUyNzU2",
    "customer_id": "TWVyY2hhbnRDdXN0b21lci0xZmNiYTgzNi01MDNmLTQyMjYtYjgzYy02NzIzNjMxNDM0YWI=",
    "label": "Groceries",
    "cardholder_name": "Jane Doe",
    "brand": "visa",
    "status": "active",
    "balance": "76.5",
    "available_balance": "76.5",
    "transaction": {
      "status": "declined",
      "type": "spend",
      "amount": "23.5",
      "currency": "USD",
      "reference": "auth_ref_8822",
      "merchant_name": "NETFLIX.COM",
      "merchant_category_code": "4899",
      "merchant_country": "USA",
      "original_amount": "23.5",
      "original_currency": "USD",
      "decline_reason": "No sufficient funds",
      "declined_at": "2026-07-20T12:43:40.914Z"
    }
  }
}
```

***

## Responding to Webhooks

{% hint style="danger" %}
Return **`200 OK` immediately**. Any non-2xx or timeout is treated as a delivery failure, and the event will be retried.
{% endhint %}

1. **Validate** – Compare the `X-CASHRAMP-TOKEN` header to the token in your dashboard.
2. **Confirm**: [Confirm the status of the payment request](https://docs.cashramp.co/cashramp/cashramp-api/queries.md#transaction-status) (`completed`, `canceled`, etc.)
3. **Process** – Perform your business logic (credit user, update order, etc.).

***

## Best Practices

* **Verify the token** before trusting the payload—prevents spoofing.
* **Log the raw body** for audits and easier debugging.
* **Keep handlers fast**—offload heavy work to background jobs.
* **Rotate tokens** periodically or immediately on suspicion of compromise.
