Skip to main content
Address the recipient by email, phone, party ID (pty_*), agent ID (agt_*), or handle and Natural sends the payment (pay_*). If an email or phone recipient is new to Natural, Natural sends a claim link and onboards them when they claim the funds. Handles, party IDs, and agent IDs must already exist. For the payment lifecycle, see the Payment object. Natural handles the orchestration, ledgering, routing, compliance, risk, fraud detection, and disputes, and scales with you from one transaction to one million. To pay someone who isn’t on Natural straight to their bank by ACH, realtime, or wire, see Pay over a specific rail. Before you start, connect Natural to your agent or create an API key. See Start here. Setup takes a couple of minutes; the MCP path needs no API key.
If an MCP host is operating Natural for you, use the MCP example. The linked API reference has per-language samples and a playground.
Amounts are integer US cents: 50000 is $500.00.

Send the payment

Send it with POST /payments. description is at most 80 characters.
When an agent (agt_*) creates, cancels, fulfills, or declines a payment, payment request, transfer, payment intent, refund, or voice session, it authenticates with its own credential (an agent key or an agent-scoped OAuth grant) and names the run with the X-Instance-ID header. Without it the call returns 400 missingInstanceId. Reads don’t need it.
The response carries the payment id (pay_*) and its initial status:
A recipient who is not on Natural yet comes back as PENDING_CLAIM. Natural emails or texts them a claim link and moves the money once they onboard and claim it. The response also carries claimLink, returned only here; anyone holding it can claim the funds, so store it as a secret.
A payment held for approval starts at IN_REVIEW. The payment draws from the sending party’s default wallet. Pass walletId (wal_*) to spend from a specific wallet instead; an agent with access to more than one wallet must pass it. Once sent, track the payment to follow it from PROCESSING to COMPLETED, or cancel a PENDING_CLAIM payment before the recipient claims it.
Webhooks: payment.*. Event catalog
To move money from a customer’s wallet instead of your own, see Move money for a customer.