Payment API

Documentation
1. Generate Payment Link

API https://paygw.globalpay.com.ng/globalpay-paymentgatewa
Endpoint y/api/paymentgateway/generate-payment-link

API verb POST

API KEY YOUR PUBLIC KEY

API This API is used to generate a checkout URL to receive payment .

description
When a customer clicks the payment action button, the transaction is
initialized by making a POST request from your server to our API. Upon
sending a post request , a payment link will be returned as response . See
the request description in the table below

Sample Request Payload 1

{
"amount": 100,
"merchantTransactionReference": "your reference no",
"redirectUrl": "www.yoururl.com",
"customer": {
"lastName": "lastname",
"firstName": "firstname",
"currency": "NGN",
"phoneNumber": "081XXXXXXXX",
"address": "string",
"emailAddress": "[email protected]"
}
}
Sample Request Payload 2 (Custom Fields)

{
"amount": 100,
"merchantTransactionReference": "your reference no",
"redirectUrl": "www.yoururl.com",
"customer": {
"lastName": "lastname",
"firstName": "firstname",
"currency": "NGN",
"phoneNumber": "081XXXXXXXX",
"address": "string",
"emailAddress": "[email protected]",
"paymentFormCustomFields": [
{
"name of custom field": "Grade",
"value of custom field": "Average"
}
]
}
}

Description

Property Data type Field Length Description

FullName String 100 Customer first and

last

Currency(NGN) String 3 Transaction

currency

Amount Decimal Decimal(8, 2) amount

value can
include
kobo
PhoneNumber Numeric 11 Customer
phone Number

Address String >5 The address of the

customer

Email Address String >5 Customer email

address

apikey String Exact as sent property not

value should
be all
 lowercase

Header parameters:

language: en
apikey: enter your public key he
Sample Response

Response: This response leads to the payment

gateway for payment to be received.

{ "data": {
"checkoutUrl": When customers complete the payment
"https://globalpay.ng/GlobalP successfully, they are redirected to the
ay/payments/channels/card?txn redirect URL set in your endpoint that calls
Ref=GLOBALPAY_TRANS_REF", the generated payment link. The customer
"accessCode": "DEG5ZCB053", will be redirected there.
"responseCode": null, If you have webhooks implemented, a
"responseDecription": null, payment.success event will be sent to your
"redirectURL": null }, webhook URL, and it's recommended that
"successMessage": null, you use this to deliver value to the customer
"responseCode": null, in your backend.
"isSuccessful": true, In your frontend, after detecting the redirect
"error": null} to the redirect URL, this means the
transaction is successful. You can confirm
the status by calling the
requerytransaction endpoint, and then you
can programmatically close the checkout
and show the customer a transaction
confirmation page in your app. This is
handled in the requerytransaction()

method.
 2. query transaction with globalpay ref

API EndPoint https://paygw.globalpay.com.ng/globalpay-paymentgate

way/api/paymentgateway/query-single-transaction{GLOB
ALPAY_TRANS_REF}

API Verb GET

API Key

API
description This API is used by the merchant to confirm the
transaction status of a transaction

Sample Request
 Sample Response

{
"data": {
"txnref": "4914065XXX932792",
"merchantid": XXX,
"channel": "Bank",
"amount": 100.00,
"paymentDate": "2024-01-17T07:17:28.293",
"paymentStatus": "Failed",
"furtherProcessed": null,
"processDate": null,
"merchantTxnref": "CGSxxxxx637839",
"inAmount": 100.00,
"inCurrency": "NGN",
"rate": null,
"redirectUrl": null,
"transactionSource": "Website",
"transactionChannel": "Bank"
},
"successMessage": "Successful",
"responseCode": "0000",
"isSuccessful": true,
"error": null
}

if isSuccessful is true - Transaction was successful

3. query transaction with merchant transaction ref

API EndPoint https://paygw.globalpay.com.ng/globalpay-paymentgate

way/api/paymentgateway/query-single-transaction-by-m
erchant-reference/{MERCHANT_TRANS_REF}

API Verb GET

API Key

API
description This API is used by the merchant to confirm the
transaction status of a transaction
 Sample Request

Sample Response

