Step 1 of 14
Configuration
API step
Authenticate
Exchange API credentials for a short-lived Bearer token (~20 minutes). Reuse the same token on every later call.
POST
https://api.cobre.co/v1/auth
Headers
| Content-Type | application/json |
Request body
{ "user_id": "cli_trust_co01",User IDiAPI user id issued by Cobre (cli_…). "secret": "sk_live_Trust9pQ2"SecretiAPI secret — treat like a password.}Response 201
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfdHJ1c3RfY28wMSJ9.Trust9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ",Access TokeniShort-lived bearer token. Attach as Authorization: Bearer on later calls. "type": "Bearer",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "expiration_time": 1200Expiration TimeiToken lifetime in seconds.}
Step 2 of 14
Configuration
API step
Subscribe to Lifecycle Events
Register webhooks for key registration, balance credits/debits (static-key payins and auto-sweep), and Money Movement status (R2P QR). Verify every delivery with HMAC-SHA256.
POST
https://api.cobre.co/v1/subscriptions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfdHJ1c3RfY28wMSJ9.Trust9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "url": "https://fiduciary.example.co/webhooks/cobre",Notification URLiHTTPS URL used by this resource (e.g. webhook endpoint). "description": "Trust encargo lifecycle",DescriptioniHuman-readable label or note. "events": [EventsiList of webhook event types this subscription listens to. "cobre_keys.status.registered", "cobre_keys.status.failed", "accounts.balance.credit", "accounts.balance.debit", "money_movements.status.initiated", "money_movements.status.processing", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected" ], "event_signature_key": "WHtrust9xZ"Signature keyiSecret you set on the subscription; Cobre uses it to HMAC-SHA256-sign deliveries (verify via event-signature + event-timestamp headers).}Response 201
{ "id": "sub_TrustEnc01",IdiUnique Cobre identifier for this resource. "url": "https://fiduciary.example.co/webhooks/cobre",Notification URLiHTTPS URL used by this resource (e.g. webhook endpoint). "description": "Trust encargo lifecycle",DescriptioniHuman-readable label or note. "events": [EventsiList of webhook event types this subscription listens to. "cobre_keys.status.registered", "cobre_keys.status.failed", "accounts.balance.credit", "accounts.balance.debit", "money_movements.status.initiated", "money_movements.status.processing", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected" ], "event_signature_key": "******9xZ",Signature keyiSecret you set on the subscription; Cobre uses it to HMAC-SHA256-sign deliveries (verify via event-signature + event-timestamp headers). "created_at": "2026-07-16T09:00:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 3 of 14
Encargo Onboarding
API step
Register Encargo Bank Account
Before creating the encargo Cobre Balance, register the encargo bank account as a counterparty (cp_…). Its id becomes metadata.primary_account — the auto-sweep destination for every credit received on the encargo balance.
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfdHJ1c3RfY28wMSJ9.Trust9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "geo": "col",GeographyiGeography code (e.g. col = Colombia, mex = Mexico). "type": "ch",Account typeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "alias": "Encargo 00123 - Banco destino",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Encargo Fiduciario 00123",Account holderiLegal or display name of the counterparty beneficiary. "beneficiary_institution": "1007",Bank codeiBank or institution code for the destination account. "account_number": "91234567890",Account numberiBank account or CLABE number for the counterparty. "counterparty_id_type": "nit",ID typeiType of identification document for the counterparty (e.g. nit, cc, rfc). "counterparty_id_number": "9001234567"ID numberiIdentification number for the counterparty. }}Response 201
{ "id": "cp_Encargo00123Bank",IdiUnique Cobre identifier for this resource. "geo": "col",GeographyiGeography code (e.g. col = Colombia, mex = Mexico). "type": "ch",Account typeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "alias": "Encargo 00123 - Banco destino",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Encargo Fiduciario 00123",Account holderiLegal or display name of the counterparty beneficiary. "beneficiary_institution": "1007",Bank codeiBank or institution code for the destination account. "account_number": "91234567890",Account numberiBank account or CLABE number for the counterparty. "counterparty_id_type": "nit",ID typeiType of identification document for the counterparty (e.g. nit, cc, rfc). "counterparty_id_number": "9001234567"ID numberiIdentification number for the counterparty. }, "created_at": "2026-07-16T09:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-16T09:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 4 of 14
Encargo Onboarding
API step
Create Encargo Cobre Balance
When a new encargo fiduciario is created, open a dedicated COP Cobre Balance (pr_col_cobre) and set metadata.primary_account to the encargo bank counterparty — auto-sweep is active from day one. Store the returned acc_… id — it is critical for all later fund operations.
POST
https://api.cobre.co/v1/accounts
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfdHJ1c3RfY28wMSJ9.Trust9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "provider_id": "pr_col_cobre",ProvideriCobre field at "provider_id" in this payload. "action": "create",ActioniCobre field at "action" in this payload. "tags": [TagsiCobre field at "tags" in this payload. "encargo_fiduciario" ], "alias": "Encargo 00123",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "primary_account": "cp_Encargo00123Bank"Primary accountiEncargo bank counterparty — every credit auto-sweeps here. }}Response 201
{ "id": "acc_Encargo00123",IdiUnique Cobre identifier for this resource. "provider_id": "pr_col_cobre",ProvideriCobre field at "provider_id" in this payload. "provider_name": "Cobre Balance Colombia",Provider NameiCobre field at "provider_name" in this payload. "connectivity": {ConnectivityiConnection/registration status for keys or accounts. "status": "connected",StatusiLifecycle status object for the resource or movement. "description": ""DescriptioniHuman-readable label or note. }, "alias": "Encargo 00123",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "cobre_tag": "@fidencargo00123",Cobre TagiCobre Balance tag identifying the destination account. "available_services": [Available ServicesiCobre field at "metadata.available_services" in this payload. "account_balance", "mm_push_from_account", "account_transactions" ], "primary_account": "cp_Encargo00123Bank"Primary accountiEncargo bank counterparty — every credit auto-sweeps here. }, "account_number": "",Account NumberiBank account or CLABE number for the counterparty. "account_type": "cobre_balance",Account TypeiCobre field at "account_type" in this payload. "obtained_balance": 0,Obtained BalanceiCobre field at "obtained_balance" in this payload. "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "tags": [TagsiCobre field at "tags" in this payload. "encargo_fiduciario" ], "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "created_at": "2026-07-16T09:06:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-16T09:06:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 5 of 14
Encargo Onboarding
API step
Create Static Bre-B Key
Register the encargo static Bre-B key on the Cobre Balance — the primary payin channel. Creation is asynchronous: do not share the key with payers until cobre_keys.status.registered arrives. The holder object is optional for this use case.
POST
https://api.cobre.co/v1/accounts/acc_Encargo00123Encargo balancei/keys
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfdHJ1c3RfY28wMSJ9.Trust9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "alias": "Llave encargo 00123",Key aliasiDisplay name that helps identify it and clarify its purpose. "key_config": "open_input",Key configiCobre field at "key_config" in this payload. "open_input": "fidencargo00123"Custom key valueiCobre field at "open_input" in this payload.}Response 201
{ "id": "key_Encargo00123",IdiUnique Cobre identifier for this resource. "key_value": "",Key ValueiBre-B key value (e.g. @merchant123). "source_id": "acc_Encargo00123",Source IdiCobre id of the source account or counterparty. "alias": "Llave encargo 00123",Key aliasiDisplay name that helps identify it and clarify its purpose. "connectivity": {ConnectivityiConnection/registration status for keys or accounts. "status": "processing",StatusiLifecycle status object for the resource or movement. "description": ""DescriptioniHuman-readable label or note. }, "previous_action": {Previous ActioniCobre field at "previous_action" in this payload. "action_requested": "create",Action RequestediCobre field at "previous_action.action_requested" in this payload. "action_code": "",Action CodeiCobre field at "previous_action.action_code" in this payload. "action_description": ""Action DescriptioniCobre field at "previous_action.action_description" in this payload. }, "created_at": "2026-07-16T09:07:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-16T09:07:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook delivered
cobre_keys.status.registeredBre-B registration completed — store key_value and expose it to payers. Map key_id and acc_Encargo00123 to encargo 00123 in your ledger.
Headers
| Content-Type | application/json |
Payload
{ "id": "ev_KeyEncRegistered",IdiUnique Cobre identifier for this resource. "event_key": "cobre_keys.status.registered",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-16T09:09:30Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "key_Encargo00123",IdiUnique Cobre identifier for this resource. "key_value": "@fidencargo00123",Key ValueiBre-B key value (e.g. @merchant123). "source_id": "acc_Encargo00123",Source IdiCobre id of the source account or counterparty. "alias": "Llave encargo 00123",AliasiDisplay name that helps identify it and clarify its purpose. "connectivity": {ConnectivityiConnection/registration status for keys or accounts. "status": "registered",StatusiLifecycle status object for the resource or movement. "description": ""DescriptioniHuman-readable label or note. }, "previous_action": {Previous ActioniCobre field at "content.previous_action" in this payload. "action_requested": "create",Action RequestediCobre field at "content.previous_action.action_requested" in this payload. "action_code": "",Action CodeiCobre field at "content.previous_action.action_code" in this payload. "action_description": ""Action DescriptioniCobre field at "content.previous_action.action_description" in this payload. }, "created_at": "2026-07-16T09:07:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-16T09:09:30Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}
Step 6 of 14
Static Key Payin (Model A)
API step
Collect via Static Key (Model A)
The payer sends funds from any bank app to @fidencargo00123. Bre-B settles in real time and Cobre credits acc_Encargo00123 with a breb_credit transaction — no Money Movement is created. Reconcile on accounts.balance.credit (primary) and cross-check with GET /accounts/{acct_id}/transactions (fallback).
GET
https://api.cobre.co/v1/accounts/acc_Encargo00123Encargo balancei/transactions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfdHJ1c3RfY28wMSJ9.Trust9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "total_items": 1,Total ItemsiTotal items matching the query across all pages. "total_pages": 1,Total PagesiNumber of pages in this result set. "is_last_page": true,Is Last PageiTrue when this is the final page of results. "page_items": 1,Page ItemsiNumber of items returned on this page. "contents": [ContentsiArray of result objects for this page. { "id": "trx_EncStatic001",Transaction IDiUnique Cobre identifier for this resource. "type": "breb_credit",Transaction typeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "account_id": "acc_Encargo00123",Account IdiCobre Balance account id affected by the event. "amount": 5000000,Amount (cents)iAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "contents.0.previous_balance" in this payload. "current_balance": 5000000,Current BalanceiCobre field at "contents.0.current_balance" in this payload. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "credit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-07-16T10:15:21Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-16T10:15:22Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "sender_account_number": "987654321",Sender Account NumberiMetadata field "sender_account_number" attached to the resource. "sender_account_type": "ch",Sender Account TypeiMetadata field "sender_account_type" attached to the resource. "sender_bank_code": "1007",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "sender_id": "1234567890",Sender IdiMetadata field "sender_id" attached to the resource. "sender_id_type": "cc",Sender Id TypeiMetadata field "sender_id_type" attached to the resource. "sender_name": "Juan Perez",Sender NameiMetadata field "sender_name" attached to the resource. "key_value": "@fidencargo00123",Cobre KeyiBre-B key value (e.g. @merchant123). "description": "Bre-B deposit encargo 00123",DescriptioniHuman-readable label or note. "mm_external_id": ""Mm External IdiMetadata field "mm_external_id" attached to the resource. } } ]}Webhook delivered
accounts.balance.creditPrimary reconciliation source for Model A payins. Map account_id to encargo 00123 and trx id to your ledger — no mm_id exists.
Headers
| Content-Type | application/json |
Payload
{ "id": "ev_EncBalCredit",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.credit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-16T10:15:22Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "trx_EncStatic001",IdiUnique Cobre identifier for this resource. "type": "breb_credit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "amount": 5000000,AmountiAmount in cents — the last two digits are decimals. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "date": "2026-07-16T10:15:21Z",DateiTimestamp when the balance transaction was posted (ISO 8601, UTC) — used in accounts.balance.* webhook notifications. "metadata": {MetadataiCustom key-value metadata attached to the resource. "sender_id_type": "cc",Sender Id TypeiMetadata field "sender_id_type" attached to the resource. "sender_account_type": "ch",Sender Account TypeiMetadata field "sender_account_type" attached to the resource. "sender_bank_code": "1007",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "sender_account_number": "987654321",Sender Account NumberiMetadata field "sender_account_number" attached to the resource. "description": "Bre-B deposit encargo 00123",DescriptioniHuman-readable label or note. "sender_name": "Juan Perez",Sender NameiMetadata field "sender_name" attached to the resource. "mm_external_id": "",Mm External IdiMetadata field "mm_external_id" attached to the resource. "key_value": "@fidencargo00123",Key ValueiBre-B key value (e.g. @merchant123). "sender_id": "1234567890"Sender IdiMetadata field "sender_id" attached to the resource. }, "account_id": "acc_Encargo00123",Account IdiCobre Balance account id affected by the event. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 5000000,Current BalanceiCobre field at "content.current_balance" in this payload. "credit_debit_type": "credit"Credit Debit Typeicredit = funds in; debit = funds out. }}
Step 7 of 14
Static Key Payin (Model A)
Reconciliation
Reconcile Static-Key Payin
Model A has no Money Movement — reconcile transaction-level on trx id and account_id. Cross-check webhook against GET /accounts/{acct_id}/transactions.
Mapping the webhook payload from an earlier step onto Encargo ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Encargo ledger field | |
content.account_id acc_Encargo00123 |
→ | cobre_acct_id Maps 1:1 to encargo 00123. |
content.id trx_EncStatic001 |
→ | cobre_trx_id Canonical reference — no mm_id. |
content.amount 5000000 |
→ | received_amount_cents |
content.metadata.key_value @fidencargo00123 |
→ | static_key_value |
Step 8 of 14
R2P QR Payin (Model B)
API step
Register Platform R2P Counterparty
For on-demand QR collections (Model B), register an r2p_breb counterparty with your platform display name (e.g. "Fiduciaria") — reused across encargos. This cp_… is the source_id of the R2P Money Movement.
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfdHJ1c3RfY28wMSJ9.Trust9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "geo": "col",GeographyiGeography code (e.g. col = Colombia, mex = Mexico). "type": "r2p_breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "alias": "Platform R2P QR",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Fiduciaria"Display nameiLegal or display name of the counterparty beneficiary. }}Response 201
{ "id": "cp_TrustR2p",IdiUnique Cobre identifier for this resource. "geo": "col",GeographyiGeography code (e.g. col = Colombia, mex = Mexico). "type": "r2p_breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "alias": "Platform R2P QR",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Fiduciaria"Display nameiLegal or display name of the counterparty beneficiary. }, "created_at": "2026-07-16T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-16T10:20:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 9 of 14
R2P QR Payin (Model B)
API step
Create R2P QR Collection (Model B)
When a payer needs a QR for a specific amount, POST /money_movements with source_id = platform r2p_breb counterparty, destination_id = encargo balance, metadata.r2p_rail = breb_key, and valid_until for QR expiry. Amount is integer cents (5000000 = COP $50,000). Reuse idempotency on retries — valid 24h.
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfdHJ1c3RfY28wMSJ9.Trust9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
| idempotency | encargo00123-qr-0001 |
Request body
{ "amount": 5000000,Amount (cents)iAmount in cents — the last two digits are decimals. "source_id": "cp_TrustR2p",R2P sourceiCobre id of the source account or counterparty. "destination_id": "acc_Encargo00123",Encargo balanceiCobre id of the destination account or counterparty. "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_key",R2P railiCobre field at "metadata.r2p_rail" in this payload. "key_config": "name",Key configiCobre field at "metadata.key_config" in this payload. "description_to_payer": "Pago encargo 00123",Description to payeriCobre field at "metadata.description_to_payer" in this payload. "description_to_payee": "Recaudo encargo 00123",Description To PayeeiCobre field at "metadata.description_to_payee" in this payload. "valid_until": "2026-07-17T22:00:00Z"QR expiryiCobre field at "metadata.valid_until" in this payload. }, "external_id": "encargo_00123"External IDiYour own reference echoed by Cobre for reconciliation.}Response 201
{ "id": "mm_R2pQr0001",IdiUnique Cobre identifier for this resource. "status": {StatusiLifecycle status object for the resource or movement. "state": "initiated",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "QR generated — awaiting payer authorization."DescriptioniHuman-readable detail for the current status. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_key",R2P railiCobre field at "metadata.r2p_rail" in this payload. "key_config": "name",Key configiCobre field at "metadata.key_config" in this payload. "qr_value": "00020101021226990014co.com.breb1...",Qr ValueiCobre field at "metadata.qr_value" in this payload. "description_to_payer": "Pago encargo 00123",Description to payeriCobre field at "metadata.description_to_payer" in this payload. "description_to_payee": "Recaudo encargo 00123",Description To PayeeiCobre field at "metadata.description_to_payee" in this payload. "valid_until": "2026-07-17T22:00:00Z"QR expiryiCobre field at "metadata.valid_until" in this payload. }, "creator": "cli_trust_co01",CreatoriAPI client id that created this resource. "external_id": "encargo_00123",External IDiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "r2p_breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_TrustR2p",R2P sourceiCobre id of the source account or counterparty. "destination_id": "acc_Encargo00123",Encargo balanceiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 5000000,Amount (cents)iAmount in cents — the last two digits are decimals. "created_at": "2026-07-16T10:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-16T10:25:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
When the payer scans and authorizes the QR, funds settle into acc_Encargo00123. Reconcile on external_id and mm_id. Cobre also posts r2p_breb_credit on the balance — see the Transaction tab.
Handle each terminal state in your webhook listener. Status codes reference the <a href="https://docs.cobre.com/money-movement-statuses-2032280m0" target="_blank" rel="noopener">Money Movement Statuses</a> guide. Cobre Balance transactions are covered in the <b>Transaction</b> tab.
Funds settled successfully. No error code is set (NA in the status guide). Use this webhook to mark the payment as paid in your system.
Event
money_movements.status.completedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_R2pQrCmp",IdiUnique Cobre identifier for this resource. "event_key": "money_movements.status.completed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-16T10:27:48Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "mm_R2pQr0001",IdiUnique Cobre identifier for this resource. "status": {StatusiLifecycle status object for the resource or movement. "state": "completed",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "",CodeiProvider or Cobre status code when the state is failed or rejected. "description": ""DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_key",R2p RailiMetadata field "r2p_rail" attached to the resource. "key_config": "name",Key ConfigiMetadata field "key_config" attached to the resource. "qr_value": "00020101021226990014co.com.breb1...",Qr ValueiMetadata field "qr_value" attached to the resource. "description_to_payer": "Pago encargo 00123",Description To PayeriMetadata field "description_to_payer" attached to the resource. "description_to_payee": "Recaudo encargo 00123",Description To PayeeiMetadata field "description_to_payee" attached to the resource. "valid_until": "2026-07-17T22:00:00Z"Valid UntiliMetadata field "valid_until" attached to the resource. }, "creator": "cli_trust_co01",CreatoriAPI client id that created this resource. "external_id": "encargo_00123",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "r2p_breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_TrustR2p",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_Encargo00123",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 5000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-16T10:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-16T10:27:48Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}Cobre or the rail could not process the movement. Inspect status.code and status.description — common failed codes include:
Possible status codes
F001 | Payment processing failed — please try again. |
F002 | NSF — not sufficient funds in the designated account. |
F003 | R2P payment link expired (payins). |
F004 | Daily transaction amount limit has been reached. |
F005 | Amount exceeds the maximum allowed transaction limit. |
F098 | Could not process the money movement at this time. |
F099 | Could not process the money movement at this time. |
Event
money_movements.status.failedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_R2pQrCmp",IdiUnique Cobre identifier for this resource. "event_key": "money_movements.status.failed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-16T10:27:48Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "mm_R2pQr0001",IdiUnique Cobre identifier for this resource. "status": {StatusiLifecycle status object for the resource or movement. "state": "failed",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "F002",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "NSF — not sufficient funds in the designated account."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_key",R2p RailiMetadata field "r2p_rail" attached to the resource. "key_config": "name",Key ConfigiMetadata field "key_config" attached to the resource. "qr_value": "00020101021226990014co.com.breb1...",Qr ValueiMetadata field "qr_value" attached to the resource. "description_to_payer": "Pago encargo 00123",Description To PayeriMetadata field "description_to_payer" attached to the resource. "description_to_payee": "Recaudo encargo 00123",Description To PayeeiMetadata field "description_to_payee" attached to the resource. "valid_until": "2026-07-17T22:00:00Z"Valid UntiliMetadata field "valid_until" attached to the resource. }, "creator": "cli_trust_co01",CreatoriAPI client id that created this resource. "external_id": "encargo_00123",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "r2p_breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_TrustR2p",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_Encargo00123",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 5000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-16T10:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-16T10:27:48Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}The bank or payment network rejected the transaction. Inspect status.code — common rejected codes include:
Possible status codes
R000 | Transaction rejected. |
R001 | Inactive or blocked account. |
R002 | Account and identification provided do not coincide. |
R005 | Account does not exist. |
R006 | Invalid account number. |
R009 | Exceeds maximum allowed amount. |
R018 | Payment rejected due to invalid key (payouts). |
R023 | Payment cancelled by the user. |
R026 | Payment rejected due to unavailable bank services. |
R034 | Account closed. |
R085 | Bank processing error (payouts). |
Event
money_movements.status.rejectedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_R2pQrCmp",IdiUnique Cobre identifier for this resource. "event_key": "money_movements.status.rejected",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-16T10:27:48Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "mm_R2pQr0001",IdiUnique Cobre identifier for this resource. "status": {StatusiLifecycle status object for the resource or movement. "state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "R001",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "Inactive or blocked account."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_key",R2p RailiMetadata field "r2p_rail" attached to the resource. "key_config": "name",Key ConfigiMetadata field "key_config" attached to the resource. "qr_value": "00020101021226990014co.com.breb1...",Qr ValueiMetadata field "qr_value" attached to the resource. "description_to_payer": "Pago encargo 00123",Description To PayeriMetadata field "description_to_payer" attached to the resource. "description_to_payee": "Recaudo encargo 00123",Description To PayeeiMetadata field "description_to_payee" attached to the resource. "valid_until": "2026-07-17T22:00:00Z"Valid UntiliMetadata field "valid_until" attached to the resource. }, "creator": "cli_trust_co01",CreatoriAPI client id that created this resource. "external_id": "encargo_00123",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "r2p_breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_TrustR2p",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_Encargo00123",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 5000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-16T10:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-16T10:27:48Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}When a payin Money Movement completes, Cobre credits the destination Cobre Balance and delivers accounts.balance.credit. Transaction type matches the movement type — see GET /accounts/{id}/transactions OAS examples.
When the payin settles, Cobre credits the destination Cobre Balance.
Event
accounts.balance.creditHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_R2pQr0001Cr",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.credit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-16T10:27:48Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "trx_R2pQr0001Cr",IdiUnique Cobre identifier for this resource. "type": "r2p_breb_credit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "account_id": "acc_Encargo00123",Account IdiCobre Balance account id affected by the event. "amount": 5000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 5000000,Current BalanceiCobre field at "content.current_balance" in this payload. "currency": "COP",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "credit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-07-16T10:27:48Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-16T10:27:48Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "sender_account_number": "",Sender Account NumberiMetadata field "sender_account_number" attached to the resource. "sender_account_type": "ch",Sender Account TypeiMetadata field "sender_account_type" attached to the resource. "sender_bank_code": "",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "sender_id": "",Sender IdiMetadata field "sender_id" attached to the resource. "sender_id_type": "cc",Sender Id TypeiMetadata field "sender_id_type" attached to the resource. "key_value": "",Key ValueiBre-B key value (e.g. @merchant123). "sender_name": "",Sender NameiMetadata field "sender_name" attached to the resource. "description": "Recaudo encargo 00123",DescriptioniHuman-readable label or note. "money_movement_id": "mm_R2pQr0001"Money Movement IdiMoney Movement that generated this balance transaction. } }}
Step 10 of 14
R2P QR Payin (Model B)
Reconciliation
Reconcile R2P QR Payin
Model B reconciliation is Money-Movement-level: join on external_id and mm_id. Fallback: GET /money_movements?external_id=encargo_00123.
Mapping the webhook payload from an earlier step onto Encargo ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Encargo ledger field | |
content.external_id encargo_00123 |
→ | encargo_reference |
content.id mm_R2pQr0001 |
→ | cobre_mm_id |
content.amount 5000000 |
→ | received_amount_cents |
content.status.state completed |
→ | payin_status Map completed → RECEIVED. |
Step 11 of 14
Fund Sweep
API step
Auto-Sweep to Encargo Bank
Because metadata.primary_account was set at account creation, every credit on acc_Encargo00123 auto-sweeps to cp_Encargo00123Bank (the encargo bank account). Cobre debits the encargo balance and pays out — watch accounts.balance.debit. Alternatives: schedulers (POST /money_movement_schedulers) or manual POST /money_movements.
GET
https://api.cobre.co/v1/accounts/acc_Encargo00123Encargo balancei/transactions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfdHJ1c3RfY28wMSJ9.Trust9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "total_items": 1,Total ItemsiTotal items matching the query across all pages. "total_pages": 1,Total PagesiNumber of pages in this result set. "is_last_page": true,Is Last PageiTrue when this is the final page of results. "page_items": 1,Page ItemsiNumber of items returned on this page. "contents": [ContentsiArray of result objects for this page. { "id": "trx_EncSweep001",Debit transaction IDiUnique Cobre identifier for this resource. "type": "col_payout_debit",Transaction typeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "account_id": "acc_Encargo00123",Account IdiCobre Balance account id affected by the event. "amount": 5000000,Amount swept (cents)iAmount in cents — the last two digits are decimals. "previous_balance": 5000000,Previous BalanceiCobre field at "contents.0.previous_balance" in this payload. "current_balance": 0,Current BalanceiCobre field at "contents.0.current_balance" in this payload. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "debit",Directionicredit = funds in; debit = funds out. "transaction_date": "2026-07-16T10:16:04Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-16T10:16:05Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Primary account auto-sweep to encargo bank"DescriptioniHuman-readable label or note. } } ]}Webhook delivered
accounts.balance.debitFires when auto-sweep debits acc_Encargo00123 after a payin credit. Funds are en route to the encargo bank account via Primary Account linkage.
Headers
| Content-Type | application/json |
Payload
{ "id": "ev_EncBalDebit",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-16T10:16:05Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "trx_EncSweep001",IdiUnique Cobre identifier for this resource. "type": "col_payout_debit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "amount": 5000000,AmountiAmount in cents — the last two digits are decimals. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "date": "2026-07-16T10:16:04Z",DateiTimestamp when the balance transaction was posted (ISO 8601, UTC) — used in accounts.balance.* webhook notifications. "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Primary account auto-sweep to encargo bank"DescriptioniHuman-readable label or note. }, "account_id": "acc_Encargo00123",Account IdiCobre Balance account id affected by the event. "previous_balance": 5000000,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 0,Current BalanceiCobre field at "content.current_balance" in this payload. "credit_debit_type": "debit"Credit Debit Typeicredit = funds in; debit = funds out. }}
Step 12 of 14
Reconciliation
API step
Daily Balance History (D+1)
On D+1 (~5 hours after midnight), pull summarized opening balance, total credits/debits, and closing balance per encargo for daily close. Filter by balance_date (YYYY-MM-DD).
GET
https://api.cobre.co/v1/accounts/acc_Encargo00123Encargo balancei/daily_balance_history?balance_date=2026-07-16Balance datei
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfdHJ1c3RfY28wMSJ9.Trust9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "total_items": 1,Total ItemsiTotal items matching the query across all pages. "total_pages": 1,Total PagesiNumber of pages in this result set. "is_last_page": true,Is Last PageiTrue when this is the final page of results. "page_items": 1,Page ItemsiNumber of items returned on this page. "Daily Balance history List": [Daily Balance history ListiCobre field at "Daily Balance history List" in this payload. { "id": "dbh_Enc00123Eod",IdiUnique Cobre identifier for this resource. "offset": "-05:00",OffsetiCobre field at "Daily Balance history List.0.offset" in this payload. "balance_date": "2026-07-16",Balance DateiCobre field at "Daily Balance history List.0.balance_date" in this payload. "initial_balance": "0",Initial BalanceiCobre field at "Daily Balance history List.0.initial_balance" in this payload. "total_credits": "10000000",Total CreditsiCobre field at "Daily Balance history List.0.total_credits" in this payload. "total_debits": "10000000",Total DebitsiCobre field at "Daily Balance history List.0.total_debits" in this payload. "end_balance": "0",End BalanceiCobre field at "Daily Balance history List.0.end_balance" in this payload. "created_at": "2026-07-17T10:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-17T10:00:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). } ]}
Step 13 of 14
Reconciliation
API step
Fallback: Query Money Movements
Mandatory fallback when webhooks may have been missed. Query R2P collections by external_id. Static-key payins have no mm_id — use GET /accounts/{acct_id}/transactions instead.
GET
https://api.cobre.co/v1/money_movements?external_id=encargo_00123External IDi
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfdHJ1c3RfY28wMSJ9.Trust9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "total_items": 1,Total ItemsiTotal items matching the query across all pages. "total_pages": 1,Total PagesiNumber of pages in this result set. "is_last_page": true,Is Last PageiTrue when this is the final page of results. "page_items": 1,Page ItemsiNumber of items returned on this page. "contents": [ContentsiArray of result objects for this page. { "id": "mm_R2pQr0001",IdiUnique Cobre identifier for this resource. "status": {StatusiLifecycle status object for the resource or movement. "state": "completed",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "",CodeiProvider or Cobre status code when the state is failed or rejected. "description": ""DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_key",R2p RailiMetadata field "r2p_rail" attached to the resource. "key_config": "name",Key ConfigiMetadata field "key_config" attached to the resource. "valid_until": "2026-07-17T22:00:00Z"Valid UntiliMetadata field "valid_until" attached to the resource. }, "creator": "cli_trust_co01",CreatoriAPI client id that created this resource. "external_id": "encargo_00123",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "r2p_breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_TrustR2p",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_Encargo00123",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 5000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-16T10:25:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-16T10:27:48Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). } ]}
Step 14 of 14
Reconciliation
Reconciliation
Close the Mixed Reconciliation Model
Webhooks are the primary source (accounts.balance.credit/debit, money_movements.status.*, cobre_keys.status.registered). Mandatory fallback: GET /accounts/{acct_id}/transactions for Model A, GET /money_movements for Model B, GET daily_balance_history for D+1 per-encargo close. Export via POST /reports when needed.
Mapping the API response from an earlier step onto Encargo ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Encargo ledger field | |
Daily Balance history List.0.balance_date 2026-07-16 |
→ | reconciliation_date |
Daily Balance history List.0.total_credits 10000000 |
→ | total_payins_cents Sum of Model A + Model B credits for the day. |
Daily Balance history List.0.total_debits 10000000 |
→ | total_sweeps_cents Auto-sweep debits to encargo bank. |
Daily Balance history List.0.end_balance 0 |
→ | closing_balance_cents Should be zero when all funds swept same day. |