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 withGET /payment-requests/incoming.
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.pay_*), starting in PROCESSING, or IN_REVIEW when an approval policy holds it:
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