{
"data": {
"txnref": "491406562XXX2792",
"merchantid": XXX,
"channel": "Bank",
"amount": 100.00,
"paymentDate": "2024-01-17T07:17:28.293",
"paymentStatus": "Failed",
"furtherProcessed": null,
"processDate": null,
"merchantTxnref": "CGxxxxxKD637839",
"inAmount": 100.00,
"inCurrency": "NGN",
"rate": null,
"redirectUrl": null,
"transactionSource": "Website",
"transactionChannel": "Bank"
},
"successMessage": "Successful",
"responseCode": "0000",
"isSuccessful": true,
"error": null
}

if paymentStatusis true - Transaction was successful

 4. query transactions reconciliation

API EndPoint https://paygw.globalpay.com.ng/globalpay-paymentgateway

/api/paymentgateway/query-transactions-for-reconciliati
on

API Verb POST

API Key

API
description This API is used by the merchant to get transaction
reports

Sample Request
Sample Response

"data": [
{
"txnref": "xxxxxxxxxxx",
"transactionFee": "ChargeMerchant",
"merchantid": xxxx,
"customerAccountNumber": "N/A",
"customerBankName": "N/A",
"amount": null,
"paymentDate": "2024-01-05T09:44:00",
"paymentStatus": "pending",
"merchantTxnref": "xxxxxxx",
"inAmount": 100.00,
"feeAmount": 1.50,
"inCurrency": "NGN",
"redirectUrl": "xxxxxxxxx",
"transactionSource": "xxxxxxx",
"transactionChannel": "xxxxxxx"
},

],
"successMessage": "Successful",
"responseCode": "0000",
"isSuccessful": true,
"error": null
}
 5. download transactions reconciliation

API EndPoint https://paygw.globalpay.com.ng/globalpay-paymentgateway

/api/paymentgateway/download-transactions-for-reconcili
ation

API Verb POST

API Key

API
description This API is used by the merchant to download transaction
reports

Sample Request
Globalpay SDks and
Libraries
 Mobile SDKs

React Native
The GlobalPay React Native SDK is a comprehensive toolkit designed to seamlessly integrate

GlobalPay's payment capabilities into React Native applications. With this SDK, developers can

easily enable secure payment processing, providing a smooth and reliable checkout experience for

users.

Project Setup

To use packages from Azure Artifacts, configure your project to reference this feed.

Create a new text file called “.npmrc” in the same directory as your package.json, then copy the

snippet below:

@zenith/registry=https://pkgs.dev.azure.com/ZBPlc/ZenithSDKs/_packaging/ZenithSDKFeed/np

Restore packages

npm install

Installation

npm install @zenith/globalpaysdk

Usage

Import the library and pass in the property.

Check below for more details on the property.

import GlobalPayRnSdk from '@zenith/globalpaysdk';

<GlobalPayRnSdk
Amount={300}
MerchantTransactionReference="your-reference"
RedirectUrl="your-redirect-url"
FirstName="customer's first name"
LastName="customer's last name"
Currency="NGN"
// Enviroment can be test or live Enviroment="live"
Address="customer's address"
EmailAddress="customer's email"
PhoneNumber="customer's phone"
onSuccess={(message) => return console.log(message)}
onFailure={(message) => return console.log(message)}
onClose={(message) => return console.log(message)}
/>

Property Type Description Required

Amount String debit amount true

MerchantTransaction String The merchant true

Reference transaction true
reference

RedirectUrl ​String A redirect URL where true

we redirect true your
customers to after
payment

FirstName String The customer's first true

name

LastName String The customer's last true

name

Currency String Transaction currency true

Environment String The work mode or true

enviroment e.g “test”
or “live”. Change it
based on the
 enviroment

Address String customer's address true

EmailAddress String Customer's email true

PhoneNumber String Customer's phone true

number

onSuccess () => void The onSuccess true

function will be
invoked when a
transaction is
successful. It takes a
parameter called
message

onFailure () => void The onFailure true

function will be
invoked when a
transaction is failed or
cancelled. It takes a
parameter called
message

onClose () => void The onClose function true

will be invoked when
the modal is closed. It
takes a parameter
called message

Flutter

Installation

To use this plugin, add global_pay as a dependency in your pubspec.yaml file.

Making Payments

The Plugin handles all the processes involved in making a payment with global pay flutter sdk.

Sample code below:

