PAYFORM™ PLUS INTEGRATION GUIDE

The purpose of this document is to specify how to integrate with Moamalat Gateway - PayForm™ Plus to extend payment options to e-commerce customers in few simple steps.

To use this PayForm™, you need a Merchant id ,Terminal id and Secure key.

GETTING STARTED

**You can use test data to try making a transaction with the PayForm™ Plus:

WHAT IS LIGHTBOX

Lightbox is a simple HTML & JavaScript plugin to integrate within merchant’s website to seamlessly enable payments with minimal technical development in order to process payments on Moamalat Gateway.

PREREQUISITES

In order to start integration with Moamalat Gateway you need to obtain the following from your partner bank:

1. Merchant ID: Merchant unique identifier.
2. Terminal ID: ID of the acceptance interface with different acceptance channels enabled/disabled (Card, Digital QR)

GLOSSARY

CVV (Card Verification Value) – Is the three digits’ number on the back of a credit card, the cardholder is required to enter the CVV number at transaction time to verify that the card is on hand.

HMAC- Hash-based Message Authentication Code - AKA keyed-hash message authentication code, is a specific type of message authentication code (MAC) involving a cryptographic hash function and a secret cryptographic key. It may be used to simultaneously verify both the data integrity and the authentication of a message, as with any MAC.

Host ID - is a specific piece of information which uniquely identifies the host used for transaction authorization.

PAN: Primary Account Number

STAN: System Trace Audit Number - A number assigned by the originator of a transaction to uniquely identify a transaction throughout its life.

CHECKLIST

In order to enable Moamalat Gateway - PayForm on the merchant’s website, the following needs to be applied:

• Merchant must subscribe in Moamalat Gateway and enable selected acceptance networks to the merchant like Card, Wallet.
• Merchant must have a “web terminal” to allow different payment channels.

CONFIGURATION STEPS

1. Reference the Lightbox.js file: Can be found on:

Test: https://tnpg.moamalat.net:6006/js/lightbox.js

Production: https://npg.moamalat.net:6006/js/lightbox.js

<script src="https://tnpg.moamalat.net:6006/js/lightbox.js"> </script>

2. Setup LightBox configuration using “Lightbox.Checkout.configure”, request parameters details at parameters section.

3. Setup callbacks functions:

• completeCallback: triggered when payment completed successfully, result data object details at parameters section.
• errorCallback: triggered when payment has an error, error object details at parameters section
• cancelCallback: triggered when user closes lightbox.

Lightbox.Checkout.configure = {
  MID: mID,
  TID: tID,
  AmountTrxn: amount,
  MerchantReference: "merchantReference",
  TrxDateTime: "202009171418",
  SecureHash:
    "EAD7AB68E23BFF2E5B03F4A0CD41581722FD14C349C6743CD91B577341465A61",
  completeCallback: function (data) {
    //your code here
  },
  errorCallback: function (error) {
    //your code here
  },
  cancelCallback: function () {
    //your code here
  },
};

4. Start the payment process by calling Lightbox.Checkout.showLightbox();
5. You can close LightBox by calling Lightbox.Checkout.closeLightbox();

PARAMETERS

REQUEST PARAMETERS

Item	Data Type	Leanght	Optional/ Mandatory	Comments
MID	String	11-18	M	The configured Moamalat Gateway Merchant ID
TID	String	6-8	M	Moamalat Gateway configured Terminal ID for the merchant
AmountTrxn	Integer	1-15	M	The payment amount in smallest currency unit, i.e., 1 Libyan dinar should be 1000
MerchantReference	String	1-50	O	Merchant reference for the transaction.
TrxDateTime	String	12	O	Request datetime in format “yyyyMMddHHmm” and it will be required when sending secure hash at request.
SecureHash	String	64	O	Used for request integrity between client call and server.

COMPLETE CALLBACK PARAMETERS

Item	Data Type	Leanght	Optional/ Mandatory	Comments
TxnDate	String	12	M	Transaction execution date and time, format yyyyMMddHHmm.
SystemReference	String	2-20	M	Moamalat Gateway transaction reference.
NetworkReference	String	10-15	M	Gateway reference number in case of card transactions.
MerchantReference	String	1-50	O	Merchant reference for the transaction.
Amount	String	1-15	M	The payment amount in smallest currency unit, i.e., 1 Libyan dinar should be 1000.
Currency	String	3	M	Transaction currency ISO code, LYD represented by 434.
PaidThrough	String	4-10	M	Transaction payment method (Card, Tahweel, mVisa).
PayerAccount	String	14-36	M	Masked card number in case of (card) transaction or (mobile number) in case of Wallet transaction.
PayerName	String	0-50	O	Payer name associated to the payer account.
ProviderSchemeName	String	5-20	O	Payer wallet provider name.
SecureHash	String	64	M	Used for response callback integrity between client call and server.

    {
        Amount: "100",
        Currency: "818",
        MerchantReference: "Txn-1234",
        NetworkReference: "10005908321",
        PaidThrough: "Card",
        PayerAccount: "400000XXXXXX0002",
        PayerName: "123",
        ProviderSchemeName: "",
        SecureHash: "7E78BC68D15B717317ED7BBDC99A4AF7C50491D0D1E99155FD103B851428D2CD",
        SystemReference: "78554"
        TxnDate: "200917135922",
    }

