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 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 |
---|---|---|
iyziEventTime | long | Unix timestamp value of first notification. |
iyziEventType | string | Shows the request type. Values: API_AUTH, THREE_DS_AUTH, BKM_AUTH |
iyziReferenceCode | string | A unique reference code for the notification |
paymentId | long | Unique iyzico reference code of realted payment |
paymentConversationId | string | Merchant's reference id for the related payment |
status | string | Payment status. Values: SUCCESS, FAILURE |
HPP Format
Similar to above, next webhook format appears on hosted page solutions which are PWI, CF.
Parameter | Type | Description |
---|---|---|
iyziEventTime | long | Unix timestamp value of first notification |
iyziEventType | string | Shows the request type. VALUES: API_AUTH, THREE_DS_AUTH, BKM_AUTH, CHECKOUT_FORM_AUTH, BALANCE, BANK_TRANSFER_AUTH |
iyziReferenceCode | string | A unique reference code for the notification |
token | string | The token generated for the related payment |
status | string | Payment status. Values: SUCCESS, FAILURE |
Validation of Notifications
To verify source of webhook, iyzico sends encrypted a variable in the header called X-IYZ-SIGNATURE
that can be decrypt with only merchants their own SECRET KEY
.
Validation of Direct Format
SECRET KEY
, eventType
and paymentId
should be created with the given order below. This string should be encrypted with Sha1 and the result should be encoded with base 64. Final value should should be equal to X-IYZ-SIGNATURE
in the header.
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 |
Validation of HPP Format
SECRET KEY
, eventType
and token
should be created with the given order below. This string should be encrypted with Sha1 and the result should be encoded with base 64. Final value should should be equal to X-IYZ-SIGNATURE
in the header.
Order | Parameter | Description |
---|---|---|
1 | secretKey | Merchant's secret key |
2 | iyziEventType | Shows the request type. Values: CHECKOUT_FORM_AUTH, BALANCE, BANK_TRANSFER_AUTH |
3 | token | The token generated for the related payment |
String should be encoded with base64 after SHA1 encryption.
String hash = Base64.encodeBase64String(DigestUtils.sha1(stringToBeHashed));
Last updated