Creating a virtual account

Creating a virtual account

Provision a virtual bank account for a registered user. The user must reach ACTIVE status before a virtual account can be assigned.


Prerequisites

  1. Register the user by calling POST /wallet/v1/onboarding-actions/simple with the identity fields. The user is created in ONBOARDING status.
  2. Background compliance and screening checks run asynchronously: no extra client-side steps are required.
  3. If any required personal data is still missing, the user stays in ONBOARDING. Send the missing fields with POST /wallet/v1/onboarding-actions/define-personal-data, see Required personal data below.
  4. Once the user transitions to ACTIVE (signalled by the USER_WALLET_STATUS_UPDATE webhook), the virtual account can be assigned.

Required personal data

The simple onboarding takes the person's core identity as flat top-level fields (there is no nested personalData object):

FieldRequiredDescription
emailYesContact email. Required for individuals; for companies, send email or phoneNumber (see Creating a virtual account for a company).
phoneNumberNoContact phone.
nameYesFirst name.
surnameYesLast name.
legalIdYesTax / national ID (e.g. CPF for Brazil).
legalIdNationalityYesNationality of the legal ID (e.g. BRAZIL).
legalIdDocumentTypeNoDocument type, when applicable.
externalIdNoYour own identifier for the user (recommended for idempotency).
addressNot at signupNested object, see below. Needed before the user can reach ACTIVE for Brazil.
nationalityNot at signupThe person's nationality. Needed before the user can reach ACTIVE for Brazil. Any nationality is accepted.
birthDateNot at signupDate of birth, YYYY-MM-DD. Required to activate the user, see Date of birth below.

Address and nationality

For Brazilian individuals, address and nationality are required to activate the user, even though neither is required by the signup call itself. You can supply them in either of two ways:

Until both are present the user stays in ONBOARDING, and assigning a virtual account returns 409. That is expected: it is not an error in the signup call, which succeeds either way. Use the missing personal data endpoint to see exactly what is left.

nationality is not the same field as legalIdNationality: the latter is the country that issued the document (always BRAZIL for a CPF), while nationality is the person's own nationality. Any nationality is accepted: a foreign resident holding a CPF is a valid case.

If you send address, street, numeration, postalCode, locality and province must all be present: you can't send a partial address. floor and apartment are optional:

FieldRequiredDescription
streetYesStreet name.
numerationYesStreet number.
postalCodeYesPostal / ZIP code.
localityYesCity / locality.
provinceYesState / province. For Brazil, send the 2-letter state (UF) code (e.g. SP): at most 5 characters, or the request is rejected.
floorNoFloor. Send "" if not applicable.
apartmentNoApartment/unit. Send "" if not applicable.

Date of birth

birthDate is required before the user can be activated, in every country. Like address and nationality, it is not required by the signup call itself: you can send it in the simple body, or later inside personalData with POST /wallet/v1/onboarding-actions/define-personal-data. Until it is present the user stays in ONBOARDING and appears in missing personal data as personalData.birthDate.

Companies (type: BUSINESS) do not have a birthDate: they declare personalData.constitutionDate instead.


Check missing personal data

At any point after registering the user, call GET /wallet/v1/info/user-missing-data/USERANYID to see which of the required personalData fields from the table above are still missing. This checks against the WALLET-specific requirements: it is not the same as the CRIPTO onboarding missing-data endpoint, which validates a different field set.


Upload onboarding documentation

Some accounts require identity documents before the virtual account can be assigned: most notably BRL (PIX) accounts, due to stricter local regulation. Each document is uploaded in two steps: request a short-lived pre-signed URL, then PUT the file straight to it.

There is one endpoint per document type:

DocumentEndpointNotes
Identity documentPOST /wallet/v1/onboarding-actions/upload-identity-imageSend one request per side: both FRONT and BACK are required.
Proof of source of fundsPOST /wallet/v1/onboarding-actions/upload-pep-documentation or upload-fep-documentationOnly for people flagged as politically exposed (PEP) or fiscally exposed (FEP / Sujeto Obligado). One document, either endpoint, see below.

The face match is done separately, with the liveness check below: either by handing the user a hosted link or by uploading a video you recorded.

PEP and FEP take the same document. A person flagged as either (or both) submits proof of their source of funds, once. The two endpoints above are interchangeable entry points for that single file: whichever you use, the document completes every one of PEP_DOCUMENTATION_VALIDATION and FEP_DOCUMENTATION_VALIDATION that is required. If the user already has an approved proof of source of funds when the flag is raised, the task is COMPLETED on the spot and you upload nothing: check the task status before asking the user for a file. See PEP & FEP documentation for the full flow.

