INTRODUCTION

Last Updated: 1st of May., 2020

Heads up! As at 30th of May, 2020. We detected a global error on SSL, so for everyone using our API might encounter an SSL error.
Please, kindly add the CURLOPT_SSL_VERIFYPEER as false on your cURL setup. And this error will be fixed.
Thank you.

Need to integrate any of the services we provide into your applications? Access the tools and resources you need to offer services similar to our platform.

If you will be needing a technical support to integrate the API or more request, kindly use the Contact form sending us a mail in respect to your request.

Heads up!

If you are an heavy user, and will need a unique request. we will appreciate you Contact us.

Kindly make use of our sandbox account to text every of your request before going live.

Sandbox URL: https://www.payscribe.ng/sandbox Sandbox Username: sandbox@payscribe.ng Sandbox Password: sandbox

User Account

GET: https://www.payscribe.ng/api/account/

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Body
{ "username": "{YOUR EMAIL ID}" }

													{
													"status": true,
													"message": {
													"description": "User authenticated successfully.",
													"details":{
													"name": "{Your full name}",
													"phone": "08144227788",
													"wallet": "16064",
													"commission": "37.25",
													"referral_code": "12457"
													}
													},
													"status_code": 200
													}
												

Services available on the API are:

Airtime Purchase
Buy 9mobile, MTN, GLO, AIRTEL VTU at cheap price using our API

Data Purchase
Buy 9mobile, MTN, GLO, AIRTEL data at cheap price using our API

Multichoice Bills
Vend for GOTV, DSTV, STARTIMES and get instant commission

Electricity Purchase
Pay Ikeja, Eko, PHED, EEDC, JED, KEDCO... Electricity both prepaid and postpaid.

VEND AIRTIME

Purchase airtime (Glo, Mtn, Airtel, 9mobile)

POST: https://www.payscribe.ng/api/vend/airtime/

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Body '{"network":"{NETWORK NAME}", "amount":200, "recipent": "{PHONE NUMBER}"}'

You can as well add the parameter ported as true, if the number you're vending is a ported number
Please replace the NETWORK NAME with the respective network eg glo, mtn 9mobile or airtel, also replace the {PHONE NUMBER} with your customer number.
Note: the recipent can come as multiple, but separate it with comma(,) i.e 07038067493, 07038067492
													"status": true,
													"message": {
														"description": "Order received. In process.",
														"transaction_status": "processing,
														"details": {
															"processed": "07038067493,",
															"amount": 96,
															"total_charge" : 96
															"transaction_id": "PS75893264",
															"network": "",
															"datetime": "2019-08-03 22:51:16"
														}
													},
													"status_code": 200
												

VEND DATA

Purchase data (Glo, Mtn, Airtel, 9mobile)

Data Lookup

GET: https://www.payscribe.ng/api/lookup/data

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Body '{"network":"{NETWORK NAME}"'

