# BKM Express with Common Payment Page

#### BKM Express with Common Payment Page Service**;**

<table><thead><tr><th width="120.33333333333331">Method</th><th width="528">API URL</th><th>Parameter</th></tr></thead><tbody><tr><td>POST</td><td>https://posservice.esnekpos.com/api/pay/CommonPaymentDealer</td><td>JSON File</td></tr></tbody></table>

### BKM Express Payment Transaction Flow with Common Payment Page Servic&#x65;**;**

In order to make a successful collection with BKM Express using the common payment page model, you must complete your integration by following the procedures described below. This method is exactly the same as the Common payment page method, the Pay with BKM Express option will be opened on the common payment page that opens, and the payment will be made through the BKM Express account when this option is selected. The JSON file and form post result that will be returned to the merchants during and after the payment is exactly the same as the common payment page model.

**Step 1:**

The merchant user sends the payment request using the above-mentioned request model, together with his/her own web address (BACK\_URL) information, basket, payment amount information, and his/her own web address (BACK\_URL) to which the payment result is requested, and initiates the payment process.

All parameters must be sent completely so that transactions can be carried out safely and smoothly and fraud transactions can be prevented.

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

#### Common Checkout Page Service Request Message Parameters

<table><thead><tr><th width="232">Parameters</th><th width="94">Type</th><th width="80">Compulsory</th><th>Descripiton</th></tr></thead><tbody><tr><td>MERCHANT</td><td>string</td><td>Yes</td><td>It is a unique credential created specifically for the member business.</td></tr><tr><td>MERCHANT_KEY</td><td>string</td><td>Yes</td><td>It is the key information created specifically for the member business.</td></tr><tr><td>ORDER_REF_NUMBER</td><td>string</td><td>Yes</td><td>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.</td></tr><tr><td>ORDER_AMOUNT</td><td>string</td><td>Yes</td><td>It is the transaction amount information of the payment transaction.</td></tr><tr><td>PRICES_CURRENCY</td><td>string</td><td>Yes</td><td>It is the currency information in which the payment transaction will be made. Currently, only “TRY, USD, EUR, GBP” can be sent.</td></tr><tr><td>BACK_URL</td><td>string</td><td>Yes</td><td>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.</td></tr><tr><td>FIRST_NAME</td><td>string</td><td>Yes</td><td>It is the name of the user (customer) performing the transaction.</td></tr><tr><td>LAST_NAME</td><td>string</td><td>Yes</td><td>It is the surname of the user (customer) who performed the transaction.</td></tr><tr><td>MAIL</td><td>string</td><td>Yes</td><td>It is the e-mail information of the user (customer) performing the transaction.</td></tr><tr><td>PHONE</td><td>string</td><td>Yes</td><td>It is the phone information of the user (customer) performing the transaction.</td></tr><tr><td>CITY</td><td>string</td><td>Yes</td><td>It is the city information of the user (customer) performing the transaction.</td></tr><tr><td>STATE</td><td>string</td><td>Yes</td><td>It is the district information of the user (customer) performing the transaction.</td></tr><tr><td>ADDRESS</td><td>string</td><td>Yes</td><td>It is the address information of the user (customer) performing the transaction.</td></tr></tbody></table>

<br>

**Product**

<table><thead><tr><th width="245">Parameters</th><th width="78">Type</th><th width="84">Compulsory</th><th>Description</th></tr></thead><tbody><tr><td>PRODUCT_ID</td><td>string</td><td>Yes</td><td>It is the ID information given to the product by the member merchant.</td></tr><tr><td>PRODUCT_NAME</td><td>string</td><td>Yes</td><td>The name of the product.</td></tr><tr><td>PRODUCT_CATEGORY</td><td>string</td><td>Yes</td><td>It is the category information of the product.</td></tr><tr><td>PRODUCT_DESCRIPTION</td><td>string</td><td>Yes</td><td>It is the description information of the product.</td></tr><tr><td>PRODUCT_AMOUNT</td><td>string</td><td>Yes</td><td>It is the amount information of the product.</td></tr></tbody></table>

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

