Payout

This endpoint retrieves a list of supported banks and their codes for making transfers.

Why you need this

Before you can send money to someone, you need to know which banks are supported and their unique codes. Think of this as your directory of Nigerian banks—it's the first step in any payout flow.

Common use cases

• Building a bank selection dropdown: When users need to choose their bank during account setup or payout configuration, this endpoint provides the complete list of available banks.
• Validating bank codes: Before processing a transfer, verify that the bank code exists in our supported list to prevent failed transactions.
• Displaying bank information: Show users friendly bank names alongside codes in your UI for better user experience.
• Pre-populating forms: Use this data to auto-complete bank selection fields in your application.

This endpoint is used to resolve the account name associated with a given bank code and account number. This is useful for verifying account details before initiating a transfer.

Why this matters

Ever sent money to the wrong person because of a typo? This endpoint helps prevent that. It's like asking the bank "Hey, does this account number belong to John Doe?" before you send the money. It's a safety net that saves you from costly mistakes and builds trust with your users.

Common use cases

• Account verification before payout: When a user enters their account details, verify the account name matches what they claim before processing the transfer. This prevents sending money to the wrong account.
• Building trust in your UI: Display the resolved account name to users before they confirm a transfer—"Sending ₦50,000 to ADEYEMI GBOLUWAGA AFOLABI" gives users confidence they're sending to the right person.
• Preventing fraud: Catch mismatches between provided names and actual account holders before funds leave your system.
• Form validation: Validate account details in real-time as users type, providing instant feedback if the account doesn't exist or the name doesn't match.

Query Parameters

This endpoint processes a single bank transfer by specifying the recipient's bank details, account number, amount, and source wallet.

The workhorse of payouts

This is your go-to endpoint for sending money to a single recipient. Whether it's a one-time payment, a refund, or a scheduled payout—this endpoint handles it all. It's fast, reliable, and gives you instant feedback on the transaction status.

Common use cases

• E-commerce refunds: When a customer returns a product, automatically refund their money to their bank account instead of store credit.
• Freelancer payments: Pay contractors, designers, or consultants directly to their bank accounts after project completion.
• Salary disbursements: For small teams or one-off payments, send salaries directly to employee bank accounts.
• Vendor settlements: Settle payments with suppliers, service providers, or partners after delivery confirmation.
• Customer withdrawals: Allow users to cash out their wallet balance to their bank account.
• One-time payouts: Process individual payments like bonuses, commissions, or rewards.
• Emergency transfers: Handle urgent payments that need immediate processing.

Request Body

This endpoint allows for processing multiple bank transfers in a single request.

Efficiency at scale

Why send 100 transfers one by one when you can send them all at once? This endpoint is perfect for when you need to pay multiple people simultaneously. It's like having a payment assistant that can handle dozens of transfers while you focus on other things.

Common use cases

• Payroll processing: Pay all your employees at once on payday. No more processing salaries one by one—just upload the list and let the API handle it.
• Marketplace seller payouts: If you run a marketplace, settle earnings to hundreds of sellers at the end of each week or month.
• Affiliate commissions: Distribute commissions to your entire affiliate network in one batch operation.
• Gig economy payouts: Pay multiple freelancers, drivers, or service providers who completed work during a period.
• Reward distributions: Send rewards, bonuses, or incentives to multiple users simultaneously.
• Bulk refunds: Process refunds for multiple orders at once, especially useful during sales events or product recalls.
• Dividend payments: Distribute dividends to shareholders or profit-sharing to partners.
• Vendor batch payments: Settle invoices with multiple suppliers in a single operation.

Why use bulk instead of single transfers?

• Faster processing: All transfers are queued and processed together, reducing overall processing time.
• Simpler code: One API call instead of looping through multiple single transfer calls.
• Better error handling: Get a comprehensive view of which transfers succeeded and which failed in one response.
• Cost efficiency: Reduce API call overhead when processing many transfers.

