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 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.
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.
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, and note can also be included in the request body. These details will be displayed in the fiscal device (ÖKC) interface.
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 (Not Up-to-Date):
POS (ÖKC) Codes: Will be added to the documentation.
Bank Related Codes: Codes starting with 5xxx, used for banking transactions.
New Codes: Will be added to the documentation.
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
-1
User Cancelled
warn
1
Missing Info
error
2
Invalid E-Invoice Customer
error
3
E-Invoice Integrator Error
error
4
Network Error
error
5
Offline Invoice
success
6
Onboarding error
error
7
Invalid E-invoice Id
error
8
Missing Customer Info
error
9
POS is Busy
warn
10
Payment Plan Error
error
11
Payment is cancelled
warn
12
Unknown E-Invoice Integrator
error
13
Integrator Response Parsing Error
error
1001
Missing ClientId
error
1002
Missing TerminalId
error
1003
Timeout
warn
1004
Missing Info
error
1005
Locked Transaction
warn
1006
Record not Found
error
1007
Duplicate ID
error
1008
Unauthorized Terminal Error
error
1009
Callback URL Error
warn
1010
Timeout
warn
1011
Transaction was not delivered to the terminal
warn
1012
Transaction is not completed yet
info
1013
Wrong data format
error
1014
General Error
error
5001
Error
error
5002
Cancelled
warn
5003
Offline Decline
error
5004
Unable Decline
error
5005
Online Decline
error
5006
Payment App Not Found
error
5008
Bank App Not Found
error
5009
Bank App Crashed
error
5101
Card Validation Error
error
5102
Card Validation User Cancelled
warn
5104
Card Validation Timeout
error
5105
Card Validation Fallback Auth
error
5106
Card Validation Parsing Error
error
5107
BIN Query Error
warn
5108
Card Type is not Credit
warn
5109
Card Type is not Debit
warn
5110
Card Type is not Domestic
warn
5111
Card is not Issued by Requested Bank
warn
5112
Card Type is not Foreign
warn
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
Details regarding the other fields to be included in the request body can be accessed via the following link.
