API

Delve Straight Into Development
Payvice - VAS API implementation.

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 such as 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.

MARKUP { 
"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.

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

Purchase Request Parameter

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

MARKUP { 
"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

Top Up Response

On successful topup request, below response will be returned:

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

Where:

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 -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.

MARKUP { 
"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.

MARKUP { 
"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.

MARKUP { 
"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 hould 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

MARKUP { 
"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

MARKUP { 
"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"
}

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:

MARKUP { 
"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
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:

MARKUP { 
"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:

MARKUP { 
"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:

MARKUP { 
"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.

MARKUP { 
"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

MARKUP { 
"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:

MARKUP
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:

MARKUP
{
"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 an amount minimum of N50.

TRANSFER Request Response

MARKUP
{
"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:

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

When the generated TOKEN as exceeded 2 minutes of its lifespan:

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

When the request TOKEN or Wallet ID is invalid

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

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

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

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

MARKUP
{
"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

MARKUP
{
"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

MARKUP
{
"vice_id": "123xxxxx",
"token": "474eef6dca8dd57xxxxxxxxxx******xxxxxxxxxx077834b61f6b1"
}
URL:https://www.payvice.com/api/tran/auth0/requery
HTTP VERB: POST

Where: vice_id is Your Payvice wallet ID and token is the Transaction token.

Requery Response

Below response will be returned:

MARKUP
{
"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"
}