Refund & Cancel

Refund

post

Used to refund a payment. The refund is executed over paymentTransactionId (per basket item). You can perform a full or partial refund for the payment amount.

Header parameters

AuthorizationstringRequired

Authorization header; a signed hash value that starts with IYZWSv2 and is generated in Base64 format.

Example: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=

Content-TypestringRequired

Content type of the request body.

Example: application/json

Body

application/json

paymentTransactionIdstringRequired

Basket item (payment breakdown) identifier (paymentTransactionId) to be refunded.

Example: 27169345

conversationIdstringOptional

Unique ID for request/response correlation.

Example: 123456789

ipstringOptional

IP address the request is sent from.

Example: 1.1.1.1

localestring · enumOptional

Response language.

Possible values:

pricedecimalRequired

Amount to refund. Must not exceed the item price.

Example: 5

currencystringOptional

Payment currency.

Example: TRY

Responses

200

Successful response

application/json

400

Error response

application/json

post

HTTPcURL

POST https://api.iyzipay.com/payment/refund
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "conversationId": "conversationId",
  "paymentTransactionId": "27169345",
  "price": 5,
  "ip": "85.34.78.112",
  "currency": "TRY"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755703798426,
  "conversationId": "conversationId",
  "paymentId": "25180188",
  "paymentTransactionId": "27169345",
  "price": 5,
  "currency": "TRY",
  "authCode": "512821",
  "hostReference": "mock00007iyzihostrfn",
  "refundHostReference": "mock00007iyzihostrfn",
  "retryable": false,
  "signature": "269ce670ac4027fc95644812d38bc1c3c3897848573215c5bf03e8dd86b328fd"
}

Refund V2

post

Enables refunds over paymentId. No item breakdown is required; the system determines the basket item to refund. You can perform a full or partial refund for the payment amount.

Header parameters

AuthorizationstringRequired

Authorization header; a signed hash value that starts with IYZWSv2 and is generated in Base64 format.

Example: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=

Content-TypestringRequired

Content type of the request body.

Example: application/json

Body

application/json

paymentIdstringRequired

Payment identifier to be refunded.

Example: 25180208

conversationIdstringOptional

Unique ID for request/response correlation.

Example: 123456789

ipstringOptional

IP address the request is sent from.

Example: 1.1.1.1

localestring · enumOptional

Response language.

Example: enPossible values:

pricedecimalRequired

Amount to refund. Must not exceed the payment total.

Example: 5

currencystringOptional

Payment currency.

Example: TRY

Responses

200

Successful response

application/json

400

Error response

application/json

post

HTTPcURL

POST https://api.iyzipay.com/v2/payment/refund
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "conversationId": "123456789",
  "price": 15,
  "paymentId": "25180208",
  "currency": "TRY",
  "ip": "1.1.1.1"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755704177107,
  "conversationId": "123456789",
  "paymentId": "25180208",
  "price": 15,
  "currency": "TRY",
  "authCode": "581421",
  "hostReference": "mock00007iyzihostrfn",
  "refundHostReference": "mock00007iyzihostrfn",
  "retryable": false,
  "signature": "429ba48e9eef33c89cc942e626c8f4aa4a4784fdc82df64f252caa5ad6233db9"
}

Cancel

post

Used to cancel a payment.

Header parameters

AuthorizationstringRequired

Authorization header; a signed hash value that starts with IYZWSv2 and is generated in Base64 format.

Example: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=

Content-TypestringRequired

Content type of the request body.

Example: application/json

Body

application/json

paymentIdstringRequired

The unique payment number assigned by iyzico for the payment you want to cancel.

Example: 25180158

conversationIdstringOptional

Unique ID for request/response correlation. Returned as-is in the response.

Example: 123456789

ipstringOptional

IP address the request is sent from.

Example: 1.1.1.1

localestring · enumOptional

Response language for iyzico messages.

Example: enPossible values:

Responses

200

Successful response

application/json

400

Error response

application/json

post

HTTPcURL

POST https://api.iyzipay.com/payment/cancel
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "conversationId": "123456789",
  "paymentId": "24511629",
  "ip": "1.1.1.1"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755703480229,
  "conversationId": "123456789",
  "paymentId": "25180158",
  "price": 50,
  "currency": "TRY",
  "authCode": "532238",
  "hostReference": "mock00007iyzihostrfn",
  "cancelHostReference": "mock00007iyzihostrfn"
}