Step 1 of 19
Configuration
API step
Authenticate
Every Cobre API call carries a short-lived Bearer token (~20 minutes). Exchange API user credentials once and attach the token to every subsequent request.
POST
https://api.cobre.co/v1/auth
Headers
| Content-Type | application/json |
Request body
{ "user_id": "cli_psp_cn_co01",User IDiAPI client user id used to obtain the access token. "secret": "sk_live_PspCn9xK2v"SecretiAPI client secret paired with user_id for authentication.}Response 201
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ",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 19
Configuration
API step
Subscribe to Webhook Events
Subscribe to balance credits/debits, Money Movement status, and Cross-Border lifecycle events. Verify HMAC-SHA256 signatures on every delivery.
POST
https://api.cobre.co/v1/subscriptions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "url": "https://psp.example.co/webhooks/cobre",Notification URLiHTTPS URL used by this resource (e.g. webhook endpoint). "description": "China merchant treasury lifecycle",DescriptioniHuman-readable label or note. "events": [EventsiList of webhook event types this subscription listens to. "accounts.balance.credit", "accounts.balance.debit", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected", "cross_border_money_movements.status.completed", "cross_border_money_movements.status.failed", "cross_border_money_movements.status.rejected" ], "event_signature_key": "WHsig_PspCn01"Signature KeyiSecret you set on the subscription; Cobre uses it to HMAC-SHA256-sign deliveries (verify via event-signature + event-timestamp headers).}Response 201
{ "id": "sub_PspCnTre01",IdiUnique Cobre identifier for this resource. "url": "https://psp.example.co/webhooks/cobre",Notification URLiHTTPS URL used by this resource (e.g. webhook endpoint). "description": "China merchant treasury lifecycle",DescriptioniHuman-readable label or note. "events": [EventsiList of webhook event types this subscription listens to. "accounts.balance.credit", "accounts.balance.debit", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected", "cross_border_money_movements.status.completed", "cross_border_money_movements.status.failed", "cross_border_money_movements.status.rejected" ], "event_signature_key": "******Cn01",Signature KeyiSecret you set on the subscription; Cobre uses it to HMAC-SHA256-sign deliveries (verify via event-signature + event-timestamp headers). "created_at": "2026-07-06T10:00:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 3 of 19
Configuration
API step
Create COP Payout Cobre Balance
Create the Colombian COP Payout balance first (primary account). It must exist before the Payin balance — Payin accounts reference it via metadata.primary_account for automatic sweeps. Also the source for local payouts and Cross-Border FX.
POST
https://api.cobre.co/v1/accounts
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "provider_id": "pr_col_cobre",ProvideriCobre field at "provider_id" in this payload. "action": "create",ActioniCobre field at "action" in this payload. "alias": "PSP COP Payout"AliasiDisplay name that helps identify it and clarify its purpose.}Response 201
{ "id": "acc_PspCopPayout",IdiUnique Cobre identifier for this resource. "provider_id": "pr_col_cobre",ProvideriCobre field at "provider_id" in this payload. "provider_name": "Cobre Balance Colombia",Provider NameiCobre field at "provider_name" in this payload. "connectivity": {ConnectivityiConnection/registration status for keys or accounts. "status": "connected",StatusiLifecycle status object for the resource or movement. "description": ""DescriptioniHuman-readable label or note. }, "alias": "PSP COP Payout",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "available_services": [Available ServicesiCobre field at "metadata.available_services" in this payload. "mm_push_from_account", "account_transactions" ] }, "account_number": "",Account NumberiBank account or CLABE number for the counterparty. "account_type": "cobre_balance",Account TypeiCobre field at "account_type" in this payload. "obtained_balance": 0,Obtained BalanceiCobre field at "obtained_balance" in this payload. "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "tags": [],TagsiCobre field at "tags" in this payload. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "created_at": "2026-07-06T10:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-06T10:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 4 of 19
Configuration
API step
Create COP Payin Cobre Balance
Create the Colombian COP Payin balance (secondary account) after the Payout balance. Set metadata.primary_account to acc_PspCopPayout so inbound credits auto-sweep. If the automatic sweep does not occur, move funds manually as described in the Internal Transfer stage.
POST
https://api.cobre.co/v1/accounts
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "provider_id": "pr_col_cobre",ProvideriCobre field at "provider_id" in this payload. "action": "create",ActioniCobre field at "action" in this payload. "alias": "PSP COP Payin",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "primary_account": "acc_PspCopPayout"Primary accountiPayout Cobre Balance (acc_PspCopPayout) — every Payin credit auto-sweeps here. }}Response 201
{ "id": "acc_PspCopPayin",IdiUnique Cobre identifier for this resource. "provider_id": "pr_col_cobre",ProvideriCobre field at "provider_id" in this payload. "provider_name": "Cobre Balance Colombia",Provider NameiCobre field at "provider_name" in this payload. "connectivity": {ConnectivityiConnection/registration status for keys or accounts. "status": "connected",StatusiLifecycle status object for the resource or movement. "description": ""DescriptioniHuman-readable label or note. }, "alias": "PSP COP Payin",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "available_services": [Available ServicesiCobre field at "metadata.available_services" in this payload. "mm_push_from_account", "account_transactions" ], "primary_account": "acc_PspCopPayout"Primary accountiPayout Cobre Balance (acc_PspCopPayout) — every Payin credit auto-sweeps here. }, "account_number": "",Account NumberiBank account or CLABE number for the counterparty. "account_type": "cobre_balance",Account TypeiCobre field at "account_type" in this payload. "obtained_balance": 0,Obtained BalanceiCobre field at "obtained_balance" in this payload. "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "tags": [],TagsiCobre field at "tags" in this payload. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "created_at": "2026-07-06T10:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-06T10:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Documentation for this step
Create or Connect an AccountAccount Linkage GuideManaging Cobre Balances
Step 5 of 19
Configuration
API step
Create USD Global Cobre Balance
Provision the USD Global Cobre Balance — destination of COP→USD Cross-Border conversions.
POST
https://api.cobre.co/v1/accounts
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "provider_id": "pr_global_cobre",ProvideriCobre field at "provider_id" in this payload. "action": "create",ActioniCobre field at "action" in this payload. "metadata": {MetadataiCustom key-value metadata attached to the resource. "currency": "usd"CurrencyiISO currency code (e.g. cop, mxn). }, "alias": "PSP USD Global Treasury"AliasiDisplay name that helps identify it and clarify its purpose.}Response 201
{ "id": "acc_PspUsdGlobal",IdiUnique Cobre identifier for this resource. "provider_id": "pr_global_cobre",ProvideriCobre field at "provider_id" in this payload. "provider_name": "Cobre Balance Global",Provider NameiCobre field at "provider_name" in this payload. "connectivity": {ConnectivityiConnection/registration status for keys or accounts. "status": "connected",StatusiLifecycle status object for the resource or movement. "description": ""DescriptioniHuman-readable label or note. }, "alias": "PSP USD Global Treasury",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "available_services": [Available ServicesiCobre field at "metadata.available_services" in this payload. "mm_push_from_account" ], "currency": "usd"CurrencyiISO currency code (e.g. cop, mxn). }, "account_number": "",Account NumberiBank account or CLABE number for the counterparty. "account_type": "cobre_balance",Account TypeiCobre field at "account_type" in this payload. "obtained_balance": 0,Obtained BalanceiCobre field at "obtained_balance" in this payload. "geo": "global",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "tags": [],TagsiCobre field at "tags" in this payload. "currency": "usd",CurrencyiISO currency code (e.g. cop, mxn). "created_at": "2026-07-06T10:06:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-06T10:06:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 6 of 19
Transfer-In Funding
API step
Create Merchant Transfer-In Reference
Create a Transfer-In account reference on the COP Payin balance for China merchant CN01. Inbound bank transfers credit acc_PspCopPayin with metadata.account_reference for merchant attribution.
POST
https://api.cobre.co/v1/account_references
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "source_id": "acc_PspCopPayin",COP Payin BalanceiCobre id of the source account or counterparty. "type": "transfer_acc",Reference typeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "alias": "Merchant CN01 Transfer-In",AliasiDisplay name that helps identify it and clarify its purpose. "provider_id": "pr_col_1066"Collection bank provideriCobre field at "provider_id" in this payload.}Response 200
{ "id": "ref_MerchantCn01",IdiUnique Cobre identifier for this resource. "alias": "Merchant CN01 Transfer-In",AliasiDisplay name that helps identify it and clarify its purpose. "type": "transfer_acc",Reference typeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "value": "291000881",ValueiCobre field at "value" in this payload. "source_id": "acc_PspCopPayin",COP Payin BalanceiCobre id of the source account or counterparty. "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "connectivity": {ConnectivityiConnection/registration status for keys or accounts. "status": "enabled",StatusiLifecycle status object for the resource or movement. "description": ""DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "account_type": "cc",Account TypeiCobre field at "metadata.account_type" in this payload. "account_holder_id": "9018877665",Account Holder IdiCobre field at "metadata.account_holder_id" in this payload. "account_holder_id_type": "NIT",Account Holder Id TypeiCobre field at "metadata.account_holder_id_type" in this payload. "provider_id": "pr_col_1066"Provider IdiCobre field at "metadata.provider_id" in this payload. }, "created_at": "2026-07-06T11:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-06T11:00:05Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 7 of 19
Transfer-In Funding
API step
Merchant Transfer-In Credit
The merchant wires COP from a local bank to their Transfer-In collection account. Cobre credits acc_PspCopPayin with transfer_credit — reconcile using metadata.account_reference 291000881 (ref_MerchantCn01).
GET
https://api.cobre.co/v1/accounts/acc_PspCopPayinPayin Cobre BalanceiPath parameter — COP Payin balance where Transfer-In credits post./transactions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "total_items": 1,Total ItemsiTotal items matching the query across all pages. "total_pages": 1,Total PagesiNumber of pages in this result set. "is_last_page": true,Is Last PageiTrue when this is the final page of results. "page_items": 1,Page ItemsiNumber of items returned on this page. "contents": [ContentsiArray of result objects for this page. { "id": "trx_MerchCn001",Transaction IDiUnique Cobre identifier for this resource. "type": "transfer_credit",Transaction typeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "account_id": "acc_PspCopPayin",Account IdiCobre Balance account id affected by the event. "amount": 50000000,Amount creditediAmount in cents — the last two digits are decimals. "previous_balance": 100000000,Previous BalanceiCobre field at "contents.0.previous_balance" in this payload. "current_balance": 150000000,Current BalanceiCobre field at "contents.0.current_balance" in this payload. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "credit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-07-06T13:10:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-06T13:10:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "reference": "0038219901",ReferenceiPayment reference echoed in metadata for reconciliation. "sender_name": "Merchant CN01 SAS",Sender NameiMetadata field "sender_name" attached to the resource. "sender_id": "9018877665",Sender IdiMetadata field "sender_id" attached to the resource. "sender_bank_code": "1066",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "tracking_key": "291000881C6059901",Tracking KeyiBre-B tracking key for the payment. "description": "Transfer-In merchant funding",DescriptioniHuman-readable label or note. "account_reference": "291000881"Account referenceiTransfer-In reference number used to reconcile incoming deposits. } } ]}Webhook delivered
accounts.balance.creditFires when the Transfer-In credit posts on acc_PspCopPayin. Map metadata.account_reference to merchant CN01.
Headers
| Content-Type | application/json |
Payload
{ "id": "ev_MerchCnTi001",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-06T13:10:01Z",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_MerchCn001",IdiUnique Cobre identifier for this resource. "type": "transfer_credit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "amount": 50000000,AmountiAmount in cents — the last two digits are decimals. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "date": "2026-07-06T13:10:00Z",DateiTimestamp when the balance transaction was posted (ISO 8601, UTC) — used in accounts.balance.* webhook notifications. "metadata": {MetadataiCustom key-value metadata attached to the resource. "reference": "0038219901",ReferenceiPayment reference echoed in metadata for reconciliation. "sender_name": "Merchant CN01 SAS",Sender NameiMetadata field "sender_name" attached to the resource. "sender_id": "9018877665",Sender IdiMetadata field "sender_id" attached to the resource. "sender_bank_code": "1066",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "tracking_key": "291000881C6059901",Tracking KeyiBre-B tracking key for the payment. "description": "Transfer-In merchant funding",DescriptioniHuman-readable label or note. "account_reference": "291000881"Account ReferenceiTransfer-In reference number used to reconcile incoming deposits. }, "account_id": "acc_PspCopPayin",Account IdiCobre Balance account id affected by the event. "previous_balance": 100000000,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 150000000,Current BalanceiCobre field at "content.current_balance" in this payload. "credit_debit_type": "credit"Credit Debit Typeicredit = funds in; debit = funds out. }}
Step 8 of 19
Transfer-In Funding
Reconciliation
Reconcile Transfer-In Credit
Match the accounts.balance.credit webhook to your treasury ledger using metadata.account_reference for merchant attribution. No Money Movement exists — reconciliation is transaction-level on acc_PspCopPayin.
Mapping the webhook payload from an earlier step onto Treasury ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Treasury ledger field | |
content.metadata.account_reference 291000881 |
→ | merchant_transfer_in_ref Primary join key — maps ref_MerchantCn01 (291000881) to merchant CN01 available COP. |
content.id trx_MerchCn001 |
→ | cobre_transaction_id |
content.amount 50000000 |
→ | credited_amount_cents COP credited to acc_PspCopMaster (50000000 = $500,000.00 COP). |
content.account_id acc_PspCopPayin |
→ | cop_payin_balance_id |
content.metadata.tracking_key 291000881C6059901 |
→ | bank_tracking_key Bank network tracking key — store for audit alongside metadata.reference. |
Step 9 of 19
Internal Transfer
API step
Manual transfer: Payin → Payout
Account linkage reliably auto-sweeps Payin credits to Payout, but it can occasionally fail. When account linkage does not auto-sweep, manually move COP from acc_PspCopPayin to acc_PspCopPayout with POST /money_movements (Cobre Balance → Cobre Balance). The same endpoint moves funds in reverse (Payout → Payin) by swapping source_id and destination_id. If the automatic sweep does not occur, move funds manually as described in the Internal Transfer stage.
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
| idempotency | psp-internal-sweep-cn001 |
Request body
{ "amount": 150000000,Amount (COP cents)iAmount in cents — the last two digits are decimals. "source_id": "acc_PspCopPayin",COP Payin balanceiCobre id of the source account or counterparty. "destination_id": "acc_PspCopPayout",COP Payout balanceiCobre id of the destination account or counterparty. "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Manual Payin to Payout transfer"DescriptioniHuman-readable label or note. }, "external_id": "psp_internal_sweep_001",External IDiYour own reference echoed by Cobre for reconciliation. "checker_approval": falseChecker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.}Response 201
{ "id": "mm_InternalSweep01",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": "Manual Payin to Payout transfer"DescriptioniHuman-readable label or note. }, "creator": "cli_psp_cn_co01",CreatoriAPI client id that created this resource. "external_id": "psp_internal_sweep_001",External IDiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "fast_pay",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_PspCopPayin",COP Payin balanceiCobre id of the source account or counterparty. "destination_id": "acc_PspCopPayout",COP Payout balanceiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 150000000,Amount (COP cents)iAmount in cents — the last two digits are decimals. "created_at": "2026-07-07T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-07T12:00:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
Manual transfer completed — COP debited from acc_PspCopPayin and credited to acc_PspCopPayout. Use when automatic linkage sweep did not run.
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_InternalSweepCmp",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-07T12:02: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_InternalSweep01",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": "Manual Payin to Payout transfer"DescriptioniHuman-readable label or note. }, "creator": "cli_psp_cn_co01",CreatoriAPI client id that created this resource. "external_id": "psp_internal_sweep_001",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "fast_pay",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_PspCopPayin",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_PspCopPayout",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 150000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-07T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-07T12:02:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}Cobre or the rail could not process the movement. Inspect status.code and status.description — common failed codes include:
Possible status codes
F001 | Payment processing failed — please try again. |
F002 | NSF — not sufficient funds in the designated account. |
F003 | R2P payment link expired (payins). |
F004 | Daily transaction amount limit has been reached. |
F005 | Amount exceeds the maximum allowed transaction limit. |
F098 | Could not process the money movement at this time. |
F099 | Could not process the money movement at this time. |
Event
money_movements.status.failedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_InternalSweepCmp",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-07T12:02: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_InternalSweep01",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": "Manual Payin to Payout transfer"DescriptioniHuman-readable label or note. }, "creator": "cli_psp_cn_co01",CreatoriAPI client id that created this resource. "external_id": "psp_internal_sweep_001",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "fast_pay",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_PspCopPayin",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_PspCopPayout",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 150000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-07T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-07T12:02:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}The bank or payment network rejected the transaction. Inspect status.code — common rejected codes include:
Possible status codes
R000 | Transaction rejected. |
R001 | Inactive or blocked account. |
R002 | Account and identification provided do not coincide. |
R005 | Account does not exist. |
R006 | Invalid account number. |
R009 | Exceeds maximum allowed amount. |
R018 | Payment rejected due to invalid key (payouts). |
R023 | Payment cancelled by the user. |
R026 | Payment rejected due to unavailable bank services. |
R034 | Account closed. |
R085 | Bank processing error (payouts). |
Event
money_movements.status.rejectedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_InternalSweepCmp",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-07T12:02: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_InternalSweep01",IdiUnique Cobre identifier for this resource. "status": {StatusiLifecycle status object for the resource or movement. "state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "R001",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "Inactive or blocked account."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Manual Payin to Payout transfer"DescriptioniHuman-readable label or note. }, "creator": "cli_psp_cn_co01",CreatoriAPI client id that created this resource. "external_id": "psp_internal_sweep_001",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "fast_pay",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_PspCopPayin",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_PspCopPayout",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 150000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-07T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-07T12:02: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_InternalSwLk",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-07T12: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_InternalSweeLk",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_PspCopPayin",Account IdiCobre Balance account id affected by the event. "amount": -150000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 155000000,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 5000000,Current BalanceiCobre field at "content.current_balance" in this payload. "currency": "COP",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "debit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-07-07T12:00:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-07T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_InternalSweep01",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Manual Payin to Payout transfer",DescriptioniHuman-readable label or note. "beneficiary_account_number": "",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "tracking_key": ""Tracking KeyiBre-B tracking key for the payment. } }}On completion the locked funds are sent to the beneficiary. The processing debit remains on the ledger — no compensation credit is posted.
Event
accounts.balance.debitHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_InternalSwLk",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-07T12: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_InternalSweeLk",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_PspCopPayin",Account IdiCobre Balance account id affected by the event. "amount": -150000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 155000000,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 5000000,Current BalanceiCobre field at "content.current_balance" in this payload. "currency": "COP",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "debit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-07-07T12:00:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-07T12:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_InternalSweep01",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Manual Payin to Payout transfer",DescriptioniHuman-readable label or note. "beneficiary_account_number": "",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "tracking_key": ""Tracking KeyiBre-B tracking key for the payment. } }}If the movement reaches a terminal failed, rejected, or canceled state, Cobre credits the source Cobre Balance to release the lock (breb_credit for Bre-B, col_cb_credit for bank rails).
Event
accounts.balance.creditHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_InternalSwCp",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-07T12:02: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_InternalSweeCp",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_PspCopPayin",Account IdiCobre Balance account id affected by the event. "amount": 150000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 150000000,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-07T12:02:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-07T12:02:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_InternalSweep01",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Manual Payin to Payout transfer",DescriptioniHuman-readable label or note. "tracking_key": "",Tracking KeyiBre-B tracking key for the payment. "sender_name": "",Sender NameiMetadata field "sender_name" attached to the resource. "sender_id": "",Sender IdiMetadata field "sender_id" attached to the resource. "sender_account_number": ""Sender Account NumberiMetadata field "sender_account_number" attached to the resource. } }}
Step 10 of 19
Internal Transfer
Reconciliation
Reconcile manual Payin → Payout transfer
Match the completion webhook on external_id psp_internal_sweep_001. Cross-check COP debit on acc_PspCopPayin and credit on acc_PspCopPayout. Only needed when automatic linkage sweep did not occur.
Mapping the webhook payload from an earlier step onto Treasury ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Treasury ledger field | |
content.external_id psp_internal_sweep_001 |
→ | sweep_reference |
content.id mm_InternalSweep01 |
→ | cobre_mm_id |
content.amount 150000000 |
→ | swept_amount_cents |
content.status.state completed |
→ | sweep_status |
Step 11 of 19
Local Payout
API step
Create Local Bank Beneficiary
Register a Colombia bank-account counterparty (cc) for a local COP payout from acc_PspCopPayout via Fast Pay/ACH.
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "geo": "col",GeographyiGeography code (e.g. col = Colombia, mex = Mexico). "type": "cc",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "alias": "Local vendor - Merchant CN01",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Local Vendor SAS",Beneficiary nameiLegal or display name of the counterparty beneficiary. "beneficiary_institution": "1007",Bank codeiBank or institution code for the destination account. "account_number": "1013555555",Account numberiBank account or CLABE number for the counterparty. "counterparty_id_type": "nit",Counterparty Id TypeiType of identification document for the counterparty (e.g. nit, cc, rfc). "counterparty_id_number": "9005551234"Counterparty Id NumberiIdentification number for the counterparty. }}Response 201
{ "id": "cp_LocalVendor01",IdiUnique Cobre identifier for this resource. "geo": "col",GeographyiGeography code (e.g. col = Colombia, mex = Mexico). "type": "cc",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "alias": "Local vendor - Merchant CN01",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_fullname": "Local Vendor SAS",Beneficiary nameiLegal or display name of the counterparty beneficiary. "beneficiary_institution": "1007",Bank codeiBank or institution code for the destination account. "account_number": "1013555555",Account numberiBank account or CLABE number for the counterparty. "counterparty_id_type": "nit",Counterparty Id TypeiType of identification document for the counterparty (e.g. nit, cc, rfc). "counterparty_id_number": "9005551234",Counterparty Id NumberiIdentification number for the counterparty. "registered_account": falseRegistered AccountiCobre field at "metadata.registered_account" in this payload. }, "created_at": "2026-07-07T12:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-07T12:10:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 12 of 19
Local Payout
API step
Pay via Fast Pay / ACH
Create a Money Movement from acc_PspCopPayout to the local bank counterparty. Cobre routes Fast Pay when the destination bank supports it, otherwise ACH — the response type indicates the rail used.
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
| idempotency | psp-local-payout-cn001 |
Request body
{ "amount": 30000000,Amount (COP cents)iAmount in cents — the last two digits are decimals. "source_id": "acc_PspCopPayout",COP Payout balanceiCobre id of the source account or counterparty. "destination_id": "cp_LocalVendor01",BeneficiaryiCobre id of the destination account or counterparty. "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Local vendor payout"DescriptioniHuman-readable label or note. }, "external_id": "psp_local_payout_001",External IDiYour own reference echoed by Cobre for reconciliation. "checker_approval": falseChecker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API.}Response 201
{ "id": "mm_LocalPayout01",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": "Local vendor payout"DescriptioniHuman-readable label or note. }, "creator": "cli_psp_cn_co01",CreatoriAPI client id that created this resource. "external_id": "psp_local_payout_001",External IDiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "fast_pay",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_PspCopPayout",COP Payout balanceiCobre id of the source account or counterparty. "destination_id": "cp_LocalVendor01",BeneficiaryiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 30000000,Amount (COP cents)iAmount in cents — the last two digits are decimals. "created_at": "2026-07-07T12:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-07T12:15:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
Local payout completed — COP debited from acc_PspCopPayout. Reconcile on external_id psp_local_payout_001.
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_LocalPayoutCmp",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-07T12:17: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_LocalPayout01",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": "Local vendor payout"DescriptioniHuman-readable label or note. }, "creator": "cli_psp_cn_co01",CreatoriAPI client id that created this resource. "external_id": "psp_local_payout_001",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "fast_pay",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_PspCopPayout",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_LocalVendor01",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-07-07T12:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-07T12:17:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}Cobre or the rail could not process the movement. Inspect status.code and status.description — common failed codes include:
Possible status codes
F001 | Payment processing failed — please try again. |
F002 | NSF — not sufficient funds in the designated account. |
F003 | R2P payment link expired (payins). |
F004 | Daily transaction amount limit has been reached. |
F005 | Amount exceeds the maximum allowed transaction limit. |
F098 | Could not process the money movement at this time. |
F099 | Could not process the money movement at this time. |
Event
money_movements.status.failedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_LocalPayoutCmp",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-07T12:17: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_LocalPayout01",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": "Local vendor payout"DescriptioniHuman-readable label or note. }, "creator": "cli_psp_cn_co01",CreatoriAPI client id that created this resource. "external_id": "psp_local_payout_001",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "fast_pay",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_PspCopPayout",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_LocalVendor01",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-07-07T12:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-07T12:17:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}The bank or payment network rejected the transaction. Inspect status.code — common rejected codes include:
Possible status codes
R000 | Transaction rejected. |
R001 | Inactive or blocked account. |
R002 | Account and identification provided do not coincide. |
R005 | Account does not exist. |
R006 | Invalid account number. |
R009 | Exceeds maximum allowed amount. |
R018 | Payment rejected due to invalid key (payouts). |
R023 | Payment cancelled by the user. |
R026 | Payment rejected due to unavailable bank services. |
R034 | Account closed. |
R085 | Bank processing error (payouts). |
Event
money_movements.status.rejectedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_LocalPayoutCmp",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-07T12:17: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_LocalPayout01",IdiUnique Cobre identifier for this resource. "status": {StatusiLifecycle status object for the resource or movement. "state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "R001",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "Inactive or blocked account."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Local vendor payout"DescriptioniHuman-readable label or note. }, "creator": "cli_psp_cn_co01",CreatoriAPI client id that created this resource. "external_id": "psp_local_payout_001",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "fast_pay",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_PspCopPayout",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_LocalVendor01",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-07-07T12:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-07T12:17: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_LocalPayouLk",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-07T12:15: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_LocalPayout0Lk",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_PspCopPayout",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-07-07T12:15:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-07T12:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_LocalPayout01",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Local vendor payout",DescriptioniHuman-readable label or note. "beneficiary_account_number": "",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "tracking_key": ""Tracking KeyiBre-B tracking key for the payment. } }}On completion the locked funds are sent to the beneficiary. The processing debit remains on the ledger — no compensation credit is posted.
Event
accounts.balance.debitHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_LocalPayouLk",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.debit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-07T12:15: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_LocalPayout0Lk",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_PspCopPayout",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-07-07T12:15:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-07T12:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_LocalPayout01",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Local vendor payout",DescriptioniHuman-readable label or note. "beneficiary_account_number": "",Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. "tracking_key": ""Tracking KeyiBre-B tracking key for the payment. } }}If the movement reaches a terminal failed, rejected, or canceled state, Cobre credits the source Cobre Balance to release the lock (breb_credit for Bre-B, col_cb_credit for bank rails).
Event
accounts.balance.creditHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_LocalPayouCp",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-07T12:17: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_LocalPayout0Cp",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_PspCopPayout",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-07-07T12:17:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-07T12:17:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_LocalPayout01",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Local vendor payout",DescriptioniHuman-readable label or note. "tracking_key": "",Tracking KeyiBre-B tracking key for the payment. "sender_name": "",Sender NameiMetadata field "sender_name" attached to the resource. "sender_id": "",Sender IdiMetadata field "sender_id" attached to the resource. "sender_account_number": ""Sender Account NumberiMetadata field "sender_account_number" attached to the resource. } }}
Step 13 of 19
Local Payout
Reconciliation
Reconcile Local Payout
Match the completion webhook on external_id psp_local_payout_001. Note content.type (fast_pay vs ach) for the rail Cobre selected.
Mapping the webhook payload from an earlier step onto Treasury ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Treasury ledger field | |
content.external_id psp_local_payout_001 |
→ | payout_reference |
content.id mm_LocalPayout01 |
→ | cobre_mm_id |
content.amount 30000000 |
→ | paid_amount_cents |
content.type fast_pay |
→ | payout_rail |
content.status.state completed |
→ | payout_status |
Step 14 of 19
Cross-Border FX
API step
Request COP/USD Quote
Lock a short-lived COP/USD static quote before converting merchant treasury COP to USD. Confirm corridor availability and quote direction with your KAM — quotes expire in ~1 minute.
POST
https://api.cobre.co/v1/fx_quotes
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
Request body
{ "currency_pair": "cop/usd",Currency pairiCobre field at "currency_pair" in this payload. "source_amount": 120000000,Source amount (COP cents)iCobre field at "source_amount" in this payload. "type": "static_quote"Quote typeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins).}Response 201
{ "id": "fxq_PspCn001",IdiUnique Cobre identifier for this resource. "type": "static_quote",Quote typeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "currency_pair": "cop/usd",Currency pairiCobre field at "currency_pair" in this payload. "source_amount": 120000000,Source amount (COP cents)iCobre field at "source_amount" in this payload. "fees_breakdown": {Fees BreakdowniCobre field at "fees_breakdown" in this payload. "spread": 1.2SpreadiCobre field at "fees_breakdown.spread" in this payload. }, "fx_rate": 4000,Fx RateiCobre field at "fx_rate" in this payload. "destination_amount": 30000,Destination AmountiCobre field at "destination_amount" in this payload. "quota_limit": 1000000000,Quota LimitiCobre field at "quota_limit" in this payload. "remaining_quota": 999625000,Remaining QuotaiCobre field at "remaining_quota" in this payload. "created_at": "2026-07-06T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "valid_until": "2026-07-06T14:01:00Z",Valid UntiliCobre field at "valid_until" in this payload. "last_quote": true,Last QuoteiCobre field at "last_quote" in this payload. "off_market": falseOff MarketiCobre field at "off_market" in this payload.}
Step 15 of 19
Cross-Border FX
API step
Execute COP→USD Cross-Border
Convert merchant treasury COP from acc_PspCopPayout to USD on acc_PspUsdGlobal using the locked quote. Reuse the idempotency header on retries (valid 24h).
POST
https://api.cobre.co/v1/cross_border_money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
| Content-Type | application/json |
| idempotency | psp_cbmm_cn001 |
Request body
{ "source_id": "acc_PspCopPayout",COP Payout balanceiCobre id of the source account or counterparty. "destination_id": "acc_PspUsdGlobal",USD GlobaliCobre id of the destination account or counterparty. "forex_quote_id": "fxq_PspCn001",FX Quote IDiCobre field at "forex_quote_id" in this payload. "metadata": {MetadataiCustom key-value metadata attached to the resource. "destination_description": "Merchant CN01 treasury FX"DescriptioniCobre field at "metadata.destination_description" in this payload. }, "external_id": "psp_fx_merchant001"External IDiYour own reference echoed by Cobre for reconciliation.}Response 201
{ "id": "mm_CbmmPspCn001",IdiUnique Cobre identifier for this resource. "creator": "cli_psp_cn_co01",CreatoriAPI client id that created 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. "destination_description": "Merchant CN01 treasury FX",DescriptioniCobre field at "metadata.destination_description" in this payload. "forex_quote_id": "fxq_PspCn001",Forex Quote IdiCobre field at "metadata.forex_quote_id" in this payload. "forex_quote": {Forex QuoteiCobre field at "metadata.forex_quote" in this payload. "type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "currency_pair": "cop/usd",Currency PairiCobre field at "metadata.forex_quote.currency_pair" in this payload. "source_amount": 120000000,Source AmountiCobre field at "metadata.forex_quote.source_amount" in this payload. "fees_breakdown": {Fees BreakdowniCobre field at "metadata.forex_quote.fees_breakdown" in this payload. "spread": 1.2SpreadiCobre field at "metadata.forex_quote.fees_breakdown.spread" in this payload. }, "fx_rate": 4000,Fx RateiCobre field at "metadata.forex_quote.fx_rate" in this payload. "destination_amount": 30000,Destination AmountiCobre field at "metadata.forex_quote.destination_amount" in this payload. "quota_limit": 1000000000,Quota LimitiCobre field at "metadata.forex_quote.quota_limit" in this payload. "remaining_quota": 999625000,Remaining QuotaiCobre field at "metadata.forex_quote.remaining_quota" in this payload. "created_at": "2026-07-06T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "valid_until": "2026-07-06T14:01:00Z",Valid UntiliCobre field at "metadata.forex_quote.valid_until" in this payload. "last_quote": true,Last QuoteiCobre field at "metadata.forex_quote.last_quote" in this payload. "off_market": falseOff MarketiCobre field at "metadata.forex_quote.off_market" in this payload. } }, "external_id": "psp_fx_merchant001",External IDiYour own reference echoed by Cobre for reconciliation. "type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "source_id": "acc_PspCopPayout",COP Payout balanceiCobre id of the source account or counterparty. "destination_id": "acc_PspUsdGlobal",USD GlobaliCobre id of the destination account or counterparty. "currency": "cop/usd",CurrencyiISO currency code (e.g. cop, mxn). "amount": 120000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-06T14:01:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-06T14:01:10Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Cross-border money movement
COP→USD conversion completed — USD is now on acc_PspUsdGlobal. Reconcile this FX leg on your treasury ledger.
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.
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
cross_border_money_movements.status.completedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_CbmmPspCn001Cmp",IdiUnique Cobre identifier for this resource. "event_key": "cross_border_money_movements.status.completed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-06T14:01:45Z",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_CbmmPspCn001",IdiUnique Cobre identifier for this resource. "creator": "cli_psp_cn_co01",CreatoriAPI client id that created 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. "destination_description": "Merchant CN01 treasury FX",Destination DescriptioniMetadata field "destination_description" attached to the resource. "forex_quote_id": "fxq_PspCn001",Forex Quote IdiMetadata field "forex_quote_id" attached to the resource. "forex_quote": {Forex QuoteiMetadata field "forex_quote" attached to the resource. "type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "currency_pair": "cop/usd",Currency PairiMetadata field "forex_quote.currency_pair" attached to the resource. "source_amount": 120000000,Source AmountiMetadata field "forex_quote.source_amount" attached to the resource. "fees_breakdown": {Fees BreakdowniMetadata field "forex_quote.fees_breakdown" attached to the resource. "spread": 1.2SpreadiMetadata field "forex_quote.fees_breakdown.spread" attached to the resource. }, "fx_rate": 4000,Fx RateiMetadata field "forex_quote.fx_rate" attached to the resource. "destination_amount": 30000,Destination AmountiMetadata field "forex_quote.destination_amount" attached to the resource. "quota_limit": 1000000000,Quota LimitiMetadata field "forex_quote.quota_limit" attached to the resource. "remaining_quota": 999625000,Remaining QuotaiMetadata field "forex_quote.remaining_quota" attached to the resource. "created_at": "2026-07-06T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "valid_until": "2026-07-06T14:01:00Z",Valid UntiliMetadata field "forex_quote.valid_until" attached to the resource. "last_quote": true,Last QuoteiMetadata field "forex_quote.last_quote" attached to the resource. "off_market": falseOff MarketiMetadata field "forex_quote.off_market" attached to the resource. } }, "external_id": "psp_fx_merchant001",External IdiYour own reference echoed by Cobre for reconciliation. "type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "source_id": "acc_PspCopPayout",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_PspUsdGlobal",Destination IdiCobre id of the destination account or counterparty. "currency": "cop/usd",CurrencyiISO currency code (e.g. cop, mxn). "amount": 120000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-06T14:01:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-06T14:01:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}Cobre or the rail could not process the movement. Inspect status.code and status.description — common failed codes include:
Possible status codes
F001 | Payment processing failed — please try again. |
F002 | NSF — not sufficient funds in the designated account. |
F003 | R2P payment link expired (payins). |
F004 | Daily transaction amount limit has been reached. |
F005 | Amount exceeds the maximum allowed transaction limit. |
F098 | Could not process the money movement at this time. |
F099 | Could not process the money movement at this time. |
Event
cross_border_money_movements.status.failedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_CbmmPspCn001Cmp",IdiUnique Cobre identifier for this resource. "event_key": "cross_border_money_movements.status.failed",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-06T14:01:45Z",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_CbmmPspCn001",IdiUnique Cobre identifier for this resource. "creator": "cli_psp_cn_co01",CreatoriAPI client id that created 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. "destination_description": "Merchant CN01 treasury FX",Destination DescriptioniMetadata field "destination_description" attached to the resource. "forex_quote_id": "fxq_PspCn001",Forex Quote IdiMetadata field "forex_quote_id" attached to the resource. "forex_quote": {Forex QuoteiMetadata field "forex_quote" attached to the resource. "type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "currency_pair": "cop/usd",Currency PairiMetadata field "forex_quote.currency_pair" attached to the resource. "source_amount": 120000000,Source AmountiMetadata field "forex_quote.source_amount" attached to the resource. "fees_breakdown": {Fees BreakdowniMetadata field "forex_quote.fees_breakdown" attached to the resource. "spread": 1.2SpreadiMetadata field "forex_quote.fees_breakdown.spread" attached to the resource. }, "fx_rate": 4000,Fx RateiMetadata field "forex_quote.fx_rate" attached to the resource. "destination_amount": 30000,Destination AmountiMetadata field "forex_quote.destination_amount" attached to the resource. "quota_limit": 1000000000,Quota LimitiMetadata field "forex_quote.quota_limit" attached to the resource. "remaining_quota": 999625000,Remaining QuotaiMetadata field "forex_quote.remaining_quota" attached to the resource. "created_at": "2026-07-06T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "valid_until": "2026-07-06T14:01:00Z",Valid UntiliMetadata field "forex_quote.valid_until" attached to the resource. "last_quote": true,Last QuoteiMetadata field "forex_quote.last_quote" attached to the resource. "off_market": falseOff MarketiMetadata field "forex_quote.off_market" attached to the resource. } }, "external_id": "psp_fx_merchant001",External IdiYour own reference echoed by Cobre for reconciliation. "type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "source_id": "acc_PspCopPayout",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_PspUsdGlobal",Destination IdiCobre id of the destination account or counterparty. "currency": "cop/usd",CurrencyiISO currency code (e.g. cop, mxn). "amount": 120000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-06T14:01:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-06T14:01:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}The bank or payment network rejected the transaction. Inspect status.code — common rejected codes include:
Possible status codes
R000 | Transaction rejected. |
R001 | Inactive or blocked account. |
R002 | Account and identification provided do not coincide. |
R005 | Account does not exist. |
R006 | Invalid account number. |
R009 | Exceeds maximum allowed amount. |
R018 | Payment rejected due to invalid key (payouts). |
R023 | Payment cancelled by the user. |
R026 | Payment rejected due to unavailable bank services. |
R034 | Account closed. |
R085 | Bank processing error (payouts). |
Event
cross_border_money_movements.status.rejectedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_CbmmPspCn001Cmp",IdiUnique Cobre identifier for this resource. "event_key": "cross_border_money_movements.status.rejected",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-07-06T14:01:45Z",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_CbmmPspCn001",IdiUnique Cobre identifier for this resource. "creator": "cli_psp_cn_co01",CreatoriAPI client id that created this resource. "status": {StatusiLifecycle status object for the resource or movement. "state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "R001",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "Inactive or blocked account."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "destination_description": "Merchant CN01 treasury FX",Destination DescriptioniMetadata field "destination_description" attached to the resource. "forex_quote_id": "fxq_PspCn001",Forex Quote IdiMetadata field "forex_quote_id" attached to the resource. "forex_quote": {Forex QuoteiMetadata field "forex_quote" attached to the resource. "type": "static_quote",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "currency_pair": "cop/usd",Currency PairiMetadata field "forex_quote.currency_pair" attached to the resource. "source_amount": 120000000,Source AmountiMetadata field "forex_quote.source_amount" attached to the resource. "fees_breakdown": {Fees BreakdowniMetadata field "forex_quote.fees_breakdown" attached to the resource. "spread": 1.2SpreadiMetadata field "forex_quote.fees_breakdown.spread" attached to the resource. }, "fx_rate": 4000,Fx RateiMetadata field "forex_quote.fx_rate" attached to the resource. "destination_amount": 30000,Destination AmountiMetadata field "forex_quote.destination_amount" attached to the resource. "quota_limit": 1000000000,Quota LimitiMetadata field "forex_quote.quota_limit" attached to the resource. "remaining_quota": 999625000,Remaining QuotaiMetadata field "forex_quote.remaining_quota" attached to the resource. "created_at": "2026-07-06T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "valid_until": "2026-07-06T14:01:00Z",Valid UntiliMetadata field "forex_quote.valid_until" attached to the resource. "last_quote": true,Last QuoteiMetadata field "forex_quote.last_quote" attached to the resource. "off_market": falseOff MarketiMetadata field "forex_quote.off_market" attached to the resource. } }, "external_id": "psp_fx_merchant001",External IdiYour own reference echoed by Cobre for reconciliation. "type": "cross_border",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "source_id": "acc_PspCopPayout",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_PspUsdGlobal",Destination IdiCobre id of the destination account or counterparty. "currency": "cop/usd",CurrencyiISO currency code (e.g. cop, mxn). "amount": 120000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-06T14:01:10Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-06T14:01:45Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}Documentation for this step
Create a Cross Border Money MovementCreate a Cross-Border Money Movement
Step 16 of 19
Cross-Border FX
Reconciliation
Reconcile Cross-Border FX
Match the Cross-Border completion webhook to your treasury ledger on external_id psp_fx_merchant001. Cross-check COP debit on acc_PspCopPayout and USD credit on acc_PspUsdGlobal.
Mapping the webhook payload from an earlier step onto Treasury ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Treasury ledger field | |
content.external_id psp_fx_merchant001 |
→ | fx_external_id |
content.id mm_CbmmPspCn001 |
→ | cobre_cbmm_id |
content.metadata.forex_quote_id fxq_PspCn001 |
→ | fxq_id |
content.amount 120000000 |
→ | cop_debited_cents COP source amount debited from acc_PspCopPayout (120000000 = $1,200,000.00 COP). |
content.metadata.forex_quote.destination_amount 30000 |
→ | usd_credited_cents USD credited to acc_PspUsdGlobal (30000 = $300.00 USD). |
content.status.state completed |
→ | fx_status |
Step 17 of 19
End-of-Day / D+1 Reconciliation
API step
Daily Balance History (Summarized)
On D+1 (available ~5 hours after midnight), retrieve summarized opening balance, total credits/debits, and end-of-day balance for acc_PspCopPayout. Use balance_date to scope a single business day.
GET
https://api.cobre.co/v1/accounts/acc_PspCopPayoutPayout balanceiPath parameter — Cobre Balance to pull daily balance history for./daily_balance_history?balance_date=2026-07-09Balance dateiBusiness day to reconcile (YYYY-MM-DD). Daily balance objects are generated per calendar day.
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "total_items": 1,Total ItemsiTotal items matching the query across all pages. "total_pages": 1,Total PagesiNumber of pages in this result set. "is_last_page": true,Is Last PageiTrue when this is the final page of results. "page_items": 1,Page ItemsiNumber of items returned on this page. "Daily Balance history List": [Daily Balance history ListiCobre field at "Daily Balance history List" in this payload. { "id": "dbh_PspCnEod01",IdiUnique Cobre identifier for this resource. "offset": "-05:00",OffsetiCobre field at "Daily Balance history List.0.offset" in this payload. "balance_date": "2026-07-09",Balance DateiCobre field at "Daily Balance history List.0.balance_date" in this payload. "initial_balance": "850000000",Initial BalanceiCobre field at "Daily Balance history List.0.initial_balance" in this payload. "total_credits": "50000000",Total CreditsiCobre field at "Daily Balance history List.0.total_credits" in this payload. "total_debits": "320000000",Total DebitsiCobre field at "Daily Balance history List.0.total_debits" in this payload. "end_balance": "580000000",End BalanceiCobre field at "Daily Balance history List.0.end_balance" in this payload. "created_at": "2026-07-10T10:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-10T10:00:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). } ]}Documentation for this step
Obtain Account Daily Balance History
Step 18 of 19
End-of-Day / D+1 Reconciliation
API step
Obtain All Transactions
Pull every transaction across all Cobre Balances for the business day — useful when reconciling platform-wide activity or catching events missed by webhooks.
GET
https://api.cobre.co/v1/transactions?date=2026-07-09Transaction dateiFilter by transaction_date (YYYY-MM-DD).
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "total_items": 2,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": 2,Page ItemsiNumber of items returned on this page. "contents": [ContentsiArray of result objects for this page. { "id": "trx_EodCnCr01",IdiUnique Cobre identifier for this resource. "type": "transfer_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_PspCopPayin",Account IdiCobre Balance account id affected by the event. "amount": 50000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 100000000,Previous BalanceiCobre field at "contents.0.previous_balance" in this payload. "current_balance": 150000000,Current BalanceiCobre field at "contents.0.current_balance" in this payload. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "credit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-07-09T13:10:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-09T13:10:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Inbound merchant collection"DescriptioniHuman-readable label or note. } }, { "id": "trx_EodCnDb01",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_PspCopPayout",Account IdiCobre Balance account id affected by the event. "amount": -120000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 700000000,Previous BalanceiCobre field at "contents.1.previous_balance" in this payload. "current_balance": 580000000,Current BalanceiCobre field at "contents.1.current_balance" in this payload. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "debit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-07-09T16:45:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-09T16:45:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_CbmmPspCn001"Money Movement IdiMoney Movement that generated this balance transaction. } } ]}
Step 19 of 19
End-of-Day / D+1 Reconciliation
API step
Obtain One Account Transactions
Drill into line-level credits and debits on acc_PspCopPayout for the same business day — cross-check against daily balance totals and webhook-driven reconciliation.
GET
https://api.cobre.co/v1/accounts/acc_PspCopPayoutPayout balanceiPath parameter — Cobre Balance whose transactions to list./transactions?date=2026-07-09Transaction dateiFilter by transaction_date (YYYY-MM-DD).
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfcHNwX25fY28wMSJ9.PspCn9xK2vN7cL4wT8aH1gF6yJ0bZ5eQ |
Response 200
{ "total_items": 2,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": 2,Page ItemsiNumber of items returned on this page. "contents": [ContentsiArray of result objects for this page. { "id": "trx_EodCnInt01",IdiUnique Cobre identifier for this resource. "type": "internal_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_PspCopPayout",Account IdiCobre Balance account id affected by the event. "amount": 50000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 530000000,Previous BalanceiCobre field at "contents.0.previous_balance" in this payload. "current_balance": 580000000,Current BalanceiCobre field at "contents.0.current_balance" in this payload. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "credit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-07-09T14:00:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-09T14:00:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Linkage auto-sweep from Payin"DescriptioniHuman-readable label or note. } }, { "id": "trx_EodCnDb01",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_PspCopPayout",Account IdiCobre Balance account id affected by the event. "amount": -120000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 700000000,Previous BalanceiCobre field at "contents.1.previous_balance" in this payload. "current_balance": 580000000,Current BalanceiCobre field at "contents.1.current_balance" in this payload. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "debit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-07-09T16:45:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-09T16:45:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "money_movement_id": "mm_CbmmPspCn001"Money Movement IdiMoney Movement that generated this balance transaction. } } ]}Documentation for this step
Obtain one Account Transactions