post https://www.bankingcircleconnect.com/api/v1/returns
The endpoint is used for returning a payment.
To perform a return payment, a reference to the original payment (paymentId) must be supplied and a valid returnReason specified. Upon initiation, a new payment transaction will be instructed, that includes return-related details embedded in the remittance information line 1, 2, 3 & 4:
Line 1: "RETURN OF PAYMENT"Line 2: Transaction reference to original payment, ex. "010F2422510258PF"Line 3&4: Return reason, ex. "By order of beneficiary"
This ensures the return is properly documented and traceable for both parties.
The new return payment will be visible among all other transactions.
Key points and limitations:
- Initiation of return payments are subject to the same limitations as initiating an outgoing payment. Please see Initiate Payments
- Return payments follow the same pricing as outgoing transactions, with the Charge Bearer set to "SHA" (shared charges)
- Return payments requiring a purpose code for mainland China are not supported
- Agency Banking & Corresponding Banking payments are not supported
- A payment cannot be returned if it has already been returned, of if a return request is currently in progress
- Support for local payments may vary depending on the payment type
- If the Creditor Name exceeds 35 characters, it will be truncated, and unsupported symbols may be converted to prevent rejections
- Second return attempts are not supported. If a return is canceled, any new return must be completed by instructing an outgoing payment - see Initiate Payments
Valid returnReasonvalues | Return reason embedded in remittanceInfoline 3 & 4 |
|---|---|
| "Beneficiary" | By order of beneficiary |
| "Duplicate" | Duplicate payment |
| "NonUnique" | Non unique transaction reference |
| "Remitter" | Remitters request |
| "UnknownCreditor" | Creditor not recognised |
| "UnknownDebtor" | Missing debtor name or address |
Error codes & descriptions
errorCode | errorDescription | HTTP Status Code |
|---|---|---|
| NotFound | Payment was not found. | 404, Not Found |
| NotProcessed | Only processed payments can be returned. | 400, Bad Request |
| InvalidPaymentClassification | Only payments with classification Incoming or Own can be returned. | 400, Bad Request |
| PaymentExpired | The payment's value date exceeds the allowed threshold. | 400, Bad Request |
| ReturnPaymentPending | A return has already been initiated for this payment. | 400, Bad Request |
| AlreadyReturned | A return has already been attempted. Please contact Client Services. | 400, Bad Request |
| InvalidReturnReason | Invalid return reason. | 400, Bad Request |
| UnknownPurposeCode | Valid purpose code required. | 400, Bad Request |
| UnsupportedPaymentFlow | This payment is not eligible for a return via this channel. Please contact Client Services. | 400, Bad Request |
| UnspecifiedError | An error occurred returning the payment. Please contact Client Services. | 400, Bad Request |