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

# Move money for a customer

> Pay and request on a customer's behalf

Pay and request from a customer's wallet by setting one field, `customerPartyId`. For the connection model, read the [Customers overview](/guides/concepts/customers).

Use `customerPartyId` in query parameters for reads and in `data.attributes` for payment and transfer mutations. Omit it to use your own party where the endpoint permits omission. Cancellation accepts an optional `data.attributes.customerPartyId`; it also works without a body for your own party.

<Note>
  On transaction lists, transaction summaries, and home metrics, `customerPartyId` only filters
  activity you can already access. It does not switch you into the customer's context or expand
  access. Transaction detail reads check your authority to act for the selected customer.
</Note>

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

<Note>
  Every action here needs the customer to have [connected their
  agent](/guides/connect/invite-customer).
</Note>

## Find the customer's party ID

Find a customer's `customerPartyId` by listing your customers with [`GET /customers`](/api-reference/customers/list-customers). Each customer's `id` is the party ID (`pty_*`) you pass.

<CodeGroup>
  ```python Python theme={null}
  customers = client.customers.list()
  for customer in customers.data:
      print(customer.id, customer.attributes.name)
  ```

  ```typescript TypeScript theme={null}
  const customers = await client.customers.list();
  for (const customer of customers.data) {
    console.log(customer.id, customer.attributes.name);
  }
  ```

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

  ```text MCP theme={null}
  List my active customers and their party IDs.
  ```

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

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

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

## Pay from the customer's wallet

Set `customerPartyId` on [`POST /payments`](/api-reference/payments/create-payment) to the customer's party ID and the payment draws from the agent's default wallet for that customer connection, within the permissions and limits they granted. Acceptance establishes that default; the customer can later add wallets or change it. Pass `walletId` to choose another wallet the customer has granted. Everything else works like [Send a payment](/guides/payments/send-payment): the same counterparty types, the same claim link for new recipients, the same status flow. Omit `customerPartyId` and the payment comes from your own wallet instead.

<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": "party_id", "value": "pty_019cd1798d681091fcf1dc98afb72d01"},
      customer_party_id="pty_019cd1798d627ad9bc302511c4f2c115",
      description="Q4 2025 development work",
      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 payment = await client.payments.create(
    {
      amount: 50_000,
      currency: "USD",
      counterparty: { type: "party_id", value: "pty_019cd1798d681091fcf1dc98afb72d01" },
      customerPartyId: "pty_019cd1798d627ad9bc302511c4f2c115",
      description: "Q4 2025 development work",
      idempotencyKey: crypto.randomUUID(),
    },
    {
      instanceId: crypto.randomUUID(),
    },
  );
  ```

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

  ```text MCP theme={null}
  Using my Procurement Agent, pay @ada-lovelace $500 from Bistro Roma's wallet 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": "party_id", "value": "pty_019cd1798d681091fcf1dc98afb72d01" },
          "customerPartyId": "pty_019cd1798d627ad9bc302511c4f2c115",
          "description": "Q4 2025 development work"
        }
      }
    }'
  ```
</CodeGroup>

The response carries the payment (`pay_*`) and its initial `status`, and its `sender` is the customer's party, confirming the funds came from their wallet:

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

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

## Request into the customer's wallet

Collecting for a customer is [Request a payment](/guides/payments/request-payment) with the same one field. Set `customerPartyId` on [`POST /payment-requests`](/api-reference/paymentrequests/create-payment-request) to the customer's party and the funds land in **their** default wallet, or the customer wallet you name in `walletId`, when the payer settles. Natural delivers the request to the payer automatically, on whatever channel matches how you addressed them.

<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"},
      customer_party_id="pty_019cd1798d627ad9bc302511c4f2c115",
      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" },
      customerPartyId: "pty_019cd1798d627ad9bc302511c4f2c115",
      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"}}' \
    --customer-party-id pty_019cd1798d627ad9bc302511c4f2c115 \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Using my Procurement Agent, request $25 from @ada-lovelace for Invoice 7 and collect it into Bistro Roma's wallet.
  ```

  ```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" },
          "customerPartyId": "pty_019cd1798d627ad9bc302511c4f2c115"
        }
      }
    }'
  ```
</CodeGroup>

The response carries the request (`prq_*`) with `requesterParty` set to the customer, so when the payer settles the money lands in the customer's default wallet, not yours:

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

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


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