Payment and Transaction Services

Complete Payment

post

https://api.iyzipay.comhttps://sandbox-api.iyzipay.com

/v2/terminal-host/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}

Authorizations

BearerAuth

AuthorizationstringRequired

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.

Body

application/json

conversationIdstringRequired

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.

localestring · enumRequired

Response language.

Possible values:

deviceUniqueIdstringRequired

Unique identifier defined for the terminal/device where the transaction is performed.

transactionReferenceIdstringRequired

uniqueId value generated by the sales application for this sales transaction.

pricenumber · doubleRequired

Price Value

currencystringRequired

Currency

salesTypestring · enumRequired

Sales Type.

Possible values:

paymentIdstringOptional

Payment Number. This field is mandatory when performing a postAuth (provision closing) transaction.

installmentinteger · enumRequired

Installment Count

Possible values:

Responses

200

Success

application/json

conversationIdstringOptional

Unique value sent by the merchant for request-response matching and transaction tracking.

localestring · enumOptional

Response language

Possible values:

deviceUniqueIdstringOptional

Unique identifier defined for the terminal/device where the transaction is performed.

transactionReferenceIdstringOptional

Unique reference number generated by the sales application for the transaction.

statusstringOptional

Transaction result. (SUCCESS, FAILURE, etc.)

errorCodestringOptional

Error code returned if the transaction fails. It is empty for successful transactions.

errorMessagestringOptional

Descriptive error message returned in case of an error.

errorGroupstringOptional

Group/category information of the error.

systemTimeinteger · int64Optional

Unix timestamp value of when the transaction was processed in iyzico systems.

transactionDateTimestringOptional

Date and time when the transaction occurred on the terminal/host (ISO-8601).

authCodestringOptional

Approval (authorization) code generated by the bank/host.

paymentIdstringOptional

Transaction-based unique payment ID generated by iyzico.

paymentDatestringOptional

Date when the transaction is posted (YYYYMMDD).

pricenumber · doubleOptional

Transaction amount.

installmentinteger · int32Optional

Installment count. Returns 0 or 1 for single-payment transactions.

currencystringOptional

Transaction currency (e.g. TRY).

binNumberstringOptional

First 6 digits of the card (BIN).

lastFourDigitsstringOptional

Last 4 digits of the card number.

hostReferencestringOptional

Transaction reference number generated by the bank/host system.

cardTypestringOptional

Card type. (CREDIT_CARD, DEBIT_CARD, etc.)

acquirerIdstringOptional

Institution ID of the acquiring bank that processes the transaction.

issuerIdstringOptional

Institution ID of the issuing bank.

bankMerchantIdstringOptional

Merchant number assigned by the bank for the merchant.

bankTerminalIdstringOptional

Terminal number defined for the terminal at the bank.

batchNostringOptional

Batch (end-of-day) number that includes the transaction.

stanNostringOptional

System Trace Audit Number (STAN).

posEntryModeCodestringOptional

Code indicating how card information was entered into the POS (e.g. chip, magnetic stripe, contactless).

cancelHostReferencestringOptional

Void transaction reference number

refundHostReferencestringOptional

Refund transaction reference number

400

Bad Request

application/json

post

/v2/terminal-host/payment

HTTPcURLJavaScriptPython

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

Postman

Query Transaction Status

post

https://api.iyzipay.comhttps://sandbox-api.iyzipay.com

/v2/terminal-host/payment/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}

Authorizations

BearerAuth

AuthorizationstringRequired

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.

Body

application/json

Service that queries the status of a transaction.

conversationIdstringRequired

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.

localestring · enumRequired

Response language.

Possible values:

paymentIdstringRequired

Payment Number to be queried

deviceUniqueIdstringRequired

Unique identifier defined for the terminal/device where the transaction is performed.

transactionReferenceIdone of · nullableRequired

Unique reference number generated during the transaction for the payment/void/refund operation to be queried.

stringOptional

or

nullOptional

Responses

200

Success

application/json

conversationIdstringOptional

Unique value sent by the merchant for request-response matching and transaction tracking.

localestring · enumOptional

Response language

Possible values:

deviceUniqueIdstringOptional

Unique identifier defined for the terminal/device where the transaction is performed.

transactionReferenceIdstringOptional

Unique reference number generated by the sales application for the transaction.

statusstringOptional

