Skip to main content
Follow a payment (pay_*) you sent through its lifecycle, list every money movement on your account, and cancel a payment the recipient has not yet claimed. To follow a payment request you created, read the request itself, as on Request a payment. For the lifecycle, see the Payment 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.

Get one payment

Look up a payment with GET /payments/{paymentId} to read its current status.
The response carries the payment’s status, amount, and the parties on each side:
Amounts are integer US cents: 50000 is $500.00.
A healthy payment moves CREATED to PROCESSING to COMPLETED. It can pause at PENDING_CLAIM while it waits for a new recipient to claim the funds, or at IN_REVIEW while it is held for review. It ends at FAILED, RETURNED, CANCELED, or APPROVAL_DENIED.

List all money movement

GET /transactions returns every transaction (txn_*) on your account: payments, transfers (deposits, withdrawals, internal), and refunds, newest first.
To read the transactions your agent ran for a customer, add the customerPartyId query param. It returns delegated activity only.
Webhooks: payment.*, deposit.*, withdrawal.*. Event catalog

Cancel a payment

Cancel a payment with POST /payments/{paymentId}/cancel while it is still PENDING_CLAIM. Once the recipient claims it, cancel returns 409. Canceling an already canceled payment returns it unchanged. To resend a claim, cancel the payment and send a new one.
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 payment moves to CANCELED and no funds leave your wallet:
Only a PENDING_CLAIM payment can be canceled, and only until the recipient claims it. Direct payments and payments held at IN_REVIEW cannot be canceled here.