Etisalat Payment Gateway

Integration Guide
Ecommerce Payment
REST
Version: 1.2.4
Prepared by: Merchant Integration Team
Email: [email protected]
Updated: July 2019
Revision History
Date Version Description Author
Jan 2018 1.0 First Draft Noor Mohamed
April 2018 1.1 Recurrence Payments Mohamed Akram
May 2018 1.2 Central Bank Payments Mohamed Akram
May 2018 1.2.1 User Name & Password Authentication Mohamed Akram
May 2018 1.2.2 Types of Recurring Payments Noor Mohamed
June 2018 1.2.3 Authorization Mohamed Akram
June 2018 1.2.4 Payment Page Customization Mohamed Akram
August 2018 1.2.4 Refund Mohamed Akram

Ecommerce Payment– Merchant Integration Support

2
Contents
1. INTRODUCTION ..................................................................................................................................... 5
2. Transaction Flow ................................................................................................................................... 5
3. Registration ........................................................................................................................................... 6
3.1. Registration Call Properties ...................................................................................................... 6
3.2. Sample Request ........................................................................................................................ 7
3.3. Sample Response ...................................................................................................................... 7
4. Finalization ............................................................................................................................................ 8
4.1. Finalization Call Properties........................................................................................................ 8
4.2. Sample Request ...................................................................................................................... 10
4.3. Sample Response .................................................................................................................... 10
5. Authorization ...................................................................................................................................... 12
5.1. Authorization call properties .................................................................................................. 12
5.2. Sample Request ...................................................................................................................... 13
5.3. Sample Response .................................................................................................................... 14
6. Capture................................................................................................................................................ 15
6.1. Capture call Properties............................................................................................................ 15
6.2. Sample Request ...................................................................................................................... 16
6.3. Sample Response .................................................................................................................... 17
7. Reversal ............................................................................................................................................... 18
7.1. Reversal call Properties ........................................................................................................... 18
7.2. Sample Request ...................................................................................................................... 19
7.3. Sample Response .................................................................................................................... 19
8. Refund ................................................................................................................................................. 20
8.1. Refund call Properties ............................................................................................................. 20
8.2. Sample Request ...................................................................................................................... 21
8.3. Sample Response .................................................................................................................... 21
9. Recurrence Payments ......................................................................................................................... 22
9.1. Registration for Recurrence Payments ....................................................................................... 22
9.1.1. User Present Scenario (Tokenization) ................................................................................. 24
9.1.2. Payer Not Present Scenario ................................................................................................ 25
10. Central Bank Payments ....................................................................................................................... 27

Ecommerce Payment– Merchant Integration Support

3
11. Payment Page Customization ............................................................................................................. 28
12. Appendix A .......................................................................................................................................... 30
12.1. Point of Sale Properties....................................................................................................... 30
12.2. Transaction Properties ........................................................................................................ 30
12.3. Buyer Properties ................................................................................................................. 33
12.4. Response Properties ........................................................................................................... 34
13. Appendix B .......................................................................................................................................... 37
13.1. Server Configuration. .......................................................................................................... 37
13.2. Test Credit Cards for Sandbox environment ....................................................................... 37
13.3. Client Certificate for Sandbox environment ....................................................................... 37
13.4. User Name and Password Authentication .......................................................................... 37

Ecommerce Payment– Merchant Integration Support

4
1. INTRODUCTION
The document provides the interface information to Integrate with Etisalat Payment Gateway
to perform Ecommerce payment using REST (JSON).

2. Transaction Flow
Please find the below transaction flow for Ecommerce transaction.

1. The registration call should be triggered to payment gateway in which the ReturnPath property
with Transaction details like amount , currency , OrderID ect should be mentioned.
2. Redirect to Payment Portal URL, returned in Register call with TransactionID as hidden field.
<form action=<Payment Portal URL> method="post">
<input type='Hidden' name='TransactionID' value=<TransactionID value>/>
<input type="submit" value="Submit">
3. Payer will proceed with 3D Secure Authentication process.
4. After 3D Authentication, control will returned back to Merchant’s ReturnPath property URL
received in registration call.
5. Merchant sends Finalization call to complete transaction.

Ecommerce Payment– Merchant Integration Support

5
3. Registration
3.1. Registration Call Properties

Required to provide the below properties while calling Registration.

