# TokenX API Integration (EN)

### Introduction

This documentation provides a detailed explanation of the integration process with the TokenX API. The integration process includes steps such as obtaining the necessary client credentials, setting up webhook addresses, and making various API calls. Below, the main steps to follow for integrating with the TokenX API are outlined in detail.

### Architecture

<figure><img src="https://828363377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTDApe9ujkHROOK7s0JPT%2Fuploads%2FcI3eTegM0MywNA2HzQxr%2FTokenX-Wireless-Integration.jpeg?alt=media&#x26;token=b2dbeada-ba36-412e-bb7c-0aeb3dd9925b" alt=""><figcaption></figcaption></figure>

## Key Words and Terminology

**Basket:** It represents the purchase details to be processed by the fiscal device (Token ÖKC), including information like product names, prices, quantities, and tax details, which are necessary for issuing receipts or invoices.

**Access\_token:** A security token used to authenticate and authorize API requests, ensuring that only authorized users can interact with the system.

**Terminal:** A point-of-sale device used to process transactions and payments in a retail environment.

**BranchId:** A unique identifier for a specific branch that is associated with one or multiple terminals.

**ÖKC (Payment Recording Device):** A fiscal device used to record sales and tax information for regulatory compliance.

## Integration

The following steps must be followed for the integration.

### 1. Client Credential Distribution

When making all API requests in TokenX Wireless Integration, each transaction must include an access\_token in its header. To obtain this access\_token, you need the `client-id` and `client-secret` information defined for each integrator you will be integrating with.

* **Credential Sharing in Production**: `client-id` and `client-secret`information created in the real environment for integrators will be shared via e-mail by our devops/security team.

{% hint style="warning" %}
When the test environment is used, the `client-id` and `client-secret` will be provided to you by the developer team.
{% endhint %}

* **Obtaining Access Token:** After receiving the `client-id` and `client-secret`, you need to send a POST request to the TEST\_AUTH\_URL/v1/auth/token endpoint, using the `client-id` and `client-secret` in the header with the Basic Auth mechanism. The response will return the access token.

<figure><img src="https://828363377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTDApe9ujkHROOK7s0JPT%2Fuploads%2FSXAXyKSVLCauvmstjnl0%2Fimage.png?alt=media&#x26;token=ac10c387-f945-42c2-8593-bd7d52fb3173" alt=""><figcaption><p>Client Credential Distribution Workflow Sequence Diagram</p></figcaption></figure>

### 2. Webhook Configuration (ClientSettings API)

Asynchronous operation results are sent to the integrating company’s service via a POST request as a Webhook. The business integrating with TokenX API must configure the Webhook address and the necessary authentication information to access this address through the ClientSettings API available in the Postman collection. Otherwise, they will not receive information about the asynchronous statuses of operations (lock, unlock, payment) in the later stages of the integration.\
\
**ClientSettings API Description**

{% hint style="warning" %}
**IP Whitelist**

If the businesses performing the integration have IP restrictions, they can optionally add specific TokenX IP addresses to their IP whitelist to ensure secure communication.

* Test Environment: Will be added to the documentation.

* Production Environment: Will be added to the documentation.
  {% endhint %}

* **Header**:&#x20;
  * The Authorization mechanism in the request `header` must be set to `Bearer Token`, and the `Bearer Token` value is the `Access Token` obtained from the previous step’s request to TEST\_URL/v1/auth/token.

