Initiate Transfer
Send money to an existing transfer recipient through bank transfer, mobile money, or other supported channels. Recipients must be created before initiating transfers.Endpoint
POST/transfer/initiate
Headers
| Name | Type | Required | Description |
|---|---|---|---|
Authorization | string | Required | Bearer token with your secret API key |
Content-Type | string | Required | Must be application/json |
Idempotency-Key | string | Recommended | Unique key to prevent duplicate transfers |
Request Body
Source of funds for the transferAvailable sources:
balance- Transfer from your PayVessel wallet balancecard- Charge a saved card authorization (coming soon)
Transfer amount in the smallest currency unit (kobo for NGN, pesewas for GHS, etc.)
For ₦1,000.00, send
"100000" (1000 × 100 kobo)Recipient code from the Create Recipient endpoint response
Reason for the transfer (optional but recommended for compliance)Common reasons:
salary, bonus, refund, payment, gift, loan_repayment, business_paymentUnique transfer reference. If not provided, PayVessel will generate one automatically
Transfer currency (must match recipient’s currency)Supported currencies:
NGN, GHS, KES, ZAR, USD, GBP, EURDescription that appears on the recipient’s bank statement (max 100 characters)
Additional information about the transfer in key-value pairs
Example Request
Response
Request status indicator -
"success" or "error"Human-readable message describing the result
Transfer data object
Example Response
Transfer Status Guide
Understanding transfer statuses is crucial for proper transfer management:pending
pending
Transfer ProcessingThe transfer has been initiated and is being processed by the bank or payment provider.What to expect:
- Processing time: 0-30 minutes for most transfers
- Bank transfers: Can take up to 24 hours
- Mobile money: Usually instant to 15 minutes
- Monitor status via webhooks or verification endpoint
- No action required from your side
otp
otp
OTP RequiredTransfer requires OTP verification to complete (usually for high-value transfers).What to do:
- Use the Complete OTP Transfer endpoint
- OTP will be sent to your registered phone number
- OTP expires in 10 minutes
- Transfer amount > ₦100,000
- First-time recipient transfers
- Flagged by fraud detection
success
success
Transfer CompletedThe transfer has been successfully processed and funds delivered to the recipient.Confirmation:
- Funds debited from your balance
- Recipient has received the money
- Transfer is final and cannot be reversed
- Instant transfers: Immediate
- Regular bank transfers: 0-30 minutes
- Inter-bank transfers: Up to 24 hours
failed
failed
Transfer FailedThe transfer could not be completed. Common reasons include:
- Invalid recipient account
- Recipient account issues
- Network timeout
- Compliance restrictions
- Funds are automatically refunded to your balance
- Refund typically takes 5-10 minutes
- Check
gateway_responsefor specific failure reason
reversed
reversed
Transfer ReversedA previously successful transfer has been reversed by the bank or payment provider.Common causes:
- Recipient account closed
- Fraud detection
- Bank reversal
- Compliance issues
- Funds automatically refunded to your balance
- Contact support for detailed reversal reason
Fee Structure
PayVessel charges competitive fees for transfers based on amount and destination:- Nigerian Banks (NGN)
- Mobile Money
- International
| Amount Range | Fee |
|---|---|
| ₦100 - ₦5,000 | ₦10 |
| ₦5,001 - ₦50,000 | ₦25 |
| ₦50,001 - ₦100,000 | ₦50 |
| Above ₦100,000 | ₦100 |
- Bank stamp duty: ₦50 (for transfers > ₦10,000)
- VAT: 7.5% of PayVessel fee
Integration Patterns
- Salary Payments
- Customer Refunds
- Vendor Payments
- Withdrawal Processing
Best Practices
Check Balance First
Always verify sufficient balance before initiating transfers to avoid failures
Use Idempotency Keys
Implement idempotency keys to prevent accidental duplicate transfers
Handle OTP Flows
Implement proper OTP handling for high-value transfers
Monitor Status
Use webhooks or verification endpoints to track transfer status
Meaningful References
Use descriptive, unique references for easier tracking and reconciliation
Store Metadata
Include relevant metadata for audit trails and reporting
Error Handling
Insufficient Balance
Insufficient Balance
Error Code:
insufficient_balanceSolution:- Check your wallet balance using the Get Balance endpoint
- Fund your wallet before retrying the transfer
- Consider the fees in your balance calculation
Invalid Recipient
Invalid Recipient
Error Code:
invalid_recipientSolution:- Verify the recipient code exists and is active
- Check if recipient account is still valid
- Recreate recipient if account details changed
Transfer Limits
Transfer Limits
Error Code:
transfer_limit_exceededSolution:- Check your account transfer limits
- Consider breaking large transfers into smaller amounts
- Contact support to increase limits if needed
Next Steps
After initiating a transfer:Verify Transfer
Check the status and details of your transfer
Complete OTP
Complete OTP verification for pending transfers
List Transfers
View all your transfer history
Bulk Transfers
Send money to multiple recipients at once
Webhook Events
This endpoint triggers the following webhook events:transfer.pending- Transfer initiated and processingtransfer.success- Transfer completed successfullytransfer.failed- Transfer failedtransfer.reversed- Transfer was reversed
