Skip to main content
POST
/
pms
/
api
/
external
/
request
/
wallet
/
transfer
/
Initiate Transfer
curl --request POST \
  --url https://api.payvessel.com/pms/api/external/request/wallet/transfer/ \
  --header 'Content-Type: <content-type>' \
  --header 'api-key: <api-key>' \
  --header 'api-secret: <api-secret>' \
  --data '
{
  "amount": "15000.00",
  "account_number": "0123456789",
  "bank_code": "999991",
  "account_name": "John Doe",
  "narration": "Vendor payout - March",
  "reference": "PAYOUT_2026_0001",
  "otp": "123456"
}
'
{
  "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"
  }
}
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/

​
Request Body

​
amount
string
required
Amount to transfer in the smallest currency unit (e.g. "15000.00" for ₦15,000.00)
​
account_number
string
required
Destination bank account number
​
bank_code
string
required
Destination bank code (see bank list endpoint for available codes)
​
account_name
string
Optional account name for your own records
​
narration
string
Description that may appear on the beneficiary’s statement
​
reference
string
required
Unique transfer reference for idempotency and reconciliation
Must be unique across all your transfers
​
otp
string
One-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.

Headers

​
api-key
string
required

Your Payvessel public API key

​
api-secret
string
required

Your Payvessel secret

​
Content-Type
enum<string>
required

Request content type

Available options:
application/json

Body

application/json
​
amount
string
required

Amount to transfer in the smallest currency unit

​
account_number
string
required

Destination bank account number

​
bank_code
string
required

Destination bank code

​
reference
string
required

Unique transfer reference

​
account_name
string

Optional account name for records

​
narration
string

Description for beneficiary statement

​
otp
string

One-time password when required

Response

200 - application/json

Transfer initiated successfully

​
status
boolean

Request status

​
message
string

Response message

​
data
object