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

Automatically receive payment from another agent, email, phone number, or Natural party ID. For new parties, Natural creates a hosted payment page, delivers the page by email or SMS, and the payer settles via ACH or card (coming soon).

<Info>
  If an AI assistant is operating Natural for you, use the **MCP** examples. Python, TypeScript,
  CLI, and cURL examples are for application developers building an integration.
</Info>

## 1. Set up Natural

### If you are using an AI assistant

Ask your assistant to load Natural's playbook and connect with OAuth:

```text theme={null}
Read https://www.natural.co/skill.md and set up Natural for me.
Connect my assistant to Natural with OAuth.
Then follow the Request a payment guide and help me collect a payment.
```

The assistant should configure Natural's hosted MCP server, start the browser OAuth flow, and tell
you when to approve the Natural authorization page. You still sign up at
[natural.co/signup](https://natural.co/signup) and complete verification yourself; the assistant
does not need an API key for the primary MCP path.

### If you are building an integration

Sign up at [natural.co/signup](https://natural.co/signup), complete verification, then create a
developer API key in the dashboard. The key is shown once; store it in a secret manager and never
commit it.

```bash theme={null}
export NATURAL_API_KEY=sk_ntl_prod_abc123...
```

Install the SDK or CLI for the surface you are building with:

<CodeGroup>
  ```bash Python theme={null}
  pip install naturalpay
  ```

  ```bash TypeScript theme={null}
  npm install @naturalpay/sdk
  ```

  ```bash CLI theme={null}
  curl -fsSL https://natural.co/install.sh | bash
  ```
</CodeGroup>

No SDK for your language? Use the REST examples with the same API key.

After setup, use the MCP examples for an OAuth-connected AI assistant, or use the SDK, CLI, and
cURL examples when you are building an integration.

## 2. Create an agent

Agents execute transactions. Create one in the **Agents** tab of the dashboard, or:

<CodeGroup>
  ```text MCP theme={null}
  Create an agent called "Invoicing Agent" for collecting invoice payments.
  ```

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

  client = Natural()  # reads NATURAL_API_KEY

  agent = client.agents.create(
      name="Invoicing Agent",
      description="Collects invoice payments",
      idempotency_key=str(uuid.uuid4()),
  )
  ```

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

  const client = new Natural(); // reads NATURAL_API_KEY

  const agent = await client.agents.create({
    name: "Invoicing Agent",
    description: "Collects invoice payments",
    "Idempotency-Key": crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural agents create --name "Invoicing Agent" --description "Collects invoice payments" --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.co/agents \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "name": "Invoicing Agent",
          "description": "Collects invoice payments"
        }
      }
    }'
  ```
</CodeGroup>

The response includes the agent's `id` (`agt_*`) — store it.

## 3. Review your wallet

Every request lands in a wallet. By default, `POST /payment-requests` uses the requester party's default wallet, so you usually do not need to pass `walletId`. `GET /wallets` returns your wallets when you need to inspect the receiving wallet or choose a specific one later.

<CodeGroup>
  ```text MCP theme={null}
  Show my wallets.
  ```

  ```python Python theme={null}
  wallets = client.wallet.list()
  ```

  ```typescript TypeScript theme={null}
  const wallets = await client.wallet.list();
  ```

  ```bash CLI theme={null}
  natural wallet list
  ```

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

## 4. Create the request

`POST /payment-requests` creates the request and notifies the payer directly. The channel is determined by the payer kind — email payers get an email with the pay link, phone payers get an SMS, on-platform party payers get a dashboard deep-link to their primary contact, and agent payers receive only the in-app `payment_request.incoming` webhook. Callers have no knob to override or suppress.

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

  ```python Python theme={null}
  request = client.payment_requests.create(
      amount=2500,
      currency="USD",
      description="Invoice 7",
      payer_name="Ada Lovelace",
      payer={"type": "email", "value": "ada@example.com"},
      x_agent_id=agent.data.id,
      x_instance_id=str(uuid.uuid4()),
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  const request = await client.paymentRequests.create({
    amount: 2500,
    currency: "USD",
    description: "Invoice 7",
    payerName: "Ada Lovelace",
    payer: { type: "email", value: "ada@example.com" },
    "X-Agent-ID": agent.data.id,
    "X-Instance-ID": crypto.randomUUID(),
    "Idempotency-Key": crypto.randomUUID(),
  });
  ```

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

  ```bash cURL theme={null}
  curl -X POST https://api.natural.co/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": "Ada Lovelace",
          "payer": { "type": "email", "value": "ada@example.com" }
        }
      }
    }'
  ```
</CodeGroup>

The response includes the request's `id` (`prq_*`) and `paymentLinkUrl`. Natural has already delivered that link to email and phone payers.

## 5. Track the request

Poll for status with the `id` from step 4:

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

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

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

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

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

## Requesting on behalf of a customer

To collect into a *customer's* wallet, the customer first delegates payment authority (`payments.create`) to your agent. Invite them:

<CodeGroup>
  ```text MCP theme={null}
  Invite bruce@propertymanagement.com to my Invoicing Agent.
  ```

  ```python Python theme={null}
  customer = client.agents.create_customer(
      agent.data.id,
      recipients=[{"type": "email", "value": "bruce@propertymanagement.com"}],
      permissions=["payments.create"],
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  const customer = await client.agents.createCustomer(agent.data.id, {
    recipients: [{ type: "email", value: "bruce@propertymanagement.com" }],
    permissions: ["payments.create"],
    "Idempotency-Key": crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural agents create-customer \
    --agent-id agt_019cd17a4f2e7b9c8d6e5f4a3b2c1d0e \
    --recipient '{type: email, value: bruce@propertymanagement.com}' \
    --permission payments.create \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.co/agents/agt_019cd17a4f2e7b9c8d6e5f4a3b2c1d0e/customers \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "recipients": [{ "type": "email", "value": "bruce@propertymanagement.com" }],
          "permissions": ["payments.create"]
        }
      }
    }'
  ```
</CodeGroup>

The customer gets an email, completes onboarding, and approves the agent-customer relationship. After that, pass their party ID as `customerPartyId` on the request. Natural uses their default receiving wallet, so the funds land in their wallet instead of yours.

Find a customer's `customerPartyId` via `GET /customers` — each customer resource's `id` is the party ID. Omit `customerPartyId` to collect into your own wallet.