Property Usage Comments
Request Properties
Customer Customer ID. Please refer to Appendix A MANDATORY
for Customer details.
Store Store. Please refer to Appendix A for Store OPTIONAL
details.
Terminal Terminal. Please refer to Appendix A for OPTIONAL
Terminal details.
Channel Payment Channel. Please refer to MANDATORY
Appendix A for Channel details.
Amount Total amount to be charged. MANDATORY
Currency Currency in which above mentioned MANDATORY
amount is to be charged.
OrderID Merchant can use this property to map id MANDATORY
for this transaction w.r.t. his system (can
also be auto generated, please refer to
Appendix A for format).
OrderName Short description for order. MANDATORY
OrderInfo Details of order. OPTIONAL
TransactionHint It is used to specify which payment MANDATORY
instruments should be available to the
buyer. Merchant can specify which
features should be supported by payment
instrument i.e. Auto Capture/Reversal or
Manual Capture/Reversal. By default it is
set Auto Capture. Kindly refer Appendix A
for more details about transactionHint.
ReturnPath Buyer will be redirected back to this URL MANDATORY
once the authentication of card is
completed.
UserName To be used in case of username/password OPTIONAL
authentication.

Ecommerce Payment– Merchant Integration Support

6
 Password To be used in case of username/password OPTIONAL
authentication.
Response Properties
TransactionID EPG TransactionID
PaymentPortal EPG Payment Page in which Payer will
enter the CreditCard
ResponseCode This field returns the exact response code.
Success is always
indicated with 0
ResponseDescription User-friendly description of the error in
ResponseCode.
Note: This field can only be used to display
the error description and
should not be used to check if transaction
was successful, to check if
transaction was successful please use
ResponseCode field.
UniqueID Unique reference ID for this call

3.2. Sample Request

{
"Registration”: {
"Currency": "AED",
"ReturnPath": "https://partner.ctdev.comtrust.ae/banktestnbad/Authorization.aspx?capture=true",
"TransactionHint": "CPT:Y;VCC:Y;",
"OrderID": "7210055701315195",
"Store": "Mobile",
"Terminal": "Recharge",
"Channel": "Web",
"Amount": "2.00",
"Customer": "Demo Merchant",
"OrderName": "Paybill",
"UserName":"Demo_fY9c",
"Password":"Comtrust@20182018"
}
}

3.3. Sample Response

Ecommerce Payment– Merchant Integration Support

7
 "Transaction":{
"PaymentPortal":"https://demo-
ipg.comtrust.ae/PaymentEx/Paymentpartner/Payment?lang=en&layout=C0STCBVLEI",
"PaymentPage":"https://demo-
ipg.comtrust.ae/PaymentEx/Paymentpartner/Payment?lang=en&layout=C0STCBVLEI",
"ResponseCode":"0",
"ResponseClass":"0",
"ResponseDescription":"Request Processed Successfully",
"ResponseClassDescription":"Success",
"TransactionID":"847718745846",
"Balance":{
"Value":"0"
},
"Amount":{
"Value":"0"
},
"Fees":{
"Value":"0"
},
"Payer":null,
"UniqueID":"a25ea7da-a212-406a-967b-94953191aad7"
}
}

4. Finalization
4.1. Finalization Call Properties

Required to provide the below properties while calling Finalization to complete payment.
Property Usage Comments
Request Properties
Customer Customer ID. Please refer to Appendix A MANDATORY
for Customer details.

Ecommerce Payment– Merchant Integration Support

8
TransactionID TransactionID returned in Registration MANDATORY
response.
UserName To be used in case of username/password OPTIONAL
authentication.
Password To be used in case of username/password OPTIONAL
authentication.
Response Properties
ResponseCode This field returns the exact response code.
Success is always
indicated with 0

ResponseDescription User-friendly description of the error in

ResponseCode.
Note: This field can only be used to display
the error description and
should not be used to check if transaction
was successful, to check if
transaction was successful please use
ResponseCode field.
UniqueID Unique reference ID for this call
OrderID It’s returned only in case of successful
transaction and if it had been set during
Registration call for same
ApprovalCode ApprovalCode, as sent by the issuer bank.
Merchant should save this code for future
reference and communication with issuer
bank related to a particular transaction.
Amount Amount charged for the transaction
Balance Balance amount for the transaction that
has not yet been captured
CardNumber Masked credit card number in following
format: xxxxxx********xxxx
It will return first 6 and last 4 digits of credit
card used for payment.
CardToken Tokenized value for the card used, it’s not
original credit card number but will always be
same for any particular credit card number
Account Name of account in payment gateway
configurations that transaction happened with
(to avoid any confusions, use this field for any

Ecommerce Payment– Merchant Integration Support

9
 references or logging only if advised by
Merchant Integration Support)

4.2. Sample Request

{
"Finalization": {
"TransactionID": "755580466468",
"Customer": "Demo Merchant",
"UserName":"Demo_fY9c",
"Password":"Comtrust@20182018"
}
}

4.3. Sample Response

{
"Transaction":{
"ResponseCode":"0",
"ResponseClass":"0",
"ResponseDescription":"Request processed successfully",
"ResponseClassDescription":"Success",
"Language":"en",
"ApprovalCode":"421218",
"Account":"NBAD mCommerce",
"Balance":{
"Value":"0"
},
"OrderID":"123456789",
"Amount":{
"Value":"1.120"
},
"Fees":{
"Value":"0"
},
"CardNumber":"411111******1111",

Ecommerce Payment– Merchant Integration Support

10
 "Payer":{
"Information":"411111******1111"
},
"CardToken":"4111110042761111",
"CardBrand":"Visa",
"UniqueID":"798ddc2f-f8e4-41e1-a5e3-b065448d75e3"
}
}

