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://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://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://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://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": ""
}