For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
API GuideAPI ReferenceChangelog
API GuideAPI ReferenceChangelog
  • API Reference
  • Webhook Reference
      • POSTPayment Status Updated Event
LogoLogo
Webhook ReferencePayments

Payment Status Updated Event

Payload
1{
2  "event_id": "string",
3  "event_type": "PAYMENT STATUS",
4  "version": "v1.0.0",
5  "event_timestamp": "2025-01-01T00:00:00Z",
6  "data": {
7    "payment_id": "string",
8    "status": "AWAITING_FUNDS",
9    "customer_id": "string"
10  }
11}
Sent when the status of a payment changes. Subscribe to the `PAYMENT STATUS` event type to receive these updates at your designated endpoint. Implement idempotent processing and store each event keyed by `event_id` and `payment_id` to handle retries and out-of-order delivery. ## Status flows and reference <Accordion title="Status Flows & Transitions"> Payment status updates follow different flows depending on whether currency conversion (FX) is required: **Flow 1: Payments with FX Conversion (Different Currencies)** ```mermaid graph TD; AWAITING_FUNDS --> RECEIVED_FUNDS --> FX_COMPLETED --> PAYOUT_INITIATED --> PAYOUT_CREDITED --> PAYMENT_COMPLETED AWAITING_FUNDS --> CANCELLED RECEIVED_FUNDS --> REFUNDED PAYOUT_INITIATED --> BOUNCED_BACK BOUNCED_BACK --> REFUNDED PAYOUT_INITIATED --> CANCELLED ``` **Flow 2: Same Currency Payments (No FX Conversion)** ```mermaid graph TD; PROCESSING --> PAYOUT_INITIATED --> PAYOUT_CREDITED --> PAYMENT_COMPLETED PROCESSING --> CANCELLED PAYOUT_INITIATED --> BOUNCED_BACK BOUNCED_BACK --> REFUNDED ``` **Status Reference:** | Status | Description | Applies To | |--------|-------------|------------| | PROCESSING | Same-currency payment accepted, processing started | Same currency only | | AWAITING_FUNDS | Payment created, waiting for incoming funds | FX payments | | RECEIVED_FUNDS | Funds received and credited to customer's Redpin wallet | FX payments | | FX_COMPLETED | Currency conversion completed | FX payments only | | PAYOUT_INITIATED | Transfer to recipient initiated | All payments | | PAYOUT_CREDITED | Funds credited to recipient's account | All payments | | CANCELLED | Payment cancelled (reason in `reason_description`) | All payments | | BOUNCED_BACK | Recipient bank returned the funds (reason in `bounce_reason`) | All payments | | REFUNDED | Payment refunded to customer (details in `refund_amount`) | All payments | | PAYMENT_COMPLETED | All recipients paid; final status | All payments | <Warning>If you receive a status not listed here, log the event and contact the Partner Integrations Team. Your integration should be resilient to new statuses being added.</Warning> > All envelope fields (`event_id`, `event_type`, `version`, `event_timestamp`) are always present. Business fields (`payment_id`, `status`, `customer_id`, etc.) are inside the `data` object. **PAYOUT_CREDITED vs PAYMENT_COMPLETED:** For single-recipient payments, both events are delivered and are functionally equivalent. For multi-recipient payments, `PAYOUT_CREDITED` fires per recipient; `PAYMENT_COMPLETED` fires once when all recipients are credited. Treat `PAYMENT_COMPLETED` as the definitive settlement signal. </Accordion> <Accordion title="Field Availability Reference"> > **Payment types explained:** > - **Third Party Payment (Session-Based)**: Payments created via [Hosted payment sessions API](/api-reference/customers/hosted-experience/sessions/create-payment-session) > - **API Payment (Third Party)**: Payments created via [Payment API](/api-reference/customers/api-integration/payments/create-payment) with `is_third_party_payment: true` > - **API Payment (Non Third Party)**: Payments created via [Payment API](/api-reference/customers/api-integration/payments/create-payment) with `is_third_party_payment: false` | Field | Third Party Payment (Session-Based) | API Payment (Third Party) | API Payment (Non Third Party) | |-------|--------------------------------------|--------------------------|-------------------------------| | `data.session_id` | ✅ Always present | ❌ Not present | ❌ Not present | | `data.client_reference_id` | ✅ Present | ✅ Present | ⚠️ Present when provided | | `data.client_customer_ref` | ✅ Present | ✅ Present | ⚠️ Present when provided | | `data.payment_id` | ✅ Present | ✅ Present | ✅ Present | | `data.status` | ✅ Present | ✅ Present | ✅ Present | | `data.customer_id` | ✅ Present | ✅ Present | ✅ Present | See the example payloads below for the specific data object schema associated with each status value. </Accordion> <Accordion title="Glossary"> | Term | Definition | |------|-----------| | Envelope fields | Top-level event metadata: `event_id`, `event_type`, `version`, `event_timestamp` | | Business data | Fields inside `data` describing the payment and its current status | | Third party payment | Payment funded by someone other than the account holder (e.g. a buyer paying a property developer) | | Non third party payment | Payment funded by the account holder from their own bank account | </Accordion> ## Example payloads Each status below shows payloads for all three payment types. The envelope (`event_id`, `event_type`, `version`, `event_timestamp`) is identical across types; only the `data` fields differ. <Accordion title="AWAITING_FUNDS"> <Tabs> <Tab title="Third Party Payment (Session-Based)"> ```json { "event_id": "1", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "session_id": "123e4567-e89b-12d3-a456-426614174000", "payment_id": "123456", "status": "AWAITING_FUNDS", "customer_id": "0201001008132685", "client_customer_ref": "CUST_001", "client_reference_id": "PAY-REF-001" } } ``` </Tab> <Tab title="API Payment (Third Party)"> ```json { "event_id": "1", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "AWAITING_FUNDS", "customer_id": "0201001008132685", "client_customer_ref": "skyline_customer_001" } } ``` </Tab> <Tab title="API Payment (Non Third Party)"> ```json { "event_id": "1", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "AWAITING_FUNDS", "customer_id": "0201001008132685" } } ``` </Tab> </Tabs> </Accordion> <Accordion title="RECEIVED_FUNDS"> <Tabs> <Tab title="Third Party Payment (Session-Based)"> ```json { "event_id": "2", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "session_id": "123e4567-e89b-12d3-a456-426614174000", "payment_id": "123456", "status": "RECEIVED_FUNDS", "customer_id": "0201001008132685", "client_customer_ref": "CUST_001", "client_reference_id": "PAY-REF-001", "amount": { "currency": "GBP", "value": 1000 } } } ``` </Tab> <Tab title="API Payment (Third Party)"> ```json { "event_id": "2", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "RECEIVED_FUNDS", "customer_id": "0201001008132685", "client_customer_ref": "skyline_customer_001", "client_reference_id": "PAY-REF-001", "amount": { "currency": "GBP", "value": 1000 } } } ``` </Tab> <Tab title="API Payment (Non Third Party)"> ```json { "event_id": "2", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "RECEIVED_FUNDS", "customer_id": "0201001008132685", "amount": { "currency": "GBP", "value": 1000 } } } ``` </Tab> </Tabs> </Accordion> <Accordion title="FX_COMPLETED"> <Tabs> <Tab title="Third Party Payment (Session-Based)"> ```json { "event_id": "3", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "session_id": "123e4567-e89b-12d3-a456-426614174000", "payment_id": "123456", "status": "FX_COMPLETED", "customer_id": "0201001008132685", "client_customer_ref": "CUST_001", "client_reference_id": "PAY-REF-001", "sell_amount": { "currency": "GBP", "value": 1000 }, "buy_amount": { "currency": "AED", "value": 4982.70 }, "quote_rate": 4.9827 } } ``` </Tab> <Tab title="API Payment (Third Party)"> ```json { "event_id": "3", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "FX_COMPLETED", "customer_id": "0201001008132685", "client_customer_ref": "skyline_customer_001", "sell_amount": { "currency": "GBP", "value": 1000 }, "buy_amount": { "currency": "AED", "value": 4982.70 }, "quote_rate": 4.9827 } } ``` </Tab> <Tab title="API Payment (Non Third Party)"> ```json { "event_id": "3", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "FX_COMPLETED", "customer_id": "0201001008132685", "sell_amount": { "currency": "GBP", "value": 1000 }, "buy_amount": { "currency": "AED", "value": 4982.70 }, "quote_rate": 4.9827 } } ``` </Tab> </Tabs> </Accordion> <Accordion title="PAYOUT_INITIATED"> <Tabs> <Tab title="Third Party Payment (Session-Based)"> ```json { "event_id": "4", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "session_id": "123e4567-e89b-12d3-a456-426614174000", "payment_id": "123456", "status": "PAYOUT_INITIATED", "customer_id": "0201001008132685", "client_customer_ref": "CUST_001", "client_reference_id": "PAY-REF-001", "amount": { "currency": "AED", "value": 4982.70 }, "recipient_id": "162345" } } ``` </Tab> <Tab title="API Payment (Third Party)"> ```json { "event_id": "4", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "PAYOUT_INITIATED", "customer_id": "0201001008132685", "client_customer_ref": "skyline_customer_001", "amount": { "currency": "AED", "value": 4982.70 }, "recipient_id": "162345" } } ``` </Tab> <Tab title="API Payment (Non Third Party)"> ```json { "event_id": "4", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "PAYOUT_INITIATED", "customer_id": "0201001008132685", "amount": { "currency": "AED", "value": 4982.70 }, "recipient_id": "162345" } } ``` </Tab> </Tabs> </Accordion> <Accordion title="PAYOUT_CREDITED"> <Tabs> <Tab title="Third Party Payment (Session-Based)"> ```json { "event_id": "5", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "session_id": "123e4567-e89b-12d3-a456-426614174000", "payment_id": "123456", "status": "PAYOUT_CREDITED", "customer_id": "0201001008132685", "client_customer_ref": "CUST_001", "client_reference_id": "PAY-REF-001", "amount": { "currency": "AED", "value": 4982.70 }, "recipient_id": "162345" } } ``` </Tab> <Tab title="API Payment (Third Party)"> ```json { "event_id": "5", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "PAYOUT_CREDITED", "customer_id": "0201001008132685", "client_customer_ref": "skyline_customer_001", "amount": { "currency": "AED", "value": 4982.70 }, "recipient_id": "162345" } } ``` </Tab> <Tab title="API Payment (Non Third Party)"> ```json { "event_id": "5", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "PAYOUT_CREDITED", "customer_id": "0201001008132685", "amount": { "currency": "AED", "value": 4982.70 }, "recipient_id": "162345" } } ``` </Tab> </Tabs> </Accordion> <Accordion title="CANCELLED"> <Tabs> <Tab title="Third Party Payment (Session-Based)"> ```json { "event_id": "6", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "session_id": "123e4567-e89b-12d3-a456-426614174000", "payment_id": "123456", "status": "CANCELLED", "customer_id": "0201001008132685", "client_customer_ref": "CUST_001", "client_reference_id": "PAY-REF-001", "reason_description": "Customer cancelled the payment" } } ``` </Tab> <Tab title="API Payment (Third Party)"> ```json { "event_id": "6", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "CANCELLED", "customer_id": "0201001008132685", "client_customer_ref": "skyline_customer_001", "reason_description": "Customer cancelled the payment" } } ``` </Tab> <Tab title="API Payment (Non Third Party)"> ```json { "event_id": "6", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "CANCELLED", "customer_id": "0201001008132685", "reason_description": "Customer cancelled the payment" } } ``` </Tab> </Tabs> </Accordion> <Accordion title="PROCESSING"> > **Note:** This status is used for same-currency payments (no FX conversion required). It is sent immediately after the Payment v3 call. The payload contains base fields only; no status-specific data fields are included. <Tabs> <Tab title="Third Party Payment (Session-Based)"> ```json { "event_id": "7", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "session_id": "123e4567-e89b-12d3-a456-426614174000", "payment_id": "123456", "status": "PROCESSING", "customer_id": "0201001008132685", "client_customer_ref": "CUST_001", "client_reference_id": "PAY-REF-001" } } ``` </Tab> <Tab title="API Payment (Third Party)"> ```json { "event_id": "7", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "PROCESSING", "customer_id": "0201001008132685", "client_customer_ref": "skyline_customer_001" } } ``` </Tab> <Tab title="API Payment (Non Third Party)"> ```json { "event_id": "7", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "PROCESSING", "customer_id": "0201001008132685" } } ``` </Tab> </Tabs> </Accordion> <Accordion title="REFUNDED"> <Tabs> <Tab title="Third Party Payment (Session-Based)"> ```json { "event_id": "8", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "session_id": "123e4567-e89b-12d3-a456-426614174000", "payment_id": "123456", "status": "REFUNDED", "customer_id": "0201001008132685", "client_customer_ref": "CUST_001", "client_reference_id": "PAY-REF-001", "refund_amount": { "currency": "GBP", "value": 1000 }, "refund_reason": "Customer overpaid" } } ``` </Tab> <Tab title="API Payment (Third Party)"> ```json { "event_id": "8", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "REFUNDED", "customer_id": "0201001008132685", "client_customer_ref": "skyline_customer_001", "refund_amount": { "currency": "GBP", "value": 1000 }, "refund_reason": "Customer overpaid" } } ``` </Tab> <Tab title="API Payment (Non Third Party)"> ```json { "event_id": "8", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "REFUNDED", "customer_id": "0201001008132685", "refund_amount": { "currency": "GBP", "value": 1000 }, "refund_reason": "Customer overpaid" } } ``` </Tab> </Tabs> </Accordion> <Accordion title="PAYMENT_COMPLETED"> > **Note:** This status indicates that all payouts in a transaction are in PAYOUT_CREDITED state. This is the final status for all payments (both FX conversion and same-currency payments). <Tabs> <Tab title="Third Party Payment (Session-Based)"> ```json { "event_id": "9", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "session_id": "123e4567-e89b-12d3-a456-426614174000", "payment_id": "123456", "status": "PAYMENT_COMPLETED", "customer_id": "0201001008132685", "client_customer_ref": "CUST_001", "client_reference_id": "PAY-REF-001", "recipient_details": [ { "amount": { "currency": "AED", "value": 4982.70 }, "recipient_id": "162345" }, { "amount": { "currency": "AED", "value": 400.00 }, "recipient_id": "162346" } ] } } ``` </Tab> <Tab title="API Payment (Third Party)"> ```json { "event_id": "9", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "PAYMENT_COMPLETED", "customer_id": "0201001008132685", "client_customer_ref": "skyline_customer_001", "recipient_details": [ { "amount": { "currency": "AED", "value": 4982.70 }, "recipient_id": "162345" }, { "amount": { "currency": "AED", "value": 400.00 }, "recipient_id": "162346" } ] } } ``` </Tab> <Tab title="API Payment (Non Third Party)"> ```json { "event_id": "9", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "PAYMENT_COMPLETED", "customer_id": "0201001008132685", "recipient_details": [ { "amount": { "currency": "AED", "value": 4982.70 }, "recipient_id": "162345" }, { "amount": { "currency": "AED", "value": 400.00 }, "recipient_id": "162346" } ] } } ``` </Tab> </Tabs> </Accordion> <Accordion title="BOUNCED_BACK"> <Tabs> <Tab title="Third Party Payment (Session-Based)"> ```json { "event_id": "10", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "session_id": "123e4567-e89b-12d3-a456-426614174000", "payment_id": "123456", "status": "BOUNCED_BACK", "customer_id": "0201001008132685", "client_customer_ref": "CUST_001", "client_reference_id": "PAY-REF-001", "amount": { "currency": "AED", "value": 4982.70 }, "recipient_id": "162345", "bounce_reason": "Invalid account number" } } ``` </Tab> <Tab title="API Payment (Third Party)"> ```json { "event_id": "10", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "BOUNCED_BACK", "customer_id": "0201001008132685", "client_customer_ref": "skyline_customer_001", "amount": { "currency": "AED", "value": 4982.70 }, "recipient_id": "162345", "bounce_reason": "Invalid account number" } } ``` </Tab> <Tab title="API Payment (Non Third Party)"> ```json { "event_id": "10", "event_type": "PAYMENT STATUS", "version": "v1.0.0", "event_timestamp": "2025-01-01T00:00:00Z", "data": { "payment_id": "123456", "status": "BOUNCED_BACK", "customer_id": "0201001008132685", "amount": { "currency": "AED", "value": 4982.70 }, "recipient_id": "162345", "bounce_reason": "Invalid account number" } } ``` </Tab> </Tabs> </Accordion>
Was this page helpful?
Previous

