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:
Status to Schema Mapping:
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
RECEIVED_FUNDS
FX_COMPLETED
PAYOUT_INITIATED
PAYOUT_CREDITED
CANCELLED
PROCESSING
REFUNDED
PAYMENT_COMPLETED
BOUNCED_BACK
Payload
Unique identifier for the payment. This is the same as the payment_id in the Create a Payment operation.
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.
data for AWAITING_FUNDS
- (empty object)
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.
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.
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.
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.
data for CANCELLED
- reason_description (string, required): Reason for the cancellation.
data for PROCESSING
- additional_info (string, required): Additional information about the processing status.
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.
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.
- amount (object, required):
- Each item (object, required):
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.
Timestamp of the event in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).