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.

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.

Client Credential Distribution Workflow Sequence Diagram

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

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.

Client Settings API Workflow Sequence Diagram

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

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:

  Details regarding the other fields to be included in the request body can be accessed via the following link. #token-integration-protocol
• 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

Flow diagram of sending the basket and completing the payment

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.

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

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 (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

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/