Webhook

iyzico uses webhooks to notify your application when the transaction is done. (Success, Failure) When a payment attempt is made, it is possible to receive the transaction result via HTTP POST notification. The first notification will be sent after 10-15 seconds of the initial payment attempt. It is a JSON Payload and server to server HTTP request. iyzico will keep continuing sending notifications every 15 minutes until your server responds with a status of "2xx". Notifications will stop after 3 attemps.

In iyzico, all of the payment methods operations results directly which towards the use of webhooks could be optional. For an instance, in a successful payment request, latest response contains all the payment details. However webhooks can still be used to trigger different mechanisms if desired.

How to activate Webhooks?

After login to iyzico Merchant Portal, you can find the Webhook Notifications under the menu called "Settings" > "Merchant Settings" > "Merchant Notifications" (HTTPS URL is required)

Webhook Forms

Webhooks posts on 3 distinguishable formats;

  • Direct Format

  • HPP(Hosted Payment Page) Format

  • Subscription

Direct Format

Following webhook format appears on NON-3DS and 3DS payment requests.

Parameter
Type
Description

paymentConversationId

string

Merchant's reference id for the related payment.

merchantId

string

Merchant's id, MID.

paymentId

string

Relevant paymentId which belongs to the payment.

status

string

Payment status. Values: FAILURE, SUCCESS, INIT_THREEDS, CALLBACK_THREEDS, BKM_POS_SELECTED, INIT_APM, INIT_CONTACTLESS

iyziReferenceCode

string

A unique reference code for the notification

iyziEventType

string

Shows the request type. Values: PAYMENT_API, API_AUTH, THREE_DS_AUTH, THREE_DS_CALLBACK, BKM_AUTH, BALANCE, CONTACTLESS_AUTH, CONTACTLESS_REFUND

iyziEventTime

long

Unix timestamp value of first notification.

iyziPaymentId

long

Relevant paymentId which belongs to the payment.

HPP Format

Similar to above, next webhook format appears on hosted page solutions which are PWI, CF.

Parameter
Type
Description

paymentConversationId

string

Merchant's reference id for the related payment.

merchantId

string

Merchant's id, MID.

token

string

The token generated for the related payment

status

string

Payment status. Values: FAILURE, SUCCESS, INIT_THREEDS, CALLBACK_THREEDS, BKM_POS_SELECTED, INIT_APM, INIT_BANK_TRANSFER, INIT_CREDIT, PENDING_CREDIT, INIT_CONTACTLESS

iyziReferenceCode

string

A unique reference code for the notification.

iyziEventType

string

Shows the request type. Values: 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

iyziEventTime

long

Unix timestamp value of first notification.

iyziPaymentId

long

Relevant paymentId which belongs to the payment.

Subscription Format

In the subscription feature, after the subscription is started, you can receive webhook notifications not only for the initial transaction but also for the recurring payments to be collected under the plan.

You can check the status of recurring payments by defining a URL in the subscription notification field located under "Settings > Merchant Settings > Merchant Subscription Notifications" in the iyzico control panel.

Example subscription notifications for successful and failed transactions are as follows.

Success

{
  "orderReferenceCode": "ae5fcbf8-4fd2-46e5-b199-8f690ae9fae5",
  "customerReferenceCode": "ff4052ca-0588-40eb-81a9-848c0c409472",
  "subscriptionReferenceCode": "ea0362e2-a1c4-4fda-89f0-3758a5c20a28",
  "iyziReferenceCode": "18d7cc48-a64b-4cd3-ae68-71aff1c76ed9",
  "iyziEventType": "subscription.order.success",
  "iyziEventTime": 1758704403161
}

Failure

{
  "orderReferenceCode": "9ed2d128-b106-464b-8170-84325e75703b",
  "customerReferenceCode": "042f0b61-079a-4a38-9454-6564a3c11a5a",
  "subscriptionReferenceCode": "b0f6d38f-b2d1-4a72-9bf2-bc9375665f3a",
  "iyziReferenceCode": "aac139a9-43db-4f40-82dd-d4e5a77a3d2e",
  "iyziEventType": "subscription.order.failure",
  "iyziEventTime": 1579612261619
}

