API Reference

Getting Started

NOTE

You need a Merchant ID and Key to authenticate against the API, use the following credentials below for a demo account.

Test Accounts

  • Test API Credentials
    Merchant ID: GP0000001
    Merchant Key: 123456789
    Endpoint: https://demo.api.gladepay.com/{method}

Live Accounts

To get your live credentials Register Here. Your API Credentials are in Merchant Credentials on the dashboard. Endpoint: https://api.gladepay.com/{method}

Making Requests

You can make PUT requests to the API for both payments collections and funds disbursement, the methods to call are:

  • Payments Collection: payment
  • Money Transfer: disburse
  • Resource: resources

Authenticating Request

Pass the following with the header request made to the
mid: 'Your Merchant Id'
key: 'Your Merchant Key'

Both mid and key can gotten from the dashboard page under settings > apikeys

curl --request PUT \
      --url https://demo.api.gladepay.com/payment \
      --header 'content-type: application/json' \
      --header 'key: Your Merchant Key' \
      --header 'mid: Your Merchant ID' \
      --data '{}'
      
1
2
3
4
5
6
  $curl = curl_init();
      curl_setopt_array($curl, array(
        CURLOPT_URL => "https://demo.api.gladepay.com/payment",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "PUT",
        CURLOPT_POSTFIELDS => "{}",
        CURLOPT_HTTPHEADER => array(
          "key: Your Merchant Key",
          "mid: Your Merchant ID"
        ),
        ));
        $response = curl_exec($curl);
        $err = curl_error($curl);
        curl_close($curl);
        if ($err) {
        echo "cURL Error #:" . $err;
        } else {
        echo $response;
        }       
        
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

Payment Collections

Endpoint: https://demo.api.gladepay.com/payment Payments collection has action property which is used to specify what API call is to be made.

payment action

With Card Payment:

Card payment requires Two Steps the first is to call the charge url to get the authentication suggestion after which the charge url is called the second time with the auth_type parameter to specify the suggested_auth required by the payment gateway.

Step 1

