Partial Payment

Enables collecting a single sale in multiple parts using different payment methods.

In the partial payment flow, the process is not completed and no fiscal record is created until the Complete call is made.

Initialize Partial Payment

post

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

Starts the partial payment flow where the same sale can be covered by different payment instruments. The returned saleNumber is used in the following steps.

Authorizations

AuthorizationstringRequired

Bearer Token authentication is performed using the access token.

Header parameters

Content-TypestringRequired

Content type

Example: application/json

Body

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: customer@example.com

Responses

200

Successful partial payment start result

application/json

statusstringOptional

success or failure

Example: success

errorCodestringOptional

Error code

Example: 0

errorMessagestringOptional

Error message

Example: Error message

conversationIdstringOptional

Correlation ID

Example: partial-conv-001

systemTimeintegerOptional

Timestamp epoch ms

Example: 1743980400000

saleNumberstringOptional

Main payment ID representing the partial payment flow. Used in Add Partial Payment and Complete Partial Payment steps.

Example: PARENT-001

remainingPaymentAmountdecimalOptional

Remaining unpaid amount

Example: 118

400

Invalid request

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": "customer@example.com",
  "saleItems": [
    {
      "name": "Laptop",
      "generic": false,
      "unitCode": "C62",
      "taxGroupCode": "VAT20",
      "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

Adds a new payment to an initiated partial payment flow. It can be called multiple times until the remaining amount becomes zero.

Authorizations

AuthorizationstringRequired

Bearer Token authentication is performed using the access token.

Header parameters

Content-TypestringRequired

Content type

Example: application/json

Body

localestringOptional

Language code

Example: TR

conversationIdstringOptional

Correlation ID

Example: add-conv-001

deviceUniqueIdstringOptional

Device unique ID

Example: P00134

transactionReferenceIdstringOptional

Reference ID of this add payment transaction

Example: REF-ADD-001

saleNumberstringRequired

saleNumber returned from the Start step

Example: PARENT-001

pricedecimalRequired

Amount to be paid in this step. Must not exceed the remaining amount

Example: 50

installmentintegerOptional

Installment count. Default is 1

Example: 1

currencystringOptional

Currency

Example: TRY

Responses

200

Successful partial payment add 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/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"
}

Complete Partial Payment

post

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

Closes the flow and finalizes the sale after all partial payments are added. Returns the full sale response.

Authorizations

AuthorizationstringRequired

Bearer Token authentication is performed using the access token.

Header parameters

Content-TypestringRequired

Content type

Example: application/json

Body

localestringOptional

Language code

Example: TR

conversationIdstringOptional

Correlation ID

Example: comp-conv-001

deviceUniqueIdstringRequired

Device unique ID. Maximum 64 characters

Example: P00134

transactionReferenceIdstringRequired

Reference ID of this completion transaction

Example: REF-COMP-001

saleNumberstringRequired

saleNumber returned from the Start Partial Payment step

Example: PARENT-001

Responses

200

Successful partial payment completion 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

remainingPaymentAmountdecimalOptional

Remaining payment amount. It must be 0 when completion is successful

Example: 0

400

Invalid request

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
}

PreviousPayment and Transaction Services

NextVoid / Refund

Last updated 4 months ago