Version: 4.7
Last Updated: 6th Feb, 2022

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.
To get your own credentials Please contact us at:

GETTING STARTED

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

Merchant test data

Field Type Value
Merchant id String 10081014649
Terminal Id String 99179395
Secure key String 39636630633731362D663963322D346362642D386531662D633963303432353936373431

Card test data

Field Type Value
Card number String 6394993077260781
EXP date String 10/23
OTP String 111111

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.

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.

Moamalat Payment Gateway

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
PayerName String 0-50 O Payer name associated to the payer account
ProviderSchemeName String 5-20 O Payer wallet provider name
SecureHash String 64/td> 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"
}

MOAMALAT GATEWAY - DATA SERVICE

This section details how to integrate with Moamalat via API interface to retrieve transaction data Message Definition
The web service takes a JSON request to search on transaction log.

API URL:

REQUEST MESSAGE FORMAT

Item Data Type Leanght Optional/ Mandatory Comments
MerchantReference String 10-36 O Merchant Reference for the transaction
NetworkReference String 10-36 O payment gateway reference number in case of card transactions
TerminalId String 6-8 M The Moamalat terminal ID
MerchantId String 11-18 M Moamalat Merchant Id applied the transaction
DisplayLength String 1-5 M Number of Transactions required to be returned for the request
DisplayStart String 1-5 M The index to start fetch data from
DateTimeLocalTrxn String 12 M The request execution date and time with format “YYMMDDHHMMSS” and it should be unique per terminal requests
DateFrom String 12 O The transaction execution date and time with format “yyyyMMdd” to start search from
DateFrom String 12 O The transaction execution date and time with format “yyyyMMdd” to start search from
DateTo String 12 O The transaction execution date and time with format “yyyyMMdd” to end search to
SortCol String 1-25 O The column name you want to sort data with
SortDir String 1-25 O The Sort direction either “asc” or “desc”
SecureHash String 20-250 O A keyed hash message authorization code (HMAC) is a specific type of message authorization code (MAC) involving a cryptographic hash function and a secret cryptographic key. It is used to verify both the data integrity and the authorization of a message.

Request Example

    
    {
        "MerchantReference":"MR123EF278",
        "TerminalId":"84949616",
        "MerchantId":"45374",
        "DisplayLength":"1",
        "DisplayStart":"0",
        "DateTimeLocalTrxn":"181142172106",
        "SecureHash":"F69E47CE228EA038034B71647DF069
        01BA36CD19F639D5CAE4AB4CA5D2D93014" 
    }

Response Message Formats

Item Data Type Leanght Comments
Message String 0-250 The message describes the transaction execution status
Success Boolean 4-5 Describe transaction execution status.
Transactions The array of transactions returned from applying search parameters
CardNo String 10-16 The card number executed the transaction
DisplayLength String 1-5 Number of Transactions required to be returned for the request
DisplayStart String 1-5 The index to start fetch data from
MobileNumber String 12-14 The mobile number in case this is a Wallet transaction
Amnt Integer 1-15 The transaction amount in smallest currency unit
Status String 1-25 “Approved” if the transaction executed successfully
Currency String 3-3 The Transaction Currency shall conform to [ISO 4217] and shall contain the 3-digit numeric representation of the currency. For example, LYD is represented by the value "434"
TransType String 1-25 The transaction type
CardType String 1-25 The card type
STAN String 1-14 The system trace number
RRN String 12-36 Retrieval reference number returned by the payment gateway
MerchantReference String 0-300 Merchant Reference for this transaction
ReceiptNo String 12-14 The receipt number returned by the payment gateway
TotalCountAllTransaction Integer 1-10 The total count of returned transactions from search result

Response Example

    

