Wallet & Payouts

Wallet & Payouts Integration Guide

Copy page

Overview

The Wallet and Payouts APIs enable merchants to manage their wallet balance, view payout history, and track scheduled payouts. Wallets store funds from successful payments, and payouts transfer those funds to your bank account.

Key Concepts

• Wallet: A merchant's account that holds payment funds
• Available Balance: Funds ready for transfer
• Pending Balance: Funds from payments not yet settled
• Payout: Scheduled transfer of wallet funds to bank
• Payout Schedule: When payouts are processed (e.g., weekly)

Quick Start

Step 1: Get Wallet Balance

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 balance = await saligpay.wallets.getBalance("wallet_abc123");
console.log("Available:", balance.available);
console.log("Pending:", balance.pending);

Step 2: List Payouts

Code
 
const payouts = await saligpay.payouts.list({
    payout_status: "deposited",
    sort_by: "created_at",
    order: "desc",
    limit: 20,
});

payouts.data.forEach((payout) => {
    console.log(`Payout ${payout.id}: ${payout.attributes.amount} ${payout.attributes.status}`);
});

Step 3: Get Payout Schedule

Code
 
const schedule = await saligpay.payouts.getSchedule("org_merchant123");
console.log("Schedule Type:", schedule.attributes.type);
console.log("Days:", schedule.attributes.days);

API Reference

Get Wallet

GET /api/wallet/{id}

Code
 
{
    "id": "wallet_abc123",
    "type": "wallet",
    "attributes": {
        "account_name": "My Business Inc",
        "account_number": "1234567890",
        "available_balance": 500000,
        "pending_balance": 50000,
        "status": "active",
        "limits": {
            "daily": { "max_amount": 1000000, "remaining": 800000 },
            "monthly": { "max_amount": 5000000, "remaining": 4500000 }
        }
    }
}

Get Wallet Balance

GET /api/wallet/{id}/balance

Code
 
{
    "available": 500000,
    "pending": 50000
}

List Payouts

GET /api/payout?payout_status=deposited&sort_by=created_at&order=desc&limit=20

Query Parameters

Parameter	Type	Description
payout_status	string	pending, on_hold, in_transit, deposited, returned, cancelled
sort_by	string	created_at or net_amount
order	string	asc or desc
limit	number	1-100, default 10
after	string	Pagination cursor

Get Payout Detail

GET /api/payout/{id}

Get Payout Transactions

GET /api/payout/{id}/transactions

Get Payout Schedule

GET /api/payout/schedule/{merchantId}

SDK Reference

WalletResource

Method	Description
get(id)	Get wallet account details
getBalance(id)	Get available and pending balance
transfer(walletId, data)	Create wallet transfer
listTransfers(walletId, options?)	List wallet transfers
getTransfer(walletId, transferId)	Get specific transfer

PayoutResource

Method	Description
list(options?)	List payouts with filters
get(id)	Get payout details
getTransactions(id, options?)	Get payout transactions
getSchedule(merchantId)	Get payout schedule

Error Handling

Error	Cause	Solution
Wallet not found	Invalid wallet ID	Verify wallet ID exists
Insufficient available balance	Balance too low for transfer	Wait for funds to settle
Invalid access token	Expired JWT	Refresh authentication

Best Practices

• Check wallet balance before initiating transfers
• Use pagination for large payout lists
• Monitor payout schedules to predict fund availability
• Implement webhook handlers for payout status updates
• Track pending_balance for cash flow forecasting

---

Related Guides:

• Transfers Guide - For sending funds
• SDK Wallets - For SDK method details