Please replace the NETWORK NAME with the respective network eg glo, mtn 9mobile or airtel. Note that if the network parameter is empty, we will return all data services.
The below data plan and amount is just a sample, this is not our current data pricing.
													{
														"status": true,
														"message": {
															"description": "Lookup successful.",
															"details": [
																{
																	"network_name": "mtn",
																	"title": "MTN Data",
																	"network_code": "PSDATA_15",
																	"check_balance": "*461*4#",
																	"plans": [
																		{
																			"plan_code": "PSPLAN_55",
																			"name": "250MB",
																			"amount": "150"
																		},
																		{
																			"plan_code": "PSPLAN_56",
																			"name": "500MB",
																			"amount": "300"
																		},
																		{
																			"plan_code": "PSPLAN_57",
																			"name": "1GB",
																			"amount": "470"
																		},
																		{
																			"plan_code": "PSPLAN_58",
																			"name": "2GB",
																			"amount": "940"
																		},
																		{
																			"plan_code": "PSPLAN_59",
																			"name": "5GB",
																			"amount": "2350"
																		}
																	]
																},
																{
																	"network_name": "glo",
																	"title": "Glo Data",
																	"network_code": "PSDATA_16",
																	"check_balance": "*127*0#",
																	"plans": [
																		{
																			"plan_code": "PSPLAN_61",
																			"name": "3.65GB/4.5GB",
																			"amount": "1700"
																		},
																		{
																			"plan_code": "PSPLAN_62",
																			"name": "7GB/8.75GB",
																			"amount": "2550"
																		},
																		{
																			"plan_code": "PSPLAN_63",
																			"name": "10GB/12.5GB",
																			"amount": "3400"
																		},
																		{
																			"plan_code": "PSPLAN_64",
																			"name": "12.5GB/15.6GB",
																			"amount": "4250"
																		},
																		{
																			"plan_code": "PSPLAN_65",
																			"name": "20GB/25GB",
																			"amount": "6800"
																		},
																		{
																			"plan_code": "PSPLAN_66",
																			"name": "26GB/32.5GB",
																			"amount": "8500"
																		},
																		{
																			"plan_code": "PSPLAN_67",
																			"name": "42GB/52.5GB",
																			"amount": "12750"
																		},
																		{
																			"plan_code": "PSPLAN_68",
																			"name": "63GB/78.7GB",
																			"amount": "17000"
																		},
																		{
																			"plan_code": "PSPLAN_69",
																			"name": "1.6GB/1.84GB",
																			"amount": "850"
																		},
																		{
																			"plan_code": "PSPLAN_70",
																			"name": "5.75GB/7.2GB",
																			"amount": "2150"
																		},
																		{
																			"plan_code": "PSPLAN_85",
																			"name": "800MB/920MB",
																			"amount": "450"
																		}
																	]
																},
																{
																	"network_name": "airtel",
																	"title": "Airtel Data",
																	"network_code": "PSDATA_17",
																	"check_balance": "*140#",
																	"plans": [
																		{
																			"plan_code": "PSPLAN_71",
																			"name": "1.5GB",
																			"amount": "970"
																		},
																		{
																			"plan_code": "PSPLAN_72",
																			"name": "3.5GB",
																			"amount": "1950"
																		},
																		{
																			"plan_code": "PSPLAN_73",
																			"name": "5.5GB",
																			"amount": "2450"
																		}
																	]
																},
																{
																	"network_name": "9mobile",
																	"title": "9mobile Data",
																	"network_code": "PSDATA_18",
																	"check_balance": "*229*9#",
																	"plans": [
																		{
																			"plan_code": "PSPLAN_74",
																			"name": "1.5GB",
																			"amount": "1110"
																		},
																		{
																			"plan_code": "PSPLAN_75",
																			"name": "1GB",
																			"amount": "920"
																		},
																		{
																			"plan_code": "PSPLAN_76",
																			"name": "2.5GB",
																			"amount": "1840"
																		},
																		{
																			"plan_code": "PSPLAN_77",
																			"name": "4GB",
																			"amount": "2760"
																		},
																		{
																			"plan_code": "PSPLAN_78",
																			"name": "5.5GB",
																			"amount": "3680"
																		},
																		{
																			"plan_code": "PSPLAN_79",
																			"name": "11.5GB",
																			"amount": "7360"
																		},
																		{
																			"plan_code": "PSPLAN_80",
																			"name": "15GB",
																			"amount": "9200"
																		},
																		{
																			"plan_code": "PSPLAN_81",
																			"name": "27.5GB",
																			"amount": "16560"
																		}
																	]
																}
															]
														},
														"status_code": 200
													}
												

Data Vending

POST: https://www.payscribe.ng/api/vend/data/

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Body '{"network":"{NETWORK}", "plan":{PLAN_CODE}, "recipent": "{PHONE NUMBER}"}'

