Refunds

Give a payment back, in full or in part, from your server.

One rule for every refund path: a secret key refunds when its app’s Refunds switch is on and an Admin has set the app’s refund limits per currency in the dashboard (with two-step verification); a restricted key needs the refunds write scope and refunds within its own limits. Every refund carries an Idempotency-Key, stays within the per-refund and per-day limits, never exceeds what was captured, and is audited. In the dashboard, Finance (or above) refunds.

Leave out amount for a full refund. reason is one of duplicate, fraudulent, customer_request, other.

Keys and scopes

A secret key with refund limits set, or a restricted key with the refunds write scope and its own limits.

Refund a payment

The SDKs send an Idempotency-Key for you; when you retry a refund yourself, pass the same key so it is never refunded twice.

typescript

const refund = await watenga.refunds.create('txn_...', { amount: '5.00', reason: 'customer_request' }, { idempotencyKey: 'refund-ORD-1001-1' });
// refund.status: pending, completed or failed

Webhook events

Event	When
`payment.refund.pending`	Sent to the provider; not final yet
`payment.refund.completed`	The money went back
`payment.refund.failed`	The provider refused it (nothing was taken from your balance)
`payment.capture.refunded`	The payment is now fully refunded

Each event carries the object in data.object; verify the signature first (Webhooks).

Test it

Use a test secret key (sk_test_…): it never moves money. Pay with the test cards and wallet numbers, and receive the webhooks on your machine with watenga listen --forward-to http://localhost:3000/webhooks (CLI).

Refund a test payment made with a test card; in test mode refunds complete at once.