Ödeme ve İşlem Servisleri

Satış İşlemi

Bu servis, GMU cihazı üzerinden standart satış işlemi gerçekleştirmek için kullanılır.

Satış işlemi sırasında, ödeme tutarı ve satış kalemleri POS cihazına iletilir ve işlem sonucu anlık olarak yanıtlanır.

Başarılı işlem sonucunda dönen paymentId, iade, iptal ve sorgulama işlemlerinde kullanılır.

saleDocumentType alanı ile belge tipi belirlenir:
1 → E-Fatura 9 → Gider Pusulası

post

/v2/terminal-host/gmu/payment

GMU cihazı üzerinden standart satış işlemi gerçekleştirir. E-Fatura için saleDocumentType=1, Gider Pusulası için saleDocumentType=9 kullanılabilir.

Authorizations

AuthorizationstringRequired

Access token kullanılarak Bearer Token doğrulaması yapılır.

Header parameters

Content-TypestringRequired

İçerik tipi

Example: application/json

Body

localestringOptional

Dil kodu. Varsayılan TR

Example: TR

conversationIdstringOptional

İstek korelasyon ID’si. Boş bırakılırsa otomatik UUID atanır.

Example: a1b2c3

deviceUniqueIdstringRequired

Cihazın benzersiz kimliği. Maksimum 64 karakter

Example: P00134

transactionReferenceIdstringRequired

Çağıran tarafın bu işleme atadığı benzersiz referans ID. İptal ve sorgulama işlemlerinde kullanılabilir.

Example: REF-12345

pricedecimalRequired

Brüt tutar. Pozitif olmalıdır

Example: 123.45

paidPricedecimalRequired

Ödenecek nihai tutar. Pozitif olmalıdır

Example: 123.45

paymentTypestring · enumRequired

Ödeme türü. (Kart, Nakit vb.)

Example: CARDPossible values:

currencystring · enumOptional

Para birimi. Varsayılan TRY

Example: TRYPossible values:

installmentintegerOptional

Taksit sayısı. Varsayılan 1

Example: 1

saleAppNamestringRequired

Satış uygulamasının adı

Example: MyPOS

saleAppVersionstringRequired

Satış uygulamasının versiyonu

Example: 1.0.0

saleDocumentTypestring · enumRequired

Belge tipi. E-Fatura için 1, Gider Pusulası için 9

Example: 1Possible values:

notificationPhonestringOptional

SMS bildirimi istenilen telefon numarası

Example: 5551234567

notificationEmailstringOptional

Bildirim istenilen E-posta adresi

Example: [email protected]

Responses

200

Başarılı işlem sonucu

application/json

statusstringOptional

success veya failure

Example: success

errorCodestringOptional

Hata kodu. Başarılı işlemlerde 0 döner

Example: 0

errorMessagestringOptional

Hata mesajı

Example: Hata mesajı

conversationIdstringOptional

İstek ile eşleşen korelasyon ID

Example: conv-001

systemTimeintegerOptional

işlem zamanı (epoch ms)

Example: 1743980400000

deviceUniqueIdstringOptional

İşlem yapılan cihazın ID'si

Example: P00134

transactionReferenceIdstringOptional

Çağıran tarafın referans ID'si

Example: REF-12345

transactionDateTimestringOptional

İşlemin gerçekleştiği tarih ve saat

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

paymentIdstringOptional

Oluşturulan ödeme ID. İade ve iptal işlemlerinde kullanılır.

Example: PAY-9876543

paymentDateintegerOptional

Ödeme tarihi. YYYYMMDD formatındadır

Example: 20260406

pricedecimalOptional

İşlem tutarı

Example: 118

installmentintegerOptional

Taksit sayısı

Example: 1

acquirerIdstringOptional

Acquirer banka ID

Example: 12

bankMerchantIdstringOptional

Banka üye işyeri numarası

Example: 000000001234

bankTerminalIdstringOptional

Banka terminal ID

Example: 00001234

issuerIdstringOptional

Kartı çıkaran kuruluş ID

Example: 59

currencystring · enumOptional

Para birimi

Example: TRYPossible values:

authCodestringOptional

Onay kodu

Example: 123456

binNumberstringOptional

Kartın BIN numarası. İlk 6 hanedir

Example: 454671

lastFourDigitsstringOptional

Kartın son 4 hanesi

Example: 1234

hostReferencestringOptional

Host referans numarası

