Skip to main content
Pay a request (prq_*) addressed to you from a wallet (wal_*) or linked bank account, or turn it down. 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.

See what’s waiting on you

List the requests addressed to you with GET /payment-requests/incoming.
Each item’s id (prq_*) is what you fulfill or decline below. payerCanPay: true means it’s still waiting on you.

Fulfill it

POST /payment-requests/{paymentRequestId}/fulfill pays the request and moves the money. The amount comes from the request itself. You choose only the source: set paymentSource to a wallet you own, { "type": "wallet", "walletId": "wal_..." } (omit walletId for your default), or to a verified linked bank account you own, { "type": "external_account", "externalAccountId": "eac_..." }. Bank-funded payments settle over ACH. A request accepts one attempt; retry with the same Idempotency-Key.
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.
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 resulting payment (pay_*), starting in PROCESSING, or IN_REVIEW when an approval policy holds it:
Track it to confirm it settles.

Decline it

POST /payment-requests/{paymentRequestId}/decline turns the request down. No money moves, the requester is notified, and the request’s status becomes DECLINED. Declining is final and cannot be undone. Only an OPEN request can be declined, and declining is not available on behalf of a customer. An agent key must send X-Instance-ID here too.
Webhooks: paymentRequest.*, payment.*. Event catalog