Disbursement Workflow

How payouts work on Atlas, covering the payout types, what Atlas checks before sending money, the payout states and their webhooks, how to track a payout, and fees.

Disbursements are payouts from your Atlas business wallet to bank accounts outside Atlas, such as paying vendors, running payroll, or settling with partners.

Payout types

Atlas supports three ways to send money out:

Single Payout

Send one NGN bank transfer to one recipient.

Bulk Payout

Send NGN bank transfers to many recipients in one batch, processed asynchronously.

International Bank Transfer

Send USD, EUR, or GBP to a bank account abroad from your foreign currency wallet.

How a payout works

Every payout follows the same steps:

Resolve the recipient. For NGN payouts, get the recipient's bank code from the bank list endpoint, then confirm the account with a name enquiry, or a bulk name enquiry for a batch. International transfers skip this step, because you supply the full recipient and bank details yourself.
Initiate the payout. Send the payout request with a source_reference that is unique to this payout. Atlas uses it to reject duplicates, and you can use it to look the payout up later.
Atlas validates the request. Atlas checks the request before any money moves, and rejects it with an error if any check fails. Nothing is debited from your wallet for a rejected request.
Atlas debits your wallet and sends the transfer. The payout is created in the Pending state, the amount and fees are debited from your wallet, and Atlas sends an OUT_FLOW_PENDING_EVENT webhook.
The recipient's bank settles the transfer. Once the bank confirms the result, the payout moves to Successful or Failed, and Atlas sends the matching webhook. Settlement usually takes seconds, but can take a few minutes depending on the recipient's bank.

What Atlas checks before sending

When you initiate an NGN payout, Atlas rejects the request if:

A required field is missing or invalid.
The amount is below ₦100 or above ₦250,000,000.
The currency isn't enabled for your business.
The source_reference has already been used for another payout.
The recipient's account can't be resolved with their bank. Atlas runs its own name enquiry for every NGN payout and uses the account name the bank returns, not the account_name in your request.
Your wallet balance doesn't cover the payout amount plus fees.

These checks happen before the payout is created, so a rejected request never appears as a failed payout. A payout only reaches the Failed state after Atlas has sent it to the recipient's bank.

Retrying a request that timed out

If a single payout request times out or you never receive a response, don't resend it straight away. Look the payout up with the Get Payout by Source Reference endpoint first. If it exists, the payout went through. Resending it with the same source_reference is rejected, and resending with a new one sends the money twice. For bulk payouts, resending the identical batch with the same source_reference is safe, because Atlas returns the existing batch instead of creating a new one.

Payout states

A payout is always in one of three states:

State	Meaning	Webhook
`Pending`	Atlas has debited your wallet and sent the transfer, and is waiting for the recipient's bank to confirm it.	`OUT_FLOW_PENDING_EVENT`
`Successful`	The recipient's bank confirmed that the funds were credited. This is a final state.	`OUT_FLOW_SUCCESS_EVENT`
`Failed`	The transfer couldn't be completed, for example because the recipient's account is closed or restricted, or because of a bank or network error. This is a final state.	`OUT_FLOW_FAILED_EVENT`

When a payout fails, the debited amount is returned to your Atlas wallet automatically.

Bulk payouts also have a batch status, alongside the status of each payout in the batch:

Batch status	Meaning
`PENDING`	At least one payout in the batch is still pending.
`COMPLETED`	Every payout in the batch has reached a final state. Some of them may have failed, so check the status of each payout.
`FAILED`	Atlas rejected the whole batch before sending any of it, and nothing was debited.

Tracking a payout

Use webhooks as your main signal. Atlas sends a webhook each time a payout changes state, including every payout in a bulk batch. See the webhooks guide to configure your endpoint and verify each event.

You can also look a payout up at any time:

Get Payout by Source Reference: find a payout using the source_reference you sent.
Get Payout by Reference: find a payout using the reference Atlas returned.
Get Bulk Payout Status and Get Bulk Payout Status By Source Reference: get a batch's status and every payout in it.

Fees

Each NGN payout incurs a fee of ₦50 by default. If your business has agreed a different fee with Duplo, that fee applies instead.

Some payouts also incur:

Stamp duty on payouts of ₦10,000 or more.
VAT on the payout fee, where it applies.

Fees are charged on top of the payout amount, so your wallet must cover both. The recipient receives the full amount you send. Each charge appears as a separate entry in the fee array of the payout response, and a bulk payout response reports the batch total as totalFees.