Refund & Cancel

Overview

A payment processed through iyzico can be refunded within a period of 365 days, 24/7.

Operation covers under two headlines;

• Refund

• Cancel

While It is important to note that the refund transaction will be reflected in the statement, the timing of the refund appearing on the card may vary depending on the respective banks typically taking a few days to complete.

Majority of banks’ are able to cancel any payment within the same day that payment was received (before banks perform their own reconciliation) where the payment will not appear in the credit card statement.

Refund or Cancel a payment only after the payment is charged.

Refund

Refund request processes on a transactional level, means that it can be refund either the entire payment or a partial of it.

To process a refund;

• the payment transaction ID (paymentTransactionId)

• and the amount to be refunded (price) must be provided.

If the refund process is successful, the refunded amount (price) will be returned from the service. The refund amount (price) should be less than or equal to the original transaction amount (itemTransaction.paidPrice) and the remaining refundable amount. As long as this rule is followed, multiple refunds can be made consecutively.

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

/payment/refund

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

Sample Codes

PHP

Java

.Net

Node.js

Python

Postman

Refund V2

Similar to Refund operation, iyzico offers Refund V2 which built upon paymentId instead of paymentTransactionId.

It is strictly not recommended to use the Refund V2 service for orders with more than one product in the basket.

To process a refund v2;

• the paymentID (paymentId)

• and the amount to be refunded (price) must be provided.

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

/v2/payment/refund

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

Sample Codes

PHP

Java

.Net

Postman

Cancel

Similar to refunds, merchant may cancel their transaction with iyzico services.

Important notes that the key distinctions between a cancel and a refund are;

• Cancel can be processed on the same day as the payment and does not create any input/output entries on the card statement.

• And cancel are not supporting partial amounts.

To initiate a cancellation, it is necessary to provide the payment ID (paymentId) associated with the transaction. If the cancellation process is successful, the canceled amount (price) will be returned from the service.

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

/payment/cancel

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

Sample Codes

PHP

Java

.Net

Node.js

Python

Postman