Third Party Customer Status Updated Event

Next
Built with

Sent when the status of a payment changes. Subscribe to the PAYMENT STATUS event type to receive these updates at your designated endpoint.

Implement idempotent processing and store each event keyed by event_id and payment_id to handle retries and out-of-order delivery.

Status flows and reference

Status Flows & Transitions

Payment status updates follow different flows depending on whether currency conversion (FX) is required:

Flow 1: Payments with FX Conversion (Different Currencies)

Flow 2: Same Currency Payments (No FX Conversion)

Status Reference:

StatusDescriptionApplies To
PROCESSINGSame-currency payment accepted, processing startedSame currency only
AWAITING_FUNDSPayment created, waiting for incoming fundsFX payments
RECEIVED_FUNDSFunds received and credited to customer’s Redpin walletFX payments
FX_COMPLETEDCurrency conversion completedFX payments only
PAYOUT_INITIATEDTransfer to recipient initiatedAll payments
PAYOUT_CREDITEDFunds credited to recipient’s accountAll payments
CANCELLEDPayment cancelled (reason in reason_description)All payments
BOUNCED_BACKRecipient bank returned the funds (reason in bounce_reason)All payments
REFUNDEDPayment refunded to customer (details in refund_amount)All payments
PAYMENT_COMPLETEDAll recipients paid; final statusAll payments
If you receive a status not listed here, log the event and contact the Partner Integrations Team. Your integration should be resilient to new statuses being added.

