Skip to main content

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

  1. Payment Transaction Result(API_AUTH): The result of the payment transaction, whether successful or unsuccessful, is transmitted to the webhook address.
  2. 3D Payment Transaction Result(API_VERIFY_AND_AUTH): This event is sent in 3D Pay model payment methods.
  3. Payment Transaction Result in uses of Payment Form(CHECKOUTFORM_AUTH): The successful result of payment transactions made using the payment form and payments considered as suspicious or fraud transactions depending on fraud rules are sent to the webhook address.
  4. 3D Secure Verification Result(THREEDS_VERIFY): The result of the 3D Secure verification process, whether successful or unsuccessful, is transmitted to the webhook address.
  5. Payment Refund Result(REFUND): The result of the payment cancellation is transmitted to the webhook address if the result is successful.
  6. Payment Transaction Refund Result(REFUND_TX): The result of the payment transaction refund is transmitted to the webhook address if the result is successful.
  7. Money Transfer Completion Result(PAYOUT_COMPLETED): The result of the settlement is transmitted to the webhook address if the settlement is completed.
  8. Autopilot Transaction Result(AUTOPILOT): Autopilot transactions are forwarded to webhook.
  9. Wallet Creation Result(WALLET_CREATED): Wallet information is transmitted to webhook address when wallet is created.
  10. Wallet Transaction Result(WALLET_TX_CREATED): Wallet transaction details is transmitted to webhook address when transaction is completed.
  11. Shopping Loan Application Result (BNPL_NOTIFICATION): Status change of shopping loan application is transmitted to webhook adress.
  12. Bank Account Ttracking Record(BANK_ACCOUNT_TRACKING_RECORD): Bank account tracking record is transmitted to webhook address when transaction is created.
  13. Multi Payment Complete(MULTI_PAYMENT_COMPLETED): Completed multi payments are transmitted to the webhook address
  14. BKM Express Payment Control(BKM_EXPRESS_PAYMENT_NOTIFICATION): Before the payment is completed, a notification is sent to check the payment.

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 Ayarları

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 and API_AUTH event type.
  • If you are using checkout form, instead of other events, only CHECKOUTFORM_AUTH will be sent.

Request Parameters​

eventTimestamp
long

Epoch value of the date the request is created

eventType
string

Indicates for which operation the request is sent.

Values:
API_AUTH
API_VERIFY_AND_AUTH
CHECKOUTFORM_AUTH
THREEDS_VERIFY
REFUND
REFUND_TX
PAYOUT_COMPLETED
AUTOPILOT
WALLET_CREATED
WALLET_TX_CREATED
BNPL_NOTIFICATION
BANK_ACCOUNT_TRACKING_RECORD
MULTI_PAYMENT_COMPLETED
BKM_EXPRESS_PAYMENT_NOTIFICATION
status
string

The status information of the operation.

Values:
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, BNPL_NOTIFICATION, BANK_ACCOUNT_TRACKING_RECORD

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. Calculation of this value is done as follows:

  1. The eventType, eventTimestamp, status and payloadId fields in the request are combined as strings, respectively.
  2. The combined value is hashed using the HmacSHA256 algorithm.
  3. The output obtained from the hashing process is encoded in Base64 format.
note

Please note that the SHA-256 output must be digested (bytes) and the byte encoding must be UTF-8

For example;

{"eventType": "API_AUTH","eventTime": "2022-01-01T09:30:32","eventTimestamp": 1681384532,"status": "SUCCESS","payloadId": "2150001"}

When eventType+eventTimestamp+status+payloadId information is combined as String, API_AUTH1641018632SUCCESS2150001 is obtained. When you hash this value with the Merchant Webhook Key value 1Q2w3E4r5T6y7U8i9Op in the Craftgate Merchant Panel Settings section and encode it with Base64, the result will be eNXKxfxUpVmp/wBrNUmOLjNXL0sYl0mh1s/rEB8K8NU=. The value can be compared to the x-cg-signature-v1 value passed in the header by Craftgate.

For the details of the algorithm, the following codes of our clients can be examined.

Java.NETPHPNode.jsGo

Webhook Sample Data​

Event TypeSample
API_AUTH{"eventType": "API_AUTH","eventTime": "2023-04-13T14:15:32.123456","eventTimestamp": 1681384532,"status": "SUCCESS","payloadId": "271591"}
API_VERIFY_AND_AUTH{"eventType": "API_VERIFY_AND_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 } }
BNPL_NOTIFICATION{"eventType": "BNPL_NOTIFICATION", "eventTime": "2023-11-01T00:00:00.123456", "eventTimestamp": 1699477200, "status": "SUCCESS", "payloadId": "204", "payload": {"additionalAction": "APPROVAL_REQUIRED"}}
BANK_ACCOUNT_TRACKING_RECORD{"eventType": "BANK_ACCOUNT_TRACKING_RECORD","eventTime": "2023-07-24T10:27:00.123456","eventTimestamp": 1690208820,"status": "SUCCESS","payloadId": "537","payload": {"currency": "TRY","recordDate": "2016-02-05T12:24:41","senderName": "Alican Akkuş","key": "160205987654321","recordType": "RECEIVE","description": "7654321 numaralı sipariş","senderIban": "TR870006400000111351052758","amount": 81500}}
MULTI_PAYMENT_COMPLETED{"eventType": "MULTI_PAYMENT_COMPLETED", "eventTime": "2024-04-05T15:40:02.123456", "eventTimestamp": 1712320802, "status": "SUCCESS", "payloadId": "774a7c17-1a47-4104-a562-35a521ad3ac7", "payload": { "paymentIds": [ 11914 ], "conversationId": "convId-123", "externalId": "externalId-123", "multiPaymentStatus": "COMPLETED", "token": "774a7c17-1a47-4104-a562-35a521ad3ac7" } }
BKM_EXPRESS_PAYMENT_NOTIFICATION{"eventType":"BKM_EXPRESS_PAYMENT_NOTIFICATION","eventTime":"2024-06-26T18:56:37.123456","eventTimestamp":1719417397,"status":"SUCCESS","payloadId":"dcfdc163-0545-46d7-8f86-5a11718e56ec","payload":{"ticketId":"dcfdc163-0545-46d7-8f86-5a11718e56ec","paidPrice":"1,00","installment":1,"price":"1,00"}}

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.