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

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Overview

> Send realtime payments to external party accounts

<Note>
  Direct is in early access and subject to change. To request Direct access, contact [hi@natural.com](mailto:hi@natural.com).
</Note>

A realtime payment (`rt_*`) pushes money from a [Wallet](/guides/concepts/wallets) to an [External party account](/guides/concepts/external-parties#external-party-accounts) over RTP or FedNow.

| | |
| - | - |
| API | [Realtime endpoints](/api-reference/realtime/create-realtime-payment) · [Errors](/api-reference/errors/realtime) |
| Direction | Credit only (wallet → external account) |
| Currency | `USD` |
| Settlement | Typically seconds |
| Reversible | No — settled payments are irrevocable, and there is no `RETURNED` status |
| Headers | `Idempotency-Key` required on create and cancel; `X-Instance-ID` for [agent](/guides/concepts/agents) calls |
| Alternatives | [ACH](/guides/concepts/ach) for accounts that cannot receive realtime credits, or [Wire](/guides/concepts/wire) |

## Create

```json theme={null}
{
  "data": {
    "attributes": {
      "amount": 25000,
      "externalPartyAccountId": "epa_019cd1798d8e5a2f8ceb96020cc3991a",
      "description": "Invoice 1042 payout"
    }
  }
}
```

* `description` is delivered to the recipient's bank. It must be 1–140 characters from the ISO 20022 character set: letters, digits, spaces, and `/ - ? : ( ) . , ' +`.
* Not every bank account can receive realtime credits. The external party account's `supportedRails` is an advisory hint refreshed from the network. The authoritative check runs when you create the payment, and unreachable accounts are rejected there.
* A network rejection usually arrives within seconds and is terminal: the payment moves to `FAILED` with the network code in `failure.code`. Natural does not retry over another rail. To reach the account anyway, create an [ACH payment](/guides/concepts/ach).
* To send on behalf of a customer, pass `customerPartyId`. See [Move money for a customer](/guides/connect/move-money-for-customer).

## Lifecycle

| Status | Meaning | Terminal | Sets |
| - | - | - | - |
| `CREATED` | Accepted and waiting to be submitted | No | |
| `AWAITING_APPROVAL` | Held for [approval](/guides/concepts/approvals) after breaching a [limit](/guides/concepts/limits) | No | |
| `PROCESSING` | Submitted to the network | No | `submittedAt` |
| `SETTLED` | Settled by the receiving bank; irrevocable | Yes | `settledAt`, `terminalAt` |
| `APPROVAL_DENIED` | Approval was denied | Yes | `terminalAt` |
| `FAILED` | Rejected by the network or failed before submission; details in `failure` | Yes | `terminalAt` |
| `CANCELED` | Canceled through the API | Yes | `terminalAt` |

**Cancel** — A payment can be canceled while it is `CREATED` or `AWAITING_APPROVAL`. Once submission starts, cancel returns `400 realtime.not_cancellable`. Canceling emits no `realtime.*` event.

**Events** — Status changes emit `realtime.created`, `realtime.processing`, `realtime.settled`, and `realtime.failed`. Approval holds emit `approval.*` events instead. The fee is assessed when the payment is submitted, so it's always null on `realtime.created`. Read it from `realtime.processing`. Payloads are documented in the [event catalog](/api-reference/event-catalog).

**Sandbox** — Drive a test payment to a terminal state without waiting on the network: [settle](/api-reference/simulations/settle-realtime-payment) moves it to `SETTLED` and [fail](/api-reference/simulations/fail-realtime-payment) moves it to `FAILED`.


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