```json
                                            
{
    "Config" :  {
        "MERCHANT" : "TEST1234",
        "MERCHANT_KEY" : "4oK26hK8MOXrIV1bzTRVPA==",
        "ORDER_REF_NUMBER" : "RFN0003",
        "ORDER_AMOUNT" : "150",
        "PRICES_CURRENCY" : "TRY",
        "BACK_URL" : "The return url address that you will specify as a result of the transaction"
    },
    "Customer" : {
         "FIRST_NAME" : "Firstname",
         "LAST_NAME" : "Lastname",
         "MAIL" : "destek@esnekpos.com",
         "PHONE" : "05435434343",
         "CITY" : "İstanbul",
         "STATE" : "Kağıthane",
         "ADDRESS" : "Merkez Mahallesi, Ayazma Cd. No:37/91 Papirus Plaza Kat:5, 34406 Kağıthane / İSTANBUL"
    },
    "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 Textils",
             "PRODUCT_DESCRIPTION" : "Product Descripiton",
             "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;

#### Secure Payment Page Service Response Message Parameters

<table><thead><tr><th>Parameters</th><th width="109">Type</th><th width="105">Compulsory</th><th>Description</th></tr></thead><tbody><tr><td>ORDER_REF_NUMBER</td><td>string</td><td>Yes</td><td>It is the reference number information of the request given by the merchant in the payment request.</td></tr><tr><td>STATUS</td><td>string</td><td>Yes</td><td>The result of the payment transaction is the status information.</td></tr><tr><td>RETURN_CODE</td><td>string</td><td>Yes</td><td>The status of the payment process is the code information.</td></tr><tr><td>RETURN_MESSAGE</td><td>string</td><td>Yes</td><td>The status message is the result of the payment process.</td></tr><tr><td>RETURN_MESSAGE_TR</td><td>string</td><td>Yes</td><td>It is the Turkish explanation information for the status message as a result of the payment transaction.</td></tr><tr><td>ERROR_CODE</td><td>string</td><td>Yes</td><td>Error code information as a result of unsuccessful payment transaction. Bank error codes are also returned within this parameter.</td></tr><tr><td>DATE</td><td>string</td><td>Yes</td><td>It is the transaction date information for the payment transaction.</td></tr><tr><td>URL_3DS</td><td>string</td><td>Yes</td><td>3D Verification Page URL Address to which the merchant will direct the user</td></tr><tr><td>REFNO</td><td>string</td><td>Yes</td><td>The reference number information given by the Esnekpos system for the payment transaction</td></tr><tr><td>HASH</td><td>string</td><td>Yes</td><td>Hash information of the payment transaction generated by the Esnekpos system</td></tr><tr><td>CUSTOMER_NAME</td><td>string</td><td>Yes</td><td>It is the name and surname of the user (customer) performing the transaction.</td></tr><tr><td>CUSTOMER_MAIL</td><td>string</td><td>Yes</td><td>It is the e-mail information of the user (customer) performing the transaction.</td></tr><tr><td>CUSTOMER_PHONE</td><td>string</td><td>Yes</td><td>It is the phone information of the user (customer) performing the transaction.</td></tr><tr><td>CUSTOMER_ADDRESS</td><td>string</td><td>Yes</td><td>It is the address information of the user (customer) performing the transaction.</td></tr><tr><td>CUSTOMER_CC_NUMBER</td><td>string</td><td>Yes</td><td>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.</td></tr><tr><td>CUSTOMER_CC_NAME</td><td>string</td><td>Yes</td><td>It is the name and surname information of the card holder to whom the payment will be made.</td></tr><tr><td>IS_NOT_3D_PAYMENT</td><td>string</td><td>Yes</td><td>It is the information of whether the payment process takes place in 3D.</td></tr><tr><td>VIRTUAL_POS_VALUES</td><td>string</td><td>Yes</td><td>It is the virtualpos description information of the payment transaction.</td></tr><tr><td>RETURN_MESSAGE_3D</td><td>string</td><td>Yes</td><td>It is the reply message information of the 3D payment transaction received from the bank.</td></tr></tbody></table>

```json
                                            
{
    "ORDER_REF_NUMBER": "RFN0003",
    "STATUS": "SUCCESS",
    "RETURN_CODE": "0",
    "RETURN_MESSAGE": "SUCCESS",
    "RETURN_MESSAGE_TR": null,
    "ERROR_CODE": null,
    "DATE": "21.10.2020 09:32:32",
    "URL_3DS": "http://pos.esnekpos.com/Pages/CommonPayment.aspx?hash=9f9bde8bafc7389395aa24f47e58905d1063cd77268b791dbc0bcf87a01c2148",
    "REFNO": "25057",
    "HASH": "9f9bde8bafc7389395aa24f47e58905d1063cd77268b791dbc0bcf87a01c2148",
    "CUSTOMER_NAME": null,
    "CUSTOMER_MAIL": null,
    "CUSTOMER_PHONE": null,
    "CUSTOMER_ADDRESS": null,
    "CUSTOMER_CC_NUMBER": null,
    "CUSTOMER_CC_NAME": null,
    "IS_NOT_3D_PAYMENT": false,
    "VIRTUAL_POS_VALUES": null,
    "RETURN_MESSAGE_3D": null
}
                                        
```

If the value of STATUS parameter is SUCCESS and the value of RETURN\_CODE parameter is 0 in the Common Payment Page transaction response message, it means that the Joint Payment Page transaction has been accepted. In the next step, if the user who will make the payment chooses the option to pay with BKM Express, the payment will be made by obtaining the BKM Express account login information and installment information.

**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 receives BKM Express account information and installment information from the user on its own servers using its own security measures and advances the payment process.

<figure><img src="https://developer.esnekpos.com/Content/classic/demos/default/assets/demo/media/img/bkm-ortak-odeme.png" alt=""><figcaption></figcaption></figure>

**Step 5:**

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
<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='AMOUNT' value='{0}'>
            <input type='hidden' name='INSTALLMENT' 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.

{% hint style="danger" %}

* <mark style="color:red;">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.</mark>&#x20;
* <mark style="color:red;">This PROCCESS\_QUERY method you have made in the client browser should not be visible and cannot be followed.</mark>
  {% endhint %}

| BKM Express Test Account Information |                  |
| ------------------------------------ | ---------------- |
| User Name                            | <isyeri@bkm.com> |
| Password                             | 147258           |
| Verification Code                    | 123456           |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer-eng.esnekpos.com/esnekpos-developer-environment/bkm-express/bkm-express-with-common-payment-page.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.