Users Creation

The Users Creation module lets you manage the complete onboarding lifecycle of users through your API integration with Vita. This covers creating users (natural persons or businesses), capturing required documentation, triggering identity verification (KYC for individuals, KYB for businesses), and tracking the verification status throughout its lifecycle. The module is designed to support secure, standardized, regulation-compliant onboarding directly from your application, with full control over when verification is initiated and full visibility into its outcome.

What you can do

Create users

Natural persons or businesses, in a single call or progressively.

Capture data progressively

Initial registration, documentation uploads, identity verification, regulatory compliance.

Patch existing users

Complete missing fields before submitting for verification.

Trigger verification on demand

Submit for verification via the submit_for_verification field.

Query verification status

Check any user’s status at any time.

Receive webhooks

Automatic notifications when verification status changes.

User types

Vita Business supports two user categories, each with its own verification flow:

Category	Description	Verification flow
`natural`	A natural person registering as an individual.	KYC (Know Your Customer)
`business`	A legal entity registering as an organization or company.	KYB (Know Your Business)

Both types must complete their respective verification flow before being authorized to operate on the platform.

User lifecycle

A user created via the API moves through the following statuses, tracked in the profile_verification field:

Status	Description
`initial`	The user has been created, but not all required information has been provided. Verification has not yet been triggered.
`started`	All required information has been submitted, and the verification process is in progress.
`verification_required`	Additional information was requested for the account to be accepted.
`accepted`	Verification was approved. The user is authorized to operate.
`rejected`	Verification was rejected. The user is not authorized to operate.

Lifecycle flow

Creation

A new user is created with category set to natural or business.

Initial state

If required information is missing, the user enters the initial status. They can be updated via PATCH to add the missing fields.

Submission

When all required fields are present, your integration triggers verification by sending submit_for_verification: true. This moves the user to started.

Resolution

Once Vita’s team reviews the user, the status moves to accepted, verification_required, or rejected.

At any point in the lifecycle, your integration can query the user’s status to determine whether they’re approved, rejected, or pending information.

How `submit_for_verification` works

Set submit_for_verification: true in the user creation (POST) or update (PATCH) request to instruct the API to initiate verification once all required fields are present.
If the field is omitted or set to false, the user is created (or updated) without starting verification, so you can build the profile progressively across multiple requests.
Once verification has been triggered and the user is in started, accepted, or rejected, this flag has no further effect.

When to use it

Scenario	Recommended approach
You have all required information at creation time	Set `submit_for_verification: true` in the `POST` request to create and submit in a single call.
You collect user data progressively across multiple steps	Create the user without `submit_for_verification`, then `PATCH` the user as new data arrives. When the final required field is captured, send `submit_for_verification: true` in the same `PATCH` to trigger verification.

Progressive onboarding (PATCH flow)

For integrations that collect user information across multiple steps (e.g., a multi-screen onboarding flow), Vita supports progressive updates via PATCH. You can build the user’s profile incrementally without triggering verification until you’re ready.

Create the user with initial data

POST /businesses/users
{ "category": "natural", "email": "user@example.com", "first_name": "John", ... }

Patch as additional fields arrive

PATCH /businesses/users/:id
{ "address": "...", "document_number": "...", "facial_image": {...} }

Trigger verification when complete

PATCH /businesses/users/:id
{ "submit_for_verification": true }

This flow gives you full flexibility to design the onboarding experience while ensuring verification only runs when the user’s data is complete.

Data model

Natural user structure

