Void / Refund

Void

post

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

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

Voids a payment transaction completed on the same day. For transactions closed after end of day, refund should be used instead of void.

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

Correlation ID

Example: void-conv-001

deviceUniqueIdstringRequired

Device unique ID. Maximum 64 characters

Example: P00134

paymentIdstringRequired

paymentId of the payment to be voided

Example: PAY-9876543

paymentDateintegerRequired

Payment date. Must be in YYYYMMDD format

Example: 20260406

transactionReferenceIdstringRequired

Reference ID of this void transaction

Example: REF-VOID-001

reasonstringOptional

Void reason

Example: Customer request

descriptionstringOptional

Description

Example: Product out of stock

Responses

200

Successful void result

application/json

statusstringOptional

success or failure

Example: success

errorCodestringOptional

Error code

Example: 0

errorMessagestringOptional

Error message

Example: Error message

conversationIdstringOptional

Correlation ID

Example: void-conv-001

systemTimeintegerOptional

Timestamp epoch ms

Example: 1743980400000

deviceUniqueIdstringOptional

Device ID

Example: P00134

transactionReferenceIdstringOptional

Void reference ID

Example: REF-VOID-001

paymentIdstringOptional

Voided payment ID

Example: PAY-9876543

pricedecimalOptional

Void amount

Example: 118

currencystringOptional

Currency

Example: TRY

authCodestringOptional

Authorization code

Example: 123456

hostReferencestringOptional

Host reference number of the original transaction

Example: HOST-001

cancelHostReferencestringOptional

Host reference number of the void transaction

Example: HOST-CANCEL-001

transactionDatestringOptional

Transaction date

Example: 2026-04-06

transactionTimestringOptional

Transaction time

Example: 10:00:00

paymentDateintegerOptional

Payment date. In YYYYMMDD format

Example: 20260406

transactionDateTimestringOptional

Transaction date and time information

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

binNumberstringOptional

Card BIN number

Example: 454671

lastFourDigitsstringOptional

Last 4 digits of the card

Example: 1234

400

Invalid request

application/json

post

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

HTTPcURL

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

{
  "locale": "TR",
  "conversationId": "void-conv-001",
  "deviceUniqueId": "P00134",
  "paymentId": "PAY-9876543",
  "paymentDate": 20260406,
  "transactionReferenceId": "REF-VOID-001",
  "reason": "Customer request",
  "description": "Product out of stock"
}

{
  "status": "success",
  "errorCode": "0",
  "conversationId": "void-conv-001",
  "systemTime": 1743980400000,
  "deviceUniqueId": "P00134",
  "transactionReferenceId": "REF-VOID-001",
  "paymentId": "PAY-9876543",
  "price": 118,
  "currency": "TRY",
  "authCode": "123456",
  "hostReference": "HOST-001",
  "cancelHostReference": "HOST-CANCEL-001",
  "transactionDate": "2026-04-06",
  "transactionTime": "10:00:00",
  "paymentDate": 20260406,
  "transactionDateTime": "2026-04-06 10:00:00",
  "binNumber": "454671",
  "lastFourDigits": "1234"
}

Refund

post

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

/v2/terminal-host/gmu/payment/refund

Performs a partial or full refund for a completed sale transaction. It is recommended to call the Refundable Sale Info service first to learn which items can be refunded.

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

Correlation ID

Example: ref-conv-001

deviceUniqueIdstringRequired

Device unique ID. Maximum 64 characters

Example: P00134

paymentIdstringRequired

paymentId returned by the sale service

Example: PAY-9876543

paymentDateintegerRequired

Payment date. Must be in YYYYMMDD format

Example: 20260406

transactionReferenceIdstringRequired

Reference ID of this refund transaction

Example: REF-REFUND-001

saleAppNamestringRequired

Sale application name

Example: MyPOS

saleAppVersionstringRequired

Sale application version

Example: 1.0.0

notificationPhonestringOptional

Phone number requested for SMS notification

Example: 5551234567

notificationEmailstringOptional

Email address requested for notification

Example: [email protected]

Responses

200

Successful refund result

application/json

statusstringOptional

success or failure

Example: success

errorCodestringOptional

Error code

Example: 0

errorMessagestringOptional

Error message

Example: Error message

conversationIdstringOptional

Correlation ID

Example: ref-conv-001

systemTimeintegerOptional

Timestamp epoch ms