You can as well add the parameter ported as true, if the number you're vending is a ported number
Please replace the {NETWORK} with the respective name: glo, mtn, 9mobile or airtel.
Replace the {PLAN_CODE} with the plan_code you want to buy as seen on the data_lookup endpoint
also replace the {PHONE_NUMBER} with your customer number (You can vend for multiple number. Separate it with comma(,))
													{
														"status": true,
														"message": {
															"description": "Order received. In process.",
															"details": {
																"transaction_status": "processing",
																"processed": "07038067493,",
																"amount": 150,
																"transaction_id": "PS82731549",
																"datetime": "2019-08-20 06:28:47"
															}
														},
														"status_code": 200
													}
												

VEND MULTICHOICE - GOTV, DSTV

GET: https://www.payscribe.ng/api/validate/multichoice/

Multichoice validation

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Body '{"multichoice_type":"DSTV|GOTV", "smart_card_no": {SMART_CARD_NO}'

Please replace the multichoice_type valuewith the respective multichoice type you're vending eg GOTV, or DSTV Replace the SMART_CARD_NO with the number you're trying to vend for.

													{
													"status": true,
													"message": {
														"description": "Validation successful.",
														"details": {
															"customer_smart_card_name": "{CUSTOMER_SMART_CARD_NAME}",
															"productCode": "6C4D42510ABB18165286343A2B588DCDDAE6477FFFC7D75E4B447FDA494AA86AC493A667884AB5627DDB119C01AC19C1CFFC92CC53CA604D8A495EE6B80109F0|eyJwcm9kdWN0IjoiTVVMVElDSE9JQ0UiLCJ1bml0IjoiR09UViIsImFjY291bnQiOiI3MDI4ODc3MTQ4IiwibmFtZSI6IlBISUxJUCBTT0tPWUEiLCJjdXN0b21lck51bWJlciI6IjEwNzk4MjU1NSIsImJvdXF1ZXRzIjpbeyJuYW1lIjoiR090diBWYWx1ZSIsInByb2R1Y3RfY29kZSI6IkRTVFZ8R09UViIsImFtb3VudCI6IjEyNTAifSx7Im5hbWUiOiJHT3R2IFBsdXMiLCJwcm9kdWN0X2NvZGUiOiJEU1RWfEdPVFZQTFMiLCJhbW91bnQiOiIxOTAwIn0seyJuYW1lIjoiR090diBNYXgiLCJwcm9kdWN0X2NvZGUiOiJEU1RWfEdPdHZNYXgiLCJhbW91bnQiOiIzMjAwIn0seyJuYW1lIjoiR090diBMaXRlIE1vbnRobHkiLCJwcm9kdWN0X2NvZGUiOiJEU1RWfEdPSEFOIiwiYW1vdW50IjoiNDAwIn0seyJuYW1lIjoiR090diBMaXRlIFF1YXJ0ZXJseSIsInByb2R1Y3RfY29kZSI6IkRTVFZ8R09MSVRFIiwiYW1vdW50IjoiMTA1MCJ9XSwic2VydmljZUlkIjoiQVFDIn0%3D",
															"bouquets": [
																{
																	"name": "GOtv Value",
																	"product_code": "DSTV|GOTV",
																	"amount": "1250"
																},
																{
																	"name": "GOtv Plus",
																	"product_code": "DSTV|GOTVPLS",
																	"amount": "1900"
																},
																{
																	"name": "GOtv Max",
																	"product_code": "DSTV|GOtvMax",
																	"amount": "3200"
																},
																{
																	"name": "GOtv Lite Monthly",
																	"product_code": "DSTV|GOHAN",
																	"amount": "400"
																},
																{
																	"name": "GOtv Lite Quarterly",
																	"product_code": "DSTV|GOLITE",
																	"amount": "1050"
																}
															]
														}
													},
													"status_code": 200
												}
												

Multichoice payment

POST: https://www.payscribe.ng/api/multichoice/payment/

Multichoice Payment

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Body '{ "multichoice_type":"GOTV|DSTV", (required)
"smart_card_no": {SMART CARD NO}, (required)
"amount" : 1900, (required)
"product_code" : "DSTV|GOTVPLS", (required)
"productCode" : "{THE VALIDATION PRODUCT CODE}", (required)
"phone_number" : "{CUSTOMER PHONE NUMBER}", (not required)
"customer_name" : "{CUSTOMER NAME}", (not mandatory)
"transaction_id" : "{YOUR UNIQUE TRANSACTION ID}", (not required)
}'