All envelope fields (event_id, event_type, version, event_timestamp) are always present. Business fields (payment_id, status, customer_id, etc.) are inside the data object.

PAYOUT_CREDITED vs PAYMENT_COMPLETED:

For single-recipient payments, both events are delivered and are functionally equivalent. For multi-recipient payments, PAYOUT_CREDITED fires per recipient; PAYMENT_COMPLETED fires once when all recipients are credited. Treat PAYMENT_COMPLETED as the definitive settlement signal.

Field Availability Reference

Payment types explained:

  • Third Party Payment (Session-Based): Payments created via Hosted payment sessions API
  • API Payment (Third Party): Payments created via Payment API with is_third_party_payment: true
  • API Payment (Non Third Party): Payments created via Payment API with is_third_party_payment: false
FieldThird Party Payment (Session-Based)API Payment (Third Party)API Payment (Non Third Party)
data.session_id✅ Always present❌ Not present❌ Not present
data.client_reference_id✅ Present✅ Present⚠️ Present when provided
data.client_customer_ref✅ Present✅ Present⚠️ Present when provided
data.payment_id✅ Present✅ Present✅ Present
data.status✅ Present✅ Present✅ Present
data.customer_id✅ Present✅ Present✅ Present

See the example payloads below for the specific data object schema associated with each status value.

