Collect and disburse synthetics

Collect and disburse are synthetics — orchestrated, multi-step operations — built on top of virtual accounts. They automate a common pooled-account setup so you don't have to chain the individual transfers yourself.

This is an advanced flow for a specific case: pooling funds across many user accounts into a single master account. If you only need to receive into and send from one account, use plain deposit detection and transfers instead.


When to use

Each of your users has their own virtual account (VA). A master account is one of your own virtual accounts that concentrates liquidity. Two synthetics cover the pooled flow:

  • Collect — pull an incoming deposit from a user's VA into the master account. Use it to concentrate funds you receive across many users.
  • Disburse — push funds out from the master account, through a user's VA, to an external destination. Use it to pay out from your pooled liquidity.

Account model

COLLECT                          DISBURSE

   Payer                          Master account
     │ deposit                          │ transfer
     ▼                                  ▼
  User VA                            User VA
     │ sweep                            │ transfer
     ▼                                  ▼
 Master account                  External destination

Collect — receive into a master account

POST /wallet/v1/synthetics/collect

Creates a collect synthetic that waits for a deposit into the user's VA and then sweeps it to the master account.

FieldTypeRequiredDescription
userAnyIdstringYesThe user whose VA receives the deposit (id, numberId, or externalId).
assetstringYesAsset to collect, e.g. BRL.
amountstringYesExpected amount, as a string. The real amount is set when the deposit arrives.
externalIdstringNoYour reference / idempotency ID.
sessionIdstringNoOptional grouping ID for a user flow.
payloadobjectNoArbitrary metadata, echoed back in the response and webhooks.
curl -X POST https://sandbox.manteca.dev/wallet/v1/synthetics/collect \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "externalId": "collect-brl-000001",
      "userAnyId": "user-br-000001",
      "asset": "BRL",
      "amount": "150.00",
      "payload": { "reference": "invoice-10001" }
  }'

The response is the synthetic object, starting in STARTING, with two stages: a DEPOSIT stage (the address is the user's VA — for BRL, their PIX key) and a TRANSFER stage that sweeps to the master account.

Flow

  1. The synthetic waits for a deposit into the user's VA (stage 1, DEPOSIT).
  2. When the deposit is detected, it transfers the funds from the user's VA to the master account (stage 2, TRANSFER).
  3. Once that transfer settles, the synthetic becomes COMPLETED and the funds are available on the master account.

Same-name enforcement. Deposits into the user's VA may be subject to same-name enforcement. A rejected deposit is returned to the payer before being credited; the collect stays ACTIVE, waiting for a valid deposit, and expires to CANCELLED after a few days of inactivity (or when you replace it with a new one).


Disburse — pay out from a master account

POST /wallet/v1/synthetics/disburse

Creates a disburse synthetic that moves funds from the master account, through the user's VA, to an external destination (any PIX key for BRL).

We recommend previewing the destination first with GET /wallet/v1/address-info/{address} to confirm the recipient's name and masked document before disbursing.

FieldTypeRequiredDescription
userAnyIdstringYesThe user whose VA acts as the intermediary hop.
assetstringYesAsset to disburse, e.g. BRL.
amountstringYesAmount to disburse, as a string.
destination.addressstringYesThe destination key (for BRL, a PIX key: UUID, CPF, email, phone).
externalIdstringNoYour reference / idempotency ID. Cannot be a purely numeric value.
sessionIdstringNoOptional grouping ID for a user flow.
payloadobjectNoArbitrary metadata, echoed back in the response and webhooks.
curl -X POST https://sandbox.manteca.dev/wallet/v1/synthetics/disburse \
  -H "md-api-key: $MD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "externalId": "disburse-brl-000001",
      "userAnyId": "user-br-000001",
      "asset": "BRL",
      "amount": "75.50",
      "destination": { "address": "6bf14d0e-6f4f-47e5-a7b7-c81ab2a5a57d" },
      "payload": { "reference": "payout-20001" }
  }'

Flow

  1. The synthetic transfers funds from the master account to the user's VA (stage 1, TRANSFER).
  2. It then transfers from the user's VA to the external destination (stage 2, TRANSFER).
  3. If stage 1 fails, the synthetic is cancelled directly — no funds have left the master account.
  4. If stage 2 fails, a third TRANSFER stage returns the funds from the user's VA back to the master account. When that return completes, the synthetic ends as CANCELLED — not COMPLETED. No recovery action is required on your side. If the return transfer also fails, the funds stay in the user's VA and the case requires manual intervention — contact Manteca. The reason for the failure is available in stages[N].errors.

Statuses and lifecycle

Both synthetics share the same status set:

StatusTerminalDescription
STARTINGNoSynthetic created, first stage being set up.
ACTIVENoA stage is running (deposit detection, sweep, or payout transfer).
COMPLETEDYesAll stages settled. Funds delivered (to the master account, or to the destination).
CANCELLEDYesFinal failure or expiration. For a disburse stage-2 failure, funds have already been returned to the master account via the reverse stage.

Tracking

Treat SYNTHETIC_STATUS_UPDATE as the canonical source of truth for the operation.

  • SYNTHETIC_STATUS_UPDATE — the synthetic changed status or advanced a stage. When it reaches COMPLETED, the operation is done.
  • VIRTUAL_ACCOUNT_TRANSFER_STATUS — each deposit or withdrawal transfer involved in the synthetic. Filter by the payload's type field.

Polling fallback: GET /wallet/v1/synthetics/{syntheticAnyId} returns the same synthetic object.

See Webhooks for configuration, signatures, and payload details.


Errors

Disburse can fail on creation (synchronous HTTP error) or be cancelled asynchronously when a transfer stage fails, in which case the failing stage carries a typed statusMessage. See Error handling for the full list of creation errors and cancellation reason codes.


Testing in sandbox

The sandbox simulates PIX so you can test end to end without real money — no external action is needed to "pay" a collect or settle a disburse.

  • Collect — the synthetic moves to COMPLETED on its own: ~95% after about 10 seconds, ~4% after about 5 minutes, ~1% after about 15 minutes. Use this to confirm your webhook handler tolerates delayed confirmations.
  • Disburse — any well-formed PIX key settles as COMPLETED after a few seconds. To test the stage-2 failure path (cancellation + reverse transfer + funds returned), use the destination key [email protected].

Did this page help you?