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

# Fulfill or decline a payment request

> Pay a request addressed to you from a wallet or bank account

Pay a request (`prq_*`) addressed to you from a wallet (`wal_*`) or linked bank account, or turn it down. For the request lifecycle, read the [Payment requests overview](/guides/concepts/payment-requests).

<Snippet file="shared/prerequisites.mdx" />

<Snippet file="shared/mcp-callout.mdx" />

## See what's waiting on you

List the requests addressed to you with [`GET /payment-requests/incoming`](/api-reference/paymentrequests/list-incoming-payment-requests).

<CodeGroup>
  ```python Python theme={null}
  from naturalpay import Natural

  client = Natural()
  requests = client.payment_requests.list_incoming()
  ```

  ```typescript TypeScript theme={null}
  import Natural from "@naturalpay/sdk";

  const client = new Natural();
  const requests = await client.paymentRequests.listIncoming();
  ```

  ```bash CLI theme={null}
  natural payment-requests list-incoming
  ```

  ```bash cURL theme={null}
  curl https://api.natural.com/payment-requests/incoming \
    -H "Authorization: Bearer $NATURAL_API_KEY"
  ```
</CodeGroup>

<Snippet file="api-examples/paymentRequests.listIncoming.response.mdx" />

Each item's `id` (`prq_*`) is what you fulfill or decline below. `payerCanPay: true` means it's still waiting on you.

## Fulfill it

[`POST /payment-requests/{paymentRequestId}/fulfill`](/api-reference/paymentrequests/fulfill-payment-request) pays the request and moves the money. The amount comes from the request itself. You choose only the source: set `paymentSource` to a wallet you own, `{ "type": "wallet", "walletId": "wal_..." }` (omit `walletId` for your default), or to a verified linked bank account you own, `{ "type": "external_account", "externalAccountId": "eac_..." }`. Bank-funded payments settle over ACH. A request accepts one attempt; retry with the same `Idempotency-Key`.

<Snippet file="shared/cents-note.mdx" />

<Snippet file="shared/on-behalf-callout.mdx" />

<Snippet file="shared/instance-id-note.mdx" />

<CodeGroup>
  ```python Python theme={null}
  import uuid
  from naturalpay import Natural

  # NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  agent_client = Natural(
      instance_id=str(uuid.uuid4()),
  )

  payment = agent_client.payment_requests.fulfill(
      "prq_019cd1798d7a68fe07c972bed48fb7fd",
      payment_source={"type": "wallet", "wallet_id": "wal_019cd1798d714ce765e0486a417c23dc"},
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  // NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  const payment = await client.paymentRequests.fulfill(
    {
      paymentRequestId: "prq_019cd1798d7a68fe07c972bed48fb7fd",
      paymentSource: { type: "wallet", walletId: "wal_019cd1798d714ce765e0486a417c23dc" },
      idempotencyKey: crypto.randomUUID(),
    },
    {
      instanceId: crypto.randomUUID(),
    },
  );
  ```

  ```bash CLI theme={null}
  # NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  natural payment-requests fulfill \
    --payment-request-id prq_019cd1798d7a68fe07c972bed48fb7fd \
    --json '{"paymentSource": {"type": "wallet", "walletId": "wal_019cd1798d714ce765e0486a417c23dc"}}' \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Fulfill payment request prq_019cd1798d7a68fe07c972bed48fb7fd from my main wallet.
  ```

  ```bash cURL theme={null}
  # NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  curl -X POST https://api.natural.com/payment-requests/prq_019cd1798d7a68fe07c972bed48fb7fd/fulfill \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "X-Instance-ID: $(uuidgen)" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "paymentSource": {
            "type": "wallet",
            "walletId": "wal_019cd1798d714ce765e0486a417c23dc"
          }
        }
      }
    }'
  ```
</CodeGroup>

The response carries the resulting payment (`pay_*`), starting in `PROCESSING`, or `IN_REVIEW` when an approval policy holds it:

<Snippet file="api-examples/paymentRequests.fulfill.response.mdx" />

[Track it](/guides/payments/track-payment) to confirm it settles.

## Decline it

[`POST /payment-requests/{paymentRequestId}/decline`](/api-reference/paymentrequests/decline-payment-request) turns the request down. No money moves, the requester is notified, and the request's `status` becomes `DECLINED`. Declining is final and cannot be undone. Only an `OPEN` request can be declined, and declining is not available on behalf of a customer. An agent key must send `X-Instance-ID` here too.

<CodeGroup>
  ```python Python theme={null}
  import uuid

  declined = client.payment_requests.decline(
      "prq_019cd1798d7a68fe07c972bed48fb7fd",
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  const declined = await client.paymentRequests.decline({
    paymentRequestId: "prq_019cd1798d7a68fe07c972bed48fb7fd",
    idempotencyKey: crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural payment-requests decline \
    --payment-request-id prq_019cd1798d7a68fe07c972bed48fb7fd \
    --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Decline payment request prq_019cd1798d7a68fe07c972bed48fb7fd.
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/payment-requests/prq_019cd1798d7a68fe07c972bed48fb7fd/decline \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)"
  ```
</CodeGroup>

<Snippet file="api-examples/paymentRequests.decline.response.mdx" />

<Snippet file="shared/webhook-payment-request-fulfill.mdx" />


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