Ecommerce Payment– Merchant Integration Support

11
 5. Authorization
In this model, merchant collects all credit related information from the customer and complete
the payment in single call, if the Auto Capture is set. Otherwise either Capture or Reversal call
has to be performed similar to redirection model.

5.1. Authorization call properties

Property Usage Comments

Request Properties
Customer Customer ID. Please refer to Appendix A MANDATORY
for Business Channel details
Store Store. Please refer to Appendix A for OPTIONAL
Business Channel details
Terminal Terminal. Please refer to Appendix A for OPTIONAL
Business Channel details
Language en or ar OPTIONAL
Channel Payment Channel. Please refer to MANDATORY
Appendix A
Amount Amount to be captured. This Amount MANDATORY for
should be less than or equal to outstanding Partial Capture
balance amount.
Currency Currency in which above mentioned MANDATORY for
amount is to be charged. This Currency Partial Capture
should be same as that of mentioned in SPI
Registration or Authorization call.
TransactionHint Only allowed value is RVS:Y or RVS:N which MANDATORY
indicates whether remaining part of
balance should be reversed automatically
or not.
OrderID Merchant can use this property to map id MANDATORY
for this transaction w.r.t. his system
OrderName Short description for order MANDATORY
CardNumber Card number MANDATORY*
ExpiryMonth Expiry Month of Card MANDATORY*
ExpiryYear Expiry Year of Card MANDATORY*
CardTrack2 Card Track Data (read from card magnetic MANDATORY**
tape or chip like in case of kiosk devices)

Ecommerce Payment– Merchant Integration Support

12
 VerifyCode Credit Card Verification Code OPTIONAL
UserName To be used in case of username/password OPTIONAL
authentication.
Password To be used in case of username/password OPTIONAL
authentication.

Response Properties
ResponseCode This field returns the exact response code.
Success is always indicated with 0
ResponseDescription User-friendly description of the error in
ResponseCode.
Note: This field can only be used to display
the error description and
should not be used to check if transaction
was successful, to check if
Transaction was successful please use
ResponseCode field.
ApprovalCode ApprovalCode, as sent by the issuer bank.
TransactionID Reference number for ongoing transaction
OrderID It’s returned if it’s set to be auto generated
Amount Amount charged for the transaction
Balance Balance amount for the transaction that
has not yet been captured
CardNumber Masked card number
CardToken Tokenized value for the card/Account used
CardBrand Provides the details about which brand
been used for the payment.

*- For non-card present payments.

**- For Card present payments like kiosk, Mobile POS etc.
Below is the sample CardTrack2 data – “;4111111111111111=18112011000089600000?”

5.2. Sample Request

{
"Authorization": {
"Customer": "Demo Merchant",
"Language": "en",

Ecommerce Payment– Merchant Integration Support

13
 "Currency": "AED",
"OrderName": "Pinger-NBAD",
"OrderID": "990000227113719",
"Channel": "W",
"Amount": "100",
"TransactionHint": "CPT:Y;",
"CardNumber": "4111111111111111",
"ExpiryMonth": "11",
"ExpiryYear": "2020",
"VerifyCode": "123",
"UserName":"Demo_fY9c",
"Password":"Comtrust@20182018"
}
}

5.3. Sample Response

{
"Transaction": {
"ResponseCode": "0",
"ResponseClass": "0",
"ResponseDescription": "Request Processed Successfully",
"ResponseClassDescription": "Success",
"Language": "en",
"TransactionID": "202414738801",
"ApprovalCode": "861586",
"Account": "NBAD",
"Balance": {
"Value": "0",
"Printable": "Dhs.0.00"
},
"OrderID": "990000227113719",
"Amount": {
"Value": "100",
"Printable": "Dhs. 100.00"
},
"Fees": {
"Value": "0",
"Printable": "Dhs.0.00"
},
"CardNumber": "411111******1111",

Ecommerce Payment– Merchant Integration Support

14
 "Payer": {
"Information": "411111******1111"
},
"CardToken": "4111116104351111",
"CardBrand": "Visa",
"CardType": "Unknown",
"UniqueID": "861be72d-2e7a-49f7-9d58-cb5e3e88d8e5"
}
}

6. Capture
When the payment is not set with Auto-Capture, then the payment has to be captured by a
separate call. Partial and Full capture ca be performed on a payment transaction. In Full
capture, the total outstanding amount will be captured and in partial capture, only a portion of
outstanding amount will be captured.
6.1. Capture call Properties

Property Usage Comments

