0% found this document useful (0 votes)

494 views58 pages

ARB Payment Gateway 3.3.0.ARB - REST API Integration Guide - V1.10

Uploaded by

anwar187

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

494 views58 pages

ARB Payment Gateway 3.3.0.ARB - REST API Integration Guide - V1.10

Uploaded by

anwar187

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 58

ARB PAYMENT

GATEWAY MERCHANT
IMPLEMENTATION
GUIDE - REST APIS

Version 1.10
[Abstract]

Publishing Date: September 2020

ARB Merchant Implementation Guide - REST APIs | ARB Payment Gateway

Version History

The following table displays the version history of this document:

Created or Up-
Version No. Reason for Change Created or Updated on
dated By

1.0 FSS Merchant integration using REST API Jan 23, 2020

1.1 FSS Updated as per comments Feb 10, 2020

1.2 FSS Updated as per bank comments Feb 13, 2020

1.3 FSS Updated as per bank observations Feb 14, 2020

Updated encryption for supporting transac-

1.4 FSS Feb 24, 2020
tions
Updated PHP encryption, decryption code
1.5 FSS Feb 27, 2020
and bank comments
Updated Merchant hosted non 3D secure
1.6 FSS Mar 12, 2020
transaction
Formatted the document and updated “Final
Response Type, Terminal Resource Key 2 for
1.7 FSS Mar 18, 2020
Final Response Encryption and Decryp-tion”
topic
Formatted the document and update, Pay-
1.8 FSS ment Data, Payment method, and Transac- April 15, 2020
tionIdentifier paraments

1.9 FSS Updated Invoice transaction April 29, 2020

1.9.1 FSS Document Formatting June 04, 2020

Updated Split payment request for purchase

1.10 FSS September 29, 2020
transaction

© 2020 API Guide Page 2 of 58

ARB Merchant Implementation Guide - REST APIs | ARB Payment Gateway

Table of Contents

VERSION HISTORY .................................................................................................................... 2

CHAPTER 1 ABOUT THIS DOCUMENT ................................................................................... 4

PURPOSE OF THE DOCUMENT ......................................................................................................... 4

CHAPTER 2 INTEGRATION PROCESS ................................................................................... 5

API REFERENCE GUIDE ............................................................................................................... 5

Integration Process ....................................................................................................... 5
Transaction and settlement Verification in merchant Portal................................................. 5

CHAPTER 3 TRANSACTION FLOW ........................................................................................ 7

UNDERSTANDING ARB PAYMENT GATEWAY ......................................................................................... 7

BANK HOSTED TRANSACTION FLOW (3D SECURE PURCHASE TRANSACTIONS) ................................................ 9
BANK HOSTED TRANSACTION FLOW (FASTER CHECKOUT TRANSACTIONS) ....................................................14
BANK HOSTED TRANSACTION FLOW (IFRAME) ....................................................................................16
MERCHANT HOSTED TRANSACTION FLOW (3D SECURE PURCHASE TRANSACTIONS).........................................19
MERCHANT HOSTED TRANSACTION FLOW (NON 3D SECURE PURCHASE TRANSACTIONS) ..................................25
MERCHANT HOSTED TRANSACTION FLOW (INQUIRY VOID, REFUND TRANSACTIONS) .......................................29
MERCHANT HOSTED TRANSACTION FLOW (APPLE PAY TRANSACTIONS) .......................................................32
INVOICE PAYMENT TRANSACTION FLOW ...........................................................................................35
MERCHANT NOTIFICATION FLOW FOR BANK HOSTED TRANSACTIONS ..........................................................39
FINAL RESPONSE TYPE , TERMINAL RESOURCE KEY 2 FOR FINAL RESPONSE ENCRYPTION AND DECRYPTION .............42
FAQ'S ON INTEGRATION PROCESS .................................................................................................43
SAMPLE ENCRYPTION AND DECRYPTION CODE FOR JAVA .......................................................................45
SAMPLE ENCRYPTION AND DECRYPTION CODE FOR JAVASCRIPT ............................................................47
SAMPLE ENCRYPTION AND DECRYPTION CODE FOR PHP ........................................................................48

CHAPTER 4 TROUBLESHOOTING ....................................................................................... 49

KNOWN ERROR CODES ..............................................................................................................49

HANDLING FINAL RESPONSE FROM PAYMENT GATEWAY ..........................................................................58

© 2020 API Guide Page 3 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Chapter 1 ABOUT THIS DOCUMENT

Purpose of the Document

The Payment Gateway follows industry standards and norms as prescribed by MasterCard and Visa
International as well in conformity with Payment Card Industry – Data Security Standards commonly
referred to as PCI – DSS.

In order that the AL Rajhi Bank merchants are integrated in a secure and mandated manner, this
reference document is being shared. The expectation being that the merchant’s system integrator
or auditor can refer to a document while performing integration as well as post integration. It con-
tains the technical integration details including message formats to be used in communicating to
the Payment Gateway irrespective of the merchant platform being used. The document also shares
the best practices and recommendations the merchant should follow during the integration with
Payment Gateway.

© 2020 API Guide Page 4 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Chapter 2 INTEGRATION PROCESS

API Reference Guide

ARB PG API’s are complete RESTFUL API’s; Merchants can test the API’s on sandbox setup before
testing on Live environment.

Test Card details.

Card type Card Number Expiry Date CVV

Credit 4012001037141112 12/2027 212

Below are the prerequisites for merchants to integrate with ARB Payment gateway. These are shared
to the merchant via mail to their registered email ID.

1. Tranportal ID
2. Tranportal Password
3. Resource Key
4. Payment gateway endpoint

Integration Process

Steps to be followed by Merchant Integration Team:

1. Verify the endpoints by sending request in postman application.

2. Frame the Json request of plain trandata with request parameters as specified in the document
3. Encrypt the plain json request with the resource key received in the mail.
4. Frame the encrypted request and send it to ARB Payment Gateway endpoint url shared via mail.
5. After receiving the response from ARB Payment Gateway , decrypt the encrypted trandata using
the resource key received in the mail.
6. Process the plain trandata - response message .

Transaction and settlement Verification in merchant

Portal

After the integration testing, transactions can be verified on merchant Portal .

Below is the URL of merchant portal:

© 2020 API Guide Page 5 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

https://digitalpayments.alrajhibank.com.sa/mrchptl/merchant.htm

To verify if a transaction has been settled or not merchant can always refer the transaction detail
report in merchant Portal . Navigation to transaction detail report in merchant portal is as below :

Merchant Portal ->Reports->Transaction Reports->Transaction Detail Report

© 2020 API Guide Page 6 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Chapter 3 TRANSACTION FLOW

Understanding ARB payment gateway

Payment Gateway uses AES encryption algorithm to encrypt transaction data which includes all sensitive
information such as Card number, Expiry period, CVV etc.,

There are two ways of processing the payment with ARB payment gateway with API integration.

• Bank Hosted setup

• Merchant Hosted setup

Bank Hosted setup

Bank hosted integration type can be used by merchants who cannot accept card credentials on
their website.

Integration flow for Bank hosted setup

▪ Customer completes the purchase and proceeds to checkout with payment options
▪ Merchant is redirected to Bank’s payment page, wherein customer inputs the card details
on Bank’s page.
▪ Card details are validated & Merchant invokes payment API
▪ Payment Gateway then will interface with respective schemes like MasterCard, VISA to pro-
cess the 3D secure authentication.
▪ Once the authentication is completed by respective scheme / ACS, PG will perform Risk
check.
▪ Once the authentication step is completed, Payment gateway completes the transaction
authorization and provides the response to the merchant.

Merchant Hosted

o Merchant hosted type is an integration flow in which merchant can accept card credentials on
their website which provides rich user experience and pass on to AL Rajhi PG.
o ARB PG processes the transaction and returns the response. In this scenario, the merchant has
to be PCI compliant.

Integration flow for Merchant hosted

o Customer completes the purchase and proceeds to checkout with payment options
o Merchant displays payment page and customer inputs the card details
o Card details are validated & Merchant invokes payment API
o Payment Gateway then will interface with respective schemes like MasterCard, VISA to process
the 3D secure authentication.
o Once the authentication is completed by respective scheme / ACS, PG will perform Risk check.

© 2020 API Guide Page 7 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

o Once the authentication step is completed, Payment gateway completes the transaction author-
ization and provides the response to the merchant through API

© 2020 API Guide Page 8 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Bank Hosted Transaction Flow (3D Secure Purchase

Transactions)

• Below are the sample JSON request and response,

Request from Merchant to ARB Payment gateway:

