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

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

# Overview

> Request, accept, and reconcile payment from another party

A payment request (`prq_*`) is a request for another party to send you funds. [Payments](/guides/concepts/payments) move money out of your wallet; payment requests bring money in. You identify the payer by email, phone number, handle, or party or agent ID. Natural notifies the payer: a payment link by email or SMS for payers new to Natural, a dashboard link for payers on Natural, and the `payment_request.incoming` webhook event for agents. Once they fulfill the request, Natural deposits the funds into your wallet.

Create one with [`POST /payment-requests`](/api-reference/paymentrequests/create-payment-request). See [Request a payment](/guides/payments/request-payment) and [Fulfill or decline a payment request](/guides/payments/fulfill-or-decline-request).

## Lifecycle

A request starts `OPEN`, moves to `PROCESSING` while the payer's fulfillment is in flight, and ends `COMPLETED`. It also ends `FAILED`, `RETURNED`, `CANCELED` when you cancel, `DECLINED` when the payer declines, or `EXPIRED`. `payerCanPay` and `payerCanDecline` on the response say whether the payer can still act. Fulfillment is the moment money moves, from the payer's wallet or a verified linked bank account, and the movement lands in [Transactions](/guides/concepts/transactions).

Requests you've been asked to pay appear in a separate incoming list, apart from the requests you created.

## How a payer pays

A payer on Natural fulfills from a wallet or a verified linked bank account. A payer new to Natural pushes funds from their bank to the account number on the payment link. That account number is reserved for the request, so the bank push reconciles to it automatically.

## Requesting for a customer

An agent authorized by a customer can create requests that collect into the customer's wallet. The request belongs to the customer; your agent acts as the operator.

## Best practices

<AccordionGroup>
  <Accordion title="Clear payer and amount">
    Always give a full payer identifier (email, phone number, handle, or party or agent ID) so Natural can deliver the request. Specify amounts as integer cents (e.g. `2500` for \$25.00). Amounts are in USD.
  </Accordion>

  <Accordion title="Include descriptive messages">
    Write a clear description so the payer knows who is asking and what they're paying for. Include
    the invoice number and what it covers (e.g., "Invoice #12345 - Raw materials for Q1 2026"). The
    description is shown to the payer, and good detail also helps Natural detect anomalous
    transactions. Descriptions are at most 80 characters.
  </Accordion>

  <Accordion title="Follow up on open requests">
    A request stays `OPEN` until the payer fulfills or declines it, or you cancel. If a payer hasn't acted, follow up with them, and cancel requests that are no longer valid so their payment links stop working.
  </Accordion>
</AccordionGroup>


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