3D Payment

3D Payment Service Request Model;

Method	API URL	Parameters
POST	https://posservice.esnekpos.com/api/pay/EYV3DPay	JSON File

3D Payment Service Transaction Flow;

In order to perform a successful collection using the 3D payment model, you must complete your integration by following the procedures described below.

Step 1:

The merchant sends the payment request to the Esnekpos 3D payment service using the above-mentioned request model together with the user, card, basket, payment amount and installment information and its own web address (BACK_URL) where the payment result is requested. and initiates the payment process.

All parameters must be fully protected in order to be able to operate in a secure and complex manner and to enable fraud.

The parameters to be sent to the service are as follows;

3D Payment Service Request Message Parameters

Parameters	Type	Compulsory	Description
MERCHANT	string	Yes	It is a unique credential created specifically for the member business.
MERCHANT_KEY	string	Yes	It is the key information created specifically for the member business.
BACK_URL	string	Yes	It is the address information to which the operation result response will be returned by the system. Transaction response will be read from this address by the member business. The result of the process is sent as a form post.
PRICES_CURRENCY	string	Yes	The currency in which the payment will be made. Currently, only “TRY, USD, EUR, GBP” can be sent.
ORDER_REF_NUMBER	string	Yes	It is the reference number information to be given by the member workplace. Payment transactions can be tracked with this reference number. A maximum of 24 characters can be used.
ORDER_AMOUNT	string	Yes	It is the transaction amount information of the payment transaction.
CC_NUMBER	string	Yes	It is the 16-digit card number information of the card on which the payment will be made.
EXP_MONTH	string	Yes	It is the month information of the 2-digit expiry date of the card on which the payment will be made.
EXP_YEAR	string	Yes	It is the 4-digit expiry date and year information of the card on which the payment will be made.
CC_CVV	string	Yes	It is the 3-digit security code information on the back of the card where the payment will be made.
CC_OWNER	string	Yes	It is the name and surname information of the card holder to whom the payment will be made.
INSTALLMENT_NUMBER	string	Yes	It is the information of the number of installments requested for the payment process. “1” information should be sent for single shot transactions.
FIRST_NAME	string	Yes	It is the name of the users (customer) who performed the transaction.
LAST_NAME	string	Yes	It is the surname of the user (customer) who performed the transaction.
MAIL	string	Yes	It is the e-mail information of the user (customer) performing the transaction.
PHONE	string	Yes	It is the phone information of the user (customer) performing the transaction.
CITY	string	Yes	It is the city information of the user (customer) performing the transaction.
STATE	string	Yes	It is the district information of the user (customer) performing the transaction.
ADDRESS	string	Yes	It is the address information of the user (customer) performing the transaction.
CLIENT_IP	string	Yes	It is the IP address information of the user (customer) performing the transaction.

Product

Parameters	Type	Compulsory	Description
PRODUCT_ID	string	Yes	It is the ID information given to the product by the member merchant.
PRODUCT_NAME	string	Yes	The name of the product.
PRODUCT_CATEGORY	string	Yes	It is the category information of the product.
PRODUCT_DESCRIPTION	string	Yes	It is the description information of the product.
PRODUCT_AMOUNT	string	Yes	It is the description information of the product.

