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

# Request a payment

> Collect money from anyone with a payment link that Natural delivers for you

Ask anyone for money and let Natural deliver the payment link. For the request lifecycle, read the [Payment requests overview](/guides/concepts/payment-requests).

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

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

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

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

## Request the payment

Create the request with [`POST /payment-requests`](/api-reference/paymentrequests/create-payment-request). Address the `payer` by email, phone, party ID (`pty_*`), agent ID (`agt_*`), or [handle](/guides/agents/handles), the same set you use for a payment counterparty. Handles, party IDs, and agent IDs must already exist on Natural. `description` is at most 80 characters and `payerName` at most 32.

<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()),
  )

  request = agent_client.payment_requests.create(
      amount=2500,
      currency="USD",
      description="Invoice 7",
      payer_name="Ada Lovelace",
      payer={"type": "email", "value": "ada@example.com"},
      idempotency_key=str(uuid.uuid4()),
  )
  ```

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

  // NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  const client = new Natural();
  const request = await client.paymentRequests.create(
    {
      amount: 2500,
      currency: "USD",
      description: "Invoice 7",
      payerName: "Ada Lovelace",
      payer: { type: "email", value: "ada@example.com" },
      idempotencyKey: crypto.randomUUID(),
    },
    {
      instanceId: crypto.randomUUID(),
    },
  );
  ```

  ```bash CLI theme={null}
  # NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
  natural payment-requests create \
    --amount 2500 \
    --currency USD \
    --description "Invoice 7" \
    --payer-name "Ada Lovelace" \
    --params '{"payer": {"type": "email", "value": "ada@example.com"}}' \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Using my Procurement Agent, request $25 from ada@example.com for Invoice 7.
  ```

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

The response carries the request `id` (`prq_*`) and the `paymentLinkUrl`. Natural delivers the request for you: the payment link by email or text message for a payer new to Natural, a dashboard link for a payer on Natural, and the `payment_request.incoming` webhook for an agent.

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

## Track it

Check status any time with [`GET /payment-requests/{paymentRequestId}`](/api-reference/paymentrequests/get-payment-request). A request is `OPEN` until the payer acts. It moves to `PROCESSING` while their payment is in flight, then `COMPLETED`. It ends at `DECLINED`, `CANCELED`, `EXPIRED`, `FAILED`, or `RETURNED`.

<CodeGroup>
  ```python Python theme={null}
  request = client.payment_requests.get(request.data.id)
  ```

  ```typescript TypeScript theme={null}
  const status = await client.paymentRequests.get({
    paymentRequestId: request.data.id,
  });
  ```

  ```bash CLI theme={null}
  natural payment-requests get --payment-request-id prq_019cd1798d7a68fe07c972bed48fb7fd
  ```

  ```text MCP theme={null}
  What's the status of that payment request?
  ```

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

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

## Cancel it

Cancel an `OPEN` request with [`POST /payment-requests/{paymentRequestId}/cancel`](/api-reference/paymentrequests/cancel-payment-request) to void its payment link and move it to `CANCELED`. A request that is already `PROCESSING` or terminal returns 409. Once the payer fulfills a request, the resulting payment settles like any other. An agent key must send `X-Instance-ID` here too.

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

  canceled = client.payment_requests.cancel(
      request.data.id,
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  const canceled = await client.paymentRequests.cancel({
    paymentRequestId: request.data.id,
    idempotencyKey: crypto.randomUUID(),
  });
  ```

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

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

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

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


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