WebHook

Interlace uses Webhooks to notify a single callback URL provided by the client in a specified format. Interlace will send different payloads according to the scenarios described further below, and the trigger event can be understood in terms of the eventType field in the payload body.

After receiving a notification, needs to return a reply packet within 5 seconds. Otherwise, Interlace considers the notification failed and sends the notification repeatedly.

The same notification may be sent multiple times, and duplicate notifications must be handled correctly. If it has been processed, return success directly to Interlace.

You will receive an HTTP request like this.

POST /webhook HTTP/1.1
Host: xxx
Content-Type: application/json
Signature-Method: HMAC-SHA256
Signature: D29qUeeyV14HFG6DiuyFRsGLILlxzL8s7okeRMHjzFU=
Timestamp: 1756879969964

{
    "eventType": "CARD_TRANSACTION.CREATED",
    "apiVersion": "v3",
    "code": "000000",
    "message": "",
    "resource": "{\"id\":\"1234567890\",\"cardId\":\"4111111111111111\",\"createTime\":\"1756879969964\",\"processingCode\":\"00\",\"accountId\":\"ACC987654321\",\"transactionAmount\":\"150.00\",\"transactionCurrency\":\"USD\",\"billingAmount\":\"150.00\",\"billingCurrency\":\"USD\",\"merchantName\":\"Example Store\",\"merchantCity\":\"New York\",\"merchantCountry\":\"USA\",\"transactionType\":\"authorization\",\"mcc\":\"5812\"}",
    "createTime": "1756879969964",
    "id": "60633733-2b0d-41a2-a6b4-12b3ba085428"
}

The client should return the specified return code. If no corresponding return code is received after sending the callback URL, the Interlace system will consider the push unsuccessful. The return fields are as follows:

Field	Type	Description
received	boolean	Receiving identifier

Example:

{
  "received": true
}

Retry interval

Retry number	Interval	Retry number	Interval
1	10 seconds	9	7 minutes
2	30 seconds	10	8 minutes
3	1 minute	11	9 minutes
4	2 minutes	12	10 minutes
5	3 minutes	13	20 minutes
6	4 minutes	14	30 minutes
7	5 minutes	15	1 hour
8	6 minutes	16	2 hours

Common Considerations

All current implementations of notification messages have the following attributes:

Name	Type	Description	Sample
id	string	notification identifier	32b0216b-66d9-498b-a4bc-17612d9cb6cd
eventType	string	The eventType of notification	CARD.CREATED
createTime	string	create time	1757657700094
resource	string	JSON fromat of resource	JSON format, Use this field to check sign
apiVersion	string	webhook version	v3
code	string	code info	000000
message	string	message	success

Signature

Each request initiated by Interlace contains a sign parameter that can be used to verify the authenticity of the request from Interlace. For each request, the data of the data parameter is fetched and processed through the HMAC-SHA256 hash function.

Example

@Slf4j
public class Example {
    private static final String HMAC_SHA256 = "HmacSHA256";

    // generate sign
    public static String sign(String data, String secret) {
        try {
            Mac mac = Mac.getInstance(HMAC_SHA256);
            SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), HMAC_SHA256);
            mac.init(secretKey);
            byte[] hash = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
            return Base64.getEncoder().encodeToString(hash);
        } catch (Exception e) {
            log.error("sign error", e);
            return null;
        }
    }

    // verify sign
    public static boolean verify(String data, String signature, String secret) {
        try {
            String computedSignature = sign(data, secret);
            return computedSignature != null && computedSignature.equals(signature);
        } catch (Exception e) {
            return false;
        }
    }

    public static void main(String[] args) {
        String data = "{\"a\":\"b\"}";
        String secret = "6d8557a0cded4483b8d9c3cea0272cd7";
        String signature = sign(data, secret);
        System.out.println(signature);
    }
	//sign = Sj972aD0pmG+zClb7mKoUBZbQd5KlAyxaCKHUSMpBME=
}

const crypto = require('crypto');

/**
 * Generates HMAC-SHA256 signature
 * @param {string} data - The data to be signed
 * @param {string} secret - The secret key for signing
 * @returns {string|null} Base64 encoded signature, null if error occurs
 */
function sign(data, secret) {
    try {
        // Create HMAC-SHA256 hash object
        const hmac = crypto.createHmac('sha256', secret);
        // Update with data using UTF-8 encoding
        hmac.update(data, 'utf8');
        // Calculate signature and return as Base64
        return hmac.digest('base64');
    } catch (error) {
        console.error('Signing error:', error);
        return null;
    }
}

/**
 * Verifies HMAC-SHA256 signature
 * @param {string} data - The original data
 * @param {string} signature - The signature to verify
 * @param {string} secret - The secret key for verification
 * @returns {boolean} True if verification succeeds, false otherwise
 */
function verify(data, signature, secret) {
    try {
        const computedSignature = sign(data, secret);
        return computedSignature !== null && computedSignature === signature;
    } catch (error) {
        console.error('Verification error:', error);
        return false;
    }
}

