Moamalat GATEWAY - NOTIFICATION SERVICES INTEGRATION GUIDE

The purpose of this document is to specify how to extend payment options to use (NOTIFICATION SERVICES) to e-commerce customers in a few simple steps.

GLOSSARY

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.

What is Notification Services

Notification Services allow merchants to receive notifications whenever a transaction is generated for their accounts. In order to receive notifications from this service, you will need to implement a restful API service according to the specifications in this document.

Supported channels:

• NUMO card schemes.
• International card schemes - Visa and Mastercard.
• Mobile Wallet schemes.

CHECKLIST

In order to enable the NOTIFICATION SERVICES you will need the following:

• Merchant should have Merchant ID assigned.
• Merchant should have at least one “web terminal” and Terminal ID assigned to allow card acceptance.

Request Message Formats

In order to receive transaction notifications, you need to implement a restful service according to below specs:

Request Example

            {
                "MerchantId":"12345678901",
                "TerminalId":"12345678",
                "DateTimeLocalTrxn":"20191231083054",
                "SecureHash":"B19F0899B305363544E81D9DADD95DFDBD0605700CC1CB02A0C2746A90D62DE8",
                "TxnType":1,
                "Message":"Approved",
                "PaidThrough":"Card",
                "SystemReference":"534727",
                "NetworkReference":"2070043320",
                "MerchantReference":null,
                "Amount":"200000",
                "Currency":"818",
                "PayerAccount":"4000000XXXXXX38",
                "PayerName":null,
                "ActionCode":"00"
            } 
                    

Response Message Formats

Response Example

    {
        "Message":"Success”,
        "Success":true
    }  
         

APIs Secure hash generation

• Request data to be hashed:
  • DateTimeLocalTrxn
  • MerchantId
  • TerminalId
  • Amount
  • Currency
• Merchant SecretKey to be provided by the merchant, should be hex decimal string with max 100 chars
• The SHA-256 HMAC is calculated as follows:
  1. The SHA-256 HMAC calculation includes all fields listed above.
  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.
     1. The field name and the value in each field name-value pair are joined using "=" as the separator.
     2. 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 and convert it to uppercase, then compare it with SecureHash field at the request it should be the same and any other values indicates unauthorized notification 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:

RESPONSE CODES

For more support, Please contact us at:

• e-mail ecomm.support@moamalat.net
• tel 0910003325