Retail Transactions Interface
The retail transaction process involves secure payment methods, where card details are not stored on the merchant server. After selecting goods and choosing "Pay by card", the system redirects to card information. The e-Commerce Gateway validates and authorizes the transaction, sending a response to the merchant with limited card details. Optional email notifications may be sent, and in case of order cancellation, a "Reversal" message is initiated, potentially leading to fund transfers.
Transaction Flow Scenario
- After selecting goods and services, the cardholder presses "Buy" or equivalent button and proceeds to a page where they can enter or modify delivery information and the payment method. Several payment methods may be offered, such as "Pay by card" or similar options. These options should not include card number, expiry date, CVC2 or any other card related sensitive information. Because of security risks involved, the merchant system should avoid requesting and storing card information on the merchant server.
- If the cardholder selects the "Pay by card" option, the merchant system must prepare authorization request fields and redirect the cardholder to an "Enter card information" page on e-Commerce Gateway URL. Alternatively, the merchant system itself may present this page directly to cardholder. In this case, posting URL for this page form must be set to eCommerce Gateway URL. This form shall include all card input fields and visible/hidden fields relating to the order and merchant as required by the authorization request format.
- After receiving the filled-in form, e-Commerce Gateway validates request information including the message authentication code. If the request fails, the validation gateway returns an error response to the merchant system.
- Gateway sends an authorization request to the AlQaseh card system. Upon authorization, reception gateway prepares and sends a transaction response to the merchant system. The transaction response contains no card information or contains the card number in blind form only. Gateway sends response messages to the merchant system using cardholder redirect. Redirect may be performed automatically or as an intermediate form to be posted on the merchant server. Response messages may also contain a message authentication code in order to verify the message's identity. If authorization is successful, the response message will contain the “Internal Reference Number” field, to be used by the merchant system so it can complete or reverse the obtained authorization without the card information.
- Additionally, the e-commerce gateway may send (if requested by the configuration) an email notification to the merchant system with the same information as the online transaction response message. This is done in case of possible transport problems while delivering a redirected message. The email address for transaction notifications can be configured in e-Commerce gateway.
- After receiving the online transaction response or its email notification, the merchant system starts delivery of ordered goods and/or services to the cardholder and the transaction amount is debited from the cardholder account and the merchant account is credited with the appropriate amount. Gateway sends a response to the merchant system within the response document.
- If the merchant is unable to fulfill the cardholder order once requested, or if the merchant allows the cardholder to cancel the order at any stage of order, the merchant system must send a "Reversal" message to cancel the pending or completed transaction.
- The merchant system sends “Reversal” directly to the gateway URL. The transaction request should include a message authentication code field for verifying the message's identity.
- Gateway validates the incoming message and requests a “reversal” of the pending or completed transaction from AlQaseh card system. This may involve transferring funds from the merchant account back to the cardholder account. Gateway sends a reply to the merchant system within the response document.
Retail Financial request Format
The following set of fields will be posted to e-Commerce Gateway URL through the HTTP POST method to prepare the request. The set is divided into two subsets: visible fields generated by the merchant system and hidden fields generated by the merchant system. E-Commerce Gateway prepares the payment request and returns the same request fields -- with new field in name request_token, the request and response fields listed in the next tables. After preparing the request the merchant system should redirect or open a web page to complete the processing, at this point the consumer will enter his card data in Alqaseh web page, when retail payment success the web page will be redirected for merchant system and sent the transaction data to the merchant system using BACKREF value that provided in preparing request. To initiate a request with Alqaseh, it is imperative to furnish the designated merchant token, bestowed by Alqaseh. This token should be meticulously incorporated into the request header under the nomenclature "X-API-Key."
Test Envirment Details
- Test Credentials
| Name | Value | Description |
|---|---|---|
| Merchant ID | EGW TEST | |
| X-API-Key | 4c2db6a1c9d841809c0fcdbf1fd0aeb8 | Test Merchant credentials |
| Card PAN | 5341432908085972 | Card PAN, 16 digits |
| Card CVV2 | 972 | |
| Card EXP | 11-2026 | Card Expiration date |
- Test Environment URL
POST https://ac.alqaseh.com:9900/api/payment/prepare
- Production Environment URL
POST https://acq.alqaseh.com:9900/api/payment/prepare
| JSON Key | FORM Key | Size | Description |
|---|---|---|---|
| amount | AMOUNT | 1-12 | Order total amount in float format with decimal point separator |
| currency | CURRENCY | 03 | Order currency: 3-character currency code USE IQD for Iraqi dinnars |
| order | ORDER | 6-32 | Merchant order ID, numeric. Last 6 digits used as a system trace audit number, which must be unique within a day for the terminal id. |
| desc | DESC | 1-50 | Order description |
| trtype | TRTYPE | 02 | Must be equal to "1" (retail financial). |
| 80 | Email address for notification. If this field is present Gateway may send transaction results notification to specified e-mail address. | ||
| timestamp | TIMESTAMP | 14 | Merchant transaction timestamp in GMT: YYYYMMDDHHMMSS. Timestamp difference between merchant server and eGateway server must not exceed 1 hour, otherwise eGateway will reject this transaction. |
| nonce | NONCE | 1-64 | Merchant nonce. Must be filled with 8-32 unpredictable random bytes in hexadecimal format. Must be present if MAC is used. |
| back_ref | BACKREF | 1-250 | Merchant URL for posting authorization result. |
| p_sign | P_SIGN | 1-256 | Merchant MAC in hexadecimal form. (Required) |
| foreign_retailer_ind | FOREIGN_RETAILER_IND | 1 | Foreign Retailer Indicator |
Retail financial Response Format
The same fields of the request body will return in response but there is additional field called request_token refers to the token of this operation that merchant system should use it in WebView to complete the transaction.
| JSON Key | FORM Key | Size | Description |
|---|---|---|---|
| request_token | REQTKN | >10 | Random key generated by gateway for identify the order request |
The next step Alqaseh Gateway should display an HTML page for consumer to enter his card data, we have to use the request_token that returned from the above response to complete the payment. The request below will show you this HTML page.
Test Environment URL
GET https://ac.alqaseh.com:9900/pay/:request_token
Production Environment URL
GET https://acq.alqaseh.com:9900/pay/:request_token
Once the consumer inputs their card details, and upon successful verification, the HTML will redirect the consumer to the BACKREF value provided in the initial preparation request. Alqaseh card system will then transmit transaction data to the merchant system using a POST request with the provided BACKREF value, formatted in FORM. The table below outlines the parameters within the request body.
| FORM Key | Size | Description |
|---|---|---|
| TERMINAL | 8 | Echo from the request |
| TRTYPE | 2 | Must equal “1” |
| ORDER | 6-32 | Echo from the request |
| AMOUNT | 12 | Amount authorized. Usually, will be equal to original amount plus acquirer’s fee if applicable. |
| CURRENCY | 3 | Echo from the request |
| ACTION | 1 | EGateway action code: |
| RC | 02 | Transaction response code (ISO-8583 Field 39) |
| APPROVAL | 06 | Client bank’s approval code (ISO-8583 Field 38). Can be empty if not provided by card management system. |
| RRN | 12 | Merchant bank’s retrieval reference number (ISO-8583 Field 37). |
| INT_REF | 1-128 | E-Commerce gateway internal reference number |
| TIMESTAMP | 14 | E-Commerce gateway timestamp in GMT: YYYYMMDDHHMMSS |
| NONCE | 1-64 | E-Commerce gateway nonce value. Will be filled with 8-32 unpredictable random bytes in hexadecimal format. Will be present if MAC is used. |
| P_SIGN | 1-256 | E-Commerce gateway MAC (Message Authentication Code) in hexadecimal form. Will be present if MAC is used. |
Reversal Request Format
The reversal transaction request must be sent by the merchant system to e-Commerce Gateway in order to reverse authorized or completed transactions in case where merchant fails to deliver the order. The request format and transmission method are as of below:
Test Environment URL
POST https://ac.alqaseh.com:5443/cgi-bin/cgi_link
Production Environment URL
POST https://acq.alqaseh.com:5443/cgi-bin/cgi_link
| FORM Key | Size | Description |
|---|---|---|
| TERMINAL | 8 | Echo from the request |
| TRTYPE | 2 | Must be equal to “24” (Reversal advice) |
| ORDER | 6-32 | Echo from the request |
| AMOUNT | 12 | Exactly the authorized Amount (in the original transaction ). Usually, will be equal to original amount plus acquirer’s fee if applicable. |
| RRN | 12 | Retrieval reference number from authorization response. |
| INT_REF | 1-128 | Internal reference number from authorization response. |
| CURRENCY | 3 | Echo from the request |
| TIMESTAMP | 14 | Merchant transaction timestamp in GMT: YYYYMMDDHHMMSS. Timestamp difference between Internet shop and eGateway must not exceed 1 hour otherwise eGateway will reject this transaction. |
| NONCE | 1-64 | E-Commerce gateway nonce value. Will be filled with 8-32 unpredictable random bytes in hexadecimal format. Will be present if MAC is used. |
| P_SIGN | 1-256 | E-Commerce gateway MAC (Message Authentication Code) in hexadecimal form. Will be present if MAC is used. (Required) |
All fields are provided by the merchant system and the cardholder does not participate in this transaction.
Reversal Response Format
Gateway processes a reversal request and returns the result fields to the merchant system within a response document. Response fields are formatted in URL-encoded form. The field set and format are the same as for the Retail financial response. The field TRTYPE must equals to “24”.
| FORM Key | Size | Description |
|---|---|---|
| TERMINAL | 8 | Echo from the request |
| TRTYPE | 2 | Must equal “24” |
| ORDER | 6-32 | Echo from the request |
| AMOUNT | 12 | Amount authorized. Usually, will be equal to original amount plus acquirer’s fee if applicable. |
| CURRENCY | 3 | Echo from the request |
| ACTION | 1 | EGateway action code: 0. Transaction successfully completed 4. Duplicate transaction detected 5. Transaction declined 6. Transaction processing error |
| RC | 02 | Transaction response code (ISO-8583 Field 39) |
| APPROVAL | 06 | Client bank’s approval code (ISO-8583 Field 38). Can be empty if not provided by card management system. |
| RRN | 12 | Merchant bank’s retrieval reference number (ISO-8583 Field 37). |
| INT_REF | 1-128 | E-Commerce gateway internal reference number |
| TIMESTAMP | 14 | E-Commerce gateway timestamp in GMT: YYYYMMDDHHMMSS |
| NONCE | 1-64 | E-Commerce gateway nonce value. Will be filled with 8-32 unpredictable random bytes in hexadecimal format. Will be present if MAC is used. |
| P_SIGN | 1-256 | E-Commerce gateway MAC (Message Authentication Code) in hexadecimal form. Will be present if MAC is used. (Required) |