Interswitch Payouts API — look up receiving institutions, discover payout channels, and route disbursements. Use this skill whenever building payout infrastructure, discovering available disbursement channels, resolving receiving institutions, or implementing multi-channel payout routing. Also use when you see references to payout channels, receiving institutions, disbursement routing, or /api/v1/payouts endpoints.
Discover available payout channels and receiving institutions for routing disbursements across Nigeria.
| Endpoint | Method | Description |
|---|---|---|
/api/v1/payouts/channels | GET | List available payout channels |
/api/v1/payouts/institutions | GET | List receiving institutions |
/api/v1/payouts/institutions/{code} | GET | Get institution details |
interface PayoutChannel {
channelCode: string;
channelName: string;
description: string;
supportedCurrencies: string[];
isActive: boolean;
}
async function getPayoutChannels(): Promise<PayoutChannel[]> {
const headers = await getAuthHeaders();
const response = await fetch(
`${process.env.INTERSWITCH_BASE_URL}/api/v1/payouts/channels`,
{ method: 'GET', headers }
);
const data = await response.json();
return data.channels;
}
| Channel | Code | Description |
|---|---|---|
| Bank Transfer | BANK | Direct bank account transfer |
| Mobile Money | MOBILE_MONEY | Mobile wallet payout |
| Card | CARD | Card-based disbursement |
| Paycode | PAYCODE | ATM cardless withdrawal |
interface ReceivingInstitution {
institutionCode: string;
institutionName: string;
type: 'BANK' | 'MICROFINANCE' | 'MOBILE_MONEY';
isActive: boolean;
supportedChannels: string[];
nipCode?: string;
}
async function getReceivingInstitutions(
channel?: string
): Promise<ReceivingInstitution[]> {
const headers = await getAuthHeaders();
const url = new URL(
`${process.env.INTERSWITCH_BASE_URL}/api/v1/payouts/institutions`
);
if (channel) url.searchParams.set('channel', channel);
const response = await fetch(url.toString(), {
method: 'GET',
headers,
});
const data = await response.json();
return data.institutions;
}
async function getInstitutionDetails(
institutionCode: string
): Promise<ReceivingInstitution> {
const headers = await getAuthHeaders();
const response = await fetch(
`${process.env.INTERSWITCH_BASE_URL}/api/v1/payouts/institutions/${encodeURIComponent(institutionCode)}`,
{ method: 'GET', headers }
);
return response.json();
}
// Build a payout router that selects the best channel
interface PayoutRequest {
recipientAccount: string;
recipientInstitution: string;
amount: number;
currency: string;
}
async function routePayout(request: PayoutRequest): Promise<string> {
// 1. Get institution details
const institution = await getInstitutionDetails(request.recipientInstitution);
// 2. Find available channels for this institution
const channels = await getPayoutChannels();
const activeChannels = channels.filter(
(c) => c.isActive && institution.supportedChannels.includes(c.channelCode)
);
if (activeChannels.length === 0) {
throw new Error(`No active payout channels for ${institution.institutionName}`);
}
// 3. Prefer bank transfer, fall back to others
const preferred = activeChannels.find((c) => c.channelCode === 'BANK')
|| activeChannels[0];
return preferred.channelCode;
}
// 1. Discover channels
const channels = await getPayoutChannels();
console.log('Available channels:', channels.map((c) => c.channelName));
// 2. List bank institutions
const banks = await getReceivingInstitutions('BANK');
console.log('Banks:', banks.length);
banks.forEach((bank) => {
console.log(`${bank.institutionCode}: ${bank.institutionName}`);
});
// 3. Get specific bank details
const gtbank = await getInstitutionDetails('058');
console.log('GTBank channels:', gtbank.supportedChannels);
// 4. Use with transfers
// Once you have the institution code, use the interswitch-transfers skill
// to initiate the actual transfer
isActive status — Only route to active institutions