Payments Webhooks

Overview

This document describes all outgoing webhook event payloads sent for payment/payout transactions, covering all 3 payment providers. Webhooks are HTTP POST requests with a Content-Type: application/json header delivered to your configured endpoint URL.

Note: All 3 providers follow the same functional lifecycle (customer → beneficiary → order/payout), but each provider may use different field names, casing, or nesting in their raw payloads. This doc defines the normalized schema your endpoint should expect after mapping. Once real provider payloads are shared, this doc will be updated with provider-specific raw formats + mapping notes.

Payload Conventions

Convention	Detail
Format	JSON
HTTP Method	`POST`
Content-Type	`application/json`
Null fields	Included as `null` (not omitted)
Timestamps	ISO 8601 — `YYYY-MM-DDTHH:mm:ssZ`
Amounts	Decimal string or number in the currency's minor/major unit as configured

Event Categories

Category	Events
Customer	`customer.approved`, `customer.rejected`, `customer.pending`
Beneficiary	`beneficiary.approved`, `beneficiary.rejected`, `beneficiary.pending`
Order / Payout	`order.created`, `order.cancelled`, `order.rejected`, `order.sent_to_beneficiary`

1. Customer Events

Applicable event types: customer.approved · customer.rejected · customer.pending

Fired when a customer's KYC/onboarding application status changes with a payment provider.

Payload

{
  "id": "evt_9f2a1c4e8b3d4f2a9c1e8b3d4f2a9c1e",
  "type": "customer.approved",
  "createdAt": "2026-04-02T14:26:37.872Z",
  "data": {
    "customer_id": "f51b8db9-0bbf-4a91-b5fe-bf9d7b16f070",
    "reference_id": "ref_customer_00123",
    "first_name": "tarun",
    "last_name": "kumar",
    "email": "tarunkumar@yopmail.com",
    "status": "approved",
    "reason": "KYC verification successful",
    "performed_at": "2026-04-02T14:26:37.872Z"
  }
}

Field Reference

Field	Type	Description
`id`	`string`	Unique identifier of this webhook event
`type`	`string`	Event type. One of `customer.approved`, `customer.rejected`, `customer.pending`
`created_at`	`string`	ISO 8601 timestamp when the event was generated
`customer_id`	`string`	Provider-side unique identifier of the customer
`reference_id`	`string`	Your internal/merchant reference ID for this customer, if sent during creation
`first_name`	`string`	Customer's first name
`last_name`	`string`	Customer's last name
`email`	`string`	Customer's email address
`status`	`string`	Current status (`approved`, `rejected`, `pending`)
`reason`	`string`	Human-readable reason accompanying the status
`performed_at`	`string`	ISO 8601 timestamp when the status change occurred

2. Beneficiary Events

Applicable event types: beneficiary.approved · beneficiary.rejected · beneficiary.pending

Fired when a beneficiary (payout recipient) added under a customer is validated by the provider.

Payload

{
  "id": "evt_3c990d0027974a269d69ecbbc6252934",
  "type": "beneficiary.approved",
  "createdAt": "2026-04-01T12:14:27.827Z",
  "data": {
    "beneficiary_id": "b6aa7a4c-ac4f-43ca-9030-9c6936f7913c",
    "customer_id": "a850b57a-23c8-48f5-846c-a25c8869ffe8",
    "reference_id": "ref_bene_00456",
    "beneficiary_name": "John Doe",
    "account_number": "XXXXXXXX1234",
    "bank_code": "HDFC0001234",
    "country": "IN",
    "status": "approved",
    "reason": "Bank account verified",
    "performed_at": "2026-04-01T12:14:27.819Z"
  }
}

Field Reference

Field	Type	Description
`id`	`string`	Unique identifier of this webhook event
`type`	`string`	Event type. One of `beneficiary.approved`, `beneficiary.rejected`, `beneficiary.pending`
`created_at`	`string`	ISO 8601 timestamp when the event was generated
`beneficiary_id`	`string`	Provider-side unique identifier of the beneficiary
`customer_id`	`string`	Customer that owns this beneficiary
`reference_id`	`string`	Your internal/merchant reference ID for this beneficiary, if sent during creation
`beneficiary_name`	`string`	Name of the payout recipient
`account_number`	`string`	Masked bank account / wallet identifier
`bank_code`	`string`	Bank routing / IFSC / SWIFT code, as applicable
`country`	`string`	ISO 3166-1 alpha-2 country code of the beneficiary
`status`	`string`	Current status (`approved`, `rejected`, `pending`)
`reason`	`string`	Human-readable reason accompanying the status
`performed_at`	`string`	ISO 8601 timestamp when the status change occurred

