rafiqPay
Developers
Webhooks

Webhook Event Catalogue

Comprehensive catalogue of all webhook event types dispatched by rafiqPay. Subscribe to specific event types in the Developer Dashboard or listen to all events with a wildcard.

Event Naming Convention

Events are formatted as resource.action or resource.subresource.action. All event payloads share the same envelope structure with an id, type, createdAt, mode, and nested data.object.

Checkout Events (3)

checkout.session.completedIn plan 035
Source: Plan 035

Sent when a customer completes payment on a Hosted Checkout session.

checkout.session.expiredIn plan 035
Source: Plan 035

Sent when an open Checkout Session passes its expiry timestamp without payment.

checkout.session.late_paymentIn plan 035
Source: Plan 035

Sent when a customer paid after the checkout closed. The money is credited; you decide whether to fulfil the order or refund.

Charges Events (4)

charge.succeededIn plan 035
Source: Plan 035

Sent whenever a payment succeeds: checkout by card or bank transfer, a saved-card charge, a mandate debit, a transfer into a customer bank account, or an accepted held transfer.

charge.pendingProposed
Source: Proposed

Sent when a payment is started and waiting for the provider to confirm it.

charge.failedProposed
Source: DASHBOARD_SPEC (proposed)

Sent when a card, wallet, or USSD payment attempt fails.

charge.refundedIn plan 035
Source: Plan 035

Sent when a charge is refunded in full or in part.

Refunds Events (2)

refund.succeededIn plan 035
Source: Plan 035

Sent when a refund has been settled back to the customer.

refund.failedIn plan 035
Source: Plan 035

Sent when the payment provider does not give the money back. The amount returns to your available balance.

Held transfers Events (4)

transfer.heldIn plan 035
Source: Plan 035

Sent when a bank transfer to a checkout’s one-time account was the wrong amount, or arrived after the account closed, and is held for you to accept or return. The checkout is not paid.

transfer.held example payload
{
  "id": "evt_01J9KANZU",
  "object": "event",
  "type": "transfer.held",
  "createdAt": "2026-11-07T10:42:05.000Z",
  "mode": "live",
  "data": {
    "object": {
      "id": "htr_01J9KANZU7",
      "object": "held_transfer",
      "status": "held",
      "reason": "mismatch",
      "currency": "NGN",
      "expectedAmount": "35000.00",
      "receivedAmount": "30000.00",
      "senderName": "AMINA BELLO",
      "chargeId": "pay_01J9KANZU881",
      "checkoutSessionId": "cs_live_kanzu_99182736",
      "acceptedChargeId": null,
      "returnPayoutId": null,
      "note": null,
      "createdAt": "2026-11-07T10:42:00.000Z",
      "decidedAt": null
    }
  }
}
transfer.acceptedIn plan 035
Source: Plan 035

Sent when a held transfer is accepted. It is credited as a new charge (acceptedChargeId), with the usual fee, and charge.succeeded is sent too.

transfer.accepted example payload
{
  "id": "evt_01J9KANZU",
  "object": "event",
  "type": "transfer.accepted",
  "createdAt": "2026-11-07T10:42:05.000Z",
  "mode": "live",
  "data": {
    "object": {
      "id": "htr_01J9KANZU7",
      "object": "held_transfer",
      "status": "accepted",
      "reason": "mismatch",
      "currency": "NGN",
      "expectedAmount": "35000.00",
      "receivedAmount": "30000.00",
      "senderName": "AMINA BELLO",
      "chargeId": "pay_01J9KANZU881",
      "checkoutSessionId": "cs_live_kanzu_99182736",
      "acceptedChargeId": "pay_01J9KANZU902",
      "returnPayoutId": null,
      "note": null,
      "createdAt": "2026-11-07T10:42:00.000Z",
      "decidedAt": "2026-11-07T11:05:00.000Z"
    }
  }
}
transfer.returnedIn plan 035
Source: Plan 035

Sent when the payout that returns a held transfer to the customer has been paid.

