Onboarding tasks

Every virtual-account user — individual or company — advances through a set of onboarding tasks. Each task represents one requirement that must be satisfied before the user can be assigned a virtual account. This page explains what each task is and, crucially, how it is completed — some happen automatically, others need you to submit data or upload a document, and some require review by Manteca.

How to read task status

Query a user's tasks with GET /wallet/v1/users/USERANYID (the onboarding array) or subscribe to the USER_ONBOARDING_UPDATE webhook, which pushes the tasks that changed. Each task carries a status:

StatusMeaning
PENDINGNot started — the task is waiting on you or on Manteca.
IN_PROGRESSReceived and being processed (e.g. a document was uploaded and is under review).
COMPLETEDSatisfied.
FAILEDRejected — action is needed (see Handling FAILED tasks).

A user can be assigned a virtual account only once all of its required tasks are COMPLETED.

How tasks complete

There are four ways a task reaches COMPLETED:

  • 🟢 Automatic — Manteca runs it in the background (compliance screening). No action from you.
  • ✍️ You submit — you provide data through an onboarding action.
  • 📎 You upload → reviewed — you upload a document; Manteca validates it. This step can end in FAILED, so always track it.
  • 🔗 You hand over a link → the user completes it — you request a link and give it to the user, who completes the step on their own device. The result reaches us directly, with no upload from your backend. It can end in FAILED, so always track it.

Base tasks (all countries)

Required for every virtual-account user.

TaskWhat it isHow it completes
IDENTITY_DECLARATIONYou declare the person's legal ID so the user record is created.✍️ You submit
BASIC_PERSONAL_DATA_DEFINITION_VAYou submit the person's (or company's) personal / corporate data.✍️ You submit
POLITICAL_CONSTRAINTS_VALIDATIONManteca screens the person's political exposure (PEP / FEP).🟢 Automatic
SECURITY_VALIDATIONManteca screens against terrorism and blacklists.🟢 Automatic

Identity verification (Brazil)

Brazil applies enhanced KYC — these two tasks are additionally required and gate activation.

TaskWhat it isHow it completes
IDENTITY_VALIDATIONUpload the identity document — one request per side (FRONT / BACK).📎 You upload → reviewed
EXTERNAL_LIVENESS_VALIDATIONThe face match, plus the provider's own verification of the person's data, which runs after the capture is approved — the task stays IN_PROGRESS until both are done. Requires BASIC_PERSONAL_DATA_DEFINITION_VA and IDENTITY_VALIDATION already COMPLETED. Completed either way: request a link with POST /wallet/v1/onboarding-actions/perform-external-liveness and hand it to the user, or record the user yourself and upload the video with POST /wallet/v1/onboarding-actions/upload-liveness-video-documentation.🔗 You hand over a link → the user completes it, or 📎 you upload a video

Conditional tasks (only if flagged)

These start optional and become required only when compliance screening flags the person. When that happens the task flips to required: true and you must upload the document.

TaskWhat it isHow it completes
PEP_DOCUMENTATION_VALIDATIONUpload proof of the person's source of funds. Required only if the person is flagged as a politically exposed person.📎 You upload → reviewed by Manteca compliance
FEP_DOCUMENTATION_VALIDATIONUpload proof of the person's source of funds. Required only if the person is flagged as fiscally exposed ("Sujeto Obligado" / UIF).📎 You upload → reviewed by Manteca compliance

One document covers both. For an individual, the document that satisfies these two tasks is the same one: proof of source of funds. Upload it once and every one of the two tasks that is required completes — a person flagged as both PEP and FEP submits a single file. Either endpoint takes it, and the one you pick has no effect on the outcome: POST /wallet/v1/onboarding-actions/upload-pep-documentation or upload-fep-documentation.

Already-approved documents count. The check is on the document, not on its timing. If the user already has an approved proof of source of funds when the screening flags them, the task is COMPLETED as soon as it becomes required, and there is nothing for you to upload. Read the task status before prompting the user for a file.

Company accounts

A company (BUSINESS) account adds tasks for the legal entity on top of the individual tasks that each of its legal representatives completes.

TaskWhat it isHow it completes
IDENTITY_VALIDATION_BUSINESSUpload the company's legal documents: articles of incorporation (ESTATUTO) and financial statement (BALANCE). Revenue declaration (REVENUE_DECLARATION) is optional.📎 You upload, reviewed by Manteca compliance
PEP_DOCUMENTATION_VALIDATIONRaised on the company itself when the screening flags it. Satisfied by the articles of incorporation (ESTATUTO) or the financial statement (BALANCE) — either one, and both are already required by IDENTITY_VALIDATION_BUSINESS, so there is no extra document to upload.📎 Already covered by the company documents
FEP_DOCUMENTATION_VALIDATIONRaised on the company itself when the screening flags it as fiscally exposed ("Sujeto Obligado"). Upload the company's AML/KYC policy through upload-fep-documentation against the company userAnyId.📎 You upload → reviewed by Manteca compliance
SHAREHOLDERS_ACTIVEEvery declared shareholder has been registered and screened.🟢 Automatic (screening)
LEGAL_REPRESENTATIVES_ACTIVEEvery legal representative has completed its own onboarding tasks.Aggregate of each representative's tasks

The company's source-of-funds rule is the individual one and does not apply here: proof of source of funds uploaded against the company userAnyId does not complete the company's PEP task. Its articles of incorporation or financial statement do, retroactively included — a company flagged after those documents were approved has the task COMPLETED from the start.

Each legal representative is a user in its own right and runs the base + identity tasks above, emitting its own USER_ONBOARDING_UPDATE events. A representative or a natural-person shareholder flagged as PEP or FEP follows the individual rule above — proof of source of funds, through either endpoint, against its own userAnyId. See Creating a virtual account for a company → Checking onboarding status.

Handling FAILED tasks

A document task moves to FAILED when the upload is invalid or the review rejects it (a rejection reason is included). Request a fresh upload URL for that document and re-upload the corrected file — the task returns to IN_PROGRESS and then COMPLETED once accepted. EXTERNAL_LIVENESS_VALIDATION is retried the same way, through either of its two routes: request a fresh liveness link and hand it to the user again, or record and upload a new video, as many times as needed. The routes are interchangeable, so a user who fails one can be retried through the other. Its rejectionReason names the provider step that failed: when that step is the person's data rather than the liveness itself (for example CAF, the match against Receita Federal), correct the personal data before requesting a new link. See Liveness check for the capture requirements and the usual rejection causes. Screening tasks (POLITICAL_CONSTRAINTS_VALIDATION, SECURITY_VALIDATION) that fail are terminal and are resolved by Manteca compliance, not by re-upload.

See Lifecycle and statuses for the account-level state machine.


Did this page help you?