Step 1: Get the upload URL

Call the endpoint for the document you are uploading. The response returns a pre-signed url.

curl -X POST https://sandbox.manteca.dev/wallet/v1/onboarding-actions/upload-identity-image \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "userAnyId": "100009791",
      "side": "FRONT",
      "fileName": "legalid-front.jpg"
  }'
{ "url": "https://manteca-documentation.s3.amazonaws.com/upload-target" }

Step 2: Upload the file to the signed URL

PUT the raw file binary directly to the url from Step 1. Do not include the md-api-key header: this request goes straight to the storage URL. Set Content-Type to match the file format.

curl -X PUT 'SIGNED_URL_FROM_STEP_1' \
  -H "Content-Type: image/jpeg" \
  --data-binary '@/path/to/legalid-front.jpg'
🚧

The signed URL expires in 90 seconds, so upload immediately after requesting it. Repeat both steps for the other side (BACK) and for the proof of source of funds, if the user was flagged as PEP or FEP.


Liveness check

The face match is done with a liveness check, and there are two parallel ways to complete it. Both close the same EXTERNAL_LIVENESS_VALIDATION onboarding task, either one works for any user, and you can switch between them at any time: the first accepted capture wins. Pick whichever fits your integration:

❗️

Requires both BASIC_PERSONAL_DATA_DEFINITION_VA and IDENTITY_VALIDATION to already be COMPLETED: submit the person's data first (see Required personal data) and upload the identity document (see Upload onboarding documentation). Calling either route before both are done returns 409 USER_STATUS.

RouteUse it when
Hosted linkYou would rather not deal with the camera, the permissions or the capture UI. You hand the user a link and they complete the capture on their own device.
Video uploadYou already record video inside your own app and do not want to send the user out of your flow.

Hosted link

You request a single-use link and hand it to the user, and they complete a guided capture on their own device. Nothing is uploaded from your backend.

curl -X POST https://sandbox.manteca.dev/wallet/v1/onboarding-actions/perform-external-liveness \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userAnyId": "100009791" }'
{ "url": "https://liveness.manteca.dev/session/9f2c1b7a3d" }

As soon as this returns a url, EXTERNAL_LIVENESS_VALIDATION moves to IN_PROGRESS. You'll see this on the next USER_ONBOARDING_UPDATE webhook or by polling the user. When the user finishes the capture, the task stays IN_PROGRESS while the verification of the person's data completes. This can take several minutes after the capture is approved. Only then does Manteca move the task to COMPLETED or FAILED on its own, notifying you the same way. Do not treat a used link as a completed check.

📘

The link covers a single attempt. Call POST /wallet/v1/onboarding-actions/perform-external-liveness again (as many times as you need) to get a fresh one when the user abandons the flow, the link was already used, or the task came back FAILED. There is no retry limit.

🚧

Right after the user is created, the link may still be in preparation. In that case the endpoint answers 409 with internalStatus: LIVENESS_URL_NOT_READY. This is transient, not a rejection: retry the same request after a few seconds and you will get the url.

🚧

When the task is FAILED, requesting a new link also restarts the verification. If it cannot be restarted yet, the endpoint answers 409 with internalStatus: LIVENESS_RESTART_FAILED. This is also transient: retry the same request later. The previous link is not returned again.

Video upload

You record the user yourself and upload the file the same two-step way as any other onboarding document. The capture is guided by you, so the video has to follow the sequence and the file requirements below: that is what keeps this route equivalent to the hosted link.

What to ask the user to do. Show these instructions in your app before recording:

  • Only their face in frame, centred and close enough to fill a good part of it.
  • Face uncovered: no hat, sunglasses or face mask.
  • Even, frontal light; avoid backlight and heavy shadows.
  • While recording, turn the head slowly to one side and then to the other.

No audio is needed: the check runs on the image only.

File requirements

RequirementValue
Format.mp4, .mov or .webm
DurationAround 5 seconds
ResolutionBetween 480 × 640 px and 1280 × 720 px
Frame rate15 FPS or higher
Maximum size15 MB

The frame-rate floor is what keeps natural movement (the head turn, a blink) smooth enough to be read. Below it the check has nothing to work with, no matter how good the resolution is.

Step 1: Get the upload URL

Call POST /wallet/v1/onboarding-actions/upload-liveness-video-documentation with the user and the moment the video was recorded. The response returns a pre-signed url.

curl -X POST https://sandbox.manteca.dev/wallet/v1/onboarding-actions/upload-liveness-video-documentation \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "userAnyId": "100009791",
      "fileName": "liveness.mp4",
      "capturedAt": "2026-07-02T15:30:00.000-03:00"
  }'
{ "url": "https://manteca-documentation.s3.amazonaws.com/upload-target" }