Request Properties
Customer Customer ID. Please refer to Appendix A MANDATORY
for Business Channel details
Store Store. Please refer to Appendix A for OPTIONAL
Business Channel details
Terminal Terminal. Please refer to Appendix A for OPTIONAL
Business Channel details
TransactionID TransactionID returned in Registration MANDATORY
response.
Amount Amount to be captured. This Amount MANDATORY for
should be less than or equal to outstanding Partial Capture
balance amount.
Currency Currency in which above mentioned MANDATORY for
amount is to be charged. This Currency Partial Capture
should be same as that of mentioned in SPI
Registration or Authorization call.
TransactionHint Only allowed value is RVS:Y or RVS:N which OPTIONAL
indicates whether remaining part of

Ecommerce Payment– Merchant Integration Support

15
 balance should be reversed automatically
or not.
UserName To be used in case of username/password OPTIONAL
authentication.
Password To be used in case of username/password OPTIONAL
authentication.
Response Properties
ResponseCode This field returns the exact response code.
Success is always indicated with 0
ResponseDescription User-friendly description of the error in
ResponseCode.
Note: This field can only be used to display
the error description and
should not be used to check if transaction
was successful, to check if
Transaction was successful please use
ResponseCode field.
UniqueID Unique reference ID for this call
TransactionID Reference for ongoing transaction
Balance Outstanding balance after current
transaction.

6.2. Sample Request

{
"Capture": {
"Amount": "1",
"Currency": "AED",
"TransactionID": "816483840525",
"Customer": "Demo Merchant",
"UserName":"Demo_fY9c",
"Password":"Comtrust@20182018"

}
}

Ecommerce Payment– Merchant Integration Support

16
 6.3. Sample Response

{
"Transaction": {
"ResponseCode": "0",
"ResponseClass": "0",
"ResponseDescription": "Request Processed Successfully",
"ResponseClassDescription": "Success",
"Balance": {
"Value": "18.000",
"Printable": "Dhs. 18.00"
},
"Amount": {
"Value": "0"
},
"Fees": {
"Value": "0"
},
"Payer": null,
"UniqueID": "94ca48ec-e046-4453-a121-9bd8996aeb8a"
}
}

Ecommerce Payment– Merchant Integration Support

17
 7. Reversal
When the payment is set with Manual-Capture, and to release the money to payer’s card
Reversal call has to be made. Full Reversal or Partial Reversal can be performed on a payment
transaction. Full Reversal will release entire outstanding amount to the payer’s card and Partial
Reversal will release portion of outstanding amount
7.1. Reversal call Properties

Property Usage Comments

Request Properties
Customer Customer ID. Please refer to Appendix A MANDATORY
for Business Channel details
Store Store. Please refer to Appendix A for OPTIONAL
Business Channel details
Terminal Terminal. Please refer to Appendix A for OPTIONAL
Business Channel details
TransactionID TransactionID returned in Registration MANDATORY
response.
Amount Amount to be Reversed. This Amount MANDATORY for
should be less than or equal to outstanding Partial Reversal
balance amount.
Currency Currency in which above mentioned MANDATORY for
amount is to be charged. This Currency Partial Reversal
should be same as that of mentioned in SPI
Registration or Authorization call.
UserName To be used in case of username/password OPTIONAL
authentication.
Password To be used in case of username/password OPTIONAL
authentication.
ResponseCode This field returns the exact response code.
Success is always indicated with 0
ResponseDescription User-friendly description of the error in
ResponseCode.
Note: This field can only be used to display
the error description and
should not be used to check if transaction
was successful, to check if

Ecommerce Payment– Merchant Integration Support

18
 transaction was successful please use
ResponseCode field.
UniqueID Unique reference ID for this call
TransactionID Reference for ongoing transaction
Balance Outstanding balance after current
transaction.

7.2. Sample Request

{
"Reversal": {
"Amount": "1",
"Currency": "AED",
"TransactionID": "816483840525",
"Customer": "Demo Merchant",
"UserName":"Demo_fY9c",
"Password":"Comtrust@20182018"

}
}

7.3. Sample Response

{
"Transaction": {
"ResponseCode": "0",
"ResponseClass": "0",
"ResponseDescription": "Request Processed Successfully",
"ResponseClassDescription": "Success",
"Balance": {
"Value": "17.000",
"Printable": "Dhs. 17.00"
},
"Amount": {
"Value": "0"
},
"Fees": {
"Value": "0"
},
"Payer": null,
"UniqueID": "41819851-04a9-4d71-97eb-59e0a9c6a5b9"
}
}

Ecommerce Payment– Merchant Integration Support

19
 8. Refund
Refund is used to refund the amount which is settled to merchant account. This will debit
money from the merchant account and credit to user’s card.
Note: Bank approval is required to enable Refund.
8.1. Refund call Properties

Property Usage Comments

