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"
}
'

import requests

url = "https://api.payvessel.com/pms/api/external/request/wallet/transfer/"

payload = {
    "amount": "15000.00",
    "account_number": "0123456789",
    "bank_code": "999991",
    "account_name": "John Doe",
    "narration": "Vendor payout - March",
    "reference": "PAYOUT_2026_0001",
    "otp": "123456"
}
headers = {
    "api-key": "<api-key>",
    "api-secret": "<api-secret>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'api-key': '<api-key>',
    'api-secret': '<api-secret>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({
    amount: '15000.00',
    account_number: '0123456789',
    bank_code: '999991',
    account_name: 'John Doe',
    narration: 'Vendor payout - March',
    reference: 'PAYOUT_2026_0001',
    otp: '123456'
  })
};

fetch('https://api.payvessel.com/pms/api/external/request/wallet/transfer/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.payvessel.com/pms/api/external/request/wallet/transfer/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '15000.00',
    'account_number' => '0123456789',
    'bank_code' => '999991',
    'account_name' => 'John Doe',
    'narration' => 'Vendor payout - March',
    'reference' => 'PAYOUT_2026_0001',
    'otp' => '123456'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "api-key: <api-key>",
    "api-secret: <api-secret>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payvessel.com/pms/api/external/request/wallet/transfer/"

	payload := strings.NewReader("{\n  \"amount\": \"15000.00\",\n  \"account_number\": \"0123456789\",\n  \"bank_code\": \"999991\",\n  \"account_name\": \"John Doe\",\n  \"narration\": \"Vendor payout - March\",\n  \"reference\": \"PAYOUT_2026_0001\",\n  \"otp\": \"123456\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("api-secret", "<api-secret>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.payvessel.com/pms/api/external/request/wallet/transfer/")
  .header("api-key", "<api-key>")
  .header("api-secret", "<api-secret>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"amount\": \"15000.00\",\n  \"account_number\": \"0123456789\",\n  \"bank_code\": \"999991\",\n  \"account_name\": \"John Doe\",\n  \"narration\": \"Vendor payout - March\",\n  \"reference\": \"PAYOUT_2026_0001\",\n  \"otp\": \"123456\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.payvessel.com/pms/api/external/request/wallet/transfer/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["api-secret"] = '<api-secret>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"amount\": \"15000.00\",\n  \"account_number\": \"0123456789\",\n  \"bank_code\": \"999991\",\n  \"account_name\": \"John Doe\",\n  \"narration\": \"Vendor payout - March\",\n  \"reference\": \"PAYOUT_2026_0001\",\n  \"otp\": \"123456\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

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"
}
'

import requests

url = "https://api.payvessel.com/pms/api/external/request/wallet/transfer/"

payload = {
    "amount": "15000.00",
    "account_number": "0123456789",
    "bank_code": "999991",
    "account_name": "John Doe",
    "narration": "Vendor payout - March",
    "reference": "PAYOUT_2026_0001",
    "otp": "123456"
}
headers = {
    "api-key": "<api-key>",
    "api-secret": "<api-secret>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'api-key': '<api-key>',
    'api-secret': '<api-secret>',
    'Content-Type': '<content-type>'
  },
  body: JSON.stringify({
    amount: '15000.00',
    account_number: '0123456789',
    bank_code: '999991',
    account_name: 'John Doe',
    narration: 'Vendor payout - March',
    reference: 'PAYOUT_2026_0001',
    otp: '123456'
  })
};

fetch('https://api.payvessel.com/pms/api/external/request/wallet/transfer/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.payvessel.com/pms/api/external/request/wallet/transfer/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '15000.00',
    'account_number' => '0123456789',
    'bank_code' => '999991',
    'account_name' => 'John Doe',
    'narration' => 'Vendor payout - March',
    'reference' => 'PAYOUT_2026_0001',
    'otp' => '123456'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "api-key: <api-key>",
    "api-secret: <api-secret>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payvessel.com/pms/api/external/request/wallet/transfer/"

	payload := strings.NewReader("{\n  \"amount\": \"15000.00\",\n  \"account_number\": \"0123456789\",\n  \"bank_code\": \"999991\",\n  \"account_name\": \"John Doe\",\n  \"narration\": \"Vendor payout - March\",\n  \"reference\": \"PAYOUT_2026_0001\",\n  \"otp\": \"123456\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-key", "<api-key>")
	req.Header.Add("api-secret", "<api-secret>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.payvessel.com/pms/api/external/request/wallet/transfer/")
  .header("api-key", "<api-key>")
  .header("api-secret", "<api-secret>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"amount\": \"15000.00\",\n  \"account_number\": \"0123456789\",\n  \"bank_code\": \"999991\",\n  \"account_name\": \"John Doe\",\n  \"narration\": \"Vendor payout - March\",\n  \"reference\": \"PAYOUT_2026_0001\",\n  \"otp\": \"123456\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.payvessel.com/pms/api/external/request/wallet/transfer/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["api-secret"] = '<api-secret>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"amount\": \"15000.00\",\n  \"account_number\": \"0123456789\",\n  \"bank_code\": \"999991\",\n  \"account_name\": \"John Doe\",\n  \"narration\": \"Vendor payout - March\",\n  \"reference\": \"PAYOUT_2026_0001\",\n  \"otp\": \"123456\"\n}"

response = http.request(request)
puts response.read_body

{
  "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

string

required

Amount to transfer in the smallest currency unit (e.g. "15000.00" for ₦15,000.00)

string

required

Destination bank account number

string

required

Destination bank code (see bank list endpoint for available codes)

string

Optional account name for your own records

string

Description that may appear on the beneficiary’s statement

string

required

Unique transfer reference for idempotency and reconciliation

Must be unique across all your transfers

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

Show child attributes

Getting Started

Transactions

Virtual Accounts

Issuing

Transfer

Wallets

Identity Verification

Value Added Services

Webhook

Initiate Transfer

Endpoint

Request Body

Example request

Example cURL

Response

Headers

Body

Response

​Endpoint

​Request Body

​Example request

​Example cURL

​Response

​Related endpoints

Headers

Body

Response

Endpoint

Request Body

Example request

Example cURL

Response

Related endpoints