Payment

Refund Integration Guide

Copy page

Overview

The Refund API allows you to process refunds for completed payments. You can issue full or partial refunds, specify reasons, and track refund status.

Refund Types

• Full Refund: Refund the entire payment amount
• Partial Refund: Refund a portion of the payment (multiple partial refunds allowed up to the original amount)

Quick Start

Step 1: Create a Refund

Code
 
import { SaligPay } from "saligpay-node";

const saligpay = new SaligPay({
    clientId: process.env.SALIGPAY_CLIENT_ID!,
    clientSecret: process.env.SALIGPAY_CLIENT_SECRET!,
    env: "sandbox",
});

await saligpay.authenticate();

const refund = await saligpay.refunds.create({
    sessionToken: "550e8400-e29b-41d4-a716-446655440000",
    amount: 5000, // ₱50.00 partial refund
    reason: "requested_by_customer",
    notes: "Customer requested partial refund",
});

console.log("Refund ID:", refund.id);
console.log("Status:", refund.status);

Step 2: Check Refund Status

Code
 
const refundStatus = await saligpay.refunds.get(refund.id);
console.log("Refund Status:", refundStatus.status);

API Reference

Create Refund

POST /api/refund/session/{sessionToken}

Code
 
{
    "amount": 5000,
    "reason": "requested_by_customer",
    "notes": "Customer requested partial refund"
}

Request Fields

Field	Type	Required	Description
amount	number	Yes	Refund amount in centavos (max 1,000,000)
reason	string	No	duplicate, fraudulent, requested_by_customer, other
notes	string	No	Additional notes (max 1000 chars)

Get Refund

GET /api/refund/{refundId}

List Refunds

GET /api/refund?status=succeeded&limit=20

SDK Reference

Refund Methods

The SDK provides refund operations through the payment client. Refunds are tied to payment sessions.

Error Handling

Error	Cause	Solution
Amount exceeds refundable balance	Refund amount too high	Check remaining refundable amount
Session not found	Invalid session token	Verify session exists and is completed
Invalid amount	Amount is 0 or negative	Use positive amount

Best Practices

• Track refundable amounts to prevent over-refunding
• Use meaningful reasons for reporting and analytics
• Store refund IDs for customer support reference
• Implement webhooks for refund status updates

---

Related Guides:

• Checkout Guide - For payment sessions
• Transactions Guide - For querying refunds