Payvice offers various Value Added Services (VAS), ranging from Airtime purchase, Bill payment, Toll Gate fee, Internet subscription to Cable TV. The lines below serve as a guidance to third party application willing to consume Payvice services over HTTP REST API or other protocol supported.

Consumming the API

While this page is enough to see through its code and get you started with, you will need to signup to https://www.payvice.com to get your wallet ID and login credentials. Sure you would have obtained your payvice credentials Wallet ID, Username and Password.

HTTP POST Request - REST

To consume Payvice API, the following two steps are required: LOOKUP call and PURCHASE for the topup

Lookup

          
            

{ "vice_id": YOUR_WALLET_ID, "user_name": YOUR_PAYVICE_USERNAME } URL: https://www.payvice.com/api/tran/auth2/lookup HTTP VERB: POST

Lookup Response

The lookup call is use to generate a request TOKEN which has a lifespan of two minutes and will be used to validate a purchase request. On successful LOOKUP request, below response will be sent. Keep your TOKEN and make sure the PURCHASE request is sent within the lifespan of your generated token - 2 minutes.

        



          {
          "vice_id": "12345xxx",
          "token": "474eef6dca8dd57xxxxxxxxxx******xxxxxxxxxx077834b61f6b1",
          "status": 0,
          "message": "Authenticated successfully"
        }



      
    

Purchase Request Parameters

After a successful LOOKUP request, as earlier stated - within the two-minute lifespan of your token, the sample code below demonstrate how to call for a purchase request. Purchase request include a specific service the third party intend to consume from Payvice, represented by its service code as listed here below:

MTNVTU - Request to purchase MTN Airtime
ETISALTVTU - Request to purchase 9Mobile Aitime
GLOVTU - Request to purchase Glo Airtime
AIRTELVTU - Request to purchase Airtel Airtime

IE - Request to pay for Ikeja Electricity bill

DSTV - Request to subscribe for Multichoice DSTV subscription
GOTV - Request to subscribe for Multichoice GOTV subscription

HTTP REST REQUEST

Up to this point you have a clear understanding of consumming Payvice API if you have successfully generated a transaction TOKEN

Next, we will proceed with sample request for TOPUP
Below code is an example of purchasing MTN Virtual Topup - MTNVTU

      

        {
        "vice_id": "123xxxx", 
        "user_name": "johndoe@payvice.com",
        "amount": "50", 
        "phone": "0810xxxx000", 
        "service": "MTNVTU", 
        "auth": "xxx",
        "token" : "474eef6dca8dd57xxxxxxxxxx******xxxxxxxxxx077834b61f6b1",
        "pwd" : "HiddenSecretxxxx"
      }

      URL:        https://www.payvice.com/api/tran/auth2/purchase
      HTTP VERB:  POST
    
  

Where:

vice_id - Your Payvice wallet ID
user_name - Your Payvice usename
amount - Transaction amount - minimum of 50
phone - Phone number to recharge
service - Request parameter specifying the service to pay for
auth - Your Payvice 4-digit transaction code
token - Transaction token gotten from LOOKUP call
pwd - Your Payvice password

Topup Response

On successful topup request, below response will be returned

    

     {
     "message": "Topup completed successfully",
     "status": 1,
     "date": "30/01/2018 07:27:50",
     "txn_ref": "5a701e76af746"
   }
 

message - Response message
status - State of the request where 1 is Approved or Completed successfully
date - Response time in dd/mm/YYYY H:i:s format
txn_ref - Your transaction reference code

Ikeja Electric Request - IE

Just like the TOPUP Request, Payvice has a defined parameters that need to passed for a request to pay for electricity bill for Ikeja Electric covered zone

The first request for IE is to validate customer name existence. This allow you to get confirmation from your customer to determine if payment is going to be made to the right owner.

Sample JSON data below define request parameters for IE name enquiry validation

  

   {
   "vice_id": "123xxxxx", 
   "user_name": "johndoe@payvice.com",
   "amount": 10, 
   "phone": "0810xxxx000", 
   "service": "IE", 
   "auth": "xxxx",
   "token" : "474eef6dca8dd57xxxxxxxxxx******xxxxxxxxxx077834b61f6b1",
   "pwd" : "HiddenSecretxxx",
   "cus_meter": "",
   "cus_account": "0100xxxxxx",
   "type": "getcus",
   "service_type": "pay"
 }

 URL:        https://www.payvice.com/api/tran/auth2/purchase
 HTTP VERB:  POST

A few things to be noted here:

