Payment Status Updated Event
Sent when the status of a payment changes at various stages of the payment journey.
Once you have subscribed to the "PAYMENT STATUS" event type, Redpin will call your designated API endpoint with the payload described below when there is an update to one of your payment's statuses.
**Status Flow Diagram:**
```mermaid
graph TD;
AWAITING_FUNDS --> RECEIVED_FUNDS --> FX_COMPLETED --> PAYOUT_INITIATED --> PAYOUT_CREDITED --> PAYMENT_COMPLETED
AWAITING_FUNDS --> PROCESSING
PROCESSING --> CANCELLED
RECEIVED_FUNDS --> REFUNDED
REFUNDED --> BOUNCED_BACK
PAYOUT_INITIATED --> BOUNCED_BACK
BOUNCED_BACK --> REFUNDED
PAYOUT_INITIATED --> CANCELLED
```
**Status to Schema Mapping:**
| Status | Description |
|--------------------|------------------------------------|
| AWAITING_FUNDS | Payment created, waiting for funds to be received |
| RECEIVED_FUNDS | Funds have been received and credited to customer's Redpin wallet |
| FX_COMPLETED | Foreign exchange conversion completed successfully |
| PAYOUT_INITIATED | Payment transfer to recipient has been initiated |
| PAYOUT_CREDITED | Payment has been successfully credited to recipient's account |
| CANCELLED | Payment has been cancelled (with reason) |
| PROCESSING | Payment is being processed (with additional information) |
| REFUNDED | Payment has been refunded to the customer |
| BOUNCED_BACK | Payment transfer failed and bounced back |
| PAYMENT_COMPLETED | All recipients have been paid and payment is fully completed |
> **Note:** If you receive a status not listed here, log the event and contact support. Your integration should be resilient to new statuses.
> **Note:** All top-level fields (`event_id`, `payment_id`, `status`, `customer_id`, `event_timestamp`, `data`) are always present in every event.
**Difference between PAYOUT_CREDITED and PAYMENT_COMPLETED:**
>If a payment has only one recipient, then PAYOUT_CREDITED is functionally equivalent to PAYMENT_COMPLETED, and both events will be delivered.
> If a payment has multiple recipients, PAYOUT_CREDITED will be delivered each time the amount for a recipient is credited to their account. PAYMENT_COMPLETED will be delivered only when all recipients have been credited with their expected amounts.
**Example Payloads:**
**AWAITING_FUNDS**
```json
{
"event_id": "1",
"payment_id": "123456",
"status": "AWAITING_FUNDS",
"customer_id": "0201001008132685",
"client_customer_ref": "CUST_001",
"event_timestamp": "2025-01-01T00:00:00Z",
"data": {}
}
```
**RECEIVED_FUNDS**
```json
{
"event_id": "2",
"payment_id": "123456",
"status": "RECEIVED_FUNDS",
"customer_id": "0201001008132685",
"client_customer_ref": "CUST_001",
"event_timestamp": "2025-01-01T00:00:00Z",
"data": {
"amount": {
"currency": "GBP",
"value": 1000
}
}
}
```
**FX_COMPLETED**
```json
{
"event_id": "3",
"payment_id": "123456",
"status": "FX_COMPLETED",
"customer_id": "0201001008132685",
"client_customer_ref": "CUST_001",
"event_timestamp": "2025-01-01T00:00:00Z",
"data": {
"sell_amount": {
"currency": "GBP",
"value": 1000
},
"buy_amount": {
"currency": "AED",
"value": 4982.70
},
"quote_rate": 4.9827
}
}
```
**PAYOUT_INITIATED**
```json
{
"event_id": "4",
"payment_id": "123456",
"status": "PAYOUT_INITIATED",
"customer_id": "0201001008132685",
"client_customer_ref": "CUST_001",
"event_timestamp": "2025-01-01T00:00:00Z",
"data": {
"amount": {
"currency": "AED",
"value": 4982.70
},
"recipient_id": "162345"
}
}
```
**PAYOUT_CREDITED**
```json
{
"event_id": "5",
"payment_id": "123456",
"status": "PAYOUT_CREDITED",
"customer_id": "0201001008132685",
"client_customer_ref": "CUST_001",
"event_timestamp": "2025-01-01T00:00:00Z",
"data": {
"amount": {
"currency": "AED",
"value": 4982.70
},
"recipient_id": "162345"
}
}
```
**CANCELLED**
```json
{
"event_id": "6",
"payment_id": "123456",
"status": "CANCELLED",
"customer_id": "0201001008132685",
"client_customer_ref": "CUST_001",
"event_timestamp": "2025-01-01T00:00:00Z",
"data": {
"reason_description": "Customer cancelled the payment"
}
}
```
**PROCESSING**
```json
{
"event_id": "7",
"payment_id": "123456",
"status": "PROCESSING",
"customer_id": "0201001008132685",
"client_customer_ref": "CUST_001",
"event_timestamp": "2025-01-01T00:00:00Z",
"data": {
"additional_info": "Recieved partial funds"
}
}
```
**REFUNDED**
```json
{
"event_id": "8",
"payment_id": "123456",
"status": "REFUNDED",
"customer_id": "0201001008132685",
"client_customer_ref": "CUST_001",
"event_timestamp": "2025-01-01T00:00:00Z",
"data": {
"refund_amount": {
"currency": "GBP",
"value": 1000
},
"refund_reason": "Customer overpaid"
}
}
```
**PAYMENT_COMPLETED**
```json
{
"event_id": "9",
"payment_id": "123456",
"status": "PAYMENT_COMPLETED",
"customer_id": "0201001008132685",
"client_customer_ref": "CUST_001",
"event_timestamp": "2025-01-01T00:00:00Z",
"data": {
"recipient_details": [
{
"amount": {
"currency": "AED",
"value": 4982.70
},
"recipient_id": "162345"
},
{
"amount": {
"currency": "AED",
"value": 400.00
},
"recipient_id": "162346"
}
]
}
}
```
**BOUNCED_BACK**
```json
{
"event_id": "10",
"payment_id": "123456",
"status": "BOUNCED_BACK",
"customer_id": "0201001008132685",
"client_customer_ref": "CUST_001",
"event_timestamp": "2025-01-01T00:00:00Z",
"data": {
"amount": {
"currency": "AED",
"value": 4982.70
},
"recipient_id": "162345",
"bounce_reason": "Invalid account number"
}
}
```
Payload
The payload of this webhook request is an object.
event_id
Unique identifier for the event.
payment_id
Unique identifier for the payment. This is the same as the payment_id in the Create a Payment operation.
status
Status of the payment.
customer_id
Unique identifier for the customer associated with the payment.
data
The structure of the `data` object varies depending on the payment status.
See the documentation below for the specific data object schema associated with each status value.
<AccordionGroup>
<Accordion title='data for AWAITING_FUNDS'>
- (empty object)
</Accordion>
<Accordion title='data for RECEIVED_FUNDS'>
- **amount** (object, required):
- **currency** (string, required): Currency code (ISO 4217).
- **value** (number, required): Amount credited to the customer's Redpin wallet.
</Accordion>
<Accordion title='data for FX_COMPLETED'>
- **sell_amount** (object, required):
- **currency** (string, required): Currency code (ISO 4217) of the currency being sold.
- **value** (number, required): Amount of currency being sold as part of the FX transaction.
- **buy_amount** (object, required):
- **currency** (string, required): Currency code (ISO 4217) of the currency being bought.
- **value** (number, required): Amount of currency being bought as part of the FX transaction.
- **quote_rate** (number, required): Exchange rate used for the FX transaction.
</Accordion>
<Accordion title='data for PAYOUT_INITIATED'>
> **Clarification:** This status means the payment transfer to the recipient has been initiated by Redpin, but the funds may not yet have reached the recipient's account.
- **amount** (object, required):
- **currency** (string, required): Currency code (ISO 4217) of the currency being paid out.
- **value** (number, required): Amount of currency being paid out to the recipient.
- **recipient_id** (string, required): Unique identifier for the recipient to whom the payout is being made.
</Accordion>
<Accordion title='data for PAYOUT_CREDITED'>
> **Clarification:** This status means the payment has been successfully credited to the recipient's account. This is a confirmation that the funds have reached the recipient.
- **amount** (object, required):
- **currency** (string, required): Currency code (ISO 4217) of the currency being paid out.
- **value** (number, required): Amount of currency credited to the recipient.
- **recipient_id** (string, required): Unique identifier for the recipient to whom the payout is being made.
</Accordion>
<Accordion title='data for CANCELLED'>
- **reason_description** (string, required): Reason for the cancellation.
</Accordion>
<Accordion title='data for PROCESSING'>
- **additional_info** (string, required): Additional information about the processing status.
</Accordion>
<Accordion title='data for REFUNDED'>
- **refund_amount** (object, required):
- **currency** (string, required): Currency code (ISO 4217) of the currency being refunded.
- **value** (number, required): Amount of currency being refunded.
- **refund_reason** (string, required): Reason for the refund.
</Accordion>
<Accordion title='data for PAYMENT_COMPLETED'>
- **recipient_details** (array, required): Details of the recipients of the payment.
- Each item (object, required):
- **amount** (object, required):
- **currency** (string, required): Currency code (ISO 4217) of the currency credited to the recipient.
- **value** (number, required): Amount of currency credited to the recipient.
- **recipient_id** (string, required): Unique identifier for the recipient to whom the payment is being made.
</Accordion>
<Accordion title='data for BOUNCED_BACK'>
- **amount** (object, required):
- **currency** (string, required): Currency code (ISO 4217) of the currency that bounced back.
- **value** (number, required): Amount of currency that bounced back from the recipient.
- **recipient_id** (string, required): Unique identifier for the recipient from whom the payment bounced back.
- **bounce_reason** (string, required): Reason why the payment transfer failed and bounced back.
</Accordion>
</AccordionGroup>
event_timestamp
Timestamp of the event in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
client_customer_ref
The unique reference identifier of the third party client for whom the third party payment was made.
Response
200
any
Return a 200 status to indicate that the data was received successfully.