Transaction result. (SUCCESS, FAILURE, etc.)

errorCodestringOptional

Error code returned if the transaction fails. It is empty for successful transactions.

errorMessagestringOptional

Descriptive error message returned in case of an error.

errorGroupstringOptional

Group/category information of the error.

systemTimeinteger · int64Optional

Unix timestamp value of when the transaction was processed in iyzico systems.

transactionDateTimestringOptional

Date and time when the transaction occurred on the terminal/host (ISO-8601).

authCodestringOptional

Approval (authorization) code generated by the bank/host.

paymentIdstringOptional

Transaction-based unique payment ID generated by iyzico.

paymentDatestringOptional

Date when the transaction is posted (YYYYMMDD).

pricenumber · doubleOptional

Transaction amount.

installmentinteger · int32Optional

Installment count. Returns 0 or 1 for single-payment transactions.

currencystringOptional

Transaction currency (e.g. TRY).

binNumberstringOptional

First 6 digits of the card (BIN).

lastFourDigitsstringOptional

Last 4 digits of the card number.

hostReferencestringOptional

Transaction reference number generated by the bank/host system.

cardTypestringOptional

Card type. (CREDIT_CARD, DEBIT_CARD, etc.)

acquirerIdstringOptional

Institution ID of the acquiring bank that processes the transaction.

issuerIdstringOptional

Institution ID of the issuing bank.

bankMerchantIdstringOptional

Merchant number assigned by the bank for the merchant.

bankTerminalIdstringOptional

Terminal number defined for the terminal at the bank.

batchNostringOptional

Batch (end-of-day) number that includes the transaction.

stanNostringOptional

System Trace Audit Number (STAN).

posEntryModeCodestringOptional

Code indicating how card information was entered into the POS (e.g. chip, magnetic stripe, contactless).

cancelHostReferencestringOptional

Void transaction reference number

refundHostReferencestringOptional

Refund transaction reference number

400

Bad Request

application/json

post

/v2/terminal-host/payment/query-transaction-status

HTTPcURLJavaScriptPython

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 paymentId is sent The details of the related sale (payment) transaction are returned.

• If transactionReferenceId + deviceUniqueId are sent together Related payment / void / refund transactions can be queried.

• If paymentId + transactionReferenceId are sent together Along with the sale transaction, related void and refund transactions can also be queried.

Sample Collection

Postman

Void Payment

post

https://api.iyzipay.comhttps://sandbox-api.iyzipay.com

/v2/terminal-host/payment/void

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}

Authorizations

BearerAuth

AuthorizationstringRequired

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.

Body

application/json

Payment Reversal Service.

conversationIdstringRequired

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.

localestring · enumRequired

Response language.

Possible values:

paymentIdstringRequired

Payment Number to be voided

paymentDatestringRequired

Date when the transaction is posted (YYYYMMDD).

deviceUniqueIdstringRequired

Unique identifier defined for the terminal/device where the transaction is performed.

transactionReferenceIdstringRequired

A unique reference number generated for the void transaction

reasonstringOptional

Void reason

descriptionstringOptional

Void description

Responses

200

Success

application/json

conversationIdstringOptional

Unique value sent by the merchant for request-response matching and transaction tracking.

localestring · enumOptional

Response language

Possible values:

deviceUniqueIdstringOptional

Unique identifier defined for the terminal/device where the transaction is performed.

transactionReferenceIdstringOptional

Unique reference number generated by the sales application for the transaction.

statusstringOptional

Transaction result. (SUCCESS, FAILURE, etc.)

errorCodestringOptional

Error code returned if the transaction fails. It is empty for successful transactions.

errorMessagestringOptional

Descriptive error message returned in case of an error.

errorGroupstringOptional

Group/category information of the error.

systemTimeinteger · int64Optional

Unix timestamp value of when the transaction was processed in iyzico systems.

transactionDateTimestringOptional

Date and time when the transaction occurred on the terminal/host (ISO-8601).

authCodestringOptional

Approval (authorization) code generated by the bank/host.

paymentIdstringOptional

Transaction-based unique payment ID generated by iyzico.

paymentDatestringOptional

Date when the transaction is posted (YYYYMMDD).

pricenumber · doubleOptional

Transaction amount.

installmentinteger · int32Optional

Installment count. Returns 0 or 1 for single-payment transactions.

currencystringOptional

Transaction currency (e.g. TRY).

