Move money for a customer

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.

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

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

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

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

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

Using my Procurement Agent, pay @natural-contractor $5,000 from customer@example.com's wallet for Q4 development work.

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

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.

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

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

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

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

Using my Procurement Agent, request $25 from @natural-client for Invoice 7 and collect it into customer@example.com's wallet.

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

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

Overview

Common use cases

Products

Guides

Move money for a customer

Pay from the customer’s wallet

Request into the customer’s wallet

​Pay from the customer’s wallet

​Request into the customer’s wallet

Pay from the customer’s wallet

Request into the customer’s wallet