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. When you transfer by target, send it on the resolve call instead (see UC-OT4): the target_id you get back already points to the expected person, and the transfer carries the same expected_creditor.

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. If you already know who should own it, add expected_creditor: Mono resolves only when the holder's document matches, and otherwise answers 400 with target_creditor_mismatch and no target_id.
2. Confirm — show the returned holder name, institution (participant_name), and masked account to your user.
3. Transfer — create the transfer with the target_id from step 1 (no query).

Step 1 request:

{
  "tenant_account_id": "bbtacc_5tgliBmzjZ6mpQPRbQjfKj",
  "format": "plain_key",
  "value": "3001234567",
  "expected_creditor": { "document_type": "CC", "document_number": "1023711432" }
}

Step 3 request:

{
  "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. When the resolution carried an expected_creditor, the transfer copies it, so its API response and webhooks show the same expected_creditor as a transfer by key.

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. The same keys work as the value of Resolve target: with an expected_creditor, the mismatch key answers 400 target_creditor_mismatch and a key that isn't a sandbox trigger resolves to the creditor you expect.
• 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.