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 withGET /payments/{paymentId} to read its current status.
status, amount, and the parties on each side:
Amounts are integer US cents:
50000 is $500.00.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.
customerPartyId query param. It returns delegated activity only.
Webhooks:
payment.*, deposit.*, withdrawal.*. Event catalogCancel a payment
Cancel a payment withPOST /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.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.