Skip to main content
Use this endpoint to initiate a single payout from your business wallet to a beneficiary’s bank account. The transfer debits your wallet and credits the destination account.
Transfers are irreversible once completed. Always validate account details and confirm available balance before initiating a transfer.

​
Endpoint

POST /pms/api/external/request/wallet/transfer/

​
Headers

NameLocationTypeRequiredDescription
api-keyheaderstringYesBusiness API key
api-secretheaderstringYesBusiness API secret
Content-TypeheaderstringYesMust be application/json

​
Request body

FieldTypeRequiredDescription
amountstringYesAmount to transfer (e.g. "15000.00")
account_numberstringYesDestination bank account number
bank_codestringYesDestination bank code
account_namestringNoOptional account name for your own records
narrationstringNoDescription that may appear on the beneficiary’s statement
referencestringYesUnique transfer reference for idempotency and reconciliation
otpstringSometimesOne‑time password when required by your security settings

​
Example request

{
  "amount": "15000.00",
  "account_number": "0123456789",
  "bank_code": "999991",
  "account_name": "John Doe",
  "narration": "Vendor payout - March",
  "reference": "PAYOUT_2026_0001",
  "otp": "123456"
}

​
Example cURL

curl -X POST "https://api.payvessel.com/pms/api/external/request/wallet/transfer/" \
  -H "api-key: YOUR_API_KEY" \
  -H "api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "15000.00",
    "account_number": "0123456789",
    "bank_code": "999991",
    "account_name": "John Doe",
    "narration": "Vendor payout - March",
    "reference": "PAYOUT_2026_0001",
    "otp": "123456"
  }'

​
Response

On success you receive a JSON response with high‑level status and details about the initiated transfer: 
{
  "status": true,
  "message": "Transfer initiated successfully",
  "data": {
    "reference": "PAYOUT_2026_0001",
    "session_id": "SESSION_123456789",
    "amount": "15000.00",
    "status": "pending",
    "destination_account_number": "0123456789",
    "destination_bank_code": "999991",
    "destination_account_name": "John Doe"
  }
}
The initial status will typically be pending while the receiving bank processes the transfer. Use these endpoints together with Initiate Transfer to build a complete payout flow:
  • Get wallet balance — check available funds before sending money.
  • Get bank list — fetch supported banks and their bank codes.
  • Validate account — confirm account number + bank code matches the expected account name.
  • Transfer status — confirm whether a transfer is pending, success, or failed using reference and session_id.
  • Wallet transactions — retrieve past transfers for reconciliation and reporting.
For high‑level guidance and examples of when to use single vs bulk transfers, see the Single Transfers and Bulk Transfers guides under Send Money & Payouts.