Glossary
TermDefinition
Envelope fieldsTop-level event metadata: event_id, event_type, version, event_timestamp
Business dataFields inside data describing the payment and its current status
Third party paymentPayment funded by someone other than the account holder (e.g. a buyer paying a property developer)
Non third party paymentPayment funded by the account holder from their own bank account

Example payloads

Each status below shows payloads for all three payment types. The envelope (event_id, event_type, version, event_timestamp) is identical across types; only the data fields differ.

AWAITING_FUNDS
Third Party Payment (Session-Based)
API Payment (Third Party)
API Payment (Non Third Party)
1{
2  "event_id": "1",
3  "event_type": "PAYMENT STATUS",
4  "version": "v1.0.0",
5  "event_timestamp": "2025-01-01T00:00:00Z",
6  "data": {
7    "session_id": "123e4567-e89b-12d3-a456-426614174000",
8    "payment_id": "123456",
9    "status": "AWAITING_FUNDS",
10    "customer_id": "0201001008132685",
11    "client_customer_ref": "CUST_001",
12    "client_reference_id": "PAY-REF-001"
13  }
14}
RECEIVED_FUNDS
Third Party Payment (Session-Based)
API Payment (Third Party)
API Payment (Non Third Party)
1{
2  "event_id": "2",
3  "event_type": "PAYMENT STATUS",
4  "version": "v1.0.0",
5  "event_timestamp": "2025-01-01T00:00:00Z",
6  "data": {
7    "session_id": "123e4567-e89b-12d3-a456-426614174000",
8    "payment_id": "123456",
9    "status": "RECEIVED_FUNDS",
10    "customer_id": "0201001008132685",
11    "client_customer_ref": "CUST_001",
12    "client_reference_id": "PAY-REF-001",
13    "amount": {
14      "currency": "GBP",
15      "value": 1000
16    }
17  }
18}
FX_COMPLETED
Third Party Payment (Session-Based)
API Payment (Third Party)
API Payment (Non Third Party)
1{
2  "event_id": "3",
3  "event_type": "PAYMENT STATUS",
4  "version": "v1.0.0",
5  "event_timestamp": "2025-01-01T00:00:00Z",
6  "data": {
7    "session_id": "123e4567-e89b-12d3-a456-426614174000",
8    "payment_id": "123456",
9    "status": "FX_COMPLETED",
10    "customer_id": "0201001008132685",
11    "client_customer_ref": "CUST_001",
12    "client_reference_id": "PAY-REF-001",
13    "sell_amount": {
14      "currency": "GBP",
15      "value": 1000
16    },
17    "buy_amount": {
18      "currency": "AED",
19      "value": 4982.70
20    },
21    "quote_rate": 4.9827
22  }
23}
PAYOUT_INITIATED
Third Party Payment (Session-Based)
API Payment (Third Party)
API Payment (Non Third Party)
1{
2  "event_id": "4",
3  "event_type": "PAYMENT STATUS",
4  "version": "v1.0.0",
5  "event_timestamp": "2025-01-01T00:00:00Z",
6  "data": {
7    "session_id": "123e4567-e89b-12d3-a456-426614174000",
8    "payment_id": "123456",
9    "status": "PAYOUT_INITIATED",
10    "customer_id": "0201001008132685",
11    "client_customer_ref": "CUST_001",
12    "client_reference_id": "PAY-REF-001",
13    "amount": {
14      "currency": "AED",
15      "value": 4982.70
16    },
17    "recipient_id": "162345"
18  }
19}
PAYOUT_CREDITED
Third Party Payment (Session-Based)
API Payment (Third Party)
API Payment (Non Third Party)
1{
2  "event_id": "5",
3  "event_type": "PAYMENT STATUS",
4  "version": "v1.0.0",
5  "event_timestamp": "2025-01-01T00:00:00Z",
6  "data": {
7    "session_id": "123e4567-e89b-12d3-a456-426614174000",
8    "payment_id": "123456",
9    "status": "PAYOUT_CREDITED",
10    "customer_id": "0201001008132685",
11    "client_customer_ref": "CUST_001",
12    "client_reference_id": "PAY-REF-001",
13    "amount": {
14      "currency": "AED",
15      "value": 4982.70
16    },
17    "recipient_id": "162345"
18  }
19}
CANCELLED
Third Party Payment (Session-Based)
API Payment (Third Party)
API Payment (Non Third Party)
1{
2  "event_id": "6",
3  "event_type": "PAYMENT STATUS",
4  "version": "v1.0.0",
5  "event_timestamp": "2025-01-01T00:00:00Z",
6  "data": {
7    "session_id": "123e4567-e89b-12d3-a456-426614174000",
8    "payment_id": "123456",
9    "status": "CANCELLED",
10    "customer_id": "0201001008132685",
11    "client_customer_ref": "CUST_001",
12    "client_reference_id": "PAY-REF-001",
13    "reason_description": "Customer cancelled the payment"
14  }
15}
PROCESSING