The above parameters should be replaced with the right parameters.

													"status": true,
													"message": {
														"description": "Transaction Successful.",
														"details": {
															"processed": "GOTV|745512200",
															"amount": 1900,
															"transaction_id": "PS75893264",
															"datetime": "2019-08-03 22:51:16"
														}
													},
													"status_code": 200
												

VEND STARTIMES

GET: https://www.payscribe.ng/api/validate/startimes/

Startimes validation

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Body '{"smart_card_no": {SMART_CARD_NO}}'

Please replace {SMART_CARD_NO} with your customer smart card number.

													{
													"status": true,
													"message": {
														"description": "Validation successful.",
														"details": {
															"customer_smart_card_name": "James Philip",
															"productCode": "576FD941ECCE240CAA6FF53D4D9995393AC33D9B6FC5573DB44FB87E3F50C2931843A882620D50F5EBE6DE8431B5B2954EFCFB2B1EB4E255A9AA2D8720456DBB|eyJwcm9kdWN0IjoiU1RBUlRJTUVTIiwiY3VzdG9tZXJRdWVyeUJhbGFuY2VCYWxhbmNlIjoiMjcuMjIiLCJjdXN0b21lclF1ZXJ5QmFsYW5jZUJpbGxBbW91bnQiOiIwLjAiLCJjdXN0b21lclF1ZXJ5QmFsYW5jZVBheVR5cGUiOiIxIiwiY3VzdG9tZXJRdWVyeUJhbGFuY2VTbWFydENhcmRDb2RlIjoiMDIxNDY0NTIzNTYiLCJjdXN0b21lclF1ZXJ5QmFsYW5jZU5hbWUiOiJGdW5zaG8gQXllbmkiLCJjdXN0b21lclZhbGlkYXRpb25TbWFydENhcmRDZGUiOiIwMjE0NjQ1MjM1NiIsImN1c3RvbWVyVmFsaWRhdGlvbkJhbGFuY2UiOiIyNy4yMiIsImN1c3RvbWVyVmFsaWRhdGlvbkJvdXF1ZXQiOiJCYXNpYyBCb3VxdWV0OyIsImN1c3RvbWVyVmFsaWRhdGlvbk5hbWUiOiJGdW5zaG8gQXllbmkifQ%3D%3D",
															"bouquets": [
																{
																	"name": "NOVA",
																	"cycles": {
																		"daily": 60,
																		"weekly": 300,
																		"monthly": 900
																	}
																},
																{
																	"name": "BASIC",
																	"cycles": {
																		"daily": 90,
																		"weekly": 450,
																		"monthly": 1300
																	}
																},
																{
																	"name": "SMART",
																	"cycles": {
																		"daily": 120,
																		"weekly": 600,
																		"monthly": 1900
																	}
																},
																{
																	"name": "CLASSIC",
																	"cycles": {
																		"daily": 180,
																		"weekly": 900,
																		"monthly": 1900
																	}
																},
																{
																	"name": "SUPER",
																	"cycles": {
																		"daily": 180,
																		"weekly": 900,
																		"monthly": 2600
																	}
																}
															]
														}
													},
													"status_code": 200
												}
												

Startimes payment

POST: https://www.payscribe.ng/api/startimes/payment/

Startimes Payment

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Body '{ "smart_card_no": {SMART CARD NO}, (required)
"amount" : 100, (required)
"product_code" : "NOVA|BASIC|SMART|CLASSIC|SUPER", (required)
"productCode" : "{THE VALIDATION PRODUCT CODE}", (required)
"phone_number" : "{CUSTOMER PHONE NUMBER}", (not mandatory)
"customer_name" : "{CUSTOMER NAME}", (not mandatory)
"transaction_id" : "{YOUR UNIQUE TRANSACTION ID}", (required)
}'

