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

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": "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,
  "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"
}

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

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": "11001100",
  "deviceUniqueId": "PAV860047264",
  "transactionReferenceId": null
}

{
  "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,
  "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"
}

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

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": "string",
  "locale": "string",
  "deviceUniqueId": "string",
  "transactionReferenceId": "string",
  "status": "string",
  "errorCode": "string",
  "errorMessage": "string",
  "errorGroup": "string",
  "systemTime": 0,
  "paymentId": "string",
  "price": 50,
  "currency": "TRY",
  "authCode": "552238",
  "hostReference": "mock0007iyzihostrf",
  "cancelHostReference": "mock0007iyzihostrfrfn"
}

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.

reasonstringOptional

Refund Reason

descriptionstringOptional

Refund Description

Responses

200

Success

application/json

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

{
  "conversationId": "conversation4",
  "locale": "TR",
  "paymentId": "11001100",
  "deviceUniqueId": "PAV860047264",
  "price": 50,
  "transactionReferenceId": "refundtransaction2",
  "reason": "",
  "description": ""
}

{
  "conversationId": "string",
  "locale": "string",
  "deviceUniqueId": "string",
  "transactionReferenceId": "string",
  "status": "string",
  "errorCode": "string",
  "errorMessage": "string",
  "errorGroup": "string",
  "systemTime": 0,
  "paymentId": "string",
  "price": 50,
  "currency": "TRY",
  "authCode": "552238",
  "hostReference": "mock0007iyzihostrf",
  "refundHostReference": "mock0007iyzihostrfrfn"
}

Sample Collection

Postman