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>