The product_code is either NOVA, BASIC, SMART, CLASSIC or SUPER

Please the above parameters should be replaced with the right parameters

													{
														["status"]=> bool(true)
														["message"]=> array(2)
															{
																["description"]=> string(23) "Transaction successful."
																["details"]=> array(4)
															{
																["processed"]=> string(21) "STARTIMES|01467438081"
																["amount"]=> string(3) "100"
																["transaction_id"]=> string(10) "PS73184296"
																["datetime"]=> string(19) "2019-11-06 16:29:03"
															}
													}
														["status_code"]=> int(200)
													}
												

VEND ELECTRICITY - IKEJA, EKO, ENUGU, PHED, IBADAN, ABUJA, KANO ELECTRICITY DISTRIBUTION

Electricity validation

Our Api covers the following electricity distribution in Nigeria.

  • Payment for Ikeja Electric Ikeja Electric (ikedc)
  • Payment for Eko Electricity Eko Electricity (ekedc)
  • Payment for Enugu Electricity Enugu Electricity (eedc)
  • Payment for Ibadan Electricity Ibadan Electricity (ibedc)
  • Payment for Portharcourt Electricity Portharcourt Electricity (phed)
  • Payment for Abuja Electricity Abuja Electricity (abuja)

Please Read

When calling our electricity API, you make use of the service short name as the endpoint For example to validate for Ikeja electricity, the short name is ie.
So the final endpoint will be https://www.payscribe.ng/api/electricity/validate/ie, Where the short name is ie

Please note the short name below

  • Ikaja Electricity = ie
  • Eko Electricity = ekedc
  • Enugu Electricity = eedc
  • Kano Electricity = kano
  • Port Harcourt Electricity = phed
  • Abuja Electricity = abuja
  • Ibadan Electricity = ibedc

Also note that all services except ikeja electricity (ie) require product_code when making payment. The product code will be sent along othe information when validating.
That is why we require you to make a validation before processing the payment.

Validation

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Endpoint https://www.payscribe.ng/api/electricity/validate/{SERVICE_SHORTNAME} Where SERVICE_SHORTNAME which can either be ie, eedc, abuja, ekedc, phed, kano ...

Body '{"meter_number":"{YOUR METER NUMBER}", "meter_type": {prepaid or postpaid}'

We validated Ikeja Postpaid, below is the response.

													{
														"status": true,
														"message": {
															"description": "IE Validation successful.",
															"details": {
																"customer_name": "MR N MRS ADEOLA TOKUNBO"
															}
														},
														"status_code": 200
													}
												

We validated Abuja Prepaid, below is the response. Take note of the product_code that comes with the response, you'll use it when making payment.

													{
														"status": true,
														"message": {
															"description": "Abuja Validation successful.",
															"details": {
																"customer_name": "AUGUTINE ARUN OGBODO",
																"product_code": "5771D757DE9B9CFCC19E71E72CD11B756473ECB1B0DC41C245B5BB93AEBBBFEB82BFD9752E12B8F702260872EB4CD7BDD7C395DEAC00B3CCB0776B8083BDE07C|eyJwcm9kdWN0IjoiQUJVSkFFTEVDVFJJQ0lUWSIsInR5cGUiOiJWYWxpZGF0aW9uIiwiY3VzdG9tZXJNZXRlck5vIjoiMDcwODU1MjI1NjgiLCJuYW1lIjoiQVVHVVRJTkUgQVJVTiBPR0JPRE8iLCJjbGllbnRJZCI6Iml0ZXgiLCJwYXNzY29kZSI6Il9pbnRlMGJ2eHoqIiwidW5pcXVlY29kZSI6IjA5MTEyMDc4NDMiLCJkYXRlVGltZSI6IjIwMTktMDktMTEgMTE6MTIiLCJkZXZpY2VJZCI6IjIwMzMwMDA5In0%3D"
															}
														},
														"status_code": 200
													}
												