transfer.returned example payload
{
  "id": "evt_01J9KANZU",
  "object": "event",
  "type": "transfer.returned",
  "createdAt": "2026-11-07T10:42:05.000Z",
  "mode": "live",
  "data": {
    "object": {
      "id": "htr_01J9KANZU7",
      "object": "held_transfer",
      "status": "returned",
      "reason": "mismatch",
      "currency": "NGN",
      "expectedAmount": "35000.00",
      "receivedAmount": "30000.00",
      "senderName": "AMINA BELLO",
      "chargeId": "pay_01J9KANZU881",
      "checkoutSessionId": "cs_live_kanzu_99182736",
      "acceptedChargeId": null,
      "returnPayoutId": "trf_01J9KANZU",
      "note": null,
      "createdAt": "2026-11-07T10:42:00.000Z",
      "decidedAt": "2026-11-07T11:05:00.000Z"
    }
  }
}
transfer.refunded_by_providerIn plan 035
Source: Plan 035

Sent when a transfer that did not match was sent straight back to the sender by the bank. Nothing is held and there is nothing to do.

transfer.refunded_by_provider example payload
{
  "id": "evt_01J9KANZU",
  "object": "event",
  "type": "transfer.refunded_by_provider",
  "createdAt": "2026-11-07T10:42:05.000Z",
  "mode": "live",
  "data": {
    "object": {
      "id": "htr_01J9KANZU7",
      "object": "held_transfer",
      "status": "refunded_by_provider",
      "reason": "mismatch",
      "currency": "NGN",
      "expectedAmount": "35000.00",
      "receivedAmount": "30000.00",
      "senderName": "AMINA BELLO",
      "chargeId": "pay_01J9KANZU881",
      "checkoutSessionId": "cs_live_kanzu_99182736",
      "acceptedChargeId": null,
      "returnPayoutId": null,
      "note": "The bank returned the money to the sender.",
      "createdAt": "2026-11-07T10:42:00.000Z",
      "decidedAt": null
    }
  }
}

Saved cards Events (2)

payment_method.savedIn plan 035
Source: Plan 035

Sent when a customer agrees at checkout to save their card with your business. The card number and token are never included.

payment_method.saved example payload
{
  "id": "evt_01J9KANZU",
  "object": "event",
  "type": "payment_method.saved",
  "createdAt": "2026-11-07T10:42:05.000Z",
  "mode": "live",
  "data": {
    "object": {
      "id": "pm_01J9KANZU3",
      "object": "payment_method",
      "type": "card",
      "status": "active",
      "brand": "Visa",
      "last4": "4081",
      "expiry": "09/28",
      "customerEmail": "amina@kanzu.ng",
      "customerId": "cus_amina_01",
      "consentedAt": "2026-11-07T10:15:00.000Z",
      "createdAt": "2026-11-07T10:15:04.000Z"
    }
  }
}
payment_method.removedIn plan 035
Source: Plan 035

Sent when a saved card is removed. It can never be charged again.

payment_method.removed example payload
{
  "id": "evt_01J9KANZU",
  "object": "event",
  "type": "payment_method.removed",
  "createdAt": "2026-11-07T10:42:05.000Z",
  "mode": "live",
  "data": {
    "object": {
      "id": "pm_01J9KANZU3",
      "object": "payment_method",
      "type": "card",
      "status": "removed",
      "brand": "Visa",
      "last4": "4081",
      "expiry": "09/28",
      "customerEmail": "amina@kanzu.ng",
      "customerId": "cus_amina_01",
      "consentedAt": "2026-11-07T10:15:00.000Z",
      "createdAt": "2026-11-07T10:15:04.000Z"
    }
  }
}

Customers Events (2)

customer.createdProposed
Source: Proposed

Sent when a new customer profile is created.

customer.updatedProposed
Source: Proposed

Sent when a customer profile or saved checkout preference is updated.

Invoices Events (6)

invoice.createdIn plan 035
Source: Plan 035

Sent when an invoice is made, by you or by a subscription period.