Field	Description
`email`	User’s email address.
`first_name`	User’s first name.
`last_name`	User’s last name.
`category`	User type (`natural`).
`birthdate`	Date of birth (`YYYY-MM-DD`).
`gender`	User’s gender.
`document_type`	Type of identity document (`dni`, `passport`, etc.).
`document_number`	Primary document number.
`secondary_document_number`	Secondary document number, if applicable.
`document_expedition_date`	Issuance date of the primary document.
`address`	Full address.
`zipcode`	Postal code.
`civil_status`	Civil status (`single`, `married`, …).
`phone`	Phone number including country code.
`profile_verification`	Current verification status.
`accept_pep`	Accepts PEP verification (`true`/`false`).
`accept_real_info`	Accepts real-information validation.
`accept_funds`	Accepts receiving funds.
`ocupation`	Profession or occupation.
`natural_interests`	Platform usage interests (`use_interests`, `other_usability`).
`url_notify_kyc`	Webhook URL for KYC notifications.
`disable_email_notifications`	Disables email notifications.
`country`	Country of residence.
`state`	State or province.
`city`	City.
`birth_country`	Country of birth.
`document_issuing_country`	Country that issued the identity document.
`facial_image`	Facial image file (`filename`, `content_type`).
`document_front`	Front of the document image.
`document_back`	Back of the document image.
`business_external_id`	Custom ID assigned by the client for tracking.

Business user — main fields

Field	Description
`email`	User’s email address.
`first_name`	User’s or business account name.
`category`	`business`.
`document_type`	Document type for the main user.
`document_number`	Primary document number.
`address`	Main user’s address.
`zipcode`	Postal code.
`profile_verification`	Current verification status.
`accept_pep`	Accepts PEP verification.
`accept_real_info`	Accepts real-information validation.
`accept_funds`	Accepts receiving funds.
`business_external_id`	Custom ID for tracking.
`is_business_api`	Has Business API credentials.
`x_login`	API login key.
`x_trans_key`	API transaction key.
`secret`	API secret key.
`url_notify_kyc`	Webhook URL for KYC notifications.
`disable_email_notifications`	Disables email notifications.
`country`	Country of residence.
`state`	State/province.
`city`	City.
`facial_image`	Facial image file.
`document_front`	Front of the document image.
`document_back`	Back of the document image.

Business object (company)

Represents the legal and commercial information of the company linked to the user — general company data, activity, physical address, legal documentation, and legal representative details.

Field	Description
`operation_countries`	Countries where the company operates.
`website_url`	Company website.
`uuid`	Internal company identifier.
`trade_name`	Trade name.
`is_financial_company`	Is a financial entity.
`has_license`	Holds a license.
`same_to_legal_location`	Physical location matches legal address.
`physical_country`	Country of the physical location.
`physical_state`	State/province of the physical location.
`physical_city`	City of the physical location.
`physical_zipcode`	Postal code of the physical location.
`physical_address`	Physical address.
`lr_first_name`	Legal representative — first name.
`lr_last_name`	Legal representative — last name.
`lr_phone_number`	Legal representative — phone.
`lr_document_number`	Legal representative — document number.
`lr_document_issuing_country`	Legal representative — document issuing country.
`lr_document_expedition_date`	Legal representative — document issuance date.
`lr_secondary_document_number`	Legal representative — secondary document number.
`lr_civil_status`	Legal representative — civil status.
`lr_occupation`	Legal representative — occupation.
`lr_gender`	Legal representative — gender.
`lr_document_type`	Legal representative — document type.
`lr_birthdate`	Legal representative — birthdate.
`expected_monthly_payments_usd`	Expected monthly payments range.
`business_interests`	Company usage interests.
`company_statute`	Company statute (PDF).
`tax_identity_document`	Tax identity document (image).
`statement_of_funds_document`	Statement of funds (PDF).
`extra_document`	Additional document (image).
`legal_representative_proof_document`	Legal representative proof document (PDF).

Business owner (UBO)

Ultimate Beneficial Owners — natural persons who own or control a significant percentage of the company.

Field	Description
`ubo_first_name`	UBO first name.
`ubo_last_name`	UBO last name.
`ubo_residence_country`	Country of residence.
`ubo_residence_state`	State or province of residence.
`ubo_residence_city`	City of residence.
`ubo_address`	Address.
`ubo_is_direct`	Is a direct owner.
`ubo_ownership_percentage`	Ownership percentage.
`ubo_document_type`	Document type.
`ubo_document_number`	Document number.
`ubo_country`	Country of birth.
`ubo_start_date`	Date became owner.
`ubo_document_expedition_date`	Document issuance date.
`ubo_has_control`	Has control over the company.
`ubo_is_signer`	Is an authorized signatory.
`ubo_title_position`	Title or position in the company.
`ubo_birthdate`	Date of birth.
`ubo_phone`	Phone number.
`ubo_email`	Email address.
`ubo_zipcode`	Postal code.
`ubo_document_image`	Document image.
`ubo_back_document_image`	Document back image.

