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

statusstring · enumOptional

Indicates the outcome of the request.

Possible values:

localestring · enumOptional

Response language.

Possible values:

systemTimeintegerOptional

Current epoch ms at the time of response.

conversationIdstringOptional

Echoes the conversationId sent in the request.

paymentIdstringOptional

Payment number.

paymentTransactionIdstringOptional

Refunded payment item identifier.

pricedecimalOptional

Refunded amount.

currencystringOptional

Currency.

authCodestringOptional

Authorization (auth) code returned by the bank.

Example: 591030

hostReferencestringOptional

Reference value provided by the bank for the payment.

Example: mock00007iyzihostrfn

refundHostReferencestringOptional

Reference value provided by the bank for the refund.

Example: mock00007iyzihostrfn

retryableboolean · enumOptional

Indicates whether the operation can be retried.

Example: truePossible values:

signaturestringOptional

Signature value that can be used for verification.

Example: 8202e30aa0f4c690f640ae4f6d4487b92b57a3693e9d560bbaf938638217271b

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

statusstring · enumOptional

Indicates the outcome of the request.

Possible values:

localestring · enumOptional

Response language.

Possible values:

systemTimeintegerOptional

Current epoch ms at the time of response.

conversationIdstringOptional

Echoes the conversationId sent in the request.

paymentIdstringOptional

Refunded payment identifier.

pricedecimalOptional

Refunded amount.

currencystringOptional

Currency.

authCodestringOptional

Authorization (auth) code returned by the bank.

Example: 591030

hostReferencestringOptional

Reference value provided by the bank for the payment.

Example: mock00007iyzihostrfn

refundHostReferencestringOptional

Reference value provided by the bank for the refund.

Example: mock00007iyzihostrfn

retryableboolean · enumOptional

Indicates whether the operation can be retried.

Example: truePossible values:

signaturestringOptional

Signature value that can be used for verification.

Example: 8202e30aa0f4c690f640ae4f6d4487b92b57a3693e9d560bbaf938638217271b

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

statusstring · enumOptional

Indicates the outcome of the request.

Possible values:

localestring · enumOptional

Response language.

Possible values:

systemTimeintegerOptional

Current epoch ms at the time of response.

conversationIdstringOptional

Echoes the conversationId sent in the request.

paymentIdstringOptional

Canceled payment number.

pricedecimalOptional

Canceled payment amount.

currencystringOptional

Currency (payment currency).

authCodestringOptional

Authorization (auth) code returned by the bank.

Example: 581421

hostReferencestringOptional

Transaction reference value.

Example: mock00007iyzihostrfn

cancelHostReferencestringOptional

Reference value for the cancel transaction.

Example: mock00007iyzihostrfn

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