Payment and Transaction Services

Sale Transaction

This service is used to perform a standard sale transaction via the GMU device.

During the sale process, the payment amount and sale items are transmitted to the POS device, and the transaction result is returned instantly.

In a successful transaction, the returned paymentId is used for subsequent operations such as refund, void, and transaction queries.

The document type is specified using the saleDocumentType field:

1 → e-Invoice 9 → Expense Receipt

post

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

/v2/terminal-host/gmu/payment

Performs a standard sale transaction via the GMU device. saleDocumentType=1 can be used for e-Invoice and saleDocumentType=9 for Expense Slip.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer Token authentication is performed using the access token.

Header parameters

Content-TypestringRequired

Content type

Example: application/json

Body

application/json

localestringOptional

Language code. Default is TR

Example: TR

conversationIdstringOptional

Request correlation ID. If left empty, a UUID is generated automatically.

Example: a1b2c3

deviceUniqueIdstringRequired

Unique identifier of the device. Maximum 64 characters

Example: P00134

transactionReferenceIdstringRequired

Unique reference ID assigned by the caller for this transaction. It can be used in void and query operations.

Example: REF-12345

pricedecimalRequired

Gross amount. Must be positive

Example: 123.45

paidPricedecimalRequired

Final payable amount. Must be positive

Example: 123.45

paymentTypestring · enumRequired

Payment type. Card, Cash, etc.

Example: CARDPossible values:

currencystring · enumOptional

Currency. Default is TRY

Example: TRYPossible values:

installmentintegerOptional

Installment count. Default is 1

Example: 1

saleAppNamestringRequired

Name of the sale application

Example: MyPOS

saleAppVersionstringRequired

Version of the sale application

Example: 1.0.0

saleDocumentTypestring · enumRequired

Document type. 1 for e-Invoice, 9 for Expense Slip

Example: 1Possible values:

notificationPhonestringOptional

Phone number requested for SMS notification

Example: 5551234567

notificationEmailstringOptional

Email address requested for notification

Example: [email protected]

Responses

200

Successful transaction result

application/json

statusstringOptional

success or failure

Example: success

errorCodestringOptional

Error code. Returns 0 for successful transactions

Example: 0

errorMessagestringOptional

Error message

Example: Error message

conversationIdstringOptional

Correlation ID matching the request

Example: conv-001

systemTimeintegerOptional

transaction time epoch ms

Example: 1743980400000

deviceUniqueIdstringOptional

ID of the device used in the transaction

Example: P00134

transactionReferenceIdstringOptional

Reference ID of the caller

Example: REF-12345

transactionDateTimestringOptional

Date and time when the transaction occurred

Example: 2026-04-06 10:00:00

paymentIdstringOptional

Generated payment ID. Used in refund and void operations.

Example: PAY-9876543

paymentDateintegerOptional

Payment date. In YYYYMMDD format

Example: 20260406

pricedecimalOptional

Transaction amount

Example: 118

installmentintegerOptional

Installment count

Example: 1

acquirerIdstringOptional

Acquirer bank ID

Example: 12

bankMerchantIdstringOptional

Bank merchant number

Example: 000000001234

bankTerminalIdstringOptional

Bank terminal ID

Example: 00001234

issuerIdstringOptional

Card issuer institution ID

Example: 59

currencystring · enumOptional

Currency

Example: TRYPossible values:

authCodestringOptional

Authorization code

Example: 123456

binNumberstringOptional

BIN number of the card. First 6 digits

Example: 454671

lastFourDigitsstringOptional

Last 4 digits of the card

Example: 1234

hostReferencestringOptional

Host reference number

Example: HOST-001

cardTypestringOptional

Card type. Example CREDIT or DEBIT

Example: CREDIT

batchNostringOptional

Batch number

Example: 001

stanNostringOptional

STAN number

Example: 00001

posEntryModeCodestringOptional

POS entry mode code

Example: 05

saleNumberstringOptional

Sale number. Used in partial payment add and complete services referenced in items 7 and 8

Example: SALE-1

400

Invalid request

application/json

post

/v2/terminal-host/gmu/payment

HTTPcURL

POST /v2/terminal-host/gmu/payment HTTP/1.1
Host: api.iyzipay.com
Authorization: Bearer {{access_token}}
Content-Type: application/json

{
  "locale": "TR",
  "conversationId": "conv-001",
  "deviceUniqueId": "P00134",
  "transactionReferenceId": "REF-12345",
  "price": 118.0,
  "paidPrice": 118.0,
  "currency": "TRY",
  "installment": 1,
  "saleAppName": "MyPOS",
  "saleAppVersion": "1.0.0",
  "saleDocumentType": "1",
  "notificationPhone": "5551234567",
  "notificationEmail": "[email protected]",
  "saleItems": [
    {
      "name": "Laptop",
      "generic": false,
      "unitCode": "C62",
      "taxGroupCode": "VAT20",
      "itemQuantity": 1,
      "unitPriceAmount": 100.0,
      "grossPriceAmount": 118.0,
      "totalPriceAmount": 118.0
    }
  ],
  "buyerInfo": null
}