Politically Exposed Person (PEP)

Include this object only if accept_pep is true. It identifies the person and their relation to relevant public activities.

Field	Description
`first_name`	First name of the PEP.
`last_name`	Last name of the PEP.
`document_number`	Identification document.
`job_title`	Public job title or position.

Permitted values for specific fields

Use the exact values below when creating or updating users.

Field	Permitted values
`gender`	`male`, `female`, `other`
`document_type`	`dni`, `company_id`, `passport`, `dni_foreigner`, `company_ruc`, `special_type`
`secondary_document_type`	`s_dni`, `s_company_id`, `s_passport`, `s_dni_foreigner`, `s_company_ruc`, `s_special_type`
`civil_status`	`single`, `married`, `divorced`, `separated`, `widowed`
`category`	`natural`, `business`
`lr_document_type`	`dni`, `company_id`, `passport`, `dni_foreigner`, `company_ruc`, `special_type`
`lr_gender`	`male`, `female`, `other`
`lr_civil_status`	`single`, `married`, `divorced`, `separated`, `widowed`
`expected_monthly_payments_usd`	`usd_0_to_40000`, `usd_40000_to_500000`, `usd_500000_plus`
`ubo_document_type`	`dni`, `company_id`, `passport`, `dni_foreigner`, `company_ruc`, `special_type`

Verification status notification

Whenever a user changes their profile_verification status, Vita Wallet sends an HTTP POST notification to the url_notify_kyc URL you provided.

Field	Description
`business_external_id`	Custom ID assigned by the client.
`email`	User’s email address.
`profile_verification`	Current verification status.

The merchant must validate the notification by calculating the signature from the request body and headers (Authorization, X-Date, X-Login, X-Trans-Key).

hash = { business_external_id: "ext-v7", email: "example@email.com", profile_verification: "started" }
// -> "business_external_idext-v7emailexample@email.comprofile_verificationstarted"

Vita Business sends the notification every 10 minutes for up to 3 days, until it receives a 200 response from the merchant’s server.

Security (important)

Requests to the Users module are signed using HMAC-SHA256, the same algorithm used by the rest of the Vita API — but with one critical difference.

Do not sort or concatenate the request body keys. For the Users module, the request body must be used exactly as a JSON string when generating the HMAC signature.

All other aspects of the signature process remain the same (x-login, x-date, API keys, Authorization header format).

const payload = JSON.stringify({
  first_name: "John",
  category: "natural",
  document_number: "123456789",
  // ...
});
const signature = CryptoJS
  .HmacSHA256(xLogin + xDate + payload, secretKey)
  .toString(CryptoJS.enc.Hex);

Use the request body exactly as shown above (as a JSON string) when generating the signature. This requirement applies only to the Users module — it’s the only part of the API that must be signed this way.

Payins

Exchange

Payouts

Transactions

Users

Webhooks

What you can do

Create users

Capture data progressively

Patch existing users

Trigger verification on demand

Query verification status

Receive webhooks

User types

User lifecycle

Lifecycle flow

How `submit_for_verification` works

When to use it

Progressive onboarding (PATCH flow)

Data model

Permitted values for specific fields

Verification status notification

Security (important)

​What you can do

Create users

Capture data progressively

Patch existing users

Trigger verification on demand

Query verification status

Receive webhooks

​User types

​User lifecycle

​Lifecycle flow

​How submit_for_verification works

​When to use it

​Progressive onboarding (PATCH flow)

​Data model

​Permitted values for specific fields

​Verification status notification

​Security (important)

What you can do

User types

User lifecycle

Lifecycle flow

How `submit_for_verification` works

When to use it

Progressive onboarding (PATCH flow)

Data model

Permitted values for specific fields

Verification status notification

Security (important)