Payment

Please Read

You can make payment for electricity using https://www.payscribe.ng/api/electricity/payment/{SERVICE_SHORT_NAME}
Please note the service short name below

  • Ikaja Electricity = ie
  • Eko Electricity = ekedc
  • Enugu Electricity = eedc
  • Port Harcourt Electricity = phed
  • Abuja Electricity = abuja
  • Kano Electricity = kano
  • Ibadan Electricity = ibedc

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Endpoint https://www.payscribe.ng/api/electricity/payment/{SERVICE_SHORTNAME} SERVICE_SHORTNAME as been explained above

Body '{"meter_number":"{YOUR METER NUMBER}", "meter_type": {prepaid or postpaid}, "phone_number": 08011223344, "amount": 1000'

Note the phone_number is not mandatory

Successful Result

													{
														"status": true,
														"message": {
															"description": "Transaction Successful.",
															"details": {
																"processes": "IE",
																"customer Name": "Olaleke James",
																"amount": "0101022291",
																"address": "20B, Ajah",
																"token": "81110082828201112",
																"Unit Value": "37Kv",
																"Amount Paid": "4000"
																"reference_number": PS22202182|IE8292229
															}
														},
														"status_code": 200
													}
												

AIRTIME TO WALLET

You may need to get fetch the available networks and our current rate before sending the airtime

Lookup

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Endpoint https://www.payscribe.ng/api/airtime_to_wallet/lookup

Calling the above endpoint will return all the active networks and our current rate.

													{
														"status": true,
														"message": {
															"description": "Lookup successful.",
															"details": [
																{
																	"network_name": "mtn",
																	"status": "active",
																	"phone_number": "07038067493",
																	"transfer_code": "*600*07038067493*[AMOUNT]*[PIN]#",
																	"rate": 80,
																},
                                                                {
																	"network_name": "glo",
																	"status": "active",
																	"phone_number": "08070994845",
																	"transfer_code": "",
																	"rate": 80,
																},
                                                                {
																	"network_name": "airtel",
																	"status": "active",
																	"phone_number": "08070994845",
																	"transfer_code": "*432*1*0914883528#",
																	"rate": 80,
																},
                                                                {
																	"network_name": "9mobile",
																	"status": "active",
																	"phone_number": "08092581371",
																	"transfer_code": "*223*08092581371*[AMOUNT]*[PIN]#",
																	"rate": 80,
																},
															]
														},
														"status_code": 200
													}
												

Process

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Endpoint: POST https://www.payscribe.ng/api/airtime_to_wallet/process

Body '{"network":"{NETWORK_NAME}", "amount":"{AMOUNT_SENT}", "phone_number":"{PHONE_NUMBER}"'

Please replace the NETWORK_NAME with the respective network eg glo, mtn 9mobile or airtel.
Also replace the AMOUNT_SENT with the actual amount you send to us, and the PHONE_NUMBER to the number you sent to.

Successful response

													{
														"status": true,
														"message": {
															"description": "Transaction Received, your wallet will be credited as sonn as we receive the airtime."
														},
														"status_code": 200
													}
												

Successful Result

													{
														"status": true,
														"message": {
															"description": "Transaction Successful.",
															"details": {
																"processes": "IE",
																"customer Name": "Olaleke James",
																"amount": "0101022291",
																"address": "20B, Ajah",
																"token": "81110082828201112",
																"Unit Value": "37Kv",
																"Amount Paid": "4000"
																"reference_number": PS22202182|IE8292229
															}
														},
														"status_code": 200
													}
												

For further record or log, you may choose to get transaction report.

GET: https://www.payscribe.ng/api/get_report/

Headers
Content-Type: application/json
Authorization: Bearer {YOUR API TOKEN}

Body
{ "trans_id": "{THE TRANSACTION ID YOU'RE TRYING TO QUERY}" }

Get transaction report for any service you vend

