Kısmi Ödeme

Bir satışın farklı ödeme yöntemleri ile parçalı olarak tahsil edilmesini sağlar.

Kısmi ödeme akışında Complete çağrılmadan akış tamamlanmaz ve mali kayıt oluşmaz.

Kısmi Ödeme Başlatma

post

/v2/terminal-host/gmu/partial-payment/start

Aynı satışın farklı ödeme araçlarıyla karşılanabileceği kısmi ödeme akışını başlatır. Dönen saleNumber sonraki adımlarda kullanılır.

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: musteri@ornek.com

Responses

200

Başarılı kısmi ödeme başlatma sonucu

application/json

statusstringOptional

success veya failure

Example: success

errorCodestringOptional

Hata kodu

Example: 0

errorMessagestringOptional

Hata mesajı

Example: Hata mesajı

conversationIdstringOptional

Korelasyon ID

Example: partial-conv-001

systemTimeintegerOptional

Zaman damgası epoch ms

Example: 1743980400000

saleNumberstringOptional

Kısmi ödeme akışını temsil eden ana ödeme ID'si. Add Partial Payment ve Complete Partial Payment adımlarında kullanılır.

Example: PARENT-001

remainingPaymentAmountdecimalOptional

Henüz ödenmemiş kalan tutar

Example: 118

400

Hatalı istek

application/json

post/v2/terminal-host/gmu/partial-payment/start

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

{
  "locale": "TR",
  "conversationId": "partial-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": "musteri@ornek.com",
  "saleItems": [
    {
      "name": "Laptop",
      "generic": false,
      "unitCode": "C62",
      "taxGroupCode": "KDV20",
      "itemQuantity": 1,
      "unitPriceAmount": 100.0,
      "grossPriceAmount": 118.0,
      "totalPriceAmount": 118.0
    }
  ],
  "buyerInfo": null
}

{
  "status": "success",
  "conversationId": "partial-conv-001",
  "systemTime": 1743980400000,
  "saleNumber": "PARENT-001",
  "remainingPaymentAmount": 118
}

Ödeme İşlemi Ekleme

post

/v2/terminal-host/gmu/partial-payment/add-payment

Başlatılmış kısmi ödeme akışına yeni bir ödeme ekler. Kalan tutar sıfırlanana kadar birden fazla kez çağrı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

Example: TR

conversationIdstringOptional

Korelasyon ID

Example: add-conv-001

deviceUniqueIdstringOptional

Cihaz benzersiz ID

Example: P00134

transactionReferenceIdstringOptional

Bu ekleme işleminin referans ID'si

Example: REF-ADD-001

saleNumberstringRequired

Start adımından dönen saleNumber

Example: PARENT-001

pricedecimalRequired

Bu adımda ödenecek tutar. Kalan tutarı aşmamalıdır

Example: 50

installmentintegerOptional

Taksit sayısı. Varsayılan 1

Example: 1

currencystringOptional

Para birimi

Example: TRY

Responses

200

Başarılı kısmi ödeme ekleme 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/partial-payment/add-payment

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

{
  "locale": "TR",
  "conversationId": "add-conv-001",
  "deviceUniqueId": "P00134",
  "transactionReferenceId": "REF-ADD-001",
  "saleNumber": "PARENT-001",
  "price": 50.0,
  "installment": 1,
  "currency": "TRY"
}

{
  "status": "success",
  "errorCode": "0",
  "conversationId": "add-conv-001",
  "systemTime": 1743980400000,
  "deviceUniqueId": "P00134",
  "transactionReferenceId": "REF-ADD-001",
  "transactionDateTime": "2026-04-06 10:00:00",
  "paymentId": "PAY-9876543",
  "paymentDate": 20260406,
  "price": 50,
  "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": "PARENT-001"
}

Kısmi Ödemeyi Tamamla

post

/v2/terminal-host/gmu/partial-payment/complete

Tüm kısmi ödemeler eklendikten sonra akışı kapatır ve satışı sonuçlandırır. Tam satış yanıtı döner.

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

Example: TR

conversationIdstringOptional

Korelasyon ID

Example: comp-conv-001

deviceUniqueIdstringRequired

Cihaz benzersiz ID. Maksimum 64 karakter

Example: P00134

transactionReferenceIdstringRequired

Bu tamamlama işleminin referans ID'si

Example: REF-COMP-001

saleNumberstringRequired

Start partial payment adımından dönen saleNumber

Example: PARENT-001

Responses

200

Başarılı kısmi ödeme tamamlama 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

remainingPaymentAmountdecimalOptional

Kalan ödeme tutarı. Başarılı tamamlamada 0 olmalıdır

Example: 0

400

Hatalı istek

application/json

post/v2/terminal-host/gmu/partial-payment/complete

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

{
  "locale": "TR",
  "conversationId": "comp-conv-001",
  "deviceUniqueId": "P00134",
  "transactionReferenceId": "REF-COMP-001",
  "saleNumber": "PARENT-001"
}

{
  "status": "success",
  "errorCode": "0",
  "conversationId": "comp-conv-001",
  "systemTime": 1743980400000,
  "deviceUniqueId": "P00134",
  "transactionReferenceId": "REF-COMP-001",
  "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": "PARENT-001",
  "remainingPaymentAmount": 0
}

Kısmi Ödemeyi İptal Etme

post

/v2/terminal-host/gmu/partial-payment/void

Kısmi ödeme işlemini iptal etmek için kullanılır.

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

deviceUniqueIdstringRequired

Cihazın benzersiz kimliği (max 64 karakter)

Example: PAV860047264

saleNumberstringRequired

İptal edilecek satışın satış numarası

Example: Lk355EIiG6

transactionReferenceIdstringRequired

Bu iade işlemine ait referans ID

Example: 1787641533594

reasonstringOptional

İptal nedeni

Example: 1

descriptionstringOptional

İptal işlemi ile ilgili açıklama

Example: 1

Responses

200

Başarılı kısmi ödeme iptal sonucu

application/json

statusstringOptional

İşlem sonucu. success veya failure döner.

Example: success

errorCodestringOptional

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

Example: 0

errorMessagestringOptional

Hata mesajı

conversationIdstringOptional

İstek ile eşleşen korelasyon ID

Example: Conversation9627

systemTimeintegerOptional

İşlem zaman damgası (Unix epoch, milisaniye)

Example: 0

deviceUniqueIdstringOptional

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

Example: PAV860047264

transactionReferenceIdstringOptional

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

Example: 1787641533594

saleNumberstringOptional

İptal edilen satışın satış numarası

Example: Lk355EIiG6

400

Hatalı istek

application/json

post/v2/terminal-host/gmu/partial-payment/void

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

{
  "locale": "TR",
  "conversationId": "Conversation9627",
  "deviceUniqueId": "PAV860047264",
  "saleNumber": "Lk355EIiG6",
  "transactionReferenceId": "1787641533594",
  "reason": "1",
  "description": "1"
}

{
  "status": "success",
  "errorCode": "0",
  "errorMessage": "",
  "systemTime": 0,
  "saleNumber": "Lk355EIiG6",
  "voidPaymentResponses": [
    {
      "status": "success",
      "errorCode": "0",
      "systemTime": 1787641545261,
      "deviceUniqueId": "PAV860047264",
      "transactionReferenceId": "1787641534133",
      "paymentId": "37468015",
      "price": 65,
      "authCode": "239707",
      "hostReference": "623707193853",
      "binNumber": "520019",
      "lastFourDigits": "2096"
    }
  ]
}

Last updated 20 days ago