Refunds return funds to the payer on-chain. Call POST /payments/refund with a settlement payment id or deposit session id: Videpay routes to PaymentSettlement.refund, escrow refundToBuyer, or deposit-address refund as needed. Subscribe to payment.refunded and you are done.
Need machine-readable request/response bodies for your AI or codebase? Download this page as plain Markdown.
A customer pays 25 USDC via deposit session. After payment.settled (deposit_sweep), they cancel. You call POST /payments/refund with that settlement (or deposit session) id. USDC returns to the payer and payment.refunded updates your CRM.
Pass the settlement payment id or deposit session id. Supported settlement flows include direct, relayed_intent, relayed_batch, deposit_sweep, virtual_wallet_sweep, subscription_charge, donation_sweep, and escrow_lock. Inbound acknowledgements do not move refundable funds.
Full refunds only (ERC-20)
The amount field is optional but the backend currently accepts only full gross refunds for ERC-20 payments. Partial refunds and native asset refunds are not supported in this flow. Omit amount to refund the full gross amount.
| Field | Type | Required | Description |
|---|---|---|---|
id | uuid | Yes | Settlement payment id or deposit session id. Videpay routes the refund automatically. |
businessId | uuid | No | Target business. Omit when your API key is scoped to one business. |
chain | string | No | Chain scope for settlement APIs (base, polygon, etc.). Required for wallet direct/intent prepare. Sandbox resolves to testnets automatically. |
amount | decimal string | No | Refund amount. Omit for a full refund. Backend currently accepts only full gross refunds for ERC-20 payments. |
authorization | object | No | Dashboard only. Step-up confirmation (PIN, OTP, or 2FA) when a logged-in owner acts in the browser. Omit entirely for secret API key integrations: the server skips this check when you authenticate with x-api-key. On sandbox, any emailed OTP code is `000000` (six zeroes). It's giving dev mode. Live sends a real code. |
authorization.pin | string | No | Transaction PIN when enabled. |
authorization.otpChallengeId | uuid | No | OTP challenge from a prior dashboard auth step. On sandbox, enter `000000` when verifying the emailed code. |
authorization.twoFactorCode | string | No | TOTP code when 2FA is enabled. |
/payments/refundUnified refund. Routes by id to settlement, escrow, or deposit refund. Requires secret API key.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{02 "id": "pst_4a8f2c1d9e7b6a3f5c2d8e1b0a9f7c6d"03}These endpoints call the same unified refund router. Prefer POST /payments/refund for new integrations.
Active deposit sessions
If the session is still AWAITING_PAYMENT, PARTIALLY_FUNDED, or FULLY_FUNDED, wait for settlement or session expiry before a deposit-address refund is available.
| Field | Type | Required | Description |
|---|---|---|---|
businessId | uuid | No | Target business. Omit when your API key is scoped to one business. |
chain | string | No | Chain scope for settlement APIs (base, polygon, etc.). Required for wallet direct/intent prepare. Sandbox resolves to testnets automatically. |
amount | decimal string | No | Optional full-refund amount override (ERC-20 gross only). |
/payments/settlements/pst_4a8f2c1d9e7b6a3f5c2d8e1b0a9f7c6d/refundAlias for settlement payment ids. Same body fields as /payments/refund except id comes from the path.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{}/payments/deposit-sessions/ds_8e4f1a2b-3c5d-4e6f-7a8b-9c0d1e2f3a4b/refundAlias for deposit session ids. Routes to settlement refund when settled, or deposit-address refund when eligible.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/json01{}Low-level refund of funds still held in the deposit contract. Prefer the unified refund endpoint; use refund-all only for admin tooling.
| Field | Type | Required | Description |
|---|---|---|---|
businessId | uuid | No | Target business. Omit when your API key is scoped to one business. |
chain | string | No | Chain scope for settlement APIs (base, polygon, etc.). Required for wallet direct/intent prepare. Sandbox resolves to testnets automatically. |
/payments/deposit-sessions/ds_8e4f1a2b-3c5d-4e6f-7a8b-9c0d1e2f3a4b/refund-allQueue refund of all tokens in the deposit address to refundAddress. Requires secret API key.
01x-api-key: sk_AbCdEfGhIj_XyZ1234567890abcdefghijklmnopqrstuvwxyz01234502Content-Type: application/jsonListen to payment.refunded for every successful refund that updates a settlement payment, including deposit sweeps, subscription charges, donation sweeps, and escrow locks returned to the buyer. Deposit-address-only refunds (pre-sweep) may also emit deposit.updated while the session moves to REFUNDED.
| Field | Type | Required | Description |
|---|---|---|---|
payment.refunded | event | No | Primary refund event. Payment status is refunded, refundTransaction is set, and amounts.refunded is populated. |
deposit.updated | event | No | Emitted when a deposit session changes during deposit-address refund processing. |
Register a webhook endpoint and verify the X-Protocol-Signature header on every delivery before fulfilling orders or updating your database.
payment.refundedSent when a settled payment is refunded to the payer.
01Content-Type: application/json02User-Agent: Protocol-Webhooks/1.003X-Protocol-Event: payment.refunded04X-Protocol-Delivery: wev_1a2b3c4d-5e6f-7890-abcd-ef123456789005X-Protocol-Business-Id: a1b2c3d4-e5f6-7890-abcd-ef123456789006X-Protocol-Attempt: 107X-Protocol-Signature: sha256=abc123def456...