import 'package:global_pay/global_pay.dart';
GlobalPay.launchGlobalPay(
context,
 email: [email protected],
amount: 100,
currency: 'NGN',
merchantId: 'merchantId',
username: 'username',
userPhone: '07030297285',
environment: GlobalPayEnvironment.test,
apiKey: 'apikey',
redirectURL: 'redirecturl',
onClose: (_) {
***User closed the checkout
},
onSuccess: (TransactionData transactionData) {
***use the transaction data response in sync with your
application needs
},
onError: (String errorMessage) {
***use the error message in sync with your application
needs
},
);

Native Android

Installation

Android Studio (using Gradle)

You do not need to clone this repository or download the files.

The latest build is available on Maven Central.

Add the following lines to your app's `build.gradle`:

 maven {
url
"https://pkgs.dev.azure.com/ZBPlc/ZenithSDKs/_packag
ing/ZenithSDKFeed/maven/v1"
}
dependencies {
implementation 'implementation
'com.zbplc:globalpay:1.0.0'
}

You should also add Java 8 support in your `build.gradle`:

android {
// ... Other configuration code
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
// For kotlin codebases, include
kotlinOptions {
jvmTarget = "1.8"
}
}

Transaction Callback

When an error occurs or transaction concludes successfully, we will call the methods available

in the callback you provided.

● OnSuccess will be called once the charge succeeds.

● onCancelled is called every time the payment process is canceled.

 ● OnError is called if an error occurred during processing.

Sample Usage

Using Java