service - Always send IE as to indicate Ikeja Electricity transaction
cus_meter - Contains value of customer number if service_type is vend as to indicate a Token transaction
type - Remains a static value of getcus to enable validation if customer exists
cus_account - Contains value of customer account number if service_type is pay as to indicate payment for postpaid customer

service_type - Should be vend or pay as explained here-above.

Ikeja Electric Name Enquiry Response

On successful IE name inquiry request, below response will be returned

  

   {
   "message": "Customer name validation was successful",
   "status": 1,
   "date": "13/03/2018 14:52:24",
   "cust_name": "JOHN DOE",
   "cust_address": "01, JUPITER ST, MARS"
 }

message - Response message
status - State of the request where 1 is Approved or Completed successfully
date - Response time in dd/mm/YYYY H:i:s format
txn_ref - Your transaction reference code
cust_name - The name tied to the account or meter number in Ikeja Electric record
cust_address - The address tied to the account or meter number in Ikeja Electric record

Ikeja Electric Purchase Request

Just as the name enquiry validation request, the purchase request will indicate that user has validated and approved the details returned by the validation request [ Name and Address ] and the puprchase request is to purchase the energy.

Still within the lifespan of the TOKEN goten from the lookup request, the below request sample show how to call for purchase.

  

   {
   "vice_id": "123xxxxx", 
   "user_name": "johndoe@payvice.com",
   "amount": 10, 
   "phone": "0810xxxx000", 
   "service": "IE", 
   "auth": "xxxx",
   "token" : "474eef6dca8dd57xxxxxxxxxx******xxxxxxxxxx077834b61f6b1",
   "pwd" : "HiddenSecretxxx",
   "cus_meter": "",
   "cus_account": "0100xxxxxx",
   "type": "getcus",
   "service_type": "pay"
 }

 URL:        https://www.payvice.com/api/tran/auth2/ie/tran
 HTTP VERB:  POST

A few things to be noted here:

service - Always send IE as to indicate Ikeja Electricity transaction
cus_meter - Contains value of customer number if service_type is vend as to indicate a Token transaction
type - Remains a static value of getcus to enable validation if customer exists
cus_account - Contains value of customer account number if service_type is pay as to indicate payment for postpaid customer

service_type - Should be vend or pay as explained here-above.

Ikeja Electric Purchase Response

On successful IE purchase request, below response will be returned

VEND Request Response

  

   {
   "message": "Credit purchase was successful",
   "status": 1,
   "date": "13/03/2018 16:15:07",
   "txn_ref": "5aa7f90b3b5dd",
   "token_value": "700xxxxxxxxxxxx24127",
   "address": "7, ROAD NAME STREET, AREA - TOWN DETAILS",
   "payer": "VANESA DOE"
 }

PAY Request Response

  

    {
    "message": "Completed successfully",
    "status": 1,
    "date": "13/03/2018 16:24:09",
    "txn_ref": "5aa7fb290d97d",
    "address": "7, ROAD NAME STREET, AREA - TOWN DETAILS",
    "payer": "JOHN DOE"
  }

Enugu Electricy Integration

To make successful payment for Enugu Electicity for both prepaid and postpaid , you should always validate customer account/smart card number before making payment. This is to enable you check that payment is being made to the intended party.

Validate Customer Details

The sample request below shows how to get validate customers account numbers:

        
    
            {
              "vice_id": "18xxxxxx3", 
              "user_name": "michxxxxxxxxxda@mail.com",
              "pwd" : "xxxxxxxx",
              "meter": "45037595423",
              "type": "prepaid"
            }
    
              URL:  https://www.payvice.com/api/tran/enugu/lookup
        
              HTTP VERB:  POST    
      
    

Where:
vice_id is your Payvice Wallet ID
user_name is your Payvice username
pwd is your secure Payvice password
meter is your electricity account/smartcard number
type is your current subscription type/package

Below response will be returned, on successful lookup:

      
          {
              "status": 1,
              "error": false,
              "message": "Customer Validation Successful",
              "description": "Customer Validation Successful",
              "name": "Sxxxxxs Nxxxxu",
              "account": "45xxxxxx3",
              "type": "prepaid",
              "productCode": "F04F15047283749C9B7B06146BAFD95E5B373DE36D61ECACEB7C115C7A1B87B6CFCCAEA57A14E202240DDB89B15D7F8471F1194D9F77C2E98217E0097ED70773|eyJwcm9kdWN0IjoiRU5VR1VFTEVDVFJJQ0lUWSIsInR5cGUiOiJwcmVwYWlkIiwiYWNjb3VudCI6IjQ1MDM3NTk1NDIzIiwibmFtZSI6IlNseXZhbnVzIE5nd3UiLCJjdXN0b21lcklkIjoiQWJha3BhfDQ1MDM3NTk1NDIzfDExMTY0OTR8U2x5dmFudXMgTmd3dXxObyAxNTUgTmlrZSBMYWtlIFJvYWQgQWJha3BhIE5pa2UgRW51Z3VfMzAuOTNfUjJTXzAuMCJ9"
          }
      
    