Note: This status is used for same-currency payments (no FX conversion required). It is sent immediately after the Payment v3 call. The payload contains base fields only; no status-specific data fields are included.

Third Party Payment (Session-Based)
API Payment (Third Party)
API Payment (Non Third Party)
1{
2  "event_id": "7",
3  "event_type": "PAYMENT STATUS",
4  "version": "v1.0.0",
5  "event_timestamp": "2025-01-01T00:00:00Z",
6  "data": {
7    "session_id": "123e4567-e89b-12d3-a456-426614174000",
8    "payment_id": "123456",
9    "status": "PROCESSING",
10    "customer_id": "0201001008132685",
11    "client_customer_ref": "CUST_001",
12    "client_reference_id": "PAY-REF-001"
13  }
14}
REFUNDED
Third Party Payment (Session-Based)
API Payment (Third Party)
API Payment (Non Third Party)
1{
2  "event_id": "8",
3  "event_type": "PAYMENT STATUS",
4  "version": "v1.0.0",
5  "event_timestamp": "2025-01-01T00:00:00Z",
6  "data": {
7    "session_id": "123e4567-e89b-12d3-a456-426614174000",
8    "payment_id": "123456",
9    "status": "REFUNDED",
10    "customer_id": "0201001008132685",
11    "client_customer_ref": "CUST_001",
12    "client_reference_id": "PAY-REF-001",
13    "refund_amount": {
14      "currency": "GBP",
15      "value": 1000
16    },
17    "refund_reason": "Customer overpaid"
18  }
19}
PAYMENT_COMPLETED

