> ## 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.

# Create realtime payment

> Create a realtime payment to an external party account



## OpenAPI

````yaml /api-reference/openapi.json post /realtime
openapi: 3.1.1
info:
  title: Natural API
  version: 0.2.0
  description: >-
    Natural's payments API for autonomous agents.


    **Base URL:** `https://api.natural.com`


    AI agents, including coding agents, should prefer the hosted MCP server at
    `https://mcp.natural.com` when an MCP-aware host runs the agent, the Natural
    CLI for terminal/CI workflows, and the official SDKs for application
    runtimes they own. Use direct HTTP only for explicit low-level integrations,
    unsupported SDK gaps, or infrastructure work where REST is required.


    For support: support@natural.com
servers:
  - url: https://api.natural.com
    description: Production
security: []
tags:
  - name: Agents
    description: Agent management
  - name: Customers
    description: Customer management
  - name: Invitation Links
    description: Shareable links that offer your agents to customers
  - name: Payments
    description: Payment management
  - name: Transactions
    description: Transaction activity and history
  - name: Transfers
    description: Deposits and withdrawals
  - name: PaymentRequests
    description: Payment request management
  - name: Approvals
    description: Approval review
  - name: Invitations
    description: Party invitation management
  - name: Parties
    description: Party and organization management
  - name: Wallets
    description: Wallet management
  - name: External Accounts
    description: Linked external bank accounts
  - name: External Parties
    description: Third parties with whom you transact over Direct
  - name: External Party Accounts
    description: Banking details belonging to external parties not on Natural
  - name: ACH
    description: Make ACH payments to external party accounts
  - name: Realtime
    description: Make realtime payments to external party accounts
  - name: Wire
    description: Send domestic wires to external party accounts
  - name: API Keys
    description: API key management
  - name: Agent Keys
    description: Agent key management
  - name: Webhooks
    description: Webhook endpoint management
  - name: Events
    description: Webhook event log
  - name: Simulations
    description: Sandbox-only simulation controls
