Single Payout

Initiate single bank transfer payouts from your Atlas account to a recipient's bank account using the Create Payout API endpoint.

Single payouts allow you to transfer funds from your Atlas business account to a recipient's bank account. This is ideal for one-time payments, refunds, vendor payments, or any scenario where you need to send money to an individual recipient.

Payout parameters

When creating a single payout, you need to provide the following parameters:

account_number: The recipient's 10-digit bank account number.
bank_code: The recipient's bank code. See Getting bank codes below.
account_name: The recipient's account name. Must match the name registered with their bank. See Getting account name below.
amount: The amount to send (e.g, 500)
narration: A description of the payment. This appears on the recipient's bank statement.
type: The transfer type. Use bank_transfer.
currency: The currency code. For example, NGN.
bank_name: The recipient's bank name.
source_reference: A unique string you provide to identify the payout. You can use it to look up the transaction later via the Get Payout by Source Reference endpoint.

Getting bank codes

Before initiating a payout, you need the recipient's bank code. Make a GET request to banking/bank/{currency} to retrieve all supported banks, then filter for your recipient's bank.

For example:

const axios = require("axios");

const getBanks = async (currency) => {
  try {
    const response = await axios.get(
      `https://atlas.tryduplo.com/api/v1/banking/bank/${currency}`,
      {
        headers: {
          Authorization: "Bearer your_api_key",
          Accept: "application/json",
        },
      },
    );

    console.log(response.data);
  } catch (error) {
    console.error(error.response.data);
  }
};

getBanks("NGN");

Getting account name

The account_name you provide must match the name registered to the account number at the recipient's bank. Make a POST request to banking/name-enquiry with the account number and bank code to look it up.

curl -X POST "https://atlas.tryduplo.com/api/v1/banking/name-enquiry" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "0123456789",
    "bankCode": "099858"
  }'

Initiating a single payout

With the bank code and account name resolved, make a POST request to payout/bank-transfer to initiate the payout.

Before initiating a payout, ensure you have sufficient balance in your Atlas business account.

curl -X POST "https://atlas.tryduplo.com/api/v1/payout/bank-transfer" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "account_number": "0123456789",
    "bank_code": "099858",
    "bank_name": "Kuda Microfinance Bank",
    "bank_code": "099858",
    "bank_name": "Kuda Microfinance Bank",
    "account_name": "John Doe",
    "amount": 50000,
    "narration": "Payment for services rendered",
    "type": "bank_transfer",
    "currency": "NGN",
    "source_reference": "SRC_PAYOUT_001"
  }'

On a successful request, you'll receive a response confirming the payout has been initiated:

JSON

{
  "requestId": "96d34fbb-0589-492f-b621-f8fb8b649f8c",
  "requestTimestamp": "2026-03-21 11:13:56.980",
  "message": "Payout initiated successfully.",
  "statusCode": 200,
  "data": {
    "id": "019d1019-f9b3-70d2-be9f-cef3ec5b4566",
    "recipientAccountName": "John Doe",
    "recipientAccountNumber": "0123456789",
    "recipientBankName": "Kuda Microfinance Bank",
    "sourceReference": "SRC_PAYOUT_001",
    "paymentChannel": "Bank Transfer",
    "sessionId": null,
    "parentTransactionReference": null,
    "reference": "TRN_QELKDOVYYCFV",
    "amount": {
      "value": 50000,
      "currency": "NGN",
      "formatted": "NGN500"
    },
    "balance": {
      "value": 316,
      "currency": "NGN",
      "formatted": "NGN316"
    },
    "status": "Pending",
    "narration": "Payment for services rendered",
    "createdAt": "2026-03-21 12:13:51",
    "fee": [
      {
        "id": "019d1019-ff2c-70fb-af1c-6004b6d67dcb",
        "recipientAccountName": "-",
        "recipientAccountNumber": "-",
        "recipientBankName": "Master Wallet",
        "sourceReference": "SRC_PAYOUT_001",
        "paymentChannel": "Fees",
        "sessionId": null,
        "parentTransactionReference": "TRN_QELKDOVYYCFV",
        "reference": "TRN_KLXCE8TGZ0QS",
        "amount": {
          "value": 10,
          "currency": "NGN",
          "formatted": "NGN10"
        },
        "balance": {
          "value": 306,
          "currency": "NGN",
          "formatted": "NGN306"
        },
        "status": "Pending",
        "narration": "Payment for services rendered",
        "createdAt": "2026-03-21 12:13:53"
      }
    ]
  }
}

Fetching a payout by source reference

You can look up a payout using the source_reference you provided when initiating it. Make a GET request to payout/transaction-by-source-reference/{sourceReference}:

curl -X GET "https://atlas.tryduplo.com/api/v1/payout/transaction-by-source-reference/SRC_PAYOUT_001" \
  -H "Authorization: Bearer your_api_key" \
  -H "Accept: application/json"

On a successful request, you'll receive the payout transaction details:

JSON

{
  "requestId": "abcd1234-5678-90ef-ghij-1234567890kl",
  "requestTimestamp": "2026-03-20 09:15:00",
  "message": "Payout transaction fetched successfully.",
  "statusCode": 200,
  "data": {
    "id": "019914a8-c4d0-7131-a5c9-b008f622813a",
    "recipientAccountName": "John Doe",
    "recipientAccountNumber": "0123456789",
    "recipientBankName": "Kuda Microfinance Bank",
    "sourceReference": "SRC_PAYOUT_001",
    "reference": "TRN_QELKDOVYYCFV",
    "paymentChannel": "Bank Transfer",
    "sessionId": null,
    "narration": "Payment for services rendered",
    "status": "Pending"
  }
}

If no payout is found for the provided source reference, the API returns a 404 response.

Webhook notifications

Atlas sends webhook notifications when a payout status changes, allowing you to track completion in real-time without polling the API. You will receive an OUT_FLOW_PENDING_EVENT when the payout is initiated and an OUT_FLOW_SUCCESS_EVENT when it completes. If the payout fails, you will receive an OUT_FLOW_FAILED_EVENT.

See the webhook events reference for the full payload shapes.

Learn how to configure and verify webhooks in the Configuring Webhooks guide.