Skip to main content
Ask anyone for money by email, phone, handle, party ID, or agent ID, and let Natural deliver the payment link. Natural handles the orchestration, ledgering, routing, compliance, risk, fraud detection, and disputes, and scales with you from one transaction to one million. For the request lifecycle, read the Payment Request object. 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.
To move money from a customer’s wallet instead of your own, see Move money for a customer.

Request the payment

Create the request with POST /payment-requests. Address the payer by email, phone, party ID (pty_*), agent ID (agt_*), or handle, the same set you use for a payment counterparty. Handles, party IDs, and agent IDs must already exist on Natural. description is at most 80 characters and payerName at most 32. To request into a customer’s wallet, see Move money for a customer.
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 request id (prq_*) and the paymentLinkUrl. Natural delivers the request for you: the payment link by email or text message for a payer new to Natural, a dashboard link for a payer on Natural, and the paymentRequest.incoming webhook for an agent. A payer new to Natural pays by bank transfer to the account number on the payment link, which is reserved for this request.

Track it

Check status any time with GET /payment-requests/{paymentRequestId}. A request is OPEN until the payer acts. It moves to PROCESSING while their payment is in flight, then COMPLETED. It ends at DECLINED, CANCELED, EXPIRED, FAILED, or RETURNED.

Cancel it

Cancel an OPEN or EXPIRED request, or a FAILED one whose payment was denied or canceled, with POST /payment-requests/{paymentRequestId}/cancel to void its payment link and move it to CANCELED. Any other request returns 409, except one already CANCELED, which comes back unchanged. Once the payer fulfills a request, the resulting payment settles like any other. An agent key must send X-Instance-ID here too.
Webhooks: paymentRequest.*. Event catalog