Subscription Notification Parameters

Parameter
Type
Description

orderReferenceCode

String

The reference code of the related payment attempt. It is used in the retry process for failed transactions.

customerReferenceCode

String

The reference code of the customer.

subscriptionReferenceCode

String

The reference code of the subscription.

iyziReferenceCode

String

The unique iyzico reference code generated for the request.

iyziEventType

String

Specifies the request type. Possible values are:

"subscription.order.success"

"subscription.order.failure"

iyziEventTime

Long

The Unix timestamp value of when the notification was created.

Validation of Notifications

To verify source of webhook, iyzico sends encrypted a variable in the header called X-IYZ-SIGNATURE-V3 that can be decrypt with only merchants their own SECRET KEY.

Validation of Direct Format

SECRET KEY, iyziEventType, paymentId, paymentConversationId, status should be created with the given order below. This string should be encrypted with HMACSHA256 and the result should be encoded with HEX. Final value should should be equal to X-IYZ-SIGNATURE-V3 in the header.

Hashing Sample for Direct Format
// Create the key for HMAC
const key = secretKey + iyziEventType + paymentId + paymentConversationId + status;

// Generate HMAC SHA256 signature
const hmac256 = crypto.createHmac('sha256', secretKey)
                       .update(key)
                       .digest('hex');

Order

Parameter

Description

1

secretKey

Merchant's secret key

2

iyziEventType

Shows the request type. Values: PAYMENT_API, API_AUTH, THREE_DS_AUTH, THREE_DS_CALLBACK, BKM_AUTH, BALANCE, CONTACTLESS_AUTH, CONTACTLESS_REFUND,

3

paymentId

Unique iyzico reference code of realted payment

4

paymentConversationId

Merchant's reference id for the related payment.

5

status

Payment status. Values: FAILURE, SUCCESS, INIT_THREEDS, CALLBACK_THREEDS, BKM_POS_SELECTED, INIT_APM, INIT_CONTACTLESS

Validation of HPP Format

SECRET KEY, iyziEventType, iyziPaymentId, token, paymentConversationId, status should be created with the given order below. This string should be encrypted with HMACSHA256 and the result should be encoded with HEX. Final value should should be equal to X-IYZ-SIGNATURE-V3 in the header.

Hashing Sample for HPP Format
// Create the key for HMAC
const key = secretKey + iyziEventType + iyziPaymentId + token + paymentConversationId + status;

// Generate HMAC SHA256 signature
const hmac256 = crypto.createHmac('sha256', secretKey)
                       .update(key)
                       .digest('hex');
Order
Parameter
Description

1

secretKey

Merchant's secret key.

2

iyziEventType

Shows the request type. Values: 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

3

iyziPaymentId

Relevant paymentId which belongs to the payment.

4

token

The token generated for the related payment.

5

paymentConversationId

Merchant's reference id for the related payment.

6

status

Payment status. Values: FAILURE, SUCCESS, INIT_THREEDS, CALLBACK_THREEDS, BKM_POS_SELECTED, INIT_APM, INIT_BANK_TRANSFER, INIT_CREDIT, PENDING_CREDIT, INIT_CONTACTLESS

Validation of Subscription Format

The X-IYZ-SIGNATURE-V3 value sent in the header can be used to validate that the request originated from iyzico, and this value can only be decrypted with your SECRET KEY.

The SECRET KEY, merchantId, eventType, subscriptionReferenceCode, orderReferenceCode, and customerReferenceCode must be concatenated in the exact order shown below. This string is then hashed with HMAC-SHA256, and the result is HEX-encoded. The final value must match the X-IYZ-SIGNATURE-V3 in the header.

// A Key (message) is generated for the HMAC
const key = merchantId 
          + secretKey 
          + eventType 
          + subscriptionReferenceCode 
          + orderReferenceCode 
          + customerReferenceCode;

// The signature is generated with HMAC SHA256 (in hex format)
const hmac256 = crypto.createHmac('sha256', secretKey)
                      .update(key)
                      .digest('hex');

Last updated