invoice.sentProposed
Source: DASHBOARD_SPEC (proposed)

Sent when an invoice is finalized and dispatched to a customer.

invoice.part_paidIn plan 035
Source: Plan 035

Sent when a partial payment is recorded against an invoice.

invoice.paidIn plan 035
Source: Plan 035

Sent when an invoice balance reaches ₦0.00.

invoice.overdueIn plan 035
Source: Plan 035

Sent when an invoice passes its due date with an unpaid balance (zero late fees applied).

invoice.voidedIn plan 035
Source: Plan 035

Sent when an invoice is voided.

Subscriptions Events (7)

subscription.createdIn plan 035
Source: Plan 035

Sent when a customer subscription starts.

subscription.renewedIn plan 035
Source: Plan 035

Sent when a new period of the subscription is billed.

subscription.trial_endingProposed
Source: Proposed

Sent 3 days before a free trial ends.

subscription.past_dueIn plan 035
Source: Plan 035

Sent when an invoice of the subscription passes its due date unpaid.

subscription.pausedIn plan 035
Source: Plan 035

Sent when a subscription is paused.

subscription.resumedIn plan 035
Source: Plan 035

Sent when a paused subscription is resumed.

subscription.canceledIn plan 035
Source: Plan 035

Sent when a subscription is canceled.

Usage Events (1)

usage.threshold_reachedProposed
Source: DASHBOARD_SPEC (proposed)

Sent when a customer crosses a configured metered usage threshold.

Wallets and mandates Events (5)

mandate.activeIn plan 035
Source: Plan 035

Sent when the customer approves a mandate with the code from their bank. Debit it once readyToDebit is true.

mandate.active example payload
{
  "id": "evt_01J9KANZU",
  "object": "event",
  "type": "mandate.active",
  "createdAt": "2026-11-07T10:42:05.000Z",
  "mode": "live",
  "data": {
    "object": {
      "id": "mnd_01J9KANZU",
      "object": "mandate",
      "mode": "live",
      "status": "active",
      "readyToDebit": false,
      "customerId": "cus_amina_01",
      "customerName": "Amina Bello",
      "customerEmail": "amina@kanzu.ng",
      "description": "Kanzu Academy monthly fees",
      "currency": "NGN",
      "maxAmount": "300000.00",
      "amountDebited": "0.00",
      "amountLeft": "300000.00",
      "startDate": "2026-11-10",
      "endDate": "2027-11-09",
      "bankName": "GTBank",
      "accountLast4": "6789",
      "approvalUrl": null,
      "lastDebitedAt": null,
      "createdAt": "2026-11-07T09:30:00.000Z"
    }
  }
}
mandate.cancelledIn plan 035
Source: Plan 035

Sent when a mandate is cancelled. It can never be debited again.

mandate.cancelled example payload
{
  "id": "evt_01J9KANZU",
  "object": "event",
  "type": "mandate.cancelled",
  "createdAt": "2026-11-07T10:42:05.000Z",
  "mode": "live",
  "data": {
    "object": {
      "id": "mnd_01J9KANZU",
      "object": "mandate",
      "mode": "live",
      "status": "cancelled",
      "readyToDebit": false,
      "customerId": "cus_amina_01",
      "customerName": "Amina Bello",
      "customerEmail": "amina@kanzu.ng",
      "description": "Kanzu Academy monthly fees",
      "currency": "NGN",
      "maxAmount": "300000.00",
      "amountDebited": "50000.00",
      "amountLeft": "250000.00",
      "startDate": "2026-11-10",
      "endDate": "2027-11-09",
      "bankName": "GTBank",
      "accountLast4": "6789",
      "approvalUrl": null,
      "lastDebitedAt": "2026-11-10T08:00:12.000Z",
      "createdAt": "2026-11-07T09:30:00.000Z"
    }
  }
}
embedded_wallet.creditedProposed
Source: Proposed

Sent when an embedded wallet receives an inflow.

embedded_wallet.debitedProposed
Source: Proposed