Example: 1743980400000

deviceUniqueIdstringOptional

Device ID used in the transaction

Example: P00134

transactionReferenceIdstringOptional

Reference ID of the refund transaction

Example: REF-REFUND-001

pricedecimalOptional

Refund amount

Example: 118

vatAmountdecimalOptional

VAT amount

Example: 18

currencystringOptional

Currency

Example: TRY

invoiceNostringOptional

Invoice number

Example: INV-001

authCodestringOptional

Authorization code

Example: 123456

hostReferencestringOptional

Host reference number

Example: HOST-REFUND-001

binNumberstringOptional

Card BIN number

Example: 454671

lastFourDigitsstringOptional

Last 4 digits of the card

Example: 1234

acquirerNamestringOptional

Acquirer bank name

Example: Bank A

acquirerIdstringOptional

Acquirer bank ID

Example: 12

batchNostringOptional

Batch number

Example: 001

400

Invalid request

application/json

post

/v2/terminal-host/gmu/payment/refund

HTTPcURL

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

{
  "locale": "TR",
  "conversationId": "ref-conv-001",
  "deviceUniqueId": "P00134",
  "paymentId": "PAY-9876543",
  "paymentDate": 20260406,
  "transactionReferenceId": "REF-REFUND-001",
  "saleAppName": "MyPOS",
  "saleAppVersion": "1.0.0",
  "notificationPhone": "5551234567",
  "notificationEmail": "[email protected]",
  "saleItems": [
    {
      "name": "Laptop",
      "unitCode": "C62",
      "taxGroupCode": "VAT20",
      "itemQuantity": 1,
      "unitPriceAmount": 100.0,
      "grossPriceAmount": 118.0,
      "totalPriceAmount": 118.0
    }
  ]
}

{
  "status": "success",
  "errorCode": "0",
  "conversationId": "ref-conv-001",
  "systemTime": 1743980400000,
  "deviceUniqueId": "P00134",
  "transactionReferenceId": "REF-REFUND-001",
  "price": 118,
  "vatAmount": 18,
  "currency": "TRY",
  "invoiceNo": "INV-001",
  "authCode": "123456",
  "hostReference": "HOST-REFUND-001",
  "binNumber": "454671",
  "lastFourDigits": "1234",
  "acquirerName": "Bank A",
  "acquirerId": "12",
  "batchNo": "001"
}

Retrieve Refundable Transaction Information

post

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

/v2/terminal-host/gmu/payment/refundable-sale-info

Returns refundable item and amount information for the sale related to the given transaction reference. It is recommended to call this before the refund operation; the returned saleUid value is used as relatedSaleId in the refund request.

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

Example: TR

conversationIdstringOptional

Correlation ID

Example: rsi-conv-001

deviceUniqueIdstringOptional

Device unique ID

Example: P00134

transactionReferenceIdstringRequired

Reference ID of the original sale transaction

Example: REF-12345

Responses

200

Successful refundable sale info result

application/json

statusstringOptional

success or failure

Example: success

errorCodestringOptional

Error code

Example: 0

errorMessagestringOptional

Error message

Example: Error message

conversationIdstringOptional

Correlation ID

Example: rsi-conv-001

systemTimeintegerOptional

Timestamp epoch ms

Example: 1743980400000

saleNumberstringOptional

Sale number

Example: SN-001

saleUidstringOptional

Unique ID of the sale. Used as relatedSaleId in the refund request.

Example: SALE-001

totalReturnableAmountdecimalOptional

Total refundable amount

Example: 118

currencystringOptional

Currency

Example: TRY

400

Invalid request

application/json

post

/v2/terminal-host/gmu/payment/refundable-sale-info

HTTPcURL

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

{
  "locale": "TR",
  "conversationId": "rsi-conv-001",
  "deviceUniqueId": "P00134",
  "transactionReferenceId": "REF-12345"
}

{
  "status": "success",
  "conversationId": "rsi-conv-001",
  "systemTime": 1743980400000,
  "saleNumber": "SN-001",
  "saleUid": "SALE-001",
  "totalReturnableAmount": 118,
  "currency": "TRY",
  "saleItems": [
    {
      "id": 1,
      "name": "Laptop",
      "itemQuantity": 1,
      "totalPriceAmount": 118,
      "vatAmount": 18,
      "returnableQuantity": 1,
      "returnableAmount": 118
    }
  ]
}