{
    "Message": null,
    "Success": true, "TotalCountAllTransaction": 1,
    "Transactions": [
    {
    "Date": "18/11/2018",
    "DateTotalAmount": "154",
    "DateTransactions": [
        {
        "Amnt": "77",
        "AmountTrxn": "77",
        "CardNo": "400000XXXXXX0002", 
        "CardType": "VISA",
        "Currency": "EGP",
        "ExternalTxnId": null,
        "FeeAmnt": "0",
        "IsRefundEnabled": true,
        "IsSend": false,
        "MerchantReference": "Merchant_REF", 
        "MobileNumber": null,
        "RRN": "1100053340",
        "ReceiptNo": "832302529385",
        "ResCodeDesc": "Approved", 
        "STAN": "878561", 
        "SenderName": null,
        "Status": "Approved",
        "TipAmnt": "0",
        "TransType": "Sale", 
        "TransactionChannel": "Card", 
        "TransactionId": "65324", 
        "TxnDateTime": "18/11/18 17:15"
        } ]
    } ]
}

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

DATA SERVICE API SECURE HASH

The SHA-256 HMAC is calculated as follows:

  1. The SHA-256 HMAC calculation includes these fields:
    • DateTimeLocalTrxn
    • MerchantId
    • 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 MOAMALAT integration 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:
34376635346431302D353564662D346334652D623965302D656239653030306637323161

Using the following parameters:
DateTimeLocalTrxn=1811101423&MerchantId=45374&TerminalId=84949616

The resulting secure hash will be:
CF0B9237DCC8D31F985B6203BDBA634019717D746BAA1B8C7F198BA3DA0B6A96

Use the following LINK with correct parameters are set:

HASH GENERATION

RESPONSE CODES

Code Meaning
00 Successful approval/completion or that VIP PIN verification is valid
01 Refer to card issuer
02 Refer to card issuer, special condition
03 Invalid merchant or service provider
04 Pickup
05 Do not honor
06 General error
07 Pick up card, special condition (other than lost/stolen card)
08 Honor with identification
09 Request in progress
10 Partial approval
11 VIP approval
12 Invalid transaction
13 Invalid amount (currency conversion field overflow) or amount exceeds maximum for card program
14 Invalid account number (no such number)
15 No such issuer
16 Insufficient funds
17 Customer cancellation
19 Re-enter transaction
20 Invalid response
21 No action taken (unable to back out prior transaction)
22 Suspected Malfunction
25 Unable to locate record in file, or account number is missing from the inquiry
28 File is temporarily unavailable
30 at error
41 Merchant should retain card (card reported lost)
43 Merchant should retain card (card reported stolen)
51 Insufficient funds
52 No checking account
53 No savings account
54 Expired card
55 Incorrect PIN
57 Transaction not permitted to cardholder
58 Transaction not allowed at terminal
59 Suspected fraud
61 Activity amount limit exceeded
62 Restricted card (for example, in country exclusion table)
63 Security violation
65 Activity count limit exceeded
68 Response received too late
75 Allowable number of PIN-entry tries exceeded
76 Unable to locate previous message (no match on retrieval reference number)
77 Previous message located for a repeat or reversal, but repeat or reversal data are inconsistent with original message
78 ’Blocked, first used’—The transaction is from a new cardholder, and the card has not been properly unblocked.
80 Visa transactions: credit issuer unavailable. Private label and check acceptance: Invalid date
81 PIN cryptographic error found (error found by VIC security module during PIN decryption)
82 Negative CAM, dCVV, iCVV, or CVV results
83 Unable to verify PIN
85 No reason to decline a request for account number verification, address verification, CVV2 verification; or a credit voucher or merchandise return
91 Issuer unavailable or switch inoperative (STIP not applicable or available for this transaction)
92 Destination cannot be found for routing
93 Transaction cannot be completed, violation of law
94 Duplicate transmission
95 Reconcile error
96 System malfunction, System malfunction or certain field error conditions
B1 Surcharge amount not permitted on Visa cards (U.S. acquirers only)
N0 Force STIP
N3 Cash service not available
N4 Cashback request exceeds issuer limit
N7 Decline for CVV2 failure
P2 Invalid biller ination
P5 PIN change/unblock request declined
P6 Unsafe PIN
Q1 Card authentication failed
R0 Stop payment order
R1 Revocation of authorization order
R3 Revocation of all authorizations order
XA Forward to issuer
XD Forward to issuer
Z3 Unable to go online
© Moamalat