Base URLS

The test base url is https://isw-payout-service.k8.isw.la/api/v1/payouts

The live base url is https://payouts.interswitchng.com/api/v1/payouts

SEND BATCH PAYOUTS

Initiates a batch payout to multiple recipients in a single request. Transactions are validated in real time and validation errors returned immediately. The batch transaction is processed asynchronously.. A reference would be returned once the request passed the original validations, it would be used to check original validations, it would be used to check the status of the batch request

Endpoint POST <base-url>/batch

SAMPLE REQUEST

{
  "payoutChannel": "BANK_TRANSFER",
  "narration": "Salary payment March 2026",
  "currencyCode": "NGN",
  "amount": 500000.00,
  "walletDetails": {
    "walletId": "WALLET-123456",
		""
  },
  "recipients": [
    {
      "transactionReference": "TXN-001",
      "recipientName": "John Doe",
      "recipientAccount": "0123456789",
      "recipientBank": "058",
      "amount": 250000.00,
      "currencyCode": "NGN"
    },
    {
      "transactionReference": "TXN-002",
      "recipientName": "Jane Smith",
      "recipientAccount": "9876543210",
      "recipientBank": "011",
      "amount": 250000.00,
      "currencyCode": "NGN"
    }
  ]
}

REQUEST FIELDS

Field	Type	Required	Description
payoutChannel	string	yes	Payment channel: BANK_TRANSFER
currencyCode	string	yes	Currency code: NGN
narration	string	yes	Description for all transactions
amount	decimal	yes	Total amount (must equal sum of all recipient amounts)otal amount (must equal sum of all recipient amounts)
walletDetails	object	yes	source wallet information
walletDetails.walletId	string	yes	Merchant wallet ID
walletDetails.pin	string	yes	Wallet PIN

RECIPIENT FIELDS

Field	Type	Required	Description
transactionReference	string	yes	Unique reference per recipient
amount	string	yes	Amount to transfer
currencyCode	string	yes	Currency code NGN
recipientAccount	string	yes	Recipients bank account number
recipientBank	string	yes	Recipient's Bank code

RESPONSE

{
  "status": "PROCESSING",
  "reference": "550e8400-e29b-41d4-a716-446655440000"
}

RESPONSE FIELDS

Field	Type	Description
status	string	Initial status: PROCESSING
reference	string	Batch reference (UUID) for tracking Batch reference (UUID) for tracking

GET BATCH PAYOUT SUMMARY

Retrieves a paginated summary of batch payouts for a merchant. Use this to get an overview of all batches and their aggregate status.

Endpoint GET /api/v1/payouts/batch-summary

QUERY PARAMETERS

Parameter	Type	Required	Description
clientId	string	yes	Merchant/client identifier
batchReference	string	yes	Filter by specific batch reference
status	string	no	Filter by batch status
totalAmount	decimal	no	Filter by total amount
totalRecipients	integer	no	Filter by number of recipients
startDate	string	no	Start date filter (DD/MM/YYYY)
endDate	string	no	Start date filter (DD/MM/YYYY
pageNum	integer	no	Page number (default: 1)
pageSize	integer	no	Page size (default: 10)

RESPONSE

{
  "content": [
    {
      "batchReference": "550e8400-e29b-41d4-a716-446655440000",
      "clientId": "MERCHANT001",
      "narration": "Salary payment March 2026",
      "totalAmount": 500000.00,
      "totalCharges": 1000.00,
      "totalRecipients": 2,
      "status": "COMPLETED",
      "createdOn": "2026-03-15T10:30:00.000+00:00"
    }
  ],
  "count": 1,
  "pageNum": 1,
  "pageSize": 10
}

GET BATCH DETAILS

Retrieves detailed transaction information for a specific batch. Use this to view individual transaction statuses within a batch.Retrieves detailed transaction information for a specific batch. Use this to view individual transaction statuses within a batch.

Endpoint GET /api/v1/payouts/batch-details

QUERY PARAMETERS

Parameter	Type	Required	Description
clientId	string	yes	Merchant/client identifier
batchReference	string	yes	Filter by specific batch reference
status	string	no	Filter by transaction status (PROCESSING, SUCCESSFUL, FAILED)
amount	decimal	no	Filter by transaction amount
recipient	integer	no	Filter by recipient name or account
startDate	string	no	Start date filter (DD/MM/YYYY)
endDate	string	no	Start date filter (DD/MM/YYYY
pageNum	integer	no	Page number (default: 1)
pageSize	integer	no	Page size (default: 10)

RESPONSE

{
  "content": [
    {
      "transactionReference": "TXN-001",
      "beneficiary": "John Doe",
      "accountNumber": "0123456789",
      "amount": 250000.00,
      "fee": 500.00,
      "narration": "Salary payment March 2026",
      "status": "SUCCESSFUL",
      "responseCode": "00",
      "responseDescription": "Approved",
      "reversed": false,
      "walletDebit": true,
      "date": "2026-03-15T10:30:15.000+00:00"
    },
    {
      "transactionReference": "TXN-002",
      "beneficiary": "Jane Smith",
      "accountNumber": "9876543210",
      "amount": 250000.00,
      "fee": 500.00,
      "narration": "Salary payment March 2026",
      "status": "SUCCESSFUL",
      "responseCode": "00",
      "responseDescription": "Approved",
      "reversed": false,
      "walletDebit": true,
      "date": "2026-03-15T10:30:18.000+00:00"
    }
  ],
  "count": 2,
  "pageNum": 1,
  "pageSize": 10
}