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

# Send a payment

> Pay anyone by email, phone, party ID, agent ID, or @handle

Address the recipient by email, phone, party ID (`pty_*`), agent ID (`agt_*`), or [handle](/guides/agents/handles) and Natural sends the payment (`pay_*`). If an email or phone recipient is new to Natural, Natural sends a claim link and onboards them when they claim the funds. Handles, party IDs, and agent IDs must already exist. For the payment lifecycle, read the [Payments overview](/guides/concepts/payments).

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

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

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

## Send the payment

Send it with [`POST /payments`](/api-reference/payments/create-payment). `description` is at most 80 characters.

<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.payments.create(
      amount=50_000,
      currency="USD",
      counterparty={"type": "email", "value": "ada@example.com"},
      description="Q4 development work",
      idempotency_key=str(uuid.uuid4()),
  )
  print(payment.data.id)
  ```

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

  // NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  const client = new Natural();
  const payment = await client.payments.create(
    {
      amount: 50_000,
      currency: "USD",
      counterparty: { type: "email", value: "ada@example.com" },
      description: "Q4 development work",
      idempotencyKey: crypto.randomUUID(),
    },
    {
      instanceId: crypto.randomUUID(),
    },
  );
  console.log(payment.data.id);
  ```

  ```bash CLI theme={null}
  # NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  natural payments create \
    --amount 50000 \
    --currency USD \
    --params '{"counterparty": {"type": "email", "value": "ada@example.com"}}' \
    --description "Q4 development work" \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Using my Procurement Agent, pay ada@example.com $500 for Q4 development work.
  ```

  ```bash cURL theme={null}
  # NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  curl -X POST https://api.natural.com/payments \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "X-Instance-ID: $(uuidgen)" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "amount": 50000,
          "currency": "USD",
          "counterparty": { "type": "email", "value": "ada@example.com" },
          "description": "Q4 development work"
        }
      }
    }'
  ```
</CodeGroup>

The response carries the payment `id` (`pay_*`) and its initial `status`:

<Snippet file="api-examples/payments.create.response.mdx" />

<Note>
  A recipient who is not on Natural yet comes back as `PENDING_CLAIM`. Natural emails or texts them
  a claim link and moves the money once they onboard and claim it. The response also carries
  `claimLink`, returned only here; anyone holding it can claim the funds, so store it as a secret.
</Note>

A payment held for approval starts at `IN_REVIEW`. The payment draws from the sending party's default wallet. Pass `walletId` (`wal_*`) to spend from a specific wallet instead; an agent with access to more than one wallet must pass it.

Once sent, [track the payment](/guides/payments/track-payment) to follow it from `PROCESSING` to `COMPLETED`, or cancel a `PENDING_CLAIM` payment before the recipient claims it.

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

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


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