Here is a sample JSON file to send to the service;

                                            
{
     "Config" :  {
         "MERCHANT" : "TEST1234",
         "MERCHANT_KEY" : "4oK26hK8MOXrIV1bzTRVPA==",
         "BACK_URL" : "The url address where the result of the transaction will be returned to the merchant",
         "PRICES_CURRENCY" : "TRY",
         "ORDER_REF_NUMBER" : "RFN0001",
         "ORDER_AMOUNT" : "150"
     },
     "CreditCard" : {
         "CC_NUMBER" : "4159562885391991",
         "EXP_MONTH" : "12",
         "EXP_YEAR" : "2023",
         "CC_CVV" : "000",
         "CC_OWNER" : "TEST USER",
         "INSTALLMENT_NUMBER" : "1"
     },
     "Customer" : {
         "FIRST_NAME" : "Firstname",
         "LAST_NAME" : "Lastname",
         "MAIL" : "[email protected]",
         "PHONE" : "05435434343",
         "CITY" : "İstanbul",
         "STATE" : "Kağıthane",
         "ADDRESS" : "Merkez Mahallesi, Ayazma Cd. No:37/91 Papirus Plaza Kat:5, 34406 Kağıthane / İSTANBUL",
         "CLIENT_IP" : "123.44.66.38"
     },
     "Product" : [
         {
             "PRODUCT_ID" : "1",
             "PRODUCT_NAME" : "Product Name 1",
             "PRODUCT_CATEGORY" : "Electronic",
             "PRODUCT_DESCRIPTION" : "Product Description",
             "PRODUCT_AMOUNT" : "80"
         },
         {
             "PRODUCT_ID" : "2",
             "PRODUCT_NAME" : "Product Name 1",
             "PRODUCT_CATEGORY" : "Home Textiles",
             "PRODUCT_DESCRIPTION" : "Product Description",
             "PRODUCT_AMOUNT" : "70"
         }
     ]
}
                                        

Step 2:

Esnekpos evaluates the information and sends the reply message to the member business. (There is URL_3DS field in the reply message.)

The parameters of the reply message sent from the service after the transaction are as follows;

3D Payment Service Reply Message Parameters

Parameters	Type	Compulsory	Description
ORDER_REF_NUMBER	string	Yes	It is the reference number information of the tables given by the member merchant payments in their requests.
STATUS	string	Yes	The result of the payment transaction is the status information.
RETURN_CODE	string	Yes	The status of the payment process is the code information.
RETURN_MESSAGE	string	Yes	The status message is the result of the payment process.
RETURN_MESSAGE_TR	string	Yes	It is the Turkish explanation information for the status message as a result of the payment transaction.
ERROR_CODE	string	Yes	Error code information as a result of unsuccessful payment transaction. Bank error codes are also returned within this parameter.
DATE	string	Yes	It is the transaction date information for the payment transaction.
URL_3DS	string	Yes	3D Verification Page URL Address to which the merchant will direct the user
REFNO	string	Yes	The reference number information given by the Esnekpos system for the payment transaction
HASH	string	Yes	Hash information of the payment transaction generated by the Esnekpos system
CUSTOMER_NAME	string	Yes	It is the name and surname of the user (customer) performing the transaction.
CUSTOMER_MAIL	string	Yes	It is the e-mail information of the user (customer) performing the transaction.
CUSTOMER_PHONE	string	Yes	It is the phone information of the user (customer) performing the transaction.
CUSTOMER_ADDRESS	string	Yes	It is the address information of the user (customer) performing the transaction.
CUSTOMER_CC_NUMBER	string	Yes	It is the 16-digit card number information of the card on which the payment will be made. Card information is shared in encrypted form.
CUSTOMER_CC_NAME	string	Yes	It is the name and surname information of the card holder to whom the payment will be made.
IS_NOT_3D_PAYMENT	boolean	Yes	It is the information of whether the payment process takes place in 3D.
VIRTUAL_POS_VALUES	string	Yes	It is the virtualpos description information of the payment transaction.
RETURN_MESSAGE_3D	string	Yes	It is the reply message information of the 3D payment transaction received from the bank.
BANK_AUTH_CODE	string	Yes	It is the provision information of the 3D payment transaction received from the bank.

                                            
{
     "ORDER_REF_NUMBER": "RFN0001",
     "STATUS": "SUCCESS",
     "RETURN_CODE": "0",
     "RETURN_MESSAGE": "SUCCESS",
     "RETURN_MESSAGE_TR": null,
     "ERROR_CODE": null,
     "DATE": "27.07.2020 16:07:08",
     "URL_3DS": "http://posservicetest.esnekpos.com/api/pay/3DSecurity/order/12d2cd918afd2413116d25c2470d6d24924b44e9c440c18aed32922eddff6c40",
     "REFNO": "150840",
     "HASH": "12d2cd918afd2413116d25c2470d6d24924b44e9c440c18aed32922eddff6c40",
     "COMMISSION_RATE": "1,490",
     "CUSTOMER_NAME": "Firstname Lastname",
     "CUSTOMER_MAIL": "[email protected]",
     "CUSTOMER_PHONE": "05435434343",
     "CUSTOMER_ADDRESS": "Merkez Mahallesi, Ayazma Cd. No:37/91 Papirus Plaza Kat:5, 34406 Kağıthane / İSTANBUL",
     "CUSTOMER_CC_NUMBER": "415956******1991",
     "CUSTOMER_CC_NAME": null,
     "IS_NOT_3D_PAYMENT": false,
     "VIRTUAL_POS_VALUES": null,
     "RETURN_MESSAGE_3D": null,
     "BANK_AUTH_CODE": ""
}
                                        