3. Order Events

Applicable event types: order.created · order.cancelled · order.rejected · order.sent_to_beneficiary

Fired across the lifecycle of a payout order — from initial creation through to funds being sent to the beneficiary (or the order being cancelled/rejected along the way).

Payload

{
  "id": "evt_5377f5d53323457688ea939284e13406",
  "type": "order.sent_to_beneficiary",
  "createdAt": "2026-04-01T12:07:51.279Z",
  "data": {
    "order_id": "ord_7f3e9c2a1b4d4e5f8a9c1e8b3d4f2a9c",
    "reference_id": "ref_order_00789",
    "customer_id": "a850b57a-23c8-48f5-846c-a25c8869ffe8",
    "beneficiary_id": "b6aa7a4c-ac4f-43ca-9030-9c6936f7913c",
    "amount": "1500.00",
    "currency": "INR",
    "fee": "5.00",
    "fee_currency": "INR",
    "status": "sent_to_beneficiary",
    "reason": "Funds successfully credited to beneficiary account",
    "utr_number": "UTR20260401123456",
    "performed_at": "2026-04-01T12:07:51.265Z"
  }
}

Field Reference

Field	Type	Description
`id`	`string`	Unique identifier of this webhook event
`type`	`string`	Event type. One of `order.created`, `order.cancelled`, `order.rejected`, `order.sent_to_beneficiary`
`created_at`	`string`	ISO 8601 timestamp when the event was generated
`order_id`	`string`	Provider-side unique identifier of the payout order
`reference_id`	`string`	Your internal/merchant reference ID for this order, if sent during creation
`customer_id`	`string`	Customer that initiated this order
`beneficiary_id`	`string`	Beneficiary this order is being paid out to
`amount`	`string`	Order/payout amount
`currency`	`string`	ISO 4217 currency code of the order
`fee`	`string`	Provider/platform fee applied to this order
`fee_currency`	`string`	Currency of the fee
`status`	`string`	Current status (`created`, `cancelled`, `rejected`, `sent_to_beneficiary`)
`reason`	`string`	Human-readable reason accompanying the status
`utr_number`	`string`	Bank UTR / transaction reference number (present once funds are sent)
`performed_at`	`string`	ISO 8601 timestamp when the status change occurred

Status Values Quick Reference

Customer Status

Value	Description
`approved`	Customer KYC/onboarding approved
`rejected`	Customer KYC/onboarding rejected
`pending`	Customer application under review

Beneficiary Status

Value	Description
`approved`	Beneficiary account verified and usable
`rejected`	Beneficiary account verification failed
`pending`	Beneficiary verification in progress

Order Status

Value	Description
`created`	Order has been created and is queued for processing
`cancelled`	Order was cancelled before completion
`rejected`	Order was rejected by the provider or beneficiary bank
`sent_to_beneficiary`	Funds have been successfully sent to the beneficiary

Error Handling

Your endpoint should return an HTTP 2xx status code to acknowledge receipt. If a non-2xx response is returned or the request times out, the provider may retry delivery with exponential backoff.

Scenario	Recommendation
Duplicate events	Use `order_id`, `beneficiary_id`, or `customer_id` + `type` for idempotency
Unknown event type	Acknowledge (`200 OK`) and ignore gracefully
Processing failure	Return `500` to trigger retry

Open Items — Pending Your Confirmation

Actual names of the 3 providers (currently placeholder: provider_a, provider_b, provider_c)

Real raw payload samples from each provider (field names/casing/nesting likely differ — e.g. some may use camelCase with a data wrapper like your Card Action events, others flat snake_case like your Transaction events)

Whether reference_id (your internal ID) is actually returned by all 3 providers or only some

Whether utr_number / bank reference is common to all providers or provider-specific

Confirm if beneficiary and order fees are separate line items or combined per provider

Overview#

Payload Conventions#

Event Categories#

1. Customer Events#

Payload#

Field Reference#

2. Beneficiary Events#

Payload#

Field Reference#

3. Order Events#

Payload#

Field Reference#

Status Values Quick Reference#

Customer Status#

Beneficiary Status#

Order Status#

Error Handling#

Open Items — Pending Your Confirmation#

Overview

Payload Conventions

Event Categories

1. Customer Events

Payload

Field Reference

2. Beneficiary Events

Payload

Field Reference

3. Order Events

Payload

Field Reference

Status Values Quick Reference

Customer Status

Beneficiary Status

Order Status

Error Handling

Open Items — Pending Your Confirmation