Note: This status indicates that all payouts in a transaction are in PAYOUT_CREDITED state. This is the final status for all payments (both FX conversion and same-currency payments).

Third Party Payment (Session-Based)
API Payment (Third Party)
API Payment (Non Third Party)
1{
2  "event_id": "9",
3  "event_type": "PAYMENT STATUS",
4  "version": "v1.0.0",
5  "event_timestamp": "2025-01-01T00:00:00Z",
6  "data": {
7    "session_id": "123e4567-e89b-12d3-a456-426614174000",
8    "payment_id": "123456",
9    "status": "PAYMENT_COMPLETED",
10    "customer_id": "0201001008132685",
11    "client_customer_ref": "CUST_001",
12    "client_reference_id": "PAY-REF-001",
13    "recipient_details": [
14      { 
15        "amount": {
16          "currency": "AED",
17          "value": 4982.70
18        }, 
19        "recipient_id": "162345" 
20      },
21      { 
22        "amount": {
23          "currency": "AED",
24          "value": 400.00
25        }, 
26        "recipient_id": "162346" 
27      }
28    ]
29  }
30}
BOUNCED_BACK
Third Party Payment (Session-Based)
API Payment (Third Party)
API Payment (Non Third Party)
1{
2  "event_id": "10",
3  "event_type": "PAYMENT STATUS",
4  "version": "v1.0.0",
5  "event_timestamp": "2025-01-01T00:00:00Z",
6  "data": {
7    "session_id": "123e4567-e89b-12d3-a456-426614174000",
8    "payment_id": "123456",
9    "status": "BOUNCED_BACK",
10    "customer_id": "0201001008132685",
11    "client_customer_ref": "CUST_001",
12    "client_reference_id": "PAY-REF-001",
13    "amount": {
14      "currency": "AED",
15      "value": 4982.70
16    },
17    "recipient_id": "162345",
18    "bounce_reason": "Invalid account number"
19  }
20}

Payload

The payload of this webhook request is an object.
event_idstringRequired
Unique identifier for the event.
event_typeenumRequired
Type of webhook event. Always "PAYMENT STATUS" for payment status events.
Allowed values:
versionstringRequired
Payload version. Currently "v1.0.0". This enables controlled evolution of the webhook contract.
event_timestampdatetimeRequired

Timestamp of the event in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).

dataobjectRequired
Business data for the payment status event. Contains payment, customer, and status information. The structure varies by payment status and integration type.

Response

200
Webhook received successfully
400
Invalid payload