Skip to main content
Return part or all of a successful card payment to the card that paid. 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.
Amounts are integer US cents: 50000 is $500.00.
Refunding for a customer? Pass their party ID as customerPartyId on each call. Your agent needs permission to act on their behalf.

Create the refund

Create a refund with either paymentIntentId or cardPaymentId, not both. Set amount for a partial refund. Omit it to refund the remaining amount.
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 includes the refund ID and its status.

Watch the refund

Get the refund to check its status, or subscribe to refund.succeeded and refund.failed webhooks.
A finished refund has status succeeded or failed. If it fails, check failure for the reason.

List refunds

List refunds to review recent activity. Filter by paymentIntentId or cardPaymentId to see refunds for one payment.

Handle a refused refund

  • Another refund is pending: wait for it to finish before requesting another.
  • The amount is too high: request no more than the remaining refundable amount.
  • Insufficient funds: add funds to your wallet, then retry.
  • A chargeback blocks the refund: review the dispute before proceeding.
See Refund errors for the full list of codes and causes.