Make Enugu Electricity Payment

The sample request below shows how to make successful payment request for Enugu Electricity.

        
    
              {
                  "vice_id": "18xxxxxxxx93", 
                  "user_name": "michxxxxxxxxxxxa@mail.com",
                  "pwd" : "xxxxxxxxxxxxxxxxxx",
                  "meter": "45037595423",
                  "type": "prepaid",
                  "amount": 100,
                  "phone": "081xxxxxxxxxx323",
                  "code": "F04F15047283749C9B7B06xxxxxxxxxxxxxxxxxx",
                  "name": "Slyvanus Ngwu",
                  "token": "7cef91d8ea5da1f2a1xxxxxxxxxxxxxxxxxxc5a3640b52113a5756f",
                  "auth": "XXXX"
              }
              URL: https://www.payvice.com/api/tran/auth2/enugu/pay
        
              HTTP VERB:  POST    
      
    

Where:
vice_id is your Payvice Wallet ID
user_name is your Payvice username
pwd is your secure Payvice password
meter is your electricity account/smartcard number
type is your current subscription type/package
code is the product code returned during previous lookup
name is the name of the customer returned during lookup

Making Multichoice Payment

To make payment for Multichoice DSTV or GOTV, there are few important steps to consider for a secure and safe payment. By safe we mean always consider to validate customer account/smart card number before making payment. This is to enable you check that payment is being made to the intended party.

Payvice also gives you the ability to select or make your users select from various subscription plans available for Multichoice DSTV or GOTV

Get Subscription Plans

The sample request below shows how to get subscription plans:

    

      { 

      "vice_id": "1234xxxxx",
      "user_name": "johndoe@payvice.com",
      "service": "DSTV", 
      "beneficiary": "1017xxxxx"

    }

    URL:        https://www.payvice.com/api/tran/auth2/bill/tv
    
    HTTP VERB:  POST


  

Where:
vice_id is your Payvice Wallet ID
user_name is your Payvice username
service indicate Multichoice service - DSTV or GOTV
beneficiary DSTV or GOTV smart card/account number

Below response will be returned, on successful request:

  

    {


    "message": "Subscription plans lookup was successful",
    "status": 1,
    "date": "18/04/2018 15:34:59",
    "plans": [
    {
    "name": "Active Package",
    "product_code": "AP",
    "amount": "1900.00"
  },
  {
  "name": "DStv French Touch",
  "product_code": "FRN7E36",
  "amount": "1400.00"
},
{
  "name": "DStv Great Wall",
  "product_code": "GWALLE36",
  "amount": "1000.00"
},
{
  "name": "DStv Indian",
  "product_code": "ASIAE36",
  "amount": "4800.00"
},
{
  "name": "DStv Compact",
  "product_code": "COMPE36",
  "amount": "6300.00"
},
{
  "name": "DStv Compact Plus",
  "product_code": "COMPLE36",
  "amount": "9900.00"
},
{
  "name": "DStv Family",
  "product_code": "COFAME36",
  "amount": "3800.00"
},
{
  "name": "DStv Premium",
  "product_code": "PRWE36",
  "amount": "14700.00"
}
]


}


Validate Customer Account

Below sample request will validate customer account or smart card number:

  

    { 

    "vice_id": "1234xxxxx",
    "user_name": "johndoe@payvice.com",
    "service": "DSTV", 
    "beneficiary": "10173xxxxxx"

  }

  URL:        https://www.payvice.com/api/tran/auth2/bill/validate

  HTTP VERB:  POST



Below response will be returned when validation is successful

  

    {
    "message": "Account validation was successful",
    "status": 1,
    "date": "18/04/2018 13:44:29",

    "customer": {

    "tran_id": "1924xxxx",
    "ref": "1183846xxxxxx",
    "response_code": "00",
    "fullname": "JOHN DOE",
    "unit": "DSTV"
  }


}


Making DSTV/GOTV Payment

When you have successfully validated the first two requests, the already-defined Payvice process of performing transaction remain the same. For the fact that your transaction TOKEN has a lifespan, we would advise you perform the 2 Multichoice calls before generating transaction token.

