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.

General Flow and Integration Model

VUK 507 Mode (Fiscal Cash Register Integrated / Hybrid Usage – Revenue Administration Approved Structure)

In this mode, the device behaves like a fiscal cash register (ÖKC) and operates with the GMU (Secure Fiscal Application) structure.

Features:

• The device functions as a fiscal cash register that records transactions in fiscal memory

• All payment types are supported:

  • Cash

  • Credit Card

  • Other payment methods (QR, meal cards, etc.)

• Sales transactions are directly converted into fiscal records (receipt generation)

• Compliant with the Revenue Administration regulations for traditional retail sales scenarios

Use Cases:

• Physical stores / retail points of sale

• Taxpayers required to use fiscal cash registers

---

VUK 509 Mode (e-Transformation Integrated / Fiscal Cash Register Exempt Structure)

In this mode, the device does not act as a fiscal device (ÖKC); it is limited to payment processing, and fiscal document generation is handled by external systems.

Features:

• Only credit card payments are supported

• Cash and alternative payment methods are not supported

• No fiscal receipt generation on the device

• Transactions are associated with e-Invoice / e-Archive processes

• Fiscal records are generated via e-Document systems instead of a fiscal cash register

Use Cases:

• Businesses exempt from fiscal cash register requirements

• e-Commerce / remote sales / field sales scenarios

• Invoice-based business models

In VUK 507 mode, the device assumes the role of a fiscal cash register (ÖKC), while in VUK 509 mode, it is positioned solely as a payment terminal, and fiscal document generation is handled through e-Document systems.

In both models, the integration proceeds with the following steps:

1. Login operations are performed

2. Access token is obtained

3. Relevant services are used based on the selected model

The login and token acquisition steps are common for both models. Service calls differ depending on whether VUK 507 or VUK 509 is used.

Important:

• VUK 507 and VUK 509 services must not be used together within the same integration.

• The model to be used should be determined before integration, based on the business model and fiscal obligations.

Integration Steps

iyzico Physical POS integration operates through a flow consisting of secure authentication and controlled transaction steps.

This section explains the overall sequence and purpose of the integration at a high level.

The sample implementation is demonstrated using the VUK 509 model.

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

Cash Register
        ↓
       POS
        ↓
     Payment 
        ↓
       POS
        ↓
  Cash Register

• 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

{
"code": "FYEff_koHQnoX9vIMo5icTrqmSsbIOvD6xz8KAEEjnvj652-WHt9HKRL1IngeOAZU6z8Z5BL3Nr_vQTcAv91nQmuOpJCUQ9qyWtoviNPLjLd5QY_ynLx0OtA5Xj8ZlMS",
"issuedAt": "2025-12-25T14:05:49.379055098+03:00",
"expiredAt": "2025-12-25T14:15:49.379055098+03:00"
}

---

2. Access Token – Response

Reponse

{
"access_token": "eyJraWQiOiI....ZEA",
"refresh_token": "eiHg.....BBp",
"scope": "iyzipayApiGateway",
"token_type": "Bearer",
"expires_in": 7199
}

---

3. Complete Sale

Request

{
    "conversationId": "conversation1",
    "locale": "TR",
    "deviceUniqueId": "PAV860047264",
    "transactionReferenceId": "string30",
    "price": 100.0,
    "currency": "TRY",
    "installment": 0,
    "saleType": "SALE",
    "paymentId": null
}

Response

{
  "conversationId": "string", 
  "locale": "string",
  "deviceUniqueId": "string",
  "transactionReferenceId": "string",
  "status": "string",
  "errorCode": "string",
  "errorMessage": "string",
  "errorGroup": "string",
  "systemTime": 0,
  "transactionDateTime": "2025-11-20T12:03:05.096Z",
  "authCode": "string",    
  "paymentId": "string",    
  "paymentDate": "20251120",
  "price": 0.0,
  "installment": 0,
  "currency": "TRY",
  "binNumber": "552879",
  "lastFourDigits": "0008",
  "hostReference": "string",
  "cardType": "CREDIT_CARD",
  "acquirerId": "string", 
  "issuerId": "string", 
  "bankMerchantId": "string",
  "bankTerminalId": "string",
  "batchNo": "string",
  "stanNo": "string",
  "posEntryModeCode": "string"
}

---

4. End of Day

Request

{
"conversationId": "string",
 "locale": "TR-EN",
 "deviceUniqueId": "string",
  "useSummary": true
}

Response

{
  "status": "string",
  "errorCode": "string",
  "errorMessage": "string",
  "errorGroup": "string",
  "locale": "string",
  "systemTime": 0,
  "conversationId": "string",
  "tails": [
    {
      "acquirerId": "string",
      "terminalId": "string",
      "bankMerchantId": "string",
      "totalTransactionAmount": "string",
      "totalTransactionCount": "string",
      "acquirerName": "string",
      "batchNo": "string",
      "responseCode": "string",
      "internalErrorCode": "string"
    }
  ],
  "batchNo": "string",
  "resultMessage": "string"
}