// Example usage
function main() {
    const data = '{"a":"b"}';
    const secret = '6d8557a0cded4483b8d9c3cea0272cd7';
    const signature = sign(data, secret);
    console.log('Generated signature:', signature);
    
    // Verify the generated signature
    const isValid = verify(data, signature, secret);
    console.log('Signature valid:', isValid);
}

// Run example
main();

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"fmt"
	"log"
)

// sign generates an HMAC-SHA256 signature for the given data using the secret key
// Returns the base64-encoded signature or an error if something fails
func sign(data, secret string) (string, error) {
	// Create a new HMAC-SHA256 hasher using the secret key
	h := hmac.New(sha256.New, []byte(secret))
	
	// Write the data to be signed
	_, err := h.Write([]byte(data))
	if err != nil {
		return "", fmt.Errorf("failed to write data: %w", err)
	}
	
	// Calculate the HMAC hash and encode it as base64
	signature := base64.StdEncoding.EncodeToString(h.Sum(nil))
	return signature, nil
}

// verify checks if the provided signature matches the computed signature for the data
// Returns true if verification succeeds, false otherwise
func verify(data, signature, secret string) bool {
	// Compute the expected signature
	computedSignature, err := sign(data, secret)
	if err != nil {
		log.Printf("Verification error: %v", err)
		return false
	}
	
	// Compare the computed signature with the provided one
	return computedSignature == signature
}

func main() {
	data := `{"a":"b"}`
	secret := "6d8557a0cded4483b8d9c3cea0272cd7"
	
	// Generate signature
	signature, err := sign(data, secret)
	if err != nil {
		log.Fatalf("Failed to generate signature: %v", err)
	}
	fmt.Println("Generated signature:", signature)
	
	// Verify signature
	isValid := verify(data, signature, secret)
	fmt.Println("Signature valid:", isValid)
}

📢 Account Notification

Event Types

Event Type	Description
ACCOUNT.REGISTERED	Account registration is the process of creating a new account in the system.

Resource Object

The resource payload will be a Object.

Example Payload

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "apiVersion": "v3",
    "code": "000000",
    "message": "",
    "createTime": "1757659595371",
    "eventType": "ACCOUNT.REGISTERED",
    "resource": "..."
}

📢 CDD Notification

Event Types

Event Type	Description
KYC.PASSED	KYC verification passed.
KYC.BLACKLISTED	KYC blacklisted. Account cannot be submitted under any circumstances.
KYC.CANCELED	KYC rejected. All information must be resubmitted.
KYC.REQUEST	KYC rejected. Partial information must be resubmitted.
KYC.AWAIT_ADDITIONAL	KYC pending additional information from user.
KYC.CHECK_ADDITIONAL	KYC additional information submitted, waiting for review.
KYC.PENDING	KYC is currently under review.
KYB.PASSED	KYB verification passed.
KYB.CANCELED	KYB rejected. All information must be resubmitted.
KYB.BLACKLISTED	KYB blacklisted. Account cannot be submitted under any circumstances.
KYB.REQUEST	KYB rejected. Partial information must be resubmitted.
KYB.PENDING	KYB is currently under review.

CDD Object

The resource payload will be a Object.

Example Payload

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "apiVersion": "v3", 
    "code": "000000",
    "message": "",
    "createTime": "1757659595371",
    "eventType": "KYC.PENDING",
    "resource": "..."
}

📢Infinity Card Notification

Card

Event Types

Event Type	Description
CARD.CREATED	card created.
CARD.UPDATED	card info updated
CARD.DELETED	card deleted

Example

Create a infinity card, you should see a notification message on your local server shell that looks like the following.

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "eventType": "CARD.CREATED",
    "code": "000000",
    "message": "",
    "resource": "...",
    "apiVersion": "v3",
    "createTime":"1756879969964"
}

The resource payload will be JSON fromat of Card Object.

Card Transaction

Event Types

Event Type	Description
CARD_TRANSACTION.CREATED	card transaction created.
CARD_TRANSACTION.UPDATED	card transaction updated.

Example

Create a infinity card, you should see a notification message on your local server shell that looks like the following.

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "eventType": "CARD_TRANSACTION.CREATED",
    "code": "000000",
    "message": "",
    "resource": "...",
    "apiVersion": "v3",
    "createTime":"1756879969964"
}

The resource payload will be JSON fromat of Card Transaction Object.

📢Budget

Event Types

Event Type	Description
BUDGET.CREATED	budget created.
BUDGET.UPDATED	budget info updated
BUDGET.DELETED	budget deleted

Example

Create a budget, you should see a notification message on your local server shell that looks like the following.

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "code": "000000",
    "message": "",
    "eventType": "BUDGET.CREATED",
    "resource": "...",
    "apiVersion": "v3",
    "createTime":"1756879969964"
}

The resource payload will be JSON fromat of Budget Object.

📢Budget Transaction

Event Types

Event Type	Description
BUDGET_TRANSACTION.CLOSED	budget transaction closed.

Example

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "code": "000000",
    "message": "",
    "eventType": "BUDGET_TRANSACTION.CREATED",
    "resource": "...",
    "apiVersion": "v3",
    "createTime":"1756879969964"
}

