Move money for a customer

Pay and request from a customer’s wallet by setting one field, customerPartyId. For the connection model, read the Customers overview. 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.

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.

Every action here needs the customer to have connected their agent.

Find the customer’s party ID

Find a customer’s customerPartyId by listing your customers with GET /customers. Each customer’s id is the party ID (pty_*) you pass.

customers = client.customers.list()
for customer in customers.data:
    print(customer.id, customer.attributes.name)

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

natural customers list

List my active customers and their party IDs.

curl https://api.natural.com/customers \
  -H "Authorization: Bearer $NATURAL_API_KEY"

Pay from the customer’s wallet

Set customerPartyId on POST /payments 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: 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.

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

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

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

Using my Procurement Agent, pay @ada-lovelace $500 from Bistro Roma's wallet for Q4 development work.

# 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"
      }
    }
  }'

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:

Request into the customer’s wallet

Collecting for a customer is Request a payment with the same one field. Set customerPartyId on POST /payment-requests 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.

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

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

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

Using my Procurement Agent, request $25 from @ada-lovelace for Invoice 7 and collect it into Bistro Roma's wallet.

# 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"
      }
    }
  }'

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:

Overview

Common use cases

Products

Guides

Move money for a customer

Find the customer’s party ID

Pay from the customer’s wallet

Request into the customer’s wallet

​Find the customer’s party ID

​Pay from the customer’s wallet

​Request into the customer’s wallet

Find the customer’s party ID

Pay from the customer’s wallet

Request into the customer’s wallet