The sample code here shows how to make payment

  

    { 

    "vice_id": "1234xxxxx",
    "user_name": "johndoe@payvice.com",
    "auth": "xxxx",
    "token" : "474eef6dca8dd57xxxxxxxxxx******xxxxxxxxxx077834b61f6b1",
    "pwd" : "HiddenSecretxxx"
    "phone": "080873xxxxxx", 
    "service": "DSTV",
    "beneficiary": "10173xxxxx",
    "product_code": "AP"

  }

  URL:        https://www.payvice.com/api/tran/auth2/tv/pay

  HTTP VERB:  POST



On a successful subscription request, the following response will be returned

  

    {

    "message": "DSTV - Subscription was successful",
    "status": 1,
    "date": "18/04/2018 15:17:39",
    "txn_ref": "5ad761935c7ee"

  }


DSTV/GOTV Test

To test Multichoice transaction call the following endpoints:

  

    https://www.payvice.com/api/tran/auth2/bill/tv/test

    https://www.payvice.com/api/tran/auth2/bill/validate/test

    https://www.payvice.com/api/tran/auth2/tv/pay/test

  

Wallet to Wallet Transfer

Another advantage of Payvice is to enable users/third party application to do a wallet-to-wallet transfer

This request will enable you transfer fund from one wallet to another Wallet ID
The parameters accepted in the request are shown in the sample request below:

    

      { 

      "vice_id": "1234xxxxx",
      "user_name": "johndoe@payvice.com",
      "amount": 50,
      "beneficiary": "4567xxxx",
      "auth": "xxxx",
      "token" : "474eef6dca8dd57xxxxxxxxxx******xxxxxxxxxx077834b61f6b1",
      "pwd" : "HiddenSecretxxx"

    }

    URL:        https://www.payvice.com/api/tran/auth2/wallet/transfer
    
    HTTP VERB:  POST


  

Where TOKEN is your generated token on LOOKUP request
beneficiary is the wallet to transfer fund to
amount minimum of N50

TRANSFER Request Response

  

    {

    "message": "Fund transfered successfully",
    "status": 1,
    "date": "06/04/2018 16:02:50",
    "txn_ref": "5ac79a2a2af29"

  }


Possible Error Messages

Yes, it is possible to encounter some errors :)
As you can also imagine, like what happens when there's a missing parameter, invalid username, incorrect account number for IE
Below are some possible errors message that might be returned when consumming our API

When one of the combination of the following parameters is wrong or all values are worng: Wallet ID, Username, Password, Transaction PIN

  

   {
   "status": 0,
   "message": "Unknown user ID or wrong password"
 }


When the generated TOKEN as exceeded 2 minutes of its lifespan

  

   {
   "status": 0,
   "message": "Unauthorized API call. Token expired"
 }


When the request TOKEN or Wallet ID is invalid

  

    {
    "status": 0,
    "message": "Failed. Please check your token/Vice ID"
  }


When the same TOKEN is sent 2 times within 2 minutes of its lifespan

  

   {
   "status": 0,
   "message": "Unauthorized API call. Token already used"
 }


When the CUSMTOMER METER or ACCOUNT NUMBER for Ikeja Electric provided is not valid

  

    {
    "message": "Lookup failed. Customer information not found",
    "status": 0,
    "date": "30/01/2018 08:24:00"
  }


When the Wallet to TRANSFER to does not exist

  

    {

    "message": "Unknown Recipient wallet",
    "status": 0,
    "date": "06/04/2018 16:27:33",
    "txn_ref": "5ac79ff51dd14"

  }


Checking Previous Transaction

Sometime you might decide to check the status of previously generated token or transaction.

The sample call below demonstrate how you can achieve the REQUERY call

    

      {
      "vice_id": "123xxxxx", 
      "token": "474eef6dca8dd57xxxxxxxxxx******xxxxxxxxxx077834b61f6b1"
    }

    URL:         https://www.payvice.com/api/tran/auth0/requery
    HTTP VERB:   POST

  

where:

vice_id - Your Payvice wallet ID
token - Transaction token

Requery Response

Below response will be returned:

  

    {
    "status": 1,
    "txn_status": "declined",
    "txn_date": "13/11/2017 08:08:48",
    "vice_id": "123xxxxx",
    "txn_token": "474eef6dca8dd57xxxxxxxxxx******xxxxxxxxxx077834b61f6b1",
    "date": "01/02/2018 07:15:09"
  }