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.
chargeback.initiated	A dispute or MoMo reversal is opened on a completed payment.

---

Example Payloads

Payment request

{
  "event_type": "payment_request.updated",
  "data": {
    "id": "VHlwZXM6OkNhc2hyYW1wOjpBUEk6Ok1lcmNoYW50UGF5bWVudFJlcXVlc3QtOGI0OTdmZTYtOTljYS00MDQwLTkzNWQtMTY2OGJhNGUyNzU2",
    "reference": "test_ref_022",
    "status": "completed",
    "customer": {
      "id": "TWVyY2hhbnRDdXN0b21lci0xZmNiYTgzNi01MDNmLTQyMjYtYjgzYy02NzIzNjMxNDM0YWI=",
      "email": "[email protected]",
      "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

Onchain Deposit

Chargeback

---

Responding to Webhooks

Return 200 OK immediately. Any non-2xx or timeout is treated as a delivery failure, and the event will be retried.

1. Validate – Compare the X-CASHRAMP-TOKEN header to the token in your dashboard.

2. Confirm: Confirm the status of the payment request (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.