Transaction Webhook

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/wallet results.

  1. Payment Transaction Result: The result of the payment transaction, whether successful or unsuccessful, is transmitted to the webhook address.
  2. 3D Payment Transaction Result: The result of the 3D Payment transaction, whether successful or unsuccessful, is transmitted to the webhook address.
  3. 3D Secure Verification Result: The result of the 3D Secure verification process, whether successful or unsuccessful, is transmitted to the webhook address.
  4. Payment Transaction Result in uses of Payment Form: The result of the payment transaction made using the payment form, whether successful or unsuccessful, is transmitted to the webhook address you provided.
  5. Payment Refund Result: The result of the payment cancellation is transmitted to the webhook address if the result is successful.
  6. Payment Transaction Refund Result: The result of the payment transaction refund is transmitted to the webhook address if the result is successful.
  7. Payment Transaction Refund Result: The result of the settlement is transmitted to the webhook address if the settlement is completed.
  8. Wallet Creation Result: Wallet information is transmitted to webhook address when wallet is created.
  9. Wallet Transaction Result: Wallet transaction details is transmitted to webhook address when transaction is completed.

Important Note

  1. In the 3DS payment flow, your requests to the callbackUrl address are made through the browser. Requests to the callbackUrl address 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.
  2. 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 Settings -> Merchant Settings-> 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.

Webhook Settings

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 Model which means you should call 3DS complete after 3DS verification, THREEDS_VERIFY event type will be sent after 3DS verification and API_AUTH event type after 3DS complete.
  • If processing POS uses 3D Pay Model, only API_VERIFY_AND_AUTH event will be sent instead of THREEDS_VERIFY andAPI_AUTH event type.
  • If you are using checkout form, instead of other events, only CHECKOUTFORM_AUTH will be sent.

Request Parameters

Parameter Name Type Description
eventTimestamp long Epoch value of the date the request is created
eventType string Indicates for which operation the request is sent. Values can be: THREEDS_VERIFY, API_AUTH, API_VERIFY_AND_AUTH, CHECKOUTFORM_AUTH, REFUND, REFUND_TX, PAYOUT_COMPLETED, AUTOPILOT, WALLET_CREATED, WALLET_TX_CREATED
status string The status information of the operation. Values can be: SUCCESS, FAILURE
payloadId string ID value of the payment or token information of the Payment Form
payload Object Depends on event type. Will be not null for PAYOUT_COMPLETED, AUTOPILOT, WALLET_CREATED, WALLET_TX_CREATED.

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, the x-cg-signature-v1 sent between the HTTP headers should be checked. The x-cg-signature-v1 is calculated by combining as String the fields sent in the request and taking the Hash with the HmacSHA256 algorithm.

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 integration, API_AUTH1641018632SUCCESS2150001 results.

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 x-cg-signature-v1.

Webhook Sample Data

Event Type Sample
API_AUTH {"eventType": "API_AUTH","eventTime": "2023-04-13T14:15:32.123456","eventTimestamp": 1681384532,"status": "SUCCESS","payloadId": "271591"}
CHECKOUTFORM_AUTH {"eventType": "CHECKOUTFORM_AUTH","eventTime": "2023-04-13T13:58:17.123456","eventTimestamp": 1681383497,"status": "SUCCESS","payloadId": "14755c78-2e55-4171-ade2-7c9e7dc453ef"}
THREEDS_VERIFY {"eventType": "THREEDS_VERIFY","eventTime": "2023-04-13T14:13:12.123456","eventTimestamp": 1681384392,"status": "SUCCESS","payloadId": "271591"}
REFUND {"eventType": "REFUND","eventTime": "2023-04-14T11:27:17.123456","eventTimestamp": 1681460837,"status": "SUCCESS","payloadId": "24"}
REFUND_TX {"eventType": "REFUND_TX","eventTime": "2023-04-14T11:27:22.123456","eventTimestamp": 1681460842,"status": "SUCCESS","payloadId": "144"}
PAYOUT_COMPLETED {"eventType": "PAYOUT_COMPLETED","eventTime": "2023-04-14T10:41:07.123456","eventTimestamp": 1681458067,"status": "SUCCESS","payloadId": "50","payload": {"settlementFileId": 50,"settlementType": "SETTLEMENT"}}
AUTOPILOT {"eventType": "AUTOPILOT","eventTime": "2023-04-14T11:07:31.123456","eventTimestamp": 1681459651,"status": "SUCCESS","payloadId": "62-garanti-59","payload": {"posAlias": "62-garanti-59","posName": "garanti","nonThreeDsStatus": "PASSIVE","threeDsStatus": "ACTIVE","notificationsEnabled": false}}
WALLET_CREATED {"eventType": "WALLET_CREATED", "eventTime": "2023-04-26T16:16:47.123456", "eventTimestamp": 1682515007, "status": "SUCCESS", "payloadId": "34", "payload": { "currency": "TRY", "walletId": 34, "memberId": 39, "negativeAmountLimit": 0 } }
WALLET_TX_CREATED {"eventType": "WALLET_TX_CREATED", "eventTime": "2023-04-28T15:13:12.123456", "eventTimestamp": 1682683992, "status": "SUCCESS", "payloadId": "34", "payload": { "currency": "TRY", "walletTransactionType": "PAYMENT_REDEEM", "id": 158, "memberId": 39, "transactionId": 1, "walletId": 34, "amount": -10 } }