capturedAt is when the video was recorded, in ISO-8601 with offset. It must be within the last 24 hours and cannot be in the future: a stale or future date is rejected with 400. Record and upload in the same session whenever you can.

Step 2: Upload the video to the signed URL

PUT the raw video binary directly to the url from Step 1. Do not include the md-api-key header: this request goes straight to the storage URL. Set Content-Type to match the file format.

curl -X PUT 'SIGNED_URL_FROM_STEP_1' \
  -H "Content-Type: video/mp4" \
  --data-binary '@/path/to/liveness.mp4'
🚧

The signed URL expires in 90 seconds, so upload immediately after requesting it.

Once the video is uploaded, EXTERNAL_LIVENESS_VALIDATION moves to IN_PROGRESS and then to COMPLETED or FAILED, notifying you through the USER_ONBOARDING_UPDATE webhook: same as the hosted link.

If the video is rejected, the rejectionReason names the cause. The usual ones are:

  • No face detected in the video.
  • More than one person in frame.
  • The head movement is missing, so liveness could not be established.
  • The video is too short, or its frame rate is too low for the movement to be read.
  • The image is too dark, blurry or out of focus.
  • The face is covered (hat, sunglasses, mask).

Record a new video and upload it again: there is no retry limit. You can also fall back to the hosted link for that user; the two routes are interchangeable.

The checks are processed asynchronously; each upload and the liveness check complete their onboarding task (IDENTITY_VALIDATION, EXTERNAL_LIVENESS_VALIDATION, PEP_DOCUMENTATION_VALIDATION, FEP_DOCUMENTATION_VALIDATION) once validated. A BRL (PIX) virtual account can only be assigned after all required tasks reach COMPLETED. See Onboarding tasks for the full list of tasks and how each one completes.

When every required task reaches COMPLETED, the user's status becomes ACTIVE and the USER_WALLET_STATUS_UPDATE webhook fires: the user is then ready for account assignment.

Handling rejections. If a check is rejected, its task moves to FAILED and the USER_ONBOARDING_UPDATE payload carries a rejectionReason. For EXTERNAL_LIVENESS_VALIDATION, retry through either route: request a fresh liveness link and hand it to the user again, or upload a new video; for a document, request a fresh upload URL and re-PUT the corrected file. A liveness rejectionReason comes as free text describing the step that failed. If the failed step is not the liveness itself but the person's data (for example CAF, the match against Receita Federal), a new capture will not fix it: correct the user's personal data first (see Required personal data) and then request a fresh link. The task returns to IN_PROGRESS and then COMPLETED once accepted. A SECURITY_VALIDATION failure (a sanctions / watchlist hit) is different: it is a hard stop: the user is set to INACTIVE, cannot be re-submitted self-service, and requires contacting Manteca support.


Create the account

Use POST /wallet/v1/user-actions/assign-virtual-account to provision the account.

curl -X POST https://sandbox.manteca.dev/wallet/v1/user-actions/assign-virtual-account \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "userAnyId": "100009791",
      "asset": "ARS",
      "externalId": "user-acc-001"
  }'

Account creation is asynchronous. The account starts in PENDING and transitions to ACTIVE once the banking network confirms it.

A user can hold one virtual account per asset (up to four today: ARS, COP, MXN, and BRL), not just one overall. Call the endpoint once per asset you need. Requesting an asset the user already has an account for returns 409 (BANK_ACCOUNT_EXISTS).


Wait for activation

Listen for the VIRTUAL_ACCOUNT_STATUS_UPDATE webhook to know when the account is ready:

{
  "event": "VIRTUAL_ACCOUNT_STATUS_UPDATE",
  "data": {
    "address": "0000003100098765432100",
    "alias": "COMPANY.USER.ARS",
    "legalId": "20-12345678-9",
    "platform": "WALLET",
    "companyId": "64b2c3d4e5f6a7b8c9d0e1f2",
    "status": "ACTIVE",
    "externalId": "user-acc-001"
  }
}

You can also poll GET /wallet/v1/accounts/{accountAnyId} to check the current status.


Share the account address

Once the account is ACTIVE, the address and alias fields contain the local bank account details (CVU, PIX key, etc.). Share these with your user so they can receive deposits.

See Lifecycle and statuses for the full account state machine.


Per-country requirements

The onboarding payload before a virtual account can be assigned varies per jurisdiction. See the dedicated country pages for the exact payload and any country-specific extras:


Did this page help you?