Transfer to External Wallet
Send money to external bank accounts or wallets securely using Payvessel’s Transfer APIs. This guide covers the end-to-end flow for moving funds from your managed wallet to a recipient.Integration Flow
To complete a transfer successfully, you must follow these three steps:1. Create a Recipient
Before you can send money, you must register the recipient’s details (bank account or mobile money wallet) and verify them. Payvessel automatically validates the account details during this step.- Action: Call the Create Recipient endpoint.
- Result: You will receive a
recipient_code(e.g.,RCP_xyz789...).
2. Initiate the Transfer
Once you have a recipient code, you can trigger the fund movement.- Action: Call the Initiate Transfer endpoint using the
recipient_code. - Idempotency: We highly recommend using an
Idempotency-Keyheader to prevent duplicate transfers in case of network retries.
3. Track Status
Transfers can be instant or take some time depending on the channel.- Webhook (Recommended): Configure a Webhook to receive real-time updates when the status changes to
success,failed, orreversed. - Polling: Alternatively, you can use the Verify Transfer endpoint to check the status manually.
Technical Reference
| Item | Details |
|---|---|
| Base URLs | https://api.payvessel.com (Prod) https://sandbox.payvessel.com (Test) |
| Authentication | Bearer Token (Secret Key) |
| Supported Channels | NUBAN (Bank), Mobile Money |
| Currencies | NGN, GHS, KES, ZAR, USD, GBP, EUR |
Best Practices
- Verify Balance: Check your managed wallet balance before initiating transfers to avoid
insufficient_balanceerrors. - Handle OTP: Some high-value transfers may require an OTP for security. Be prepared to handle the
otpstatus response. - Detailed Narrations: Use clear narrations (e.g., “Invoice #1234”) to help your customers reconcile their bank statements.