Returns
Sometimes you may need to return Payments because of various reasons such as compliance, third party payments etc. You can easily return unwanted Payments (Payins) back to the sender or a third party without having to manually create new Payees.
When you create a return, the full amount of the payment will be returned using the same payment scheme via which it was received.
Return a Payment to the sender (Payer)
Usually, you will need to return a payment to the sender i.e. to the same bank account from where it came. This can be done by simply calling the Create Return endpoint providing the id
of the Payment you want to return along with an internal reason
to capture why you are returning the payment.
curl --request POST \
--url https://sandbox.fiatrepublic.com/api/v1/payment-returns \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ZmlhdHJlcHVibGljOmZpYXRyZXB1YmxpYw==' \
--header 'Content-Type: application/json' \
--data '
{
"paymentId": "pmt_xpn6le15na21v9jo4g",
"reason": "3rd party payment"
}
'
Creating a return is asynchronous and will create a new Payment Return
entity that is linked to the payment being returned. Initially, this will be in a CREATED
state.
{
"id":"rtn_j82rl497g47g5ykvzn",
"memberId":"mbr_emv4j231821oaz56yx",
"status":"CREATED",
"paymentId":"pmt_xpn6le15nyk1v9jo4g",
"payeeId":"pye_pgrbvdy1vy31z54n6m",
"reference":"RET - Deposit",
"amount":"100.12",
"currency":"GBP",
"paymentScheme":"FPS",
"reason":"3rd party payment",
"createdAt":1677249715102,
"updatedAt":1677249715102
}
Once the return payment has been processed by the banking provider, the status of the Payment Return
entity will be updated to COMPLETED
, and the status of the Payment
that was returned will be updated to RETURNED
. Funds will be debited from the same account into which they were received, and a new Transaction
of type RETURN
will be created on the relevant Fiat / Virtual Account.
Return a Payment to the another existing Payee
Sometimes you may wish to return a payment to another Payee that was already created on the system previously. In this case, it is sufficient to provide the id of the payee in the returnDetails
part of the request.
curl --request POST \
--url https://sandbox.fiatrepublic.com/api/v1/payment-returns \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ZmlhdHJlcHVibGljOmZpYXRyZXB1YmxpYw==' \
--header 'Content-Type: application/json' \
--data '
{
"paymentId":"pmt_xpn6le15na21v9jo4g",
"reason":"3rd party payment",
"returnDetails":{
"payeeId":"pye_nx83lr41ov7dy5va2g"
}
}
'
In addition to creating the return entity, the system will also automatically create a Payee with the details provided which can be reused in the future by referencing its' id.
Custom Return Reference and Payment Scheme
By default, the payment reference
used in the return will be the same as the reference received on the original payment but prefixed with RET -
. e.g. if the original payment had a reference Deposit
, the return payment will have the reference RET - Deposit
. However, you can also provide a different reference in the return request if required.
Similarly, if you wish the return a payment via a payment scheme different from the one that was used fo the original payment, you can provide a custom value in the return request.
curl --request POST \
--url https://sandbox.fiatrepublic.com/api/v1/payment-returns \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ZmlhdHJlcHVibGljOmZpYXRyZXB1YmxpYw==' \
--header 'Content-Type: application/json' \
--data '
{
"paymentId":"pmt_xpn6le15na21v9jo4g",
"reason":"3rd party payment",
"returnDetails":{
"reference":"custom reference",
"paymentScheme":"CHAPS"
}
}
'
Updated 27 days ago