Request Body

This endpoint retrieves the transfer record with the most up-to-date status of the transfer at that time.

Stay in the loop

After initiating a transfer, you'll want to know if it went through. This endpoint gives you the real-time status of any transfer—whether it's pending, successful, or failed. It's like checking your delivery tracking, but for money transfers.

Common use cases

• Status checks in your dashboard: Display the current status of transfers in your admin panel or user dashboard.
• Polling for updates: Periodically check transfer status until it's completed, especially for transfers that might take a few minutes.
• Customer support: When users ask "Where's my money?", quickly look up the transfer status to provide accurate information.
• Reconciliation: Match your internal records with actual transfer statuses for accounting purposes.
• Retry logic: Check if a pending transfer has completed before retrying a failed operation.
• Audit trails: Retrieve transfer details for compliance, reporting, or dispute resolution.
• Webhook verification: After receiving a webhook notification, verify the transfer status to ensure data consistency.

Transfer statuses you might see

• Pending: The transfer is queued and being processed. Give it a moment.
• Success: Money has been successfully sent to the recipient's account. Party time! 🎉
• Failed: Something went wrong. Check the error details to understand what happened.

Path Parameters

This endpoint retrieves the transfer record with the most up-to-date status using the transfer reference.

Find transfers your way

Sometimes you don't have the transfer ID, but you do have the reference you created when initiating the transfer. This endpoint lets you look up transfers using your own reference system—perfect for when you want to track transfers using your internal order IDs, invoice numbers, or custom identifiers.

Common use cases

• Order-based lookups: When a customer asks about their refund, look it up using your order ID (which you used as the reference).
• Invoice reconciliation: Match payments to invoices using invoice numbers as references.
• Customer support queries: Users often remember their order number or transaction reference, not the transfer ID. This makes it easy to find their transfer.
• Integration with existing systems: If your system already uses reference numbers, you can continue using them and look up transfers the same way.
• Webhook verification: When you receive a webhook with a reference, verify the transfer details using this endpoint.
• Duplicate prevention: Before creating a new transfer, check if a transfer with the same reference already exists.
• Reporting and analytics: Generate reports by looking up transfers using your business-specific reference patterns.

Why use reference instead of ID?

• Human-readable: References like "ORDER-12345" are easier to remember and communicate than UUIDs.
• Business context: Your references can encode business logic (e.g., "REFUND-2024-001" tells you it's a refund from 2024).
• System integration: Works seamlessly with your existing order management, invoicing, or accounting systems.

Query Parameters

This endpoint retrieves the transfer fee associated with a specified amount. It is useful for users who want to understand the costs involved before initiating a transfer.

Know the cost upfront

Nobody likes surprises, especially when it comes to fees. This endpoint lets you calculate transfer fees before processing a payment, so you can show users exactly how much they'll receive and how much will be deducted. Transparency builds trust.

Common use cases

• Fee calculator in your UI: Show users the exact fee before they confirm a transfer. "Sending ₦10,000? That'll cost ₦100 in fees, so the recipient gets ₦9,900."
• Pre-transfer validation: Calculate fees before initiating transfers to ensure sufficient wallet balance (amount + fee).
• Cost estimation: Help users understand the total cost of their transaction before committing.
• Budget planning: For businesses processing many transfers, calculate total fees to budget accurately.
• Fee comparison: Display fees for different transfer amounts to help users make informed decisions.
• User education: Show users how fees work and help them understand the cost structure.
• Dynamic fee display: Update fee information in real-time as users enter different amounts in your transfer form.

Why this matters

• Transparency: Users appreciate knowing fees upfront, reducing support queries and building trust.
• Better UX: Displaying fees helps users make informed decisions and prevents failed transfers due to insufficient balance.
• Compliance: Some regulations require fee disclosure before transaction completion.
• Accurate calculations: Ensure your fee calculations match the actual fees charged by the API.

Query Parameters