The Refund object

Represents a refund for a previously completed transaction. Refunds allow merchants to return funds to customers for completed payments. A refund can be for the full amount or a partial amount of the original transaction.

Fields

Field	Type	Description
id REQUIRED	string	Unique identifier for the refund
merchantId REQUIRED	string	ID of the merchant that issued the refund
transactionId REQUIRED	string	ID of the original transaction being refunded
customerId OPTIONAL	string	ID of the customer receiving the refund (if registered)
customerName OPTIONAL	string	Name of the customer receiving the refund
customerEmail OPTIONAL	string	Email of the customer receiving the refund
amount REQUIRED	number	Refund amount in the smallest currency unit (e.g., cents for USD)
currency REQUIRED	string	Three-letter ISO currency code
status REQUIRED	RefundStatus	Current status of the refund RefundStatus
reason OPTIONAL	string	Reason provided for the refund
failureReason OPTIONAL	string	Reason for failure if the refund failed
tspRefundId OPTIONAL	string	External refund ID from the payment provider
processedAt OPTIONAL	string	ISO 8601 timestamp when the refund was processed
metadata OPTIONAL	Record<string, unknown>	Custom key-value data attached to the refund
createdAt REQUIRED	string	ISO 8601 timestamp when the refund was created
updatedAt REQUIRED	string	ISO 8601 timestamp when the refund was last updated

Example

{
  "id": "obj_1a2b3c",
  "merchantId": "merchant_1a2b3c",
  "transactionId": "transaction_1a2b3c",
  "customerId": "customer_1a2b3c",
  "customerName": "string",
  "customerEmail": "customer@example.com",
  "amount": 5000,
  "currency": "USD",
  "status": "pending_approval",
  "createdAt": "2026-01-15T09:30:00Z",
  "updatedAt": "2026-01-15T09:30:00Z"
}

Usage

const refund = await client.refunds.get('ref_123');
if (refund.status === 'completed') {
  console.log(`Refund of ${refund.amount} ${refund.currency} completed`);
}