Ödeme ve İşlem Servisleri

Complete Payment

post

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

/v2/terminal-host/payment/complete

Bu servis, terminal üzerinde ödeme işlemini başlatır. Pos cihazı üzerinde kart okutularak ödeme işlemi tamamlanır. Örnek: "Satış uygulamasının başlattığı işlemi complete ederek ödemeId/authCode vb. alanları alırsınız."

Authorization (Bearer Token):

• Token değeri OAuth token servisinden dönen access_token'dır.

• Header formatı: Authorization: Bearer {access_token}

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer Token ile yetkilendirme. Header formatı: Authorization: Bearer {access_token}

access_token, OAuth token servisinden üretilir ve Terminal Host servislerinde kullanılır.

Body

application/json

conversationIdstringRequired

İstek ve yanıt eşleşmesi yapılacak ID değeri. Üye işyeri tarafından belirlenir, istekte gönderilen bilgi yanıtta geri döner.

localestring · enumRequired

Yanıt dili.

Possible values:

deviceUniqueIdstringRequired

İşlemin gerçekleştirildiği terminal / cihaz için tanımlı benzersiz kimlik bilgisi.

transactionReferenceIdstringRequired

Satış uygulaması tarafından üretilen, bu satış işlemine ait uniqueId değeri.

pricenumber · doubleRequired

Fiyat Değeri

currencystringRequired

Para birimi

installmentinteger · enumRequired

Taksit Sayısı

Possible values:

Responses

200Success

application/json

400Error

application/json

post

/v2/terminal-host/payment/complete

HTTPcURLJavaScriptPython

POST /v2/terminal-host/payment/complete HTTP/1.1
Host: api.iyzipay.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 161

{
  "conversationId": "conversation1",
  "locale": "TR",
  "deviceUniqueId": "PAV860047264",
  "transactionReferenceId": "string16",
  "price": 100,
  "currency": "TRY",
  "installment": 0
}

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

Örnek Collection

Postman

Query Transaction Status

post

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

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

Bu servis, daha önce gerçekleşen bir işlemin durumunu sorgular. Örnek: "paymentId ile ödeme durumunu ve varsa hata bilgilerini öğrenirsiniz."

Authorization (Bearer Token):

• Token değeri OAuth token servisinden dönen access_token'dır.

• Header formatı: Authorization: Bearer {access_token}

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer Token ile yetkilendirme. Header formatı: Authorization: Bearer {access_token}

access_token, OAuth token servisinden üretilir ve Terminal Host servislerinde kullanılır.

Body

application/json

İşlemin Durumunu Sorgulayan Servis.

conversationIdstringRequired

İstek ve yanıt eşleşmesi yapılacak ID değeri. Üye işyeri tarafından belirlenir, istekte gönderilen bilgi yanıtta geri döner.

localestring · enumRequired

Yanıt dili.

Possible values:

paymentIdstringRequired

Sorgulanacak Ödeme Numarası

deviceUniqueIdstringRequired

İşlemin gerçekleştirildiği terminal / cihaz için tanımlı benzersiz kimlik bilgisi.

transactionReferenceIdone of | nullableRequired

Sorgulanmak istenen payment/ void/refund işlemi için işlem sırasında üretilmiş eşsiz referans numarasıdır.

stringOptional

or

nullOptional

Responses

200Success

application/json

400Error

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 – Önemli Not

Query Status servisinde paymentId, transactionReferenceId ve deviceUniqueId alanlarının tamamı aynı anda zorunlu değildir. Servisin çalışabilmesi için aşağıdaki alan kombinasyonlarından en az biri gönderilmelidir:

• Sadece paymentId gönderilirse İlgili satış (payment) işleminin bilgileri döner.

• transactionReferenceId + deviceUniqueId birlikte gönderilirse İlgili payment / void / refund işlemleri sorgulanabilir.

• paymentId + transactionReferenceId birlikte gönderilirse Satış işlemi ile birlikte, ödeme ilişkili void ve refund işlemleri de sorgulanabilir.

Örnek Collection

Postman

Void Payment

post

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

/v2/terminal-host/payment/void

Bu servis, uygun durumdaki bir ödemeyi iptal eder. Örnek: "paymentId ve paymentDate ile iptal işlemi başlatılır. Kart pos cihazı üzerinde okutularak iptal işlemi tamamlanır."

Authorization (Bearer Token):

• Token değeri OAuth token servisinden dönen access_token'dır.

• Header formatı: Authorization: Bearer {access_token}

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer Token ile yetkilendirme. Header formatı: Authorization: Bearer {access_token}

access_token, OAuth token servisinden üretilir ve Terminal Host servislerinde kullanılır.

Body

application/json

Ödeme İade Servisi.

conversationIdstringRequired

İstek ve yanıt eşleşmesi yapılacak ID değeri. Üye işyeri tarafından belirlenir, istekte gönderilen bilgi yanıtta geri döner.

localestring · enumRequired

Yanıt dili.

Possible values:

paymentIdstringRequired

İptal Edilecek Ödeme Numarası

paymentDatestringRequired

İşlemin muhasebeleştirildiği tarih (YYYYMMDD).

deviceUniqueIdstringRequired

İşlemin gerçekleştirildiği terminal / cihaz için tanımlı benzersiz kimlik bilgisi.

transactionReferenceIdstringRequired

İptal işlemine ait üretilen benzersiz bir referans numarası

reasonstringOptional

İptal nedi

descriptionstringOptional

İptal açıklaması

Responses

200Success

application/json

422Error

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

Örnek Collection

Postman

Refund Payment

post

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

/v2/terminal-host/payment/refund

Bu servis, uygun durumdaki bir ödemeye iade işlemi uygular (partial/total). Örnek: "paymentId ve price ile iade işlemi başlatılır. Kart pos cihazı üzerinde okutularak iptal işlemi tamamlanır."

Authorization (Bearer Token):

• Token değeri OAuth token servisinden dönen access_token'dır.

• Header formatı: Authorization: Bearer {access_token}

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer Token ile yetkilendirme. Header formatı: Authorization: Bearer {access_token}

access_token, OAuth token servisinden üretilir ve Terminal Host servislerinde kullanılır.

Body

application/json

conversationIdstringRequired

İstek ve yanıt eşleşmesi yapılacak ID değeri. Üye işyeri tarafından belirlenir, istekte gönderilen bilgi yanıtta geri döner.

localestring · enumRequired

İstek dili.

Possible values:

paymentIdstringRequired

İade yapılacak ödeme numarası

deviceUniqueIdstringRequired

İşlemin gerçekleştirildiği terminal / cihaz için tanımlı benzersiz kimlik bilgisi.

pricenumber · doubleRequired

İşlem tutarı.

transactionReferenceIdstringRequired

İade işlemi için satış uygulaması tarafından üretilen, benzersiz referans numarası.

reasonstringOptional

İade Nedeni

descriptionstringOptional

İade Açıklaması

Responses

200Success

application/json

400Error

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

Örnek Collection

Postman