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

# Move money for a customer

> Pay and request on a customer's behalf.

Once a customer connects their agent to you, one field, `customerPartyId`, switches a payment or request from your money to theirs. Everything else works exactly like moving your own money.

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

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

Find a customer's `customerPartyId` by listing your customers. Each customer's `id` is the party id 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 **their** wallet, within the permissions and limits they 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

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

  payment = agent_client.payments.create(
      amount=500_000,
      currency="USD",
      counterparty={"type": "party_id", "value": "pty_019cd1798d627ad9bc302511c4f2c115"},
      customer_party_id="pty_019cd1798d617f65a79cb965dda9eac3",
      description="Q4 2025 development work",
      idempotency_key=str(uuid.uuid4()),
  )
  ```

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

  const client = new Natural();
  const payment = await client.payments.create(
    {
      amount: 500_000,
      currency: "USD",
      counterparty: { type: "party_id", value: "pty_019cd1798d627ad9bc302511c4f2c115" },
      customerPartyId: "pty_019cd1798d617f65a79cb965dda9eac3",
      description: "Q4 2025 development work",
      idempotencyKey: crypto.randomUUID(),
    },
    {
      xAgentId: "agt_019cd1798d637a4da75dce386343931d",
      xInstanceId: crypto.randomUUID(),
    },
  );
  ```

  ```bash CLI theme={null}
  natural payments create \
    --amount 500000 \
    --currency USD \
    --params '{"counterparty": {"type": "party_id", "value": "pty_019cd1798d627ad9bc302511c4f2c115"}}' \
    --customer-party-id pty_019cd1798d617f65a79cb965dda9eac3 \
    --description "Q4 2025 development work" \
    --x-agent-id agt_019cd1798d637a4da75dce386343931d \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Using my Procurement Agent, pay @natural-contractor $5,000 from customer@example.com's wallet for Q4 development work.
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/payments \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "X-Agent-ID: agt_019cd1798d637a4da75dce386343931d" \
    -H "X-Instance-ID: $(uuidgen)" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "amount": 500000,
          "currency": "USD",
          "counterparty": { "type": "party_id", "value": "pty_019cd1798d627ad9bc302511c4f2c115" },
          "customerPartyId": "pty_019cd1798d617f65a79cb965dda9eac3",
          "description": "Q4 2025 development work"
        }
      }
    }'
  ```
</CodeGroup>

The response carries a `pay_*` id and an initial `status`, and its `sender` is the customer's party, confirming the funds came from their wallet.

<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 receiving wallet 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

  agent_client = Natural(
      x_agent_id="agt_019cd1798d637a4da75dce386343931d",
      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"},
      customer_party_id="pty_019cd1798d617f65a79cb965dda9eac3",
      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" },
      customerPartyId: "pty_019cd1798d617f65a79cb965dda9eac3",
      idempotencyKey: crypto.randomUUID(),
    },
    {
      xAgentId: "agt_019cd1798d637a4da75dce386343931d",
      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"}}' \
    --customer-party-id pty_019cd1798d617f65a79cb965dda9eac3 \
    --x-agent-id agt_019cd1798d637a4da75dce386343931d \
    --x-instance-id "$(uuidgen)" \
    --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Using my Procurement Agent, request $25 from @natural-client for Invoice 7 and collect it into customer@example.com's wallet.
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/payment-requests \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "X-Agent-ID: agt_019cd1798d637a4da75dce386343931d" \
    -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" },
          "customerPartyId": "pty_019cd1798d617f65a79cb965dda9eac3"
        }
      }
    }'
  ```
</CodeGroup>

The response's `requesterParty` is the customer, and when the payer settles the money lands in the customer's default receiving wallet, not yours.

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