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:
- The SHA-256 HMAC calculation includes all fields listed above.
- The field names are sorted in ascending of parameter name as listed above.
-
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.
- 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.
- 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
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:
- e-mail ecomm.support@moamalat.net
- tel 0910003325