---
title: "Create realtime payment"
method: POST
path: "/realtime"
tags: ["Realtime"]
---

# Create realtime payment

`POST /realtime`

Create a realtime payment to an external party account

## Headers

- `Idempotency-Key` string, required
- `X-Instance-ID` string, nullable

## Request body

- object
  - `data` object, required
    - `attributes` object, required
      - `customerPartyId` string — Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf.
      - `amount` integer, required — Amount in cents.
      - `currency` 'USD' — Currency code. Defaults to USD.
      - `walletId` string — Wallet (wal_*) to pay from. Omit to use the party default for user or party API calls, or the agent default for the current customer connection when acting through a connected agent. Owned agents use their own agent default.
      - `externalPartyAccountId` string, required — External party account (epa_*) to pay.
      - `description` string, required — Payment description delivered to the recipient bank with the payment. Maximum 140 characters from the ISO 20022 character set (letters, digits, spaces, and / - ? : ( ) . , ' +).
      - `internalDescription` string — Description for your internal reference. Never shared with the counterparty or the banking network. Maximum 255 characters.

## Response `201`

Successful Response

- object
  - `data` object, required
    - `type` 'realtime', required — Resource type. Always `realtime`.
    - `id` string, required — Realtime payment ID (rt_*).
    - `attributes` object, required
      - `amount` integer, required — Amount in cents.
      - `currency` 'USD', required — Currency code.
      - `fee` object, nullable, required — Fee added to your cost as the sender. Null when no fee applies, the payment failed, was denied, or was canceled, the fee was voided, or your party is not the fee payer.
        - `amount` integer, required — Fee amount in cents.
        - `currency` 'USD', required — Currency of the fee.
        - `payer` 'sender', required — Party role charged the fee.
        - `applied` 'on_top', required — The fee is added to the sender's cost without reducing the principal amount.
      - `status` 'CREATED' | 'AWAITING_APPROVAL' | 'APPROVAL_DENIED' | 'PROCESSING' | 'SETTLED' | 'FAILED' | 'CANCELED', required — Realtime payment status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, SETTLED; APPROVAL_DENIED, FAILED, or CANCELED end it.
      - `description` string, required — Payment description delivered to the recipient bank.
      - `internalDescription` string, nullable, required — Description for your internal reference, or null. Never shared with the counterparty or the banking network.
      - `failure` object, nullable, required — Failure details when the payment failed, or null.
        - `reason` string, nullable, required — Failure reason, or null.
        - `code` string, nullable, required — Failure code, or null.
      - `submittedAt` string, nullable, required — RFC 3339 timestamp when the payment was submitted to the network, or null.
      - `settledAt` string, nullable, required — RFC 3339 timestamp when the payment settled, or null. Settled realtime payments cannot be returned.
      - `terminalAt` string, nullable, required — RFC 3339 timestamp when the payment reached a terminal status, or null.
      - `createdAt` string, required — RFC 3339 timestamp when the realtime payment was created.
      - `updatedAt` string, required — RFC 3339 timestamp when the realtime payment was last updated.
    - `relationships` object, required
      - `customerParty` object, required — Party the payment was created for.
        - `data` object, required — Related resource identifier.
          - `type` 'party', required — Resource type. Always `party`.
          - `id` string, required
      - `wallet` object, required — Wallet the payment pays from.
        - `data` object, required — Related resource identifier.
          - `type` 'wallet', required — Resource type. Always `wallet`.
          - `id` string, required
      - `externalParty` object, required — External party paid.
        - `data` object, required — Related resource identifier.
          - `type` 'external_party', required — Resource type. Always `external_party`.
          - `id` string, required
      - `externalPartyAccount` object, required — External party account paid.
        - `data` object, required — Related resource identifier.
          - `type` 'external_party_account', required — Resource type. Always `external_party_account`.
          - `id` string, required

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409` — Conflict
- `422` — Validation Error. The response contains one error object for each invalid request value.
- `428` — Precondition Required
- `429` — Too Many Requests
- `500` — Internal Server Error
- `501` — Not Implemented
- `502` — Bad Gateway
- `503` — Service Unavailable

## Changes

- **2026-09-24** `e79d669f0234` — 2 info
  - added the new optional request property `data/attributes/internalDescription`
  - added the required property `data/attributes/internalDescription` to the response with the `201` status
- **2026-09-23** `bcf3b028c3e5` — 1 info
  - added the required property `data/attributes/fee` to the response with the `201` status
- **2026-09-04** `3d0bfe344af2` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/natural/apis/natural-api/changes/realtime/post.md)

---

[API](https://skmtc.dev/natural/apis/natural-api.md) · [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc.dev/natural/apis/natural-api/revisions/acc8f2f3d25e?raw)