paths:
  /realtime:
    post:
      tags:
        - Realtime
      summary: Create realtime payment
      description: Create a realtime payment to an external party account
      operationId: realtime.create
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            maxLength: 255
          description: >-
            Unique key for safely retrying a request without creating
            duplicates.
        - name: X-Instance-ID
          in: header
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 1024
              - type: 'null'
          description: >-
            Caller-chosen identifier for the agent run, session, or
            conversation, required when an agent moves money.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      type: object
                      properties:
                        customerPartyId:
                          type: string
                          pattern: ^pty_[0-9a-f]{32}$
                          description: >-
                            Customer party ID (pty_*). Omit to create for your
                            own party; provide for delegated creation.
                        amount:
                          type: integer
                          exclusiveMinimum: 0
                          description: Integer amount in the minor units of currency.
                        currency:
                          enum:
                            - USD
                          type: string
                          default: USD
                        walletId:
                          type: string
                          pattern: ^wal_[0-9a-f]{32}$
                        externalPartyAccountId:
                          type: string
                          pattern: ^epa_[0-9a-f]{32}$
                        description:
                          type: string
                          minLength: 1
                          maxLength: 140
                          pattern: ^[A-Za-z0-9 /?:().,'+-]+$
                          description: >-
                            Payment description delivered to the recipient bank.
                            Maximum 140 characters from the ISO 20022 character
                            set (letters, digits, spaces, and / - ? : ( ) . , '
                            +).
                      required:
                        - amount
                        - externalPartyAccountId
                        - description
                      additionalProperties: false
                      title: RealtimeCreateAttributes
                  required:
                    - attributes
                  additionalProperties: false
              required:
                - data
              additionalProperties: false
              title: RealtimeCreateRequest
            examples:
              default:
                summary: Default
                value:
                  data:
                    attributes:
                      amount: 25000
                      currency: USD
                      externalPartyAccountId: epa_550e8400e29b41d4a716446655440000
                      description: Invoice 1042 settlement
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - realtime
                      id:
                        type: string
                        pattern: ^rt_[0-9a-f]{32}$
                      attributes:
                        type: object
                        properties:
                          amount:
                            type: integer
                            exclusiveMinimum: 0
                            description: Integer amount in the minor units of currency.
                          currency:
                            enum:
                              - USD
                            type: string
                          status:
                            enum:
                              - CREATED
                              - AWAITING_APPROVAL
                              - APPROVAL_DENIED
                              - PROCESSING
                              - SETTLED
                              - FAILED
                              - CANCELED
                            type: string
                          description:
                            type: string
                            description: >-
                              Payment description delivered to the recipient
                              bank.
                          failure:
                            anyOf:
                              - type: object
                                properties:
                                  reason:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                  code:
                                    anyOf:
                                      - type: string
                                      - type: 'null'
                                required:
                                  - reason
                                  - code
                                additionalProperties: false
                              - type: 'null'
                          submittedAt:
                            anyOf:
                              - type: string
                              - type: 'null'
                          settledAt:
                            anyOf:
                              - type: string
                              - type: 'null'
                            description: >-
                              When the transfer settled. Settled realtime
                              transfers are irrevocable; there is no return
                              state.
                          terminalAt:
                            anyOf:
                              - type: string
                              - type: 'null'
                          createdAt:
                            type: string
                          updatedAt:
                            type: string
                        required:
                          - amount
                          - currency
                          - status
                          - description
                          - failure
                          - submittedAt
                          - settledAt
                          - terminalAt
                          - createdAt
                          - updatedAt
                        additionalProperties: false
                        title: RealtimeAttributes
                      relationships:
                        type: object
                        properties:
                          customerParty:
                            type: object
                            properties:
                              data:
                                type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                      - party
                                  id:
                                    type: string
                                    pattern: ^pty_[0-9a-f]{32}$
                                required:
                                  - type
                                  - id
                                additionalProperties: false
                                title: ResourceIdentifier
                                description: Related resource identifier.
                            required:
                              - data
                            additionalProperties: false
                            title: ToOneRelationship
                          wallet:
                            type: object
                            properties:
                              data:
                                type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                      - wallet
                                  id:
                                    type: string
                                    pattern: ^wal_[0-9a-f]{32}$
                                required:
                                  - type
                                  - id
                                additionalProperties: false
                                title: ResourceIdentifier
                                description: Related resource identifier.
                            required:
                              - data
                            additionalProperties: false
                            title: ToOneRelationship
                          externalParty:
                            type: object
                            properties:
                              data:
                                type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                      - external_party
                                  id:
                                    type: string
                                    pattern: ^epty_[0-9a-f]{32}$
                                required:
                                  - type
                                  - id
                                additionalProperties: false
                                title: ResourceIdentifier
                                description: Related resource identifier.
                            required:
                              - data
                            additionalProperties: false
                            title: ToOneRelationship
                          externalPartyAccount:
                            type: object
                            properties:
                              data:
                                type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                      - external_party_account
                                  id:
                                    type: string
                                    pattern: ^epa_[0-9a-f]{32}$
                                required:
                                  - type
                                  - id
                                additionalProperties: false
                                title: ResourceIdentifier
                                description: Related resource identifier.
                            required:
                              - data
                            additionalProperties: false
                            title: ToOneRelationship
                        required:
                          - customerParty
                          - wallet
                          - externalParty
                          - externalPartyAccount
                        additionalProperties: false
                        title: RealtimeRelationships
                    required:
                      - type
                      - id
                      - attributes
                      - relationships
                    additionalProperties: false
                    title: RealtimeResource
                required:
                  - data
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    data:
                      type: realtime
                      id: rt_550e8400e29b41d4a716446655440000
                      attributes:
                        amount: 25000
                        currency: USD
                        status: PROCESSING
                        description: Invoice 1042 settlement
                        failure: null
                        submittedAt: '2026-09-03T15:30:00Z'
                        settledAt: null
                        terminalAt: null
                        createdAt: '2026-09-03T15:30:00Z'
                        updatedAt: '2026-09-03T15:30:00Z'
                      relationships:
                        customerParty:
                          data:
                            type: party
                            id: pty_7c9e6679e29b41d4a716446655440001
                        wallet:
                          data:
                            type: wallet
                            id: wal_550e8400e29b41d4a716446655440000
                        externalParty:
                          data:
                            type: external_party
                            id: epty_550e8400e29b41d4a716446655440000
                        externalPartyAccount:
                          data:
                            type: external_party_account
                            id: epa_550e8400e29b41d4a716446655440000
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed per window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp when rate limit resets.
              schema:
                type: integer
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Stable lower-snake-case public error code.
                        detail:
                          type: string
                          description: Safe user-facing error detail.
                        status:
                          type: string
                          description: HTTP status code as a string.
                        source:
                          type: object
                          description: Location of the invalid request value.
                          properties:
                            pointer:
                              type: string
                              description: JSON Pointer to the invalid request value.
                            parameter:
                              type: string
                              description: Name of the invalid query parameter.
                            header:
                              type: string
                              description: Name of the invalid request header.
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Additional error context, including support and
                            provider details when available.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting.
                            limitScope:
                              type: string
                              enum:
                                - merchant
                                - program
                              description: >-
                                Which family of acquiring limit refused the
                                payment. Thresholds and usage are never
                                disclosed.
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking.
                            provider:
                              type: object
                              description: Provider error details, when available.
                              properties:
                                name:
                                  type: string
                                  enum:
                                    - plaid
                                  description: Provider that returned the underlying error.
                                errorCode:
                                  type: string
                                  description: Provider error code, when available.
                                errorType:
                                  type: string
                                  description: Provider error type, when available.
                                requestId:
                                  type: string
                                  description: Provider request ID for troubleshooting.
                              required:
                                - name
                              additionalProperties: false
                          required:
                            - supportId
                          additionalProperties: false
                      required:
                        - code
                        - detail
                        - status
                        - meta
                      additionalProperties: false
                required:
                  - errors
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    errors:
                      - code: invalid_value
                        detail: >-
                          The information you entered isn't valid. Please check
                          it and try again.
                        status: '400'
                        meta:
                          supportId: req_a1b2c3d4e5f6
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Stable lower-snake-case public error code.
                        detail:
                          type: string
                          description: Safe user-facing error detail.
                        status:
                          type: string
                          description: HTTP status code as a string.
                        source:
                          type: object
                          description: Location of the invalid request value.
                          properties:
                            pointer:
                              type: string
                              description: JSON Pointer to the invalid request value.
                            parameter:
                              type: string
                              description: Name of the invalid query parameter.
                            header:
                              type: string
                              description: Name of the invalid request header.
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Additional error context, including support and
                            provider details when available.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting.
                            limitScope:
                              type: string
                              enum:
                                - merchant
                                - program
                              description: >-
                                Which family of acquiring limit refused the
                                payment. Thresholds and usage are never
                                disclosed.
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking.
                            provider:
                              type: object
                              description: Provider error details, when available.
                              properties:
                                name:
                                  type: string
                                  enum:
                                    - plaid
                                  description: Provider that returned the underlying error.
                                errorCode:
                                  type: string
                                  description: Provider error code, when available.
                                errorType:
                                  type: string
                                  description: Provider error type, when available.
                                requestId:
                                  type: string
                                  description: Provider request ID for troubleshooting.
                              required:
                                - name
                              additionalProperties: false
                          required:
                            - supportId
                          additionalProperties: false
                      required:
                        - code
                        - detail
                        - status
                        - meta
                      additionalProperties: false
                required:
                  - errors
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    errors:
                      - code: unauthenticated
                        detail: Authentication is required.
                        status: '401'
                        meta:
                          supportId: req_a1b2c3d4e5f6
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Stable lower-snake-case public error code.
                        detail:
                          type: string
                          description: Safe user-facing error detail.
                        status:
                          type: string
                          description: HTTP status code as a string.
                        source:
                          type: object
                          description: Location of the invalid request value.
                          properties:
                            pointer:
                              type: string
                              description: JSON Pointer to the invalid request value.
                            parameter:
                              type: string
                              description: Name of the invalid query parameter.
                            header:
                              type: string
                              description: Name of the invalid request header.
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Additional error context, including support and
                            provider details when available.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting.
                            limitScope:
                              type: string
                              enum:
                                - merchant
                                - program
                              description: >-
                                Which family of acquiring limit refused the
                                payment. Thresholds and usage are never
                                disclosed.
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking.
                            provider:
                              type: object
                              description: Provider error details, when available.
                              properties:
                                name:
                                  type: string
                                  enum:
                                    - plaid
                                  description: Provider that returned the underlying error.
                                errorCode:
                                  type: string
                                  description: Provider error code, when available.
                                errorType:
                                  type: string
                                  description: Provider error type, when available.
                                requestId:
                                  type: string
                                  description: Provider request ID for troubleshooting.
                              required:
                                - name
                              additionalProperties: false
                          required:
                            - supportId
                          additionalProperties: false
                      required:
                        - code
                        - detail
                        - status
                        - meta
                      additionalProperties: false
                required:
                  - errors
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    errors:
                      - code: forbidden
                        detail: You do not have permission to perform this action.
                        status: '403'
                        meta:
                          supportId: req_a1b2c3d4e5f6
        '404':
          description: >-
            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.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Stable lower-snake-case public error code.
                        detail:
                          type: string
                          description: Safe user-facing error detail.
                        status:
                          type: string
                          description: HTTP status code as a string.
                        source:
                          type: object
                          description: Location of the invalid request value.
                          properties:
                            pointer:
                              type: string
                              description: JSON Pointer to the invalid request value.
                            parameter:
                              type: string
                              description: Name of the invalid query parameter.
                            header:
                              type: string
                              description: Name of the invalid request header.
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Additional error context, including support and
                            provider details when available.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting.
                            limitScope:
                              type: string
                              enum:
                                - merchant
                                - program
                              description: >-
                                Which family of acquiring limit refused the
                                payment. Thresholds and usage are never
                                disclosed.
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking.
                            provider:
                              type: object
                              description: Provider error details, when available.
                              properties:
                                name:
                                  type: string
                                  enum:
                                    - plaid
                                  description: Provider that returned the underlying error.
                                errorCode:
                                  type: string
                                  description: Provider error code, when available.
                                errorType:
                                  type: string
                                  description: Provider error type, when available.
                                requestId:
                                  type: string
                                  description: Provider request ID for troubleshooting.
                              required:
                                - name
                              additionalProperties: false
                          required:
                            - supportId
                          additionalProperties: false
                      required:
                        - code
                        - detail
                        - status
                        - meta
                      additionalProperties: false
                required:
                  - errors
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    errors:
                      - code: not_found
                        detail: The requested resource was not found.
                        status: '404'
                        meta:
                          supportId: req_a1b2c3d4e5f6
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Stable lower-snake-case public error code.
                        detail:
                          type: string
                          description: Safe user-facing error detail.
                        status:
                          type: string
                          description: HTTP status code as a string.
                        source:
                          type: object
                          description: Location of the invalid request value.
                          properties:
                            pointer:
                              type: string
                              description: JSON Pointer to the invalid request value.
                            parameter:
                              type: string
                              description: Name of the invalid query parameter.
                            header:
                              type: string
                              description: Name of the invalid request header.
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Additional error context, including support and
                            provider details when available.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting.
                            limitScope:
                              type: string
                              enum:
                                - merchant
                                - program
                              description: >-
                                Which family of acquiring limit refused the
                                payment. Thresholds and usage are never
                                disclosed.
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking.
                            provider:
                              type: object
                              description: Provider error details, when available.
                              properties:
                                name:
                                  type: string
                                  enum:
                                    - plaid
                                  description: Provider that returned the underlying error.
                                errorCode:
                                  type: string
                                  description: Provider error code, when available.
                                errorType:
                                  type: string
                                  description: Provider error type, when available.
                                requestId:
                                  type: string
                                  description: Provider request ID for troubleshooting.
                              required:
                                - name
                              additionalProperties: false
                          required:
                            - supportId
                          additionalProperties: false
                      required:
                        - code
                        - detail
                        - status
                        - meta
                      additionalProperties: false
                required:
                  - errors
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    errors:
                      - code: conflict
                        detail: The request conflicts with the current resource state.
                        status: '409'
                        meta:
                          supportId: req_a1b2c3d4e5f6
        '422':
          description: >-
            Validation Error. The response contains one error object for each
            invalid request value.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Stable lower-snake-case public error code.
                        detail:
                          type: string
                          description: Safe user-facing error detail.
                        status:
                          type: string
                          description: HTTP status code as a string.
                        source:
                          type: object
                          description: Location of the invalid request value.
                          properties:
                            pointer:
                              type: string
                              description: JSON Pointer to the invalid request value.
                            parameter:
                              type: string
                              description: Name of the invalid query parameter.
                            header:
                              type: string
                              description: Name of the invalid request header.
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Additional error context, including support and
                            provider details when available.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting.
                            limitScope:
                              type: string
                              enum:
                                - merchant
                                - program
                              description: >-
                                Which family of acquiring limit refused the
                                payment. Thresholds and usage are never
                                disclosed.
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking.
                            provider:
                              type: object
                              description: Provider error details, when available.
                              properties:
                                name:
                                  type: string
                                  enum:
                                    - plaid
                                  description: Provider that returned the underlying error.
                                errorCode:
                                  type: string
                                  description: Provider error code, when available.
                                errorType:
                                  type: string
                                  description: Provider error type, when available.
                                requestId:
                                  type: string
                                  description: Provider request ID for troubleshooting.
                              required:
                                - name
                              additionalProperties: false
                          required:
                            - supportId
                          additionalProperties: false
                      required:
                        - code
                        - detail
                        - status
                        - meta
                      additionalProperties: false
                required:
                  - errors
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    errors:
                      - code: invalid_value
                        detail: 'Too big: expected string to have <=80 characters'
                        status: '422'
                        source:
                          pointer: /data/attributes/description
                        meta:
                          supportId: req_a1b2c3d4e5f6
        '428':
          description: Precondition Required
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Stable lower-snake-case public error code.
                        detail:
                          type: string
                          description: Safe user-facing error detail.
                        status:
                          type: string
                          description: HTTP status code as a string.
                        source:
                          type: object
                          description: Location of the invalid request value.
                          properties:
                            pointer:
                              type: string
                              description: JSON Pointer to the invalid request value.
                            parameter:
                              type: string
                              description: Name of the invalid query parameter.
                            header:
                              type: string
                              description: Name of the invalid request header.
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Additional error context, including support and
                            provider details when available.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting.
                            limitScope:
                              type: string
                              enum:
                                - merchant
                                - program
                              description: >-
                                Which family of acquiring limit refused the
                                payment. Thresholds and usage are never
                                disclosed.
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking.
                            provider:
                              type: object
                              description: Provider error details, when available.
                              properties:
                                name:
                                  type: string
                                  enum:
                                    - plaid
                                  description: Provider that returned the underlying error.
                                errorCode:
                                  type: string
                                  description: Provider error code, when available.
                                errorType:
                                  type: string
                                  description: Provider error type, when available.
                                requestId:
                                  type: string
                                  description: Provider request ID for troubleshooting.
                              required:
                                - name
                              additionalProperties: false
                          required:
                            - supportId
                          additionalProperties: false
                      required:
                        - code
                        - detail
                        - status
                        - meta
                      additionalProperties: false
                required:
                  - errors
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    errors:
                      - code: mfa_required
                        detail: MFA verification required
                        status: '428'
                        meta:
                          supportId: req_a1b2c3d4e5f6
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Stable lower-snake-case public error code.
                        detail:
                          type: string
                          description: Safe user-facing error detail.
                        status:
                          type: string
                          description: HTTP status code as a string.
                        source:
                          type: object
                          description: Location of the invalid request value.
                          properties:
                            pointer:
                              type: string
                              description: JSON Pointer to the invalid request value.
                            parameter:
                              type: string
                              description: Name of the invalid query parameter.
                            header:
                              type: string
                              description: Name of the invalid request header.
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Additional error context, including support and
                            provider details when available.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting.
                            limitScope:
                              type: string
                              enum:
                                - merchant
                                - program
                              description: >-
                                Which family of acquiring limit refused the
                                payment. Thresholds and usage are never
                                disclosed.
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking.
                            provider:
                              type: object
                              description: Provider error details, when available.
                              properties:
                                name:
                                  type: string
                                  enum:
                                    - plaid
                                  description: Provider that returned the underlying error.
                                errorCode:
                                  type: string
                                  description: Provider error code, when available.
                                errorType:
                                  type: string
                                  description: Provider error type, when available.
                                requestId:
                                  type: string
                                  description: Provider request ID for troubleshooting.
                              required:
                                - name
                              additionalProperties: false
                          required:
                            - supportId
                          additionalProperties: false
                      required:
                        - code
                        - detail
                        - status
                        - meta
                      additionalProperties: false
                required:
                  - errors
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    errors:
                      - code: rate_limited
                        detail: Too many requests. Please try again later.
                        status: '429'
                        meta:
                          supportId: req_a1b2c3d4e5f6
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Maximum requests allowed per window.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp when rate limit resets.
              schema:
                type: integer
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Stable lower-snake-case public error code.
                        detail:
                          type: string
                          description: Safe user-facing error detail.
                        status:
                          type: string
                          description: HTTP status code as a string.
                        source:
                          type: object
                          description: Location of the invalid request value.
                          properties:
                            pointer:
                              type: string
                              description: JSON Pointer to the invalid request value.
                            parameter:
                              type: string
                              description: Name of the invalid query parameter.
                            header:
                              type: string
                              description: Name of the invalid request header.
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Additional error context, including support and
                            provider details when available.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting.
                            limitScope:
                              type: string
                              enum:
                                - merchant
                                - program
                              description: >-
                                Which family of acquiring limit refused the
                                payment. Thresholds and usage are never
                                disclosed.
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking.
                            provider:
                              type: object
                              description: Provider error details, when available.
                              properties:
                                name:
                                  type: string
                                  enum:
                                    - plaid
                                  description: Provider that returned the underlying error.
                                errorCode:
                                  type: string
                                  description: Provider error code, when available.
                                errorType:
                                  type: string
                                  description: Provider error type, when available.
                                requestId:
                                  type: string
                                  description: Provider request ID for troubleshooting.
                              required:
                                - name
                              additionalProperties: false
                          required:
                            - supportId
                          additionalProperties: false
                      required:
                        - code
                        - detail
                        - status
                        - meta
                      additionalProperties: false
                required:
                  - errors
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    errors:
                      - code: server_error
                        detail: Something went wrong.
                        status: '500'
                        meta:
                          supportId: req_a1b2c3d4e5f6
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Stable lower-snake-case public error code.
                        detail:
                          type: string
                          description: Safe user-facing error detail.
                        status:
                          type: string
                          description: HTTP status code as a string.
                        source:
                          type: object
                          description: Location of the invalid request value.
                          properties:
                            pointer:
                              type: string
                              description: JSON Pointer to the invalid request value.
                            parameter:
                              type: string
                              description: Name of the invalid query parameter.
                            header:
                              type: string
                              description: Name of the invalid request header.
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Additional error context, including support and
                            provider details when available.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting.
                            limitScope:
                              type: string
                              enum:
                                - merchant
                                - program
                              description: >-
                                Which family of acquiring limit refused the
                                payment. Thresholds and usage are never
                                disclosed.
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking.
                            provider:
                              type: object
                              description: Provider error details, when available.
                              properties:
                                name:
                                  type: string
                                  enum:
                                    - plaid
                                  description: Provider that returned the underlying error.
                                errorCode:
                                  type: string
                                  description: Provider error code, when available.
                                errorType:
                                  type: string
                                  description: Provider error type, when available.
                                requestId:
                                  type: string
                                  description: Provider request ID for troubleshooting.
                              required:
                                - name
                              additionalProperties: false
                          required:
                            - supportId
                          additionalProperties: false
                      required:
                        - code
                        - detail
                        - status
                        - meta
                      additionalProperties: false
                required:
                  - errors
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    errors:
                      - code: not_implemented
                        detail: This operation is not available.
                        status: '501'
                        meta:
                          supportId: req_a1b2c3d4e5f6
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Stable lower-snake-case public error code.
                        detail:
                          type: string
                          description: Safe user-facing error detail.
                        status:
                          type: string
                          description: HTTP status code as a string.
                        source:
                          type: object
                          description: Location of the invalid request value.
                          properties:
                            pointer:
                              type: string
                              description: JSON Pointer to the invalid request value.
                            parameter:
                              type: string
                              description: Name of the invalid query parameter.
                            header:
                              type: string
                              description: Name of the invalid request header.
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Additional error context, including support and
                            provider details when available.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting.
                            limitScope:
                              type: string
                              enum:
                                - merchant
                                - program
                              description: >-
                                Which family of acquiring limit refused the
                                payment. Thresholds and usage are never
                                disclosed.
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking.
                            provider:
                              type: object
                              description: Provider error details, when available.
                              properties:
                                name:
                                  type: string
                                  enum:
                                    - plaid
                                  description: Provider that returned the underlying error.
                                errorCode:
                                  type: string
                                  description: Provider error code, when available.
                                errorType:
                                  type: string
                                  description: Provider error type, when available.
                                requestId:
                                  type: string
                                  description: Provider request ID for troubleshooting.
                              required:
                                - name
                              additionalProperties: false
                          required:
                            - supportId
                          additionalProperties: false
                      required:
                        - code
                        - detail
                        - status
                        - meta
                      additionalProperties: false
                required:
                  - errors
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    errors:
                      - code: bad_gateway
                        detail: >-
                          We couldn't complete that request because one of
                          Natural's services returned an unexpected response.
                          Please try again.
                        status: '502'
                        meta:
                          supportId: req_a1b2c3d4e5f6
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    minItems: 1
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Stable lower-snake-case public error code.
                        detail:
                          type: string
                          description: Safe user-facing error detail.
                        status:
                          type: string
                          description: HTTP status code as a string.
                        source:
                          type: object
                          description: Location of the invalid request value.
                          properties:
                            pointer:
                              type: string
                              description: JSON Pointer to the invalid request value.
                            parameter:
                              type: string
                              description: Name of the invalid query parameter.
                            header:
                              type: string
                              description: Name of the invalid request header.
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Additional error context, including support and
                            provider details when available.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting.
                            limitScope:
                              type: string
                              enum:
                                - merchant
                                - program
                              description: >-
                                Which family of acquiring limit refused the
                                payment. Thresholds and usage are never
                                disclosed.
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking.
                            provider:
                              type: object
                              description: Provider error details, when available.
                              properties:
                                name:
                                  type: string
                                  enum:
                                    - plaid
                                  description: Provider that returned the underlying error.
                                errorCode:
                                  type: string
                                  description: Provider error code, when available.
                                errorType:
                                  type: string
                                  description: Provider error type, when available.
                                requestId:
                                  type: string
                                  description: Provider request ID for troubleshooting.
                              required:
                                - name
                              additionalProperties: false
                          required:
                            - supportId
                          additionalProperties: false
                      required:
                        - code
                        - detail
                        - status
                        - meta
                      additionalProperties: false
                required:
                  - errors
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    errors:
                      - code: service_unavailable
                        detail: The service is temporarily unavailable.
                        status: '503'
                        meta:
                          supportId: req_a1b2c3d4e5f6
      security:
        - HTTPBearer: []
components:
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication: send your API key, agent key, or OAuth access
        token as `Authorization: Bearer <credential>`.

````