The resource payload will be JSON fromat of Budget Transaction Object.

📢Cardholder

Event Types

Event Type	Description
CARDHOLDER.CREATED	cardholder created.
CARDHOLDER.UPDATED	cardholder info updated
CARDHOLDER.DELETED	cardholder deleted

Example

Create a cardholder, you should see a notification message on your local server shell that looks like the following.

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "code": "000000",
    "message": "",
    "eventType": "CARDHOLDER.CREATED",
    "resource": "...",
    "apiVersion": "v3",
    "createTime":"1756879969964"
}

The resource payload will be JSON fromat of Cardholder Object.

📢 Payment Notification

Event Types

Event Type	Description
BUSINESS_TRANSFER.PAYOUT.PAYMENT.CREATED	Payment has been created but is not yet completed.
BUSINESS_TRANSFER.PAYOUT.PAYMENT.UPDATE	Payment has been successfully completed.Refund related to a payout payment has been successfully completed.

Resource Object

The resource payload will be a Object.

Example Payload

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "code": "000000",
    "message": "",
    "apiVersion": "v3",
    "createTime": "1757659595371",
    "eventType": "BUSINESS_TRANSFER.PAYOUT.PAYMENT.CREATED",
    "resource": "..."
}

📢 Business Transfer Notification

Event Types

Event Type	Description
BUSINESS_TRANSFER.CREATED	Triggered after an order is submitted, notifying your system of the new order.
BUSINESS_TRANSFER.UPDATE	The business transfer has failed and was not completed successfully.Triggered after an order is completed, notifying your system that the transfer is finished.

Resource Object

The resource payload will be a Object.

Example Payload

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "code": "000000",
    "message": "",
    "apiVersion": "v3",
    "createTime": "1757649535314",
    "eventType": "BUSINESS_TRANSFER.CREATED",
    "resource": "..."
}

📢 Blockchain Transfer Notification

Event Types

Event Type	Description
BLOCKCHAIN_TRANSFER.CREATED	Notifies your system of a new order upon the submission of a blockchain transfer.
BLOCKCHAIN_TRANSFER.UPDATE	Your system will receive this notification when any of the following events occur: An on-chain transaction is completed. A deposit transaction is flagged as high-risk by KYT. A refund is completed.

Event Type

Description

BLOCKCHAIN_TRANSFER.CREATED

Notifies your system of a new order upon the submission of a blockchain transfer.

BLOCKCHAIN_TRANSFER.UPDATE

Your system will receive this notification when any of the following events occur:

An on-chain transaction is completed.

A deposit transaction is flagged as high-risk by KYT.

A refund is completed.

Resource Object

The resource payload will be a Blockchain Transfer Object.

Example Payload

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "code": "000000",
    "message": "",
    "apiVersion": "v3",
    "createTime": "1757649535314",
    "eventType": "BLOCKCHAIN_TRANSFER.CREATED",
    "resource": "..."
}

📢 Blockchain Refund Notification

Event Types

Event Type	Description
BLOCKCHAIN_REFUND.CREATED	Notifies your system of a new order upon the submission of a blockchain refund.
BLOCKCHAIN_REFUND.UPDATE	Your system will receive this notification once an on-chain refund transaction has been finalized, whether it succeeded or failed.

Resource Object

The resource payload will be a Blockchain Refund Object.

Example Payload

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "code": "000000",
    "message": "",
    "apiVersion": "v3",
    "createTime": "1757649535314",
    "eventType": "BLOCKCHAIN_REFUND.CREATED",
    "resource": "..."
}

📢 Acquiring Notification

Event Types

Event Type	Description
acquiring.order	This resource defines the data structure of the webhook notification sent when an acquiring order’s status changes. It is used to synchronize real-time order status updates to merchants, enabling timely business processing (e.g., order fulfillment, refund handling).

Resource Object

The resource payload will be a Acquiring Order Webhook Object.

Example Payload

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "code": "000000",
    "message": "",
    "createTime": "1757649535314",
    "eventType": "ACQUIRING.ORDER",
    "resource": "..."
}

Event Types

Event Type	Description
acquiring.dispute	When a dispute is initiated (e.g., by a cardholder or issuing bank), updated (e.g., status change to "Representation"), or resolved (e.g., status change to "CB Dispute Win" or "CB Dispute loss"), the system sends this webhook to the merchant’s pre-configured endpoint.

Resource Object

The resource payload will be a Acquiring Dispute Webhook Object.

Example Payload

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "code": "000000",
    "message": "",
    "apiVersion": "v3",
    "createTime": "1757649535314",
    "eventType": "ACQUIRING.DISPUTE",
    "resource": "..."
}

📢 3DS Notification

Event Types

Event Type	Description
CARD.3DS.OTP	This event sends OTP details for a card consumption transaction, including card info, amount, and the one-time code, to enable secure verification.

Resource Object

The resource payload will be a 3DS Object.

Example Payload

{
    "id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
    "code": "000000",
    "message": "",
    "createTime": "1757649535314",
    "eventType": "CARD.3DS.OTP",
    "resource": "..."
}