Example: HOST-001

cardTypestringOptional

Kart tipi. Örnek CREDIT veya DEBIT

Example: CREDIT

batchNostringOptional

Batch parti numarası

Example: 001

stanNostringOptional

STAN numarası

Example: 00001

posEntryModeCodestringOptional

POS giriş modu kodu

Example: 05

saleNumberstringOptional

Satış numarası. Parçalı ödeme ekleme 7. madde ve tamamlama 8. madde servislerinde kullanılır

Example: SALE-1

400

Hatalı istek

application/json

post

/v2/terminal-host/gmu/payment

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

İşlem Sorgulama

post

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

Bir ödeme, iade veya iptal işleminin güncel durumu sorgulanır. paymentId veya transactionReferenceId ile sorgu yapılabilir, ikisi birlikte de gönderilebilir.

Authorizations

AuthorizationstringRequired

Access token kullanılarak Bearer Token doğrulaması yapılır.

Header parameters

Content-TypestringRequired

İçerik tipi

Example: application/json

Body

paymentId veya transactionReferenceId alanlarından en az biri gönderilmelidir.

localestringOptional

Dil kodu

Example: TR

conversationIdstringOptional

Korelasyon ID

Example: query-conv-001

paymentIdstringOptional

Sorgulanmak istenen işlem için ödeme ID bilgisi

Example: PAY-9876543

deviceUniqueIdstringOptional

Cihaz benzersiz ID

Example: P00134

transactionReferenceIdstringOptional

Sorgulanmak istenen işlemi başlatırken gönderilen transactionReferenceId

Example: REF-12345

Responses

200

Başarılı işlem sorgulama sonucu

application/json

statusstringOptional

success veya failure

Example: success

errorCodestringOptional

Hata kodu. Başarılı işlemlerde 0 döner

Example: 0

errorMessagestringOptional

Hata mesajı

Example: Hata mesajı

conversationIdstringOptional

İstek ile eşleşen korelasyon ID

Example: conv-001

systemTimeintegerOptional

işlem zamanı (epoch ms)

Example: 1743980400000

deviceUniqueIdstringOptional

İşlem yapılan cihazın ID'si

Example: P00134

transactionReferenceIdstringOptional

Çağıran tarafın referans ID'si

Example: REF-12345

transactionDateTimestringOptional

İşlemin gerçekleştiği tarih ve saat

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

paymentIdstringOptional

Oluşturulan ödeme ID. İade ve iptal işlemlerinde kullanılır.

Example: PAY-9876543

paymentDateintegerOptional

Ödeme tarihi. YYYYMMDD formatındadır

Example: 20260406

pricedecimalOptional

İşlem tutarı

Example: 118

installmentintegerOptional

Taksit sayısı

Example: 1

acquirerIdstringOptional

Acquirer banka ID

Example: 12

bankMerchantIdstringOptional

Banka üye işyeri numarası

Example: 000000001234

bankTerminalIdstringOptional

Banka terminal ID

Example: 00001234

issuerIdstringOptional

Kartı çıkaran kuruluş ID

Example: 59

currencystring · enumOptional

Para birimi

Example: TRYPossible values:

authCodestringOptional

Onay kodu

Example: 123456

binNumberstringOptional

Kartın BIN numarası. İlk 6 hanedir

Example: 454671

lastFourDigitsstringOptional

Kartın son 4 hanesi

Example: 1234

hostReferencestringOptional

Host referans numarası

Example: HOST-001

cardTypestringOptional

Kart tipi. Örnek CREDIT veya DEBIT

Example: CREDIT

batchNostringOptional

Batch parti numarası

Example: 001

stanNostringOptional

STAN numarası

Example: 00001

posEntryModeCodestringOptional

POS giriş modu kodu

Example: 05

saleNumberstringOptional

Satış numarası. Parçalı ödeme ekleme 7. madde ve tamamlama 8. madde servislerinde kullanılır

Example: SALE-1

cancelHostReferencestring · nullableOptional

İptal yapılmışsa iptal işlemine ait host referansı

Example: HOST-CANCEL-001

refundHostReferencestring · nullableOptional

İade yapılmışsa iade işlemine ait host referansı

Example: HOST-REFUND-001

400

Hatalı istek

application/json

post

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

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
}

Last updated 28 days ago

hashtagSatış İşlemi

hashtagİşlem Sorgulama

Satış İşlemi

İşlem Sorgulama