Create User

Creates a new end user or links an existing user to the merchant.

Endpoint

POST /whitelabel/users/signup

Request Headers

x-tlp-apikey: <api-key>
x-tlp-signature: <hmac-signature>
Content-Type: application/json

Request Parameters

Field	Type	Required	Description
emailId	String	Yes	Valid email address of the end user
externalUserId	String	Yes	Unique user identifier assigned by the merchant
firstName	String	No	End user’s first name
lastName	String	No	End user’s last name
countryOfResidence	String	Yes	The ISO 3166-1 alpha-3 code representing the country in which the individual currently and ordinarily resides. Eg. "CAN", "DEU","USA"
countryOfCitizenship	String	No	The ISO 3166-1 alpha-3 code representing the country in which the individual currently a citizen.Eg. "CAN", "DEU","USA"
countryOfBirth	String	No	The ISO 3166-1 alpha-3 code representing the country in which the individual was born.Eg. "CAN", "DEU","USA"
taxId	String	No	Tax Id of the end user
dob	String	Yes	Date of birth of the user in YYYY-MM-DD
phone	String	No	End user’s telephone number, preferably in international format
timestamp	String	Yes	Unix epoch milliseconds; allowed skew is ±120 seconds
nonce	String	Yes	Unique random request string to prevent replay intercept actions

Request Body

{
  "emailId": "[e-mail]",
  "externalUserId": "user-10021",
  "firstName": "Joe",
  "lastName": "Doe",
  "dob": "2001-04-25",
  "countryOfResidence": "BRA",
  "countryOfCitizenship": "BRA",
  "countryOfBirth": "BRA",
  "taxId":"3100299900",
  "phone": "[phone]",
  "timestamp": 1784793600000,
  "nonce": "9d8934143ca747ebaaba3100f15cb4a1"
}

Code Snippet

JavaScript (Axios)

import crypto from 'crypto';
import axios from 'axios';

const apiKey = 'your-api-key';
const apiSecret = 'your-api-secret';

const requestBody = {
    emailId: '[e-mail]',
    externalUserId: 'u-xyz-987',
    firstName: 'Joe',
    lastName: 'Doe',
    dob: '2001-04-25',
    countryOfResidence: 'BRA',
    countryOfCitizenship: 'BRA',  // optional
    countryOfBirth: 'BRA', // optional
    taxId:'23100299900' // optional
    phone: '[phone]', // optional
    timestamp: Date.now(),
    nonce: crypto.randomBytes(8).toString('hex')
};

const raw = JSON.stringify(requestBody);
const signature = crypto.createHmac('sha256', apiSecret).update(raw).digest('hex');

const headers = {
    'x-tlp-apikey': apiKey,
    'x-tlp-signature': signature,
    'Content-Type': 'application/json'
};

axios.post('https://api.tylt.money/whitelabel/users/signup', raw, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error('Error:', error.response ? error.response.data : error.message));

Successful Response

New User Created

HTTP Status

201 Created

Response

{
  "msg": "User provisioned successfully.",
  "data": {
    "endUserId": 1012,
    "externalUserId": "user-10021",
    "ownerCode": "merchant-code",
    "kycStatus": "incomplete",
    "userUUID": "550e8400-e29b-41d4-a716-446655440000",
    "totpSecret": "JBSWY3DPEHPK3PXP",
    "totpQrCodeString": "otpauth://totp/..."
  }
}

Response Fields

Field	Description
endUserId	Tylt end-user ID
externalUserId	Merchant-provided user identifier
ownerCode	Merchant or wallet-program code
kycStatus	Current overall KYC status
userUUID	Tylt user UUID, returned only when the user is first created
totpSecret	Two-factor authentication secret, returned only when the user is first created
totpQrCodeString	Authenticator enrollment URI, returned only when the user is first created

Two-Factor Authentication Enrollment

The totpSecret and totpQrCodeString must be securely provided to the end user so that they can enroll an authenticator application.

The merchant must:

1. Store the credentials securely.

2. Never expose the secret in logs or analytics systems.

3. Display the QR code or enrollment information only to the relevant end user.

4. Require the end user to complete two-factor authentication enrollment before initiating transactions.

The TOTP credentials are returned only during the first successful user creation.

Existing User Response

When the same user already exists with the same externalUserId, the request is treated as idempotent.

HTTP Status

200 OK

Response

{
  "msg": "User already exists.",
  "data": {
    "endUserId": 1012,
    "externalUserId": "user-10021",
    "ownerCode": "merchant-code",
    "kycStatus": "approved"
  }
}

Credentials such as totpSecret, totpQrCodeString, and userUUID are not returned again.

User-Linking Behaviour

Where a user already exists under the merchant but is not yet mapped to the submitted externalUserId, Tylt may link the user to the merchant’s identifier.

A successful linking request returns:

200 OK

No new TOTP credentials are returned.

Possible Errors

HTTP Status	Message	Description
400	Validation error	One or more required fields are missing or invalid
401	Api Key authentication failed!	API key or signature is missing or invalid
403	API key or owner is inactive.	API access or merchant account is inactive
403	IP not whitelisted.	Request originated from an unauthorized IP address
409	externalUserId is already mapped to a different user.	The external ID is already assigned to another user
409	Email already registered under this owner with a different externalUserId.	The email and external ID conflict
429	Rate-limit error	Too many user-provisioning requests

---