Refund a captured payment back to the payer's wallet
Returns captured money to the payer's wallet as a contra posting: the original transaction is never rewritten, so both movements stay in the history.
/v1/refundsReturns captured money to the payer's wallet as a contra posting: the original transaction is never rewritten, so both movements stay in the history. Partial refunds may repeat, and the cumulative refunded amount can never exceed what was captured (refund_exceeds_captured, 422). Requires refunds:write and an Idempotency-Key. Refuses payment_not_found (404), invalid_state (409) for a payment that was never captured, insufficient_funds (422) when the funding side cannot cover it, and idempotency_key_reuse (409) when the key comes back with a different body.
Authorization
bearerAuth A tenant API key (sk_{env}_{id}_{secret}), a wallet user token, or an IdP access token. Which principal the credential resolves to decides the scopes it carries; see the authentication guide.
In: header
Header Parameters
1 <= length <= 200Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
# Cumulative refunds can never exceed what was captured.curl -sS -X POST "$WALLETD_API/v1/refunds" \ -H "Authorization: Bearer $WALLETD_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: refund-order-4471-1" \ -d '{"payment_id": "'$PAYMENT_ID'", "amount": 950, "reason": "wrong item"}'{ "id": "0191c2db-03e6-7c24-b7d0-84a1f5920e6b", "payment_id": "0191c2da-7d55-7a80-9143-6be2f08c5d97", "amount": 950, "status": "completed", "reason": "wrong item", "created_at": "2026-09-20T10:04:27Z"}