S2S APM (NAPS only)

Version: 1.0.0
Released: 2022/12/10

Introduction

This document describes integration procedures and VIRTUAL PAYMENT GATEWAY protocol usage for e-commerce merchants. Merchants using only NAPS (Local Qatari Debit Cards) can use this integration method.

VIRTUAL PAYMENT GATEWAY protocol implements acquiring payments (purchases) with using specific API interaction.

Integration Process

Definitions

{{API_HOST}} = https://api.tesspayments.com/post-va

Client Registration

Before you get an account to access Payment Platform, you must provide the following data to the Payment Platform administrator.

Data	Description
Callback URL	URL which will be receiving the notifications of the processing results of your request to Payment Platform
Contact e-mail	Client`s contact email
IP List	List of your IP addresses, from which requests to Payment Platform will be sent.

With all Payment Platform POST requests at Callback URL the Client must return the string "OK" if he/she successfully received data or return "ERROR".

You should get the following information from administrator to begin working with the Payment Platform.

Parameter	Description
CLIENT_KEY	Unique key to identify the account in Payment Platform (used as request parameter). In the administration platform this parameter corresponds to the "Merchant key" field
PASSWORD	Password for Client authentication in Payment Platform (used for calculating hash parameter). In the administration platform this parameter corresponds to the "Password" field
PAYMENT_URL	URL to request the Payment

Payment Platform Interaction

For the transaction you must send the server to server HTTPS POST request to the Payment Platform URL (PAYMENT_URL). In response Payment Platform will return the JSON (http://json.org/)) encoded string.

List of possible actions in Payment Platform

When you make request to Payment Platform, you need to specify action that needs to be done. Possible actions are:

Action	Description
SALE	Creates SALE transaction
CREDITVOID	Creates REFUND transaction
GET_TRANS_STATUS	Gets status of transaction in Payment Platform

List of possible transaction results and statuses

Result – value that system returns on request. Possible results are:

Result	Description
SUCCESS	Action was successfully completed in Payment Platform
DECLINED	Result of unsuccessful action in Payment Platform
REDIRECT	Additional action required from requester
ACCEPTED	Action was accepted by Payment Platform, but will be completed later
ERROR	Request has errors and was not validated by Payment Platform

Status – actual status of transaction in Payment Platform. Possible statuses are:

Status	Description
PREPARE	Status is undetermined, final status will be sent in callback
REDIRECT	The transaction awaits SALE
SETTLED	Successful transaction
REFUND	Transaction for which refund was made
DECLINED	Not successful transaction

Transactions requests

SALE request

Use SALE request to create a payment in the Payment Platform.

If you want to send a payment for the specific sub-account (channel), you need to use channel_id that specified in your Payment Platform account settings.

This request is sent by POST in the background (e.g. through PHP CURL).

Request Parameters

Parameter	Description	Limitations	Required
`action`	Action to perform (=SALE)	= SALE	+
`client_key`	Unique client key (CLIENT_KEY)		+
`channel_id`	Payment channel (Sub-account)	String up to 16 characters	-
`brand`	Brand through which the transaction is performed	String up to 36 characters(Appendix B)	+
`order_id`	Transaction ID in the Clients system	String up to 255 characters	+
`order_amount`	The amount of the transaction	Numbers in the format XXXX.XX Pay attention that amount format depends on currency exponent. If exponent = 0, then amount is integer (without decimals). It used for currencies: CLP, VND, ISK, UGX, KRW, JPY. If exponent = 3, then format: XXXX.XXX (with 3 decimals). It used for currencies: BHD, JOD, KWD, OMR, TND.	+
`order_currency`	Currency	3-letter code	+
`order_description`	Description of the transaction (product name)	String up to 1024 characters [a-zA-Z0-9,]	+
`payer_first_name`	Customer's name	String up to 32 characters	-
`payer_last_name`	Customer's surname	String up to 32 characters	-
`payer_address`	Customer's address	String up to 255 characters	-
`payer_country`	Customer's country	2-letter code	-
`payer_state`	Customer's state	String up to 32 characters	-
`payer_city`	Customer's city	String up to 32 characters	-
`payer_zip`	ZIP-code of the Customer	String up to 32 characters	-
`payer_email`	Customer's email	String up to 256 characters	-
`payer_phone`	Customer's phone	String up to 32 characters	-
`payer_birth_date`	Customer's birthday	Date format is "YYYY-MM-DD"	-
`payer_ip`	IP-address of the Customer	XXX.XXX.XXX.XXX	+
`return_url`	URL to which Customer should be returned after operation in third-party system	String up to 1024 characters	+
`identifier`	Extra parameter for transaction. It could be token, account information, additional descriptor etc. Value should be unique.	String up to 255 characters	+
`hash`	Special signature to validate your request to Payment Platform	See Appendix A, Sale signature.	+

Response Parameters

You will get JSON encoded string with transaction result.

Successful sale response

Parameter	Description
`action`	SALE
`result`	SUCCESS
`status`	SETTLED
`order_id`	Transaction ID in the Client's system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Transaction date in the Payment Platform
`descriptor`	This is a string which the owner of the credit card will see in the statement from the bank. In most cases, this is the Customers support web-site.

Unsuccessful sale response

Parameter	Description
`action`	SALE
`result`	DECLINED
`status`	DECLINED
`order_id`	Transaction ID in the Client's system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Transaction date in the Payment Platform
`decline_reason`	The reason why the transaction was declined

Redirect transaction response

Parameter	Description
`action`	SALE
`result`	REDIRECT
`status`	REDIRECT
`order_id`	Transaction ID in the Client's system
`trans_id`	Transaction ID in the Payment Platform
`trans_date`	Transaction date in the Payment Platform
`redirect_url`	URL to which the Client should redirect the Customer
`redirect_params`	Array of specific parameters
`redirect_method`	The method of transferring parameters (POST/GET)

Callback parameters

Successful sale response

Parameter	Description
`action`	SALE
`result`	SUCCESS
`status`	SETTLED
`order_id`	Transaction ID in the Client's system
`trans_id`	Transaction ID in the Client's system
`trans_date`	Transaction date in the Payment Platform
`descriptor`	This is a string which the owner of the credit card will see in the statement from the bank.In most cases, this is the Customers support web-site
`hash`	Special signature to validate callback. See Appendix A, Callback signature.

Unsuccessful sale response

Parameter	Description
`action`	SALE
`result`	DECLINED
`status`	DECLINED
`order_id`	Transaction ID in the Client's system
`trans_id`	Transaction ID in the Client's system
`trans_date`	Transaction date in the Payment Platform
`descriptor`	Transaction date in the Payment Platform
`decline_reason`	Description of the cancellation of the transaction
`hash`	Special signature to validate callback. See Appendix A, Callback signature.

Redirect transaction response

Parameter	Description
`action`	SALE
`result`	REDIRECT
`status`	REDIRECT
`order_id`	Transaction ID in the Client's system
`trans_id`	Transaction ID in the Client's system
`trans_date`	Transaction date in the Payment Platform
`redirect_url`	URL to which the Client should redirect the Customer
`redirect_params`	Array parameters
`redirect_method`	The method of transferring parameters (POST/GET)
`hash`	Special signature to validate callback. See Appendix A, Callback signature.

CREDITVOID request

CREDITVOID request is used to complete REFUND transactions.

REFUND transaction is used to return funds to account, previously submitted by SALE transactions.

This request is sent by POST in the background (e.g. through PHP CURL).

Request parameters

Parameter	Description	Limitations	Required
`action`	Action to perform	= CREDITVOID	+
`client_key`	Unique client key (CLIENT_KEY)		+
`trans_id`	Transaction ID in the Payment Platform	String up to 255 characters	+
`amount`	The amount for partial refund. Several partial refunds allowed.	Numbers in the format XXXX.XX Pay attention that amount format depends on currency exponent. If exponent = 0, then amount is integer (without decimals). It used for currencies: CLP, VND, ISK, UGX, KRW, JPY. If exponent = 3, then format: XXXX.XXX (with 3 decimals). It used for currencies: BHD, JOD, KWD, OMR, TND.	-
`hash`	Special signature to validate your request to Payment Platform	See Appendix A, Creditvoid signature.	+

Response parameters

Parameter	Description
`action`	CREDITVOID
`result`	ACCEPTED
`order_id`	Transaction ID in the Client's system
`trans_id`	Transaction ID in the Payment Platform

Callback parameters

Successful refund response

Parameter	Description
`action`	CREDITVOID
`result`	SUCCESS
`status`	REFUND (full refund) / SETTLED (partial refund)
`order_id`	Transaction ID in the Client system
`trans_id`	Transaction ID in the Payment Platform
`creditvoid_date`	Date of the refund/reversal
`amount`	Amount of refund
`hash`	Special signature, used to validate callback. See Appendix A, Creditvoid signature.

Unsuccessful refund response

Parameter	Description
`action`	CREDITVOID
`result`	DECLINED
`order_id`	Transaction ID in the Client system
`trans_id`	Transaction ID in the Payment Platform
`decline_reason`	Description of the cancellation of the transaction
`hash`	Special signature, used to validate callback. See Appendix A, Creditvoid signature.

GET_TRANS_STATUS request

Gets order status from Payment Platform. This request is sent by POST in the background (e.g., through PHP CURL).

Request parameters

Parameter	Description	Values	Required
`action`	GET_TRANS_STATUS	GET_TRANS_STATUS	+
`client_key`	Unique client key (CLIENT_KEY)		+
`trans_id`	Transaction ID in the Payment Platform	String up to 255 characters	+
`hash`	Special signature to validate your request to Payment Platform	See Appendix A, GET_TRANS_STATUS signature	+

Response parameters

Parameter	Description
`action`	GET_TRANS_STATUS
`result`	SUCCESS
`status`	DECLINED/SETTLED
`order_id`	Order ID in the Client’s system
`trans_id`	Transaction ID in the Payment Platform
`decline_reason`	Reason of transaction decline. It shows for the transactions with the “DECLINED” status

Errors

In case error you get synchronous response from Payment Platform:

Parameter	Description
`result`	ERROR
`error_message`	Error message

Appendix A

Hash is signature rule used either to validate your requests to payment platform or to validate callback from payment platform to your system. It must be md5 encoded string calculated by rules below:

Sale signature

Hash is calculated by the formula:

md5(strtoupper(strrev(identifier + order_id + order_amount + order_currency + PASSWORD)));

Creditvoid signature

Hash is calculated by the formula:

_md5(strtoupper(strrev(trans_id + PASSWORD)));

GET_TRANS_STATUS signature

$hash = md5(strtoupper(strrev($trans_id)) . $ PASSWORD);

Callback signature

Hash is calculated by the formula:

array_walk_recursive($params, static function (&$value) {
    $value = strrev($value);
});
$params['hash'] = md5(strtoupper(convert($params) . PASSWORD));
function convert($params)
{
    foreach ($params as &$value) {
        if (is_array($value)) {
            $value = $this->convert($value);
        }
    }
    ksort($params);
    return implode($params);
}

Introduction​

Integration Process​

Definitions​

Client Registration​

Payment Platform Interaction​

List of possible actions in Payment Platform​

List of possible transaction results and statuses​

Transactions requests

SALE request​

Request Parameters​

Response Parameters​

Callback parameters​

CREDITVOID request​

Request parameters​

Response parameters​

Callback parameters​

GET_TRANS_STATUS request​

Request parameters​

Response parameters​

Errors​

Appendix A​

Sale signature​

Creditvoid signature​

GET_TRANS_STATUS signature​

Callback signature​

Introduction

Integration Process

Definitions

Client Registration

Payment Platform Interaction

List of possible actions in Payment Platform

List of possible transaction results and statuses

SALE request

Request Parameters

Response Parameters

Callback parameters

CREDITVOID request

Request parameters

Response parameters

Callback parameters

GET_TRANS_STATUS request

Request parameters

Response parameters

Errors

Appendix A

Sale signature

Creditvoid signature

GET_TRANS_STATUS signature

Callback signature