Terminal API Integration
Overview
The Terminal API is a specialized communication protocol developed to ensure secure and controlled communication between Cash Register systems (ECR) and Physical POS devices during payment transactions.
This API defines the entire payment flow in a standardized and deterministic structure, from initiating the payment process to delivering the result back to the cash register.
Scope of the Documentation
This document covers the following topics:
Terminal API core concepts
Payment lifecycle and statuses
Request / response message formats
All requests sent to the services must be made using the iyzico OAuth2 authentication structure. A Bearer access_token is required to access payment and end-of-day services.
All requests sent to the services must be made using the iyzico OAuth2 authentication structure. A Bearer access_token is required to access payment and end-of-day services.
Integration Steps
The iyzico Physical POS integration operates through a flow consisting of secure authentication and controlled transaction steps. This section outlines the overall sequence and purpose of the integration.
User Authentication and Authorization Initialization
Obtaining Access Token
Completing the Sale Transaction
Querying Transaction Status
Void/Refund (Optional)
End of Day
1. User Authentication and Authorization Initialization
In the first step of the integration, an authorization process is initiated using the user credentials defined in the merchant system.
In this step:
The user is authenticated
An Authorization Code representing the authorization process is generated
This code:
Is short-lived and single-use
Is used in the next step to obtain access authorization
2. Obtaining Access Token
An access token is generated by the system using the Authorization Code.
This token:
Is used in all service calls including payment, void, refund, and end-of-day operations
Has a limited validity period
Must be refreshed when expired
After this stage, the system becomes an authorized terminal capable of performing transactions.
3. Completing the Sale Transaction
After authorization is completed, the sale transaction is initiated and the payment process is completed.
In this step:
A unique reference is generated for the sale
Terminal and cash register identification is performed
The payment result is recorded by the system
The returned paymentId is used as the main reference for all subsequent operations (void, refund, query).
4. Transaction Status Query
The status of completed transactions can be queried at this stage.
Through this query:
Whether the sale was successful
The status of void or refund operations
Detailed information about the transaction
can be retrieved via a single service.
5. Sale Void
This step is used when a same-day sale needs to be canceled.
The void operation:
Is associated with the original sale transaction
Returns the result to the system upon success
This step is only valid for transactions that have not yet been included in end-of-day closing.
6. Refund
Full or partial refund operations after a sale are handled in this step.
The refund operation:
Is performed independently with its own reference
Returns refund details upon success
7. End of Day (EOD)
End-of-day processing is performed to settle transactions with the bank.
In this step:
Daily transactions are closed in bulk
Summary and total information can be retrieved
The bank-side batch process is completed
Architectural Flow
The payment flow within the Terminal API proceeds as follows:
The cash register creates the payment initiation request
The POS device manages user interaction (card reading, PIN entry, contactless, etc.)
The payment result is transmitted back to the cash register via defined protocol messages
Protocol Design
The Terminal API is a custom protocol designed and developed by iyzico.
Message formats, state transitions, and error scenarios are clearly defined.
The protocol is designed with the following objectives:
Low latency
Clear and predictable responses
Standardized error handling
Extensible structure for POS manufacturers
Supported POS Devices
Currently, the Terminal API is compatible with the following POS manufacturer:
Pavo (EFT POS)
Support for additional POS manufacturers can be added in the future while maintaining the same protocol structure.
Sample Implementation
1. Authorization Initialization – Response
Response
2. Access Token – Response
Reponse
3. Complete Sale
Request
Response
4. End of Day
Request
Response
Last updated