PaySky OMNI Gateway – Notification Services Integration Guide


Purpose of Document #

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:

  • International card schemes – Visa and Mastercard
  • Mobile Wallet schemes – TAHWEEL
  • Digital payment scheme – mVisa

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

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

Message Item Data Type Min-Max




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.

For more information on how to generate and verify secure hash read appendix A

DateTimeLocalTrxn String 12-12 M The transaction execution date and time with format” yyyyMMddHHmmss”
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 PaySky gateway Reference number
NetwrokReference String 0-32 O Tahweel reference number in case of a tahweel transaction. mVisa reference in case of mVisa Transaction
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
PayerName String 0-100 O The customer name used for the transaction
ActionCode String 0-3 O The payment gateway action code. For complete list please check appendix B

“00”: transaction approved

SID String 0-200 O Terminal SID
Token String 0-200 O Terminal Token

Request Example

D62DE8″,”TxnType”:1,”Message”:”Approved”,”PaidThrough”:”Card”,”SystemReference”:”5347 27″,”NetworkReference”:”2070043320″,”MerchantReference”:null,”Amount”:”200000″,”Curre ncy”:”818″,”PayerAccount”:”4000000XXXXXX38″,”PayerName”:null,”ActionCode”:”00″}

Response Message Formats

Message Item Data Type Min-Max




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


Appendix A: 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 PAYSKY 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.


Using the following merchant secret key:

Using the following parameters:
“Amount=100&Currency=818&DateTimeLocalTrxn=20180311035022&MerchantId=45374&TerminalId =84949616”

The resulting secure hash will be:

use the following URL: with correct parameters are set: 

Appendix B: Transaction 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

Powered by BetterDocs