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 a normal payment. Please see Initiate Payments
- A return payment will follow the same pricing as outgoing transactions
- Return payments requiring a purpose code for mainland China are not supported
- Agency Banking & Corresponding Banking payments are not supported
- Charge Bearer will be set to "SHA" (shared charges)
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 | This payment has already been returned. | 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 |