Step 1 of 20
Configuration
API step
Authenticate
Every Cobre API call carries a short-lived Bearer token (valid ~20 minutes). Exchange your API user credentials for a token and attach it to every later request.
POST
https://api.cobre.co/v1/auth
Headers
| Content-Type | application/json |
Request body
{ "user_id": "cli_demo_co_01",User IDRequirediYour API user identifier issued by Cobre. Format: cli_xxxx. "secret": "sk_live_2Hg8nP4qR7"SecretRequirediThe secret from your API key. Treat it like a password.}Response 201
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ",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 20
Configuration
API step
Obtain the Master Cobre Balance
With a single-concentrator model the master Cobre Balance is created once in the Cobre web portal during onboarding. This call only retrieves it. Persist the acc_… — it is source_id on every disbursement and destination_id on every Checkout.
GET
https://api.cobre.co/v1/accounts/acc_FundingCOP01Account IDRequirediacc_… of the master Cobre Balance created in the portal.
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "id": "acc_FundingCOP01",IdiUnique Cobre identifier for this resource. "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": "Cobre Balance COP",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "cobre_tag": "@lendercop001",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": ""Primary AccountiCobre field at "metadata.primary_account" in this payload. }, "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "tags": [TagsiCobre field at "tags" in this payload. "accounting" ], "provider_id": "pr_col_cobre",Provider IdiCobre field at "provider_id" in this payload. "provider_name": "Cobre Balance Colombia",Provider NameiCobre field at "provider_name" in this payload. "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": 36937102,Obtained BalanceiCobre field at "obtained_balance" in this payload. "obtained_balance_at": "2025-11-25T14:07:45Z",Obtained Balance AtiCobre field at "obtained_balance_at" in this payload. "created_at": "2025-11-06T15:40:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2025-11-25T14:07:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 3 of 20
Configuration
API step
Subscribe to Webhook Events
Create the webhook subscription once. The Cobre web portal is enough for a single instance; use POST /subscriptions when you onboard your own clients and have admin rights on their Cobre instances. Include Money Movement status events, bulk_money_movements.status.* (batch disbursements), accounts.balance.debit (disbursements) and accounts.balance.credit (Checkout repayments).
POST
https://api.cobre.co/v1/subscriptions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "url": "https://yourplatform.co/webhooks/cobre",Notification URLRequirediYour HTTPS endpoint that receives Cobre webhook POSTs. "description": "Lender disbursement and repayment",DescriptioniA label to identify this subscription. "events": [EventsiList of webhook event types this subscription listens to. "money_movements.status.initiated", "money_movements.status.processing", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected", "bulk_money_movements.status.validating", "bulk_money_movements.status.processing", "bulk_money_movements.status.completed", "bulk_money_movements.status.failed", "accounts.balance.debit", "accounts.balance.credit" ], "event_signature_key": "WHsig_demo_44"Signature KeyRequirediA secret you provide; Cobre HMAC-signs each notification with it so you can verify authenticity.}Response 201
{ "id": "sub_PayoutDemo1",IdiUnique Cobre identifier for this resource. "url": "https://yourplatform.co/webhooks/cobre",Notification URLRequirediYour HTTPS endpoint that receives Cobre webhook POSTs. "description": "Lender disbursement and repayment",DescriptioniA label to identify this subscription. "events": [EventsiList of webhook event types this subscription listens to. "money_movements.status.initiated", "money_movements.status.processing", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected", "bulk_money_movements.status.validating", "bulk_money_movements.status.processing", "bulk_money_movements.status.completed", "bulk_money_movements.status.failed", "accounts.balance.debit", "accounts.balance.credit" ], "event_signature_key": "******_44",Signature KeyRequirediA secret you provide; Cobre HMAC-signs each notification with it so you can verify authenticity. "created_at": "2026-06-26T12:00:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 4 of 20
Bre-B Disbursement
API step
Verify the Beneficiary's Bre-B Key
Before the first Bre-B disbursement, confirm the borrower's key belongs to the declared ID with col_key_ownership_1. The check is asynchronous — do not treat processing as success.
POST
https://api.cobre.co/v1/account_verifications
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "model": "col_key_ownership_1",ModelRequiredicol_key_ownership_1 = confirm the key belongs to the declared ID. "verification_request": {Verification RequestiInput fields sent to the verification model. "key_value": "@AcmeVendor10",Bre-B keyRequirediThe beneficiary's Bre-B key. "account_holder_id_number": "9001234567"Holder IDRequirediThe beneficiary's identification number; must match the key owner. }, "external_id": "verify-vendor-10"External IDiYour reference for this verification.}Response 201
{ "id": "av_PayoutDemo1",IdiUnique Cobre identifier for this resource. "creator_id": "cli_demo_co_01",Creator IdiCobre field at "creator_id" in this payload. "model": "col_key_ownership_1",ModelRequiredicol_key_ownership_1 = confirm the key belongs to the declared ID. "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "verification_request": {Verification RequestiInput fields sent to the verification model. "key_value": "@AcmeVendor10",Bre-B keyRequirediThe beneficiary's Bre-B key. "account_holder_id_number": "9001234567"Holder IDRequirediThe beneficiary's identification number; must match the key owner. }, "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 detail for the current status. }, "external_id": "verify-vendor-10",External IDiYour reference for this verification. "created_at": "2026-06-26T12:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:10:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 5 of 20
Bre-B Disbursement
API step
Retrieve Beneficiary Key Verification Result
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.
GET
https://api.cobre.co/v1/account_verifications/av_PayoutDemo1
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "id": "av_PayoutDemo1",Verification IDRequirediThe av_… identifier returned by the create response. "creator_id": "cli_demo_co_01",Creator IdiCobre field at "creator_id" in this payload. "model": "col_key_ownership_1",ModeliVerification model identifier (region- and rail-specific). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "verification_request": {Verification RequestiInput fields sent to the verification model. "key_value": "@AcmeVendor10",Key ValueiBre-B key value (e.g. @merchant123). "account_holder_id_number": "9001234567"Account Holder Id NumberiCobre field at "verification_request.account_holder_id_number" in this payload. }, "status": {StatusiLifecycle status object for the resource or movement. "state": "completed",StatusRequirediMust be completed before creating the counterparty or Money Movement. "code": "",CodeiProvider or Cobre status code when the state is failed or rejected. "description": ""DescriptioniHuman-readable detail for the current status. }, "external_id": "verify-vendor-10",External IdiYour own reference echoed by Cobre for reconciliation. "created_at": "2026-06-26T12:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:10:00Z",Updated AtiTimestamp of the last update (ISO 8601, UTC). "verification_response": {Verification ResponseiResult returned by the verification model. "verification_result": "matched"Ownership resultRequiredimatched confirms the key ownership check; unmatched or failed blocks the payout. }}
Step 6 of 20
Bre-B Disbursement
API step
Create the Bre-B Counterparty
Register the verified Bre-B key as a breb_key counterparty. The counterparty type is what selects the Bre-B rail at payout time.
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "geo": "col",GeographyRequiredicol = Colombia. "type": "breb_key",TypeRequiredibreb_key routes a payout to a Bre-B key. "alias": "Acme Vendor - Bre-B",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "key_value": "@AcmeVendor10",Bre-B keyRequirediThe verified beneficiary key. "counterparty_email": "pagos@acmevendor.co"EmailiBeneficiary email. }}Response 201
{ "id": "cp_BrebVendor10",IdiUnique Cobre identifier for this resource. "geo": "col",GeographyRequiredicol = Colombia. "type": "breb_key",TypeRequiredibreb_key routes a payout to a Bre-B key. "alias": "Acme Vendor - Bre-B",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "key_value": "@AcmeVendor10",Bre-B keyRequirediThe verified beneficiary key. "key_type": "alphanumeric",Key TypeiCobre field at "metadata.key_type" in this payload. "counterparty_email": "pagos@acmevendor.co"EmailiBeneficiary email. }, "created_at": "2026-06-26T12:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:15:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 7 of 20
Bre-B Disbursement
API step
Send the Bre-B Payout
Disburse loan principal from the master Cobre Balance to the Bre-B counterparty. external_id is your contract + payment id. Always send the same idempotency header on retry.
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
| idempotency | payout-breb-5567-001 |
Request body
{ "amount": 3000000,Amount (cents)RequirediAmount in cents. 3000000 = $30,000.00 COP. "source_id": "acc_FundingCOP01",Source (funding balance)RequirediYour funding Cobre Balance — money leaves from here. "destination_id": "cp_BrebVendor10",Destination (counterparty)RequirediThe Bre-B counterparty from the previous step. "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Supplier payout Bre-B"DescriptionRequirediInformative description (max 40 chars). On Bre-B it is informative only. }, "external_id": "payout-breb-5567"External IDiYour payout reference, echoed in the response and webhook.}Response 201
{ "id": "mm_BrebPay5567",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": ""DescriptioniHuman-readable detail for the current status. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Supplier payout Bre-B"DescriptionRequirediInformative description (max 40 chars). On Bre-B it is informative only. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "payout-breb-5567",External IDiYour payout reference, echoed in the response and webhook. "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": "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": "acc_FundingCOP01",Source (funding balance)RequirediYour funding Cobre Balance — money leaves from here. "destination_id": "cp_BrebVendor10",Destination (counterparty)RequirediThe Bre-B counterparty from the previous step. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 3000000,Amount (cents)RequirediAmount in cents. 3000000 = $30,000.00 COP. "created_at": "2026-06-26T12:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:20:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
Fires when the Bre-B payout settles (typically seconds). Mark the payout paid by external_id. While processing, Cobre locked funds with a breb_debit — see the Transaction tab. No compensation credit is posted on completion.
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_BrebPay5567Cmp",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-06-26T12:20:09Z",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_BrebPay5567",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. "description": "Supplier payout Bre-B",DescriptioniHuman-readable label or note. "tracking_key": "55671200901",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "key_value": "@AcmeVendor10",Key ValueiBre-B key value (e.g. @merchant123). "beneficiary_account_number": "@AcmeVendor10"Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "payout-breb-5567",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": "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": "acc_FundingCOP01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_BrebVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 3000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T12:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:20:09Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}Cobre or the rail could not process the movement. Inspect status.code and status.description. The list below is filtered to this Money Movement’s direction (payin, payout, or both):
Possible status codes
| Code | Description | Applies to |
|---|---|---|
F001 | Payment processing failed please try again. | Payin and payout |
F002 | NSF - Not Sufficient Funds in the designated account. | Payin and payout |
F004 | Daily transaction amount limit has been reached. | Payin and payout |
F005 | Amount exceeds the maximum allowed transaction limit. | Payin and payout |
F098 | Could not process the money movement at this time. | Payin and payout |
F099 | Could not process the money movement at this time. | Payin and payout |
Event
money_movements.status.failedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BrebPay5567Cmp",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-06-26T12:20:09Z",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_BrebPay5567",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. "description": "Supplier payout Bre-B",DescriptioniHuman-readable label or note. "tracking_key": "55671200901",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "key_value": "@AcmeVendor10",Key ValueiBre-B key value (e.g. @merchant123). "beneficiary_account_number": "@AcmeVendor10"Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "payout-breb-5567",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": "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": "acc_FundingCOP01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_BrebVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 3000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T12:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:20:09Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}The bank or payment network rejected the transaction. Inspect status.code. The list below is filtered to this Money Movement’s direction (payin, payout, or both):
Possible status codes
| Code | Description | Applies to |
|---|---|---|
R000 | Transaction rejected. | Payin and payout |
R001 | Inactive or blocked account. | Payin and payout |
R002 | Account and identification provided do not coincide. | Payin and payout |
R004 | ID not valid. | Payout |
R005 | Account does not exist. | Payin and payout |
R006 | Invalid account number. | Payin and payout |
R009 | Exceeds maximum allowed amount. | Payin and payout |
R010 | Account not authorized to debit. | Payin and payout |
R011 | Invalid Account type. | Payout |
R015 | Account not authorized to be credited. | Payout |
R018 | Payment rejected due invalid key. | Payout |
R023 | Payment cancelled by the user. | Payin and payout |
R024 | Exceeds maximum allowed number of transactions. | Payout |
R025 | Required information missing. | Payout |
R026 | Payment rejected due to unavailable bank services. | Payin and payout |
R027 | Account exceeds the maximum allowed transaction limit. | Payin and payout |
R034 | Account closed. | Payin and payout |
R085 | Bank processing error. | Payout |
Event
money_movements.status.rejectedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_BrebPay5567Cmp",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-06-26T12:20:09Z",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_BrebPay5567",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": "R018",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "Payment rejected due invalid key."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Supplier payout Bre-B",DescriptioniHuman-readable label or note. "tracking_key": "55671200901",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "key_value": "@AcmeVendor10",Key ValueiBre-B key value (e.g. @merchant123). "beneficiary_account_number": "@AcmeVendor10"Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "payout-breb-5567",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": "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": "acc_FundingCOP01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_BrebVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 3000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T12:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:20:09Z"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_BrebPay556Lk",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-06-26T12: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": "trx_BrebPay5567Lk",IdiUnique Cobre identifier for this resource. "type": "breb_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": -3000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 8000000,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-06-26T12:20:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T12:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "beneficiary_account_number": "@AcmeVendor10",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "beneficiary_account_type": "ch",Beneficiary Account TypeiMetadata field "beneficiary_account_type" attached to the resource. "beneficiary_name": "",Beneficiary NameiMetadata field "beneficiary_name" attached to the resource. "beneficiary_id": "",Beneficiary IdiMetadata field "beneficiary_id" attached to the resource. "description": "Supplier payout Bre-B",DescriptioniHuman-readable label or note. "money_movement_id": "mm_BrebPay5567",Money Movement IdiMoney Movement that generated this balance transaction. "tracking_key": "55671200901"Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). } }}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_BrebPay556Lk",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-06-26T12: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": "trx_BrebPay5567Lk",IdiUnique Cobre identifier for this resource. "type": "breb_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": -3000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 8000000,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-06-26T12:20:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T12:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "beneficiary_account_number": "@AcmeVendor10",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "beneficiary_account_type": "ch",Beneficiary Account TypeiMetadata field "beneficiary_account_type" attached to the resource. "beneficiary_name": "",Beneficiary NameiMetadata field "beneficiary_name" attached to the resource. "beneficiary_id": "",Beneficiary IdiMetadata field "beneficiary_id" attached to the resource. "description": "Supplier payout Bre-B",DescriptioniHuman-readable label or note. "money_movement_id": "mm_BrebPay5567",Money Movement IdiMoney Movement that generated this balance transaction. "tracking_key": "55671200901"Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). } }}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_BrebPay556Cp",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.credit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-06-26T12:20:09Z",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_BrebPay5567Cp",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). "account_id": "acc_FundingCOP01",Account IdiCobre Balance account id affected by the event. "amount": 3000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 3000000,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-06-26T12:20:09Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T12:20:09Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Supplier payout Bre-B",DescriptioniHuman-readable label or note. "money_movement_id": "mm_BrebPay5567",Money Movement IdiMoney Movement that generated this balance transaction. "tracking_key": "55671200901"Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). } }}Documentation for this step
Create a Money MovementMoney Movements ApprovalBre-B PayoutsMoney Movement Statuses
Step 8 of 20
Bre-B Disbursement
Reconciliation
Reconcile the Bre-B Payout
Close the Bre-B disbursement on your loan ledger with mm_id + external_id (contract + payment). No API call — read the completion webhook.
Mapping the webhook payload from an earlier step onto Your Ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Your Ledger field | |
content.external_id payout-breb-5567 |
→ | payout_reference Your own reference — locates the payout record. |
content.id mm_BrebPay5567 |
→ | cobre_mm_id Canonical Money Movement id. |
content.status.state completed |
→ | payout_status Map completed -> PAID; rejected/failed -> FAILED. |
content.amount 3000000 |
→ | paid_amount_cents |
content.updated_at 2026-06-26T12:20:09Z |
→ | paid_at |
Step 9 of 20
Bank Disbursement
API step
Create the Bank-Account Counterparty
For Fast Pay / ACH disbursement (and the 100 COP penny test), register a cc / ch / dp counterparty. Account Verification does not cover bank accounts.
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "geo": "col",GeographyRequiredicol = Colombia. "type": "cc",Account TypeRequiredicc = Cuenta Corriente (checking), ch = Ahorros (savings), dp = Depósito. "alias": "Acme Vendor - Bank",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Acme Vendor SAS",Beneficiary NameRequirediLegal name of the account holder. "beneficiary_institution": "1007",Bank CodeRequirediBeneficiary institution code from Cobre's platform catalog (e.g. 1007 = Bancolombia). "account_number": "1013555555",Account NumberRequirediThe destination bank account number. "counterparty_id_type": "nit",ID TypeRequirediIdentification type of the beneficiary. "counterparty_id_number": "9001234567"ID NumberRequirediThe beneficiary's identification number. }}Response 201
{ "id": "cp_BankVendor10",IdiUnique Cobre identifier for this resource. "geo": "col",GeographyRequiredicol = Colombia. "type": "cc",Account TypeRequiredicc = Cuenta Corriente (checking), ch = Ahorros (savings), dp = Depósito. "alias": "Acme Vendor - Bank",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Acme Vendor SAS",Beneficiary NameRequirediLegal name of the account holder. "beneficiary_institution": "1007",Bank CodeRequirediBeneficiary institution code from Cobre's platform catalog (e.g. 1007 = Bancolombia). "account_number": "1013555555",Account NumberRequirediThe destination bank account number. "counterparty_id_type": "nit",ID TypeRequirediIdentification type of the beneficiary. "counterparty_id_number": "9001234567",ID NumberRequirediThe beneficiary's identification number. "registered_account": falseRegistered AccountiCobre field at "metadata.registered_account" in this payload. }, "created_at": "2026-06-26T12:30:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:30:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 10 of 20
Bank Disbursement
API step
Penny-test the Bank Account (100 COP)
Account Verification does not cover bank accounts. Send 100 COP (amount 10000) to the same counterparty. completed means the account exists, can be credited, and belongs to the declared ID. Persist this external_id separately from the full disbursement.
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
| idempotency | loan-1001-penny-01 |
Request body
{ "amount": 10000,Amount (cents)Requiredi10000 cents = 100.00 COP. "source_id": "acc_FundingCOP01",Source (funding balance)RequirediYour funding Cobre Balance. "destination_id": "cp_BankVendor10",Destination (counterparty)RequirediThe bank-account counterparty from the previous step. "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Account validation"DescriptionRequirediInformative description (max 40 chars). }, "external_id": "loan-1001-penny-01"External IDiYour payout reference, echoed in the response and webhook.}Response 201
{ "id": "mm_Penny1001",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": ""DescriptioniHuman-readable detail for the current status. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Account validation"DescriptionRequirediInformative description (max 40 chars). }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "loan-1001-penny-01",External IDiYour payout reference, echoed in the response and webhook. "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 (funding balance)RequirediYour funding Cobre Balance. "destination_id": "cp_BankVendor10",Destination (counterparty)RequirediThe bank-account counterparty from the previous step. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 10000,Amount (cents)Requiredi10000 cents = 100.00 COP. "created_at": "2026-06-26T12:35:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:35:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
Fires when the penny test settles. completed + no account-rejection code means you may disburse the full principal to the same counterparty.
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_Penny1001Cmp",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-06-26T12:35:21Z",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_Penny1001",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. "description": "Account validation"DescriptioniHuman-readable label or note. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "loan-1001-penny-01",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_BankVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 10000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T12:35:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:35:21Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}Cobre or the rail could not process the movement. Inspect status.code and status.description. The list below is filtered to this Money Movement’s direction (payin, payout, or both):
Possible status codes
| Code | Description | Applies to |
|---|---|---|
F001 | Payment processing failed please try again. | Payin and payout |
F002 | NSF - Not Sufficient Funds in the designated account. | Payin and payout |
F004 | Daily transaction amount limit has been reached. | Payin and payout |
F005 | Amount exceeds the maximum allowed transaction limit. | Payin and payout |
F098 | Could not process the money movement at this time. | Payin and payout |
F099 | Could not process the money movement at this time. | Payin and payout |
Event
money_movements.status.failedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_Penny1001Cmp",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-06-26T12:35:21Z",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_Penny1001",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. "description": "Account validation"DescriptioniHuman-readable label or note. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "loan-1001-penny-01",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_BankVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 10000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T12:35:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:35:21Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}The bank or payment network rejected the transaction. Inspect status.code. The list below is filtered to this Money Movement’s direction (payin, payout, or both):
Possible status codes
| Code | Description | Applies to |
|---|---|---|
R000 | Transaction rejected. | Payin and payout |
R001 | Inactive or blocked account. | Payin and payout |
R002 | Account and identification provided do not coincide. | Payin and payout |
R004 | ID not valid. | Payout |
R005 | Account does not exist. | Payin and payout |
R006 | Invalid account number. | Payin and payout |
R009 | Exceeds maximum allowed amount. | Payin and payout |
R010 | Account not authorized to debit. | Payin and payout |
R011 | Invalid Account type. | Payout |
R015 | Account not authorized to be credited. | Payout |
R018 | Payment rejected due invalid key. | Payout |
R023 | Payment cancelled by the user. | Payin and payout |
R024 | Exceeds maximum allowed number of transactions. | Payout |
R025 | Required information missing. | Payout |
R026 | Payment rejected due to unavailable bank services. | Payin and payout |
R027 | Account exceeds the maximum allowed transaction limit. | Payin and payout |
R034 | Account closed. | Payin and payout |
R085 | Bank processing error. | Payout |
Event
money_movements.status.rejectedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_Penny1001Cmp",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-06-26T12:35:21Z",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_Penny1001",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": "R018",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "Payment rejected due invalid key."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Account validation"DescriptioniHuman-readable label or note. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "loan-1001-penny-01",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_BankVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 10000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T12:35:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:35:21Z"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_Penny1001Lk",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-06-26T12:35: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_Penny1001Lk",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": -10000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 5010000,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-06-26T12:35:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T12:35:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_Penny1001",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Account validation",DescriptioniHuman-readable label or note. "beneficiary_account_number": "",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "tracking_key": ""Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). } }}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_Penny1001Lk",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-06-26T12:35: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_Penny1001Lk",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": -10000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 5010000,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-06-26T12:35:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T12:35:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_Penny1001",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Account validation",DescriptioniHuman-readable label or note. "beneficiary_account_number": "",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "tracking_key": ""Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). } }}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_Penny1001Cp",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.credit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-06-26T12:35:21Z",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_Penny1001Cp",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": 10000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 10000,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-06-26T12:35:21Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T12:35:21Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_Penny1001",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Account validation",DescriptioniHuman-readable label or note. "tracking_key": "",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "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. } }}Documentation for this step
Create a Money MovementMoney Movements ApprovalFast Pay & ACHMoney Movement Statuses
Step 11 of 20
Bank Disbursement
API step
Send the Fast Pay Payout
After a completed penny test, disburse the full principal to the same bank counterparty with a new external_id and a new idempotency value. Cobre chooses Fast Pay or ACH from the destination institution.
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
| idempotency | payout-fp-5568-001 |
Request body
{ "amount": 3000000,Amount (cents)RequirediAmount in cents. 3000000 = $30,000.00 COP. "source_id": "acc_FundingCOP01",Source (funding balance)RequirediYour funding Cobre Balance. "destination_id": "cp_BankVendor10",Destination (counterparty)RequirediThe bank-account counterparty from the previous step. "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Supplier payout FastPay"DescriptionRequirediInformative description (max 40 chars). }, "external_id": "payout-fp-5568"External IDiYour payout reference, echoed in the response and webhook.}Response 201
{ "id": "mm_FastPay5568",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": ""DescriptioniHuman-readable detail for the current status. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Supplier payout FastPay"DescriptionRequirediInformative description (max 40 chars). }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "payout-fp-5568",External IDiYour payout reference, echoed in the response and webhook. "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 (funding balance)RequirediYour funding Cobre Balance. "destination_id": "cp_BankVendor10",Destination (counterparty)RequirediThe bank-account counterparty from the previous step. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 3000000,Amount (cents)RequirediAmount in cents. 3000000 = $30,000.00 COP. "created_at": "2026-06-26T12:35:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:35:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
Fires when the Fast Pay payout settles. If the bank had not supported Fast Pay, type would be 'ach' and settlement D+0/D+1 — but your reconciliation logic is identical. Funds were locked with a col_cb_debit during processing — 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_FastPay5568Cmp",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-06-26T12:35:21Z",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_FastPay5568",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. "description": "Supplier payout FastPay"DescriptioniHuman-readable label or note. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "payout-fp-5568",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_BankVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 3000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T12:35:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:35:21Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}Cobre or the rail could not process the movement. Inspect status.code and status.description. The list below is filtered to this Money Movement’s direction (payin, payout, or both):
Possible status codes
| Code | Description | Applies to |
|---|---|---|
F001 | Payment processing failed please try again. | Payin and payout |
F002 | NSF - Not Sufficient Funds in the designated account. | Payin and payout |
F004 | Daily transaction amount limit has been reached. | Payin and payout |
F005 | Amount exceeds the maximum allowed transaction limit. | Payin and payout |
F098 | Could not process the money movement at this time. | Payin and payout |
F099 | Could not process the money movement at this time. | Payin and payout |
Event
money_movements.status.failedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_FastPay5568Cmp",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-06-26T12:35:21Z",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_FastPay5568",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. "description": "Supplier payout FastPay"DescriptioniHuman-readable label or note. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "payout-fp-5568",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_BankVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 3000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T12:35:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:35:21Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}The bank or payment network rejected the transaction. Inspect status.code. The list below is filtered to this Money Movement’s direction (payin, payout, or both):
Possible status codes
| Code | Description | Applies to |
|---|---|---|
R000 | Transaction rejected. | Payin and payout |
R001 | Inactive or blocked account. | Payin and payout |
R002 | Account and identification provided do not coincide. | Payin and payout |
R004 | ID not valid. | Payout |
R005 | Account does not exist. | Payin and payout |
R006 | Invalid account number. | Payin and payout |
R009 | Exceeds maximum allowed amount. | Payin and payout |
R010 | Account not authorized to debit. | Payin and payout |
R011 | Invalid Account type. | Payout |
R015 | Account not authorized to be credited. | Payout |
R018 | Payment rejected due invalid key. | Payout |
R023 | Payment cancelled by the user. | Payin and payout |
R024 | Exceeds maximum allowed number of transactions. | Payout |
R025 | Required information missing. | Payout |
R026 | Payment rejected due to unavailable bank services. | Payin and payout |
R027 | Account exceeds the maximum allowed transaction limit. | Payin and payout |
R034 | Account closed. | Payin and payout |
R085 | Bank processing error. | Payout |
Event
money_movements.status.rejectedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_FastPay5568Cmp",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-06-26T12:35:21Z",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_FastPay5568",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": "R018",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "Payment rejected due invalid key."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Supplier payout FastPay"DescriptioniHuman-readable label or note. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "payout-fp-5568",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_BankVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 3000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T12:35:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:35:21Z"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_FastPay556Lk",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-06-26T12:35: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_FastPay5568Lk",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": -3000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 8000000,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-06-26T12:35:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T12:35:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_FastPay5568",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Supplier payout FastPay",DescriptioniHuman-readable label or note. "beneficiary_account_number": "",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "tracking_key": ""Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). } }}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_FastPay556Lk",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-06-26T12:35: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_FastPay5568Lk",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": -3000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 8000000,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-06-26T12:35:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T12:35:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_FastPay5568",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Supplier payout FastPay",DescriptioniHuman-readable label or note. "beneficiary_account_number": "",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "tracking_key": ""Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). } }}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_FastPay556Cp",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.credit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-06-26T12:35:21Z",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_FastPay5568Cp",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": 3000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 3000000,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-06-26T12:35:21Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T12:35:21Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_FastPay5568",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Supplier payout FastPay",DescriptioniHuman-readable label or note. "tracking_key": "",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "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. } }}Documentation for this step
Create a Money MovementMoney Movements ApprovalFast Pay & ACHMoney Movement Statuses
Step 12 of 20
Bank Disbursement
Reconciliation
Reconcile the Fast Pay Payout
Close the Fast Pay / ACH disbursement on your loan ledger with mm_id + external_id. Same keys as Bre-B.
Mapping the webhook payload from an earlier step onto Your Ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Your Ledger field | |
content.external_id payout-fp-5568 |
→ | payout_reference |
content.id mm_FastPay5568 |
→ | cobre_mm_id |
content.type fast_pay |
→ | rail_used fast_pay or ach — the rail Cobre selected. |
content.status.state completed |
→ | payout_status |
content.amount 3000000 |
→ | paid_amount_cents |
Step 13 of 20
Bank Disbursement
API step
Submit Bulk Disbursement File (alternative)
When several already-validated loans must go out in one API call, POST /bulk_money_movements as multipart/form-data (field file, JSON array, max ~4.7 MB). Each line is a Create Money Movement body. Prefer destination_id of counterparties already penny-tested or AV-verified — do not put penny tests in the file. Do not mix incompatible rails in one file. Response id (bat_…) becomes batch_id on every child Money Movement. A bulk completed means every line reached a terminal MM state — not that every loan was paid.
POST
https://api.cobre.co/v1/bulk_money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Multipart upload
| file | @disbursements_batch_001.json |
File content
[ { "amount": 30000000, "source_id": "acc_FundingCOP01", "destination_id": "cp_BankVendor10", "metadata": { "description": "Loan 1002 principal" }, "external_id": "loan-1002-pay-01" }, { "amount": 25000000, "source_id": "acc_FundingCOP01", "destination_id": "cp_BankVendor11", "metadata": { "description": "Loan 1003 principal" }, "external_id": "loan-1003-pay-01" }]Response 201
{ "id": "bat_LenderBulk01",IdiUnique Cobre identifier for this resource. "input_filename": "disbursements_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": "55000000",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_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "created_at": "2026-08-15T15:00: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 finished — every line reached a terminal Money Movement state. Reconcile the batch on content.id; drill into each loan on money_movements.status.* using external_id (child batch_id = bat_LenderBulk01).
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_LenderBulk01Cmp",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-08-15T15:10: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_LenderBulk01",IdiUnique Cobre identifier for this resource. "input_filename": "disbursements_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": "55000000",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_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "created_at": "2026-08-15T15:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-08-15T15:05:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-08-15T15:10: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_LenderBulk01Cmp",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-08-15T15:10: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_LenderBulk01",IdiUnique Cobre identifier for this resource. "input_filename": "disbursements_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": "55000000",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_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "created_at": "2026-08-15T15:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-08-15T15:05:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-08-15T15:10: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_LenderBulk01Cmp",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-08-15T15:10: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_LenderBulk01",IdiUnique Cobre identifier for this resource. "input_filename": "disbursements_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": "55000000",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_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "created_at": "2026-08-15T15:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-08-15T15:05:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-08-15T15:10: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_LenderBulk01Cmp",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-08-15T15:10: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_LenderBulk01",IdiUnique Cobre identifier for this resource. "input_filename": "disbursements_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": "55000000",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_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "created_at": "2026-08-15T15:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-08-15T15:05:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-08-15T15:10: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_LenderBulk01Cmp",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-08-15T15:10: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_LenderBulk01",IdiUnique Cobre identifier for this resource. "input_filename": "disbursements_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": "55000000",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_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "created_at": "2026-08-15T15:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-08-15T15:05:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-08-15T15:10: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_LenderBulk01Cmp",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-08-15T15:10: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_LenderBulk01",IdiUnique Cobre identifier for this resource. "input_filename": "disbursements_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": "55000000",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_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "created_at": "2026-08-15T15:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-08-15T15:05:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-08-15T15:10:00Z"Processed AtiTimestamp when bulk processing finished (ISO 8601, UTC). }}
Step 14 of 20
Bank Disbursement
API step
Obtain the Bulk Disbursement
GET /bulk_money_movements/{id} returns the batch object (Bulk Money Movement | Obtain Response). It does not list child Money Movements — those arrive on money_movements.status.* with batch_id = this bat_….
GET
https://api.cobre.co/v1/bulk_money_movements/bat_LenderBulk01Bulk idRequiredibat_… returned by POST /bulk_money_movements.
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "id": "bat_LenderBulk01",IdiUnique Cobre identifier for this resource. "input_filename": "disbursements_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 detail for the current status. }, "total_money_movements": 2,Total Money MovementsiNumber of Money Movement entries in the bulk file. "total_amount": "55000000",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_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "created_at": "2026-08-15T15:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "executed_at": "2026-08-15T15:05:00Z",Executed AtiTimestamp when bulk processing started executing movements (ISO 8601, UTC). "processed_at": "2026-08-15T15:10:00Z"Processed AtiTimestamp when bulk processing finished (ISO 8601, UTC).}
Step 15 of 20
Bank Disbursement
API step
Bulk Line Completed (Webhook)
Each bulk line creates a child Money Movement. POST /bulk_money_movements does not return it. Cobre sends money_movements.status.* per line — reconcile on external_id (contract + payment). batch_id equals the bulk bat_…, not a Checkout chk_….
GET
https://api.cobre.co/v1/money_movements/mm_BulkLine001Money Movement IDRequiredimm_… for this bulk line.
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "id": "mm_BulkLine001",IdiUnique Cobre identifier for this resource. "batch_id": "bat_LenderBulk01",Bulk batch IDRequirediEquals bat_LenderBulk01 from the bulk upload response. "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 detail for the current status. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Loan 1002 principal"DescriptioniHuman-readable label or note. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "loan-1002-pay-01",External IDRequirediYour per-line reference — contract + payment. "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_BankVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 30000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-08-15T15:06:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-08-15T15:09:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
Per-line disbursement settled. Match external_id to the loan. batch_id ties the line back to the bulk file. Cobre debited the master Cobre 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_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-08-15T15:09: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_LenderBulk01",Batch IdiCheckout id (chk_…) when the Money Movement was created from a Checkout; otherwise the bulk batch id (bat_…). "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": "Loan 1002 principal"DescriptioniHuman-readable label or note. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "loan-1002-pay-01",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_BankVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 30000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-08-15T15:06:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-08-15T15:09: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. The list below is filtered to this Money Movement’s direction (payin, payout, or both):
Possible status codes
| Code | Description | Applies to |
|---|---|---|
F001 | Payment processing failed please try again. | Payin and payout |
F002 | NSF - Not Sufficient Funds in the designated account. | Payin and payout |
F004 | Daily transaction amount limit has been reached. | Payin and payout |
F005 | Amount exceeds the maximum allowed transaction limit. | Payin and payout |
F098 | Could not process the money movement at this time. | Payin and payout |
F099 | Could not process the money movement at this time. | Payin and payout |
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-08-15T15:09: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_LenderBulk01",Batch IdiCheckout id (chk_…) when the Money Movement was created from a Checkout; otherwise the bulk batch id (bat_…). "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": "Loan 1002 principal"DescriptioniHuman-readable label or note. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "loan-1002-pay-01",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_BankVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 30000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-08-15T15:06:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-08-15T15:09:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}The bank or payment network rejected the transaction. Inspect status.code. The list below is filtered to this Money Movement’s direction (payin, payout, or both):
Possible status codes
| Code | Description | Applies to |
|---|---|---|
R000 | Transaction rejected. | Payin and payout |
R001 | Inactive or blocked account. | Payin and payout |
R002 | Account and identification provided do not coincide. | Payin and payout |
R004 | ID not valid. | Payout |
R005 | Account does not exist. | Payin and payout |
R006 | Invalid account number. | Payin and payout |
R009 | Exceeds maximum allowed amount. | Payin and payout |
R010 | Account not authorized to debit. | Payin and payout |
R011 | Invalid Account type. | Payout |
R015 | Account not authorized to be credited. | Payout |
R018 | Payment rejected due invalid key. | Payout |
R023 | Payment cancelled by the user. | Payin and payout |
R024 | Exceeds maximum allowed number of transactions. | Payout |
R025 | Required information missing. | Payout |
R026 | Payment rejected due to unavailable bank services. | Payin and payout |
R027 | Account exceeds the maximum allowed transaction limit. | Payin and payout |
R034 | Account closed. | Payin and payout |
R085 | Bank processing error. | Payout |
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-08-15T15:09: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_LenderBulk01",Batch IdiCheckout id (chk_…) when the Money Movement was created from a Checkout; otherwise the bulk batch id (bat_…). "status": {StatusiLifecycle status object for the resource or movement. "state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "R018",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "Payment rejected due invalid key."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Loan 1002 principal"DescriptioniHuman-readable label or note. }, "creator": "cli_demo_co_01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "external_id": "loan-1002-pay-01",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_BankVendor10",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 30000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-08-15T15:06:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-08-15T15:09: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-08-15T15:06: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": -30000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 35000000,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-08-15T15:06:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-08-15T15:06: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": "Loan 1002 principal",DescriptioniHuman-readable label or note. "beneficiary_account_number": "",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "tracking_key": ""Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). } }}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-08-15T15:06: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": -30000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 35000000,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-08-15T15:06:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-08-15T15:06: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": "Loan 1002 principal",DescriptioniHuman-readable label or note. "beneficiary_account_number": "",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "tracking_key": ""Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). } }}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-08-15T15:09: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": 30000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 30000000,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-08-15T15:09:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-08-15T15:09: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": "Loan 1002 principal",DescriptioniHuman-readable label or note. "tracking_key": "",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "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 16 of 20
Bank Disbursement
Reconciliation
Reconcile the Bulk Disbursement
Match the bulk completion webhook to your disbursement batch on bat_id. Drill into each loan via money_movements.status.* (external_id = contract + payment, batch_id = bat_…). Bulk completed is not every loan paid.
Mapping the webhook payload from an earlier step onto Loan ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Loan ledger field | |
content.id bat_LenderBulk01 |
→ | disbursement_batch_id Bulk id — also batch_id on every child Money Movement (not a Checkout chk_…). |
content.total_money_movements 2 |
→ | disbursement_line_count |
content.total_amount 55000000 |
→ | disbursement_batch_total_cents |
content.status.state completed |
→ | disbursement_batch_status Bulk completed when every line is terminal. Use per-line MM webhooks for loan-level status. |
Step 17 of 20
Checkout Repayment
API step
Register the Payer (r2p Counterparty)
Pre-register the payer as an r2p counterparty and pass source_id when creating the Checkout. Email is used for PSE authentication; phone for Nequi push. Cobre can collect payer data on the hosted page if you skip this step — this flow shows explicit counterparty creation for faster checkout and pre-filled payer details.
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "geo": "col",GeographyRequiredicol = Colombia. "type": "r2p",TypeRequiredir2p supports all Checkout rails (PSE, Bancolombia, Nequi, Bre-B). "alias": "Checkout payer - payin_ref_002",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Juliana Restrepo",Full nameRequirediPayer's full legal name. "counterparty_email": "payer@example.co",EmailRequirediRequired for PSE bank authentication on Checkout. "counterparty_id_type": "cc",ID typeRequirediColombian identification type. "counterparty_id_number": "5334623427",ID numberRequirediPayer identification number. "counterparty_phone": "+573123927834"PhoneRequirediUsed for Nequi push notifications on Checkout. }}Response 201
{ "id": "cp_PayerCheckout01",IdiUnique Cobre identifier for this resource. "geo": "col",GeographyRequiredicol = Colombia. "type": "r2p",TypeRequiredir2p supports all Checkout rails (PSE, Bancolombia, Nequi, Bre-B). "alias": "Checkout payer - payin_ref_002",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_email": "payer@example.co",EmailRequirediRequired for PSE bank authentication on Checkout. "counterparty_fullname": "Juliana Restrepo",Full nameRequirediPayer's full legal name. "counterparty_id_number": "5334623427",ID numberRequirediPayer identification number. "counterparty_id_type": "cc",ID typeRequirediColombian identification type. "counterparty_phone": "+573123927834"PhoneRequirediUsed for Nequi push notifications on Checkout. }, "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 18 of 20
Checkout Repayment
API step
Create Checkout (All Rails)
Create a fixed-amount Checkout for an installment. source_id is the r2p counterparty, destination_id is the master Cobre Balance. Offer pse, bancolombia, nequi, and breb. Use a short valid_until for in-app redirect, a longer one for email or WhatsApp.
POST
https://api.cobre.co/v1/checkouts
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "alias": "Order payin_ref_002",AliasiDisplay name that helps identify it and clarify its purpose. "amount": 500000,Amount (cents)Requiredi500000 cents = COP 5,000.00. Use -1 for open amount. "external_id": "payin_ref_002",External IDiYour order reference — copied to the Money Movement for reconciliation. "source_id": "cp_PayerCheckout01",Payer counterpartyRequiredicp_… from the registered r2p payer. "destination_id": "acc_FundingCOP01",Destination balanceRequirediYour COP Cobre Balance that receives the payin. "checkout_rails": [Checkout RailsiCobre field at "checkout_rails" in this payload. "pse", "bancolombia", "nequi", "breb" ], "checkout_header": "My Platform",Checkout headerRequirediTitle shown on the hosted Checkout page. "checkout_item": "Order #002",Item descriptionRequirediProduct or service label on Checkout (max 40 chars). "description_to_payee": "Checkout payment",Balance descriptioniDescription on the credit transaction in your Cobre Balance. "valid_until": "2050-12-31T23:59:00Z",Valid untilRequirediISO 8601 expiry. Use -1 for no expiration. "money_movement_intent_limit": 1,Payment limitRequiredi1 = single-use link. Use -1 for unlimited reusable link. "redirect_url": "https://yourplatform.co/checkout/return"Return URLRequirediWhere Cobre redirects the payer after the confirmation screen.}Response 201
{ "id": "chk_CheckoutDemo1",IdiUnique Cobre identifier for this resource. "alias": "Order payin_ref_002",AliasiDisplay name that helps identify it and clarify its purpose. "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "amount": 500000,Amount (cents)Requiredi500000 cents = COP 5,000.00. Use -1 for open amount. "external_id": "payin_ref_002",External IDiYour order reference — copied to the Money Movement for reconciliation. "source_id": "cp_PayerCheckout01",Payer counterpartyRequiredicp_… from the registered r2p payer. "destination_id": "acc_FundingCOP01",Destination balanceRequirediYour COP Cobre Balance that receives the payin. "checkout_rails": [Checkout RailsiCobre field at "checkout_rails" in this payload. "pse", "bancolombia", "nequi", "breb" ], "checkout_header": "My Platform",Checkout headerRequirediTitle shown on the hosted Checkout page. "checkout_item": "Order #002",Item descriptionRequirediProduct or service label on Checkout (max 40 chars). "valid_until": "2050-12-31T23:59:00Z",Valid untilRequirediISO 8601 expiry. Use -1 for no expiration. "money_movement_intent_limit": 1,Payment limitRequiredi1 = single-use link. Use -1 for unlimited reusable link. "money_movement_created": 0,Money Movement CreatediCobre field at "money_movement_created" in this payload. "redirect_url": "https://yourplatform.co/checkout/return",Return URLRequirediWhere Cobre redirects the payer after the confirmation screen. "checkout_url": "https://links.cobre.co/ChkDemo01",Checkout UrliCobre field at "checkout_url" in this payload. "description_to_payee": "Checkout payment",Balance descriptioniDescription on the credit transaction in your Cobre Balance. "active": true,ActiveiCobre field at "active" in this payload. "created_at": "2026-07-03T10:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-03T10:10:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 19 of 20
Checkout Repayment
API step
Payment Completed (Webhook)
POST /checkouts does not return a Money Movement. When the payer finishes on the hosted page, Cobre creates an R2P MM and sends money_movements.status.*. Poll GET /money_movements/{mm_id} if needed (nested defaults to false — source and destination are null). batch_id equals the Checkout chk_…; creator is the r2p source counterparty. This demo is a completed PSE payment; other rails produce r2p_nequi, r2p_bancolombia, or r2p_breb.
GET
https://api.cobre.co/v1/money_movements/mm_ChkPayin001
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb18wMSJ9.Dm3kP9xR2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "id": "mm_ChkPayin001",Money Movement IDRequiredimm_… created by Checkout when payment completes. "batch_id": "chk_CheckoutDemo1",Checkout IDRequirediEquals the Checkout chk_… that initiated this payment. "external_id": "payin_ref_002",External IDRequirediYour order reference from the Checkout request. "creator": "cp_PayerCheckout01",CreatorRequirediActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "type": "r2p_pse",Rail typeRequirediMM type reflects the rail the payer chose (e.g. r2p_pse). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "status": {StatusiLifecycle status object for the resource or movement. "state": "completed",StatusRequiredicompleted when funds have settled to your Cobre Balance. "code": "",CodeiProvider or Cobre status code when the state is failed or rejected. "description": ""DescriptioniHuman-readable detail for the current status. }, "source_id": "cp_PayerCheckout01",Source counterpartyRequirediCobre id of the source account or counterparty. "source": null,SourceiCobre field at "source" in this payload. "destination_id": "acc_FundingCOP01",Destination IdiCobre id of the destination account or counterparty. "destination": null,DestinationiInline Create Counterparty body when destination_id is not used (supported in bulk uploads). "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 500000,AmountiAmount in cents — the last two digits are decimals. "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "pse",R2P railRequirediRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "tracking_key": "558741001",Tracking keyRequirediNetwork tracking key for the payment (PSE ticket or Bre-B key). "payment_link": "https://registro.pse.com.co/PSENF/index.html?enc=_chkdemo001",Payment linkRequirediRail-hosted URL the payer used to complete the payment (e.g. PSE). "description_to_payer": "Order #002",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "description_to_payee": "Checkout payment",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "redirect_url": "https://links.cobre.co/ChkDemo01",Checkout URLRequirediOn a Checkout-created Money Movement this is the hosted checkout_url (links.cobre.co), not the merchant return URL from POST /checkouts. "financial_institution_code": "1002",Bank codeRequirediBank code the payer selected (PSE). See Colombian bank codes. "ticket_id": "178648058366091001"Ticket IDRequirediTicket id the payment network assigned to this transaction. }, "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. "created_at": "2026-07-03T10:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-03T10:20:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
Cobre delivers this when the Checkout payment reaches completed. Use external_id to mark your order paid and batch_id to tie back to the Checkout link. creator and source_id are the r2p counterparty. Cobre credits your Cobre Balance (r2p_credit) — 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_ChkPayin001Cmp",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: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": "mm_ChkPayin001",IdiUnique Cobre identifier for this resource. "batch_id": "chk_CheckoutDemo1",Batch IdiCheckout id (chk_…) when the Money Movement was created from a Checkout; otherwise the bulk batch id (bat_…). "external_id": "payin_ref_002",External IdiYour own reference echoed by Cobre for reconciliation. "creator": "cp_PayerCheckout01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "type": "r2p_pse",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). "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. }, "source_id": "cp_PayerCheckout01",Source IdiCobre id of the source account or counterparty. "source": null,SourceiCobre field at "content.source" in this payload. "destination_id": "acc_FundingCOP01",Destination IdiCobre id of the destination account or counterparty. "destination": null,DestinationiInline Create Counterparty body when destination_id is not used (supported in bulk uploads). "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 500000,AmountiAmount in cents — the last two digits are decimals. "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "pse",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "tracking_key": "558741001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "payment_link": "https://registro.pse.com.co/PSENF/index.html?enc=_chkdemo001",Payment LinkiRail-hosted URL the payer used to complete the payment (e.g. PSE). "description_to_payer": "Order #002",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "description_to_payee": "Checkout payment",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "redirect_url": "https://links.cobre.co/ChkDemo01",Redirect UrliOn a Checkout-created Money Movement this is the hosted checkout_url (links.cobre.co), not the merchant return URL from POST /checkouts. "financial_institution_code": "1002",Financial Institution CodeiBank code the payer selected (PSE). See Colombian bank codes. "ticket_id": "178648058366091001"Ticket IdiTicket id the payment network assigned to this transaction. }, "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. "created_at": "2026-07-03T10:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-03T10:20: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. The list below is filtered to this Money Movement’s direction (payin, payout, or both):
Possible status codes
| Code | Description | Applies to |
|---|---|---|
F001 | Payment processing failed please try again. | Payin and payout |
F002 | NSF - Not Sufficient Funds in the designated account. | Payin and payout |
F003 | R2P Payment link expired. | Payin |
F004 | Daily transaction amount limit has been reached. | Payin and payout |
F005 | Amount exceeds the maximum allowed transaction limit. | Payin and payout |
F098 | Could not process the money movement at this time. | Payin and payout |
F099 | Could not process the money movement at this time. | Payin and payout |
Event
money_movements.status.failedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_ChkPayin001Cmp",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: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": "mm_ChkPayin001",IdiUnique Cobre identifier for this resource. "batch_id": "chk_CheckoutDemo1",Batch IdiCheckout id (chk_…) when the Money Movement was created from a Checkout; otherwise the bulk batch id (bat_…). "external_id": "payin_ref_002",External IdiYour own reference echoed by Cobre for reconciliation. "creator": "cp_PayerCheckout01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "type": "r2p_pse",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). "status": {StatusiLifecycle status object for the resource or movement. "state": "failed",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "F003",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "R2P Payment link expired."DescriptioniHuman-readable label or note. }, "source_id": "cp_PayerCheckout01",Source IdiCobre id of the source account or counterparty. "source": null,SourceiCobre field at "content.source" in this payload. "destination_id": "acc_FundingCOP01",Destination IdiCobre id of the destination account or counterparty. "destination": null,DestinationiInline Create Counterparty body when destination_id is not used (supported in bulk uploads). "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 500000,AmountiAmount in cents — the last two digits are decimals. "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "pse",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "tracking_key": "558741001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "payment_link": "https://registro.pse.com.co/PSENF/index.html?enc=_chkdemo001",Payment LinkiRail-hosted URL the payer used to complete the payment (e.g. PSE). "description_to_payer": "Order #002",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "description_to_payee": "Checkout payment",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "redirect_url": "https://links.cobre.co/ChkDemo01",Redirect UrliOn a Checkout-created Money Movement this is the hosted checkout_url (links.cobre.co), not the merchant return URL from POST /checkouts. "financial_institution_code": "1002",Financial Institution CodeiBank code the payer selected (PSE). See Colombian bank codes. "ticket_id": "178648058366091001"Ticket IdiTicket id the payment network assigned to this transaction. }, "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. "created_at": "2026-07-03T10:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-03T10:20:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}The bank or payment network rejected the transaction. Inspect status.code. The list below is filtered to this Money Movement’s direction (payin, payout, or both):
Possible status codes
| Code | Description | Applies to |
|---|---|---|
R000 | Transaction rejected. | Payin and payout |
R001 | Inactive or blocked account. | Payin and payout |
R002 | Account and identification provided do not coincide. | Payin and payout |
R005 | Account does not exist. | Payin and payout |
R006 | Invalid account number. | Payin and payout |
R009 | Exceeds maximum allowed amount. | Payin and payout |
R010 | Account not authorized to debit. | Payin and payout |
R012 | The user has abandoned the transaction. | Payin |
R016 | Payment rejected due to timeout. | Payin |
R017 | Payment rejected due to expired money movement. | Payin |
R019 | Payment rejected due to incorrect amount. | Payin |
R020 | Payment rejected due to user authentication failure. | Payin |
R021 | Insufficient funds in payer account. | Payin |
R023 | Payment cancelled by the user. | Payin and payout |
R026 | Payment rejected due to unavailable bank services. | Payin and payout |
R027 | Account exceeds the maximum allowed transaction limit. | Payin and payout |
R034 | Account closed. | Payin and payout |
R081 | The counterparty registration has expired. | Payin |
R082 | The counterparty registration has been canceled. | Payin |
R084 | The counterparty registration has been rejected. | Payin |
Event
money_movements.status.rejectedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_ChkPayin001Cmp",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: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": "mm_ChkPayin001",IdiUnique Cobre identifier for this resource. "batch_id": "chk_CheckoutDemo1",Batch IdiCheckout id (chk_…) when the Money Movement was created from a Checkout; otherwise the bulk batch id (bat_…). "external_id": "payin_ref_002",External IdiYour own reference echoed by Cobre for reconciliation. "creator": "cp_PayerCheckout01",CreatoriActor that created the resource. On a Checkout-created Money Movement this is the r2p source counterparty (cp_…), not the API user. "type": "r2p_pse",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). "status": {StatusiLifecycle status object for the resource or movement. "state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "R016",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "Payment rejected due to timeout."DescriptioniHuman-readable label or note. }, "source_id": "cp_PayerCheckout01",Source IdiCobre id of the source account or counterparty. "source": null,SourceiCobre field at "content.source" in this payload. "destination_id": "acc_FundingCOP01",Destination IdiCobre id of the destination account or counterparty. "destination": null,DestinationiInline Create Counterparty body when destination_id is not used (supported in bulk uploads). "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 500000,AmountiAmount in cents — the last two digits are decimals. "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "pse",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "tracking_key": "558741001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "payment_link": "https://registro.pse.com.co/PSENF/index.html?enc=_chkdemo001",Payment LinkiRail-hosted URL the payer used to complete the payment (e.g. PSE). "description_to_payer": "Order #002",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "description_to_payee": "Checkout payment",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "redirect_url": "https://links.cobre.co/ChkDemo01",Redirect UrliOn a Checkout-created Money Movement this is the hosted checkout_url (links.cobre.co), not the merchant return URL from POST /checkouts. "financial_institution_code": "1002",Financial Institution CodeiBank code the payer selected (PSE). See Colombian bank codes. "ticket_id": "178648058366091001"Ticket IdiTicket id the payment network assigned to this transaction. }, "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. "created_at": "2026-07-03T10:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-03T10:20:00Z"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_ChkPayin00Cr",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: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": "trx_ChkPayin001Cr",IdiUnique Cobre identifier for this resource. "type": "r2p_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": 500000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 500000,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:20:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-03T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "sender_bank_code": "1002",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "money_movement_id": "mm_ChkPayin001",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Checkout payment",DescriptioniHuman-readable label or note. "sender_name": "",Sender NameiMetadata field "sender_name" attached to the resource. "r2p_method": "pse",R2p MethodiR2P channel for r2p_credit transactions (e.g. pse). "tracking_key": "558741001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "sender_id": ""Sender IdiMetadata field "sender_id" attached to the resource. } }}
Step 20 of 20
Reconciliation
Reconciliation
Reconcile the Checkout Payin
Match the Checkout repayment on external_id (contract + installment) and batch_id (chk_…). Cross-check the credit with GET /accounts/{acct_id}/transactions or daily_balance_history. Export D+1 with POST /reports.
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.external_id payin_ref_002 |
→ | order_reference Primary join key — your order or payin id. |
content.id mm_ChkPayin001 |
→ | cobre_mm_id |
content.batch_id chk_CheckoutDemo1 |
→ | checkout_id Checkout id — correlates the MM to the hosted link that initiated payment. |
content.amount 500000 |
→ | received_amount_cents |
content.status.state completed |
→ | payin_status Map completed → PAID; failed/rejected → review or re-issue Checkout. |
content.type r2p_pse |
→ | payin_rail Rail the payer chose on Checkout (r2p_pse, r2p_nequi, r2p_bancolombia, r2p_breb, …). |