Initiate Bank Payout

Initiate a single bank-transfer payout from the authenticated business wallet.

Endpoint

POST

/api/v1/payout/bank-transfer

Authorization

BearerAuth

AuthorizationBearer

In: header

Request Body

application/json

account_number: string
bank_code: string
bank_name: string
account_name: string
amount: number (Format float)
narration: string
save_as_beneficiary?: boolean
type: string
currency: string
source_reference?: string

Response Body

200 application/json

400 application/json

401 application/json

403 application/json

422 application/json

500 application/json

503 application/json

cURL Example

curl -X POST "https://atlas.tryduplo.com/api/v1/payout/bank-transfer" \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "1234567890",
    "bank_code": "000000",
    "bank_name": "Test Bank",
    "account_name": "John Doe",
    "amount": 200,
    "narration": "Payment for services rendered",
    "type": "bank_transfer",
    "currency": "NGN"
  }'

Sample Responses

Successful Response

{
  "id": "019914a8-c4d0-7131-a5c9-b008f622813a",
  "recipientAccountName": "Test User",
  "recipientAccountNumber": "123443231",
  "recipientBankName": "Access Bank Plc",
  "sourceReference": "SRC_PAYOUT_001",
  "reference": "TRN_R67QZJVLLY",
  "paymentChannel": "Bank Transfer",
  "sessionId": "1SDW323RWD234FRGTD24F3R22",
  "narration": "Sending money ...",
  "amount": {
    "value": 20000,
    "currency": "NGN",
    "formatted": "NGN 200.00"
  },
  "balance": {
    "value": 10000,
    "currency": "NGN",
    "formatted": "NGN 100.00"
  },
  "status": "Pending",
  "fee": [
    {
      "id": "019914a8-c4d0-7131-a5c9-b008f622813a",
      "recipientAccountName": "Test User",
      "recipientAccountNumber": "123443231",
      "recipientBankName": "Access Bank Plc",
      "sourceReference": "SRC_PAYOUT_001",
      "reference": "TRN_R67QZJVLLY",
      "paymentChannel": "Bank Transfer",
      "sessionId": "1SDW323RWD234FRGTD24F3R22",
      "narration": "Sending money ...",
      "amount": {
        "value": 20000,
        "currency": "NGN",
        "formatted": "NGN 200.00"
      },
      "balance": {
        "value": 10000,
        "currency": "NGN",
        "formatted": "NGN 100.00"
      },
      "status": "Pending"
    }
  ]
}

Error Responses

400 Bad Request

{
  "requestId": "f006ad7b-096c-4254-8c7e-2d23a55b0b0e",
  "requestTimestamp": "2025-09-04 11:49:40",
  "message": "Invalid request data or insufficient funds.",
  "statusCode": 400
}

401 Unauthorized

{
  "requestId": "f006ad7b-096c-4254-8c7e-2d23a55b0b0e",
  "requestTimestamp": "2025-09-04 11:49:40",
  "message": "Invalid API key.",
  "statusCode": 401
}

403 Forbidden

{
  "requestId": "f006ad7b-096c-4254-8c7e-2d23a55b0b0e",
  "requestTimestamp": "2025-09-04 11:49:40",
  "message": "Incorrect PIN or access denied.",
  "statusCode": 403
}

422 Unprocessable Entity

{
  "requestId": "f006ad7b-096c-4254-8c7e-2d23a55b0b0e",
  "requestTimestamp": "2025-09-04 11:49:40",
  "message": "The given data was invalid.",
  "errors": {
    "account_number": [
      "The account number must be valid."
    ],
    "amount": [
      "The amount must be greater than 0."
    ]
  },
  "statusCode": 422
}

500 Internal Server Error

{
  "requestId": "f006ad7b-096c-4254-8c7e-2d23a55b0b0e",
  "requestTimestamp": "2025-09-04 11:49:40",
  "message": "An error occurred while processing your request.",
  "statusCode": 500
}

503 Service Unavailable

{
  "requestId": "f006ad7b-096c-4254-8c7e-2d23a55b0b0e",
  "requestTimestamp": "2025-09-04 11:49:40",
  "message": "Banking service is temporarily unavailable.",
  "statusCode": 503
}