Request Properties
Customer Customer ID. Please refer to Appendix A MANDATORY
for Business Channel details
Store Store. Please refer to Appendix A for OPTIONAL
Business Channel details
Terminal Terminal. Please refer to Appendix A for OPTIONAL
Business Channel details
TransactionID TransactionID returned in Registration MANDATORY
response.
Amount Amount to be Refund. This Amount should OPTIONAL
be same as the transaction amount.
Currency Currency used in Registration or OPTIONAL
Authorization call.
UserName To be used in case of username/password OPTIONAL
authentication.
Password To be used in case of username/password OPTIONAL
authentication.
ResponseCode This field returns the exact response code. MANDATORY
Success is always indicated with 0
ResponseDescription User-friendly description of the error in MANDATORY
ResponseCode.
Note: This field can only be used to display
the error description and

Ecommerce Payment– Merchant Integration Support

20
 should not be used to check if transaction
was successful, to check if
Transaction was successful please use
ResponseCode field.
ApprovalCode ApprovalCode, as sent by the issuer bank if Conditional
response code is 0. Mandatory
TransactionID Reference number for ongoing transaction

8.2. Sample Request

{
"Refund": {
"Amount": "1",
"Currency": "AED",
"TransactionID": "816483840525",
"Customer": "Demo Merchant",
"UserName":"Demo_fY9c",
"Password":"Comtrust@20182018"
}
}

8.3. Sample Response

"Transaction": {
"ResponseCode": "0",
"ResponseClass": "0",
"ResponseDescription": "Request Processed Successfully",
"ResponseClassDescription": "Success",
"Language": "en",
"ApprovalCode": "730274",
"Balance": {
"Value": "0"
},
"Amount": {
"Value": "0"
},

Ecommerce Payment– Merchant Integration Support

21
 "Fees": {
"Value": "0"
},
"Payer": null,
"UniqueID": "1fd1a6f2-3ec4-46de-8465-a28b14e46503"
}
}

9. Recurrence Payments
Recurring Payments is a solution where a Merchant wants to save Credit Card information
(sensitive data) and payer gives him permission to make future transactions on his behalf or
may be on just one click by payer (payer does not need to provide same Credit Card
information again and again) for his future transactions.
As per PCI standards, only PCI compliant companies are allowed to store any Credit Card
sensitive data like card number. Every merchant who wants to implement Recurring Payments
kind of functionality cannot afford to be PCI compliance.
So EPG is providing “Recurring Payments” feature where merchants will redirect the payers to
EPG where they’ll provide their Credit Card details, EPG will authenticate provided data and
return a reference for saved Card details for future Recurring Payment call from same Merchant
for that specific Credit Card.

9.1. Registration for Recurrence Payments

In this model, when the customer makes payment for the first time, he/she will be redirected
to payment page where he will provide his credit card number and complete the payment.
When this payment is marked as recurrence payment, EPG will store this credit number against
the TransactionID of this payment. This transaction is called Master Transaction and all the
subsequent transactions must use this master transaction id to indicate EPG to use the stored
credit card number.
To register for recurrence transaction, the below parameter to be added in the Registration call
and EPG will consider as a recurrence payment and will store the credit card number.

Ecommerce Payment– Merchant Integration Support

22
Sample Registration request to register for recurrence:
{
"Registration": {
"Customer": "Demo Merchant",
"Language": "en",
"OrderName": "PaymentDesc",
"OrderID": "TEST",
"Amount": "75.00",
"Currency": "AED",
"Recurrence": { "Type": "M" },
"OrderInfo": "Telephone Bills",
"TransactionHint": "CPT:Y;VCC:Y",
"ReturnPath": "https://demo-ipg.comtrust.ae/MerchantDemo/Authorization.aspx"
}
}

And in the response of registration call will have TransactionID as like normal payment call. This
ID is recurrence id and to be stored and used in all subsequent transaction. Other than this
minor change, everything else (Redirection, Finalization call) is similar to the normal payment.

Subsequent recurrence transaction can be initiated in 2 ways.

1) Payer Present Scenario: In this case payer will initiate payment, once redirecting to
payment gateway credit card will be auto populated so payer need to enter only CVV
value followed by 3D authentication.
2) Payer not Present Scenario: In this method Merchant can initiate payment through
batch process without the intervention of Payer.

Ecommerce Payment– Merchant Integration Support

23
 9.1.1. User Present Scenario (Tokenization)

When merchant initiate the subsequent payment transaction, the master transaction id to be
used in the registration call. Below is the extra parameter to be added in the Registration call
request.

The sample request message will look like below:

{
"Registration": {
"-version": "1.0",
"Customer": "Demo Merchant",
"Language": "en",
"OrderName": "PaymentDesc",
"OrderID": "TEST",
"Amount": "75.00",
"Currency": "AED",
"ReturnPath": "https://demo-ipg.comtrust.ae/MerchantDemo/Authorization.aspx",
"OrderInfo": "Telephone Bills",
"TransactionHint": "CPT:Y;VCC:Y",
"ExtraData": { "RecurrenceID": "806382547836" }
}
}