{
  "action":"initiate",
  "paymentType":"card",
  "user": {
      "firstname":"John",
      "lastname":"Doe",
      "email":"hello@example.com",
      "ip":"192.168.33.10",
      "fingerprint": "cccvxbxbxb"
  },
  "card":{
      "card_no":"5438898014560229",
      "expiry_month":"09",
      "expiry_year":"19",
      "ccv":"789",
      "pin":"3310"
  },
  "amount":"10000",
  "country": "NG",
  "currency": "NGN",
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

The response from step 1 will contain information on what step is required for Step 2

Response

{"status":202,"txnRef":"GP8720656L","apply_auth":"PIN"}
1

For Recurrent Payments

{
  "action":"initiate",
  "paymentType":"card",
  "user": {
      "firstname":"John",
      "lastname":"Doe",
      "email":"hello@example.com",
      "ip":"192.168.33.10",
      "fingerprint": "cccvxbxbxb"
  },
  "card":{
      "card_no":"5438898014560229",
      "expiry_month":"09",
      "expiry_year":"19",
      "ccv":"789",
      "pin":"3310"
  },
  "amount":"10000",
  "country": "NG",
  "currency": "NGN",
  "recurrent": {
      "frequency" : "daily | weekly | monthly",
      "value" : "00 | 1 | 30"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

For Installmental Payments

{
  "action":"initiate",
  "paymentType":"card",
  "user": {
      "firstname":"John",
      "lastname":"Doe",
      "email":"hello@example.com",
      "ip":"192.168.33.10",
      "fingerprint": "cccvxbxbxb"
  },
  "card":{
      "card_no":"5438898014560229",
      "expiry_month":"09",
      "expiry_year":"19",
      "ccv":"789",
      "pin":"3310"
  },
  "amount":"10000",
  "country": "NG",
  "currency": "NGN",
  "installment": {
      "payment_schedule" : {
          "31-11-2017" : 20,
          "31-12-2017" : 30,
          "30-01-2017" : 50
      }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

Step 2

{
  "action":"charge",
  "paymentType":"card",
  "user": {
      "firstname":"John",
      "lastname":"Doe",
      "email":"hello@example.com",
      "ip":"192.168.33.10",
      "fingerprint": "cccvxbxbxb"
  },
  "card":{
      "card_no":"5438898014560229",
      "expiry_month":"09",
      "expiry_year":"19",
      "ccv":"789",
      "pin":"3310"
  },
  "amount":"10000",
  "country": "NG",
  "currency": "NGN",
  "txnRef":"GP8720656L",
  "auth_type":"PIN"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Payment with Token:

{
  "action":"charge",
  "paymentType":"token",
  "token":"01fae68d805957cc24697c990961a130",
  "user": {
      "firstname":"John",
      "lastname":"Doe",
      "email":"hello@example.com",
      "ip":"192.168.33.10",
      "fingerprint": "cccvxbxbxb"
  },
  "amount":"10000"
}
1
2
3
4
5
6
7
8
9
10
11
12
13

Reponse is as follows: When Charge is completed.

{"status":200,"txnRef":"GP895105347H","fraudStatus":"ok"}
1

NOTE

There are two types of validation required

First Validation

when OTP validation is required:

{
  "status":202, 
  "txnRef":"GP983340165W",
  "fraudStatus":"ok"
}
1
2
3
4
5
validate action

This is used for OTP Validation

{
  "action":"validate",
  "txnRef":"GP1507382986",
  "otp":"123456"
}
1
2
3
4
5

TIP

Use 123456 as OTP

Second Validation Type

When 3DSECURE validation is required: an authURL is returned with the validation response, you can then load the authURL directly into the browser or iframe to redirect the user to their bank for verfications

{
  "status":202, 
  "txnRef":"GP983340165W",
  "authURL":"https://link.gladepay.com/1g477sy",
  "fraudStatus":"ok"
}
1
2
3
4
5
6

Response

{"status":200,"message":"Validation Successful","cardToken":"6tj663dh"}
1

TIP

cardToken is the token code for saved card's.

verify action

This is used to requery a payment

{
  "action":"verify",
  "txnRef":"GP1507382986"
}
1
2
3
4

Response is:

  {"status":200, "txnStatus":"successful", "chargedAmount":10000, "fraudStatus":"ok"}
1

NOTE

txnStatus determines the status of the transaction if it is successful, failed or pending

With Account Payments

This is the sample payload to request for payment using bank account

{
  "action":"charge",
  "paymentType":"account",
  "user": {
      "firstname":"John",
      "lastname":"Doe",
      "email":"hello@example.com",
      "ip":"192.168.33.10",
      "fingerprint": "ddsdschhdghgshghdgshghcx"
  },
  "account":{
      "accountnumber":"0690000007",
      "bankcode":"044"
  },
  "amount":"10000"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

The list of bank codes can be gotten from the resource section

Validate Account Payment

validate action

This is used for OTP Validation

{
  "action":"validate",
  "txnRef":"GP547925318M",
  "validate": "account",
  "otp":"12345"
}
1
2
3
4
5
6

Split Payment

This feature allows you to split settlements into multiple accounts, generate the split reference and setup from the dashboard area.

Pass an array of how the split payment should be handled as shown below for any payment type.

{
    "action":"initiate",
    "paymentType":"card",
    "user": {
        "firstname":"John",
        "lastname":"Doe",
        "email":"hello@example.com",
        "ip":"192.168.33.10",
        "fingerprint": "cccvxbxbxb"
    },
    "card":{
        "card_no":"5438898014560229",
        "expiry_month":"09",
        "expiry_year":"19",
        "ccv":"789"
    },
    "amount":"10000",
    "country": "NG",
    "currency": "NGN",
    "split":[
    	{
    		"ref_code":"000",
    		"percentage": "40"
    	},{
    		"ref_code": "000",
    		"share": "100"
    	}
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

Money Transfer

In order to transfer money you must have a funded wallet which funds will be deducted from to disburse to any account of your choice.

Endpoint: https://demo.api.gladepay.com/disburse

{
  "action":"transfer",
  "amount": "100",
  "bankcode":"058", 
  "accountnumber":"0040000008",
  "sender_name": "John Doe",
  "narration": "Upkeep",
  "orderRef":"TX00001"
}
1
2
3
4
5
6
7
8
9

Response

{
  "action":"transfer",
  "amount": "100",
  "bankcode":"058", 
  "accountnumber":"0040000008",
  "sender_name": "John Doe",
  "narration": "Upkeep",
  "orderRef":"TX00001"
}
1
2
3
4
5
6
7
8
9

Bulk Transfer

Send multiple transfers to different accounts using a single API call.

{
  "action":"transfer",
  "type": "bulk",
  "data": [
	{
		"amount": "100",
		"bankcode":"058", 
		"accountnumber":"0040000008",
		"sender_name": "John Doe",
		"narration": "",
		"orderRef": "TX00001"
	},{
		"amount": "100",
		"bankcode":"058", 
		"accountnumber":"0040000009",
		"sender_name": "John Doe",
		"narration": "",
		"orderRef": "TX00002"
	}	
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

NOTE

After bulk transfers you will need to re-query the order reference of each order to verify the status of the transaction.

The transaction can be verified by passing the payload with the order reference of the transfer

{
  "action":"verify",
  "txnRef":"TX00002"
}
1
2
3
4

Response

{
  "status": 200,
  "txnStatus": "successful",
  "message": "Transfer Successful"
}
1
2
3
4
5

Note

txnStatus determines the status of the transaction if it is successful, failed or pending

Airtime and Bills

Endpoint: https://demo.api.gladepay.com/bills

With this endpoint you can purchase airtime and make bills payment.

Get the List of bills

This method retrieves the list of category, billers, and payment items.

{
	"action": "pull"
}
1
2
3

Sample Response:

{
  "data": {
    "categories": [
      {
        "name": "Airtime",
        "code": "airtime"
      },
      {
        "name": "Electricity Tokens",
        "code": "electricity"
      },
      {
        "name": "Internet Services",
        "code": "internet"
      }
    ],
    "bills": [
      {
        "id": 1,
        "name": "MTN Prepaid Topup",
        "reference": "Phone Number",
        "category": "airtime"
      },
      {
        "id": 3,
        "name": "Glo Prepaid Topup",
        "reference": "Phone Number",
        "category": "airtime"
      },
      {
        "id": 4,
        "name": "9Mobile Prepaid Topup",
        "reference": "Phone Number",
        "category": "airtime"
      },
      {
        "id": 5,
        "name": "Airtel Prepaid Topup",
        "reference": "Phone Number",
        "category": "airtime"
      },
      {
        "id": 6,
        "name": "AEDC",
        "reference": "Meter Number",
        "category": "electricity"
      }
    ],
    "items": [
      {
        "name": "TopUp",
        "bills_id": 1,
        "amount": "0",
        "discount": 3,
        "fee": 0,
        "paycode": "cHwBhPniYesycir",
        "require_name_query": 0
      },
      {
        "name": "TopUp",
        "bills_id": 3,
        "amount": "0",
        "discount": 3,
        "fee": 0,
        "paycode": "6rHQCyP0252mg0J",
        "require_name_query": 0
      },
      {
        "name": "TopUp",
        "bills_id": 4,
        "amount": "0",
        "discount": 3,
        "fee": 0,
        "paycode": "jhMIV5j3K8SmPAy",
        "require_name_query": 0
      },
      {
        "name": "TopUp",
        "bills_id": 5,
        "amount": "0",
        "discount": 3,
        "fee": 0,
        "paycode": "Alhdu86riyoyHg0",
        "require_name_query": 0
      },
      {
        "name": "AEDC Prepaid",
        "bills_id": 6,
        "amount": "0",
        "discount": 0,
        "fee": 70,
        "paycode": "lAApm6OBmRmp3cQ",
        "require_name_query": 1
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

The category is mapped to the biller and payment item. Category and Biller are linked by the category field in biller and biller is linked to the items by the bills_id field.

Resolve Bills Name

This method allows you to the name of a customers reference e.g SmartCard Number, Meter Number etc

{
	"action": "resolve",
	"paycode": "lAApm6OBmRmp3cQ",
	"reference": "0000000001"
}
1
2
3
4
5

Make Bills Payment

To make bills payment pass the paycode and reference that is required by the biller e.g SmartCard Number, Meter Number etc

paycode must be retrieved from the items list when you retrieved the list of available bills

{
	"action": "pay",
	"paycode": "lAApm6OBmRmp3cQ",
	"reference": "0000000001",
	"amount": "100",
	"orderRef": "xxcd"
}
1
2
3
4
5
6
7

Verify Bills Payment

The transaction can be verified by passing the transaction reference and setting the action as verify.

{
	"action": "verify",
	"txnRef": "GP|BP|987555815|20190115N"
}
1
2
3
4

NOTE

txnStatus determines the status of the transaction if it is successful, failed or pending

Resources

Endpoint:https://demo.api.gladepay.com/resources

WARNING

Pass the following payload to the server using the resources method to pull resources for use.

Get Supported Chargeable Banks

{"inquire": "supported_chargable_banks"}
1

Get The List of Banks

{"inquire": "banks"} 
1

Bank List Response

 {"214":"FIRST CITY MONUMENT BANK PLC","215":"UNITY BANK PLC","221":"STANBIC IBTC BANK PLC","232":"STERLING BANK PLC","301":"JAIZ BANK","304":"Stanbic Mobile","305":"PAYCOM","307":"Ecobank Mobile","309":"FBN MOBILE","311":"Parkway","315":"GTBank Mobile Money","322":"ZENITH Mobile","323":"ACCESS MOBILE","401":"Aso Savings and Loans","044":"ACCESS BANK NIGERIA","014":"AFRIBANK NIGERIA PLC","063":"DIAMOND BANK PLC","050":"ECOBANK NIGERIA PLC","084":"ENTERPRISE BANK LIMITED","070":"FIDELITY BANK PLC","011":"FIRST BANK PLC","058":"GTBANK PLC","030":"HERITAGE BANK","082":"KEYSTONE BANK PLC","076":"SKYE BANK PLC","068":"STANDARD CHARTERED BANK NIGERIA LIMITED","032":"UNION BANK OF NIGERIA PLC","033":"UNITED BANK FOR AFRICA PLC","035":"WEMA BANK PLC","057":"ZENITH BANK PLC","090114":"Empire Trust Microfinance Bank"}
1

Verify The Account Name

{"inquire": "accountname", "accountnumber": "0040000009", "bankcode": "058"}
1

Account Name Response

 {"status":"success","resolved":true,"data":{"account_name":"John Doe"}} 
1

Verify BVN

{"inquire": "bvn", "bvn": "12345678901"}
1

BVN Response

 {"status":"success","data":{"firstname":"John","lastname":"Doe","dob":"1914-01-01","bvn":"12345678901","phone":"08000000000"}} 
1

Get Card Details

The first six digits is all that is required to get the details of the such as issuer country, brand, issuer.

{"inquire": "card", "card_no": "543889"}
1

Get Charge

Get the charges for a card.

{"inquire": "charges", "card_no": "543889", "amount": "1000"}
1

Get the charges for an acccount.

{"inquire": "charges", "type": "account", "amount": "1000"}
1

Error Codes

Codes Meaning
101 Merchant Authentication Failed.
102 Invalid Method Call.
103 Invalid JSON Request.
104 Invalid Data Request.
200 Successful
201 Unrecognized Response From Gateway
202 OTP Validation required
203 Validation not successful
204 An error has occured

PostMan Samples

Check Sample →

Questions

If you encounter any issues while trying to implement this, please reach out to support@gladepay.com