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:

Message Item Data Type Leanght Optional/ Mandatory Comments
MerchantId String 1-18 M The merchant ID
TerminalId String 1-8 M The terminal ID defined to use APIs
SecureHash String 20-250 M 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.
DateTimeLocalTrxn String 12-12 M The transaction execution date and time with format” yyyyMMddHHmmss”
TrxDateTime String 12 O Request datetime in format “yyyyMMddHHmm” and it will be required when sending secure hash at request
Message String 0-250 M The message describes the transaction initiation status.
TxnType Integer 1-5 M Identifies transaction type:
1: Sale
2: Refund
3: Void Sale
4: Void Refund
PaidThrough String 1-50 M The source of transaction execution (Card, Wallet, etc…)
SystemReference String 1-14 M Moamalat gateway Reference number
NetwrokReference String 0-32 O Network reference number
MerchantReference String 0-300 O Merchant Reference for this transaction, TLV
Amount String 1-15 M The original transaction amount in smallest currency units
Currency String 3-3 M The Transaction Currency shall conform to [ISO 4217] and shall contain the 3-digit numeric representation of the currency. For example, EGP is represented by the value "818".
PayerAccount String 10-100 M The customer account used for the transaction, for card transactions it’s the masked card number
ActionCode String 0-3 O The payment gateway action code.
SID String 0-200 O Terminal SID
Token String 0-200 O Terminal Token

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

Message Item Data Type Leanght Optional/ Mandatory Comments
Message String 0-250 M The message describes the transaction initiation status.
Success Boolean 4-4 M True, if the transaction initiated successfully.

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:

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


For more support, Please contact us at: