E-Payment Gateway

Technical Specification v1.7

12 September 2021
 Confidentiality Notice
This document is confidential. Arab Payment Services strictly prohibits any reprinting,
copying, translating and any sort of reproducing of this document, whether it is partially or
completely.

Revisions
Date Revision Author Description
16/09/2018 1.0 Abdullah Adel Document Preparation
19/ 10/2018 1.1 Hussein Shaker Document Preparation
03/12/2020 1.2 Salah Hassan Change API link
04/08/2021 1.3 Salah Hassan Change API Request
06/07/2021 1.4 Salah Hassan Add getOrderStatusExtended.do,
Remove refund,
Remove reversal
12/09/2021 1.5 Salah Hassan API to get list of transactions
07/11/2021 1.6 Salah Hassan Add New field (Phone) to send an
SMS notification to the customer
01/06/2022 1.7 Salah Hassan Remove Fail URL and the
merchant should be sent Get
Order Status to check the
Payment.
© 2021 Arab Payment Services

1. Introduction
Internet acquiring is used to sell goods and services via the public Internet, allowing
customers to use their regular bank cards to make purchases. A merchant planning to sell
goods or services via the
Internet must ensure the security of the payments being processed by taking the following
measures.

• Key data (such as personal data and bank cards details) must be transferred via a
secure (SSL or TLS) connection.

• Information on the current payment (amount, currency, or description of the order)

and the result of the payment must be protected from and not be accessed by
intruders.

• Before the payment is made, the customer’s card parameters (for example, the expiry
date, cardholder name and so on) should be checked.

The 3-D Secure protocol is used to provide an additional security layer. The major payments
networks have introduced their own services based on the 3-D Secure protocol, for example,
MasterCard has “Mastercard SecureCode” and Visa has “Verified by Visa. ”

The APS E-commerce Payment Gateway is used as a technology platform. It enables a

merchant to perform the necessary safety procedures without the need to significantly
restructure their Internet store site and existing business processes.

2. Merchant Requirements
The merchant should have developed a website that can interact with APS E-commerce
Payment Gateway. There is no specific programming language required, the website can be
developed using any language that can send/receive HTTP requests. The merchant website
should be integrated with a database to store all orders made by the customers as an order
ID will be required by the EPG to process the order.

The flow starts with the merchant making an order registration request, after the request is
approved by EPG, the customer will be redirected to APS payment page. The customer will
input its information, submits the payment, and get redirected based on the operation result.
3. REST Interface
Interactions between the merchant and the APS E-commerce Payment Gateway are
implemented as HTTP requests with POST method to specific URLs. These are separate for
each individual request type.
The parameters used in the interactions are sent as parameters of POST request; their values
must be URL-encoded in the request body with the content type application/x-www-form-
URL-encoded.

The result of processing a request returns as a JSON object, for example:

{"errorCode":"12","errorMessage":"Empty amount"}

For authorization purposes, each request must include the login and password of the
merchant that were generated during its registration. The values are sent as the following
parameters:

Name Type Mandatory Description

userName AN..30 Yes Login of the merchant generated
during registration.
password AN..30 Yes Password of the merchant generated
during registration.

All text fields must use UTF-8 encoding. In REST requests special characters must be
encoded using URL encoding. The table of characters can be viewed at the following URL:

https://www.w3schools.com/tags/ref_urlencode.asp. For example, a password qwe?rt%y is

transferred as qwe%0Frt%25y.

Note: The error code does not display the order status. To view the status of an order, use
the getOrderStatus.

3.1 Order Registration Request

To register an order use register.do, these requests are designed to register orders in the
APS Ecommerce Payment Gateway and have the same set of parameters.
Request Parameters:
Name Type Mandatory Description
userName AN..30 Yes Merchant login received during
registration.
password AN..30 Yes Merchant password received during
registration.
orderNumber AN..32 Yes Identifier of the order in the
merchant system.

amount N..20 Yes Order amount in the

minor denomination (for
example, cents).
currency N3 Yes Payment currency code in the ISO
4217 format.
You will add currency exponent based
on currency code, for IQD the code is
368 and for USD the code is 840, so for
IQD will add 000 to amount (Fils), and
for USD add 00 to amount (cent)

Example: the amount is 100 $ so you

will send 10000 and for IQD the amount
is 1000 IQD you will sent 1000000

returnUrl AN..512 Yes URL to which the customer is

redirected after completed the
transaction and you should be send a
new request as get order status.
description AN..512 No Free form description of the order.
language A2 No Language code in the ISO 639-1
format. If unspecified, APS E-
commerce Payment Gateway uses
the default language from the
merchant settings. Error messages
are returned in this language.

The system support three languages

EN: English
AR: Arabic
KU: kurdish
clientId AN..255 No Customer identifier in the merchant
system. Itis used in binding.
 sessionTimeoutSecs N...9 No Lifespan of the order in seconds. If
the parameter is not specified, then
the value from the merchant settings
is used, therwise the default value
(1200 seconds) is used. If the request
contains the expirationDate
parameter, the sessionTimeoutSecs
parameter is ignored.
phone AN..255 No If notifying customers is enabled, the
customer’s phone number to send
SMS notifications to.

Response Parameters:
Name Type Mandatory Description
orderId ANS36 No Unique order number in the APS
Ecommerce Payment Gateway.
It is absent if the order registration
has failed
(the error is described in the
ErrorCode field).
formUrl AN..512 No URL of the payment page to which the
customer should be redirected. If the
order registration has failed, this
parameter is absent (the error is
described in the ErrorCode field).
errorCode N3 No Response code: 0 in the case of a
successful transaction, other code if
an error occurred when processing
the request.
errorMessage AN..512 No Description of the error in the
language that was sent in the
language parameter of the request.

Error codes (values of the errorCode field)

Value Description
0 No system error.
Order with given order number has already been processed or the
childId is incorrect.
1
Order with this number was registered, but was not paid.
Sub-merchant is blocked or deleted.
 3 Unknown currency.
Order number is not specified.
Merchant user name is not specified.
4 Amount is not specified.
Return URL cannot be empty.
Password cannot be empty.
Incorrect value of a request parameter.
Incorrect value in the Language parameter.
5 Access is denied.
Merchant must change the password.
Invalid jsonParams[].
7 System error.

Request example for UAT (test environment)

POST /rest/register.do HTTP/1.1

Host: uat-proxy.aps.iq:5443
Content-Type: application/x-www-form-urlencoded

userName=API_USERNAME&password=API_PASSWORD&orderNumber=SALAH_26911719&amount
=100000&currency=368&returnUrl=https://www.google.com&language=ar&description=Test&sessi
onTimeoutSecs=5000

Request example for Production (LIVE environment)

POST /rest/register.do HTTP/1.1

Host: ecommerce.aps.iq:4443
Content-Type: application/x-www-form-urlencoded

userName=API_USERNAME&password=API_PASSWORD&orderNumber=SALAH_26911719&amount
=100000&currency=368&returnUrl=https://www.google.com&language=ar&description=Test&sessi
onTimeoutSecs=5000

Response example

{"errorCode":0,"orderId":"778a7ebf-88d5-4407-94b3-dfcab6e51f56","formUrl":"https://uat-
proxy.aps.iq:5443/epg/merchants/test/payment_ar.html?mdOrder=778a7ebf-88d5-4407-94b3-
dfcab6e51f56"}
3.2 Order status request
To obtain the current state of a registered order, send data with getOrderStatus.do method
(GET or POST) to the corresponding URL. The order status is determined by the value of
the OrderStatus parameter. Note: The authCode field is deprecated.

Request Parameters:
Name Type Mandatory Description
userName AN..30 Yes Merchant login received during
registration.
password AN..30 Yes Merchant password received during
registration.
orderId ANS36 Yes Unique order number in the
APS Ecommerce Payment
Gateway.
language A2 No Language code in the ISO 639-1
format.
If unspecified, APS E-commerce
Payment Gateway uses the default
language from the merchant
settings. Error messages are
returned in this language.

Response Parameters:
Name Type Mandatory Description
OrderStatus N3 No Displays the order status in APS
Ecommerce Payment Gateway.
Possible values are listed in the
table below. This parameter is
absent if no order with the
specified ID is found.
ErrorCode N3 No Error code.
ErrorMessage AN..512 No Description of the error in the
language that was sent in the
language parameter of the request.
OrderNumber AN..32 Yes Identifier of the order in the
merchant system.
Pan N..19 No Masked number of the card that
was used in payment. It is specified
only for paid orders.
expiration N6 No Card expiration date in the YYYYMM
format. It is specified only for paid
orders.
cardholderName A..64 No Cardholder name. It is specified only
for paid orders.
Amount N..20 Yes Order amount in the minor
denomination (for example, cents).
currency N3 No Payment currency code in the ISO
4217 format.
approvalCode AN6 No Payments network authorization
code. The field has fixed length of
six characters; it can contain both
numbers and letters.

authCode N3 No This parameter is deprecated. Its

value is always 2 regardless of the
order status and the processing
system authorization code.

Ip AN..20 No IP address of the customer who

paid for the order.

clientId AN..255 No Identifier of the customer in the

merchant’s system. It is used to
implement the binding functional. It
may be present, if the merchant
has the permission to create
bindings.

bindingId AN..255 No Identifier of the binding created

when paying this order or created
earlier and used to pay for
this order. It is present only if
the merchant has the
permission to create bindings.
The OrderStatus field may have the following values:

State Number Description

0 Order registered, but not paid.
1 Preauthorization amount was put on hold (for a two-phase payment).
2 Amount was deposited successfully.
3 Authorization has been reversed.
4 Transaction has been refunded.
5 Authorization has been initiated via the issuer’s ACS.
6 Authorization is declined.

Error codes (values of the ErrorCode field)

Value Description
0 No system error.
2 The order is declined because of an error in the payment credentials.
Access is denied.
5 The user must change the password.
orderId is empty.
6 Unregistered OrderId.
7 System error.

Request example for UAT (test environment)

POST /payment/rest/getOrderStatus.do HTTP/1.1

Host: uat-proxy.aps.iq:5443
Content-Type: application/x-www-form-urlencoded

orderId=8d9364ce-916f-4f96-8f60-
4c3194e7cb1f&language=en&password=API_PASSWORD&userName=API_USERNAME

example for Production (LIVE environment)

POST /payment/rest/getOrderStatus.do HTTP/1.1

Host: ecommerce.aps.iq:4443
Content-Type: application/x-www-form-urlencoded

orderId=8d9364ce-916f-4f96-8f60-
4c3194e7cb1f&language=en&password=API_PASSWORD&userName=API_USERNAME
Response example
{"expiration":"202301","cardholderName":"SDSD","depositAmount":0,"currency":"368","authCode":2,"ErrorC
ode":"2","ErrorMessage":"Payment is
declined","OrderStatus":6,"OrderNumber":"SALAH_30","Pan":"521097******0454","Amount":1000000,"Ip":"
192.168.2.248"}

3.3 Order status Extended request

To obtain the current state of a registered order, send data with getOrderStatusExtended.do
method (GET or POST) to the corresponding URL. The order status is determined by the
value of the OrderStatus parameter. Note: The authCode field is deprecated.

Request Parameters:
Name Type Mandatory Description
userName AN..30 Yes Merchant login received during
registration.
password AN..30 Yes Merchant password received during
registration.
orderId ANS36 Yes Unique order number in the
APS Ecommerce Payment
Gateway.
language A2 No Language code in the ISO 639-1
format.
If unspecified, APS E-commerce
Payment Gateway uses the default
language from the merchant
settings. Error messages are
returned in this language.
Response Parameters:
There are many templates for this API, So kindly check with APS team about the response.

The OrderStatusExtended field may have the following values:

State Number Description

0 Order registered, but not paid.
1 Preauthorization amount was put on hold (for a two-phase payment).
2 Amount was deposited successfully.
3 Authorization has been reversed.
4 Transaction has been refunded.
5 Authorization has been initiated via the issuer’s ACS.
6 Authorization is declined.

Error codes (values of the ErrorCode field)

Value Description
0 No system error.
2 The order is declined because of an error in the payment credentials.
Access is denied.
5 The user must change the password.
orderId is empty.
6 Unregistered OrderId.
7 System error.

Request example for UAT (test environment)

POST /payment/rest/getOrderStatusExtended.do HTTP/1.1

Host: uat-proxy.aps.iq:5443
Content-Type: application/x-www-form-urlencoded

orderId=8d9364ce-916f-4f96-8f60-
4c3194e7cb1f&language=en&password=API_PASSWORD&userName=API_USERNAME

example for Production (LIVE environment)

POST /payment/rest/getOrderStatusExtended.do HTTP/1.1

Host: ecommerce.aps.iq:4443
Content-Type: application/x-www-form-urlencoded
orderId=8d9364ce-916f-4f96-8f60-
4c3194e7cb1f&language=en&password=API_PASSWORD&userName=API_USERNAME
Response example
{"errorCode":"0","errorMessage":"Success","orderNumber":"SALAH_30","orderStatus":6,"actionCode":15101
9,"actionCodeDescription":"Processing timeout. Please, try again
later.","amount":1000000,"currency":"368","date":1624165703963,"orderDescription":"Test","ip":"192.168.2.
248","attributes":[{"name":"mdOrder","value":"8d9364ce-916f-4f96-8f60-
4c3194e7cb1f"}],"cardAuthInfo":{"expiration":"202301","cardholderName":"SDSD","paymentSystem":"MASTE
RCARD","pan":"521097******0454"},"authDateTime":1624165703963,"terminalId":"00020019","paymentAm
ountInfo":{"paymentState":"DECLINED","approvedAmount":0,"depositedAmount":0,"refundedAmount":0},"b
ankInfo":{"bankCountryCode":"UNKNOWN","bankCountryName":"<Unknown>"},"chargeback":false,"feeAmou
nt":0}

3.4 Request for payments statistics for a period

The getLastOrdersForMerchants.do method is used to get the payment statistics for
a specified period. The method returns a list of order descriptions, each description
represents an extended order status (that can be received by executing the
getOrderStatusExtended.do request.

Request parameters
Name Type Manda- Description
tory

userName AN 1..30 Yes User’s login.

password AN 1..30 Yes User’s password.

language A2 No Language code in the ISO 639-1 format. If

unspecified, SmartVista E-commerce
Payment Gateway uses the default language
from the settings of the user used to
process the merchant’s payments.
Error messages are returned in this
language.

The system support one language with this

API.
EN: English

page N No When processing the request, a list is

formed that is broken down into pages (with
the number of records on each page equal
to size). A page with the number that was
specified in the page parameter is returned
in the response. The pages numbering
starts from 0. If the parameter is not
specified, a page with the number 0 is
returned.
 size N..3 Yes Number of elements on a page (the
maximum value = 200).

from Yes The date and time when the period of

collecting orders starts, in the format
YYYYMMDDHHmmss.
to Yes The date and time when the period of
collecting orders ends, in the format
YYYYMMDDHHmmss.
transactionStates[] A..9 Yes In this block, it is necessary to list the
required order statuses. Only orders in one
of the specified statuses are included in the
report.
If there are several values, they are
separated by commas. The available values
are: CREATED, APPROVED, DEPOSITED,
DECLINED, REVERSED, REFUNDED.
merchants[] ANS Yes List of logins of the merchant whose
transactions are included in the report. If
there are several values, they are separated
by commas.
Leave this field empty to get the list of
reports on all the available merchants (child
merchants and merchants specified in the
settings of the user).
searchByCreatedDate Boolean No The possible values are:
· true — a search for orders that have the
creation date that falls into the specified
period.
· false — a search for orders that have the
payment date that falls into the specified
period (thus, orders in the CREATED or
DECLINED status cannot be present in the
report).
The default value is false.

Response parameters

Name Type Manda- Description

tory

errorCode N 1..3 No Error code.

errorMessage AN No Description of the error in the language that

1..512 was sent in the language parameter of the
request.
orderStatuses[] Block that contains information about the orders
included in the report.
 totalCount N Yes Total number of elements in the report (on all
pages).
page N Yes Number of the current page (it is equal to the
page number passed in the request).

pageSize N..3 Yes Maximum number of records on a page (it is

equal to the page number passed in the
request).

Parameters in the orderStatuses block:

Name Type Manda- Description

tory

orderNumber AN Yes Number (identifier) of the order in the

1..32 merchant’s online store system. It is
unique for every store in the system and is
generated on the order registration.
orderStatus N..2 Yes Status of the order in the payment system.

actionCode N..3 Yes Response code.

actionCodeDescription AN..512 Yes Meaning of the response code.

amount N 1..19 Yes Payment amount in the minor

denomination of the currency.

currency N3 Yes ISO 4217 code of the payment currency. If it

is not specified, it is considered to be equal
to the default currency value.

date ANS Yes Order registration date.

orderDescription AN..512 No Order description passed on its

registration.
ip AN..20 No IP-address of the buyer. It is specified only
after a payment.

errorCode N 1..3 Yes Error code.

merchantOrderParam No Tag containing attributes that contain

s[] additional merchant parameters.

attributes[] Yes Attributes of the order in the payment

system (order number).
 cardAuthInfo[] No Tag containing the payment attributes.

p2pData[] No In the case of a card-to-card transfer, this

block contains the details about the source
and recipient cards.

bindingInfo[] No Tag containing information about the

binding with which the payment is
performed.
See the bindingInfo block parameters table
52 below.
authDateTime ANS No Authorization date and time.

terminalId AN..10 No Terminal ID.

authRefNum AN..24 No Reference number.

paymentAmountInfo[ No Tag containing information about the

] confirmation amount, debit amount, and
refund amount.

bankInfo[] No Tag containing information about the

issuing bank.

Parameters in the merchantOrderParams block:

Name Type Manda- Description

tory

name AN..20 Yes Name of the additional merchant parameter.

value AN..1024 Yes Value of the additional merchant parameter.

Parameters in the attributes block:

Name Type Manda- Description

tory

name AN7 Yes Attribute name is mdOrder.

value ANS36 Yes Attribute value is the order number in the

payment system (is unique within the system).
Parameters in the cardAuthInfo block:

Name Type Manda- Description

tory

pan N No Masked number of the card that has been

12...19 used for the payment. It is specified only for
paid orders.
expiration N6 No Card expiration date in the YYYYMM format. It
is specified only for paid orders.

cardholderName A..25 No Name of the cardholder.

This parameter is verified according to the
following criteria.
· Acceptable characters are: Latin letters, 0-
9, $, ), (, , . , a space
· Cardholder name must start with a letter
· Minimum length: one Latin letter
· Maximum length: 25 characters
· Null is valid
· Uppercase and lowercase are acceptable

authorizationRespons AN6 No Payments network authorization code. The

eId field has fixed length of six characters; it can
contain both numbers and letters.

secureAuthInfo[] No Tag containing information about secure

authentication.

The secureAuthInfo[] block parameters

Name Type Manda- Description

tory
 eci AN2 No Electronic Commerce Indicator.

cavv ANS..200 No Cardholder Authentication Verification Value.

xid ANS..80 No Electronic Commerce Transaction Identifier.

Parameters in the p2pData block:

Name Type Manda- Description

tory

debitPan N No Masked number of a card that is the source of

12...19 funds to transfer.

creditPan N No Masked number of a card that is the receiver of

12...19 funds.

Parameters in the bindingInfo block:

Name Type Manda- Description

tory

clientId AN No Identifier of the customer in the merchant’s

1..255 system. It is used to implement the binding
functional. It may be present, if the merchant
has the permissions to create and manage
bindings (the Merchant is allowed to use
bindings merchant option and other, see “Main
bindingId ANS..255 No Identifier of the binding created when paying
this order or created earlier and used to pay
for this order. It is present only if the merchant
has the permission to create bindings.

Parameters in the paymentAmountInfo block:

Name Type Manda- Description

tory

paymentState N..9 No Payment status.

approvedAmount N 1..19 No Amount confirmed to be debited.

 depositedAmount N 1..19 No Amount confirmed debited from the card.

refundedAmount N 1..19 No The refund amount.

Parameters in the bankInfo block:

Name Type Manda- Description

tory

bankName AN..200 No Name of the issuing bank.

bankCountryCode AN..4 No Code of the issuing bank country.

bankCountryName AN..160 No Name of the country of the issuing bank passed

in the language parameter of the request or in
the language of the user who has called the
method if the language has not been specified
in the request.

The orderStatus field can have the following values:

Value Description

0 The order has been registered but not paid.

1 The preauthorized amount has been put on hold (for two-phase payments).

2 Full authorization of the order amount has been performed.

3 Authorization is canceled.

4 A refund operation has been processed for the transaction.

5 Authorization through ACS of the issuing bank has been initiated.

6 Authorization is declined.

Error codes (values of the errorCode field)

Value Description
 0 The request has been processed without system errors.

5 One of the mandatory fields is not filled in.

5 Incorrect format of the transactionStates parameter.

5 Access is denied.

7 System error.

10 Value of the size parameter exceeds the maximum allowed value.

10 Insufficient permissions to view transactions for the specified merchant.

 Add example

Request example for UAT (test environment)

POST /payment/rest/getLastOrdersForMerchants.do HTTP/1.1

Host: uat-proxy.aps.iq:5443
Content-Type: application/x-www-form-urlencoded

userName=USER_NAME&password=PASSWORD&page=0&size=100&from=201808091
60000&to=20210909160000&transactionStates=DEPOSITED,DECLINED&merchants=M
ERCHANT_NAME&searchByCreatedDate=false

example for Production (LIVE environment)

POST /payment/rest/getLastOrdersForMerchants.do HTTP/1.1

Host: ecommerce.aps.iq:4443
Content-Type: application/x-www-form-urlencoded

userName=USER_NAME&password=PASSWORD&page=0&size=100&from=201808091
60000&to=20210909160000&transactionStates=DEPOSITED,DECLINED&merchants=M
ERCHANT_NAME&searchByCreatedDate=false

Response example
As json
This flow shows the merchant the request processing.