Successful Result

													{
														"status": true,
														"message": {
															"description": "Lookup successful.",
															"details": {
																"trans_id": "PS321865",
																"description": "N200 MTN Airtime Purchase for 1 Recipent (07038067496)",
																"amount": "192",
																"prev_balance": "6700",
																"balance": "6508",
																"date_initiated": "2019-05-22 12:31:40",
																"status": "success"
															}
														},
														"status_code": 200
													}
												

Events (Webhooks)

User webhooks to get notified about transaction events that happen in your Payscribe account.

What is a Webhook

A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST. A web application implementing WebHooks will POST a message to a URL when certain things happen.

In Payscribe you can setup webhooks that would let us notify you anytime events - A change in airtime status, a change in data purchase status, - we update a pending payment to successful- happen in your account.

Pascribe sends webhooks events that notify your application any time a payment event happens in your account.

When to use Webhooks


Webhooks can be used for all kinds of payment methods, transactions made on your payscribe account.
You might also use webhooks to:

  • Update a customer's transaction record in your database when the transaction is completed on payscribe portal.
  • Email a customer when a transaction fail
  • Update your database when the status of a pending transaction is updated to successful

Please Note


Not in all cases would you be able to rely completely on webhooks to get notified, an example is if your server is experiencing a downtime and your hook endpoints are affected, some customers might still be transacting independently of that and the hook call triggered would fail because your server was unreachable.

In such cases we advise that developers set up a re-query service that goes to poll for the transaction status at regular intervals e.g. every hour using the get transaction endpoint, till a successful or failed response is returned.

Sample Transaction Payload


On Payscribe, Webhooks can be configured for transactions. When a transaction is completed, a POST HTTP request is sent to the URL you have configured. The HTTP payload will contain

Hook Structure


The hook request structure is consistent across the board, but you can differentiate the event type using the event.type parameter returned. See the list of possible values for the parameter below:

  • Data Purchase: DATA_PURCHASE
  • Airtime Purchase: AIRTIME_PURCHASE
  • TV Subscription Purchase: TV_SUBSCRIPTION_PURCHASE
  • Electricity Bill: ELECTRICITY_BILL
  • Wallet Funding: WALLET_FUNDING
  • Wallet Transfer: WALLET_TRANSFER
  • Epin (Waec, Neco, GCE, jamb...): EPIN
  • Airtime to Wallet: AIRTIME_TO_TRANSFER
  • Bulk SMS: BULK_SMS

Successful Result

													{
														'status' => 'success',
														'event_type' : 'DATA_PURCHASE'
														'transaction_status': 'success',
														'trans_id' : 'PS1234567890',
														'transaction_amount': 970,
														'charge': 00,
														'prev_balance': 9970,
														'balance_after': 9000,
														'product_name': 'AIRTIME,
														'description': 'MTN 5GB (SME) purchased for 08100223344',
														'remark': 'You have successfully sent 5000MB data to 08100223344',
														'time_initiated' : 22 Apr. 10:03AM,
														'time_updated' : 22 Apr. 10:04AM,
													}
												

How to setup webhooks on your dashboard.


Login to your account, navigate to Profile & Settings, click on the "API / Webhook Tab"

Webhook page

Receiving a webhook notification.

Creating a webhook endpoint on your server is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Laravel, Flask, Sinatra, you would add a new route with the desired webhook URL.

Webhook data is sent as form-urlencoded by default.

Please Note

On your account you can't set a webhook secret hash on your account at the moment.

Download a sample script on how to receive our webhook notification and process it --> Click here

List of our status code

Successful Result

													200 - Success
													201 - Transaction Pending
													400 - Bad Request, Something missing in your body request
													401 - User not authenticated
													402 - Insufficient Fund
													403 - Forbidden request
													404 - Page Not found
													405 - Duplicate Transaction
													406 - Missing Required Information, Please check that you have provided all mandatory information
													407 - Invalid product code
													408 - MSISDN Invalid
													409 - Amount invalid To Process
													434 - General Operator Side Error, Transaction Failed
													435 - General Database Error, Transaction Failed
													5xx - Some server-side error