ERROR CALLBACK PARAMETERS

Item	Data Type	Leanght	Optional/ Mandatory	Comments
error	String	11-18	M	Error message and may contain error codes.
DateTimeLocalTrxn	String	12	M	Error datetime
MerchantReference	Integer	1-50	O	Merchant reference for the transaction
Amount	String	12	O	transaction amount
SecureHash	String	64	M	Used for request integrity between client call and server.

{
     Amount: "1",
     DateTimeLocalTrxn: "200917142042",
     MerchantReferenece: "Txn-1234",
     SecureHash: "6226DEDA2D88E356BF3552F089EBC228242AC5B2ACD72C7A8B9749E048C65C0C",
     error: "Host Error"
}

SECURE HASH GENERATION

Secure hash used to verify client request and to ensure request data integrity, and its used at:

1. LightBox request verification.
2. LightBox complete callback verification.
3. LightBox error callback verification.
4. Data service API request verification.

Pre-requisite:

Merchant Secret Key: to generate a valid secure hash is to have merchant secret key provided by MOAMALAT

LIGHTBOX REQUEST SECURE HASH

The SHA-256 HMAC is calculated as follows:

1. The SHA-256 HMAC calculation includes these fields:

• Amount
• DateTimeLocalTrxn
• MerchantId
• MerchantReference
• TerminalId

2. The field names are sorted in ascending of parameter name as listed above.
3. Construct a string by concatenating the string form of the sorted field name-value pairs. The string form of a name-value pair is the name followed by the value.

• The field name and the value in each field name-value pair are joined using "=" as the separator.
• The resulting joined field name-value pairs are themselves joined using "&" as the separator.

4. Create a SHA-256 HMAC of the resultant string using the hex decoded value of merchant secret key given by MOAMALATintegration consultant as the key.
5. Encode the HMAC in hexadecimal convert it to uppercase and populate it in the request as the value for the SecureHash field that will be added to the request.

Example:

Using the following merchant secret key: 35333335653063302D663464372D343237652D623739362D643234666661386432323065

Using the following parameters: Amount=100&DateTimeLocalTrxn=202009171418&MerchantId=43233&MerchantReference=Txn-1234&TerminalId=53532091

The resulting secure hash will be: EAD7AB68E23BFF2E5B03F4A0CD41581722FD14C349C6743CD91B577341465A61

LIGHTBOX COMPLETE CALLBACK SECURE HASH

The SHA-256 HMAC is calculated as follows:

1. All response query strings parameters except “SecureHash” should be included at hashing.
2. The field names are sorted in ascending of parameter name as listed above.
3. Construct a string by concatenating the string form of the sorted field name-value pairs. The string form of a name-value pair is the name followed by the value.

• The field name and the value in each field name-value pair are joined using "=" as the separator.
• The resulting joined field name-value pairs are themselves joined using "&" as the separator.

4. Create a SHA-256 HMAC of the resultant string using the hex decoded value of merchant secret key given by MOAMALATintegration consultant as the key.
5. Encode the HMAC in hexadecimal convert it to uppercase andcompare it to callback SecureHash value

Example:

Using the following merchant secret key: 62656164643366382D626466612D343461392D383630332D346135613363376666356264

Using the following parameters: Amount=55&Currency=818&MerchantId=14554075972&MerchantReference=1234&PaidThrough=Card&TerminalId=93171742&TxnDate=20190826111304

The resulting secure hash will be: AFE674E81B1933DAFBCB5BB4A7A78C5F644AF104CA340AEBD5379FEE86FF1EEE

LIGHTBOX ERROR CALLBACK SECURE HASH

The SHA-256 HMAC is calculated as follows:

1. The SHA-256 HMAC calculation includes these fields:

• Amount
• DateTimeLocalTrxn
• ErrorMessage
• MerchantId
• MerchantReference
• TerminalId

2. The field names are sorted in ascending of parameter name as listed above.
3. Construct a string by concatenating the string form of the sorted field name-value pairs. The string form of a name-value pair is the name followed by the value.

• The field name and the value in each field name-value pair are joined using "=" as the separator.
• The resulting joined field name-value pairs are themselves joined using "&" as the separator.

4. Create a SHA-256 HMAC of the resultant string using the hex decoded value of merchant secret key given by MOAMALATintegration consultant as the key.
5. Encode the HMAC in hexadecimal convert it to uppercase andcompare it to callback SecureHash value

Example:

Using the following merchant secret key: 62656164643366382D626466612D343461392D383630332D346135613363376666356264

Using the following parameters: Amount=55&DateTimeLocalTrxn=20190826111304&ErrorMessage=CubeEX:132123&MerchantId=14554075972&MerchantReference=1234&TerminalId=93171742

The resulting secure hash will be: 92DCAEF9F9F3FB0280F29892A1E88DBBF562F34005024CCBA21DC7D83B046C8C

Use the following LINK with correct parameters are set:

RESPONSE CODES

**For more details

DEMO PAY