Authorization – Completion Interface

This transaction process involves an Authorization stage, blocking funds upon successful approval. Subsequently, the Sales Completion stage occurs after goods/services delivery, triggering financial completion through the gateway. A "Reversal" option exists for order cancellations or unfulfillment, with the gateway facilitating fund transfer back to the cardholder account from the merchant account.

Transaction Flow Scenario

1. The flow of this type of transactions is similar to retail transaction flow, however, the main difference is related to the delivery of the goods and services, and the movement of funds. The Authorization – completion flow is related to the case where goods or services are delivered at later stages, and the amount at the time of delivery completion may differ from the original transaction. One of the clearest examples is the hotel bookings where amount at checkout may differ from amount at authorization stage.

2. The flow is split into Authorization stage where same process of retail transaction is followed BUT with TRType must be equal to “0”. if authorization is successful, the amount will be blocked in cardholder account. The merchant should send an email invoice message to the cardholder with order information and delivery time if applicable.

3. The second stage is when the merchant has delivered the goods and services to the cardholder, the merchant system sends a "Sales completion" transaction directly to the e-Commerce Gateway URL using an internal reference number to refer to the authorization transaction with its corresponding card information. The transaction request should include a message authentication code field for verifying the message's identity.

4. Gateway validates the incoming message and requests financial completion of the transaction from the Way4 card system. At this point, 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.

5. If the merchant is unable to fulfill the cardholder order or if the cardholder cancels the order at a stage allowed by the merchant, the merchant system must send a "Reversal" message to cancel the pending or completed transaction. The merchant system sends this message directly to the gateway URL. The transaction request should include a message authentication code field for verifying the message's identity.

6. Gateway validates the incoming message and requests a reversal of the pending or completed transaction from the Way4 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.

Authorization Request Format

The same fields of the request body for retail transaction should be sent. The field set and format are the same as for the Retail financial request. The field TRTYPE must equals to “0”.

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 "0" (Authorization).
email	EMAIL	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

Authorization Response Format

The same response and flow of Retail financial Response Format will be followed BUT with TRType “0”

Sales Completion Request Format

This transaction must be sent by the merchant system when goods and/or services are delivered to the cardholder. The card system will complete the financial transaction and transfer funds to the merchant account.

All fields are provided by the merchant system and the cardholder does not participate in this transaction.

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
AMOUNT	1-12	Order total amount in float format with decimal point separator
CURRENCY	03	Order currency: 3-character currency code USE IQD for Iraqi dinnars
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.
RRN	12	Retrieval reference number from authorization response.
INT_REF	1-128	Internal reference number from authorization response
DESC	1-50	Order description
TRTYPE	02	Must be equal to "1" (retail financial).
EMAIL	80	Email address for notification. If this field is present Gateway may send transaction results notification to specified e-mail address.
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	1-64	Merchant nonce. Must be filled with 8-32 unpredictable random bytes in hexadecimal format. Must be present if MAC is used.
BACKREF	1-250	Merchant URL for posting authorization result.
P_SIGN	1-256	Merchant MAC in hexadecimal form. (Required)
FOREIGN_RETAILER_IND	1	Foreign Retailer Indicator