{
  "status": "success",
  "errorCode": "0",
  "conversationId": "conv-001",
  "systemTime": 1743980400000,
  "deviceUniqueId": "P00134",
  "transactionReferenceId": "REF-12345",
  "transactionDateTime": "2026-04-06 10:00:00",
  "paymentId": "PAY-9876543",
  "paymentDate": 20260406,
  "price": 118,
  "installment": 1,
  "acquirerId": "12",
  "bankMerchantId": "000000001234",
  "bankTerminalId": "00001234",
  "issuerId": "59",
  "currency": "TRY",
  "authCode": "123456",
  "binNumber": "454671",
  "lastFourDigits": "1234",
  "hostReference": "HOST-001",
  "cardType": "CREDIT",
  "batchNo": "001",
  "stanNo": "00001",
  "posEntryModeCode": "05",
  "saleItems": [],
  "saleNumber": "SALE-1"
}

Transaction Query

post

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

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

Queries the current status of a payment, refund, or void transaction. A query can be made with paymentId or transactionReferenceId, or both can be sent together.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer Token authentication is performed using the access token.

Header parameters

Content-TypestringRequired

Content type

Example: application/json

Body

application/json

At least one of paymentId or transactionReferenceId must be sent.

localestringOptional

Language code

Example: TR

conversationIdstringOptional

Correlation ID

Example: query-conv-001

paymentIdstringOptional

Payment ID information for the transaction to be queried

Example: PAY-9876543

deviceUniqueIdstringOptional

Device unique ID

Example: P00134

transactionReferenceIdstringOptional

transactionReferenceId sent when initiating the transaction to be queried

Example: REF-12345

Responses

200

Successful transaction status query result

application/json

statusstringOptional

success or failure

Example: success

errorCodestringOptional

Error code. Returns 0 for successful transactions

Example: 0

errorMessagestringOptional

Error message

Example: Error message

conversationIdstringOptional

Correlation ID matching the request

Example: conv-001

systemTimeintegerOptional

transaction time epoch ms

Example: 1743980400000

deviceUniqueIdstringOptional

ID of the device used in the transaction

Example: P00134

transactionReferenceIdstringOptional

Reference ID of the caller

Example: REF-12345

transactionDateTimestringOptional

Date and time when the transaction occurred

Example: 2026-04-06 10:00:00

paymentIdstringOptional

Generated payment ID. Used in refund and void operations.

Example: PAY-9876543

paymentDateintegerOptional

Payment date. In YYYYMMDD format

Example: 20260406

pricedecimalOptional

Transaction amount

Example: 118

installmentintegerOptional

Installment count

Example: 1

acquirerIdstringOptional

Acquirer bank ID

Example: 12

bankMerchantIdstringOptional

Bank merchant number

Example: 000000001234

bankTerminalIdstringOptional

Bank terminal ID

Example: 00001234

issuerIdstringOptional

Card issuer institution ID

Example: 59

currencystring · enumOptional

Currency

Example: TRYPossible values:

authCodestringOptional

Authorization code

Example: 123456

binNumberstringOptional

BIN number of the card. First 6 digits

Example: 454671

lastFourDigitsstringOptional

Last 4 digits of the card

Example: 1234

hostReferencestringOptional

Host reference number

Example: HOST-001

cardTypestringOptional

Card type. Example CREDIT or DEBIT

Example: CREDIT

batchNostringOptional

Batch number

Example: 001

stanNostringOptional

STAN number

Example: 00001

posEntryModeCodestringOptional

POS entry mode code

Example: 05

saleNumberstringOptional

Sale number. Used in partial payment add and complete services referenced in items 7 and 8

Example: SALE-1

cancelHostReferencestring · nullableOptional

Host reference of the void transaction if the payment has been voided

Example: HOST-CANCEL-001

refundHostReferencestring · nullableOptional

Host reference of the refund transaction if the payment has been refunded

Example: HOST-REFUND-001

400

Invalid request

application/json

post

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

HTTPcURL

POST /v2/terminal-host/gmu/payment/query-transaction-status HTTP/1.1
Host: api.iyzipay.com
Authorization: Bearer {{access_token}}
Content-Type: application/json

{
  "locale": "TR",
  "conversationId": "query-conv-001",
  "paymentId": "PAY-9876543",
  "deviceUniqueId": "P00134",
  "transactionReferenceId": "REF-12345"
}

{
  "status": "success",
  "errorCode": "0",
  "conversationId": "query-conv-001",
  "systemTime": 1743980400000,
  "deviceUniqueId": "P00134",
  "transactionReferenceId": "REF-12345",
  "transactionDateTime": "2026-04-06 10:00:00",
  "paymentId": "PAY-9876543",
  "paymentDate": 20260406,
  "price": 118,
  "installment": 1,
  "acquirerId": "12",
  "bankMerchantId": "000000001234",
  "bankTerminalId": "00001234",
  "issuerId": "59",
  "currency": "TRY",
  "authCode": "123456",
  "binNumber": "454671",
  "lastFourDigits": "1234",
  "hostReference": "HOST-001",
  "cardType": "CREDIT",
  "batchNo": "001",
  "stanNo": "00001",
  "posEntryModeCode": "05",
  "saleItems": [],
  "saleNumber": "SALE-1",
  "cancelHostReference": null,
  "refundHostReference": null
}