[{"id":"IPAYlCR6qZF7q6w", “trandata”:”<encrypted trandata> ”

"responseURL":"http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentRe-
sult.jsp","errorURL":"http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentRe-
sult.jsp" }]

• Trandata will contain below parameters encrypted with AES algorithm with CBC Mode, PKCS5Pad-
ding with initialization vector value PGKEYENCDECIVSPC under Resource Key

Plain Trandata:

[{“amt”:”12.00”,”action”:”1”,”pass-
word”:”q@a68O$27@JLkcK”,”id”:”IPAYlCR6qZF7q6w”,”curren-
cyCode”:”682”,”trackId”:”12345656789”,”udf1”:”udf1text”,”udf2”:”udf2text”,”udf3”:”u
df3text”,”udf4”:”udf4text”,”udf5”:”udf5text”,”re-
sponseURL”:”http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentResult.jsp”,”er-
rorURL”:http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentResult.jsp,
"accountDetails":[{"bankIdCode": "12345d6f", "iBanNum":
"567896743281926354276254","serviceAmount":"200.00","valueDate":"20203112"
},{"bankIdCode": "1234ret3", "iBanNum": "987656743281926354276254","serviceA-
mount":"300.00","valueDate":"20213112" }]
}]
Request from Merchant to ARB Payment gateway

S. No Fields M/C/O Field Type Description

Tranportal ID. Merchant can download the Tranportal id from

1 Id M Alphanum
Merchant portal
All the below request parameters encrypted and pass the en-
2 trandata M Alphanum
crypted value in trandata.
The merchant success URL where Payment Gateway send the
3 responseURL M Alphanum
notification request.
4 errorURL M Alphanum Merchant error URL

© 2020 API Guide Page 9 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Detailed description of Plain Trandata request parameters

S. No Fields M/C/O Field Type Description

1 amt M Numeric Transaction amount

It defines the transactions actions

Purchase: 1
2 action M Numeric Refund: 2
Void: 3
Inquiry: 8

Tranportal password. Merchant download the same in mer-

3 password M Alphanum
chant portal.

Tranportal ID. Merchant download the same in merchant

4 id M Alphanum
portal

5 currencyCode M Numeric 3-digit currency code of KSA. Ex:682

6 trackId M Numeric Merchant unique reference no

The user (merchant) defines these fields. The field data is

passed along with a transaction request and then returned
7 udf1 O Alphanum
in the transaction response. Merchant should ensure that
field is left blank when no data needs to be passed.

The user (merchant) defines these fields. The field data is

passed along with a transaction request and then returned
8 udf2 O Alphanum
in the transaction response. Merchant should ensure that
field is left blank when no data needs to be passed.

The user (merchant) defines these fields. The field data is

passed along with a transaction request and then returned
9 udf3 O Alphanum
in the transaction response. Merchant should ensure that
field is left blank when no data needs to be passed.

The user (merchant) defines these fields. The field data is

passed along with a transaction request and then returned
10 udf5 O Alphanum
in the transaction response. Merchant should ensure that
field is left blank when no data needs to be passed.

The merchant success URL where Payment Gateway send

11 responseURL M Alphanum
the notification request.

The merchant error URL where Payment Gateway send the

12 errorURL M Alphanum
response in case any error while Processing the transaction.

ac-
13 C JSON Array Split Payment Details.
countDetails

13.1 bankIdCode C Alphanum 8 – Digit Bank Identification Code

© 2020 API Guide Page 10 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

S. No Fields M/C/O Field Type Description

13.2 iBanNum C Alphanum 24 – Digit IBAN Number

serviceA-
13.3 C Numeric Service Amount
mount

13.4 valueDate C Numeric Value Date Format: YYYYDDMM

• ARB Payment gateway internally validates the request and gives payment ID and payment page
URL in the response in case of successful validation, if failure then error code and description will be
provided. The below response will be in plain format and there is no encryption for the below.
Merchant can directly parse the response-based status and result fields as mentioned below.

Success:

[{"status": "1","result":"100201931620827468:http://10.44.71.241:8080/AR-
BiPay3.3.0_AlRajhibank/paymentpage.htm" //Payment ID:Paymentpage URL
“error”:null,
“errorText”:null}]

Failure:
[{
"status": "2","error":" IPAY0100124”,
“errorText”:” Problem occurred while validating transaction data”
“result”:null
}]
Initial Response from PG to Merchant

S. No Fields M/C/O Field Type Description

1 status M Numeric If the request validation success, then status will be ‘1’. If the
validation failed, then status will be ‘2’
2 result M Alphanum It contains payment ID and Payment URL if the validation suc-
cess else this will be null
3 error C Alphanum If validation failed, then Payment gateway will provide the re-
spective error code
4 errorText C Alphanum If validation failed, then Payment gateway will provide the re-
spective error description

• If success, Merchant needs to frame the payment page URL like the below sample

© 2020 API Guide Page 11 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

http://10.44.71.241:8080/ARBiPay3.3.0_AlRajhibank_restAPI/paymentpage.htm?Paymen-
tID=100201931620827468

• If Merchant notification is disabled, then ARB Payment gateway will provide the final response in
URL redirection. Below is the sample response from ARB PG to merchant

[{“paymentId”:100201935166676976,“trandata”:”<encrypted trandata>”,
“error”:””,“errorText”:””}]

• Plain Trandata:

[{“paymentId”:100201935166676976,”result”:”CAPTURED”,”transId”:201935166561122,
”ref”:”935110000001”,”date”:1217,”trackId”:”1003383844”,”udf1”:””,”udf2”:””,”ud
f3”:”8870091137”,”udf4”:”FC”,”udf5”:”Tidal5”,”amt”:”70.0,”authRespCode”,”00”,"a
uthCode":"000000"}]

Final URL redirection response from ARB payment gateway to Merchant

S. No Fields M/C/O Field Type Description

1 paymentId M Numeric Unique payment Id generated by PG and merchant can use this
ID to match the response from PG
2 trandata C Alphanum All the below response parameters encrypted and send the en-
crypted value in trandata
3 error C Alphanum If any error, PG will send the error code

4 errorText C Alphanum If any error, PG will send the error description

© 2020 API Guide Page 12 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Detailed description of Plain trandata parameters

S. No Fields M/C/O Field Type Description

1 paymentId M Numeric Unique ID generated by payment gateway. Based on this pay-

ment Id merchant can match the final URL redirection re-
sponse
2 result M Alphanum Transaction status

3 ref M Numeric Transaction reference number (RRN)

4 transId M Numeric Unique transaction Id generated by Payment gateway and mer-

chant can use this id for initiating supported transactions (Void,
refund and inquiry)
5 date M Numeric Transaction date and time

6 trackId M Numeric Merchant unique reference no

7 udf1 O Alphanum The user (merchant) defines these fields. The field data is
passed along with a transaction request and then returned in
the transaction response. Merchant should ensure that field is
left blank when no data needs to be passed.
8 udf2 O Alphanum The user (merchant) defines these fields. The field data is
passed along with a transaction request and then returned in
the transaction response. Merchant should ensure that field is
left blank when no data needs to be passed.
9 udf3 O Alphanum The user (merchant) defines these fields. The field data is
passed along with a transaction request and then returned in
the transaction response. Merchant should ensure that field is
left blank when no data needs to be passed.
10 udf5 O Alphanum The user (merchant) defines these fields. The field data is
passed along with a transaction request and then returned in
the transaction response. Merchant should ensure that field is
left blank when no data needs to be passed.
11 amt M Numeric Transaction amount

12 authRespCod M Numeric Auth response code provided by PG

e
13 authCode M Numeric 6 digit authorization code received from switch

© 2020 API Guide Page 13 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Bank Hosted Transaction Flow (Faster Checkout Trans-

actions)

Faster Checkout functionality is supported for the merchants only when Faster Checkout flag is enabled
at the terminal level.

Payment gateway supports faster checkout option where customer can register card details based on
unique customer ID which merchant have to send for payment transactions

• Below are the sample JSON request and response,

Request from Merchant to ARB Payment gateway:

[{"id":"IPAYlCR6qZF7q6w", “trandata”:”<encrypted trandata> ”

• Trandata will contain below parameters encrypted with AES algorithm with CBC Mode, PKCS5Pad-
ding with initialization vector value PGKEYENCDECIVSPC under Resource Key

Plain Trandata:

[{“amt”:”12.00”,”action”:”1”,”pass-
word”:”q@a68O$27@JLkcK”,”id”:”IPAYlCR6qZF7q6w”,”curren-
cyCode”:”682”,”trackId”:”12345656789”,”udf1”:”udf1text”,”udf2”:”udf2text”,”udf3”:”u
df3text”,”udf4”:”udf4text”,”udf5”:”udf5text”,”re-
sponseURL”:”http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentResult.jsp”,”er-
rorURL”:”http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentResult.jsp”,
"accountDetails":[{"bankIdCode": "12345d6f", "iBanNum":
"567896743281926354276254","serviceAmount":"200.00","valueDate":"20203112"
},{"bankIdCode": "1234ret3", "iBanNum": "987656743281926354276254","serviceA-
mount":"300.00","valueDate":"20213112" }],
"custid":"201936122890007","cust_cardHolderName":"Test","cust_mobile_num-
ber":"7788667755","cust_emailId":"[email protected]"}]
• For Faster Checkout Transactions below are the additional parameters sent in the request of bank
hosted transactions :

© 2020 API Guide Page 14 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Additional request Parameters in Bank Hosted Transactions for Faster Checkout Function-
ality.

S. No Fields M/C/O Field Type Description

Unique Customer ID generated on faster checkout regis-

1 Custid M Numeric
tration.
cust_cardHolder-
2 O Alphabetic Cardholder Name
Name
cust_mobile_num-
3 O Numeric Customer Mobile Number
ber:
4 cust_emailId O Alphanum Customer E-mail ID

• Payment gateway will provide the final response in URL redirection. Below is the sample response
from ARB PG to merchant

[{“paymentId”:100201935166676976,“trandata”:”<encrypted trandata>”,“error”:””,“er-
rorText”:””}]

Plain Trandata:

[{“paymentId”:100201935166676976,”result”:”CAPTURED”,”tran-
sId”:201935166561122,"fcCus-
tId":"201936122890007",”ref”:”935110000001”,”date”:1217,”trackId”:”1003383844”,
”udf1”:””,”udf2”:””,”udf3”:”8870091137”,”udf4”:”FC”,”udf5”:”Tidal5”,”amt”:”70.0
,”authRespCode”,”00”,"authCode":"000000"}]
Additional response Parameter in Bank Hosted Transactions for Faster Checkout Func-
tionality.

S. No Fields M/C/O Field Type Description

Unique Customer ID generated on faster checkout registra-

1 fcCustId M Numeric
tion.

© 2020 API Guide Page 15 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Bank Hosted Transaction Flow (Iframe)

Payment gateway shall support Iframe integration to enable merchants to accept online payments on
own checkout page and without having to be a PCI compliant. Instead of being redirected to ARB Pay-
ment page, customers will remain on merchant website to make payments. However, at the back end,
ARB PG will securely collect the payment information and get it authorized.

Merchant needs to send value 'iframe' in the UDF3 field of the request as below

• Below are the sample JSON request and response,

Request from Merchant to ARB Payment gateway:

[{"id":"IPAYlCR6qZF7q6w", “trandata”:”<encrypted trandata> ”

• Trandata will contain below parameters encrypted with AES algorithm with CBC Mode, PKCS5Pad-
ding with initialization vector value PGKEYENCDECIVSPC under Resource Key

Plain Trandata:

[{“amt”:”12.00”,”action”:”1”,”pass-
word”:”q@a68O$27@JLkcK”,”id”:”IPAYlCR6qZF7q6w”,”curren-
cyCode”:”682”,”trackId”:”12345656789”,”udf1”:”udf1text”,”udf2”:”udf2text”,”udf3”:”i
frame”,”udf4”:”udf4text”,”udf5”:”udf5text”,”re-
sponseURL”:”http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentResult.jsp”,”er-
rorURL”:http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentResult.jsp,
"accountDetails":[{"bankIdCode": "12345d6f", "iBanNum":
"567896743281926354276254","serviceAmount":"200.00","valueDate":"20203112"
},{"bankIdCode": "1234ret3", "iBanNum": "987656743281926354276254","serviceA-
mount":"300.00","valueDate":"20213112"}]
}]

Success:

[{"status": "1", "result": "100201931620827468:http://10.44.71.241:8080/AR-

BiPay3.3.0_AlRajhibank/paymentpage.htm" //Payment ID:Paymentpage URL
“error”:null,“errorText”:null}]

© 2020 API Guide Page 16 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Failure:

[{"status": "2","error":" IPAY0100124”,

“errorText”:” Problem occurred while validating transaction data”
“result”:null}]
• If success, Merchant needs to frame the payment page URL like the below sample

http://10.44.71.241:8080/ARBiPay3.3.0_AlRajhibank_restAPI/paymentpage.htm?Paymen-
tID=100201931620827468

Merchant needs to add the following code snippet to load the payment page in an iframe window:

Code Snippet

if("iframe".equals(pipe.getUdf3()))
{
%>
<script>
if(window.parent.document.getElementById("iframe")!=null)
{
var division=document.createElement("div");
division.setAttribute("id", "payframe");
division.setAttribute("style", "min-height: 100%; position: fixed; top:
0px; left: 0px; width: 100%; height: 100%; background: rgba(0, 0, 0, 0); padding-
right: 0px; padding-left: 0px;padding-top: 0px;");
division.innerHTML ='<div style="position: absolute;right: 0px;top:
0px;cursor: pointer;font-size: 24px;opacity: .6;width: 100%;text-align: cen-
ter;line-height: 0px;z-index: 1;" class="close" id="F" onclick="javascript: win-
dow.parent.document.getElementById(\'iframe\').parentNode.removeChild(window.par-
ent.document.getElementById(\'iframe\'));window.parent.document.getEle-
mentById(\'payframe\').parentNode.removeChild(window.parent.document.getEle-
mentById(\'payframe\'));">x</div><iframe id="iframe" style="opacity: 7; height:
100%; position: relative; background: none; display: block; border: 0px none trans-
parent; margin-left: 0%; padding: 0px; z-index: 2; width: 100%; margin-top: 0%" al-
lowtransparency="true" frameborder="0" allowpaymentrequest="true"
src="<%=pipe.getWebAddress()%>"></iframe>';
document.body.appendChild(division);
}
else
{
var division=document.createElement("div");
division.setAttribute("id", "payframe");

© 2020 API Guide Page 17 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

division.setAttribute("style", "min-height: 100%; transition: all 0.3s

ease-out 0s; position: fixed; top: 0px; left: 0px; width: 100%; height: 100%; back-
ground: rgba(0, 0, 0, 0.4); padding-right: 10px; padding-left: 250px;padding-top:
0px;");
division.innerHTML ='<div style="position: absolute;right: 0px;top:
0px;cursor: pointer;font-size: 24px;opacity: .6;width: 24px;text-align: cen-
ter;line-height: 0px;z-index: 1;" class="close" id="F" onclick="javascript: win-
dow.parent.document.getElementById(\'iframe\').parentNode.removeChild(window.par-
ent.document.getElementById(\'iframe\'));window.parent.document.getEle-
mentById(\'payframe\').parentNode.removeChild(window.parent.document.getEle-
mentById(\'payframe\'));">x</div><iframe id="iframe" style="opacity: 7; height:
100%; position: relative; background: none; display: block; border: 0px none trans-
parent; margin-left: 7%; padding: 0px; z-index: 2; width: 65%; margin-top: 0%" al-
lowtransparency="true" frameborder="0" allowpaymentrequest="true"
src="<%=pipe.getWebAddress()%>"></iframe>';
document.body.appendChild(division);
}
</script>
}
else
{
response.sendRedirect(pipe.getWebAddress());
}

• Payment gateway will provide the final response in URL redirection. Below is the sample response
from ARB PG to merchant

[{“paymentId”:100201935166676976,“trandata”:”<encrypted trandata>”,“error”:””,“er-
rorText”:””}]

Plain Trandata:

[{“paymentId”:100201935166676976,”result”:”CAPTURED”,”tran-
sId”:201935166561122,"fcCus-
tId":"201936122890007",”ref”:”935110000001”,”date”:1217,”trackId”:”1003383844”,”udf
1”:””,”udf2”:””,”udf3”:”8870091137”,”udf4”:”FC”,”udf5”:”Tidal5”,”amt”:”70.0,”authRe
spCode”,”00”,"authCode":"000000"}]

© 2020 API Guide Page 18 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Merchant Hosted Transaction Flow (3D Secure Purchase

Transactions)

• Below are the sample request and response parameters,

Request from Merchant to ARB Payment gateway:

[{"id":"IPAYlCR6qZF7q6w",“trandata”:”<encrypted trandata>”,"re-
sponseURL":"http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentResult.jsp","er-
rorURL":"http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentResult.jsp" }]

• Trandata will contain below parameters encrypted with AES algorithm with CBC Mode, PKCS5Pad-
ding with initialization vector value PGKEYENCDECIVSPC under Resource key.

Plain Trandata

[{“amt”:”12.00”,”action”:”1”,”password”:”q@a68O$27@JLkcK”,”id”:”IPAYlCR6qZF7q6w”,”curren-
cyCode”:”682”,”trackId”:”123456”,”udf1”:”udf1text”,”udf2”:”udf2text”,”udf3”:”udf3text”,”udf4”:”u
df4text”,”udf5”:”udf5text”,”responseURL”:”http://10.44.71.241:8089/pgdemo/jsp/ARB/Host-
edPaymentResult.jsp”,”errorURL”:”http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentRe-
sult.jsp”,”expYear”:”2022”,”expMonth”:”12”,”member”:”cardholder-
name”,”cvv2”:”212”,”cardNo”,”5453********5539”,”cardType”:”C”,

"acountDetails":[{"bankIdCode":"12345d6f","iBanNum":"567896743281926354276254","ser-
viceAmount":"200.00","valueDate":"20203112"},{"bankIdCode":"1234ret3","iBan-
Num":"987656743281926354276254","serviceAmount":"300.00","valueDate":"20213112" }]

}]

Plain Trandata for Credit Card Installment Transactions(udf6 and udf7 additional param-
eters)

[{“amt”:”12.00”,”action”:”1”,”password”:”q@a68O$27@JLkcK”,”id”:”IPAYlCR6qZF7q6w”,”curren-
cyCode”:”682”,”trackId”:”123456”,”udf1”:”udf1text”,”udf2”:”udf2text”,”udf3”:”udf3text”,”udf4”:”u
df4text”,”udf5”:”udf5text","udf6":"12345","udf7":"C",”re-
sponseURL”:”http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentResult.jsp”,”er-
rorURL”:”http://10.44.71.241:8089/pgdemo/jsp/ARB/HostedPaymentRe-
sult.jsp”,”expYear”:”2022”,”expMonth”:”12”,”member”:”cardholder-
name”,”cvv2”:”212”,”cardNo”,”5453********5539”,”cardType”:”C”,

}]

© 2020 API Guide Page 19 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Request from Merchant to ARB payment gateway

S. No Fields M/C/O Field Type Description

1 id M Alphanum Tranportal ID. Merchant can download the Tranportal id

from Merchant portal
2 trandata M Alphanum All the below request parameters encrypted and pass the
encrypted value in trandata.
3 responseURL M Alphanum The merchant success URL where Payment Gateway send
the notification request.
4 errorURL M Alphanum Merchant error URL

Detailed description of Plain trandata request parameters

S.No Fields M/C/O Field Type Description

1 amt M Numeric Transaction amount

2 action M Numeric It defines the transactions actions

Purchase: 1
Refund: 2
Void: 3
Inquiry: 8
3 password M Alphanum Tranportal password. Merchant download the same in
merchant portal.
4 id M Alphanum Tranportal ID. Merchant download the same in merchant
portal
5 currencyCode M Numeric 3-digit currency code of KSA. Ex:682

6 trackId M Numeric Merchant unique reference no

7 udf1 O Alphanum The user (merchant) defines these fields. The field data is
passed along with a transaction request and then re-
turned in the transaction response. Merchant should en-
sure that field is left blank when no data needs to be
passed.
8 udf2 O Alphanum The user (merchant) defines these fields. The field data is
passed along with a transaction request and then re-
turned in the transaction response. Merchant should en-
sure that field is left blank when no data needs to be
passed.
9 udf3 O Alphanum The user (merchant) defines these fields. The field data is
passed along with a transaction request and then re-
turned in the transaction response. Merchant should en-
sure that field is left blank when no data needs to be
passed.
10 udf5 O Alphanum The user (merchant) defines these fields. The field data is
passed along with a transaction request and then re-
turned in the transaction response. Merchant should

© 2020 API Guide Page 20 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

S.No Fields M/C/O Field Type Description

ensure that field is left blank when no data needs to be

passed.
11 responseURL M Alphanum The merchant success URL where Payment Gateway send
the notification request.
12 errorURL M Alphanum The merchant error URL where Payment Gateway send
the response in case any error while Processing the trans-
action.
13 expYear M Numeric Expiry year of card

14 expMonth M Numeric Expiry month of card

15 Member M Alphanum Card holder name

16 cvv2 M Numeric CVV of the card

17 cardNumber M Numeric Cardholders card number

18 cardType M Alphanum Card type Ex : Credit card – C, Debit Card – D

19 accountDetails C JSON Array Split Payment Details.

19.1 bankIdCode C Alphanum 8 – Digit Bank Identification Code

19.2 iBanNum C Alphanum 24 – Digit IBAN Number

19.3 serviceAmount C Numeric Service Amount

19.4 valueDate C Numeric Value Date Format: YYYYDDMM

UDF 6 and UDF7 parameters should be passed only for Credit Card installment Transactions as be-
low:
20 udf6 O Alphanum Credit Card Installment Short Code

21 udf7 O Alphanum Credit Card Installment Type

• ARB Payment gateway internally validates the request and gives payment ID and payment page
URL in the response if the validation success. If failure then, Error code and description will be
provided.

© 2020 API Guide Page 21 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Plain Response:

Success:
[{"status": "1",
"result":"100201931620827468:http://10.44.71.241:8080/FSSiPay3.3.0_AlRajhi/Tranpor-
talVbv.htm", //Payment ID:Payment page URL
“error”:null,“errorText”:null}]

Failure:
[{"status": "2","error":" IPAY0100124”,
“errorText”:” Problem occurred while validating transaction data”
“result”:null}]

Initial Response from PG to Merchant

S. No Fields M/C/O Field Type Description

1 status M Numeric If the request validation success, then status will be ‘1’. If
the validation failed, then status will be ‘2’
2 result M Alphanum It contains payment ID and Payment URL if the validation
success else this will be null
3 error C Alphanum If validation failed, then Payment gateway will provide the
respective error code
4 errorText C Alphanum If validation failed, then Payment gateway will provide the
respective error description

• Merchant needs to frame the payment page URL like the below sample

http://10.44.71.241:8080/FSSiPay3.3.0_AlRajhi_restAPI/paymentpage.htm?Paymen-
tID=100201931620827468&id=1234$ssdfg
• Merchant needs to redirects the customer to ARB Payment gateway.

Customer browser will redirect to ACS page and will complete the authentication. PG then process
for authorization with the respective schemes. Once payment response received from respective
scheme, then ARB Payment gateway returns the response to merchant. This is URL redirection.
Below is sample response from ARB PG to merchant,

[{“paymentId”:100201935044735860,"trandata": "<encrypted trandata>",

“Error”:””,“ErrorText”:””}]

© 2020 API Guide Page 22 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Plain Trandata

[{“paymentId”:100201935044735860,”result”:”captured”,”amt”:10.55,”date”:1221,
”ref”:”935110000001”,”udf1”:”udf1text”,”udf2”:”udf2text”,”udf3”:”udf3text”,”udf4”:”
udf4text”,”udf5”:”udf5text”,”trackId”,”3423423”,”tran-
sId”:1242345345234,“authRespCode”:”00”,"authCode":"000000"}]

Final Response from ARB payment gateway to Merchant

S. No Fields M/C/O Field Type Description

1 paymentId M Numeric Unique ID generated by Payment gateway. Merchant can

store the payment ID to match the final URL redirection re-
sponse
2 trandata C Alphanum All the below response parameters encrypted and send the
encrypted value in trandata
Ex: [{“paymen-
tId”:100201935166676976,”re-
sult”:”CAP-
TURED”,”ref”:”935110000001”,”tran-
sId”:201935166561122,”date”:1217,”tra
ckId”:”1003383844”,”udf1”:””,”udf2”:”
”,”udf3”:”8870091137”,”udf
4”:”FC”,”udf5”:”Tidal5”,”amt”:”70.0,”authRespCode”,”00”}
]
3 Error C Numeric If any error, PG will provide the error code
4 ErrorText C Alphanum PG will provide the error description if any transaction de-
clined.

Detailed description of Plain trandata response parameters

S. No Fields M/C/O Field Type Description

Unique ID generated by payment gateway. Based on this

1 paymentId M Numeric payment Id merchant can match the final URL redirection
response

2 result M Alphanum Transaction status

3 ref M Numeric Transaction reference number (RRN)

Unique transaction Id generated by Payment gateway and

4 transId M Numeric merchant can use this id for initiating supported transac-
tions (Void, refund and inquiry)

5 date M Numeric Transaction date and time

6 trackId M Numeric Merchant unique reference no

© 2020 API Guide Page 23 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

S. No Fields M/C/O Field Type Description

The user (merchant) defines these fields. The field data is

passed along with a transaction request and then returned
7 udf1 O Alphanum
in the transaction response. Merchant should ensure that
field is left blank when no data needs to be passed.
The user (merchant) defines these fields. The field data is
passed along with a transaction request and then returned
8 udf2 O Alphanum
in the transaction response. Merchant should ensure that
field is left blank when no data needs to be passed.
The user (merchant) defines these fields. The field data is
passed along with a transaction request and then returned
9 udf3 O Alphanum
in the transaction response. Merchant should ensure that
field is left blank when no data needs to be passed.
The user (merchant) defines these fields. The field data is
passed along with a transaction request and then returned
10 udf5 O Alphanum
in the transaction response. Merchant should ensure that
field is left blank when no data needs to be passed.

11 amt M Numeric Transaction amount

12 authRespCode M Numeric Auth response code provided by PG

13 authCode M Numeric 6 digit authorization code received from switch

© 2020 API Guide Page 24 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Merchant Hosted Transaction Flow (Non 3D Secure Pur-

chase Transactions)

• For Non 3D Secure Purchase Transactions Merchant forwards the API request to ARB Payment gate-
way, below is sample request.
• Action Code for Purchase Transactions is 1

Below is the sample encrypted request from Merchant to PG

[{"id":"IPAYlCR6qZF7q6w", “trandata”:”<encrypted trandata>”} ]

Below are the plain Trandata request

[{“amt”:”12.00”,”action”:”1”,”pass-
word”:”q@a68O$27@JLkcK”,”id”:”IPAYlCR6qZF7q6w”,”curren-
cyCode”:”682”,”trackId”:”123456”,”udf1”:”udf1text”,”udf2”:”udf2text”,”udf3”:”udf3te
xt”,”udf4”:”udf4text”,”udf5”:”udf5text” ,”expYear”:”2022”,”expMonth”:”12”,”mem-
ber”:”cardholdername”,”cvv2”:”212”,”cardNo”,”5453********5539”,”cardType”:”C",
"accountDetails":[{"bankIdCode": "12345d6f", "iBanNum":
"567896743281926354276254","serviceAmount":"200.00","valueDate":"20203112"
},{"bankIdCode": "1234ret3", "iBanNum": "987656743281926354276254","serviceA-
mount":"300.00","valueDate":"20213112" }]
}]

plain Trandata request for Credit Card Installment Transactions (udf6 and udf7 additional
parameters)

[{“amt”:”12.00”,”action”:”1”,”pass-
word”:”q@a68O$27@JLkcK”,”id”:”IPAYlCR6qZF7q6w”,”curren-
cyCode”:”682”,”trackId”:”123456”,”udf1”:”udf1text”,”udf2”:”udf2text”,”udf3”:”udf3te
xt”,”udf4”:”udf4text”,”udf5”:”udf5text”,"udf6":"12345","udf7","C",”expYear”:”2022”,
”expMonth”:”12”,”member”:”cardholder-
name”,”cvv2”:”212”,”cardNo”,”5453********5539”,”cardType”:”C",
"accountDetails":[{"bankIdCode": "12345d6f", "iBanNum":
"567896743281926354276254","serviceAmount":"200.00","valueDate":"20203112"
},{"bankIdCode": "1234ret3", "iBanNum": "987656743281926354276254","serviceA-
mount":"300.00","valueDate":"20213112" }]
}]

© 2020 API Guide Page 25 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Request from Merchant to ARB payment gateway

S. No Fields M/C/O Field Type Description

1 id M Alphanum Tranportal ID. Merchant can download the Tranportal id

from Merchant portal
2 trandata M Alphanum All the below request parameters encrypted and pass the
encrypted value in trandata.

Detailed description of Plain Trandata request parameters

S. No Fields M/C/O Field Type Description

1 amt M Numeric Transaction amount

2 action M Numeric It defines the transactions actions

Purchase: 1
Refund: 2
Void: 3
Inquiry: 8
3 password M Alphanum Tranportal password. Merchant download the same in mer-
chant portal.
4 id M Alphanum Tranportal ID. Merchant download the same in merchant
portal
5 currencyCode M Numeric 3-digit currency code of KSA. Ex:682

6 trackId M Numeric Merchant unique reference no

© 2020 API Guide Page 26 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

S. No Fields M/C/O Field Type Description

11 expYear M Numeric Expiry year of card

12 expMonth M Numeric Expiry month of card

13 member M Alphanum Card holder name

14 cvv2 M Numeric CVV of the card

15 cardNumber M Numeric Cardholders card number

16 cardType M Alphanum Card type Ex : Credit card – C, Debit Card - D

17 accountDetails O JSON Array Split Payment Details.

17.1 bankIdCode C Alphanum 8 – Digit Bank Identification Code

17.2 iBanNum C Alphanum 24 – Digit IBAN Number

17.3 serviceAmount C Numeric Service Amount

17.4 valueDate C Numeric Value Date Format: YYYYDDMM

UDF 6 and UDF7 parameters should be passed only for Credit Card installment Transactions as be-
low:
18 udf6 O Alphanum Credit Card Installment Short Code

19 udf7 O Alphanum Credit Card Installment Type

• Once ARB payment gateway verifies the transaction and returns the response to the same request.

Below is the sample encrypted response from PG to Merchant

[{“tranid”: 201931951332346,"trandata": "<encrypted trandata>",

“status”:”1”, //1 for success transaction, 2 for failure transaction
“error”:null,“errorText”: null}]

© 2020 API Guide Page 27 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Plain trandata in response

[{“paymentId”:-1,”result”:”captured”,”amt”:10.55,”date”:1221,
”ref”:”935110000001”,”udf1”:”udf1text”,”udf2”:”udf2text”,”udf3”:”udf3text”,”udf4”:”
udf4text”,”udf5”:”udf5text”,”trackId”,”3423423”,”tran-
sId”:1242345345234,“authRespCode”:”00”,"authCode":"000000"}]

Response from ARB Payment Gateway to Merchant

S. No Fields M/C/O Field Type Description

1 trandata M AlphaNum All the below response parameters will be provided in

trandata field
2 error C Alphanum If any error during processing, PG will provide the error
code
3 errorText C Alphanum If any error during processing, PG will provide the error de-
scription
4 status M Alphanum If transaction success 1.
If transaction failure 2.

© 2020 API Guide Page 28 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Merchant Hosted Transaction Flow (Inquiry Void, Re-

fund Transactions)

• Inquiry Transactions :As an added security measure ARB Payment Gateway allows merchants to
do an inquiry of already completed transaction by passing certain details of the payment message,
ARB Payment Gateway provides response to this request with appropriate fields in the response;
the merchant is expected to verify the relevant fields like Transaction amount, transaction status
and other transaction fields.
• Refund Transactions : Merchant collects the cancellation request and initiate the transaction using
Refund API. Merchant may initiate refund for full amount or partial amount; Payment Gateway will
allow amount until it reached to original transaction amount.
• Action Code for Inquiry Transactions is 8
• Action code for void Transactions is 3
• Action code for refund Transactions is 2

Below is the sample encrypted request from Merchant to PG

[{"id":"IPAYlCR6qZF7q6w", “trandata”:”<encrypted trandata>” } ]

Below are the plain trandata request

Based on TransID (Payment Gateway Transaction ID):

[{"amt":"70.00","action":"<action code>","password":"q@a68O$27@JLkcK",
"id":"IPAYlCR6qZF7q6w","currencyCode":"682","trackId":"696921377",
"udf5":"TRANID","transId":"201931951332346"}]
Based on Payment ID (Payment ID):

[{"amt":"70.00","action":"<action code>","password":"q@a68O$27@JLkcK",
"id":"IPAYlCR6qZF7q6w","currencyCode":"682","trackId":"696921377","udf5":"Pay-
mentID","transId":"100201931948635783"}]
Based on TrackID (Merchant Transaction ID/Track ID):

[{"amt":"70.00","action":"<action code>","password":"q@a68O$27@JLkcK",
"id":"IPAYlCR6qZF7q6w","currencyCode":"682","trackId":"696921377",
"udf5":"TrackID","transId":"696921377"}]
Request from Merchant to ARB Payment Gateway

S. No Fields M/C/O Field Type Description

1 id M Alphanum Tranportal ID. Merchant can download the Tranportal id from Mer-
chant portal
2 trandata M Alphanum All the below request parameters encrypted and pass the encrypted
value in trandata.

© 2020 API Guide Page 29 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Detailed description of Plain Tran data request parameters

S. No Fields M/C/O Field Type Description

1 id M AlphaNum Unique tranportal ID.

2 password M Alphanum Tranportal password.

3 action M Numeric Transaction action

Ex: “2” for Refund
“3” for Void purchase
“8” for Inquiry
4 amt M Numeric Transaction amount

5 currencyCode M Numeric Currency code of merchant

6 trackId O Numeric A unique tracking id issued by the merchant's system

7 udf5 M Alphanum When merchant want to perform refund/Void/Inquiry based

on PaymentID / TransID / TrackID then merchant need to
pass, a word PaymentID / TRANID/ TrackID in Udf5 field.
8 transId M Numeric When merchant want to perform refund/Void/Inquiry based
on PaymentID / TransID / TrackID then merchant need to
pass the value of, PaymentID / TRANID/ TrackID in this field

• Once ARB payment gateway verifies the transaction and returns the response to the same request.

Below is the sample encrypted response from PG to Merchant

[{“tranid”: 201931951332346,"trandata": "<encrypted trandata>",

“status”:”1”, //1 for success transaction, 2 for failure transaction
“error”: null,“errorText”: null}]

Plain trandata in response

[{“paymentId”:100201934525118923,”result”:”suc-
cess”,”date”:1221,”udf1”:”udf1text”,”udf2”:”udf2text”,”udf3”:”udf3text”,”udf4”:”udf
4text”,”udf5”:”PaymentID”,”trackId”,”3423423”,”transId”:201931951332346,
”ref”:”935110000001”,”authRespCode”:”00”,"authCode":"000000"}]

Response from ARB Payment Gateway to Merchant

© 2020 API Guide Page 30 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

S. No Fields M/C/O Field Type Description

1 trandata M AlphaNum All the below response parameters will be provided in trandata field

2 error C Alphanum If any error during processing, PG will provide the error code

3 errorText C Alphanum If any error during processing, PG will provide the error description

4 status M Alphanum If transaction success 1.

If transaction failure 2.

© 2020 API Guide Page 31 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Merchant Hosted Transaction Flow (Apple Pay Transac-

tions)

• For Apple Pay purchase Transactions Merchant forwards the API request to ARB Payment gateway
below is sample request.
• Action Code for Purchase Transactions is 1

Below is the sample encrypted request from Merchant to PG

[{"id":"IPAYlCR6qZF7q6w", “trandata”:”<encrypted trandata>” } ]

Below are the plain Trandata request

[{"password":"OlE34@zAfcR5$2!","trackId":"466418734","udf5":"Select","payment-
Data":"<encrypted payment Data>","transactionIdenti-
fier":"93FEFF8B40ACB2FC46B3B48130A91E5E83BD7A1EFC0FAA3FA0F128BC755A0D9F","amt":"50.
00","action":"1","paymentMethod":"{\"displayName\":\"Visa 4228\",\"net-
work\":\"Visa\",\"type\":\"debit\"}","id":"IPAYN6dz0roK9DR","currencyCode":"SAR"}]
Request from Merchant to ARB payment gateway

S. No Fields M/C/O Field Type Description

1 id M Alphanum Tranportal ID. Merchant can download the Tranportal id from

Merchant portal
2 trandata M Alphanum All the below request parameters encrypted and pass the en-
crypted value in trandata.

Detailed description of Plain Trandata request parameters

S. No Fields M/C/O Field Type Description

1 amt M Numeric Transaction amount

2 action M Numeric It defines the transactions actions

Purchase: 1
Refund: 2
Void: 3
Inquiry: 8
3 Password M Alphanum Tranportal password. Merchant download the same in mer-
chant portal.
4 id M Alphanum Tranportal ID. Merchant download the same in merchant por-
tal
5 currencyCode M Numeric 3-digit currency code of KSA. Ex:682

© 2020 API Guide Page 32 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

S. No Fields M/C/O Field Type Description

6 trackId M Numeric Merchant unique reference no

• Once ARB payment gateway verifies the transaction and returns the response to the same request.

Below is the sample encrypted response from PG to Merchant

[{“tranid”: 201931951332346,"trandata": "<encrypted trandata>",

“status”:”1”, //1 for success transaction, 2 for failure transaction
“error”:null,“errorText”: null}]

Plain trandata in response

[{"date":520,"trackId":"466418734","transId":202014168384115,"udf5":"Se-
lect","amt":"50.0","udf3":"null","udf4":"null","udf1":"null","udf2":"null","re-
sult":"CAPTURED","authRespcode":"00","ref":"014136000005","paymentId":-1,
"authCode":"000000"}]
Response from ARB Payment Gateway to Merchant

© 2020 API Guide Page 33 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

S. No Fields M/C/O Field Type Description

1 trandata M AlphaNum All the below response parameters will be provided in trandata field

2 error C Alphanum If any error during processing, PG will provide the error code

3 errorText C Alphanum If any error during processing, PG will provide the error description

4 status M Alphanum If transaction success 1.

If transaction failure 2.

© 2020 API Guide Page 34 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Invoice Payment Transaction Flow

1. Customer visits the merchant site and selects the merchandise and confirms to pay using the pay-
ment gateway.
2. Merchant redirects the customer with the Invoice transaction data to the payment gateway.
3. Payment Gateway verifies the invoice transaction request from the merchant and generates the
invoice Payment URL based on the invoice type.
4. Payment gateway will provide the response to merchant with invoice Payment URL.
5. Merchant to redirect the Payment URL to Payment Gateway.
6. There are two types of invoice transactions namely Dedicated and Open invoice.
7. If the initiated transaction type is dedicated, Merchant need to send the buyer details in the request.
8. PG presents the hosted payment page with buyer details to customer and prompts the customer to
enter the card credentials.
9. If the initiated transaction type is open then merchant no need to send buyer details.
10. Payment gateway will get the buyer detail and process the transaction with the respective schemes.
11. Once the transaction complete, PG will send the response to merchant and customer via mail &
SMS.

• Below are the sample JSON request and response,

Request from Merchant to ARB Payment gateway:

[{"id":"IPAYlCR6qZF7q6w", “trandata”:”<encrypted trandata>” }]

• Trandata will contain below parameters encrypted with AES algorithm with CBC Mode, PKCS5Pad-
ding with initialization vector value PGKEYENCDECIVSPC under Resource Key

Plain Trandata for Dedicated Invoice:

[{"password":"1lY@q4Ln7@$DI7x","mobile":"9952919578","amt":"100.00","invoice-
Type":"D","invoiceId":"123456789","id":"IPAYPP9ckEq57Fh","itemDesc":"Watch","buy-
erName":"Alex","currencyCode":"682","email":[email protected],"expiryDate":"15-05-
2020 16:14:18"}]

Plain Trandata for Open Invoice:

[{"password":"1lY@q4Ln7@$DI7x","amt":"100.00","invoiceType":"O","in-
voiceId":"123456789","id":"IPAYPP9ckEq57Fh","itemDesc":"Watch","curren-
cyCode":"682","expiryDate":"15-05-2020 16:14:18"}]
Request from Merchant to ARB Payment gateway

S. No Fields M/C/O Field Type Description

Tranportal ID. Merchant can download the Tranportal id from

1 id M Alphanum
Merchant portal

© 2020 API Guide Page 35 of 58

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

All the below request parameters encrypted and pass the en-
2 trandata M Alphanum
crypted value in trandata.

Dedicated Invoice detailed description of Plain Trandata request parameters.

Field
S. No Fields M/C/O Description
Type

Tranportal password. Merchant download the same in mer-

1 password M Alphanum
chant portal.

Tranportal ID. Merchant download the same in merchant por-

2 Id M Alphanum
tal

3 currencyCode M Numeric 3-digit currency code of KSA. Ex:682

4 invoiceId M Alphanum 50-digit unique Id.

5
itemDesc M Alphanum 500-digit Item Description.

Alpha- 1-digit value ‘’D’’ or ‘’O’’

5 invoiceType M
betic (D-dedicated invoice / O – Open Invoice)

Alpha-
6 buyerName M 50-digit Buyer Name.
betic

7 amt M Numeric Transaction amount.

8 email M alphanum Buyer mail Id.

9 mobile M Numeric Buyer Mobile Number.

Expiry Date of the payment Link.

10 expiryDate O Alphanum
Date Format: “dd-MM-yyyy hh:mm:ss”

Open Invoice detailed description of Plain Trandata request parameters.

Field
S. No Fields M/C/O Description
Type

Tranportal password. Merchant download the same in mer-

1 password M Alphanum
chant portal.

Tranportal ID. Merchant download the same in merchant por-

2 id M Alphanum
tal

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Field
S. No Fields M/C/O Description
Type

3 currencyCode M Numeric 3-digit currency code of KSA. Ex: “682”

4 invoiceId M Alphanum 50-digit unique Id.

5
itemDesc M Alphanum 500-digit Item Description

Alpha- 1-digit value ‘’D’’ or ‘’O’’

5 invoiceType M
betic (D-dedicated invoice / O – Open Invoice)

7 amt O numeric Transaction amount. Ex: “100.00”

Expiry Date of the payment Link.

10 expiryDate O Alphanum
Date Format: “dd-MM-yyyy hh:mm:ss”

• ARB Payment gateway internally validates the request and gives invoice payment page URL in the
response in case of successful validation, if failure then error code and description will be provided.
The below response will be in plain format and there is no encryption for the below. Merchant can
directly parse the response-based on the status and result fields as mentioned below.

Success:
[{"status": "1", "result":
"https://securepayments.alrajhibank.com.sa/mrchptl/iP.htm?Id=Y3FT9" //Invoice Pay-
ment Page URL}]

Failure:
[{"status": "2","error":" IPAY0100124”,
“errorText”:” Problem occurred while validating transaction data”}]
Initial Response from PG to Merchant for Dedicated and Open Invoice

S. No Fields M/C/O Field Type Description

1 status M Numeric If the request validation success, then status will be ‘1’. If the valida-
tion failed, then status will be ‘2’
2 result C Alphanum It contains invoice Payment URL if the validation success
3 error C Alphanum If validation failed, then Payment gateway will provide the respective
error code
4 error- C Alphanum If validation failed, then Payment gateway will provide the respective
Text error description

• If success, Merchant needs to redirect the invoice payment page URL like the below sample

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

https://securepayments.alrajhibank.com.sa/mrchptl/iP.htm?Id=Y3FT9
• Once merchant redirects the link, ARB Payment Gateway shows the invoice Payment Page to cus-
tomer based on the invoice type.
• After validating the customer card details then ARB Payment gateway will provide the final response
to merchant and customer via mail & SMS.

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Merchant Notification Flow for Bank Hosted Transac-

tions

If Notification enabled at Merchant level,

1. Payment gateway will initiate REST call to send the transaction status notification request to
merchant and wait for the acknowledgement.
2. If PG receives the acknowledgment from merchant, then Payment Gateway logs the response
and provides the transaction update to Cortex system for processing the settlement and Pay-
ment Gateway sends the final response to merchant. The final response will be URL redirection.
3. Merchant displays transaction result to customer.
4. In case, if PG does not receive the acknowledgment from merchant then PG will initiate the
VOID transaction to respective scheme to reverse the transaction and there is no payment
advise initiated to Cortex.

If Notification disabled at Merchant level,

1. Payment Gateway logs the response and provides the transaction update to Cortex system for
processing the settlement and Payment Gateway sends final response to merchant and this will
be URL redirection.
2. Merchant displays transaction result to customer.

• Below is the sample merchant notification request and response,

Notification Request from ARB payment gateway to Merchant:

[{“paymentId”:100201935044735860,“trandata”:”<encrypted trandata>”,}]

Plain Trandata:

[{“paymentId”:100201935166676976,”result”:”CAPTURED”,”ref”:”935110000001”,”tran-
sId”:201935166561122,date:1217,”trackId”:”1003383844”,”udf1”:””,”udf2”:””,”udf3”:”8
870091137”,”udf4”:”FC”,”udf5”:”Tidal5”,”amt”:”70.0,”authRespCode”,”00”,"authCode":"
000000"}]
Notification request from PG to Merchant

S. No Fields M/C/O Field Type Description

1 paymentId M Numeric Unique ID generated by Payment gateway. Merchant can store the
payment ID to match the final URL redirection response
2 trandata M Alphanum All the below response parameters encrypted and send the en-
crypted value in trandata

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Detailed description of Plain trandata parameters

S. No Fields M/C/O Field Type Description

Unique ID generated by payment gateway. Based on this payment

1 paymentId M Numeric
Id merchant can match the final URL redirection response

2 result M Alphanum Transaction status

3 ref M Numeric Transaction reference number (RRN)

Unique transaction Id generated by Payment gateway and mer-

4 transId M Numeric chant can use this id for initiating supported transactions (Void, re-
fund and inquiry)

5 date M Numeric Transaction date and time

6 trackId M Numeric Merchant unique reference no

The user (merchant) defines these fields. The field data is passed
along with a transaction request and then returned in the transac-
7 udf1 O Alphanum
tion response. Merchant should ensure that field is left blank when
no data needs to be passed.
The user (merchant) defines these fields. The field data is passed
along with a transaction request and then returned in the transac-
8 udf2 O Alphanum
tion response. Merchant should ensure that field is left blank when
no data needs to be passed.
The user (merchant) defines these fields. The field data is passed
along with a transaction request and then returned in the transac-
9 udf3 O Alphanum
tion response. Merchant should ensure that field is left blank when
no data needs to be passed.
The user (merchant) defines these fields. The field data is passed
along with a transaction request and then returned in the transac-
10 udf5 O Alphanum
tion response. Merchant should ensure that field is left blank when
no data needs to be passed.

11 amt M Numeric Transaction amount

authRespCo
12 M Numeric Auth response code provided by PG
de

13 authCode M Numeric 6 digit authorization code received from switch

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Notification response from Merchant to ARB Payment gateway

S. No Fields M/C/O Field Type Description

1 status M Numeric Status should be ‘1’

2 result M Alphanum Merchant response URL for which PG will provide the final URL redirection
response

Acknowledgment response from merchant to PG:

[{"status": "1", "result":"https://merchant.com/finalresultURL",}]

• If ARB payment gateway receives the acknowledgement from merchant, PG logs the response and
provide the response back to merchant. This will be URL redirection.

Response from PG to merchant.

[{“paymentId”:”100201935166676976”,“trandata”:”<encrypted trandata>”,
“Error”:””,“ErrorText”:””}]

Plain Trandata:

[{“paymentId”:100201935166676976,”result”:”CAPTURED”,”ref”:”935110000001”,”tran-
sId”:201935166561122,”date”:1217,”trackId”:”1003383844”,”udf1”:””,”udf2”:””,”udf3”:
”8870091137”,”udf4”:”FC”,”udf5”:”Tidal5”,”amt”:”70.0,”authRespCode”,”00”,"authCode"
:"000000"}]

• If there is no acknowledgement from Merchant After initiating the merchant notification, PG will wait
for the response based on the configured time and no acknowledgement from merchant then PG
will void the transaction and update the response back to merchant error URL received in the initial
API request.

Response from PG to merchant if no acknowledgement from Merchant:

[{“paymentId”:100201935166676976,”Result”:”Voided”,”error”:”IPAY0200025”,”error-
Text”:”!ERROR!-IPAY0200025 - Problem occurred while getting merchant acknowledge-
ment & transaction reversed”,”trackId”:”123456”,”amt”:”12.0”}]

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Final Response Type , Terminal Resource Key 2 for Final

Response Encryption and Decryption

o If Merchant has REST Flag enabled and key type chosen as two, terminal resource key 2 is
generated for all the terminals created for the merchant.
o Merchant shall encrypt the REST API request to Payment Gateway using the terminal re-source
key 1
o Payment Gateway will decrypt the REST API request from merchant using the default terminal
resource key 1
o The terminal Resource key 2 is used to encrypt the final REST API final response from Payment
Gateway to merchant.
o Merchant needs to decrypt the Rest API final response from Payment Gateway using this Re-
source key 2.
o If Merchant has Rest Flag enabled and Response type chosen as 'GET' , The response type of
REST API final response from payment Gateway to Merchant is GET .
o If Merchant has Rest Flag enabled and Response type chosen as 'POST' , The response type of
REST API final response from payment Gateway to Merchant is POST .

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

FAQ's on Integration Process

Q1. What are the pre requisities for integration process?

Ans. 1. Tranportal ID

2. Tranportal Password

3. Resource Key

4. Payment gateway endpoint

Q2.Where to get tranportal ID , Password , Resource key and end point Url's?

Ans. Tranportal Id , Password , Resource Key and end point URL's will be shared to the merchant
via mail to their registered E-mail Id.

Q3.What is resource key?

Ans. Resource key is unique for a terminal . It is required for encryption of request parameters
and decryption of response paramters while connecting to ARB Payment Gateway. Bank
user will share the resource key in a secured manner.

Q4.What is inquiry transaction?

Ans. ARB Payment Gateway allows merchants to do an inquiry of already completed transaction
by passing certain details of the payment message, ARB Payment Gateway provides re-
sponse to this request with appropriate fields in the response; merchant is expected to
verify the relevant fields like Transaction amount, transaction status and other transaction
fields.

Q5. What are the action codes for inquiry ,refunds and Void transactions?

Ans. action codes :

Action Codes

Action Action code

Purchase 1
Refund 2
Inquiry 8
Void 3
Q6. Based on what parameters can transactions be inquired?

Ans. Transactions can be inquired based on transaction ID , Payment ID and Track ID of original
transaction.

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Q7.How to verify transactions and settlement ?

Ans. After the integration testing, transactions can be verified on merchant Portal
To verify if a transaction has been settled or not merchant can always refer the transaction
detail report in merchant Portal . Navigation to transaction detail report in merchant
portal is as below :

Merchant Portal ->Reports->Transaction Reports->Transaction Detail Report

Q8 . What are the various result codes and their description.

Ans.

Result Description

CAPTURED Captured result will be considered as transaction success

NOT CAPTURED This will be considered as transaction failure
VOIDED Success for Void transaction
DENIED BY RISK If the Risk validation failed, then PG will decline the transaction with this result
HOST TIMEOUT If there is no response from respective interchange during authorization, then PG
will provide the Host timeout result.

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Sample Encryption and Decryption Code for JAVA

public static String encryptAES(String key,String encryptString) throws Exception{

String AES_IV = “PGKEYENCDECIVSPC”;

Byte [] encryptedText=null;
IvParameterSpec ivspec=null;
SecretKeySpec skeySpec=null;
Cipher cipher=null;
Byte [] text=null;
String s=null;
try {
ivspec = new IvParameterSpec(AES_IV.getBytes("UTF-8"));
skeySpec = new SecretKeySpec(key.getBytes("UTF-8"), "AES");
cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
cipher.init(Cipher.ENCRYPT_MODE, skeySpec,ivspec);
text = encryptString.getBytes("UTF-8");
encryptedText = cipher.doFinal(text);
s = byteArrayToHexString(encryptedText);
} catch (Exception e) {
e.printStackTrace();
}
finally
{
encryptedText=null;
ivspec=null;
skeySpec=null;
cipher=null;
text=null;
}
return s.toUpperCase();
}
Note: Before encrypting encryptString value. merchant needs to encode the value with URL
Encoder.
public static String decryptAES(String key,String encryptedString) throws Excep-
tion{
String AES_IV = “PGKEYENCDECIVSPC”;
SecretKeySpec skeySpec=null;
IvParameterSpec ivspec=null;
Cipher cipher =null;

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Byte [] textDecrypted=null;
Try {
Byte [] b = hexStringToByteArray(encryptedString);
skeySpec = new SecretKeySpec(key.getBytes("UTF-8"),"AES");
ivspec = new IvParameterSpec(AES_IV.getBytes("UTF-8"));
cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
cipher.init(Cipher.DECRYPT_MODE, skeySpec,ivspec);
textDecrypted = cipher.doFinal(b);
} catch (Exception e) {
e.printStackTrace();
}
finally
{
skeySpec=null;
ivspec=null;
cipher =null;
}
return(new String(textDecrypted));
}
Note: After decrypting encryptedString value. Merchant needs to decode the textDecrypted value
with URL Decoder.

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Sample Encryption and Decryption Code For JAVAS-

CRIPT

function aesEncrypt(trandata,key)
{
var iv = "PGKEYENCDECIVSPC";
var rkEncryptionIv = aesjs.utils.utf8.toBytes(iv);
var enckey= aesjs.utils.utf8.toBytes(key);
var aesCtr = new aesjs.ModeOfOperation.cbc(enckey, rkEncryptionIv);
var textBytes = aesjs.utils.utf8.toBytes(trandata);
var encryptedBytes = aesCtr.encrypt(aesjs.padding.pkcs7.pad(text Bytes));
var encryptedHex = aesjs.utils.hex.fromBytes(encryptedBytes);
return encryptedHex;
}
Note: Before encrypting trandata value. merchant needs to encode the value with URL
Encoder.

function AESdecryption(encryptedHex,key)
{
var iv = "PGKEYENCDECIVSPC";
var enckey= aesjs.utils.utf8.toBytes(key);
var rkEncryptionIv = aesjs.utils.utf8.toBytes(iv);
var encryptedBytes = aesjs.utils.hex.toBytes(encryptedHex);
var aesCbc = new aesjs.ModeOfOperation.cbc(enckey, rkEncryptionIv);
var decryptedBytes = aesCbc.decrypt(encryptedBytes);
var decryptedText = aesjs.utils.utf8.fromBytes(decryptedBytes);
return decryptedText;
}
Note: After decrypting encryptedHex value. Merchant needs to decode the decryptedText value
with URL Decoder.

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Sample Encryption and Decryption Code For PHP

Encryption:

function encryptAES($str,$key)
{
$str = $this->pkcs5_pad($str);
$ivlen = openssl_cipher_iv_length($cipher="aes-256-cbc");
$iv="PGKEYENCDECIVSPC";
$encrypted = openssl_encrypt($str, "aes-256-cbc",$key, OPENSSL_ZERO_PADDING, $iv);
$encrypted = base64_decode($encrypted);
$encrypted = unpack('C*', ($encrypted));
$encrypted=$this->byteArray2Hex($encrypted);
$encrypted = urlencode($encrypted);
return $encrypted;
}
Note: Before encrypting transaction data, data needs to be encoded using URL-Encoder

Decryption:

function decryptAES ($codcode, $)

{
$code = $this->hex2ByteArray(trim($code));
$code=$this->byteArray2String($code);
$iv = "PGKEYENCDECIVSPC";
$code = base64_encode($code);
$decrypted = openssl_decrypt($code, 'AES-256-CBC', $key, OPENSSL_ZERO_PADDING,
$iv);
return $this->pkcs5_unpad($decrypted);
}
Note: After decrypting transaction data needs to be decoded using URL-Decoder

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Chapter 4 TROUBLESHOOTING

Known Error Codes

The error codes are listed below:

The following table contains the known error codes and their descriptions:

Error Code Error Code Description

IPAY0100114 Duplicate Record, transaction ID already exist

IPAY0100115 Transaction denied due to missing original transaction id.
IPAY0100116 Transaction denied due to invalid original transaction id.
IPAY0100118 Transaction denied due to card number length error
IPAY0100119 Transaction denied due to invalid card number
IPAY0100120 Transaction denied due to invalid payment instrument
IPAY0100121 Transaction denied due to invalid card holder name.
IPAY0100122 Transaction denied due to invalid address.
IPAY0100123 Transaction denied due to invalid postal code.
IPAY0100124 Problem occurred while validating transaction data
IPAY0100125 Payment instrument not enabled.
IPAY0100126 Brand not enabled.
IPAY0100127 Problem occurred while doing validate original transaction
IPAY0100128 Transaction denied due to Institution ID mismatch
IPAY0100129 Transaction denied due to Merchant ID mismatch
IPAY0100130 Transaction denied due to Terminal ID mismatch
IPAY0100131 Transaction denied due to Payment Instrument mismatch
IPAY0100132 Transaction denied due to Currency Code mismatch
IPAY0100133 Transaction denied due to Card Number mismatch
IPAY0100134 Transaction denied due to invalid Result Code
IPAY0100135 Problem occurred while doing perform action code reference id (Validate Original
Transaction)
IPAY0200028 Problem occurred while loading default institution configuration (Validate Original
Transaction)

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Error Code Error Code Description

IPAY0100136 Transaction denied due to previous capture check failure (Validate Original Transac-
tion)
IPAY0100138 Transaction denied due to capture amount versus auth amount check failure (Vali-
date Original
IPAY0100139 Transaction denied due to void amount versus original amount check failure (Vali-
date Original
IPAY0100140 Transaction denied due to previous void check failure (Validate Original Transaction)
IPAY0100141 Transaction denied due to authorization already captured (Validate Original Transac-
tion)
IPAY0100142 Problem occurred while validating original transaction
IPAY0200030 No external connection details for Extr Conn id :
IPAY0200031 Alternate external connection details not found for the alt Extr Conn id :
IPAY0100143 Transaction action is null
IPAY0100144 ISO MSG is null. See log for more details!
IPAY0100145 Problem occurred while loading default messages in ISO Formatter
IPAY0100147 Problem occurred while formatting purchase request in B24 ISO Message Formatter
IPAY0100150 Problem occurred while formatting Reverse purchase request in B24 ISO Message
Formatter
IPAY0100152 Problem occurred while formatting authorization request in B24 ISO Message For-
matter
IPAY0100153 Problem occurred while formatting Capture request in B24 ISO Message Formatter
IPAY0100155 Problem occurred while formatting reverse authorization request in B24 ISO Mes-
sage Formatter
IPAY0100156 Problem occurred while formatting Reverse Capture request in B24 ISO Message
Formatter
IPAY0100159 External message system error
IPAY0100160 Unable to process the transaction.
IPAY0100163 Problem occurred during transaction.
IPAY0100166 Transaction Not Processed due to Empty Authentication Status
IPAY0100167 Transaction Not Processed due to Invalid Authentication Status
IPAY0100168 Transaction Not Processed due to Empty Enrollment Status
IPAY0100169 Transaction Not Processed due to Invalid Enrollment Status
IPAY0100170 Transaction Not Processed due to invalid CAVV
IPAY0100171 Transaction Not Processed due to Empty CAVV
IPAY0100172 Problem occurred while converting amount.
IPAY0100173 Problem occurred while building refund request.

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Error Code Error Code Description

IPAY0100175 Problem occurred in refund process.

IPAY0100039 Invalid payment id .
IPAY0200009 Problem occurred while getting payment details.
IPAY0100041 Payment details missing.
IPAY0100042 Transaction time limit exceeds.
IPAY0200011 Problem occurred while getting IP block details.
IPAY0100043 IP address is blocked already
IPAY0100044 Problem occurred while loading payment page.
IPAY0100045 Denied by Risk
IPAY0200013 Problem occurred while updating description details in payment log.
IPAY0100047 Payment Page validation failed due to invalid Order Status:
IPAY0200015 Problem occurred while getting terminal details.
IPAY0100050 Invalid terminal key.
IPAY0100051 Missing terminal key.
IPAY0100053 Problem occurred while processing direct debit.
IPAY0100054 Payment details not available
IPAY0100056 Instrument not allowed in Terminal and Brand
IPAY0200016 Problem occurred while getting payment instrument.
IPAY0200018 Problem occurred while getting transaction details
IPAY0100057 Transaction denied due to invalid processing option action code
IPAY0100058 Transaction denied due to invalid instrument
IPAY0100059 Transaction denied due to invalid currency code.
IPAY0100060 Transaction denied due to missing amount.
IPAY0100061 Transaction denied due to invalid amount.
IPAY0100062 Transaction denied due to invalid Amount/Currency.
IPAY0100063 Transaction denied due to invalid track ID
IPAY0100064 Transaction denied due to invalid UDF1:
IPAY0100065 Transaction denied due to invalid UDF2:
IPAY0100066 Transaction denied due to invalid UDF3:
IPAY0100067 Transaction denied due to invalid UDF4:
IPAY0100068 Transaction denied due to invalid UDF5:
IPAY0100069 Missing payment instrument.
IPAY0100070 Transaction denied due to failed card check digit calculation.

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Error Code Error Code Description

IPAY0100071 Transaction denied due to missing CVD2.

IPAY0100072 Transaction denied due to invalid CVD2.
IPAY0100073 Transaction denied due to invalid CVV.
IPAY0100074 Transaction denied due to missing expiry year.
IPAY0100075 Transaction denied due to invalid expiry year.
IPAY0100076 Transaction denied due to missing expiry month.
IPAY0100077 Transaction denied due to invalid expiry month.
IPAY0100078 Transaction denied due to missing expiry day.
IPAY0100079 Transaction denied due to invalid expiry day.
IPAY0100080 Transaction denied due to expiration date.
IPAY0100081 Card holder name is not present
IPAY0100082 Card address is not present
IPAY0100083 Card postal code is not present
IPAY0100086 Transaction denied due to missing CVV.
IPAY0100095 Terminal inactive.
IPAY0100098 Terminal Action not enabled for Transaction request, Terminal “termid” ,Tran Action
: “action”
IPAY0100099 Terminal Payment Instrument not enabled for Transaction request, Terminal “termid
” , Tran Instrument:"PAYMENT_INSTRUMENT"
IPAY0100100 Problem occurred while authorize
IPAY0200019 Problem occurred while getting risk profile details
IPAY0100102 Denied by risk : Maximum Floor Limit Check - Fail
IPAY0100103 Transaction denied due to Risk : Maximum transaction count
IPAY0100104 Transaction denied due to Risk : Maximum processing amount
IPAY0200022 Problem occurred while getting currency.
IPAY0100106 Invalid payment instrument
IPAY0200024 Problem occurred while getting brand rules details.
IPAY0100107 Instrument not enabled.
IPAY0200025 Problem occurred while getting terminal details.
IPAY0100109 Invalid subsequent transaction, payment id is null or empty.
IPAY0200026 Problem occurred while getting transaction log details.
IPAY0200027 Missing encrypted card number.
IPAY0100111 Card decryption failed.

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Error Code Error Code Description

IPAY0100113 “transaction id” is a subsequent transaction, but original transaction id is invalid :

IPAY0100021 Missing currency.
IPAY0100024 Invalid amount.
IPAY0100027 Invalid track id.
IPAY0100030 Invalid user defined field3.
IPAY0200007 Problem occurred while validating payment details
IPAY0200008 Problem occurred while verifying payment details.
IPAY0100037 Payment id missing.
IPAY0100040 Transaction in progress in another tab/window.
IPAY0100052 Problem occurred during merchant response encryption.
IPAY0100055 Invalid Payment Status
IPAY0200017 Problem occurred while getting payment instrument list
IPAY0100094 Sorry, this instrument is not handled
IPAY0100101 Denied by risk : Risk Profile does not exist
IPAY0200020 Problem occurred while performing transaction risk check
IPAY0200021 Problem occurred while performing risk check
IPAY0200023 Problem occurred while determining payment instrument
IPAY0100108 Perform risk check : Failed
IPAY0100110 Invalid subsequent transaction, Tran Ref id is null or empty.
IPAY0100112 Problem occurred in method loading original transaction data(card number, exp
month / year) for orig_tran_id
IPAY0100117 Transaction denied due to missing card number.
IPAY0100137 Transaction denied due to refund amount greater than auth amount check failure (
Validate Original Transaction )
IPAY0200029 Problem occurred while getting external connection details.
IPAY0200032 Problem occurred while getting external connection details for Extr CConn id :
IPAY0100151 Problem occurred while formatting Refund request in B24 ISO Message Formatter
IPAY0100154 Problem occurred while formatting Reverse Refund request in B24 ISO Message For-
matter
IPAY0100158 Host (SWITCH) timeout
IPAY0100161 Merchant is not allowed for encryption process.
IPAY0100176 Decrypting transaction data failed.
IPAY0100177 Invalid input data received.
IPAY0100178 Merchant encryption enabled.

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Error Code Error Code Description

IPAY0100179 IVR not enabled.

IPAY0100180 Authentication not available.
IPAY0100181 Card encryption failed.
IPAY0200037 Error occurred while getting Merchant ID
IPAY0100186 Encryption enabled.
IPAY0100189 Transaction denied due to brand directory unavailable
IPAY0100190 Transaction denied due to Risk : Maximum transaction count
IPAY0100191 Denied by risk : Negative Card check - Fail
IPAY0100192 Transaction Not Processed due to Empty XID
IPAY0100193 Transaction Not Processed due to invalid XID
IPAY0100202 Error occurred in Determine Payment Instrument
IPAY0100194 Transaction denied due to Risk : Minimum Transaction Amount processing
IPAY0100195 Transaction denied due to Risk : Maximum refund processing amount
IPAY0100196 Transaction denied due to Risk : Maximum processing amount
IPAY0100197 Transaction denied due to Risk : Maximum debit amount
IPAY0100198 Transaction denied due to Risk : Transaction count limit exceeded for the IP
IPAY0100199 Transaction denied due to previous refund check failure ( Validate Original Transac-
tion )
IPAY0100200 Denied by risk : Negative BIN check - Fail
IPAY0100201 Denied by risk : Declined Card check – Fail
IPAY0100203 Problem occurred while doing perform transaction
IPAY0100204 Missing payment details
IPAY0100206 Problem occurred while getting currency minor digits
IPAY0100207 Bin range not enabled
IPAY0100208 Action not enabled
IPAY0100209 Institution config not enabled
IPAY0100213 Problem occurred while processing the hosted transaction request
IPAY0100214 Problem occurred while verifying tranportal id
IPAY0100215 Invalid tranportal id
IPAY0100216 Invalid data received
IPAY0100217 Invalid payment detail
IPAY0100218 Invalid brand id
IPAY0100219 Missing card number

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Error Code Error Code Description

IPAY0100220 Invalid card number

IPAY0100221 Missing card holder name
IPAY0100222 Invalid card holder name
IPAY0100223 Missing cvv
IPAY0100224 Invalid cvv
IPAY0100225 Missing card expiry year
IPAY0100226 Invalid card expiry year
IPAY0100227 Missing card expiry month
IPAY0100228 Invalid card expiry month
IPAY0100229 Invalid card expiry day
IPAY0100230 Card expired
IPAY0100231 Invalid user defined field
IPAY0100232 Missing original transaction id
IPAY0100233 Invalid original transaction id
IPAY0100234 Problem occurred while formatting Reverse completion request in ISO Message For-
matter
IPAY0100235 Problem occurred while formatting Reverse refund request in ISO Message Format-
ter
IPAY0100236 Problem occurred while formatting Reverse refund request in ISO Message Format-
ter
IPAY0100237 Problem occurred while formatting Reverse purchase request in ISO Message For-
matter
IPAY0100238 Problem occurred while formatting Capture request in ISO Message Formatter
IPAY0100239 Problem occurred while formatting authorization request in ISO Message Formatter
IPAY0100240 Problem occurred while formatting refund request in ISO Message Formatter
IPAY0100241 Problem occurred while formatting purchase request in ISO Message Formatter
IPAY0100243 NOT SUPPORTED
IPAY0100244 Payment Instrument Not Configured
IPAY0100245 Problem occurred while sending/receiving ISO message
IPAY0100246 Problem occurred while doing perform ip risk check
IPAY0100249 Merchant response url is down
IPAY0100250 Payment details verification failed
IPAY0100251 Invalid payment data
IPAY0100253 Problem occurred while cancelling the transaction

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Error Code Error Code Description

IPAY0100254 Merchant not enabled

IPAY0100255 External connection not enabled
IPAY0100256 Payment encryption failed
IPAY0100257 Brand rules not enabled
IPAY0100260 Payment option(s) not enabled
IPAY0100261 Payment hashing failed
IPAY0100262 Problem occurred during VEREQ process
IPAY0100263 Transaction details not available
IPAY0100264 Signature validation failed
IPAY0100265 PARes status not successful
IPAY0100266 Brand directory unavailable
IPAY0100267 PARes status not successful
IPAY0100268 3d secure not enabled for the brand
IPAY0100269 Invalid card check digit
IPAY0100270 PARes status not successful
IPAY0100271 Problem occurred while formatting purchase request in MASTER ISO Message For-
matter
IPAY0100272 Problem occurred while validating xml message format
IPAY0100273 Problem occurred while validation VERES message format
IPAY0100274 VERES message format is invalid
IPAY0100275 Problem occurred while formatting Credit request in MASTER ISO Message Format-
ter
IPAY0100276 Problem occurred while formatting Reverse purchase request in MASTER ISO Mes-
sage Formatter
IPAY0100277 Problem occurred while formatting Reverse Credit request in MASTER ISO Message
Formatter
IPAY0100278 Problem occurred while formatting reverse authorization request in MASTER ISO
Message Formatter
IPAY0100279 Problem occurred while formatting Reverse Capture request in MASTER ISO Mes-
sage Formatter
IPAY0100280 Problem occurred while formatting Capture request in MASTER ISO Message For-
matter
IPAY0100281 Transaction Denied due to missing Master Brand
IPAY0100282 Transaction Denied due to missing Visa Brand
IPAY0100283 Problem occurred in determine payment instrument

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Error Code Error Code Description

IPAY0100284 Invalid subsequent transaction, track id is null or empty

IPAY0100285 Transaction denied due to invalid original transaction
IPAY0100289 Transaction denied due to Risk : Maximum credit amount
IPAY0100291 Problem occurred while validating original transaction
IPAY0100292 Transaction denied due to invalid PIN
IPAY0100293 Transaction denied due to duplicate Merchant trackid
IPAY0100294 Transaction denied due to missing Merchant trackid
IPAY0100295 Missing Merchant Track Id
IPAY0100327 Invalid Buyer Email ID
IPAY0100328 Invalid Buyer Mobile No.
IPAY0100329 Invalid Buyer Name
IPAY0100330 Invalid Minor digits length
IPAY0100331 Invalid Expiry Date
IPAY0100332 Invalid Invoice Id
IPAY0100333 Invalid Item Description
IPAY0100334 Invalid Udf1

ARB Merchant Implementation Guide – REST APIs | Rest API Specifications

Handling Final Response from Payment Gateway

Handling Transaction Response:

▪ By decrypting trandata Merchant can able to get the JSON Response. JSON response con-
tains all the required data.

Handling Failure Transaction Response:

▪ If trandata is null or empty, then merchant needs to do follow below step to get response
fields from Payment Gateway.
▪ To get Transaction Id: request.getParameter("tranid") this value can be null or empty
▪ To get Payment Id: request.getParameter("paymentid") this value can be null or empty
▪ To get Error Description: request.getParameter("ErrorText")
▪ To get Error Code: request.getParameter("Error")

Obelwb PDF
83% (6)
Obelwb PDF
22 pages
Fiscal Device Gateway API v7.2 - Clients
No ratings yet
Fiscal Device Gateway API v7.2 - Clients
77 pages
Customization Guide
No ratings yet
Customization Guide
838 pages
Importers and Distributors - The Saudi Arabian Furniture Sector
67% (9)
Importers and Distributors - The Saudi Arabian Furniture Sector
26 pages
Importers and Distributors - The Saudi Arabian Furniture Sector
67% (9)
Importers and Distributors - The Saudi Arabian Furniture Sector
26 pages
ARB Payment Gateway REST API Integration Doc - V1.26
No ratings yet
ARB Payment Gateway REST API Integration Doc - V1.26
288 pages
Gas and LNG Sales and Transportation Agreements - Principles and Practice
No ratings yet
Gas and LNG Sales and Transportation Agreements - Principles and Practice
749 pages
PostEx-COD API Integration Guide V4.1.9-1
No ratings yet
PostEx-COD API Integration Guide V4.1.9-1
33 pages
Payment Gateway Integration Guide
No ratings yet
Payment Gateway Integration Guide
69 pages
Machine Learning-1
No ratings yet
Machine Learning-1
64 pages
Server Side Swift With Kitura v2.0.0
No ratings yet
Server Side Swift With Kitura v2.0.0
303 pages
David Harris - Art of Calligraphy PDF
No ratings yet
David Harris - Art of Calligraphy PDF
128 pages
APIGateway DevelopersGuide allOS en PDF
No ratings yet
APIGateway DevelopersGuide allOS en PDF
162 pages
MC4204 - Mobile Application Development
No ratings yet
MC4204 - Mobile Application Development
200 pages
APi File Structures
0% (1)
APi File Structures
58 pages
TPH Day - 3 - R18withoutnotespage
No ratings yet
TPH Day - 3 - R18withoutnotespage
107 pages
What Is API
No ratings yet
What Is API
13 pages
On Ipo
100% (1)
On Ipo
24 pages
YoozRising RestAPI User Manual EN
No ratings yet
YoozRising RestAPI User Manual EN
24 pages
Business Requirement Document For Payment Service Provider Platform
100% (1)
Business Requirement Document For Payment Service Provider Platform
3 pages
OTA Firmware
No ratings yet
OTA Firmware
10 pages
Redp 5458
No ratings yet
Redp 5458
118 pages
CnMaestro 2.4.1 RESTful API
No ratings yet
CnMaestro 2.4.1 RESTful API
89 pages
Generic Communication Protocols Evaluation: Intro To Restful Api and Json
No ratings yet
Generic Communication Protocols Evaluation: Intro To Restful Api and Json
15 pages
PGD v5 Documentation
No ratings yet
PGD v5 Documentation
443 pages
Bkash Parameter - Requirement-9-10-2019
No ratings yet
Bkash Parameter - Requirement-9-10-2019
4 pages
Tamara RLC Master v20 DIGITAL
No ratings yet
Tamara RLC Master v20 DIGITAL
25 pages
XUI20Programming20Guide 331789465
No ratings yet
XUI20Programming20Guide 331789465
47 pages
ICC Model Contracts Catalogue PDF
0% (1)
ICC Model Contracts Catalogue PDF
8 pages
Technology Behind Uber PDF
No ratings yet
Technology Behind Uber PDF
18 pages
Ics2305 Systems Programming Lecture Notes
No ratings yet
Ics2305 Systems Programming Lecture Notes
73 pages
8-Puzzle Solving Using The A - Algorithm Using Python and PyGame - CodeProject
No ratings yet
8-Puzzle Solving Using The A - Algorithm Using Python and PyGame - CodeProject
9 pages
NetworkUPSTools UserManual
No ratings yet
NetworkUPSTools UserManual
87 pages
04 State Management
No ratings yet
04 State Management
35 pages
Static Code Analysis Exercise
No ratings yet
Static Code Analysis Exercise
6 pages
10 MiddleWare
No ratings yet
10 MiddleWare
23 pages
ZK 5 Developer's Reference
No ratings yet
ZK 5 Developer's Reference
378 pages
DESCO Tender Notice (12 Storied Building)
No ratings yet
DESCO Tender Notice (12 Storied Building)
2 pages
Schdule A P2 PDF
No ratings yet
Schdule A P2 PDF
42 pages
A Guide To The ACI Worldwide BASE24-eps On z/OS: Front Cover
No ratings yet
A Guide To The ACI Worldwide BASE24-eps On z/OS: Front Cover
198 pages
GitHub Manual
No ratings yet
GitHub Manual
18 pages
Codebeamer SwaggerAPI
No ratings yet
Codebeamer SwaggerAPI
7 pages
Yahya Thesis - Draft
100% (1)
Yahya Thesis - Draft
58 pages
INTERN
No ratings yet
INTERN
40 pages
AWP Manual (2019) (E-Next - In)
No ratings yet
AWP Manual (2019) (E-Next - In)
27 pages
Meat and Live Animal Export in Ethiopia - Status, Challenges and Opportunities
75% (4)
Meat and Live Animal Export in Ethiopia - Status, Challenges and Opportunities
6 pages
C# XMLRPC Example
No ratings yet
C# XMLRPC Example
2 pages
Accounting Systems
No ratings yet
Accounting Systems
2 pages
Chemistry and Envi Engg
No ratings yet
Chemistry and Envi Engg
7 pages
300-LARAVEL-Intro API RESTful PDF
No ratings yet
300-LARAVEL-Intro API RESTful PDF
30 pages
Introduction To Transaction Processing
No ratings yet
Introduction To Transaction Processing
66 pages
Oracle Flexcube Restful Services Usage
No ratings yet
Oracle Flexcube Restful Services Usage
10 pages
Block Chain: Ilma University (Formerly Ibt)
No ratings yet
Block Chain: Ilma University (Formerly Ibt)
15 pages
Web Services: J.Amirtharaj Solomon Technology Group
100% (1)
Web Services: J.Amirtharaj Solomon Technology Group
34 pages
Icepay Rest API Manual
No ratings yet
Icepay Rest API Manual
19 pages
Api 141
No ratings yet
Api 141
16 pages
URL and Socket
No ratings yet
URL and Socket
10 pages
API Pentesting
No ratings yet
API Pentesting
27 pages
DSpace Installation v4.0 PDF
No ratings yet
DSpace Installation v4.0 PDF
29 pages
Concept of Shariah
100% (3)
Concept of Shariah
13 pages
Documentation Postman SalesPad WebAPI Example Usage
No ratings yet
Documentation Postman SalesPad WebAPI Example Usage
16 pages
Automated System in Banking
No ratings yet
Automated System in Banking
60 pages
Business Analytics
No ratings yet
Business Analytics
9 pages
PHP Hyper Text Preprocessor
100% (2)
PHP Hyper Text Preprocessor
35 pages
SF Rest API Cheatsheet Web
No ratings yet
SF Rest API Cheatsheet Web
4 pages
NMMS Ut-3 em (20.10.2023)
No ratings yet
NMMS Ut-3 em (20.10.2023)
4 pages
Product Booklet
No ratings yet
Product Booklet
19 pages
MPG Developer Guide
No ratings yet
MPG Developer Guide
19 pages
Auth API Documentation
No ratings yet
Auth API Documentation
6 pages
The Bhagavata Its Philosophy, Its Ethics, and Its Theology
No ratings yet
The Bhagavata Its Philosophy, Its Ethics, and Its Theology
125 pages
Jadwa Investment Annual Report 2007 - English
No ratings yet
Jadwa Investment Annual Report 2007 - English
22 pages
Synopsis NFT Marketplace
No ratings yet
Synopsis NFT Marketplace
7 pages
Introduction To Takaful
No ratings yet
Introduction To Takaful
2 pages
Ma Geography Syllabus Revised 2020
No ratings yet
Ma Geography Syllabus Revised 2020
61 pages
Thesis Scarlet Letter
100% (3)
Thesis Scarlet Letter
8 pages
TeamDesk REST API
No ratings yet
TeamDesk REST API
30 pages
PHP FTP Functions
No ratings yet
PHP FTP Functions
3 pages
قمة الرياض الخليجية آسيان
No ratings yet
قمة الرياض الخليجية آسيان
31 pages
Release Doc BAXI
No ratings yet
Release Doc BAXI
9 pages
1 4
No ratings yet
1 4
20 pages
Ivan Ilyin, Putin's Philosopher of Russian Fascism
100% (1)
Ivan Ilyin, Putin's Philosopher of Russian Fascism
32 pages
Zakat Dalel English
No ratings yet
Zakat Dalel English
8 pages
Ethiopia - Open Letter To DR Eleni Gabre-Madhin: Ethiopian Commodity Exchange
No ratings yet
Ethiopia - Open Letter To DR Eleni Gabre-Madhin: Ethiopian Commodity Exchange
5 pages
Electric Vehicles: Zero Carbon Australia
No ratings yet
Electric Vehicles: Zero Carbon Australia
98 pages
Master of Science in Commodity Trading
No ratings yet
Master of Science in Commodity Trading
2 pages
MPP 2019
No ratings yet
MPP 2019
28 pages
Condo Adjustment Suggestions
No ratings yet
Condo Adjustment Suggestions
1 page
IR6001 Syllabus
No ratings yet
IR6001 Syllabus
19 pages
EUR Doc 025 V2.0 RNP APCH Guidance Material
No ratings yet
EUR Doc 025 V2.0 RNP APCH Guidance Material
42 pages
Today: in This Issue AAOMS Provides OMSF $120,000 To Support Clinical Surgery Fellowships
No ratings yet
Today: in This Issue AAOMS Provides OMSF $120,000 To Support Clinical Surgery Fellowships
18 pages
TX001202 2-Handout-D-The Nicene Creed and Commentary
No ratings yet
TX001202 2-Handout-D-The Nicene Creed and Commentary
4 pages
Document Cheikh Barry Lambey
No ratings yet
Document Cheikh Barry Lambey
1 page
Electronic Documents and Records Management Systems (EDRMS)
No ratings yet
Electronic Documents and Records Management Systems (EDRMS)
5 pages
Kliping Bahasa Inggris
No ratings yet
Kliping Bahasa Inggris
15 pages
Hair Co
No ratings yet
Hair Co
1 page
The Meaning of Life
No ratings yet
The Meaning of Life
4 pages
EOC FR 001 Transmittal Form
No ratings yet
EOC FR 001 Transmittal Form
10 pages
CHUYÊN ĐỀ MATCHING HEADINGS
No ratings yet
CHUYÊN ĐỀ MATCHING HEADINGS
9 pages
Topic 3 - Process Conception, Types, Management and Measurement of Performance
No ratings yet
Topic 3 - Process Conception, Types, Management and Measurement of Performance
8 pages
Ordinance No. 651 - Ocred
No ratings yet
Ordinance No. 651 - Ocred
2 pages
I.example Logbook
No ratings yet
I.example Logbook
5 pages
Sro 913
No ratings yet
Sro 913
1 page
Presentation1.Ppt Ass
No ratings yet
Presentation1.Ppt Ass
8 pages
Sakshi Choudhary
No ratings yet
Sakshi Choudhary
1 page
Islamic Finance
No ratings yet
Islamic Finance
2 pages