Skip to main content
The Client SDK provides complete refund management capabilities for payers. All refund methods interact directly with the RefundRequest contract on-chain.
About the nonce parameter: Every refund method requires a nonce: bigint parameter. This is the record index from the PaymentIndexRecorder and identifies which charge within a payment you are requesting a refund for. For the first (and most common) charge, use 0n.

​
requestRefund

Submit a refund request for a payment that is in escrow. The request goes on-chain and is visible to the merchant and any assigned arbiter. 
const { txHash } = await client.requestRefund(
  paymentInfo,
  BigInt('1000000'), // amount to refund (e.g., 1 USDC with 6 decimals)
  0n                 // nonce: first charge
);

console.log(`Refund requested: ${txHash}`);

​
cancelRefundRequest

Cancel a pending refund request that you submitted. Only the original requester (payer) can cancel, and only while the request status is Pending. 
const { txHash } = await client.cancelRefundRequest(paymentInfo, 0n);
console.log(`Refund request cancelled: ${txHash}`);

​
Query Refund State

These methods read on-chain state for refund requests. None require a wallet client.

​
Check existence and status

// Check if a refund request exists
const hasRequest = await client.hasRefundRequest(paymentInfo, 0n);

// Get just the status
const status = await client.getRefundStatus(paymentInfo, 0n);
// Returns: RequestStatus.Pending | Approved | Denied | Cancelled

​
Get full refund request data

// By paymentInfo + nonce
const request = await client.getRefundRequest(paymentInfo, 0n);
console.log(request.amount, request.status);

// By composite key (from getMyRefundRequests)
const request2 = await client.getRefundRequestByKey(compositeKey);

​
List your refund requests

// Get total count
const count = await client.getMyRefundRequestCount();

// Get paginated keys, then fetch details
const { keys, total } = await client.getMyRefundRequests(0n, 10n);

for (const key of keys) {
  const request = await client.getRefundRequestByKey(key);
  console.log(`Amount: ${request.amount}, Status: ${request.status}`);
}

​
Refund Request Lifecycle

​
Method Reference

MethodParametersReturns
requestRefundpaymentInfo, amount, nonce{ txHash }
cancelRefundRequestpaymentInfo, nonce{ txHash }
hasRefundRequestpaymentInfo, nonceboolean
getRefundStatuspaymentInfo, nonceRequestStatus
getRefundRequestpaymentInfo, nonceRefundRequestData
getRefundRequestByKeycompositeKeyRefundRequestData
getMyRefundRequestsoffset, count{ keys, total }
getMyRefundRequestCountnonebigint

​
Next Steps

Escrow Management

Freeze payments and check escrow period timing.

Event Subscriptions

Watch for refund status updates in real-time.

Payment Queries

Query payment state and details.

Client Quickstart

Full setup guide for the Client SDK.