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 withPOST /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.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 withGET /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 anOPEN 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