PaySky OMNI Gateway – PayForm Plus Integration guide

INTRODUCTION #

PURPOSE OF DOCUMENT #

The purpose of this document is to specify how to integrate with PaySky OMNI Gateway – PayForm™ Plus to enable payment options on any website in few simple steps. 

Supported Payment channels by PaySky OMNI Gateway:

• Digital Payment Schemes – Tahweel and mVISA.
• National Payment Scheme (Egypt) – Meeza cards.
• International Card Schemes – Visa and Mastercard.
• Pay on Delivery (Payment on POS with delivery)

PREREQUISITES #

In order to start integration with PaySky OMNI Gateway you need to obtain the following from your partner bank:

1. Merchant ID: Merchant unique identifier.
2. Terminal ID: ID of the acceptance interface with different acceptance channels enabled/disabled (Card, Digital QR, & Pay on Delivery)

GLOSSARY #

CVV (Card Verification Value) – Is the three digits’ number on the back of a credit card, the cardholder is required to enter the CVV number at transaction time to verify that the card is on hand.

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.

Host ID – is a specific piece of information which uniquely identifies the host used for transaction authorization.

PAN: Primary Account Number

STAN: System Trace Audit Number – A number assigned by the originator of a transaction to uniquely identify a transaction throughout its life.

PAYSKY OMNI GATEWAY – DATA SERVICE #

This section details how to integrate with PAYSKY via API interface to retrieve transaction data Message Definition

The web service takes a JSON request to search on transaction log.

API URL:

• Test: https://grey.paysky.io/cube/paylink.svc/api/FilterTransactions
• Production: https://cube.paysky.io/cube/paylink.svc/api/FilterTransactions

Request Message Format

Request Example

Response Message Formats

Response Example

ANNEX A: TEST DATA #

• International Card Test data:

• National Card Test data:

• Terminal ID:  Please refer to your integration consultant 
• Merchant ID:  Please refer to your integration consultant
• Sample Test Page:(you can view below page source and copy JS sample)

http://grey.paysky.io/PaySkyPayFormTestCheckout.html

ANNEX B: SECURE HASH GENERATION #

Secure hash used to verify client request and to ensure request data integrity, and its used at:

1. LightBox request verification
2. LightBox complete callback verification
3. LightBox error callback verification
4. Data service API request verification

Pre-requisite:

Merchant Secret Key: to generate a valid secure hash is to have merchant secret key provided by PaySky

 LIGHTBOX REQUEST SECURE HASH #

The SHA-256 HMAC is calculated as follows:

1. The SHA-256 HMAC calculation includes these fields:
   • Amount
   • DateTimeLocalTrxn
   • MerchantId
   • MerchantReference
   • TerminalId
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.
   • 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.
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 convert it to uppercase and populate it in the request as the value for the SecureHash field that will be added to the request.

Example:

Using the following merchant secret key:

35333335653063302D663464372D343237652D623739362D643234666661386432323065

Using the following parameters:

Amount=100&DateTimeLocalTrxn=202009171418&MerchantId=43233&MerchantReference=Txn 1234&TerminalId=53532091

The resulting secure hash will be:

EAD7AB68E23BFF2E5B03F4A0CD41581722FD14C349C6743CD91B577341465A61

LIGHTBOX COMPLETE CALLBACK SECURE HASH #

The SHA-256 HMAC is calculated as follows:

1. All response query strings parameters except “SecureHash” should be included at hashing.
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.
   • 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.
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 convert it to uppercase and compare it to callback SecureHash value

Example:

Using the following merchant secret key:

62656164643366382D626466612D343461392D383630332D346135613363376666356264

Using the following parameters:

Amount=55&Currency=818&MerchantId=14554075972&MerchantReference=1234&PaidThrough=Card&Te  rminalId=93171742&TxnDate=20190826111304

The resulting secure hash will be:

AFE674E81B1933DAFBCB5BB4A7A78C5F644AF104CA340AEBD5379FEE86FF1EEE

LIGHTBOX ERROR CALLBACK SECURE HASH #

The SHA-256 HMAC is calculated as follows:

6. The SHA-256 HMAC calculation includes these fields:
   • Amount
   • DateTimeLocalTrxn
   • ErrorMessage
   • MerchantId
   • MerchantReference
   • TerminalId
7. The field names are sorted in ascending of parameter name as listed above.
8. 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.

9. 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.
10. Encode the HMAC in hexadecimal convert it to uppercase and compare it to callback SecureHash value

Example:

Using the following merchant secret key:

62656164643366382D626466612D343461392D383630332D346135613363376666356264

Using the following parameters:

Amount=55&DateTimeLocalTrxn=20190826111304&ErrorMessage=CubeEX:132123&MerchantId=14554075  972&MerchantReference=1234&TerminalId=93171742

The resulting secure hash will be:

92DCAEF9F9F3FB0280F29892A1E88DBBF562F34005024CCBA21DC7D83B046C8C

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

ANNEX C: RESPONSE CODES #