Hosted KYC Widget

Creates a new KYC instance for an individual user and returns a hosted KYC link that can be shared with the user to complete verification.

This endpoint is intended for server-to-server use only and must be called from the merchant's backend.

Endpoint

POST https://api.tylt.money/kycIndividualUserMerchant/createKYCLinkIndividualUser

Authentication

The request must include the merchant API key and an HMAC-SHA256 signature.

Header	Description
x-tlp-apikey	Merchant API key
x-tlp-signature	HMAC-SHA256 signature of the request body using the merchant API secret
Content-Type	application/json

The merchant is identified from the API key. merchantId and userId must not be included in the request body.

---

Request Parameters

Field	Type	Required	Description
userEmail	string	Yes	Valid email address of the individual user for whom the KYC instance is being created

Example Request Body

{
  "userEmail": "[e-mail]"
}

---

Example Request

The request signature must be generated from the exact JSON body being sent.

import crypto from "crypto";
import axios from "axios";

const apiKey = process.env.TYLT_API_KEY;
const apiSecret = process.env.TYLT_API_SECRET;

const body = {
  userEmail: "[e-mail]",
};

const bodyString = JSON.stringify(body);

const signature = crypto
  .createHmac("sha256", apiSecret)
  .update(bodyString)
  .digest("hex");

const response = await axios.post(
  "https://<host>/kycIndividualUserMerchant/createKYCLinkIndividualUser",
  bodyString,
  {
    headers: {
      "Content-Type": "application/json",
      "x-tlp-apikey": apiKey,
      "x-tlp-signature": signature,
    },
  }
);

console.log(response.data);

Signature Generation

The signature is calculated as:

HMAC-SHA256(apiSecret, JSON.stringify(body))

The resulting hexadecimal digest must be passed as the x-tlp-signature header.

The JSON string used to generate the signature must exactly match the request body sent to the API.

---

Validation Requirements

The merchant should ensure that:

• userEmail contains a valid email address.

• The request is made from the merchant's backend.

• x-tlp-apikey and x-tlp-signature are included in the request headers.

• The signature is generated using the exact JSON request body.

The merchant identity is automatically resolved from the API key after the signature has been validated.

---

Response

Success Response

HTTP 201 — Created

{
  "msg": "KYC instance created successfully.",
  "data": {
    "kycInstanceId": "550e8400-e29b-41d4-a716-446655440000",
    "userEmail": "[e-mail]",
    "merchantId": 123,
    "kycLink": "https://app.tylt.money/kyc?kycInstanceId=550e8400-e29b-41d4-a716-446655440000"
  }
}

Response Parameters

Field	Type	Description
kycInstanceId	string	Unique identifier of the KYC instance
userEmail	string	Email address of the individual user
merchantId	number	Merchant associated with the authenticated API key
kycLink	string	Hosted KYC URL that should be shared with or opened for the individual user

The merchant should store the kycInstanceId against the user. It can be used to identify the KYC instance for subsequent status checks and KYC operations.

The returned kycLink should be used to redirect the user to the hosted KYC verification flow.

---

Error Responses

Invalid User Email

HTTP 400

{
  "msg": "A valid userEmail is required.",
  "data": {}
}

Returned when userEmail is missing, empty, or invalid.

Invalid Signature

HTTP 400

{
  "msg": "Invalid signature.",
  "data": {}
}

Returned when the supplied HMAC signature does not match the request body.

Missing Authentication Headers

HTTP 401

{
  "msg": "API key and signature headers are required.",
  "data": {}
}

Returned when x-tlp-apikey or x-tlp-signature is missing.

Invalid API Key

HTTP 401

{
  "msg": "Invalid API key.",
  "data": {}
}

Returned when the supplied merchant API key is not recognized.

Merchant Identity Missing

HTTP 403

{
  "msg": "Merchant identity is missing.",
  "data": {}
}

Returned when the API key is not associated with a valid merchant.

Server Error

HTTP 500

{
  "msg": "Failed to create KYC instance.",
  "data": {}
}

Returned when the KYC instance cannot be created because of an internal server or database error.

---

cURL Example

Generate the x-tlp-signature from the exact request body using the merchant API secret.

curl --location 'https://<host>/kycIndividualUserMerchant/createKYCLinkIndividualUser' \
  --header 'Content-Type: application/json' \
  --header 'x-tlp-apikey: <your_api_key>' \
  --header 'x-tlp-signature: <hmac_sha256_hex>' \
  --data '{"userEmail":"[e-mail]"}'

---

Next Step

After receiving the kycLink, redirect or share the URL with the individual user.

The hosted KYC flow will collect the required user information and initiate the applicable verification modules, including:

• Basic identity information

• Proof of Identity (POI)

• Proof of Address (POA)

• AML screening

• Liveness verification