In the 3D Payment transaction response message, the value of the STATUS parameter is SUCCESS and the RETURN_CODE parameter is 0, indicating that the 3D Payment transaction has been accepted. In the next step, 3D verification will be done from the user to be paid.

Step 3:

If the payment is accepted by evaluating the answer received, the merchant directs the customer to the URL_3DS address given by Esnekpos.

Step 4:

Esnekpos finalizes the 3D verification process and reports the result of the payment to the BACK_URL address that the member merchant reported in step 1, with the FORM POST method.

<html xmlns=\"http://www.w3.org/1999/xhtml\" >
    <head><meta http-equiv=\"Content-Type\" content=\"text/html;charset=iso-8859-9\" /></head>
    <body onload='document.forms[0].submit()'>
        <form action='" + payment.DEALER_RESPONSE_URL + "' method='post'>
            <input type='hidden' name='DATE' value='{0}'>
            <input type='hidden' name='HASH' value='{0}'>
            <input type='hidden' name='ORDER_REF_NUMBER' value='{0}'>
            <input type='hidden' name='REFNO' value='{0}'>
            <input type='hidden' name='RETURN_CODE' value='{0}'>
            <input type='hidden' name='RETURN_MESSAGE' value='{0}'>
            <input type='hidden' name='RETURN_MESSAGE_TR' value='{0}'>
            <input type='hidden' name='STATUS' value='{0}'>
            <input type='hidden' name='ERROR_CODE' value='{0}'>
            <input type='hidden' name='CUSTOMER_NAME' value='{0}'>
            <input type='hidden' name='CUSTOMER_MAIL' value='{0}'>
            <input type='hidden' name='CUSTOMER_PHONE' value='{0}'>
            <input type='hidden' name='CUSTOMER_ADDRESS' value='{0}'>
            <input type='hidden' name='CUSTOMER_CC_NUMBER' value='{0}'>
            <input type='hidden' name='CUSTOMER_CC_NAME' value='{0}'>
            <input type='hidden' name='COMMISSION' value='{0}'>
            <input type='hidden' name='COMMISSION_RATE' value='{0}'>
            <input type='hidden' name='AMOUNT' value='{0}'>
            <input type='hidden' name='INSTALLMENT' value='{0}'>
            <input type='hidden' name='BANK_AUTH_CODE' value='{0}'>
    </form>
    </body>
</html>

In the FORM POST message sent to the merchant, the value of the STATUS parameter is SUCCESS and the RETURN_CODE parameter is 0, indicating that the 3D Payment process has been completed without any problems.

• In order to be sure of the payment status, you need to query with the PROCCESS_QUERY method and take into account the answer of the PROCCESS_QUERY method. You need to configure this query as server to server, not client-side.

• This PROCCESS_QUERY method you have made in the client browser should not be visible and cannot be followed.