Step 1 of 6
Configuration
API step
Authenticate
Exchange API credentials for a short-lived Bearer token (~20 minutes). Reuse the same token string on every later call in this flow.
POST
https://api.cobre.co/v1/auth
Headers
| Content-Type | application/json |
Request body
{ "user_id": "cli_demo_co_bulk01",User IDiAPI user id issued by Cobre (cli_…). "secret": "sk_live_2Hg8nP4qR7"SecretiAPI secret from key creation — treat like a password.}Response 201
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19idWxrMDEIn0.BlkP9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ",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 6
Configuration
API step
Subscribe to Bulk & Payout Events
Subscribe to Bulk Money Movement batch status, individual Money Movement line status, and Cobre Balance debits. Bulk completed means every line reached a terminal MM state. Verify deliveries with HMAC-SHA256.
POST
https://api.cobre.co/v1/subscriptions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19idWxrMDEIn0.BlkP9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "url": "https://yourplatform.co/webhooks/cobre",Notification URLiHTTPS endpoint that receives Cobre POST notifications. "description": "Bulk payout lifecycle",DescriptioniLabel for this subscription in the Cobre portal. "events": [EventsiList of webhook event types this subscription listens to. "bulk_money_movements.status.validating", "bulk_money_movements.status.processing", "bulk_money_movements.status.completed", "bulk_money_movements.status.failed", "money_movements.status.initiated", "money_movements.status.processing", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected", "accounts.balance.debit" ], "event_signature_key": "WHblkCo9xZ"Signature keyiSecret you provide; Cobre HMAC-signs each delivery.}Response 201
{ "id": "sub_BulkPay01",IdiUnique Cobre identifier for this resource. "url": "https://yourplatform.co/webhooks/cobre",Notification URLiHTTPS endpoint that receives Cobre POST notifications. "description": "Bulk payout lifecycle",DescriptioniLabel for this subscription in the Cobre portal. "events": [EventsiList of webhook event types this subscription listens to. "bulk_money_movements.status.validating", "bulk_money_movements.status.processing", "bulk_money_movements.status.completed", "bulk_money_movements.status.failed", "money_movements.status.initiated", "money_movements.status.processing", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected", "accounts.balance.debit" ], "event_signature_key": "******9xZ",Signature keyiSecret you provide; Cobre HMAC-signs each delivery. "created_at": "2026-07-03T10:00:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 3 of 6
Bulk Payout
API step
Register a Beneficiary Counterparty
Register at least one beneficiary before bulk upload — use destination_id in the bulk file for known counterparties. The second demo line uses an inline destination object to create a counterparty on the fly (same fields as POST /counterparties).
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19idWxrMDEIn0.BlkP9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "geo": "col",Geographyicol = Colombia. "type": "ch",Account typeicc = checking, ch = savings, dp = deposit — Fast Pay / ACH payout. "alias": "Vendor A - bulk line 1",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Maria Gomez",Beneficiary nameiLegal name of the account holder. "beneficiary_institution": "1007",Bank codeiBeneficiary institution code (e.g. 1007 = Bancolombia). "account_number": "1013661234",Account numberiColombian bank account number. "counterparty_id_type": "cc",ID typeiColombian identification type. "counterparty_id_number": "5298765432"ID numberiBeneficiary identification number. }}Response 201
{ "id": "cp_BeneficiaryBulk01",IdiUnique Cobre identifier for this resource. "geo": "col",Geographyicol = Colombia. "type": "ch",Account typeicc = checking, ch = savings, dp = deposit — Fast Pay / ACH payout. "alias": "Vendor A - bulk line 1",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Maria Gomez",Beneficiary nameiLegal name of the account holder. "beneficiary_institution": "1007",Bank codeiBeneficiary institution code (e.g. 1007 = Bancolombia). "account_number": "1013661234",Account numberiColombian bank account number. "counterparty_id_type": "cc",ID typeiColombian identification type. "counterparty_id_number": "5298765432"ID numberiBeneficiary identification number. }, "created_at": "2026-07-03T10:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-03T10:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 4 of 6
Bulk Payout
API step
Submit Bulk Payout File
Upload a JSON array via multipart/form-data (field file). Demo includes two lines: line 1 pays an existing counterparty (destination_id); line 2 embeds a destination object to create a new bank counterparty inline. Response id (bat_…) becomes batch_id on every child Money Movement. Do not send checker_approval_decision unless modeling maker-checker bulk.
POST
https://api.cobre.co/v1/bulk_money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19idWxrMDEIn0.BlkP9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Multipart upload
| file | @bulk_payouts_batch_001.json |
File content
[ { "amount": 1500000, "source_id": "acc_FundingCOP01", "destination_id": "cp_BeneficiaryBulk01", "metadata": { "description": "Vendor A payment", "reference": "bulk_ref_001" }, "external_id": "bulk_pay_ref_001" }, { "amount": 2500000, "source_id": "acc_FundingCOP01", "destination": { "geo": "col", "type": "ch", "alias": "Vendor B - bulk line 2", "metadata": { "account_number": "1013669876", "beneficiary_institution": "1007", "counterparty_fullname": "Carlos Ramirez", "counterparty_id_type": "cc", "counterparty_id_number": "1023456789" } }, "metadata": { "description": "Vendor B payment", "reference": "bulk_ref_002" }, "external_id": "bulk_pay_ref_002" }]Response 201
{ "id": "bat_BulkPayDemo1",IdiUnique Cobre identifier for this resource. "input_filename": "bulk_payouts_batch_001.json",Input FilenameiOriginal filename of the uploaded bulk JSON file. "status": {StatusiLifecycle status object for the resource or movement. "state": "validating",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "",CodeiProvider or Cobre status code when the state is failed or rejected. "description": ""DescriptioniHuman-readable detail for the current status. }, "total_money_movements": 2,Total Money MovementsiNumber of Money Movement entries in the bulk file. "total_amount": "4000000",Total AmountiSum of all amounts in the bulk file, in cents. "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. "creator": "cli_demo_co_bulk01",CreatoriAPI client id that created this resource. "created_at": "2026-07-03T10:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": ""Processed AtiTimestamp when bulk processing finished (ISO 8601, UTC).}Webhook outcomes — Bulk money movement
Bulk batch finished — every line reached a terminal Money Movement state (completed, failed, canceled, or rejected). Reconcile the batch on content.id; drill into individual payouts on money_movements.status.* webhooks using external_id (each child MM has batch_id = bat_BulkPayDemo1).
Bulk statuses are validating, processing, pending_approval, completed, failed, and canceled — <b>rejected</b> is not a bulk status. The bulk completes when every Money Movement in the file reaches a terminal MM state (completed, failed, canceled, or rejected). See the <a href="https://docs.cobre.com/bulk-money-movements-1886564m0" target="_blank" rel="noopener">Bulk Money Movements</a> guide.
Initial bulk status while Cobre validates the uploaded JSON file format.
Event
bulk_money_movements.status.validatingHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BulkPayDemoCmp",IdiUnique Cobre identifier for this resource. "event_key": "bulk_money_movements.status.validating",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-03T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "bat_BulkPayDemo1",IdiUnique Cobre identifier for this resource. "input_filename": "bulk_payouts_batch_001.json",Input FilenameiOriginal filename of the uploaded bulk JSON file. "status": {StatusiLifecycle status object for the resource or movement. "state": "validating",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. }, "total_money_movements": 2,Total Money MovementsiNumber of Money Movement entries in the bulk file. "total_amount": "4000000",Total AmountiSum of all amounts in the bulk file, in cents. "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. "creator": "cli_demo_co_bulk01",CreatoriAPI client id that created this resource. "created_at": "2026-07-03T10:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-07-03T10:15:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-07-03T10:20:00Z"Processed AtiTimestamp when bulk processing finished (ISO 8601, UTC). }}File validated — each Money Movement in the batch is being created and executed.
Event
bulk_money_movements.status.processingHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BulkPayDemoCmp",IdiUnique Cobre identifier for this resource. "event_key": "bulk_money_movements.status.processing",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-03T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "bat_BulkPayDemo1",IdiUnique Cobre identifier for this resource. "input_filename": "bulk_payouts_batch_001.json",Input FilenameiOriginal filename of the uploaded bulk JSON file. "status": {StatusiLifecycle status object for the resource or movement. "state": "processing",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. }, "total_money_movements": 2,Total Money MovementsiNumber of Money Movement entries in the bulk file. "total_amount": "4000000",Total AmountiSum of all amounts in the bulk file, in cents. "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. "creator": "cli_demo_co_bulk01",CreatoriAPI client id that created this resource. "created_at": "2026-07-03T10:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-07-03T10:15:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-07-03T10:20:00Z"Processed AtiTimestamp when bulk processing finished (ISO 8601, UTC). }}Bulk submitted with checker_approval; awaiting an approver decision before processing.
Event
bulk_money_movements.status.pending_approvalHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BulkPayDemoCmp",IdiUnique Cobre identifier for this resource. "event_key": "bulk_money_movements.status.pending_approval",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-03T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "bat_BulkPayDemo1",IdiUnique Cobre identifier for this resource. "input_filename": "bulk_payouts_batch_001.json",Input FilenameiOriginal filename of the uploaded bulk JSON file. "status": {StatusiLifecycle status object for the resource or movement. "state": "pending_approval",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. }, "total_money_movements": 2,Total Money MovementsiNumber of Money Movement entries in the bulk file. "total_amount": "4000000",Total AmountiSum of all amounts in the bulk file, in cents. "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. "creator": "cli_demo_co_bulk01",CreatoriAPI client id that created this resource. "created_at": "2026-07-03T10:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-07-03T10:15:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-07-03T10:20:00Z"Processed AtiTimestamp when bulk processing finished (ISO 8601, UTC). }}Every Money Movement in the file reached a terminal state. Reconcile each line via its MM webhooks using external_id; child movements include batch_id matching the bulk id.
Event
bulk_money_movements.status.completedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BulkPayDemoCmp",IdiUnique Cobre identifier for this resource. "event_key": "bulk_money_movements.status.completed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-03T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "bat_BulkPayDemo1",IdiUnique Cobre identifier for this resource. "input_filename": "bulk_payouts_batch_001.json",Input FilenameiOriginal filename of the uploaded bulk JSON file. "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. }, "total_money_movements": 2,Total Money MovementsiNumber of Money Movement entries in the bulk file. "total_amount": "4000000",Total AmountiSum of all amounts in the bulk file, in cents. "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. "creator": "cli_demo_co_bulk01",CreatoriAPI client id that created this resource. "created_at": "2026-07-03T10:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-07-03T10:15:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-07-03T10:20:00Z"Processed AtiTimestamp when bulk processing finished (ISO 8601, UTC). }}Bulk validation failed — the file format could not be processed. Fix the JSON and re-upload.
Event
bulk_money_movements.status.failedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BulkPayDemoCmp",IdiUnique Cobre identifier for this resource. "event_key": "bulk_money_movements.status.failed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-03T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "bat_BulkPayDemo1",IdiUnique Cobre identifier for this resource. "input_filename": "bulk_payouts_batch_001.json",Input FilenameiOriginal filename of the uploaded bulk JSON file. "status": {StatusiLifecycle status object for the resource or movement. "state": "failed",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. }, "total_money_movements": 2,Total Money MovementsiNumber of Money Movement entries in the bulk file. "total_amount": "4000000",Total AmountiSum of all amounts in the bulk file, in cents. "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. "creator": "cli_demo_co_bulk01",CreatoriAPI client id that created this resource. "created_at": "2026-07-03T10:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-07-03T10:15:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-07-03T10:20:00Z"Processed AtiTimestamp when bulk processing finished (ISO 8601, UTC). }}Bulk process was canceled before completion.
Event
bulk_money_movements.status.canceledHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BulkPayDemoCmp",IdiUnique Cobre identifier for this resource. "event_key": "bulk_money_movements.status.canceled",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-03T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "bat_BulkPayDemo1",IdiUnique Cobre identifier for this resource. "input_filename": "bulk_payouts_batch_001.json",Input FilenameiOriginal filename of the uploaded bulk JSON file. "status": {StatusiLifecycle status object for the resource or movement. "state": "canceled",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. }, "total_money_movements": 2,Total Money MovementsiNumber of Money Movement entries in the bulk file. "total_amount": "4000000",Total AmountiSum of all amounts in the bulk file, in cents. "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. "creator": "cli_demo_co_bulk01",CreatoriAPI client id that created this resource. "created_at": "2026-07-03T10:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-07-03T10:15:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-07-03T10:20:00Z"Processed AtiTimestamp when bulk processing finished (ISO 8601, UTC). }}
Step 5 of 6
Bulk Payout
API step
Payout Line Completed (Webhook)
Each bulk line creates a child Money Movement. Cobre sends money_movements.status.* webhooks per line — reconcile on external_id. batch_id on the MM equals the bulk bat_… id. This demo shows line 1 (Fast Pay to the registered beneficiary).
GET
https://api.cobre.co/v1/money_movements/mm_BulkLine001
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19idWxrMDEIn0.BlkP9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "id": "mm_BulkLine001",Money Movement IDimm_… for this bulk line. "batch_id": "bat_BulkPayDemo1",Bulk batch IDiEquals bat_BulkPayDemo1 from the bulk upload response. "status": {StatusiLifecycle status object for the resource or movement. "state": "completed",Statusicompleted when the payout settled. "code": "",CodeiProvider or Cobre status code when the state is failed or rejected. "description": ""DescriptioniHuman-readable detail for the current status. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Vendor A payment",DescriptioniHuman-readable label or note. "reference": "bulk_ref_001",ReferenceiPayment reference echoed in metadata for reconciliation. "beneficiary_institution": "1007",Beneficiary InstitutioniBank or institution code for the destination account. "beneficiary_account_number": "1013661234",Beneficiary Account NumberiCobre field at "metadata.beneficiary_account_number" in this payload. "counterparty_fullname": "Maria Gomez"Counterparty FullnameiLegal or display name of the counterparty beneficiary. }, "creator": "cli_demo_co_bulk01",CreatoriAPI client id that created this resource. "external_id": "bulk_pay_ref_001",External IDiYour per-line payout reference from the bulk file. "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": "fast_pay",Rail typeifast_pay or ach for bank payouts; breb for Bre-B key lines. "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_FundingCOP01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_BeneficiaryBulk01",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 1500000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-03T10:12:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-03T10:18:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
Per-line payout settled. Match external_id to your ledger entry for this beneficiary. Cobre debited your Cobre Balance during processing (col_cb_debit) — 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_BulkLine001Cmp",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-03T10:18:00Z",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_BulkLine001",IdiUnique Cobre identifier for this resource. "batch_id": "bat_BulkPayDemo1",Batch IdiBulk batch identifier when the movement belongs to a batch. "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. "description": "Vendor A payment",DescriptioniHuman-readable label or note. "reference": "bulk_ref_001",ReferenceiPayment reference echoed in metadata for reconciliation. "beneficiary_institution": "1007",Beneficiary InstitutioniBank or institution code for the destination account. "beneficiary_account_number": "1013661234",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "counterparty_fullname": "Maria Gomez"Counterparty FullnameiLegal or display name of the counterparty beneficiary. }, "creator": "cli_demo_co_bulk01",CreatoriAPI client id that created this resource. "external_id": "bulk_pay_ref_001",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": "fast_pay",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": "acc_FundingCOP01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_BeneficiaryBulk01",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 1500000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-03T10:12:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-03T10:18:00Z"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_BulkLine001Cmp",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-03T10:18:00Z",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_BulkLine001",IdiUnique Cobre identifier for this resource. "batch_id": "bat_BulkPayDemo1",Batch IdiBulk batch identifier when the movement belongs to a batch. "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. "description": "Vendor A payment",DescriptioniHuman-readable label or note. "reference": "bulk_ref_001",ReferenceiPayment reference echoed in metadata for reconciliation. "beneficiary_institution": "1007",Beneficiary InstitutioniBank or institution code for the destination account. "beneficiary_account_number": "1013661234",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "counterparty_fullname": "Maria Gomez"Counterparty FullnameiLegal or display name of the counterparty beneficiary. }, "creator": "cli_demo_co_bulk01",CreatoriAPI client id that created this resource. "external_id": "bulk_pay_ref_001",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": "fast_pay",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": "acc_FundingCOP01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_BeneficiaryBulk01",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 1500000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-03T10:12:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-03T10:18:00Z"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_BulkLine001Cmp",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-03T10:18:00Z",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_BulkLine001",IdiUnique Cobre identifier for this resource. "batch_id": "bat_BulkPayDemo1",Batch IdiBulk batch identifier when the movement belongs to a batch. "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. "description": "Vendor A payment",DescriptioniHuman-readable label or note. "reference": "bulk_ref_001",ReferenceiPayment reference echoed in metadata for reconciliation. "beneficiary_institution": "1007",Beneficiary InstitutioniBank or institution code for the destination account. "beneficiary_account_number": "1013661234",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "counterparty_fullname": "Maria Gomez"Counterparty FullnameiLegal or display name of the counterparty beneficiary. }, "creator": "cli_demo_co_bulk01",CreatoriAPI client id that created this resource. "external_id": "bulk_pay_ref_001",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": "fast_pay",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": "acc_FundingCOP01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_BeneficiaryBulk01",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 1500000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-03T10:12:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-03T10:18:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}Payouts debit the source Cobre Balance while the movement is processing to lock funds. If the movement ends in failed, rejected, or canceled, Cobre posts a compensation credit (breb_credit or col_cb_credit). Payins credit the destination on completion only.
While the movement is in processing, Cobre debits the source Cobre Balance to lock the payout amount. Subscribe to accounts.balance.debit and money_movements.status.processing.
Event
accounts.balance.debitHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BulkLine00Lk",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-03T10:12:00Z",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_BulkLine001Lk",IdiUnique Cobre identifier for this resource. "type": "col_cb_debit",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_FundingCOP01",Account IdiCobre Balance account id affected by the event. "amount": -1500000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 6500000,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": "debit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-07-03T10:12:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-03T10:12:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_BulkLine001",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Vendor A payment",DescriptioniHuman-readable label or note. "beneficiary_account_number": "1013661234",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "tracking_key": ""Tracking KeyiBre-B tracking key for the payment. } }}On completion the locked funds are sent to the beneficiary. The processing debit remains on the ledger — no compensation credit is posted.
Event
accounts.balance.debitHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BulkLine00Lk",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-03T10:12:00Z",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_BulkLine001Lk",IdiUnique Cobre identifier for this resource. "type": "col_cb_debit",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_FundingCOP01",Account IdiCobre Balance account id affected by the event. "amount": -1500000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 6500000,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": "debit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-07-03T10:12:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-03T10:12:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_BulkLine001",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Vendor A payment",DescriptioniHuman-readable label or note. "beneficiary_account_number": "1013661234",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "tracking_key": ""Tracking KeyiBre-B tracking key for the payment. } }}If the movement reaches a terminal failed, rejected, or canceled state, Cobre credits the source Cobre Balance to release the lock (breb_credit for Bre-B, col_cb_credit for bank rails).
Event
accounts.balance.creditHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BulkLine00Cp",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-03T10:18:00Z",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_BulkLine001Cp",IdiUnique Cobre identifier for this resource. "type": "col_cb_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_FundingCOP01",Account IdiCobre Balance account id affected by the event. "amount": 1500000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 1500000,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-03T10:18:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-03T10:18:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_BulkLine001",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Vendor A payment",DescriptioniHuman-readable label or note. "tracking_key": "",Tracking KeyiBre-B tracking key for the payment. "sender_name": "",Sender NameiMetadata field "sender_name" attached to the resource. "sender_id": "",Sender IdiMetadata field "sender_id" attached to the resource. "sender_account_number": ""Sender Account NumberiMetadata field "sender_account_number" attached to the resource. } }}
Step 6 of 6
Reconciliation
Reconciliation
Reconcile the Bulk Payout Batch
Match the bulk completion webhook to your payout batch record on bat_id and total_amount. Drill into each line via money_movements.status.* webhooks (external_id + batch_id). Use GET /bulk_money_movements/{id} for batch audit and POST /reports for D+1 close.
Mapping the webhook payload from an earlier step onto Platform ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Platform ledger field | |
content.id bat_BulkPayDemo1 |
→ | payout_batch_id Bulk id — also batch_id on every child Money Movement. |
content.total_money_movements 2 |
→ | payout_line_count |
content.total_amount 4000000 |
→ | payout_batch_total_cents |
content.status.state completed |
→ | payout_batch_status Bulk completed when every line is terminal. Map completed → BATCH_SETTLED; use per-line MM webhooks for line-level status. |