* **Body:**
  * **Callback URL:** The user must enter their own Webhook address in this field. This URL is where the asynchronous operation statuses will be sent during the integration process. (Note: During testing, to easily view operation results without setting up a server, you can use a site like <https://webhook.site/> to generate a Webhook address that handles REST API requests.)
  * **Callback Auth**: This is your Callback URL's Authorization mechanism which will be provided by you.

<figure><img src="https://828363377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTDApe9ujkHROOK7s0JPT%2Fuploads%2FlHQXEJGxMBIAuLU2rNhv%2Fimage.png?alt=media&#x26;token=ac08d302-cad0-4641-a2c3-ad5f44205b9f" alt=""><figcaption><p>Client Settings API Workflow Sequence Diagram</p></figcaption></figure>

### 3. Get Fiscal Parameters

This is a mandatory step to ensure fiscal matching between the external system and the Token ÖKC (Payment Recording Device). The `terminalId` information must be included in the header of the request, which is available in the Postman Collection.

* **Header:** The `terminalId` and the `access_token` must be included in the header.
* **Response:** Details regarding the response format and content will be added to the documentation soon.<br>

### 4. Send Basket

{% hint style="warning" %}
Created, incomplete (open), and cancelled baskets are retained for a maximum of 2 weeks.
{% endhint %}

* **Creating a Basket for a Single Terminal:**\
  If the request is to be sent to a single terminal, the `terminalId` and the `access_token` must be added to the header of the request available in the Postman Collection.
* **Creating a Basket for All Terminals Assigned to the Branch:**\
  If the request is to be sent to all terminals assigned to a branch, the `branchId` and `access_token` must be added to the header of the request available in the Postman Collection.
* **Request Body Details and Response:**

  Details regarding the other fields to be included in the request body can be accessed via the following link.\
  [#token-integration-protocol](https://developer.tokeninc.com/token-developer-portal-1/x-platform/token-x-connect-wire/genel-tanitim#token-integration-protocol "mention")
* **Optional Fields**: Optionally, `checkNumber`, `title`, `note` and `filter` can also be included in the request body. These details will be displayed in the fiscal device (ÖKC) interface.
* **Example Baskets**: Details regarding the example basket requests can be accessed via the following link.\
  [hazir-ornek-sepetler](https://developer.tokeninc.com/token-developer-portal-1/x-platform/token-x-connect-wire/hazir-ornek-sepetler "mention")

<figure><img src="https://828363377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTDApe9ujkHROOK7s0JPT%2Fuploads%2FWCNZfQQg0wihDByokGjL%2Fimage.png?alt=media&#x26;token=cb9e055f-9962-4502-8247-53fbddaebc1f" alt=""><figcaption><p>Flow diagram of sending the basket and completing the payment</p></figcaption></figure>

### 5. Send Instant Basket

This request is used to send a basket directly to a terminal for instant payment. The optional parameters and body specified in step 4 remain the same. In the header, the `terminal-id`  must be provided. Additionally, for authentication, the `access_token` should also be included in the header.

{% hint style="warning" %}

* To use this endpoint for sending a basket directly to the terminal, the device’s mode must be changed to **‘immediate basket payment’.**
* The `branch-id`  should not be included in the header of this request.
* Created, incomplete (open), and cancelled baskets are retained for a maximum of 2 weeks.
  {% endhint %}

### 6. Get Basket Details

To retrieve the details of the created basket, the basket’s `id` must be specified in the **path** of the request available in the Postman Collection. This `id` should be the same as the `id` found in the body of the request sent in step 4 (Send Basket).

* **Path Parameter**: The basket’s `id` must be included in the URL **path** of the request.
* **Header**: The `access_token` must be included in the header.
* **Response**: Details regarding the response format and content will be added to the documentation soon.

### 7. Delete Basket

To delete the created basket, the basket’s `id` must be specified in the **path** of the request available in the Postman Collection. This `id` should be the same as the `id` found in the body of the request sent in step 4 (Send Basket).

* **Path Parameter**: The basket’s `id` must be included in the URL **path** of the request.
* **Header**: The `access_token` must be included in the header.
* **Response**: Details regarding the response format and content will be added to the documentation soon.

### 8. Status Codes

Status Codes for Basket Operations are as follows:

* **POS (ÖKC) Status Codes**

<table data-header-hidden><thead><tr><th></th><th></th><th></th><th data-hidden></th><th data-hidden></th></tr></thead><tbody><tr><td><strong>Status</strong></td><td><strong>Description</strong></td><td><strong>Type</strong></td><td><strong>Step</strong></td><td><strong>Source</strong></td></tr><tr><td>0001</td><td>JWT token's algorithm does not match the expected one.</td><td>Token algorithm validation error</td><td></td><td></td></tr><tr><td>0002</td><td>JWT token has expired and is no longer valid.</td><td>Token expiration error</td><td></td><td></td></tr><tr><td>0003</td><td>JWT token's signature is invalid or does not match the expected signature.</td><td>Token signature validation error</td><td></td><td></td></tr><tr><td>0004</td><td>Authorization header is missing or improperly formatted.</td><td>Authorization header error</td><td></td><td></td></tr><tr><td>0005</td><td>Specific field (such as a claim) cannot be extracted from the JWT token.</td><td>Token field extraction error</td><td></td><td></td></tr><tr><td>0006</td><td>One of terminal-id, branch-id, merchant-id must be present.</td><td>No credential header provided</td><td></td><td></td></tr><tr><td>0007</td><td>Only one of terminal-id, branch-id, merchant-id must be present.</td><td>Multiple credential headers provided</td><td></td><td></td></tr><tr><td>0011</td><td>Forbidden access.</td><td>Forbidden access</td><td></td><td></td></tr><tr><td>0012</td><td>Internal server error.</td><td>Internal server error</td><td></td><td></td></tr><tr><td>0013</td><td>x-application-resource header is required.</td><td>Application resource header is missing</td><td></td><td></td></tr><tr><td>0</td><td>Successful</td><td>success</td><td>-</td><td>POS</td></tr><tr><td>1006</td><td>No record found</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1007</td><td>DB error: Duplicate record</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1013</td><td>Wrong data format</td><td>error</td><td>3</td><td>API</td></tr><tr><td>1018</td><td>Error: Order locked! For this operation you must first unlock the order</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1100</td><td>There is already an open basket assigned to this terminal</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1101</td><td>There is already an open basket for this check number</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1102</td><td>This basket has already been completed</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1103</td><td>The total of the items and the total payment amount are not equal</td><td>error</td><td>1</td><td>API</td></tr><tr><td>1104</td><td>This terminals mode is not suitable for receiving instant baskets</td><td>error</td><td>12</td><td>API</td></tr></tbody></table>

## Demo Video (Send Basket & Instant Basket)

<https://tokenfintech-my.sharepoint.com/:v:/g/personal/25200284_tokeninc_com/EfUk29I2H-RGqda7K31B6qkBXwRB_HZiY1scYVc-p-rmBA?e=fo4OJW>

## Postman Collection Link

This collection contains the details of the requests for interacting with TokenX API's, including authentication, basket management, and client settings. You can use this collection to test and explore our API functionalities quickly and efficiently.

<https://documenter.getpostman.com/view/29891759/2sB34hEzUj>

## Automation Software Simulator

By clicking on the link below, you can easily test the TokenX APIs through our dynamic simulator application:\
<https://xci.devtokeninc.com/>