Payouts

A Bre-B payout from Core is two calls: you resolve the destination, then you pay it. In the sandbox both calls run against the sandbox Bre-B directory, and a set of reserved values lets you trigger each error on demand instead of waiting for it to happen in production.

Before you start

You will need:

• A sandbox API key, and requests pointed at https://api.sandbox.cuentamono.com.
• The payouts scope on your credentials.
• The co_breb payout method enabled in your program. Ask Mono to enable it if your sandbox tenant does not have it yet.
• A funded subaccount to pay from. Payouts and target resolution only work on accounts of type subaccount; fund it with a topup before you start.

A successful payout

Any well-formed key that is not one of the reserved values below resolves, and every one of them resolves to the same sandbox creditor. An email (payee@example.com) or an alphanumeric key (@payee123) works.

1. Resolve the key with POST /v1/core/payouts/co_breb/targets/resolve:

   {
     "account_id": "lacc_...",
     "format": "plain_key",
     "value": "@payee123"
   }

   The response carries the target id and the creditor, masked: the document keeps its last three digits and each word of the name its first three letters. In the sandbox it is always the same person:

   {
     "type": "natural",
     "document_type": "CC",
     "document_number": "*****455",
     "full_name": "Jua*** Car*** Per*** Gom***"
   }

   Compare the creditor against the person you mean to pay before you move money. To walk the happy path end to end, register your test user with document CC 123143455.

2. Pay the resolved target with POST /v1/core/payouts, using target.kind: co_breb_target_id:

   {
     "method": "co_breb",
     "account_id": "lacc_...",
     "external_id": "withdrawal-0001",
     "target_amount": { "amount": 5000000, "currency": "COP" },
     "target": {
       "country": "CO",
       "currency": "COP",
       "kind": "co_breb_target_id",
       "target_id": "<id from step 1>"
     }
   }

   The call answers 201 with the payout in state processed. The rest of the lifecycle reaches you over webhooks: Mono sends one on every state change, and each one carries the full payout. Read its state to know where it is: created, processed, charged, sending_to_provider, sent_to_provider and finally successful. A failed payout ends in declined, rejected or returned, with the reason in state_reason.

3. Reconcile with GET /v1/core/payouts/find_successful_by using your external_id.

Errors when resolving a key

Send these values as value with format: plain_key. Each one answers synchronously, so you can test the message your users see without creating a payout.

The last row is not an error from Mono: the key resolves normally, but to a document that differs from the usual sandbox creditor (12314345500 instead of 123143455). Use it to prove that your integration compares the resolved creditor against your own records and refuses to pay when they differ.

Errors when creating the payout

These are validated before any money moves, so the payout is not created and the call answers 400.

Coming next

Next steps

• Payouts — how payouts, targets and fees fit together.
• Ledger — check the ledger entries each payout leaves behind.
• Production checklist — steps to take before processing real payouts.