void makePayment(){
Button payBtn = findViewById(R.id.button);
GlobalPayCheckOut checkout = new
GlobalPayCheckOut.Builder(this, "[email protected]",
50, "NGN", "22903", "Aboyeji Dotun",
"08056162610","https://www.example.com/")
.build();

payBtn.setOnClickListener(view -> {
checkout.charge(new GlobalPayResultListener()
{
@Override
public void onSuccess(@NonNull String
message) {
String value =
String.format("Transaction complete - Ref: %s", message);
Toast.makeText(TestingActivity.this,
value, Toast.LENGTH_LONG).show();
Log.i("TAG", "Transaction Success");
}
@Override
public void onError(@NonNull Throwable
exception) {
Toast.makeText(TestingActivity.this,
"Transaction failed", Toast.LENGTH_LONG)
.show();
Log.e("TAG",
exception.getMessage(), exception);
}

@Override
public void onCancelled() {
Toast.makeText(TestingActivity.this,
"Transaction cancelled by user", Toast.LENGTH_LONG)
.show();
Log.i("TAG", "Payment process
cancelled!");
}
});
 });
}

Using Kotlin

private fun makePayment(){

val button =
findViewById<Button>(R.id.button)

val checkoutResultListener = object :

GlobalPayResultListener {
override fun onSuccess(transaction: String) {
showMessage("Transaction complete")
Log.i(TAG, "Transaction Success")
}
override fun onError(exception: Throwable) {

showMessage(exception.message.toString())
Log.e(TAG,
exception.message.orEmpty(), exception)
}
override fun onCancelled() {
showMessage("Transaction cancelled by user")
Log.e(TAG, "Cancelled!")
}
}
val checkoutBuilder =
GlobalPayCheckOut.Builder(
this, "[email protected]",
50, "NGN",merchantId = "XXXXX",names =
"Aboyeji Dotun",phone = "07030297285",RedirectUrl =
"https://www.example.com/"
)
val checkout = checkoutBuilder.build()
button.setOnClickListener {
checkout.charge(checkoutResultListener)
 }
}

Frontend Libraries

React
React library for integrating GlobalPay Payment Gateway into React applications.

Project Setup
To use packages from Azure Artifacts, configure your project to reference this feed.

Create a new text file called “.npmrc” in the same directory as your package.json, then copy
the snippet below

@zenith/registry=https://pkgs.dev.azure.com/ZBPlc/ZenithSDKs/_packaging/ZenithSDKFee
d/npm

Installation
npm install @zenith/globalpay-react

Sample Usage

import { GlobalPay, GeneratePaymentLinkPayload } from

'@zenith/globalpay-react';

export const App = () => {

const payload: GeneratePaymentLinkPayload = {
amount: 200,
merchantTransactionReference: "your-reference",
redirectUrl: "your-redirect-url",
customer: {
lastName: "Doe",
firstName: "John",
currency: "NGN",
phoneNumber: "081000000000",
address: "customer's address",
emailAddress: "customer's email"
 }
};

const style = {
background: 'green',
color: 'yellow'
};

function onError(error) {
console.log(error);
}

return (
<>
<GlobalPay
apiKey="your-api-key"
buttonText="Pay Me"
buttonStyle={style}
payload={payload}
onError={onError}
></GlobalPay>
</>
)
};
Angular
Angular library for integrating GlobalPay Payment Gateway into Angular applications.

Project Setup

To use packages from Azure Artifacts, configure your project to reference this feed.

Create a new text file called “.npmrc” in the same directory as your package.json, then copy the
snippet below

@zenith/registry=https://pkgs.dev.azure.com/ZBPlc/ZenithSDKs/_packaging/ZenithSDKFeed/np
m

Installation
npm install @zenith/globalpay-angular

Usage

Module (<= angular 16) - Import the module

Import GlobalPayModule into your Angular application's module where Globalpay is used:

import { NgModule } from '@angular/core';

import { BrowserModule } from '@angular/platform-browser';

import { GlobalPayModule } from '@zenith/globalpay-angular';

@NgModule({

declarations: [

// Your components
 ],

imports: [

BrowserModule,

GlobalPayModule
],

providers: [],

bootstrap: [AppComponent]
})

export class AppModule { }

Standalone (>= angular 17) - Add to imports

import { Component } from '@angular/core';

import { GeneratePaymentLinkPayload } from '@zenith/globalpay-angular';

@Component({
selector: 'your-component',
standalone: true,
imports: [GlobalPayModule],
templateUrl: './your-component.component.html',
styleUrls: ['./your-component.component.scss']
})
export class YourComponent {
}
Use the component
Use the globalpay component in your template:

<globalpay
[apiKey]="apiKey"
[payload]="payload"
[buttonStyle]="buttonStyle"
[buttonText]="buttonText"
(onError)="onError($event)"
>
</globalpay>

import { GeneratePaymentLinkPayload } from '@zenith/globalpay-angular';

import { Component } from '@angular/core';

import { GeneratePaymentLinkPayload } from '@zenith/globalpay-angular';

@Component({

selector: 'your-component',

templateUrl: './your-component.component.html',

styleUrls: ['./your-component.component.scss']

})

export class YourComponent {

payload: GeneratePaymentLinkPayload = {

amount: 1500,
 merchantTransactionReference: "your transaction reference",

redirectUrl: "your redirect url",

customer: {

lastName: "Doe",

firstName: "John",

currency: "NGN",

phoneNumber: "customer phone number",

address: "string",

emailAddress: "customer email"

};

apiKey = 'your api key';

buttonStyle = {

'background': 'red',

'font-size': '16px'

// other styles

};

buttonText = "Proceed to Pay";

onError(error: GeneratePaymentLinkError){

console.log(error)

}
Vue

VueJs library for integrating GlobalPay Payment Gateway into VueJs applications

Project Setup

To use packages from Azure Artifacts, configure your project to reference this feed.

Create a new text file called “.npmrc” in the same directory as your package.json, then copy the
snippet below

@zenith/registry=https://pkgs.dev.azure.com/ZBPlc/ZenithSDKs/_packaging/ZenithSDKFeed/np
m

Installation
npm install @zenith/globalpay-vue

Sample Usage

Import the GlobalPay Component (and Payload Type if you're using Typescript)

<script setup lang="ts">

import { GlobalPay } from '@zenith/globalpay-vue';

import { GeneratePaymentLinkPayload, GeneratePaymentLinkError } from

'@zenith/globalpay-vue/components/GlobalPay.vue';

const payload: GeneratePaymentLinkPayload = {

amount: 200,

merchantTransactionReference: "your-reference",

redirectUrl: "www.google.com",

customer: {

lastName: "customerfirstname",
 firstName: "customerlastname",

currency: "NGN",

phoneNumber: "081000000000",

address: "",

emailAddress: "customer email address"

};

const style = {

background: 'green',

color: 'yellow'

};

const erroHandler = (error: GeneratePaymentLinkError) => {console.log(error)}

</script>

<template>

<GlobalPay

:isLive="false"

:apiKey="'your-api-key'"

:buttonText="'Pay'"

:buttonStyle="style"

:payload="payload"

:onError="erroHandler"

/>

</template>
Javascript
Plain Javascript library for integrating GlobalPay Payment Gateway into websites.

Sample Usage
Add a script tag as part of your header with link below as source

<!DOCTYPE html>

<html lang="en">

<head>

<meta charset="UTF-8">

<meta name="viewport" content="width=device-width, initial-scale=1.0">

<title>Document</title>

<script src="{link}/globalpay-javascript-library/dist/globalpay-library.js"></script>

</head>

<body>

<button onclick="pay()">Test Payment</button>

<script>

function errorHandler(error){

window.alert(error.message);

function pay(){

let payload = {
 "amount": 200,

"merchantTransactionReference": "your-reference",

"redirectUrl": "your-redirect-url",

"customer": {

"lastName": "CustomerFirstName",

"firstName": "CustomerLastName",

"currency": "NGN",

"phoneNumber": "customerphone",

"address": "string",

"emailAddress": "customer email"

};

try{

GlobalPay.generatePaymentLink(true, "your-api-key", payload, errorHandler);

}catch(error){

console.log(error.message);

</script>

</body>

</html>
WEBHOOKS
Webhook

1. Webhook url is set up on the globalpay dashboard by the merchant during activation.
2. For every transaction, a notification is sent via this webhook, for every successful and failed
transaction.
3. There must be a connection establishment using the public key.
4. There is encryption using the AES algorithm.
a. length - 16bytes
b. Decryption key - merchant public key

Decryption Engine:

public static string DecryptString(string cipherText, string keyString)

{
byte[] fullCipher = Convert.FromBase64String(cipherText);
try
{

using (Aes aesAlg = Aes.Create())

{
aesAlg.Padding = PaddingMode.PKCS7;
aesAlg.Key = Encoding.UTF8.GetBytes(keyString);

// Extract IV from the beginning of the cipher text

byte[] iv = new byte[aesAlg.IV.Length];
Array.Copy(fullCipher, 0, iv, 0, aesAlg.IV.Length);

using (ICryptoTransform decryptor = aesAlg.CreateDecryptor(aesAlg.Key, iv))

{
string result;
 using (MemoryStream msDecrypt = new MemoryStream())
{
using (CryptoStream csDecrypt = new CryptoStream(msDecrypt, decryptor,
CryptoStreamMode.Write))
{
// Skip the IV when decrypting
csDecrypt.Write(fullCipher, aesAlg.IV.Length, fullCipher.Length -
aesAlg.IV.Length);
}

result = Encoding.UTF8.GetString(msDecrypt.ToArray());
}

return result;
}
}
}
catch(Exception ex)
{
return
string.IsNullOrWhiteSpace(ex.Message)?ex?.InnerException.Message:ex.Message;
}
}

Decryption sample code

public static WebhookResponse Getresponse(WebHookPayloadRequest

request, IConfiguration config)
{
var response = new WebhookResponse();
var publiccKy =
config.GetValue<string>("Settings:PublicKey");
var decrypted =
EncryptionHelper.DecryptString(request.Request, publiccKy);
var data =
JsonConvert.DeserializeObject<WebhookPayload>(decrypted);
if (data != null &&
!string.IsNullOrWhiteSpace(data.TransactionReference))
{
response.Status = true;
response.ResponseDescription = "Request was
successful";
response.ResponseCode = "00";

}
else
{
 response.Status = false;
response.ResponseDescription = "Request was not
successful";
response.ResponseCode = "99";
}
return response;

}
(2) Data Contracts:

(a) Payload Model:

public class WebHookPayloadRequest
{
public string Request { get; set; }

}
(b) Response Model:
public class WebhookResponse
{
public string ResponseCode { get; set; }
public string ResponseDescription { get; set; }
public bool Status { get; set; }

(c) Deserialized Model:

public class WebhookPayload

{
public decimal? TransactionFee { get; set; }
public string TransactionReference { get; set; }
public string MerchantTransactionreference { get; set; }
public DateTime PaymentDate { get; set; }
public string PaymentChannel { get; set; }
public decimal? InAmount { get; set; }
public decimal? Amount { get; set; }
public string ChargeOn { get; set; }
public string Customer { get; set; }
public string Currency { get; set; }
public string AccountNumber { get; set; }
public string RedirectUrl { get; set; }
public string CardPan { get; set; }
public string TransactionSource { get; set; }
}

5. Status -

a. if Status is true, call is successful

b. If status is false, call is unsuccessful.

6. Response code:
 a. If 00 = Successful

b. if 99 = Unsuccessful

7. Merchants are advised not to disclose any of their credentials to

anyone.

8. If merchant feels credentials are exposed, another can be

generated via the merchant’s dashboard.