---
updatedAt: 2025-06-12T23:56:44.000Z
agentTools:
  projectIndex: https://docs.fiatrepublic.com/llms.txt
---

# 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](https://docs.fiatrepublic.com/reference/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 Create Return
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.

```json Create Return Response
{
   "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 Create Return
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"
   }
}
'
```

<br />

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 Create Return
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"
   }
}
'
```