Integrate virtual accounts (BaaS)
Give each of your users a dedicated local bank account (CVU in Argentina, PIX key in Brazil, CLABE in Mexico, Bre-B in Colombia) to receive deposits, hold a balance and send transfers. Examples use Brazil (BRL, PIX); country differences are called out where they matter. Countries, rails and which ones accept foreign users: Coverage.
At a glance
- Users: each user is onboarded under
/wallet/v1and gets one virtual account per currency. - Funds: payers transfer to the user's virtual account and the balance is credited there. Optionally, you pool deposits into a master account of your own and pay out from it.
- Tracking:
USER_ONBOARDING_UPDATEandUSER_WALLET_STATUS_UPDATEfor the user,VIRTUAL_ACCOUNT_STATUS_UPDATEfor the account,VIRTUAL_ACCOUNT_TRANSFER_STATUSandVIRTUAL_ACCOUNT_TRANSFER_REVERTEDfor money movements, or pollGET /wallet/v1/transfers/{transferAnyId}.
How it works
- Register the user and complete the onboarding tasks their country requires (in Brazil: identity document and liveness check).
- When the user is
ACTIVE, assign a virtual account. It startsPENDINGand becomesACTIVEwith its address. - Share the address. Deposits are detected and credited automatically.
- Send transfers out of the account to any local destination.
- Optional: sweep deposits into your master account and pay out from it.
- Reconcile with balances and the settlement report.
Before you start
- Your company must be enabled for virtual accounts in each country you operate. Otherwise assigning an account returns
403 PERMISSIONS. - Register your webhooks with
PATCH /wallet/v1/company. The update replaces thewebhooksmap, so send every URL you already have. AddSYNTHETIC_STATUS_UPDATEonly if you use collect and disburse synthetics.
{
"notificationInfo": {
"type": "WEBHOOK",
"secret": "your-webhook-secret",
"webhooks": {
"USER_ONBOARDING_UPDATE": "https://your-domain.com/webhooks/onboarding",
"USER_WALLET_STATUS_UPDATE": "https://your-domain.com/webhooks/user-status",
"VIRTUAL_ACCOUNT_STATUS_UPDATE": "https://your-domain.com/webhooks/va-status",
"VIRTUAL_ACCOUNT_TRANSFER_STATUS": "https://your-domain.com/webhooks/va-transfers",
"VIRTUAL_ACCOUNT_TRANSFER_REVERTED": "https://your-domain.com/webhooks/va-reversals"
}
}
}You can also send generalWebhook inside notificationInfo: it receives every event that has no URL of its own in webhooks. Your listener must accept POST and answer 2xx within 10 seconds, so store the event and process it asynchronously. Verify the md-webhook-signature header on every delivery and process duplicates idempotently (see Webhooks).
Webhooks are sent from four fixed IP addresses: allowlist all of them (see Webhooks).
Register the user
Create the user with POST /wallet/v1/onboarding-actions/simple. Identity fields go at the top level. email, name, legalId and legalIdNationality are required for an individual; externalId is your own reference and can be used as userAnyId afterwards.
Send address and nationality in this call (or later with POST /wallet/v1/onboarding-actions/define-personal-data). Without them the user stays in ONBOARDING. nationality is the person's own nationality; province is the 2-letter state code. An address must carry street, numeration, postalCode, locality and province (partial addresses are rejected); floor and apartment are optional. Only users with legalIdNationality: BRAZIL (a CPF) can get a BRL account.
{
"externalId": "user-br-001",
"email": "[email protected]",
"name": "JOHN",
"surname": "DOE",
"legalId": "12345678909",
"legalIdDocumentType": "CPF",
"legalIdNationality": "BRAZIL",
"nationality": "BRAZIL",
"birthDate": "1990-01-15",
"address": {
"street": "Rua Exemplo",
"numeration": "100",
"postalCode": "01000000",
"locality": "SAO PAULO",
"province": "SP",
"floor": "",
"apartment": ""
}
}Send the identity fields and birthDate. Foreign residents can be onboarded with their local ID.
{
"externalId": "user-ar-001",
"email": "[email protected]",
"name": "JUAN",
"surname": "PEREZ",
"legalId": "20300000003",
"legalIdDocumentType": "CUIT",
"legalIdNationality": "ARGENTINA",
"birthDate": "1990-01-15"
}Response 201 (trimmed)
{
"user": {
"id": "6c2d9285e491b28b021775aa",
"numberId": "100051",
"externalId": "user-br-001",
"status": "ONBOARDING",
"type": "INDIVIDUAL",
"exchange": "BRAZIL",
"onboarding": {
"BASIC_PERSONAL_DATA_DEFINITION_VA": { "required": true, "status": "PENDING" },
"IDENTITY_VALIDATION": { "required": true, "status": "PENDING" },
"EXTERNAL_LIVENESS_VALIDATION": { "required": true, "status": "PENDING" }
}
},
"causedConflict": false
}The onboarding map lists every task and whether it is required. Screening tasks run on their own. If you are unsure what data is still missing, call GET /wallet/v1/info/user-missing-data/USERANYID, which returns paths such as personalData.birthDate; an empty missingData array means nothing is missing.
A legalId that is already registered returns 409 USER_EXISTS (and an email already in use, 409 USER_EXISTS_EMAIL): fetch the existing user instead of creating it again.
Complete the required tasks
Track each task with USER_ONBOARDING_UPDATE (or poll GET /wallet/v1/users/USERANYID). When all required tasks are COMPLETED, the user becomes ACTIVE and USER_WALLET_STATUS_UPDATE fires.
Identity document. Call POST /wallet/v1/onboarding-actions/upload-identity-image once per side (FRONT and BACK), then PUT the file to the returned url (no md-api-key header, Content-Type matching the file). The URL expires in 90 seconds.
{ "userAnyId": "user-br-001", "side": "FRONT", "fileName": "id-front.jpg" }Liveness check. Available once personal data and the identity document are COMPLETED (before that: 409 USER_STATUS). Pick one route; both close EXTERNAL_LIVENESS_VALIDATION:
- Hosted link:
POST /wallet/v1/onboarding-actions/perform-external-livenesswith{"userAnyId": "user-br-001"}returns a single-useurlto hand to the user. Every call returns a fresh link, so request a new one when the user abandons the flow or the link was used.409 LIVENESS_URL_NOT_READYright after signup is transient: retry in a few seconds. After aFAILEDcheck, a new request also restarts the verification;409 LIVENESS_RESTART_FAILEDis transient too, retry later. - Your own video:
POST /wallet/v1/onboarding-actions/upload-liveness-video-documentationwithuserAnyId,fileNameandcapturedAt(within the last 24 hours), thenPUTthe video.
The task stays IN_PROGRESS for a few minutes after the capture while the person's data is verified. On FAILED, read rejectionReason and retry through either route; if it points at the person's data, fix the data first.
No document upload or liveness is required by default. The user activates once personal data is complete and screening passes.
PEP and FEP. Screening runs on its own after registration. When POLITICAL_CONSTRAINTS_VALIDATION is COMPLETED, check PEP_DOCUMENTATION_VALIDATION and FEP_DOCUMENTATION_VALIDATION: a flagged person has the task turned to required: true while it stays PENDING. Both tasks take the same document, a proof of source of funds, uploaded once through either endpoint (see PEP & FEP documentation). If an approved proof is already on file, the task is COMPLETED right away, so read its status before asking the user for a file. The review is manual.
Rejections. Any task can end FAILED, the automatic ones included. rejectionReason usually reads "<index>. <description>": the index is stable, so map it to your own messages, and the description is in Spanish. Manually reviewed documents and the liveness check carry free text without an index (see Rejection reason catalogs). To retry, call the same action again with the corrected data or file (for personal data, the registration call again with the same legalId). EXPIRED tasks are renewed the same way. Failed screening tasks are final: after a failed SECURITY_VALIDATION the user becomes INACTIVE, no reason is exposed, and only Manteca support can review it.
Company users (KYB, Brazil only). A company registers through the same call with type: "BUSINESS", its corporate data in personalData, its shareholders and its beneficiaries (legal representatives). Each representative is a separate user that completes the same identity checks as an individual, and the company uploads its own documents. The company becomes ACTIVE when SHAREHOLDERS_ACTIVE and LEGAL_REPRESENTATIVES_ACTIVE are COMPLETED; then you assign its account exactly as above. Webhooks carry no link to the parent company, so store every numberId from the registration response and match events by it. Full flow: Creating a virtual account for a company.
Assign the virtual account
Call POST /wallet/v1/user-actions/assign-virtual-account once per currency (ARS, BRL, MXN, COP) the user needs.
{ "userAnyId": "user-br-001", "asset": "BRL", "externalId": "user-br-001-brl" }Response 200
{
"id": "64b2c3d4e5f6a7b8c9d0e1f3",
"address": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"alias": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"status": "PENDING",
"bank": "PIX",
"currency": "BRL",
"externalId": "user-br-001-brl"
}Wait for VIRTUAL_ACCOUNT_STATUS_UPDATE with status: ACTIVE before sharing the account (or poll GET /wallet/v1/accounts/{accountAnyId}). address and alias are what payers use: the PIX key in Brazil, the CVU and its alias in Argentina. BRL accounts also carry qrCode, a static PIX copia e cola with no amount. An account that fails registration ends FAILED.
Receive deposits
Nothing to call: when a payer transfers to the address, the deposit is detected, credited and reported through VIRTUAL_ACCOUNT_TRANSFER_STATUS with type: DEPOSIT.
{
"event": "VIRTUAL_ACCOUNT_TRANSFER_STATUS",
"data": {
"id": "71c3d4e5-f6a7-48c9-8d0e-1f2a34567890",
"nationalId": "E012180001234567899s12345abc",
"type": "DEPOSIT",
"from": "payer-pix-key",
"fromLegalId": "12345678909",
"fromName": "JOHN DOE",
"to": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"currency": "BRL",
"amount": "150.00",
"status": "COMPLETED"
}
}- The first event can be
PENDING,COMPLETEDorCANCELLED, depending on the network.COMPLETEDmeans the funds are available. - Before acting on a deposit (crediting your ledger, sweeping it), check the signature, that
data.typeisDEPOSITanddata.statusisCOMPLETED, thatdata.tois an account you know, and thatdata.idis new to you. Storeid,nationalId,toandamount. CANCELLEDbeforeCOMPLETEDmeans the deposit was rejected and returned to the payer, never credited (for example an over-limit deposit, or a third-party deposit when same-name enforcement is on).- Same-name enforcement is opt-in per company: ask Manteca to enable it for deposits, withdrawals or both. Deposits from a legal ID other than the account holder's are then returned automatically.
- For a checkout with a known amount in Brazil,
POST /wallet/v1/deposit-actions/deposit-requestreturns an amount-specific PIX code.
Return a deposit. POST /wallet/v1/transfer-actions/{transferAnyId}/return with an empty body returns a completed deposit in full; send {"amount": "50.00"} for a partial return. The account must hold the amount (400 NO_FUNDS otherwise): if you already swept the deposit to your master account, transfer it back to the user's account and wait for COMPLETED first. 204 means the return was requested; the deposit moves COMPLETED → CANCELLED when it settles. If the deposit keeps its status and loses its reversalId, the bank rejected the return and you can request it again.
Send a transfer
Optionally preview the destination with GET /wallet/v1/address-info/{address} (exchange is required; URL-encode the key, for example + in phone keys as %2B and @ in email keys as %40) to show the recipient before paying.
GET /wallet/v1/address-info/e7a3c2f1-9b4d-4e8a-b2c1-5f3d7e9a8c2b?exchange=BRAZIL
{
"exchange": "BRAZIL",
"asset": "BRL",
"destination": "e7a3c2f1-9b4d-4e8a-b2c1-5f3d7e9a8c2b",
"recipientName": "JOHN DOE",
"recipientLegalId": "123******09",
"accountType": "PIX"
}Then call POST /wallet/v1/transfers. from is the user's account address, to the destination (PIX key or PIX QR in Brazil, CBU/CVU or alias in Argentina). Use a distinct externalId per transfer.
{
"from": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"to": "e7a3c2f1-9b4d-4e8a-b2c1-5f3d7e9a8c2b",
"currency": "BRL",
"amount": "100.00",
"comments": "Payout",
"externalId": "tx-ref-001"
}Response 202
{
"id": "64b2c3d4e5f6a7b8c9d0e1f2",
"externalId": "tx-ref-001",
"type": "WITHDRAW",
"amount": "100.00",
"filledAmount": "100.00",
"status": "PENDING"
}The balance is debited at creation; if it does not cover the amount, the call fails with 400 NO_FUNDS and nothing is created. A repeated externalId returns 409 TRANSFER_EXISTS: fetch the transfer with GET /wallet/v1/transfers/{externalId} instead of creating it again.
Optional: pool into a master account
If you concentrate liquidity in a master account of your own, the collect and disburse synthetics chain the transfers for you and report progress through SYNTHETIC_STATUS_UPDATE (STARTING, ACTIVE, then COMPLETED or CANCELLED).
-
Collect,
POST /wallet/v1/synthetics/collect: waits for a deposit into the user's account, then sweeps it to the master account.{ "userAnyId": "user-br-001", "asset": "BRL", "amount": "150.00", "externalId": "collect-0001" } -
Disburse,
POST /wallet/v1/synthetics/disburse: moves funds from the master account to the user's account and on todestination.address. If the last leg fails, the funds go back to the master account automatically and the synthetic endsCANCELLED.{ "userAnyId": "user-br-001", "asset": "BRL", "amount": "75.50", "destination": { "address": "e7a3c2f1-9b4d-4e8a-b2c1-5f3d7e9a8c2b" }, "externalId": "disburse-0001" }
Poll with GET /wallet/v1/synthetics/{syntheticAnyId}. A repeated externalId returns 409 SYNTHETIC_EXISTS.
You can also run the same flow with plain transfers from step 5: user account to master account after each COMPLETED deposit, and master account to user account, then user account to destination, for payouts. In that case you drive each leg from its webhook:
- Sweep (user account to master, for the exact deposit amount):
CANCELLEDbeforeCOMPLETEDleaves the funds in the user account; afterCOMPLETEDit means the sweep was reversed. Reconcile the user account balance before another attempt. - Funding leg (master to user account):
COMPLETEDstarts the destination leg;CANCELLEDbeforeCOMPLETEDmeans the payout failed and nothing else happens. - Destination leg (user account to destination):
CANCELLED, before or afterCOMPLETED, leaves the funds in the user account, so create the recovery leg (user account back to master). - A funding leg reversed after the destination leg exists, or a recovery leg that ends
CANCELLED, needs manual reconciliation: stop and compare both transfers and both balances.
Give every leg a distinct externalId derived from your operation (for example payout-20001-fund-user, payout-20001-send-destination, payout-20001-recover-master), store the returned ids, and apply each state change once (compare-and-set) so duplicate or stale webhooks never create a second leg.
Track the operation
Every transfer, deposit or withdrawal, ends in COMPLETED or CANCELLED:
| Status | Deposit | Withdrawal |
|---|---|---|
PENDING | Optional, wait. | Being processed, wait. |
COMPLETED | Funds credited. | Delivered. Keep accepting later reversals. |
CANCELLED before COMPLETED | Rejected, never credited. | Failed; the amount is back in the account. Read genericErrorMessage (for example C3: Account number does not exist). |
CANCELLED after COMPLETED | Returned to the payer. | Fully reversed by the network (E2: Transfer reverted). |
genericErrorMessage reads <code>: <description>; the letter gives the category (C account, D document, U user, B bank, R compliance, E generic). Persist the full value and key your logic on the code. C and D errors usually need corrected destination data or legal ID before another attempt. A reverted transfer also carries reversalId and reversalNationalId (the network end-to-end id of the return). Partial reversals keep the transfer COMPLETED and lower filledAmount; each one arrives as VIRTUAL_ACCOUNT_TRANSFER_REVERTED. Deduplicate that event by transferId + reversalId.
Webhooks are the trigger; to reconcile after downtime, fetch a transfer with GET /wallet/v1/transfers/{transferAnyId} or list them with GET /wallet/v1/transfers.
Balances. GET /wallet/v1/account-balances/{address} accepts the address, alias or externalId of any account, the master account included; GET /wallet/v1/account-balances lists them all.
{ "address": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "balance": { "BRL": "150.00" }, "externalId": "user-br-001-brl" }Limits. Each legal identity has one VIRTUAL_ACCOUNTS limit in USDT, shared by all its accounts, with monthly and yearly windows. The default is 10,000 USDT per month and 120,000 per year. Deposits and payouts draw down the same pool, so a round trip of 1,000 consumes 2,000. The limit is checked after the transfer is accepted: a deposit over the limit is returned to the payer, and a payout over the limit is accepted and then fails with R3: Exceeds virtual account limits. Do not retry either until the window resets or the limit is raised.
- Check the remaining allowance with
GET /wallet/v1/limits/{numberId}(availableMonthlyLimit,availableYearlyLimit; addassetto convert). - Before onboarding someone, query
GET /wallet/v1/limitswithlegalIdNationalityandlegalId. - Listen for
COMPLIANCE_NOTICE:CLOSE_TO_OPERATION_LIMITfires when 10% or less of a window remains,OPERATION_LIMIT_UPDATEDwhen the limit changes. - To raise it, upload a proof of fund origin with
POST /wallet/v1/documentation-actions/get-upload-url(docType: "FUNDS",associatedSubIdis the user'snumberId), thenPUTthe file. The review is manual; track it withGET /wallet/v1/documentations/{documentationAnyId}(valid: trueonce approved). A raise applies to the monthly window (see Raise limits).
{ "associatedSubId": "100051", "docType": "FUNDS", "fileName": "proof-of-funds.pdf", "extension": "pdf" }Settlement report. Request a CSV of every movement in a period with POST /wallet/v1/stats/account-movements-report (currency is optional; omit it for every currency). It returns 202 with a jobId. Poll GET /wallet/v1/stats/account-movements-report/{jobId} while status moves PENDING, PROCESSING, then COMPLETED (or FAILED), and download fileUrl (it expires after about 10 minutes; call again for a fresh one). Each row carries the counterparty, the end-to-end id, the resulting balance and a Sub Type: Deposit, Withdrawal, Reversal of Deposit, Reversal of Withdrawal, Sweep in or Sweep out (a sweep is a movement whose counterparty is your master account).
{ "from": "2026-07-01T00:00:00.000Z", "to": "2026-07-31T23:59:59.999Z", "currency": "BRL" }Test in sandbox
-
Simulate an incoming transfer with
POST /wallet/v1/sandbox-actions/create-deposit. It returns204and fires the usual deposit webhook. Withoutsender, the user's own data is used.{ "userAnyId": "user-br-001", "asset": "BRL", "amount": "150.00" } -
Outgoing PIX to any well-formed key reaches
COMPLETEDafter a few seconds. Use[email protected]as the destination to test theCANCELLEDpath (and the disburse recovery). -
A collect synthetic completes on its own, usually within seconds and sometimes after several minutes, so your handler sees delayed confirmations too.
-
Before going live, also check that one deposit creates exactly one sweep, that a failed payout creates exactly one recovery, that returning a completed (and already swept) deposit ends
CANCELLED, that replayed webhooks and stalePENDINGevents after a later status change nothing, and that you can reconcile every leg with theGETendpoints after turning your listener off for a while.
Errors
Every error response carries internalStatus (the stable value to key on), message (may change, so show your own text) and, on validation failures, errors[] with field detail.
Full catalog: Virtual Accounts error handling.
Go deeper
- Onboarding tasks and Creating a virtual account, including the liveness video requirements.
- Company accounts (KYB, Brazil only): Creating a virtual account for a company.
- Lifecycle and statuses, Collect and disburse synthetics and Receiving funds.
- Coverage, Operational limits, Settlement report and Country requirements.
-
Updated 27 days ago