Skip to main content
Refund a completed transaction (charge or capture) either fully or partially. Refunds are processed through the same provider that handled the original transaction.

​
Method signature

async refund(request: RefundRequest): Promise<RefundResult>

​
Parameters

​
body.transactionId
string
required
The transaction ID of the original charge or capture to refund.
​
body.amount
number
Partial refund amount in smallest currency unit. Omit to refund the full transaction amount.
​
body.reason
string
Human-readable reason for the refund, forwarded to the payment provider.
​
body.idempotencyKey
string
Unique key to prevent duplicate refunds when retrying the same request.

​
Returns

​
RefundResult
object
Normalized refund result containing refund details and status.

​
Error handling

The refund() method may throw the following errors:
Thrown when an idempotency key is reused with different request data.
Thrown when the provider for the original transaction cannot be found.
The provider may return errors such as:
  • Transaction not found
  • Transaction not refundable (e.g., already fully refunded)
  • Refund amount exceeds original transaction amount
  • Refund window expired

​
Example

// Charge customer
const charge = await client.charge({
  amount: 5000,
  currency: 'USD',
  paymentMethod: { type: 'card', token: 'tok_visa' },
  idempotencyKey: 'order-123'
});

// Customer requests refund
const refund = await client.refund({
  transactionId: charge.id,
  reason: 'Customer requested cancellation',
  idempotencyKey: 'refund-order-123'
});

console.log(refund.status); // 'completed' or 'pending'
console.log(refund.amount); // 5000

​
Implementation details

The refund operation (src/client/vault-client.ts:247-272):
  1. Looks up the provider that handled the original transaction using the transaction index
  2. Executes the refund through the provider adapter
  3. Returns a RefundResult with refund details (not a full PaymentResult)
  4. Queues transaction report to the platform for analytics
Refunds are processed through the same provider that handled the original transaction. You cannot refund a Stripe charge through Adyen, for example.
Refund timing varies by provider and payment method:
  • Card refunds typically take 5-10 business days to appear in the customer’s account
  • Some providers process refunds instantly
  • Refund status may be "pending" initially and update to "completed" later
Use partial refunds for price adjustments, damaged goods, or promotional credits without refunding the entire order.

​
Refund status lifecycle

1

Refund initiated

Status is "pending" when the refund request is submitted to the provider.
2

Provider processing

The payment provider processes the refund and initiates the transfer back to the customer.
3

Refund completed

Status changes to "completed" when the provider confirms the refund. Funds may still take additional days to reach the customer’s account.

Build docs developers (and LLMs) love

Get started for freeTalk to us