> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.redpincompany.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.redpincompany.com/_mcp/server. # Payment Status Updated Event POST 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 referencePayment 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 PAYOUT_INITIATED --> BOUNCED_BACK 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 ```**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 | All payments | | BOUNCED\_BACK | Recipient bank returned the funds | All payments | | PAYMENT\_COMPLETED | All recipients paid; final status | All 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.> **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.| 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 |## Example payloadsEach 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.```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" } } ``````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" } } ``````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" } } ``````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 } } } ``````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 } } } ``````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 } } } ``````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 } } ``````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 } } ``````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 } } ``````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" } } ``````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" } } ``````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" } } ``````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" } } ``````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" } } ``````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" } } ``````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" } } ``````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" } } ``````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" } } ```> **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.```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" } } ``````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" } } ``````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" } } ```> **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).```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" } ] } } ``````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" } ] } } ``````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" } ] } } ``````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" } } ``````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" } } ``````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" } } ``` Reference: https://docs.redpincompany.com/api-reference/webhooks/payments/webhook-payment-status-updated ## Request ### Payload - `event_id` (string, required) — Unique identifier for the event. - `event_type` (enum, required) — Type of webhook event. Always "PAYMENT STATUS" for payment status events. - Allowed values: `PAYMENT STATUS` - `version` (string, required) — Payload version. Currently "v1.0.0". This enables controlled evolution of the webhook contract. - `event_timestamp` (datetime, required) — Timestamp of the event in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). - `data` (PaymentStatusEventData, required) — Business data for the payment status event. Contains payment, customer, and status information. The structure varies by payment status and integration type. ## Types ### PaymentStatusEventData Business data for the payment status event. Contains payment, customer, and status information. The structure varies by payment status and integration type. - `payment_id` (string, required) — Unique identifier for the payment. This is the same as the payment_id in the `Create a Payment` operation. - `status` (enum, required) — Status of the payment. - Allowed values: `AWAITING_FUNDS`, `RECEIVED_FUNDS`, `FX_COMPLETED`, `PAYOUT_INITIATED`, `PAYOUT_CREDITED`, `CANCELLED`, `PROCESSING`, `PAYMENT_COMPLETED`, `BOUNCED_BACK` - `customer_id` (string, required) — Unique identifier for the customer associated with the payment. - `session_id` (string, optional) — Unique identifier for the payment session. - `client_customer_ref` (string, optional) — Unique reference of the third party client for whom the payment was made. - `client_reference_id` (string, optional) — Client-provided reference for payment reconciliation. For third-party payments only, uniqueness is enforced per customer (per `customer_id`); duplicate values for the same customer are rejected. For non-third-party payments, uniqueness is not checked. - `amount` (PaymentStatusEventDataAmount, optional) — Payment amount (present for RECEIVED_FUNDS, PAYOUT_INITIATED, PAYOUT_CREDITED, BOUNCED_BACK). - `recipient_id` (string, optional) — Unique identifier for the recipient (present for PAYOUT_INITIATED, PAYOUT_CREDITED, BOUNCED_BACK). - `recipient_details` (list of PaymentStatusEventDataRecipientDetailsItems, optional) — Details of recipients for multi-recipient payments (present for PAYMENT_COMPLETED). - `sell_amount` (PaymentStatusEventDataSellAmount, optional) — Amount being sold in FX conversion (present for FX_COMPLETED). - `buy_amount` (PaymentStatusEventDataBuyAmount, optional) — Amount being bought in FX conversion (present for FX_COMPLETED). - `quote_rate` (double, optional) — Exchange rate used for FX conversion (present for FX_COMPLETED). ### PaymentStatusEventDataAmount Payment amount (present for RECEIVED_FUNDS, PAYOUT_INITIATED, PAYOUT_CREDITED, BOUNCED_BACK). - `currency` (string, optional) - `value` (double, optional) ### PaymentStatusEventDataRecipientDetailsItems - `amount` (PaymentStatusEventDataRecipientDetailsItemsAmount, optional) - `recipient_id` (string, optional) ### PaymentStatusEventDataSellAmount Amount being sold in FX conversion (present for FX_COMPLETED). - `currency` (string, optional) - `value` (double, optional) ### PaymentStatusEventDataBuyAmount Amount being bought in FX conversion (present for FX_COMPLETED). - `currency` (string, optional) - `value` (double, optional) ### PaymentStatusEventDataRecipientDetailsItemsAmount - `currency` (string, optional) - `value` (double, optional)