Returns

Sometimes you may need to return Payments because for various reasons such as compliance, third party payments etc. You can easily return unwated 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"
   }
}
'

Return a Payment to another bank account

It is also possible to return a payment to a new payee altogether. You may need to do this sometimes if the sender's original bank doesn't accept the return and therefore you need to return the funds to another account held by your user at a different bank. To do this, you will be able to provide the full details of the new payee within the Payment Returns request in a similar format to how you would provide payee details when creating a new payee via the Create Payee endpoint.

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_pgrbvdy1vnd7z54n6m",
   "reason":"3rd party payment",
   "returnDetails":{
      "payee":{
         "endUserId":"eus_j82rl497g47g5ykvzn",
         "type":"PERSON",
         "name":"Satoshi Nakamoto",
         "currency":"EUR",
         "address":null,
         "bankDetails":{
            "iban":"DE26500105175531162342"
         }
      }
   }
}
'

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"
   }
}
'