TokenX API Integration (EN)
Last updated
Last updated
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.
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.
The following steps must be followed for the integration.
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.
When the test environment is used, the client-id and client-secret will be provided to you by the developer team.
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.
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
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.
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 Auth: This is your Callback URL's Authorization mechanism which will be provided by you.
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.
Created, incomplete (open), and cancelled baskets are retained for a maximum of 2 weeks.
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:
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
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.
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.
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.
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.
Status Codes for Basket Operations are as follows:
POS (ÖKC) Status Codes
Status
Description
Type
0001
JWT token's algorithm does not match the expected one.
Token algorithm validation error
0002
JWT token has expired and is no longer valid.
Token expiration error
0003
JWT token's signature is invalid or does not match the expected signature.
Token signature validation error
0004
Authorization header is missing or improperly formatted.
Authorization header error
0005
Specific field (such as a claim) cannot be extracted from the JWT token.
Token field extraction error
0
Successful
success
1006
No record found
error
1007
DB error: Duplicate record
error
1013
Wrong data format
error
1018
Error: Order locked! For this operation you must first unlock the order
error
1100
There is already an open basket assigned to this terminal
error
1101
There is already an open basket for this check number
error
1102
This basket has already been completed
error
1103
The total of the items and the total payment amount are not equal
error
1104
This terminals mode is not suitable for receiving instant baskets
error
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 to generate a Webhook address that handles REST API requests.)
Details regarding the other fields to be included in the request body can be accessed via the following 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.
By clicking on the link below, you can easily test the TokenX APIs through our dynamic simulator application:
