> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payvessel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Initiate Transfer
> Send money from your managed wallet to a bank account
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 to transfer in the smallest currency unit (e.g. `"15000.00"` for ₦15,000.00)
Destination bank account number
Destination bank code (see bank list endpoint for available codes)
Optional account name for your own records
Description that may appear on the beneficiary's statement
Unique transfer reference for idempotency and reconciliation
Must be unique across all your transfers
One-time password when required by your security settings
### Example request
```json theme={null}
{
"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
```bash theme={null}
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:
```json theme={null}
{
"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.
## Related endpoints
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**.
## OpenAPI
````yaml POST /pms/api/external/request/wallet/transfer/
openapi: 3.1.0
info:
title: PayVessel API
description: >-
PayVessel API for accepting payments, sending money, verifying identities,
and managing wallets
version: 1.0.0
servers:
- url: https://api.payvessel.com
- url: https://sandbox.payvessel.com
security:
- {}
paths:
/pms/api/external/request/wallet/transfer/:
post:
tags:
- Transfers
summary: Initiate Transfer
description: Send money from your managed wallet to a bank account
parameters:
- name: api-key
in: header
description: Your Payvessel public API key
required: true
schema:
type: string
- name: api-secret
in: header
description: Your Payvessel secret
required: true
schema:
type: string
- name: Content-Type
in: header
description: Request content type
required: true
schema:
type: string
enum:
- application/json
example: application/json
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateTransferRequest'
example:
amount: '15000.00'
account_number: '0123456789'
bank_code: '999991'
account_name: John Doe
narration: Vendor payout - March
reference: PAYOUT_2026_0001
otp: '123456'
responses:
'200':
description: Transfer initiated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateTransferResponse'
example:
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
components:
schemas:
InitiateTransferRequest:
type: object
required:
- amount
- account_number
- bank_code
- reference
properties:
amount:
type: string
description: Amount to transfer in the smallest currency unit
account_number:
type: string
description: Destination bank account number
bank_code:
type: string
description: Destination bank code
account_name:
type: string
description: Optional account name for records
narration:
type: string
description: Description for beneficiary statement
reference:
type: string
description: Unique transfer reference
otp:
type: string
description: One-time password when required
InitiateTransferResponse:
type: object
properties:
status:
type: boolean
description: Request status
message:
type: string
description: Response message
data:
type: object
properties:
reference:
type: string
description: Transfer reference
session_id:
type: string
description: Session ID for status tracking
amount:
type: string
description: Transfer amount
status:
type: string
description: Transfer status
destination_account_number:
type: string
description: Destination account number
destination_bank_code:
type: string
description: Destination bank code
destination_account_name:
type: string
description: Destination account name
````