Payment and Transaction Services
Complete Payment
This service starts the payment transaction on the terminal. The payment is completed by presenting the card on the POS device. Example: "You complete the transaction started by the sales application and receive fields such as paymentId/authCode."
Authorization (Bearer Token):
The token value is the access_token returned by the OAuth token service.
Header format: Authorization: Bearer {access_token}
Authorization with Bearer Token. Header format: Authorization: Bearer {access_token}
The access_token is generated by the OAuth token service and is used in Terminal Host services.
ID value used to match the request and response. It is determined by the merchant, and the value sent in the request is returned in the response.
Response language.
Unique identifier defined for the terminal/device where the transaction is performed.
uniqueId value generated by the sales application for this sales transaction.
Price Value
Currency
Sales Type.
Payment Number. This field is mandatory when performing a postAuth (provision closing) transaction.
Installment Count
Success
Unique value sent by the merchant for request-response matching and transaction tracking.
Response language
Unique identifier defined for the terminal/device where the transaction is performed.
Unique reference number generated by the sales application for the transaction.
Transaction result. (SUCCESS, FAILURE, etc.)
Error code returned if the transaction fails. It is empty for successful transactions.
Descriptive error message returned in case of an error.
Group/category information of the error.
Unix timestamp value of when the transaction was processed in iyzico systems.
Date and time when the transaction occurred on the terminal/host (ISO-8601).
Approval (authorization) code generated by the bank/host.
Transaction-based unique payment ID generated by iyzico.
Date when the transaction is posted (YYYYMMDD).
Transaction amount.
Installment count. Returns 0 or 1 for single-payment transactions.
Transaction currency (e.g. TRY).
First 6 digits of the card (BIN).
Last 4 digits of the card number.
Transaction reference number generated by the bank/host system.
Card type. (CREDIT_CARD, DEBIT_CARD, etc.)
Institution ID of the acquiring bank that processes the transaction.
Institution ID of the issuing bank.
Merchant number assigned by the bank for the merchant.
Terminal number defined for the terminal at the bank.
Batch (end-of-day) number that includes the transaction.
System Trace Audit Number (STAN).
Code indicating how card information was entered into the POS (e.g. chip, magnetic stripe, contactless).
Void transaction reference number
Refund transaction reference number
Bad Request
POST /v2/terminal-host/payment HTTP/1.1
Host: api.iyzipay.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 197
{
"conversationId": "conversation1",
"locale": "TR",
"deviceUniqueId": "PAV860047264",
"transactionReferenceId": "string16",
"price": 100,
"currency": "TRY",
"installment": 0,
"salesType": "SALE",
"paymentId": null
}{
"conversationId": "conversation1",
"locale": "tr",
"deviceUniqueId": "PAV860047264",
"transactionReferenceId": "TXN-20260101-000001",
"status": "SUCCESS",
"errorCode": "",
"errorMessage": "",
"errorGroup": "",
"systemTime": 1768221663000,
"transactionDateTime": "2026-01-01T10:23:45+03:00",
"authCode": "552238",
"paymentId": "28251001",
"paymentDate": "20260101",
"price": 100,
"installment": 1,
"currency": "TRY",
"binNumber": "552879",
"lastFourDigits": "0008",
"hostReference": "HSTREF0000000001",
"cardType": "CREDIT_CARD",
"acquirerId": "0010",
"issuerId": "0046",
"bankMerchantId": "800000001",
"bankTerminalId": "T0000001",
"batchNo": "001",
"stanNo": "000001",
"posEntryModeCode": "051"
}Sample Collection
Query Transaction Status
This service queries the status of a previously completed transaction. Example: You can retrieve the payment status and any error details using the paymentId.
Authorization (Bearer Token):
The token value is the access_token returned by the OAuth token service.
Header format: Authorization: Bearer {access_token}
Authorization with Bearer Token. Header format: Authorization: Bearer {access_token}
The access_token is generated by the OAuth token service and is used in Terminal Host services.
Service that queries the status of a transaction.
ID value used to match the request and response. It is determined by the merchant, and the value sent in the request is returned in the response.
Response language.
Payment Number to be queried
Unique identifier defined for the terminal/device where the transaction is performed.
Unique reference number generated during the transaction for the payment/void/refund operation to be queried.
Success
Unique value sent by the merchant for request-response matching and transaction tracking.
Response language
Unique identifier defined for the terminal/device where the transaction is performed.
Unique reference number generated by the sales application for the transaction.
Transaction result. (SUCCESS, FAILURE, etc.)
Error code returned if the transaction fails. It is empty for successful transactions.
Descriptive error message returned in case of an error.
Group/category information of the error.
Unix timestamp value of when the transaction was processed in iyzico systems.
Date and time when the transaction occurred on the terminal/host (ISO-8601).
Approval (authorization) code generated by the bank/host.
Transaction-based unique payment ID generated by iyzico.
Date when the transaction is posted (YYYYMMDD).
Transaction amount.
Installment count. Returns 0 or 1 for single-payment transactions.
Transaction currency (e.g. TRY).
First 6 digits of the card (BIN).
Last 4 digits of the card number.
Transaction reference number generated by the bank/host system.
Card type. (CREDIT_CARD, DEBIT_CARD, etc.)
Institution ID of the acquiring bank that processes the transaction.
Institution ID of the issuing bank.
Merchant number assigned by the bank for the merchant.
Terminal number defined for the terminal at the bank.
Batch (end-of-day) number that includes the transaction.
System Trace Audit Number (STAN).
Code indicating how card information was entered into the POS (e.g. chip, magnetic stripe, contactless).
Void transaction reference number
Refund transaction reference number
Bad Request
POST /v2/terminal-host/payment/query-transaction-status HTTP/1.1
Host: api.iyzipay.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 133
{
"conversationId": "conversation2",
"locale": "TR",
"paymentId": "28251001",
"deviceUniqueId": "PAV860047264",
"transactionReferenceId": null
}{
"conversationId": "conversation2",
"locale": "tr",
"deviceUniqueId": "PAV860047264",
"transactionReferenceId": "TXN-20260101-000001",
"status": "SUCCESS",
"errorCode": "",
"errorMessage": "",
"errorGroup": "",
"systemTime": 1768221700000,
"transactionDateTime": "2026-01-01T10:23:45+03:00",
"authCode": "552238",
"paymentId": "28251001",
"paymentDate": "20260101",
"price": 100,
"installment": 1,
"currency": "TRY",
"binNumber": "552879",
"lastFourDigits": "0008",
"hostReference": "HSTREF0000000001",
"cardType": "CREDIT_CARD",
"acquirerId": "0010",
"issuerId": "0046",
"bankMerchantId": "800000001",
"bankTerminalId": "T0000001",
"batchNo": "001",
"stanNo": "000001",
"posEntryModeCode": "051"
}Query Status – Important Note
In the Query Status service, the fields paymentId, transactionReferenceId, and deviceUniqueId are not all mandatory at the same time.
To successfully execute the service, at least one of the following field combinations must be provided:
If only
paymentIdis sent The details of the related sale (payment) transaction are returned.If
transactionReferenceId+deviceUniqueIdare sent together Related payment / void / refund transactions can be queried.If
paymentId+transactionReferenceIdare sent together Along with the sale transaction, related void and refund transactions can also be queried.
Sample Collection
Void Payment
This service cancels an eligible payment. Example: "The cancellation process is initiated with paymentId and paymentDate. The cancellation is completed by swiping the card on the POS device."
Authorization (Bearer Token):
The token value is the access_token returned by the OAuth token service.
Header format: Authorization: Bearer {access_token}
Authorization with Bearer Token. Header format: Authorization: Bearer {access_token}
The access_token is generated by the OAuth token service and is used in Terminal Host services.
Payment Reversal Service.
ID value used to match the request and response. It is determined by the merchant, and the value sent in the request is returned in the response.
Response language.
Payment Number to be voided
Date when the transaction is posted (YYYYMMDD).
Unique identifier defined for the terminal/device where the transaction is performed.
A unique reference number generated for the void transaction
Void reason
Void description
Success
Unique value sent by the merchant for request-response matching and transaction tracking.
Response language
Unique identifier defined for the terminal/device where the transaction is performed.
Unique reference number generated by the sales application for the transaction.
Transaction result. (SUCCESS, FAILURE, etc.)
Error code returned if the transaction fails. It is empty for successful transactions.
Descriptive error message returned in case of an error.
Group/category information of the error.
Unix timestamp value of when the transaction was processed in iyzico systems.
Date and time when the transaction occurred on the terminal/host (ISO-8601).
Approval (authorization) code generated by the bank/host.
Transaction-based unique payment ID generated by iyzico.
Date when the transaction is posted (YYYYMMDD).
Transaction amount.
Installment count. Returns 0 or 1 for single-payment transactions.
Transaction currency (e.g. TRY).
First 6 digits of the card (BIN).
Last 4 digits of the card number.
Transaction reference number generated by the bank/host system.
Card type. (CREDIT_CARD, DEBIT_CARD, etc.)
Institution ID of the acquiring bank that processes the transaction.
Institution ID of the issuing bank.
Merchant number assigned by the bank for the merchant.
Terminal number defined for the terminal at the bank.
Batch (end-of-day) number that includes the transaction.
System Trace Audit Number (STAN).
Code indicating how card information was entered into the POS (e.g. chip, magnetic stripe, contactless).
Void transaction reference number
Refund transaction reference number
Unprocessable Entity
POST /v2/terminal-host/payment/void HTTP/1.1
Host: api.iyzipay.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 201
{
"conversationId": "conversation3",
"locale": "TR",
"paymentId": "28251028",
"paymentDate": "20260112",
"deviceUniqueId": "PAV860047264",
"transactionReferenceId": "voidtransaction1",
"reason": "",
"description": ""
}{
"conversationId": "conversation3",
"locale": "tr",
"deviceUniqueId": "PAV860047264",
"transactionReferenceId": "voidtransaction1",
"status": "SUCCESS",
"errorCode": "",
"errorMessage": "",
"errorGroup": "",
"systemTime": 1768217880000,
"paymentId": "28251028",
"paymentDate": "20260112",
"price": 50,
"currency": "TRY",
"authCode": "552238",
"hostReference": "HSTREF0000000001",
"cancelHostReference": "HSTREF0000000002"
}Sample Collection
Refund Payment
This service performs a refund operation on an eligible payment (partial/total). Example: "A refund process is initiated with paymentId and price. The cancellation process is completed by swiping the card on the POS device."
Authorization (Bearer Token):
The token value is the access_token returned by the OAuth token service.
Header format: Authorization: Bearer {access_token}
Authorization with Bearer Token. Header format: Authorization: Bearer {access_token}
The access_token is generated by the OAuth token service and is used in Terminal Host services.
ID value used to match the request and response. It is determined by the merchant, and the value sent in the request is returned in the response.
Request language.
Payment number to be refunded
Unique identifier defined for the terminal/device where the transaction is performed.
Transaction amount.
Unique reference number generated by the sales application for the refund transaction.
Date when the transaction is posted (YYYYMMDD).
Refund Reason
Refund Description
Success
Unique value sent by the merchant for request-response matching and transaction tracking.
Response language
Unique identifier defined for the terminal/device where the transaction is performed.
Unique reference number generated by the sales application for the transaction.
Transaction result. (SUCCESS, FAILURE, etc.)
Error code returned if the transaction fails. It is empty for successful transactions.
Descriptive error message returned in case of an error.
Group/category information of the error.
Unix timestamp value of when the transaction was processed in iyzico systems.
Date and time when the transaction occurred on the terminal/host (ISO-8601).
Approval (authorization) code generated by the bank/host.
Transaction-based unique payment ID generated by iyzico.
Date when the transaction is posted (YYYYMMDD).
Transaction amount.
Installment count. Returns 0 or 1 for single-payment transactions.
Transaction currency (e.g. TRY).
First 6 digits of the card (BIN).
Last 4 digits of the card number.
Transaction reference number generated by the bank/host system.
Card type. (CREDIT_CARD, DEBIT_CARD, etc.)
Institution ID of the acquiring bank that processes the transaction.
Institution ID of the issuing bank.
Merchant number assigned by the bank for the merchant.
Terminal number defined for the terminal at the bank.
Batch (end-of-day) number that includes the transaction.
System Trace Audit Number (STAN).
Code indicating how card information was entered into the POS (e.g. chip, magnetic stripe, contactless).
Void transaction reference number
Refund transaction reference number
Bad Request
POST /v2/terminal-host/payment/refund HTTP/1.1
Host: api.iyzipay.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 212
{
"conversationId": "conversation4",
"locale": "TR",
"paymentId": "11001100",
"deviceUniqueId": "PAV860047264",
"price": 50,
"transactionReferenceId": "refundtransaction2",
"paymentDate": 20260101,
"reason": "",
"description": ""
}{
"conversationId": "conversation4",
"locale": "tr",
"deviceUniqueId": "PAV860047264",
"transactionReferenceId": "refundtransaction2",
"status": "SUCCESS",
"errorCode": "",
"errorMessage": "",
"errorGroup": "",
"systemTime": 1768221749000,
"paymentId": "11001100",
"paymentDate": "20260101",
"price": 50,
"currency": "TRY",
"authCode": "552238",
"hostReference": "HSTREF0000000001",
"refundHostReference": "HSTREF0000000003"
}Sample Collection
Last updated