Webhook

Note that X-Iyz-Signature and X-Iyz-Signature-V2 will no longer supported. We expect our merchants to enhance their system to X-Iyz-Signature-V3 in timely manner.

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 2 distinguishable formats;

• Direct Format

• HPP(Hosted Payment Page) Format

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_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, PAYMENT_API, API_AUTH, THREE_DS_AUTH, THREE_DS_CALLBACK, BANK_TRANSFER_AUTH, BKM_AUTH, BALANCE, CONTACTLESS_AUTH, CONTACTLESS_REFUND, CREDIT_PAYMENT_AUTH, CREDIT_PAYMENT_PENDING, CREDIT_PAYMENT_INIT, REFUND_RETRY_FAILURE, REFUND_RETRY_SUCCESS
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, PAYMENT_API, API_AUTH, THREE_DS_AUTH, THREE_DS_CALLBACK, BANK_TRANSFER_AUTH, BKM_AUTH, BALANCE, CONTACTLESS_AUTH, CONTACTLESS_REFUND, CREDIT_PAYMENT_AUTH, CREDIT_PAYMENT_PENDING, CREDIT_PAYMENT_INIT, REFUND_RETRY_FAILURE, REFUND_RETRY_SUCCESS
iyziEventTime	long	Unix timestamp value of first notification.
iyziPaymentId	long	Relevant paymentId which belongs to the payment.

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.

Note that X-Iyz-Signature and X-Iyz-Signature-V2 will no longer supported. We expect our merchants to enhance their system to X-Iyz-Signature-V3 in timely manner.

Validation of Direct Format

SECRET KEY, eventType and paymentId 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 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: API_AUTH, THREE_DS_AUTH, BKM_AUTH
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_BANK_TRANSFER, INIT_CREDIT, PENDING_CREDIT, INIT_CONTACTLESS.

Validation of HPP Format

SECRET KEY, iyziEventType, iyziPaymentId, token, paymentConversationId, status, eventType and token 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, BALANCE, BANK_TRANSFER_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