Step 1 of 13
Configuration
API step
Authenticate
Every Cobre API call carries a short-lived Bearer token (valid ~20 minutes). Your backend exchanges its API user credentials for a token, then attaches it to every later request.
POST
https://api.cobre.co/v1/auth
Headers
| Content-Type | application/json |
Request body
{ "user_id": "cli_lender_co_01",User IDRequirediYour API user identifier, issued by Cobre when the API key was created. Format: cli_xxxx. "secret": "sk_live_4Tg9aQ2pL7"SecretRequirediThe secret obtained when creating the API key. Treat it like a password — never log it or expose it client-side.}Response 201
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbGVuZGVyX2NvXzAxIn0.s7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ",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 13
Configuration
API step
Subscribe to Webhook Events
Tell Cobre where to send real-time notifications and which events you care about. For lending you want the money-movement lifecycle so your system learns when a disbursement or repayment settles — no polling required.
POST
https://api.cobre.co/v1/subscriptions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbGVuZGVyX2NvXzAxIn0.s7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "url": "https://creditoagil.co/webhooks/cobre",Notification URLRequirediThe HTTPS endpoint on your side that will receive webhook POSTs from Cobre. "description": "Lending lifecycle",DescriptioniA label to identify this subscription later. "events": [EventsiList of webhook event types this subscription listens to. "money_movements.status.initiated", "money_movements.status.pending_approval", "money_movements.status.processing", "money_movements.status.completed", "money_movements.status.canceled", "money_movements.status.rejected", "money_movements.status.failed", "accounts.balance.debit", "accounts.balance.credit" ], "event_signature_key": "WH5gT2kP9xZ"Signature KeyRequirediA secret you provide; Cobre uses it to HMAC-sign each notification so you can verify it genuinely came from Cobre.}Response 201
{ "id": "sub_zod5IW",IdiUnique Cobre identifier for this resource. "url": "https://creditoagil.co/webhooks/cobre",Notification URLRequirediThe HTTPS endpoint on your side that will receive webhook POSTs from Cobre. "description": "Lending lifecycle",DescriptioniA label to identify this subscription later. "events": [EventsiList of webhook event types this subscription listens to. "money_movements.status.initiated", "money_movements.status.pending_approval", "money_movements.status.processing", "money_movements.status.completed", "money_movements.status.canceled", "money_movements.status.rejected", "money_movements.status.failed", "accounts.balance.debit", "accounts.balance.credit" ], "event_signature_key": "******9xZ",Signature KeyRequirediA secret you provide; Cobre uses it to HMAC-sign each notification so you can verify it genuinely came from Cobre. "created_at": "2026-06-20T13:40:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 3 of 13
Loan Disbursement
API step
Verify the Borrower's Bre-B Account
In the Crédito Ágil app, the borrower enters the Bre-B key where they want to receive the loan. Behind the scenes this runs the col_key_ownership_1 verification so funds only ever go to a key the borrower actually owns.
POST
https://api.cobre.co/v1/account_verifications
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbGVuZGVyX2NvXzAxIn0.s7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "model": "col_key_ownership_1",ModeliVerification model identifier (region- and rail-specific). "verification_request": {Verification RequestiInput fields sent to the verification model. "key_value": "@JAR1234",Your Bre-B keyRequirediThe Bre-B key (alias) you receive money with — for example an @-handle, phone, or document-based key. "account_holder_id_number": "5334623427"Your ID numberRequirediYour identification number — it must match the registered owner of the Bre-B key. }, "external_id": "loan-CO-88231-verify"External IdiYour own reference echoed by Cobre for reconciliation.}Response 201
{ "id": "av_134trewqe2",IdiUnique Cobre identifier for this resource. "creator_id": "cli_lender_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": "@JAR1234",Your Bre-B keyRequirediThe Bre-B key (alias) you receive money with — for example an @-handle, phone, or document-based key. "account_holder_id_number": "5334623427"Your ID numberRequirediYour identification number — it must match the registered owner of the Bre-B key. }, "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": "loan-CO-88231-verify",External IdiYour own reference echoed by Cobre for reconciliation. "created_at": "2026-06-20T13:45:07Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-20T13:45:07Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 4 of 13
Loan Disbursement
API step
Retrieve Borrower 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_134trewqe2
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbGVuZGVyX2NvXzAxIn0.s7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
Response 200
{ "id": "av_134trewqe2",Verification IDRequirediThe av_… identifier returned by the create response. "creator_id": "cli_lender_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": "@JAR1234",Key ValueiBre-B key value (e.g. @merchant123). "account_holder_id_number": "5334623427"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": "loan-CO-88231-verify",External IdiYour own reference echoed by Cobre for reconciliation. "created_at": "2026-06-20T13:45:07Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-20T13:45:07Z",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 5 of 13
Loan Disbursement
API step
Register the Borrower as a Counterparty
A counterparty is a reusable record of who you pay. Operations registers the borrower's verified Bre-B key once; the returned ID is what you reference on every future payout to them.
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbGVuZGVyX2NvXzAxIn0.s7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "geo": "col",GeographyRequirediCountry domain of the counterparty. col = Colombia. "type": "breb_key",TypeRequirediThe payment rail. breb_key routes funds to a Bre-B key. "alias": "Borrower - loan CO-88231",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "key_value": "@JAR1234",Bre-B KeyRequirediThe borrower's Bre-B key — the same one just verified. "counterparty_phone": "+18800347411",PhoneiBorrower phone, including country code. "counterparty_email": "borrower@example.co"EmailiBorrower email address. }}Response 201
{ "id": "cp_AWgvElV9js",IdiUnique Cobre identifier for this resource. "geo": "col",GeographyRequirediCountry domain of the counterparty. col = Colombia. "type": "breb_key",TypeRequirediThe payment rail. breb_key routes funds to a Bre-B key. "alias": "Borrower - loan CO-88231",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "key_value": "@JAR1234",Bre-B KeyRequirediThe borrower's Bre-B key — the same one just verified. "key_type": "alphanumeric",Key TypeiCobre field at "metadata.key_type" in this payload. "counterparty_phone": "+18800347411",PhoneiBorrower phone, including country code. "counterparty_email": "borrower@example.co"EmailiBorrower email address. }, "created_at": "2026-06-20T13:50:22Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-20T13:50:22Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 6 of 13
Loan Disbursement
API step
Disburse the Loan (Maker)
The maker creates the disbursement with checker_approval set to true in the request body. Cobre sets the Money Movement to pending_approval, locks funds on the source Cobre Balance with a debit transaction, and returns mm_approval_id linking to the approval object. Your maker–checker rules run outside Cobre — once the checker decides, send approved or denied via the Money Movement Approvals API (next steps).
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbGVuZGVyX2NvXzAxIn0.s7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
| idempotency | loan-CO-88231-disb-001 |
Request body
{ "source_id": "acc_LenderCOP01",Source AccountRequirediYour Cobre COP funding account that money leaves from. "destination_id": "cp_AWgvElV9js",Destination (Counterparty)RequirediThe counterparty ID from the previous step — the borrower's Bre-B key. "amount": 50000000,Amount (cents)RequirediAmount in cents — the last two digits are decimals. 50000000 = $500,000.00 COP. "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Loan disbursement CO-88231"DescriptioniOptional description attached to the money movement for your own tracking. }, "external_id": "loan-CO-88231-disb",External IDiYour loan reference, echoed back in responses and webhooks for reconciliation. "checker_approval": trueChecker approvalRequirediWhen true, Cobre pauses at pending_approval and locks funds on the source account until you submit an approval or denial decision. The response includes mm_approval_id — store it for the decision call.}Response 201
{ "id": "mm_xK9mP3q7TZ",IdiUnique Cobre identifier for this resource. "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": "Awaiting checker approval before processing."DescriptioniHuman-readable detail for the current status. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Loan disbursement CO-88231"DescriptioniOptional description attached to the money movement for your own tracking. }, "creator": "cli_lender_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-CO-88231-disb",External IDiYour loan reference, echoed back in responses and webhooks for reconciliation. "checker_approval": true,Checker approvalRequirediWhen true, Cobre pauses at pending_approval and locks funds on the source account until you submit an approval or denial decision. The response includes mm_approval_id — store it for the decision call. "mm_approval_id": "mma_dnQOheIG9J",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_LenderCOP01",Source AccountRequirediYour Cobre COP funding account that money leaves from. "destination_id": "cp_AWgvElV9js",Destination (Counterparty)RequirediThe counterparty ID from the previous step — the borrower's Bre-B key. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 50000000,Amount (cents)RequirediAmount in cents — the last two digits are decimals. 50000000 = $500,000.00 COP. "created_at": "2026-06-20T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-20T14:00:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
After your checker approves via the Approvals API and the disbursement clears the rail, Cobre POSTs this to your subscription URL. Mark the loan as funded here. Funds were locked at pending_approval and again 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_LenderDisbCmp",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-20T14:32:11Z",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_xK9mP3q7TZ",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. "tracking_key": "88231432001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "description": "Loan disbursement CO-88231"DescriptioniHuman-readable label or note. }, "creator": "cli_lender_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-CO-88231-disb",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": true,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": "mma_dnQOheIG9J",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_LenderCOP01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_AWgvElV9js",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 50000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-20T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-20T14:32:11Z"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_LenderDisbCmp",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-20T14:32:11Z",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_xK9mP3q7TZ",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. "tracking_key": "88231432001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "description": "Loan disbursement CO-88231"DescriptioniHuman-readable label or note. }, "creator": "cli_lender_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-CO-88231-disb",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": true,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": "mma_dnQOheIG9J",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_LenderCOP01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_AWgvElV9js",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 50000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-20T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-20T14:32:11Z"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_LenderDisbCmp",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-20T14:32:11Z",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_xK9mP3q7TZ",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. "tracking_key": "88231432001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "description": "Loan disbursement CO-88231"DescriptioniHuman-readable label or note. }, "creator": "cli_lender_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-CO-88231-disb",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": true,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": "mma_dnQOheIG9J",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_LenderCOP01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_AWgvElV9js",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 50000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-20T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-20T14:32:11Z"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_xK9mP3q7TZLk",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-20T14:00: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_xK9mP3q7TZLk",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_LenderCOP01",Account IdiCobre Balance account id affected by the event. "amount": -50000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 55000000,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-20T14:00:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-20T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "beneficiary_account_number": "",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": "Loan disbursement CO-88231",DescriptioniHuman-readable label or note. "money_movement_id": "mm_xK9mP3q7TZ",Money Movement IdiMoney Movement that generated this balance transaction. "tracking_key": "88231432001"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_xK9mP3q7TZLk",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-20T14:00: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_xK9mP3q7TZLk",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_LenderCOP01",Account IdiCobre Balance account id affected by the event. "amount": -50000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 55000000,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-20T14:00:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-20T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "beneficiary_account_number": "",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": "Loan disbursement CO-88231",DescriptioniHuman-readable label or note. "money_movement_id": "mm_xK9mP3q7TZ",Money Movement IdiMoney Movement that generated this balance transaction. "tracking_key": "88231432001"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_xK9mP3q7TZCp",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-20T14:32:11Z",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_xK9mP3q7TZCp",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_LenderCOP01",Account IdiCobre Balance account id affected by the event. "amount": 50000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 50000000,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-20T14:32:11Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-20T14:32:11Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Loan disbursement CO-88231",DescriptioniHuman-readable label or note. "money_movement_id": "mm_xK9mP3q7TZ",Money Movement IdiMoney Movement that generated this balance transaction. "tracking_key": "88231432001"Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). } }}
Step 7 of 13
Loan Disbursement
API step
Find the Pending Approval
Your external approval workflow (ERP, treasury tool, or internal checker UI) decides whether to release the disbursement. Cobre holds the payment in pending_approval — use this call to retrieve the Money Movement Approval object and its mma_… ID before submitting the decision.
GET
https://api.cobre.co/v1/money_movement_approvals
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbGVuZGVyX2NvXzAxIn0.s7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
Response 200
{ "total_items": 1,Total ItemsiTotal items matching the query across all pages. "total_pages": 1,Total PagesiNumber of pages in this result set. "is_last_page": true,Is Last PageiTrue when this is the final page of results. "page_items": 1,Page ItemsiNumber of items returned on this page. "contents": [ContentsiArray of result objects for this page. { "id": "mma_dnQOheIG9J",Approval IDiThe money-movement-approval ID (mma_...) the checker will approve. "mm_id": "mm_xK9mP3q7TZ",Money Movement IDiThe disbursement this approval gates — matches the money movement just created. "status": {StatusiLifecycle status object for the resource or movement. "decision": "pending",Current DecisioniPending until a checker approves or denies. "description": "",DescriptioniHuman-readable label or note. "approvers": []ApproversiCobre field at "contents.0.status.approvers" in this payload. }, "created_at": "2026-06-20T14:00:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-20T14:00:01Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). } ]}
Step 8 of 13
Loan Disbursement
API step
Approve the Disbursement (Checker)
Submit the checker's decision to Cobre after your external approval workflow completes. Include approvers for auditability — each approval can only be decided once. If approved, the Money Movement continues processing; if denied, Cobre cancels it and releases the hold.
POST
https://api.cobre.co/v1/money_movement_approvals/mma_dnQOheIG9J/decision
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbGVuZGVyX2NvXzAxIn0.s7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "decision": "approved",DecisionRequirediapproved releases the funds; denied cancels the disbursement. "description": "Approved by Credit Committee.",DescriptionRequirediA note recorded with the decision for your audit trail. "approvers": [ApproversiCobre field at "approvers" in this payload. "ceo@lender.co" ]}Response 201
{ "id": "mma_dnQOheIG9J",IdiUnique Cobre identifier for this resource. "mm_id": "mm_xK9mP3q7TZ",Mm IdiMoney Movement id linked to an approval object. "status": {StatusiLifecycle status object for the resource or movement. "decision": "approved",DecisioniMoney Movement Approval decision: pending, approved, or denied. "description": "Approved by Credit Committee.",DescriptioniHuman-readable detail for the current status. "approvers": [ApproversiCobre field at "status.approvers" in this payload. "ceo@lender.co" ] }, "created_at": "2026-06-20T14:00:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-20T14:05:33Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 9 of 13
Loan Disbursement
Reconciliation
Update the Loan from the Disbursement Webhook
After checker_approval, external decision, and rail settlement, Cobre delivers the money_movements.status.completed webhook from the disbursement step. No API call is needed — read the payload and update your loan-management system in real time.
Mapping the webhook payload from an earlier step onto Loan Management System. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Loan Management System field | |
content.external_id loan-CO-88231-disb |
→ | loan_disbursement_ref Your own reference — use it to locate the loan record. |
content.id mm_xK9mP3q7TZ |
→ | cobre_payment_id Store as the canonical Cobre payment id for audit. |
content.status.state completed |
→ | loan_status Map completed -> FUNDED; rejected/failed -> DISBURSEMENT_FAILED. |
content.amount 50000000 |
→ | disbursed_amount_cents |
content.updated_at 2026-06-20T14:32:11Z |
→ | funded_at |
Step 10 of 13
Repayment
API step
Set Up the Borrower for Bre-B Collection
To collect a repayment you register the borrower as an r2p_breb counterparty. This lets you send them a Bre-B request-to-pay; the returned ID is referenced as the source of the collection.
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbGVuZGVyX2NvXzAxIn0.s7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "geo": "col",GeographyRequirediCountry domain. col = Colombia. "type": "r2p_breb",TypeRequiredir2p_breb = Bre-B request-to-pay collection. "alias": "Repayment - loan CO-88231",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Juliana Restrepo",Full NameRequirediThe borrower's full name. "counterparty_id_type": "cc",ID TypeiIdentification type of the borrower. "counterparty_id_number": "5334623427",ID NumberiThe borrower's identification number. "counterparty_email": "borrower@example.co"EmailiBorrower email — used for PSE/Bre-B updates; must be valid or the movement fails. }}Response 201
{ "id": "cp_R2pBrwr88231",IdiUnique Cobre identifier for this resource. "geo": "col",GeographyRequirediCountry domain. col = Colombia. "type": "r2p_breb",TypeRequiredir2p_breb = Bre-B request-to-pay collection. "alias": "Repayment - loan CO-88231",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Juliana Restrepo",Full NameRequirediThe borrower's full name. "counterparty_id_type": "cc",ID TypeiIdentification type of the borrower. "counterparty_id_number": "5334623427",ID NumberiThe borrower's identification number. "counterparty_email": "borrower@example.co"EmailiBorrower email — used for PSE/Bre-B updates; must be valid or the movement fails. }, "created_at": "2026-07-20T09:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-20T09:00:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 11 of 13
Repayment
API step
Request Repayment via Bre-B
The borrower receives a Bre-B request-to-pay in the Crédito Ágil app and confirms it. On your side this is a money movement payin: the source is the borrower's r2p_breb counterparty and the destination is your funding account.
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbGVuZGVyX2NvXzAxIn0.s7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
| idempotency | loan-CO-88231-repay-001 |
Request body
{ "source_id": "cp_R2pBrwr88231",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_LenderCOP01",Destination IdiCobre id of the destination account or counterparty. "amount": 50000000,Amount to pay (cents)RequirediAmount in cents — last two digits are decimals. 50000000 = $500,000.00 COP. "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Loan repayment CO-88231"DescriptioniOptional description attached to the money movement for your own tracking. }, "external_id": "loan-CO-88231-repay"ReferenceiYour repayment reference, echoed in responses and webhooks for reconciliation.}Response 201
{ "id": "mm_RepayQ7x2Lc",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": "Request to pay sent to the borrower; awaiting authorization."DescriptioniHuman-readable detail for the current status. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_key",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "description_to_payer": "Loan repayment CO-88231",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "description_to_payee": "Loan repayment CO-88231",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "description": "Loan repayment CO-88231"DescriptioniOptional description attached to the money movement for your own tracking. }, "creator": "cli_lender_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-CO-88231-repay",ReferenceiYour repayment reference, echoed in responses and webhooks for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "r2p_breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_R2pBrwr88231",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_LenderCOP01",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 50000000,Amount to pay (cents)RequirediAmount in cents — last two digits are decimals. 50000000 = $500,000.00 COP. "created_at": "2026-07-20T09:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-20T09:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
When the borrower authorizes the Bre-B request-to-pay and the funds settle into your account, Cobre delivers this. Mark the installment as paid on receipt. Cobre also credits your funding balance (r2p_breb_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_LenderRepayCmp",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-20T09:07:48Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "mm_RepayQ7x2Lc",IdiUnique Cobre identifier for this resource. "status": {StatusiLifecycle status object for the resource or movement. "state": "completed",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "",CodeiProvider or Cobre status code when the state is failed or rejected. "description": ""DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_key",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "description_to_payer": "Loan repayment CO-88231",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "description_to_payee": "Loan repayment CO-88231",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "tracking_key": "88231074801",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "key_value": "@BorrowerKey88231",Key ValueiBre-B key value (e.g. @merchant123). "sender_name": "Juliana Restrepo",Sender NameiMetadata field "sender_name" attached to the resource. "sender_id": "5334623427",Sender IdiMetadata field "sender_id" attached to the resource. "sender_id_type": "cc",Sender Id TypeiMetadata field "sender_id_type" attached to the resource. "sender_bank_code": "1007",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "description": "Loan repayment CO-88231"DescriptioniHuman-readable label or note. }, "creator": "cli_lender_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-CO-88231-repay",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "r2p_breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_R2pBrwr88231",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_LenderCOP01",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 50000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-20T09:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-20T09:07:48Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}Cobre or the rail could not process the movement. Inspect status.code and status.description. 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_LenderRepayCmp",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-20T09:07:48Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "mm_RepayQ7x2Lc",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": "F003",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "R2P Payment link expired."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_key",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "description_to_payer": "Loan repayment CO-88231",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "description_to_payee": "Loan repayment CO-88231",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "tracking_key": "88231074801",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "key_value": "@BorrowerKey88231",Key ValueiBre-B key value (e.g. @merchant123). "sender_name": "Juliana Restrepo",Sender NameiMetadata field "sender_name" attached to the resource. "sender_id": "5334623427",Sender IdiMetadata field "sender_id" attached to the resource. "sender_id_type": "cc",Sender Id TypeiMetadata field "sender_id_type" attached to the resource. "sender_bank_code": "1007",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "description": "Loan repayment CO-88231"DescriptioniHuman-readable label or note. }, "creator": "cli_lender_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-CO-88231-repay",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "r2p_breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_R2pBrwr88231",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_LenderCOP01",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 50000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-20T09:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-20T09:07:48Z"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_LenderRepayCmp",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-20T09:07:48Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "mm_RepayQ7x2Lc",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": "R016",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "Payment rejected due to timeout."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "breb_key",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "description_to_payer": "Loan repayment CO-88231",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "description_to_payee": "Loan repayment CO-88231",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "tracking_key": "88231074801",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "key_value": "@BorrowerKey88231",Key ValueiBre-B key value (e.g. @merchant123). "sender_name": "Juliana Restrepo",Sender NameiMetadata field "sender_name" attached to the resource. "sender_id": "5334623427",Sender IdiMetadata field "sender_id" attached to the resource. "sender_id_type": "cc",Sender Id TypeiMetadata field "sender_id_type" attached to the resource. "sender_bank_code": "1007",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "description": "Loan repayment CO-88231"DescriptioniHuman-readable label or note. }, "creator": "cli_lender_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-CO-88231-repay",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "r2p_breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_R2pBrwr88231",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_LenderCOP01",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 50000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-20T09:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-20T09:07:48Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}When a payin Money Movement completes, Cobre credits the destination Cobre Balance and delivers accounts.balance.credit. Transaction type matches the movement type — see GET /accounts/{id}/transactions OAS examples.
When the payin settles, Cobre credits the destination Cobre Balance.
Event
accounts.balance.creditHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_RepayQ7x2LCr",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-20T09:07:48Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "trx_RepayQ7x2LcCr",IdiUnique Cobre identifier for this resource. "type": "r2p_breb_credit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "account_id": "acc_LenderCOP01",Account IdiCobre Balance account id affected by the event. "amount": 50000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 50000000,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-20T09:07:48Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-20T09:07:48Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "sender_account_number": "",Sender Account NumberiMetadata field "sender_account_number" attached to the resource. "sender_account_type": "ch",Sender Account TypeiMetadata field "sender_account_type" attached to the resource. "sender_bank_code": "1007",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "sender_id": "5334623427",Sender IdiMetadata field "sender_id" attached to the resource. "sender_id_type": "cc",Sender Id TypeiMetadata field "sender_id_type" attached to the resource. "key_value": "@BorrowerKey88231",Key ValueiBre-B key value (e.g. @merchant123). "sender_name": "Juliana Restrepo",Sender NameiMetadata field "sender_name" attached to the resource. "description": "Loan repayment CO-88231",DescriptioniHuman-readable label or note. "money_movement_id": "mm_RepayQ7x2Lc"Money Movement IdiMoney Movement that generated this balance transaction. } }}Documentation for this step
Create a Money MovementMoney Movement GuideNotifications & Subscriptions
Step 12 of 13
Reconciliation
API step
Generate the D+1 Cobre Balance Statement
At end-of-day or D+1, generate an account statement to reconcile every disbursement and repayment against your ledger in bulk. You ask for the statement; Cobre produces a downloadable file.
POST
https://api.cobre.co/v1/reports
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbGVuZGVyX2NvXzAxIn0.s7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "resource": "accounts",ResourceRequirediWhat the report covers. accounts = account statements. "layout": "cobre_balance_statements_v1",LayoutRequirediThe report layout / format template. "metadata": {MetadataiCustom key-value metadata attached to the resource. "account_id": "acc_LenderCOP01",AccountRequirediWhich account to produce the statement for — your COP funding account. "statement_date": "2026-07"Statement PeriodRequirediThe period to report on (YYYY-MM). }}Response 201
{ "id": "repo_kJs8GO03vC",IdiUnique Cobre identifier for this resource. "resource": "accounts",ResourceRequirediWhat the report covers. accounts = account statements. "start_date": "2026-07-01T00:00:00Z",Start DateiCobre field at "start_date" in this payload. "end_date": "2026-07-31T23:59:59Z",End DateiCobre field at "end_date" in this payload. "file_name": "2026-07_accounts_repo_kJs8GO03vC_acc_LenderCOP01",File NameiCobre field at "file_name" in this payload. "file_format": "pdf",File FormatiCobre field at "file_format" in this payload. "file_layout": "cobre_balance_statements_v1",File LayoutiCobre field at "file_layout" in this payload. "metadata": {MetadataiCustom key-value metadata attached to the resource. "account_id": "acc_LenderCOP01",AccountRequirediWhich account to produce the statement for — your COP funding account. "statement_date": "2026-07"Statement PeriodRequirediThe period to report on (YYYY-MM). }, "sensitive_data": false,Sensitive DataiCobre field at "sensitive_data" in this payload. "requested_at": "2026-08-01T00:00:01Z",Requested AtiCobre field at "requested_at" in this payload. "created_at": "2026-08-01T00:01:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 13 of 13
Reconciliation
Reconciliation
Reconcile the Statement to Your Ledger
The final close: map the generated statement onto your accounting ledger. This is the batch counterpart to the real-time webhooks — once these fields line up, the lending cycle is provably closed.
Mapping the Cobre report from an earlier step onto Accounting Ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Accounting Ledger field | |
id repo_kJs8GO03vC |
→ | statement_reference The report id, stored against the reconciliation batch. |
file_name 2026-07_accounts_repo_kJs8GO03vC_acc_LenderCOP01 |
→ | statement_file |
metadata.account_id acc_LenderCOP01 |
→ | gl_account |
end_date 2026-07-31T23:59:59Z |
→ | period_close_date |