Payment Status Updated Event

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>