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

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

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

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