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

# Request a payment

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

<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, agent id, or [handle](/guides/agents/handles), the same set you use for a payment counterparty.

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

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

  agent_client = Natural(
      x_agent_id="agt_019cd17a4f2e7b9c8d6e5f4a3b2c1d0e",
      x_instance_id=str(uuid.uuid4()),
  )

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

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

  const client = new Natural();
  const request = await client.paymentRequests.create(
    {
      amount: 2500,
      currency: "USD",
      description: "Invoice 7",
      payerName: "Natural Client",
      payer: { type: "email", value: "client@example.com" },
      idempotencyKey: crypto.randomUUID(),
    },
    {
      xAgentId: "agt_019cd17a4f2e7b9c8d6e5f4a3b2c1d0e",
      xInstanceId: crypto.randomUUID(),
    },
  );
  ```

  ```bash CLI theme={null}
  natural payment-requests create \
    --amount 2500 \
    --currency USD \
    --description "Invoice 7" \
    --payer-name "Natural Client" \
    --params '{"payer": {"type": "email", "value": "client@example.com"}}' \
    --x-agent-id agt_019cd17a4f2e7b9c8d6e5f4a3b2c1d0e \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

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

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/payment-requests \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "X-Agent-ID: agt_019cd17a4f2e7b9c8d6e5f4a3b2c1d0e" \
    -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": "Natural Client",
          "payer": { "type": "email", "value": "client@example.com" }
        }
      }
    }'
  ```
</CodeGroup>

The response carries the request `id` (`prq_*`) and the `paymentLinkUrl`. Natural delivers the payment request over email or phone number.

<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 stays `OPEN` until the payer settles it.

<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_550e8400e29b41d4a716446655440000
  ```

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

  ```bash cURL theme={null}
  curl https://api.natural.com/payment-requests/prq_550e8400e29b41d4a716446655440000 \
    -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`. Once a payer fulfills one, it's money movement and settles normally.

<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_550e8400e29b41d4a716446655440000 \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/payment-requests/prq_550e8400e29b41d4a716446655440000/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" />