---
title: Return rails
slug: apis/lending/loan-funding-payment-rails/return-rails
description: Discover how to efficiently return rails using the ReturnRail API, ensuring eligibility checks, accurate tracking, and seamless error handling for optimal results.
icon: {"apiMethod":"PUT"}
docTags: 
createdAt: 2024-11-10T10:44:01.526Z
---

:::CtaButton{label="Loan returns concepts" docId="yvKvFJcitSb3lCSg1d6Op" openInNewTab="true"}
You can manage both deposit and withdrawal checking for your customers using Cross River APIs.
:::

## ReturnRail API overview

The **ReturnRail API** provides partners with a method to return a rail that already received a **`Success`** status and has not yet been **`Returned`**. This API enables partners to programmatically trigger the return operation (revoke/reverse) on a specific rail that was requested on a loan.

### Supported rail types

- **XPay** (Internal Transfer)
- **Check** (only if not yet cashed)

## Flow of funds

### When this API can be called

Before calling the ReturnRail API, ensure the rail is eligible for return:

Rail should have received a status `Success`, and **not **received after one of the following terminal statuses:

- `Returned`
- `Failed`
- `Cancelled`
- `CosXPaymentCanceled`
- `CosXPaymentRejected`
- `CosXPaymentFailed`

:::hint{type="warning"}
Returning a check actually revokes it from our Positive Pay system. This can only be done before a check is cashed. 
:::

### Flow of return rails

When trying to fund a rail, an ID is returned in the response. You will need this *Rail ID *in order to:

- Track this Rail ID using the `RailUpdated` [Hook notifications](docId\:jXGfRbtNHOshrZJYHYKTo) . 
  - The full list of FundResults found in this webhook is in the RailResultType [Enums](docId\:hpq_QWOAKV9JprqwkFR1I) . 
- Request the ReturnRails API, using this RaiID.

When the return of a rail completes, the loan status will also be updated, depending on the current status of the loan. You can track this with the `LoanStatusUpdated` hook notification.

:::hint{type="warning"}
Requesting the ReturnRails API, will always return a `200` if the request was correct. The return is considered completed when you receive the return status in the RailUpdated webhook event. If the return is NOT completed, you will not receive a notification about this.
:::

Flow of statuses in `RailUpdated` webhook.

| Action                     | FundResult (`RailResultType` [Enums](docId\:hpq_QWOAKV9JprqwkFR1I) ) | Description                                                                                                            |
| -------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Post /ReturnRails succeeds |                                                                      | This APi just kicks off the return process. The status of the rail does not yet change.                                |
| The Return Succeeds        | Returned                                                             | The rail has been successfully reversed, and now the loan amount of the rail will be available to be disbursed again.  |

## PUT /{LoanID}/ReturnRails

:::ApiMethodV2
```json
{
  "name": "Return Rails",
  "method": "PUT",
  "url": "https://arixapisandbox.crbnj.net/Loan/{LoanID}/ReturnRails",
  "description": "",
  "tab": "examples",
  "examples": {
    "languages": [
      {
        "id": "lhSugoeGPG4flwK7y_4Ou",
        "language": "curl",
        "code": "curl --location --globoff 'https://arixapisandbox.crbnj.net/Loan/{LoanID}/ReturnRails' \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--data '{\n  \"railIds\": [\"<railId1>\", \"<railId2>\"],\n  \"reason\": \"string\"\n}'",
        "customLabel": ""
      }
    ],
    "selectedLanguageId": "lhSugoeGPG4flwK7y_4Ou"
  },
  "results": {
    "languages": [
      {
        "id": "QqHiLt-FHhPgn7vzGSzAQ",
        "language": "200",
        "code": "{\n   \n}",
        "customLabel": ""
      },
      {
        "id": "tyfobRzvVk1n0SUYH7D-l",
        "language": "400",
        "code": " {\n    \"ResponseStatus\": {\n        \"ErrorCode\": \"BadRequest\",\n        \"Message\": \"Loan was not provided for the provided loanId\",\n        \"Errors\": []\n    }\n}\n",
        "customLabel": ""
      }
    ],
    "selectedLanguageId": "tyfobRzvVk1n0SUYH7D-l"
  },
  "request": {
    "pathParameters": [
      {
        "name": "LoanID",
        "kind": "required",
        "type": "string",
        "description": "The Unique ID of the loan returned from the POST /Loan API call.",
        "": "The Unique ID of the loan returned from the POST /Loan API call."
      }
    ],
    "queryParameters": [],
    "headerParameters": [],
    "bodyDataParameters": [
      {
        "name": "railIds",
        "kind": "required",
        "type": "array",
        "description": "Unique identifier of rail that was previously created in Arix. Arix generates this Identifier. ",
        "": "Unique identifier of rail that was previously created in Arix. Arix generates this Identifier. "
      },
      {
        "name": "reason",
        "kind": "required",
        "type": "string",
        "description": "The reason that you are requesting a return. ",
        "": "The reason that you are requesting a return. "
      }
    ],
    "formDataParameters": []
  },
  "currentNewParameter": {
    "label": "Body Parameter",
    "value": "bodyDataParameters"
  },
  "response": [
    {
      "name": "message",
      "kind": "optional",
      "type": "string",
      "description": "Returns a verbose message that explains the status of the request",
      "children": []
    }
  ],
  "hasTryItOut": false,
  "autoGeneratedAnchorSlug": "return-rails",
  "legacyHash": "GiyxreRBS0oUFTGmVV7-K"
}
```
:::