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

> Send and receive money via direct payments or payment claims

A payment (`pay_*`) moves money from your wallet to another party. Natural picks the route: a direct payment when the recipient is already on Natural, or a payment claim when they aren't. Either way, the recipient can withdraw the funds to their bank account via ACH. [Payment requests](/guides/concepts/payment-requests) are the inverse: they bring money in.

Create one with [`POST /payments`](/api-reference/payments/create-payment). See [Send a payment](/guides/payments/send-payment) and [Track a payment](/guides/payments/track-payment).

## Lifecycle

A healthy payment moves `CREATED` to `PROCESSING` to `COMPLETED`. It can pause at `PENDING_CLAIM` while it waits for a new recipient to claim the funds, or at `IN_REVIEW` during a compliance hold. It ends at `FAILED`, `RETURNED`, `APPROVAL_DENIED`, or `CANCELED`.

## Direct payment

Send a payment by naming the recipient with their email, phone number, [handle](/guides/agents/handles), or party or agent ID. If that party is already on Natural, the money moves straight from the sender's wallet to theirs. If not, Natural sends a payment claim instead.

## Payment claims

When the recipient isn't on Natural yet, Natural emails or texts them a claim link. They onboard, then claim the funds. Before they can withdraw, they must pass KYB/KYC under Natural's [compliance](/guides/overview/compliance) program.

A claim link stays valid until the recipient redeems it, the sender cancels the payment, or the payment ends in `FAILED` or `APPROVAL_DENIED`.

## Canceling a payment

Only a payment in `PENDING_CLAIM` can be canceled. Until the recipient starts claiming, canceling voids the claim link and the money stays in your wallet, the real-world equivalent of voiding a check nobody has cashed yet. It's also how you handle a stale claim: cancel the payment and reissue it. A payment held at `IN_REVIEW` resolves through [Approvals](/guides/controls/approvals) instead.

The window closes the moment the recipient begins claiming; after that, the funds are theirs to collect. A direct payment can't be canceled at all: the money lands in the recipient's wallet the moment you send it, so there's nothing in flight to take back.

## Best practices

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

  <Accordion title="Include descriptive messages">
    Write clear descriptions so recipients know who paid them and why. Include the invoice number and
    what it covers (e.g., "Invoice #12345 - Raw materials for Q1 2026"). These show up in the email
    and SMS copies and in the dashboard, and good detail also helps Natural detect anomalous
    transactions. Descriptions are at most 80 characters.
  </Accordion>

  <Accordion title="Follow up on unredeemed claims">
    If a recipient hasn't redeemed a claim, follow up with them or work with your customer on whether to reissue the payment with a fresh claim link.
  </Accordion>
</AccordionGroup>


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