Sent when an embedded wallet is debited for a payment, mandate, or transfer.

virtual_account.expiredProposed
Source: Proposed

Sent when a temporary checkout virtual account expires.

Transfers Events (10)

payout.paidIn plan 035
Source: Plan 035

Sent when the payout provider says a payout was paid. Carries your merchantReference when you gave one.

payout.failedIn plan 035
Source: Plan 035

Sent when a payout failed and the money returned to your available balance. Carries your merchantReference when you gave one.

transfer.awaiting_approvalProposed
Source: Proposed

Sent when a transfer requires two-person checker approval in the Dashboard.

transfer.pending_confirmationProposed
Source: Proposed

Sent when a payout has been sent and the provider has not yet confirmed it.

transfer.succeededProposed
Source: DASHBOARD_SPEC (proposed)

Sent when the payout provider confirms the money reached the receiving bank.

transfer.failedProposed
Source: DASHBOARD_SPEC (proposed)

Sent when a transfer fails terminally and funds are reversed to available balance.

transfer_batch.approvedProposed
Source: Proposed

Sent when a transfer batch passes checker approval.

transfer_batch.declinedProposed
Source: Proposed

Sent when a transfer batch is declined by an approver.

payout.heldProposed
Source: ACCESS_RULES (proposed)

Sent when a solo business payout enters a cool-off hold window.

payout.releasedProposed
Source: ACCESS_RULES (proposed)

Sent when a held solo business payout finishes its wait window and is dispatched.

Security and ownership Events (8)

security_policy.change_scheduledProposed
Source: ACCESS_RULES (proposed)

Sent when an Owner schedules a looser security policy change (24-hour hold).

security_policy.updatedProposed
Source: ACCESS_RULES (proposed)

Sent when a security policy change or rafiqPay clamp/override takes effect.

ownership_transfer.requestedProposed
Source: ACCESS_RULES (proposed)

Sent when the Owner initiates an ownership transfer to a team member.

ownership_transfer.acceptedProposed
Source: ACCESS_RULES (proposed)

Sent when the recipient accepts the ownership transfer and the hold starts.

ownership_transfer.completedProposed
Source: ACCESS_RULES (proposed)

Sent when the ownership transfer hold finishes and roles swap.

ownership_transfer.cancelledProposed
Source: ACCESS_RULES (proposed)

Sent when an ownership transfer is cancelled.

ownership_recovery.requestedProposed
Source: ACCESS_RULES (proposed)

Sent when a verified director or shareholder submits an Owner recovery request.

ownership_recovery.decidedProposed
Source: ACCESS_RULES (proposed)

Sent when rafiqPay Risk & Compliance approves or declines an Owner recovery case.

Connect Events (3)

connected_account.updatedProposed
Source: Proposed

Sent when a connected sub-merchant KYB status or profile changes.

connected_account.requirements_dueProposed
Source: Proposed

Sent when additional verification documents are required for a connected account.

connected_account.payouts_pausedProposed
Source: Proposed

Sent when settlements to a connected account are paused.

Cards Events (8)

cardholder.createdProposed
Source: Proposed

Sent when a cardholder profile is created.

card.createdProposed
Source: Proposed

Sent when a virtual or physical card is issued.

card.updatedProposed
Source: Proposed

Sent when a card status or spend limit changes.

card.shippedProposed
Source: Proposed

Sent when a physical card is handed to the courier with tracking details.

card_authorization.requestProposed
Source: Proposed

Synchronous JIT webhook (2,000ms deadline) asking your server to approve or decline a card swipe.

card_authorization.createdProposed
Source: Proposed

Asynchronous notification emitted after a card authorization is approved or declined.

card_authorization.updatedProposed
Source: Proposed

Sent when an authorization hold is reversed or adjusted.

card_transaction.createdProposed
Source: Proposed

Sent when a card authorization settles and posts to the wallet ledger.

Webhooks Events (1)

webhook.testIn plan 035
Source: Plan 035

A test event, sent when you press Send a test in the dashboard (Developers, Webhooks).