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 withPOST /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.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.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 catalogTo move money from a customer’s wallet instead of your own, see Move money for a
customer.