Every Cobre API call carries a short-lived Bearer token (~20 minutes). Your lending platform exchanges API credentials once and attaches the token to every subsequent request.

There is no checkout.* event — subscribe to Money Movement lifecycle events, cobre_keys.status.registered, and accounts.balance.credit/debit. Checkout creates a Money Movement once the payer selects a rail (track via MM webhooks + external_id). Static Bre-B payins credit the balance as breb_credit with no Money Movement — track via accounts.balance.credit.

One master/omnibus Cobre Balance funds all loan disbursements. Create it once at integration setup (skip on later runs if it already exists).

At loan origination, create one Cobre Balance per borrower. Checkout repayments and static Bre-B payins both credit this balance, giving per-borrower visibility in Cobre for collections.

Register a persistent Bre-B payin key on the borrower's Cobre Balance — always available without generating a new link per installment. Creation is asynchronous: do not share the key until cobre_keys.status.registered arrives.

Before the first Bre-B disbursement to a new borrower, run col_key_ownership_1 and block the payout until verification_result is matched. This replaces manual/OCR-based key validation on the lending platform.

Poll the Account Verification by id until status.state is completed. Continue with the payout only when verification_response.verification_result is matched; route unmatched or failed results to manual review.

Create a reusable counterparty for the borrower's Bre-B payout destination. Run only after Bre-B key Account Verification has returned matched.

Send approved loan principal from the master Cobre Balance to the borrower's verified Bre-B counterparty. Proceed only if the Account Verification step returned matched. Include a unique idempotency header (min. 9 chars, valid 24h) tied to the loan event.

Map money_movements.status.completed to your loan record via external_id. No API call — process the webhook payload in real time.

Mapping the webhook payload from an earlier step onto Lending platform. No API call is made — this step closes the loop in your own system.

When an installment is due, calculate the exact amount owed and create a Checkout for PSE, Bancolombia, or Nequi — credited to the borrower's individual Cobre Balance. Bre-B repayments use the static Cobre Key instead (see next steps). Set valid_until to the last day before overdue; once overdue, regenerate via your portal.

POST /checkouts does not return a Money Movement. When the borrower selects a rail on the hosted page, Cobre creates an R2P MM (initiated → completed) and sends money_movements.status.*. There is no checkout.* event — match by external_id; batch_id equals the Checkout chk_…. creator and source_id are the r2p counterparty Cobre created on the hosted page (this Checkout omitted source_id). GET defaults to nested=false — source and destination are null.

On money_movements.status.completed for the Checkout-triggered MM, update your ledger using external_id (= installment id). Cross-check accounts.balance.credit on the borrower's Cobre Balance.

Mapping the webhook payload from an earlier step onto Lending platform. No API call is made — this step closes the loop in your own system.

The borrower sends any amount from any Bre-B-enabled bank app to their static Cobre Key @xfin88231. Bre-B settles in real time and Cobre credits their Cobre Balance with a breb_credit transaction — there is no Money Movement. Match the credit to the loan in your ledger by borrower + amount + timestamp.

On accounts.balance.credit with a breb_credit transaction, match borrower balance + amount + timestamp to the open installment or apply against total owed. No external_id on the credit — your platform owns the allocation logic.

Mapping the webhook payload from an earlier step onto Lending platform. No API call is made — this step closes the loop in your own system.

At end-of-day, request Money Movement reports for disbursements and Checkout repayments, and Account Transaction reports for static Bre-B breb_credit payins over a date range.

Match report rows to loan/disbursement/installment records using external_id, mm_id, amount, and status.state. Use GET /money_movements as a fallback when webhooks were missed.

Mapping the Cobre report from an earlier step onto Finance / ERP. No API call is made — this step closes the loop in your own system.