> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instant payment eligibility

> Check which instant rails, RTP or FedNow, a recipient's bank can receive on before you send.

A receiving bank may take RTP, FedNow, both, or neither. Look up the recipient's routing number before an RTP or FedNow send to pick a rail the bank can receive on.

`GET /embedded-banking/v1/instant-payment-eligibility/{routingNumber}`

The lookup takes a 9-digit ABA routing number. A number that fails the ABA checksum returns `400` with `errorCode: VALIDATION_ERROR`.

```json title="Example Response" lines theme={null}
{
  "routingNumber": "123456780",
  "bankName": "Example Community Bank",
  "availableRails": ["RTP"],
  "rails": [
    { "rail": "RTP", "eligibility": "ELIGIBLE", "asOfDate": "2026-11-02" },
    { "rail": "FED_NOW", "eligibility": "NOT_ELIGIBLE", "asOfDate": "2026-11-03" }
  ]
}
```

`rails` always holds one entry per rail, RTP first. `availableRails` lists the rails whose answer is `ELIGIBLE`, and is empty when there are none. `bankName` is the name the RTP list gives the bank, or the FedNow list's name when only FedNow lists it.

> [!NOTE]
>
> Required scope: `transfer:write:org`, on a user or app token. The lookup needs no per-rail scope.

## What each answer means

| `eligibility` | Meaning | A send on this rail |
| :- | :- | :- |
| `ELIGIBLE` | The bank is on the rail's participant list and can receive credits on it today. | Proceeds |
| `NOT_ELIGIBLE` | The bank is listed only on the other rail, or its RTP activation date is still in the future. A future activation turns `ELIGIBLE` on that date. | Refused with `422` |
| `UNKNOWN` | The routing number is on neither rail's list, or the rail's list isn't available. | Proceeds |

A routing number on neither list returns `200`, both rails `UNKNOWN`, no `bankName`, and an empty `availableRails`:

```json title="Example Response" lines theme={null}
{
  "routingNumber": "111111118",
  "availableRails": [],
  "rails": [
    { "rail": "RTP", "eligibility": "UNKNOWN", "asOfDate": "2026-11-02" },
    { "rail": "FED_NOW", "eligibility": "UNKNOWN", "asOfDate": "2026-11-03" }
  ]
}
```

`UNKNOWN` isn't a refusal. Tesouro sends the payment and the receiving network decides. When a rail's list isn't available, that rail's entry has no `asOfDate`.

## What the answer does not promise

Each answer comes from the rail's participant list, as of the business date in `asOfDate`. Tesouro loads the RTP and FedNow lists every business day. That makes the answer:

* About the bank, not the account. A bank that is `ELIGIBLE` can still reject a credit to a particular account.
* As of a list date, not live. A change in a bank's participation shows up only once a newer list loads.
* Not a promise that the payment posts. An `ELIGIBLE` bank can still decline or fail to post a payment after Tesouro accepts it.

Look the routing number up close to the send rather than caching the answer for long.

## When a send is refused

An RTP or FedNow send to a bank whose answer for that rail is `NOT_ELIGIBLE` fails with `422 Unprocessable Entity` and isn't sent. The body names the rail, the list date, and the rails the bank can receive on:

```json title="Example Response" lines theme={null}
{
  "status": 422,
  "errorCode": "INSTANT_PAYMENT_RECIPIENT_NOT_ELIGIBLE",
  "detail": "The recipient's bank cannot receive FED_NOW payments as of 2026-11-03.",
  "rail": "FED_NOW",
  "asOfDate": "2026-11-03",
  "availableRails": ["RTP"]
}
```

Retry on a rail from `availableRails`, with a new `idempotencyKey`. An empty `availableRails` means no rail is `ELIGIBLE`, not that every rail refuses: a rail the lookup answers `UNKNOWN` still sends. When the lookup answers `NOT_ELIGIBLE` on both rails, send by [ACH](https://docs.tesouro.com/embedded-banking/guides/money-movement/ach.md) instead.

## Sandbox

Sandbox callers get answers from the same live participant lists, and their sends are refused the same way. There are no test routing numbers that force an answer. To exercise a `NOT_ELIGIBLE` path, look up a real routing number the lists place on one rail only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.