In the response to the subsequent registration calls, the unique TransactionID will be generated
and sent by EPG as this will be unique identifier for current payment and the same to be used
for redirection and finalization calls.

Master transaction id should not be used anywhere except in the “RecurrenceID” to indicate
EPG to use the stored credit card number. Each and every transaction will have unique
transaction id and this unique id to be used for redirection and
finalization/capture/reversal/refund calls.

Ecommerce Payment– Merchant Integration Support

24
 9.1.2. Payer Not Present Scenario

In this process merchant can initiate payment without the intervention of payer. In this way transaction
will not be 3D Secure. RecurrenceID saved while registering recurrence transaction should be send as
TransactionID in below Authorization request.

The sample request message will look like below:

Sample request:
{
"Authorization" : {
"Currency": "AED",
"TransactionHint": "CPT:Y;VCC:Y;",
"OrderID": "3333333344444",
"Channel": "R",
"Amount": "2.00",
"Customer": "Demo Merchant",
"TransactionID" :"806382547836",
"OrderName": "Paybill"
}
}

Sample response:
{
"Transaction": {
"ResponseCode": "0",
"ResponseClass": "0",
"ResponseDescription": "Request Processed Successfully",
"ResponseClassDescription": "Success",
"Language": "en",
"TransactionID": "805087587162",
"ApprovalCode": "789038",

Ecommerce Payment– Merchant Integration Support

25
 "Account": "NBAD",
"Balance": {
"Value": "0",
"Printable": "Dhs.0.00"
},
"OrderID": "3333333344444",
"Amount": {
"Value": "2.00",
"Printable": "Dhs. 2.00"
},
"Fees": {
"Value": "0",
"Printable": "Dhs.0.00"
},
"CardNumber": "411111******1111",
"Payer": {
"Information": "411111******1111"
},
"CardToken": "4111118733841111",
"CardBrand": "Visa",
"CardType": "Unknown",
"UniqueID": "99ddc603-c57b-4f57-8f85-c9e35c985113"
}
}

Ecommerce Payment– Merchant Integration Support

26
 10. Central Bank Payments
Central Bank Online payment has no difference with the normal payment flow. But In case of
offline payments, there are few more action required by Merchants and the same is explained
below.

Payment Flow:
1. Portal/Web Site initiates Registration call to EPG.
2. On successful response from EPG, Portal redirects to EPG Payment Portal.
3. Once the payment is done, EPG returns the control to ReturnPath URL set in
Registration call.
4. Portal will initiate Finalization call to EPG. This call will have following types of
responses.
Response Code Status Comments
0 Success Its online payment. No further action required.
210 Pending Its Offline payment and the required actions are described below.
Any other codes Failed Payment Failed

Central Bank Offline Payments:

When the finalization call response code is 201 then the payment is pending status and it is
consider to be offline scenario. The payment status update for this type of payment happens in
below two methods.
1. When the central bank updates EPG with payment status, EPG will send notification to
merchant via HTTPS POST method. Merchant need to provide HTTPS URL to receive this
notification. This notification will contains below 3 information.

a) TransactionID
b) ResponseCode
c) ResponseMessage
Response Code Status of Payment Action Required by Merchant
000 OR 200 Success Initiate Finalization Call to complete the payment.
210 Still Pending Payment is still pending and wait for next notification.
095 Rejected Transaction is rejected by Bank.

Ecommerce Payment– Merchant Integration Support

27
 2. The second approach is to perform query transaction call to EPG to get the status
periodically until the status is received wither success or failure. For more details on
query transaction and samples, please refer query transaction manual. Below details are
to be check in query transaction response to get the payment status.

D*/Type/Name D*/Response/Code Action Required by Merchant

Authentication Update 000 OR 200 Initiate Finalization Call.
Authentication Update 210 Payment still pending.
Authentication Update 095 Transaction Rejected by Bank.

11. Payment Page Customization

Etisalat Payment Gateway allows merchant to have a customized payment page to match the
theme of their website. Below are the property which can be used for customization. All these
properties are optional and merchant can set any of the below property as required. These
property has to be sent as hidden field similar to Transaction ID while re-directing to payment
page after registration call.

Property Name Usage

BackgroundColor Specifying overall background color of Payment Page
PayButtonColor Background color of Pay Button
ResetButtonColor Background color of Reset Button
HeadingFont Font name for 2 heading on Payment Page (‘Payment Details’ & ‘Payment
Method’)
HeadingColor Heading color for text ‘Payment Details’ & ‘Payment Method’

LabelFont Font name for almost all other text shown on Payment Page
LabelColor Font color for almost all other text shown on Payment Page

