PaySky OMNI Gateway – Notification Services Integration Guide

INTRODUCTION #

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.

NOTIFICATION SERVICES #

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

Request Example

Response Message Formats

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.

Example:

use the following URL: https://www.liavaag.org/English/SHA–Generator/HMAC/ with correct parameters are set: