Craftgate regularly transmits the results and information of the following transactions to a URL that you define from merchant panel. Thus, you can follow the results of all your payment transactions made through Craftgate, even if the payment flow is interrupted, and you can plan your flows according to the payment/cancel/refund/settlement results.
- Payment Transaction Result(API_AUTH): The result of the payment transaction, whether successful or unsuccessful, is transmitted to the webhook address.
- 3D Payment Transaction Result(API_VERIFY_AND_AUTH): This event is sent in 3D Pay model payment methods.
- Payment Transaction Result in uses of Payment Form(CHECKOUTFORM_AUTH): The result of the payment transaction made using the payment form, whether successful or unsuccessful, is transmitted to the webhook address you provided.
- 3D Secure Verification Result(THREEDS_VERIFY): The result of the 3D Secure verification process, whether successful or unsuccessful, is transmitted to the webhook address.
- Payment Refund Result(REFUND): The result of the payment cancellation is transmitted to the webhook address if the result is successful.
- Payment Transaction Refund Result(REFUND_TX): The result of the payment transaction refund is transmitted to the webhook address if the result is successful.
- Money Transfer Completion Result(PAYOUT_COMPLETED): The result of the settlement is transmitted to the webhook address if the settlement is completed.
- Autopilot Transaction Result(AUTOPILOT): Autopilot transactions are forwarded to webhook.
- Wallet Creation Result(WALLET_CREATED): Wallet information is transmitted to webhook address when wallet is created.
- Wallet Transaction Result(WALLET_TX_CREATED): Wallet transaction details is transmitted to webhook address when transaction is completed.
- Shopping Loan Application Result (BNPL_NOTIFICATION): Status change of shopping loan application is transmitted to webhook adress.
- In the 3DS payment flow, your requests to the
callbackUrladdress are made through the browser. Requests to the
callbackUrladdress may not be met if the end user stops the flow or problems occur in the user’s internet. Therefore, our webhook services can be especially useful for tracking 3DS payments and detecting user behavior.
- We will be adding new event types in the future. Please be careful about unhandled event types in your application.
Address Definition to Receive Webhook Notification
In order to activate the Webhook notification, the
Merchant Webhook URL field under Craftgate panel
General Settings must be filled in. When you accept the
POST requests as the webhook URL
and enter a URL that returns
2xx from the
HTTP codes, Craftgate will send the relevant data after the payments.
Request Forwarded to the Webhook Address
Payment, Refund, Refund Tx, 3D payment and 3D secure verification, Settlement completed results are sent to the webhook address you specified in JSON format via
POST http method.
While 3DS payment:
- If processing POS uses
3D Modelwhich means you should call 3DS complete after 3DS verification,
THREEDS_VERIFYevent type will be sent after 3DS verification and
API_AUTHevent type after 3DS complete.
- If processing POS uses
3D Pay Model, only
API_VERIFY_AND_AUTHevent will be sent instead of
- If you are using checkout form, instead of other events, only
CHECKOUTFORM_AUTHwill be sent.
Epoch value of the date the request is created
Indicates for which operation the request is sent.
The status information of the operation.
ID value of the payment or token information of the Payment Form
Depends on event type. Will be not null for
Checking If Webhook Request was sent by Craftgate
In order to confirm that the requests coming to your Webhook URL are sent from the Craftgate system, the
x-cg-signature-v1 value sent with HTTP headers must be validated. The
x-cg-signature-v1 value is calculated by concatenating the fields (other than payload) sent in the request as
String, hashing this value with the
HmacSHA256 algorithm, and then encoding the new value with
Base64. Please note that the SHA-256 output must be digest (bytes) and the byte encoding must be UTF-8.
For example, using API integration, when
eventType+eventTimestamp+status+payloadId information is combined as String for payment with id 2150001 successfully received on 2022-01-01T09:30:32 GMT+3 (epoch: 1641018632), the value
API_AUTH1641018632SUCCESS2150001 is generated. When you hash this value with
1Q2w3E4r5T6y7U8i9Op, which is the
Member Merchant Webhook Key value in the Craftgate Merchant panel Settings section, and encode it with Base64, the result will be
eNXKxfxUpVmp/wBrNUmOLjNXL0sYl0mh1s/rEB8K8NU=. The value can be compared with the
x-cg-signature-v1 value passed by Craftgate in the header.
For the details of the algorithm, the following codes of our clients can be examined.
Webhook Sample Data
Confirming that the Request Forwarded to the Webhook Address is Sent by Craftgate
In order to confirm that the requests received on your webhook URL are sent from the Craftgate system,
x-cg-signature-v1 sent between the HTTP headers should be checked. The
x-cg-signature-v1 is calculated by combining
String the fields sent in the request and taking the Hash with the
For example, when
eventType+eventTimestamp+status+payloadId information is combined as a String for the payment with ID
2150001, which was successfully received on 2022-01-01T09:30:32 GMT+3 (epoch: 1641018632) using API
When you hash this with the Merchant Webhook Key value in the Craftgate
Merchant Panel Settings section and you get
the Base64 encoded version, the result equals to the