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

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 sending API requests, the access_token must be included in the header for all operations. To obtain the Access Token, you will need the client-id and client-secret specifically assigned to the business owner integrating with the TokenX API.

• Business Owner And Credential Distribution: The business owner can obtain the client-id and client-secret from the Wireless Integration page in the TokenX Merchant Panel.

• Obtaining Access Token: After receiving the client-id and client-secret, you need to send a POST request to the TEST_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.

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

• Header:

  • 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.

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.

4. Send Basket

• 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. Genel Tanıtım

• 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. Hazır Örnek Sepetler

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.

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

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/31664195/2sAY4rEQbG

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/