ErrorMessageFont Font name for message text displayed during validation

ErrorMessageColor Font color for message text displayed during validation

ShowLogo Show merchant logo beside his name under Payment Detail section. Logo
to be shared separately with Etisalat for configuration.

Ecommerce Payment– Merchant Integration Support

28
Sample Code:

Ecommerce Payment– Merchant Integration Support

29
 12. Appendix A

12.1. Point of Sale Properties

Property Description
Customer This property maps to Customer ID as mentioned in Work Order, for
testing on staging Demo Merchant should be used as Customer ID.
Channel Payment Channel to be used for the transaction Acceptable
Values:
• Web (default)
• Terminal
• POS
• Recurring
• Phone
• Mail
• USSD
• MEC
Store The name of the store (this property is optional unless the merchant
requested support for more than one store or the default store has not
been provisioned in Payment Gateway, Merchant Integration Support
team advises the merchant on its usage upon request)
Terminal The name of the terminal (this property is optional unless the merchant
requested support for more than one terminal or the default terminal has
not been provisioned in Payment Gateway, Merchant Integration Support
team advises the merchant on its usage upon request)

12.2. Transaction Properties

Property Description

Ecommerce Payment– Merchant Integration Support

30
Language This property can be used with any request and it specifies which
language is used for error message descriptions. In order to display
messages correctly, the proper language code page has to be installed on
the server. Currently defined languages:
- EN – English
- AR – Arabic
- QQ – Technical descriptions (detailed description suited for
troubleshooting and testing, but not recommended to be used as an end
user messages)
Amount It represents the transaction amount (in standard format with dot as a
separator e.g. 12.34)
Currency Transaction’s currency as ISO currency code (e.g. 840 for US Dollar, 874
for UAE Dirham) or ISO currency name (e.g. USD for US Dollar, AED for
UAE Dirham). Please refer to following link for complete list:
http://www.currency-iso.org/iso_index/iso_tables/iso_tables_a1.htm
TransactionHint This property is used to specify which payment instruments should be
available to the buyer. Merchant can specify which features should be
supported by payment instrument i.e. later reversal, capture, partial
reversal, partial capture etc. Additionally a merchant can request the final
step to perform either authorization and capture or authorization alone
e.g.
CPT:N –only authorization (Manual Capture)
CPT:Y –authorization and capture (Auto Capture) (Default behavior)

Merchant can also use this property to select one of scenarios which has
been configured on Payment Gateway – SCN:<scenario letter> e.g.
SCN:X – ‘X’ is the Scenario ID as configured and communicated by EPG
team for a particular type of transaction scenario

For controlling whenever and for which brands Payment Portal should
require payer to enter Verification Code (i.e. CVV2, CVC2, CID). VCC tag
will control verification codes for all brands, while CVV, CVC, CID will
control it for specific brand only e.g.
VCC:Y –ask verification code for all brands (Default behavior)
VCC:N – don’t ask verification code for any brand

Ecommerce Payment– Merchant Integration Support

31
Ecommerce Payment– Merchant Integration Support
32
 o GMT / Local time
By default all dates and sequences are using GMT (UTC) time, in order to
use local time instead, the suffix “g” can be added to any command, this
suffix should be placed before the number in the sequence (or before
closing “}” if a sequence does not contain any numbers).
Examples (assuming it’s 1st of December 2004, 14:12pm): {Y}{m}{d}{Od5}
– generates: 2004120100001, 2004120100002, 2004120100003 etc. and
then in the next day 2004120200001, 2004120200002, 2004120100003
etc. {Yg}{mg}{dg}{Od5g} – same as above but operating on local UAE time
· Box{b}{H}{Oy7}–generates: BoxDec140000001, BoxDec140000002 etc.,
at 15pm it resets to BoxDec150000001, BoxDec150000002 etc.
OrderName Short description of the order. The OrderName has to be shorter than 25
characters. It can contain only printable Unicode characters and it cannot
neither start nor end nor have to adjacent white characters.
OrderInfo Long description of the goods which are being purchased (this will be
displayed on Common Payment Page as a tooltip). The OrderInfo has to
be shorter than 256 characters. It can contain only printable and end of
line Unicode characters and it cannot neither start nor end nor have to
adjacent white characters.
TransactionID Transaction reference number. This is returned by EPG itself in response
of WEB SERVICE Registration call
RecurrenceID Transaction reference number for registered credit card to initiate
recurrence transaction.
MerchantAccount Name of account in payment gateway configurations that transaction happened
with (to avoid any confusions, use this field for any references or logging only if
advised by Merchant Integration Support)

12.3. Buyer Properties

Property Description
AccountNumber Credit or Debit Card number
ExpiryDate Specify ExpiryDate as yyyy-mm (given format is recommended, but yy-mm
mm/yyyy, mm/yyare also accepted);

