BANK Transfer API Integration
This section contains the recommended flow for integrating Bank Transfer services on the VTpass RESTful API.
The VTpass bank transfer API allows you to transfer funds from your VTpass account to another bank account.
Authentication
The VTpass API uses Basic Authentication.
It should be passed as a concatenated string like this
username:password
Please use the following details for authentication
Username: YourVtpassEmail
Password: YourPassword
Please create your authentication details by following the instructions here.
Available Endpoints
To integrate the VTpass Bank Transfer RESTful API, the endpoints below applies:
- Get Bank Variations (endpoint to get the various names of banks available)
- Verify Bank Account Number (endpoint to verify the customer account number)
- Transfer Funds (endpoint to make the actual transfer)
- Query transaction status
Always ensure you validate the customer’s bank account number.
ServiceID: bank-deposit
GET VARIATION CODES
Using a GET method, the VTpass variation code for bank names can be accessed with the endpoint below:
Live: https://api-service.vtpass.com/api/service-variations?serviceID=bank-deposit
Sandbox: https://sandbox.vtpass.com/api/service-variations?serviceID=bank-deposit
FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
N/A | N/A | N/A | N/A |
EXPECTED RESPONSE
{ "response_description": "000", "content": { "ServiceName": "Bank Deposit", "serviceID": "bank-deposit", "convinience_fee": "0 %", "varations": [ { "variation_code": "providus", "name": "Providus Bank", "variation_amount": "0.00", "fixedPrice": "Yes" }, { "variation_code": "gtb", "name": "GTBANK PLC", "variation_amount": "0.00", "fixedPrice": "Yes" }, { "variation_code": "uba", "name": "UBA - UNITED BANK FOR AFRICA PLC", "variation_amount": "0.00", "fixedPrice": "Yes" }, { "variation_code": "zenith", "name": "ZENITH BANK PLC", "variation_amount": "0.00", "fixedPrice": "Yes" }, ... ] } }
VERIFY BANK ACCOUNT NUMBER
Using a POST method, you can verify an account number with the following endpoint:
Live: https://api-service.vtpass.com/api/merchant-verify
Sandbox: https://sandbox.vtpass.com/api/merchant-verify
On Sandbox, please use the following bank account number to test:
Account Number: 1234567890
To simulate a failed bank account validation, please use any number apart from the one provided above as account number.
FIELDS | M/O | TYPE | DESCRIPTION |
billersCode | M | String | The bank account number you wish to transfer funds to.
On Sandbox use 1234567890 |
serviceID | M | String | Service ID as specified by VTpass. In this case, it is bank-deposit |
type | M | String | This is basically the bank variation you are trying to validate. It can be gtb for instance. |
EXPECTED RESPONSE
{ "code": "000", "content": { "account_name": "TESTIMETRY ADAMS" } }
PURCHASE PRODUCT (Payment)
Using a POST method, funds can be transferred for GTB bank with the endpoint below:
Live: https://api-service.vtpass.com/api/pay
Sandbox: https://sandbox.vtpass.com/api/pay
ServiceID: bank-deposit
On Sandbox, please use the following bank account number (sandbox) to test:
Account Number: 1234567890
To simulate a failed bank transfer, please use any number apart from the one provided above as account number.
FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
request_id | M | String | This is a unique reference with which you can use to identify and query the status of a given transaction after the transaction has been executed.
|
serviceID | M | String | Service ID as specified by VTpass. In this case, it is bank-deposit |
billersCode | M | String | The account number you wish to transfer funds to |
variation_code | M | String | This is the bank name. In this case gtb |
amount | M | Number | The amount (Naira) of funds you want to transfer. |
phone | M | Number | The phone number of the customer or recipient of this service |
EXPECTED RESPONSE
{ "code": "000", "content": { "transactions": { "status": "delivered", "product_name": "Bank Deposit", "unique_element": "08089980886", "unit_price": 1000, "quantity": 1, "service_verification": null, "channel": "api", "commission": 500, "total_amount": 500, "discount": null, "type": "Funds", "email": "sandbox@vtpass.com", "phone": "07061933309", "name": null, "convinience_fee": 0, "amount": 1000, "platform": "api", "method": "api", "transactionId": "1600780402886" } }, "response_description": "TRANSACTION SUCCESSFUL", "requestId": "34w0eid28p7849i00js09440oet00", "amount": "1000.00", "transaction_date": { "date": "2020-09-22 14:13:22.000000", "timezone_type": 3, "timezone": "Africa/Lagos" }, "purchased_code": "" }
QUERY TRANSACTION STATUS
Using a POST method, transaction status can be queried with the endpoint below:
LIVE: https://api-service.vtpass.com/api/requery
Sandbox: https://sandbox.vtpass.com/api/requery
FIELDS | Mandatory/Optional | TYPE | DESCRIPTION |
request_id | M | String | This is the reference with which you sent when purchasing a transaction after the transaction has been executed. |
EXPECTED RESPONSE
{ "code": "000", "content": { "transactions": { "status": "delivered", "product_name": "Bank Deposit", "unique_element": "08089980886", "unit_price": 1000, "quantity": 1, "service_verification": null, "channel": "api", "commission": 500, "total_amount": 500, "discount": null, "type": "Funds", "email": "sandbox@vtpass.com", "phone": "07061933309", "name": null, "convinience_fee": 0, "amount": "1000.00", "platform": "api", "method": "wallet", "transactionId": "1600780209397" } }, "response_description": "TRANSACTION SUCCESSFUL", "requestId": "34w0eid28p7849i00js09440oet", "amount": "1000.00", "transaction_date": { "date": "2020-09-22 14:10:09.000000", "timezone_type": 3, "timezone": "Africa/Lagos" }, "purchased_code": "" }