Skip to navigation
Webhook ReferencePayments

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

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

Flow 1: Payments with FX Conversion (Different Currencies)

AWAITING_FUNDS RECEIVED_FUNDS FX_COMPLETED PAYOUT_INITIATED PAYOUT_CREDITED PAYMENT_COMPLETED CANCELLED BOUNCED_BACK

Flow 2: Same Currency Payments (No FX Conversion)

PROCESSING PAYOUT_INITIATED PAYOUT_CREDITED PAYMENT_COMPLETED CANCELLED BOUNCED_BACK

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 cancelledAll payments
BOUNCED_BACKRecipient bank returned the fundsAll 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.

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.

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.

{
  "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"
  }
}
{
  "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
    }
  }
}
{
  "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
  }
}
{
  "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"
  }
}
{
  "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"
  }
}
{
  "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"
  }
}

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.

{
  "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"
  }
}

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).

{
  "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" 
      }
    ]
  }
}
{
  "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"
  }
}

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