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.
| Field | Type | Required | Description |
|---|---|---|---|
userAnyId | string | Yes | The user whose VA receives the deposit (id, numberId, or externalId). |
asset | string | Yes | Asset to collect, e.g. BRL. |
amount | string | Yes | Expected amount, as a string. The real amount is set when the deposit arrives. |
externalId | string | No | Your reference / idempotency ID. |
sessionId | string | No | Optional grouping ID for a user flow. |
payload | object | No | Arbitrary 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
- The synthetic waits for a deposit into the user's VA (stage 1,
DEPOSIT). - When the deposit is detected, it transfers the funds from the user's VA to the master account (stage 2,
TRANSFER). - Once that transfer settles, the synthetic becomes
COMPLETEDand 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 toCANCELLEDafter 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.
| Field | Type | Required | Description |
|---|---|---|---|
userAnyId | string | Yes | The user whose VA acts as the intermediary hop. |
asset | string | Yes | Asset to disburse, e.g. BRL. |
amount | string | Yes | Amount to disburse, as a string. |
destination.address | string | Yes | The destination key (for BRL, a PIX key: UUID, CPF, email, phone). |
externalId | string | No | Your reference / idempotency ID. Cannot be a purely numeric value. |
sessionId | string | No | Optional grouping ID for a user flow. |
payload | object | No | Arbitrary 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
- The synthetic transfers funds from the master account to the user's VA (stage 1,
TRANSFER). - It then transfers from the user's VA to the external destination (stage 2,
TRANSFER). - If stage 1 fails, the synthetic is cancelled directly — no funds have left the master account.
- If stage 2 fails, a third
TRANSFERstage returns the funds from the user's VA back to the master account. When that return completes, the synthetic ends asCANCELLED— notCOMPLETED. 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 instages[N].errors.
Statuses and lifecycle
Both synthetics share the same status set:
| Status | Terminal | Description |
|---|---|---|
STARTING | No | Synthetic created, first stage being set up. |
ACTIVE | No | A stage is running (deposit detection, sweep, or payout transfer). |
COMPLETED | Yes | All stages settled. Funds delivered (to the master account, or to the destination). |
CANCELLED | Yes | Final 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 reachesCOMPLETED, the operation is done.VIRTUAL_ACCOUNT_TRANSFER_STATUS— each deposit or withdrawal transfer involved in the synthetic. Filter by the payload'stypefield.
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
COMPLETEDon 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
COMPLETEDafter a few seconds. To test the stage-2 failure path (cancellation + reverse transfer + funds returned), use the destination key[email protected].
Updated 3 months ago