Webhooks

FinVeil fires a signed webhook every time something meaningful happens on your account — a payment settles, a disbursement lands, a receipt mints. Subscribe to what you care about, verify the signature, and react in real time.

payment.succeeded

A collection succeeded. Final amount + provider are confirmed.

payment.failed

A collection attempt failed. Includes the provider-specific failure reason.

payment.refunded

A refund settled back to the original payment method.

disbursement.settled

A disbursement landed in the recipient bank account.

disbursement.failed

A disbursement was rejected (invalid account, bank timeout, etc.).

receipt.minted

A cryptographic receipt was anchored to the public ledger and is ready to verify.

reconciliation.discrepancy_found

A reconciliation run detected a mismatch between provider and bank settlements.

conditional_payout.released

A held conditional payout met its release condition and funds were sent.

payment_link.paid

A payment link was paid. Includes link id, payment id, and reference.

Example payload

All events are POSTed as JSON with an X-FinVeil-Signature header. Verify the HMAC before trusting the payload.

payment.succeeded.httphttp

POST /your-webhook-endpoint
Content-Type: application/json
X-FinVeil-Signature: sha256=<hmac>

{
  "event":     "payment.succeeded",
  "timestamp": "2026-04-18T08:41:22.531Z",
  "data": {
    "id":            "pay_01HRWXC2YQ8K...",
    "amount":        125000,
    "currency":      "ZAR",
    "reference":     "ORDER-4821",
    "provider_used": "paystack",
    "receipt_id":    "rct_0f3a9b2c7e..."
  }
}