---
title: "Fulfill payment request"
method: POST
path: "/payment-requests/{paymentRequestId}/fulfill"
tags: ["PaymentRequests"]
---

# Fulfill payment request

`POST /payment-requests/{paymentRequestId}/fulfill`

Fulfill an open payment request from a wallet or a verified linked bank account

## Path parameters

- `paymentRequestId` string, required — Payment request ID (prq_*).

## Headers

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

## Request body

- object
  - `partyId` 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.
  - `data` object, required
    - `attributes` object, required
      - `paymentSource` union, required — Source of funds for the payment.
        - object
          - `type` 'wallet', required
          - `walletId` string — Wallet (wal_*) to pay from. Defaults to your default wallet, or the wallet granted to the agent.
        - object
          - `type` 'external_account', required
          - `externalAccountId` string, required — Verified linked bank account (eac_*) to pay from.
      - `tags` object — Key-value metadata stored on the resource. At most 30 keys; keys 1-128 characters, alphanumeric and underscores; values 1-256 characters. Visible to anyone who can read the resource; do not include sensitive data.

## Response `200`

Successful Response

- object
  - `data` object, required
    - `type` 'payment', required — Resource type. Always `payment`.
    - `id` string, required — Payment ID (pay_*).
    - `attributes` object, required
      - `amount` integer, required — Amount in cents.
      - `currency` string, required — Currency code.
      - `status` 'CREATED' | 'PROCESSING' | 'PENDING_CLAIM' | 'IN_REVIEW' | 'COMPLETED' | 'FAILED' | 'RETURNED' | 'APPROVAL_DENIED' | 'CANCELED', required — Payment status.
      - `description` string, nullable, required — Payment description.
      - `tags` object, required — Metadata visible to anyone who can read the resource.
      - `createdAt` string, required — RFC 3339 timestamp when this payment was created.
      - `updatedAt` string, nullable, required — RFC 3339 timestamp when this payment was last updated, or null.
    - `relationships` object, required
      - `sender` object, required — Party that initiated the payment, when the sender is on Natural.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'party', required — Resource type. Always `party`.
          - `id` string, required
      - `senderAgent` object, required — Sending agent, or null when the payment was not sent by an agent.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'agent', required — Resource type. Always `agent`.
          - `id` string, required
      - `recipient` object, required — Recipient party for this payment, when known.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'party', required — Resource type. Always `party`.
          - `id` string, required
      - `recipientAgent` object, required — Recipient agent, or null unless addressed by agent ID or agent handle.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'agent', required — Resource type. Always `agent`.
          - `id` string, required
      - `transaction` object, required — Sender-side transaction for this payment, when available.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'transaction', required — Resource type. Always `transaction`.
          - `id` string, required
      - `paymentRequest` object, required — Payment request that produced this payment, when applicable.
        - `data` object, nullable, required — Related resource identifier.
          - `type` 'paymentRequest', required — Resource type. Always `paymentRequest`.
          - `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-14** `a7210001d0d4` — 1 breaking, 1 info
  - removed `subschema #1, subschema #2` from the `data/attributes/paymentSource` request property `anyOf` list
  - added `subschema #1, subschema #2` to the `data/attributes/paymentSource` request property `anyOf` list
- **2026-09-02** `c7c12da5915f` — 12 info
  - added the optional property `errors/items/meta/limitScope` to the response with the `400` status
  - added the optional property `errors/items/meta/limitScope` to the response with the `401` status
  - added the optional property `errors/items/meta/limitScope` to the response with the `403` status
  - added the optional property `errors/items/meta/limitScope` to the response with the `404` status
  - …8 more
- **2026-08-27** `359d267dca88` — 1 info
  - deleted the `header` request parameter `X-Agent-ID` with deprecation
- **2026-08-23** `b1ad79e918ac` — 1 info
  - `header` request parameter `X-Agent-ID` was deprecated
- **2026-08-13** `ba1fb54c5939` — 2 info
  - added the new optional request property `data/attributes/tags`
  - added the required property `data/attributes/tags` to the response with the `200` status

[Full history](https://skmtc.dev/natural/apis/natural-api/changes/payment-requests/:paymentRequestId/fulfill/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/1132c9ddb7bd?raw)