For the complete documentation index, see llms.txt. This page is also available as Markdown.

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": "user@example.com"
}

Example Request

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

Signature Generation

The signature is calculated as:

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

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

Returned when userEmail is missing, empty, or invalid.

Invalid Signature

HTTP 400

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

Missing Authentication Headers

HTTP 401

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

Invalid API Key

HTTP 401

Returned when the supplied merchant API key is not recognized.

Merchant Identity Missing

HTTP 403

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

Server Error

HTTP 500

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.


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

Last updated