Make a payout

Learn how to initiate a payout request.

To use the Payout APIs in a live or production environment, Novac Payment uses IP whitelisting to grant access.
You’ll need to contact [e-mail] to request access for your IP address.

Overview

The payout flow describes the complete process of sending funds from your Novac account to a customer’s settlement account.
It ensures that every payout is validated, securely processed, and easily verifiable.

To initiate a payout, your integration follows this flow:

How payout flow works

1. Fetch Supported Banks

   Retrieve the list of banks supported for payouts, filtered by country code. You’ll need the correct bank code from this list to verify a recipient’s account and to initiate a payout.

   Using an incorrect or unsupported bank code will cause later steps to fail.

2. Verify the Recipient's Bank Account

   Before sending money, confirm the recipient’s account number resolves to a valid, correctly named account at the selected bank. This step returns the account holder’s name so you can display it back to your user for confirmation.

3. Check Your Balance (Optional)

   Optionally check your available balance before initiating a payout, to confirm you have sufficient funds. This step is optional because the payout request itself will fail gracefully with an insufficient-funds error if your balance is too low.

4. Initiate the Payout

   Send the actual payout request, specifying the verified recipient account, bank code, and amount. A successful call here doesn’t necessarily mean the money has arrived. It means the payout has been accepted and is being processed. You’ll receive a reference to track its status.

5. Verify the Transaction Status

   Use the reference returned in the previous step to check whether the payout completed successfully, failed, or is still processing. Because payouts can take time to settle on the recipient’s end, this is typically the step you’ll listen for via webhook.

Get supported payout banks based on country

When a customer initiates a payout request, your system begins by fetching the list of supported banks from Novac by sending a GET request to the endpoint /api/v1/banks/{countryCode}.

You can pass NG, GH and KE as your country code, as Novac support payout on Nigeria, Ghana and Kenya.

This allows you to display the available banks for the customer to select from.

---

Verify customer settlement account

After the customer selects a destination bank and enters their account number, your system should verify the account details by making a POST request to /api/v1/banks/account/verify.

This verification confirms that the account exists and returns the account holder’s name, which can then be displayed to the customer for confirmation.

Before proceeding with the payout, your system can optionally check the available balance by sending a GET request to /api/v1/balance/{currency} to ensure sufficient funds.

---

Initiate a payout request

Once the customer confirms the payout, your system sends a POST request to /api/v1/transfers, including the payout details such as the amount, bank, and account information.

Novac processes the transaction and returns a unique transaction reference, which your system can display to the customer as proof of submission.

Finally, to verify the payout’s completion, your system can send a GET request to /api/v1/transfers/{reference} using the transaction reference returned earlier.

This endpoint provides the current transaction status such as “pending”, “successful”, or “failed” allowing your system to communicate the result back to the customer.

This complete flow ensures that every payout is securely processed, verified, and transparently tracked from initiation to confirmation.