Users

The Users API allows you to manage user profiles, balances, security settings, and authentication preferences. This includes operations like retrieving user information, updating profiles, managing two-factor authentication, and handling security codes.

The User Object

{
  "id": "443b4dd0-e8b3-11ec-bcf1-49674ab3a8ea",
  "name": "John",
  "surname": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "state": 1,
  "kycLevel": 4,
  "balance": 163202,
  "pendingIn": 1339174,
  "pendingOut": 0,
  "twoFaMode": 1,
  "logo": "https://umedia.tropipay.com/develop/user-id/logo-257.png",
  "createdAt": "2022-06-10T11:48:38.319Z",
  "updatedAt": "2025-07-24T05:50:54.066Z"
}

Attributes

Attribute	Type	Description
id	string	Unique identifier for the user (UUID).
name	string	User's first name.
surname	string	User's last name.
email	string	User's email address.
phone	string	User's phone number.
state	integer	Numeric code representing the user's account state (e.g., 1 for active).
kycLevel	integer	Know Your Customer verification level.
balance	integer	The user's primary account balance in cents.
pendingIn	integer	Total amount of incoming funds pending confirmation, in cents.
pendingOut	integer	Total amount of outgoing funds pending confirmation, in cents.
twoFaMode	integer	Numeric code for the two-factor authentication mode (e.g., 1 for enabled).
logo	string	URL to the user's profile logo/avatar.
createdAt	string	Timestamp of when the user was created.
updatedAt	string	Timestamp of the last update to the user's profile.

Retrieve User Profile

Retrieves the details of the authenticated user.

GET/users/profile

curl -X GET https://sandbox.tropipay.me/api/v3/users/profile \
  -H "Authorization: Bearer sk_test_..."

Response

{
  "id": "443b4dd0-e8b3-11ec-bcf1-49674ab3a8ea",
  "name": "John",
  "surname": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "state": 1,
  "kycLevel": 4,
  "balance": 163202,
  "pendingIn": 1339174,
  "pendingOut": 0,
  "twoFaMode": 1,
  "logo": "https://umedia.tropipay.com/develop/user-id/logo-257.png",
  "createdAt": "2022-06-10T11:48:38.319Z",
  "updatedAt": "2025-07-24T05:50:54.066Z",
  "group": { ... },
  "userDetail": { ... },
  "options": { ... }
}

Send Security Code

This endpoint sends a security code to the user's phone or email. It is a critical step during the registration process to validate and update the user's contact information, ensuring the account is secure.

POST/users/sendSecurityCode

curl -X POST https://sandbox.tropipay.me/api/v3/users/sendSecurityCode \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sms",
    "callingCode": "+1",
    "phone": "234567890"
  }'

Parameters

Parameter	Type	Required	Description
type	string	Yes	Type of verification (sms, email)
phone	string	Conditional	Required when type is sms
callingCode	string	Conditional	Required when type is sms. User's country calling code.
email	string	Conditional	Required when type is email

Validate Security Token

Validates a security code that was previously sent to the user.

POST/users/validateToken

curl -X POST https://sandbox.tropipay.me/api/v3/users/validateToken \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "securityCode": "123456",
    "type": "sms"
  }'

Parameters

Parameter	Type	Required	Description
securityCode	string	Yes	The 6-digit security code
type	string	Yes	Type of verification (sms, email, totp)

Response

A successful validation returns a boolean isValid, the complete user object, and a new, short-lived JSON Web Token (JWT). This new token should be used for subsequent actions that require a recently verified session.

info

Important: If the security code was sent to a new phone number not previously associated with the account, a successful validation will update the user's profile with the new number.

{
  "isValid": true,
  "user": {
    "id": "443b4dd0-e8b3-11ec-bcf1-49674ab3a8ea",
    "name": "John",
    "surname": "Doe",
    "email": "john.doe@example.com",
    "phone": "+3455555555",
    // ... other user fields
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Configure Two-Factor Authentication

Enables or disables two-factor authentication for the user account.

POST/users/2fa

curl -X POST https://sandbox.tropipay.me/api/v3/users/2fa \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "type": "totp",
    "securityCode": "123456"
  }'

Parameters

Parameter	Type	Required	Description
enabled	boolean	Yes	Whether to enable or disable 2FA
type	string	Yes	Type of 2FA (totp, sms)
securityCode	string	Yes	Verification code

Get 2FA Secret

Generates a new TOTP secret for setting up two-factor authentication.

POST/users/2fa/secret

curl -X POST https://sandbox.tropipay.me/api/v3/users/2fa/secret \
  -H "Authorization: Bearer sk_test_..."

Response

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCodeUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Response Parameters

Parameter	Type	Description
secret	string	Base32-encoded TOTP secret
qrCodeUrl	string	Data URL of QR code for easy setup

Change Password

Changes the user's account password.

POST/users/pass

curl -X POST https://sandbox.tropipay.me/api/v3/users/pass \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "oldPass": "password123",
    "newPass": "newpassword456"
  }'

Parameters

Parameter	Type	Required	Description
oldPass	string	Yes	Current password
newPass	string	Yes	New password

Disable User Account

Disables the user account, preventing further access.

POST/users/disable

curl -X POST https://sandbox.tropipay.me/api/v3/users/disable \
  -H "Authorization: Bearer sk_test_..."

Response

{
  "success": true,
  "message": "User account has been disabled"
}

Error Handling

The Users API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

• 2xx range indicate success
• 4xx range indicate an error that failed given the information provided
• 5xx range indicate an error with TropiPay's servers

Common Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid authentication
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error