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

# The Returns Object

Unwanted Incoming Payments (Payins) can be easily returned via the returns endpoints.

If you need to return funds to anyone other than the original or Existing Payee, the requirement will be to first create such a payee and only use it once it is `ACTIVE` with option Existing Payee selected.

Each return creates a dedicated `Payment Returns` object containing the details of the return, and is linked to the Payment that was returned by its id.

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Attribute
      </th>

      <th>
        Description
      </th>

      <th>
        Format/Enum
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **id**
        *string*
      </td>

      <td>
        Unique identifier of the return payment.
      </td>

      <td>
        e.g. `rtn_4jalpeo0em7bkx39z6`
      </td>
    </tr>

    <tr>
      <td>
        **paymentId**\
        *string*
      </td>

      <td>
        Unique identifier of the payment for which the return was created.
      </td>

      <td>
        e.g. `pmt_nx83lr41ov7dy5va2g`
      </td>
    </tr>

    <tr>
      <td>
        **payeeId**\
        *string*
      </td>

      <td>
        Unique identifier of the payee to who the payment was returned.
      </td>

      <td>
        e.g. `pye_exz3l6d7b9n0myjr5v`
      </td>
    </tr>

    <tr>
      <td>
        **reference**\
        *string*
      </td>

      <td>
        Reference sent with the return.
      </td>

      <td>
        Return reference must consist of at least 6 alphanumeric characters that are not all the same. Can contain special characters include space, hyphen(-), full stop (.), ampersand(&), and forward slash (/), which are  uncounted.  
      </td>
    </tr>

    <tr>
      <td>
        **amount**\
        *string*
      </td>

      <td>
        Amount of the return payment in 2 decimal places.
      </td>

      <td>
        e.g. 121.21
      </td>
    </tr>

    <tr>
      <td>
        **currency**\
        *string*
      </td>

      <td>
        Currency of the return payment.
      </td>

      <td>
        Three-letter [ISO 4217 code](https://en.wikipedia.org/wiki/ISO_4217) e.g. `GBP`, `EUR` , `USD`
      </td>
    </tr>

    <tr>
      <td>
        **paymentScheme**\
        *string*
      </td>

      <td>
        Payment scheme used for the return payment.
      </td>

      <td>
        `FPS`, `CHAPS`, `SCT`
      </td>
    </tr>

    <tr>
      <td>
        **status**\
        *string*
      </td>

      <td>
        Status of the return payment.
      </td>

      <td>
        `CREATED`, `PROCESSING`, `COMPLETED`, `COMPLIANCE_REVIEW`, `FAILED`, `REJECTED`
      </td>
    </tr>

    <tr>
      <td>
        **createdAt**\
        *integer*
      </td>

      <td>
        Epoch timestamp at which the object was created.
      </td>

      <td>
        e.g. `1637593856104`
      </td>
    </tr>

    <tr>
      <td>
        **updatedAt**\
        *integer*
      </td>

      <td>
        Epoch timestamp at which the object was last updated.
      </td>

      <td>
        e.g. `1637593856104`
      </td>
    </tr>
  </tbody>
</Table>