Outgoing transfer use cases (Dispersiones)

An outgoing transfer is how your business sends money over Bre-B: you name a recipient by their payment key (or a pre-resolved target), Mono routes the funds, and webhooks track the result. The same endpoint covers a single seller payout, a verified refund, or a batch of hundreds — what changes is the configuration. This page lists the common scenarios and the fields to set for each.

Read Payment keys and Targets first if these terms are new. Amounts below are in centavos (1 COP = 100 centavos).

Before you start

You will need:

• A funded tenant account (tenant_account_id) to send from.
• A webhook endpoint for transfer and target-resolution events — see Webhook payloads.
• Familiarity with the outgoing-transfer lifecycle and the error reference.

How a transfer names its recipient

Every transfer in the transfers array identifies its recipient one of two ways:

• By key — a query Mono resolves for you: { "query": { "value": "3001234567" } }. The transfer passes through target_resolved before settling.
• By target — a target_id you already resolved (see UC-OT4 below): { "target_id": "bbtgt_..." }. This skips the resolution step.

Optionally add expected_creditor (document_type + document_number) to refuse the transfer if the resolved owner doesn't match.

UC-OT1 — Seller payment (single transfer)

Pay one seller by their key. A one-item batch is still a batch.

{
  "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj",
  "description": "Seller payout — order ORD-9931",
  "transfers": [
    {
      "query": { "value": "@MNVENDEDOR1" },
      "amount": { "amount": 8000000, "currency": "COP" },
      "external_id": "payout-ORD-9931"
    }
  ]
}

8000000 centavos = $80,000 COP. The transfer walks the full state machine created → processing → target_resolved → ... → successful, emitting webhooks at each step. This is the payout that completes a marketplace split.

UC-OT2 — Client refund (identity check)

Return funds to a specific person, refusing to pay if the key now belongs to someone else. Add expected_creditor.

{
  "query": { "value": "3001234567" },
  "amount": { "amount": 5000000, "currency": "COP" },
  "expected_creditor": { "document_type": "CC", "document_number": "1023711432" },
  "external_id": "refund-INV-552"
}

If the resolved owner matches, the transfer settles. If not, it fails with target_creditor_mismatch — see recipient validation errors. In sandbox, force the mismatch with the key sandbox@key_target_creditor_mismatch.err.

UC-OT3 — Post-sale split (batch)

Pay several recipients from one settled sale, mixing key types in a single batch. Pair this with the marketplace split collection: read the split rules from the collection.paid webhook, then send.

{
  "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj",
  "description": "Split for order ORD-9931",
  "transfers": [
    {
      "query": { "value": "@MNVENDEDOR1" },
      "amount": { "amount": 8000000, "currency": "COP" },
      "external_id": "split-1-vendor"
    },
    {
      "query": { "value": "@MNPLATFORM" },
      "amount": { "amount": 1000000, "currency": "COP" },
      "external_id": "split-2-platform"
    },
    {
      "query": { "value": "shipping@logistics.com" },
      "amount": { "amount": 500000, "currency": "COP" },
      "external_id": "split-3-shipping"
    }
  ]
}

Each transfer is tracked independently by its external_id; one failing does not roll back the others.

UC-OT4 — Pre-resolution (resolve → confirm → transfer)

When you want the payer to confirm the recipient before any money moves, resolve the key first, show the resolved name, then transfer by target_id.

1. Resolve — call Resolve target with the key.
2. Confirm — show the returned name, bank, and masked account to your user.
3. Transfer — create the transfer with the target_id from step 1 (no query).

{
  "transfers": [
    {
      "target_id": "bbtgt_5tgliBmzjZ6mpQPRbQjfKj",
      "amount": { "amount": 12000000, "currency": "COP" },
      "external_id": "confirmed-transfer-1"
    }
  ]
}

Because the recipient is already resolved, the transfer skips target_resolved and goes straight to settlement.

UC-OT5 — Batch supplier payments (mixed results)

A larger batch where some entries succeed and others are rejected. The create response returns accepted transfers and a rejected_transfers list; resolution failures (like a bad key) arrive later as outgoing_transfer.failed webhooks.

Handle both: reconcile the synchronous rejected_transfers (e.g. amount_exceeds_max_limit, duplicates) and subscribe to failure webhooks for per-transfer outcomes. See Handling rejected transfers.

UC-OT6 — Every key type

A transfer can target any of the five key types. Use the right query.value format:

Mono resolves each to the same kind of target; the resolved data shown back differs by type.

UC-OT7 — Error handling (sandbox)

Exercise every failure path deterministically in sandbox before going live:

• Resolution errors — set query.value to a trigger key such as sandbox@key_not_found.err, sandbox@key_suspended.err, or sandbox@key_target_creditor_mismatch.err.
• Settlement errors — encode the trigger in the transfer description (e.g. timeout, risk-control, creditor-account-not-found).
• Creation rejections — malformed requests (missing amount, unknown target, amount over the limit) are rejected synchronously with no webhooks.

The full list of state_reason codes, their meanings, and recommended handling is in the outgoing-transfer error reference. Walk the triggers end to end in Sandbox: outgoing transfers.

Next steps

• Collection use cases — the receiving side (and the split that feeds UC-OT3).
• Outgoing transfer flow — the end-to-end sequence and state machine.
• Sandbox: outgoing transfers — simulate any recipe above.