binNumberstringOptional

First 6 digits of the card (BIN).

lastFourDigitsstringOptional

Last 4 digits of the card number.

hostReferencestringOptional

Transaction reference number generated by the bank/host system.

cardTypestringOptional

Card type. (CREDIT_CARD, DEBIT_CARD, etc.)

acquirerIdstringOptional

Institution ID of the acquiring bank that processes the transaction.

issuerIdstringOptional

Institution ID of the issuing bank.

bankMerchantIdstringOptional

Merchant number assigned by the bank for the merchant.

bankTerminalIdstringOptional

Terminal number defined for the terminal at the bank.

batchNostringOptional

Batch (end-of-day) number that includes the transaction.

stanNostringOptional

System Trace Audit Number (STAN).

posEntryModeCodestringOptional

Code indicating how card information was entered into the POS (e.g. chip, magnetic stripe, contactless).

cancelHostReferencestringOptional

Void transaction reference number

refundHostReferencestringOptional

Refund transaction reference number

422

Unprocessable Entity

application/json

post

/v2/terminal-host/payment/void

HTTPcURLJavaScriptPython

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

Postman

Refund Payment

post

https://api.iyzipay.comhttps://sandbox-api.iyzipay.com

/v2/terminal-host/payment/refund

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}

Authorizations

BearerAuth

AuthorizationstringRequired

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.

Body

application/json

conversationIdstringRequired

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.

localestring · enumRequired

Request language.

Possible values:

paymentIdstringRequired

Payment number to be refunded

deviceUniqueIdstringRequired

Unique identifier defined for the terminal/device where the transaction is performed.

pricenumber · doubleRequired

Transaction amount.

transactionReferenceIdstringRequired

Unique reference number generated by the sales application for the refund transaction.

paymentDatestringRequired

Date when the transaction is posted (YYYYMMDD).

reasonstringOptional

Refund Reason

descriptionstringOptional

Refund Description

Responses

200

Success

application/json

conversationIdstringOptional

Unique value sent by the merchant for request-response matching and transaction tracking.

localestring · enumOptional

Response language

Possible values:

deviceUniqueIdstringOptional

Unique identifier defined for the terminal/device where the transaction is performed.

transactionReferenceIdstringOptional

Unique reference number generated by the sales application for the transaction.

statusstringOptional

Transaction result. (SUCCESS, FAILURE, etc.)

errorCodestringOptional

Error code returned if the transaction fails. It is empty for successful transactions.

errorMessagestringOptional

Descriptive error message returned in case of an error.

errorGroupstringOptional

Group/category information of the error.

systemTimeinteger · int64Optional

Unix timestamp value of when the transaction was processed in iyzico systems.

transactionDateTimestringOptional

Date and time when the transaction occurred on the terminal/host (ISO-8601).

authCodestringOptional

Approval (authorization) code generated by the bank/host.

paymentIdstringOptional

Transaction-based unique payment ID generated by iyzico.

paymentDatestringOptional

Date when the transaction is posted (YYYYMMDD).

pricenumber · doubleOptional

Transaction amount.

installmentinteger · int32Optional

Installment count. Returns 0 or 1 for single-payment transactions.

currencystringOptional

Transaction currency (e.g. TRY).

binNumberstringOptional

First 6 digits of the card (BIN).

lastFourDigitsstringOptional

Last 4 digits of the card number.

hostReferencestringOptional

Transaction reference number generated by the bank/host system.

cardTypestringOptional

Card type. (CREDIT_CARD, DEBIT_CARD, etc.)

acquirerIdstringOptional

Institution ID of the acquiring bank that processes the transaction.

issuerIdstringOptional

Institution ID of the issuing bank.

bankMerchantIdstringOptional

Merchant number assigned by the bank for the merchant.

bankTerminalIdstringOptional

Terminal number defined for the terminal at the bank.

batchNostringOptional

Batch (end-of-day) number that includes the transaction.

stanNostringOptional

System Trace Audit Number (STAN).

posEntryModeCodestringOptional

Code indicating how card information was entered into the POS (e.g. chip, magnetic stripe, contactless).

cancelHostReferencestringOptional

Void transaction reference number

refundHostReferencestringOptional

Refund transaction reference number

400

Bad Request

application/json

post

/v2/terminal-host/payment/refund

HTTPcURLJavaScriptPython

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

Postman