Iyzico Webhooks

generated: '2026-07-19'
method: searched
source: https://docs.iyzico.com/en/advanced/webhook
spec_type: Webhooks
note: >-
  iyzico ships a server-to-server webhook (notification) surface but does not
  publish a machine-readable AsyncAPI document, so this captures the webhook
  catalog (type: Webhooks) rather than an AsyncAPI spec.
delivery:
  transport: HTTP POST (JSON payload), server-to-server
  first_attempt: 10-15 seconds after the initial payment attempt
  retry: Every 15 minutes until the merchant server responds 2xx; stops after 3 attempts
  ack: HTTP 2xx
configuration: iyzico control panel — Settings > Merchant Settings (per-URL, incl. Merchant Subscription Notifications)
signature:
  header: X-IYZ-SIGNATURE-V3
  algorithm: HMACSHA256 over an ordered concatenation, encoded as HEX
  payment_formula: HMACSHA256(secretKey + iyziEventType + paymentId + paymentConversationId + status)
  hpp_formula: HMACSHA256(secretKey + iyziEventType + iyziPaymentId + token + paymentConversationId + status)
  deprecated: [X-Iyz-Signature, X-Iyz-Signature-V2]
  activation: Signature feature enabled per account via entegrasyon@iyzico.com
formats:
- name: API (NON-3DS / 3DS)
  key_fields: [paymentConversationId, paymentId, status, iyziEventType, iyziPaymentId]
  statuses: [FAILURE, SUCCESS, INIT_THREEDS, CALLBACK_THREEDS, BKM_POS_SELECTED, INIT_APM, INIT_CONTACTLESS]
  event_types: [PAYMENT_API, API_AUTH, THREE_DS_AUTH, THREE_DS_CALLBACK, BKM_AUTH, BALANCE, CONTACTLESS_AUTH, CONTACTLESS_REFUND]
- name: HPP (CheckoutForm / Pay with iyzico)
  key_fields: [paymentConversationId, token, status, iyziEventType, iyziPaymentId]
  statuses: [FAILURE, SUCCESS, INIT_THREEDS, CALLBACK_THREEDS, BKM_POS_SELECTED, INIT_APM, INIT_BANK_TRANSFER, INIT_CREDIT, PENDING_CREDIT, INIT_CONTACTLESS]
  event_types: [CHECKOUT_FORM_AUTH, BANK_TRANSFER_AUTH, BKM_AUTH, BALANCE, CONTACTLESS_AUTH, CONTACTLESS_REFUND, CREDIT_PAYMENT_AUTH, CREDIT_PAYMENT_PENDING, CREDIT_PAYMENT_INIT, PWI_TKN_FUND, PWI_TKN_AUTH, PWI_TKN_THREEDS_AUTH]
- name: Subscription
  key_fields: [orderReferenceCode, customerReferenceCode, subscriptionReferenceCode, iyziReferenceCode, iyziEventType, iyziEventTime]
  event_types: [subscription.order.success, subscription.order.failure]