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 provide the following parameters:

account_number (required): The recipient's 10-digit bank account number.
bank_code (required): The recipient's bank code. See Getting bank codes below.
bank_name (required): The recipient's bank name.
account_name (required): The recipient's account name. See Getting account name below.
amount (required): The amount to send in naira, for example 5000 for ₦5,000. It must be between ₦100 and ₦250,000,000.
currency (required): The currency code. Use NGN.
source_reference (required): A unique string you provide to identify the payout. Atlas rejects a second payout with the same value, and you can use it to look the payout up later with the Get Payout by Source Reference endpoint.
narration (optional): A description of the payment, between 3 and 100 characters. It appears on the recipient's bank statement.
save_as_beneficiary (optional): Set to true to save the recipient as a beneficiary on your business.

Getting bank codes

Before initiating a payout, you need the recipient's bank code. Make a GET request to banking/banks/{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/banks/${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

Confirm the recipient's account before you send money by making a POST request to banking/name-enquiry with the account number, bank code, and currency. The response returns the account name registered with the recipient's bank, so you can check it against the person you intend to pay.

Atlas runs the same name enquiry again when you initiate the payout. It rejects the payout if the account can't be resolved, and it uses the name the bank returns rather than the account_name in your request.

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

Initiating a single payout

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

Your Atlas wallet must cover the payout amount plus fees, or Atlas rejects the request.

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": "090267",
    "bank_name": "Kuda Microfinance Bank",
    "account_name": "John Doe",
    "amount": 5000,
    "narration": "Payment for services rendered",
    "currency": "NGN",
    "source_reference": "SRC_PAYOUT_001"
  }'

On a successful request, you'll receive a response confirming the payout has been initiated. The payout starts in the Pending state, and the fee array lists each fee charged on top of the amount:

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": 5000,
      "currency": "NGN",
      "formatted": "NGN5000"
    },
    "balance": {
      "value": 95000,
      "currency": "NGN",
      "formatted": "NGN95000"
    },
    "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": 50,
          "currency": "NGN",
          "formatted": "NGN50"
        },
        "balance": {
          "value": 94950,
          "currency": "NGN",
          "formatted": "NGN94950"
        },
        "status": "Pending",
        "narration": "Payment for services rendered",
        "createdAt": "2026-03-21 12:13:53"
      }
    ]
  }
}

If you send a source_reference that you have already used, Atlas rejects the request with the message The provided source reference is already in use. Please provide a unique source reference.

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-21 12:15:00.000",
  "message": "Payout transaction fetched 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": "100004260321121351000123456789",
    "parentTransactionReference": null,
    "reference": "TRN_QELKDOVYYCFV",
    "amount": {
      "value": 5000,
      "currency": "NGN",
      "formatted": "NGN5000"
    },
    "balance": {
      "value": 95000,
      "currency": "NGN",
      "formatted": "NGN95000"
    },
    "status": "Successful",
    "narration": "Payment for services rendered",
    "createdAt": "2026-03-21 12:13:51"
  }
}

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, then either an OUT_FLOW_SUCCESS_EVENT when it completes or an OUT_FLOW_FAILED_EVENT if it fails. See payout states for what each state means.

See the webhook events reference for the full payload shapes.

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