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 eitherpaymentIntentId 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.Watch the refund
Get the refund to check its status, or subscribe torefund.succeeded and refund.failed webhooks.
succeeded or failed. If it fails, check failure for the reason.
List refunds
List refunds to review recent activity. Filter bypaymentIntentId 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.