Receiving funds

Receiving funds

When someone sends money to a virtual account address, the deposit is detected automatically and the balance is credited. No API call is required on your side.


How deposits work

  1. An external party sends funds to the virtual account address (CVU, PIX key, etc.)
  2. Manteca detects the incoming transfer
  3. The account balance is credited automatically
  4. A VIRTUAL_ACCOUNT_TRANSFER_STATUS webhook fires with type: DEPOSIT

Same-name enforcement

Optionally, a virtual account can require that the counterparty of a transfer is the account's own holder: the counterparty's legal ID (e.g. CPF/CNPJ in Brazil) must match the user's. The check runs per transfer, per virtual account — it applies to any deposit, whether or not a collect synthetic is active on the account.

  • Opt-in per account, off by default. Ask Manteca to enable it on the accounts you need.
  • Deposits and withdrawals are configured separately — you can enforce it on one direction only.
  • Rejection happens before crediting. A deposit from a non-matching sender is automatically returned to the payer and the balance is never credited. The deposit goes from PENDING to CANCELLED without passing through COMPLETED, and on networks that reverse the original transfer it also arrives as a VIRTUAL_ACCOUNT_TRANSFER_REVERTED with type: DEPOSIT. The CANCELLED deposit carries E2: Transfer reverted; the rejection reason is not exposed.
  • Transfers against the master virtual account are exempt from the check.

Use the account's own PIX QR

Every BRL virtual account carries a qrCode field — a static PIX copia e cola for that account, with no amount and no expiration. It comes in GET /wallet/v1/accounts/{accountAnyId} and in the VIRTUAL_ACCOUNT_STATUS_UPDATE webhook, so a top-up flow needs no extra call. For a checkout with a known amount, generate an amount-specific QR instead.


Generate an amount-specific PIX QR

For a checkout-style flow, call POST /wallet/v1/deposit-actions/deposit-request with the wallet user's identifier, BRL, and the expected amount. This returns both a PIX copia e cola code and a hosted QR url.

curl -X POST https://sandbox.manteca.dev/wallet/v1/deposit-actions/deposit-request \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "userAnyId": "user-br-000001",
      "asset": "BRL",
      "network": "PIX",
      "amount": "150.00",
      "externalId": "deposit-qr-000001"
  }'

The QR supplies payment instructions. A VIRTUAL_ACCOUNT_TRANSFER_STATUS event with type: DEPOSIT and status: COMPLETED confirms that the funds were received.


Test a fiat deposit in sandbox

Use POST /wallet/v1/sandbox-actions/create-deposit to simulate an incoming fiat transfer to the user's virtual account. The action returns 204 No Content; observe the normal VIRTUAL_ACCOUNT_TRANSFER_STATUS webhook or query the transfers endpoint to confirm the completed deposit.

The optional sender identifies the simulated originator. If it is omitted, the wallet user's person data is used.

curl -X POST https://sandbox.manteca.dev/wallet/v1/sandbox-actions/create-deposit \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "userAnyId": "user-br-000001",
      "asset": "BRL",
      "amount": "150.00"
  }'

This action is only available in sandbox and requires the user to have a virtual account for the requested fiat asset.


Webhook: VIRTUAL_ACCOUNT_TRANSFER_STATUS

{
  "event": "VIRTUAL_ACCOUNT_TRANSFER_STATUS",
  "data": {
    "id": "64c3d4e5f6a7b8c9d0e1f2a3",
    "externalId": "dep-ext-00112",
    "nationalId": "2026032600001234",
    "type": "DEPOSIT",
    "from": "0140000003000012345678",
    "fromLegalId": "20-87654321-0",
    "fromName": "Juan Pérez",
    "to": "0000003100098765432100",
    "toLegalId": "20-12345678-9",
    "toName": "María González",
    "currency": "ARS",
    "amount": "50000.00",
    "status": "COMPLETED",
    "concept": "VAR",
    "companyId": "64b2c3d4e5f6a7b8c9d0e1f2",
    "creationTime": "2026-03-26T14:30:00.000Z",
    "updatedAt": "2026-03-26T14:30:05.000Z"
  }
}

PENDING is optional for deposits. The supported lifecycle paths are:

PathMeaning
PENDING → COMPLETED or COMPLETEDDeposit completed and the funds are available.
PENDING → CANCELLED or CANCELLEDDeposit rejected before completion and returned to the sender, for example by same-name enforcement or a virtual account limit. The funds were never credited.
COMPLETED → CANCELLEDThe completed deposit was returned manually.

For a manual return, call POST /wallet/v1/transfer-actions/{transferAnyId}/return. The user virtual account must contain the deposit amount; fund it from the master account first if the deposit was already swept. A successful request returns 204 No Content: the return was requested from the bank, not settled. The deposit carries a reversalId from that moment, and while it is there a second return request for the same deposit is refused with 409.

To return only part of a deposit, send {"amount": "50.00"} in the body. Each partial return lowers the deposit's filledAmount by its own amount and arrives as its own VIRTUAL_ACCOUNT_TRANSFER_REVERTED with partial: true; the deposit turns CANCELLED once filledAmount reaches 0. A return for more than the remaining filledAmount is refused with 409, and a partial return on a network that returns by sending a new transfer instead of reversing the original one is refused with 501.

Read the state of the return off the deposit with GET /wallet/v1/transfers/{transferAnyId}:

DepositWhat to do
Status unchanged, with reversalIdWait. The return is in flight.
CANCELLEDNothing. The return settled and the deposit is final.
Status unchanged, no reversalIdCall the endpoint again. The bank rejected the return and the amount is back in the virtual account.

A rejection changes no status and fires no webhook, so the reversalId disappearing is the only signal. The amount is credited back to the virtual account when that happens, so a retry needs no extra funding and no longer hits the 409. The reason the bank gives is not exposed on the API: if a return is rejected twice for the same deposit, contact Manteca instead of retrying a third time, and send the funds back with a regular transfer if the account cannot receive them.

After the return request is accepted, track the original deposit through VIRTUAL_ACCOUNT_TRANSFER_STATUS. Its transition from COMPLETED to CANCELLED confirms that the funds were returned to the original sender. Depending on the network behind the virtual account, the return may also arrive as a VIRTUAL_ACCOUNT_TRANSFER_REVERTED with partial: false. If neither arrives, contact Manteca.


Querying deposits and balances


Did this page help you?