Skip to content
HitchPay API Docs

Webhooks

Transfer Status Update

POST {your-webhook-url}

HitchPay sends this payload when a global transfer succeeds or fails.

Headers

Header Description
x-hitchpay-signature HMAC SHA256 signature — verify before processing

Payload — Transfer Succeeded

{
  "event": "crossborder.transfer.success",
  "data": {
    "reference": "HTCB13BE4DAC468B",
    "external_reference": "REF_BANK_001",
    "status": "successful",
    "amount_sent": 100,
    "source_currency": "USD",
    "estimated_amount_received": 12873.28,
    "destination_currency": "KES",
    "beneficiary": {
      "account_name": "Jane Doe",
      "country_code": "KE",
      "account_type": "bank"
    },
    "failure_reason": null
  },
  "sent_at": "2026-03-16T01:00:00.000Z"
}

Payload — Transfer Failed

{
  "event": "crossborder.transfer.failed",
  "data": {
    "reference": "HTCB13BE4DAC468B",
    "external_reference": "REF_BANK_001",
    "status": "failed",
    "amount_sent": 100,
    "source_currency": "USD",
    "destination_currency": "KES",
    "beneficiary": {
      "account_name": "Jane Doe",
      "country_code": "KE",
      "account_type": "bank"
    },
    "failure_reason": "Invalid account number"
  },
  "sent_at": "2026-03-16T01:05:00.000Z"
}

Expected Response

{ "status": "ok" }

See Webhook Overview for signature verification and deduplication guidance.

Questions? Email [email protected]. Also on GitBook.