Ecommerce Payment– Merchant Integration Support

33
 VerifyCode This property refers to CVV2/CVC/etc. The format of the value has to
match format used by given card brand (3 digits for Visa/MC/JCB and
Diners and 4 digits for AMEX and Simulator). Some brands accept to
additional symbols: ‘N/A’ to indicate that VerifyCode is unavailable and
‘ILG’ which specifies that the value printed on the card is illegible.
CardTrackData This property is used in case of card present scenario where payer swaps
the card into a machine like KIOSK. KIOSK reads the Card Track Data and
sends it to EPG in CardTrackData field.
Note: In case CardTrackData is being sent to EPG then there is no need to
send any other property from Buyer Related Properties.

12.4. Response Properties

These response properties can be retrieved in response to a particular call. For code
sample/syntax refer to Section 5.3.8.2 Late Bound Properties.

Property Description
ResponseCode This field returns the exact response code. Success is always
indicated with 0, and any code using WEB SERVICE component
should verify this status.
Note: The exact meaning of this value may be different depend on
the buyer’s card issuer, merchant’s account bank or the step at
which authentication failed, which means that we are unable to
provide a list of all possible descriptions, in order to receive user-
friendly description of the event please use ResponseDescription
field.
Please refer to FAQ Document for Troubleshooting guide on EPG
errors.
ResponseDescription User-friendly description of the error in ResponseCode.
Note: This field can only be used to display the error description and
should not be used to check if transaction was successful, to check if
transaction was successful please use ResponseCode field.

Ecommerce Payment– Merchant Integration Support

34
 ResponseClass This field serves a similar purpose as ResponseCode, but instead of
giving a very detailed error it specifies at which stage or part of the
system request failed (for example it may point out that issuer
declined request or acquire did not accept it or Payment Gateway
rejected it, without going into detail)
ResponseClassDescription This is a user-friendly description of ResponseClass
TransactionID Unique ID for in progress transaction (Returned in response for
every call)
RecurrenceID Recurrence ID used for subsequent recurrence transaction.

PaymentPortal Link to Common Payment Page where payer will be asked to input
Credit Card information for secure transaction (Returned only in
response for Registration call)
ApprovalCode This is the response coming from respective bank for Authorization
(Returned only in response forAuthorization & Finalizationcalls)
OrderID OrderID as provided by Customer or if Customer chose automated
OrderID generation in Registration or Authorization call then the
generated value (Returned only in response forAuthorization &
Finalization calls)
Balance This is the response coming from respective bank for Authorization
(Returned only in response for Capture & Reversal calls)
AccountExpiry Expiry date of Credit Card. This value will be send only while registering a
Credit Card for Recurring Payments. It will be send in DateTime format
Details/Type Below are the list of Operation name.
Name Value
Registration V
PaymentPage Query V
Payment Data Update V
Authentication Update V
CC Fraud F
CC Authorization A
CC Reversal R
CC Capture S
CB Authorization A
CB Capture S
CB Reversal R
Details/Status Below are the list of Status which can be associated for any operation
mentioned above.

Ecommerce Payment– Merchant Integration Support

35
 Name Value
Pending p
Accepted A
Not Accepted F
Reverting r
Reverted R
Rejected U
Waiting w
Canceled C
Timeout T
Invalid I
Payer/CardBrand or Below are the list of Card Brand and its symbols
AccountBrand Name Symbol
Visa V
MasterCard M
AMEX A
CentralBank
UNB Account
ADCB Account

Ecommerce Payment– Merchant Integration Support

36
 13. Appendix B
13.1. Server Configuration.
Server URL Port
Production https://ipg.comtrust.ae 2443
Sandbox https://demo-ipg.comtrust.ae 2443

Connectivity with EPG should be done using TLSv1.2, Also note that Store and Terminal must be
configurable for all above call, based on production set up We may or may not provide store and
terminal values.
Please contact Merchant Integration Support [email protected] to provision and share
below configuration.
a) Customer
b) Store
c) Terminal

13.2. Test Credit Cards for Sandbox environment

Visa Card Master Card Error Code Error Description
4111111111111111 5555555555554444 0 Success
4012888888881881 51 Not Sufficient Fund
5105105105105100 5 Do not honor
Other Valid Visa Cards Other Valid Master Cards 91 Issuer Switch
inoperative

13.3. Client Certificate for Sandbox environment

Download Demo Merchant Certificate using below link. Password is “Comtrust”
https://demo-ipg.comtrust.ae/merchant/Downloads/Certificates.zip

13.4. User Name and Password Authentication

Instead of using digital certificate for client authentication, merchants can also use basic user name and
password authentication. Below is the test user credentials for Demo Merchant account. In the input
JSON request, merchant need to send the below two parameters.
UserName Demo_fY9c
Password Comtrust@20182018

Ecommerce Payment– Merchant Integration Support

37