Step 1 of 14
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 and attaches it to every later request.
POST
https://api.cobre.co/v1/auth
Headers
| Content-Type | application/json |
Request body
{ "user_id": "cli_psp_co_01",User IDRequirediYour API user identifier issued by Cobre. Format: cli_xxxx. "secret": "sk_live_9Vf2bQ7mR3"SecretRequirediThe secret from your API key. Treat it like a password.}Response 201
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfc3Rha2VfY29fMDEifQ.Qm9wZT3kR7nXcV2aL9pY8wH4tJ1gF6dZ",Access TokeniShort-lived bearer token. Attach as Authorization: Bearer on later calls. "type": "Bearer",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "expiration_time": 1200Expiration TimeiToken lifetime in seconds.}
Step 2 of 14
Configuration
API step
Subscribe to Webhook Events
Subscribe to the events that drive the wallet: Cobre Key registration, balance credits (breb_credit deposits to a Cobre Key), and money-movement status (Direct Link deposits and payouts). Event-driven means no polling.
POST
https://api.cobre.co/v1/subscriptions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfc3Rha2VfY29fMDEifQ.Qm9wZT3kR7nXcV2aL9pY8wH4tJ1gF6dZ |
| Content-Type | application/json |
Request body
{ "url": "https://wallet.example.com/webhooks/cobre",Notification URLRequirediYour HTTPS endpoint that receives Cobre webhook POSTs. "description": "Wallet lifecycle",DescriptioniA label to identify this subscription. "events": [EventsiList of webhook event types this subscription listens to. "cobre_keys.status.registered", "accounts.balance.credit", "accounts.balance.debit", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected" ], "event_signature_key": "WHsig_PspDemo_77"Signature KeyRequirediA secret you provide; Cobre HMAC-signs every notification with it so you can verify authenticity.}Response 201
{ "id": "sub_PspDemo01",IdiUnique Cobre identifier for this resource. "url": "https://wallet.example.com/webhooks/cobre",Notification URLRequirediYour HTTPS endpoint that receives Cobre webhook POSTs. "description": "Wallet lifecycle",DescriptioniA label to identify this subscription. "events": [EventsiList of webhook event types this subscription listens to. "cobre_keys.status.registered", "accounts.balance.credit", "accounts.balance.debit", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected" ], "event_signature_key": "******_77",Signature KeyRequirediA secret you provide; Cobre HMAC-signs every notification with it so you can verify authenticity. "created_at": "2026-06-26T12:00:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 3 of 14
User Onboarding
API step
Create the User's Cobre Balance
The platform runs a one-Cobre-Balance-per-user model so each player's funds and history are visible and reconcilable in Cobre. At registration, create a COP Cobre Balance and keep the returned account_id mapped to the user.
POST
https://api.cobre.co/v1/accounts
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfc3Rha2VfY29fMDEifQ.Qm9wZT3kR7nXcV2aL9pY8wH4tJ1gF6dZ |
| Content-Type | application/json |
Request body
{ "provider_id": "pr_col_cobre",ProviderRequirediThe Colombia Cobre Balance provider. "action": "create",ActionRequiredicreate = open a new Cobre Balance. "tags": [TagsiCobre field at "tags" in this payload. "psp_user_12345" ], "alias": "psp_user_12345"AliasiDisplay name that helps identify it and clarify its purpose.}Response 201
{ "id": "acc_PspUser12345",IdiUnique Cobre identifier for this resource. "provider_id": "pr_col_cobre",ProviderRequirediThe Colombia Cobre Balance provider. "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_user_12345",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "cobre_tag": "@cibaa77012",Cobre TagiCobre Balance tag identifying the destination account. "available_services": [Available ServicesiCobre field at "metadata.available_services" in this payload. "account_balance", "mm_push_from_account", "account_transactions" ], "primary_account": ""Primary AccountiCobre field at "metadata.primary_account" in this payload. }, "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. "psp_user_12345" ], "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "created_at": "2026-06-26T12:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 4 of 14
User Onboarding
API step
Create the User's Cobre Key
Create one personalized Cobre Key (Static Key flow) on the user's Cobre Balance — their always-on deposit identifier. Creation is asynchronous: the response is processing with an empty key_value; the value arrives on the cobre_keys.status.registered webhook.
POST
https://api.cobre.co/v1/accounts/acc_PspUser12345/keys
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfc3Rha2VfY29fMDEifQ.Qm9wZT3kR7nXcV2aL9pY8wH4tJ1gF6dZ |
| Content-Type | application/json |
Request body
{ "alias": "Player deposit key",AliasiDisplay name that helps identify it and clarify its purpose. "key_config": "open_input",Key ConfigRequirediopen_input = a custom alias (5–20 chars). id = derived from the user's ID number. "open_input": "Player1234",Custom AliasRequirediThe custom Bre-B handle the user will deposit to. "holder": {HolderiCobre field at "holder" in this payload. "full_name": "Juliana Restrepo",Holder NameRequirediLegal name of the account holder (the user). "id_number": "1019123456",Holder IDRequirediThe user's identification number. "id_type": "cc"ID TypeRequirediIdentification type. }}Response 201
{ "id": "key_Psp8Hd2Qe1Lv",IdiUnique Cobre identifier for this resource. "key_value": "",Key ValueiBre-B key value (e.g. @merchant123). "source_id": "acc_PspUser12345",Source IdiCobre id of the source account or counterparty. "alias": "Player deposit key",AliasiDisplay name that helps identify it and clarify its purpose. "connectivity": {ConnectivityiConnection/registration status for keys or accounts. "status": "processing",StatusiLifecycle status object for the resource or movement. "description": ""DescriptioniHuman-readable label or note. }, "previous_action": {Previous ActioniCobre field at "previous_action" in this payload. "action_requested": "create",Action RequestediCobre field at "previous_action.action_requested" in this payload. "action_code": "",Action CodeiCobre field at "previous_action.action_code" in this payload. "action_description": ""Action DescriptioniCobre field at "previous_action.action_description" in this payload. }, "created_at": "2026-06-26T12:06:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:06:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook delivered
cobre_keys.status.registeredWhen Bre-B registration completes, Cobre delivers the key's final key_value. Store it mapped to the user and show it as their deposit handle.
Headers
| Content-Type | application/json |
Payload
{ "id": "ev_KeyPspRegistered",IdiUnique Cobre identifier for this resource. "event_key": "cobre_keys.status.registered",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-06-26T12:08:30Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "key_Psp8Hd2Qe1Lv",IdiUnique Cobre identifier for this resource. "key_value": "@Player1234",Key ValueiBre-B key value (e.g. @merchant123). "source_id": "acc_PspUser12345",Source IdiCobre id of the source account or counterparty. "alias": "Player deposit key",AliasiDisplay name that helps identify it and clarify its purpose. "connectivity": {ConnectivityiConnection/registration status for keys or accounts. "status": "registered",StatusiLifecycle status object for the resource or movement. "description": ""DescriptioniHuman-readable label or note. }, "previous_action": {Previous ActioniCobre field at "content.previous_action" in this payload. "action_requested": "create",Action RequestediCobre field at "content.previous_action.action_requested" in this payload. "action_code": "",Action CodeiCobre field at "content.previous_action.action_code" in this payload. "action_description": ""Action DescriptioniCobre field at "content.previous_action.action_description" in this payload. }, "created_at": "2026-06-26T12:06:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T12:08:30Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}
Step 5 of 14
Deposits
API step
Deposit via Cobre Key
The player sends money from any bank app to their personal Cobre Key @Player1234. Bre-B settles in real time and Cobre credits their Cobre Balance with a breb_credit transaction — there is no Money Movement object. Your backend reads it from GET /accounts/{id}/transactions and from the accounts.balance.credit webhook.
GET
https://api.cobre.co/v1/accounts/acc_PspUser12345/transactions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfc3Rha2VfY29fMDEifQ.Qm9wZT3kR7nXcV2aL9pY8wH4tJ1gF6dZ |
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_PspDep77012",Transaction IDiThe Cobre transaction id — your reconciliation key for Cobre Key deposits (no mm_id exists). "type": "breb_credit",Transaction typeiCobre Balance transaction type for an incoming Bre-B transfer to a Cobre Key (breb_credit per Cobre Keys docs). "account_id": "acc_PspUser12345",Account IdiCobre Balance account id affected by the event. "amount": 5000000,Amount creditediCredited amount in cents. 5000000 = $50,000.00 COP. "previous_balance": 0,Previous BalanceiCobre field at "contents.0.previous_balance" in this payload. "current_balance": 5000000,Current BalanceiCobre field at "contents.0.current_balance" in this payload. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "credit",Directionicredit = funds came in. "transaction_date": "2026-06-26T13:10:21Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T13:10:22Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "sender_account_number": "987654321",Sender Account NumberiMetadata field "sender_account_number" attached to the resource. "sender_account_type": "ch",Sender Account TypeiMetadata field "sender_account_type" attached to the resource. "sender_bank_code": "1007",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "sender_id": "1234567890",Sender IdiMetadata field "sender_id" attached to the resource. "sender_id_type": "cc",Sender Id TypeiMetadata field "sender_id_type" attached to the resource. "sender_name": "Juan Perez",Sender NameiMetadata field "sender_name" attached to the resource. "key_value": "@Player1234",Cobre KeyiThe player's Cobre Key that received the deposit (metadata.key_value in breb_credit notifications). "description": "Bre-B deposit",DescriptioniHuman-readable label or note. "mm_external_id": ""Mm External IdiMetadata field "mm_external_id" attached to the resource. } } ]}Webhook delivered
accounts.balance.creditFires the instant a Bre-B transfer credits the player's Cobre Balance via their Cobre Key. Identify the user by account_id and metadata.key_value, then top up their in-game balance — no Money Movement is involved.
Headers
| Content-Type | application/json |
Payload
{ "id": "ev_PspBalCredit",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-26T13:10:22Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "trx_PspDep77012",IdiUnique Cobre identifier for this resource. "type": "breb_credit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "amount": 5000000,AmountiAmount in cents — the last two digits are decimals. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "date": "2026-06-26T13:10:21Z",DateiTimestamp when the balance transaction was posted (ISO 8601, UTC) — used in accounts.balance.* webhook notifications. "metadata": {MetadataiCustom key-value metadata attached to the resource. "sender_id_type": "cc",Sender Id TypeiMetadata field "sender_id_type" attached to the resource. "sender_account_type": "ch",Sender Account TypeiMetadata field "sender_account_type" attached to the resource. "sender_bank_code": "1007",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "sender_account_number": "987654321",Sender Account NumberiMetadata field "sender_account_number" attached to the resource. "description": "Bre-B deposit",DescriptioniHuman-readable label or note. "sender_name": "Juan Perez",Sender NameiMetadata field "sender_name" attached to the resource. "mm_external_id": "",Mm External IdiMetadata field "mm_external_id" attached to the resource. "key_value": "@Player1234",Key ValueiBre-B key value (e.g. @merchant123). "sender_id": "1234567890"Sender IdiMetadata field "sender_id" attached to the resource. }, "account_id": "acc_PspUser12345",Account IdiCobre Balance account id affected by the event. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 5000000,Current BalanceiCobre field at "content.current_balance" in this payload. "credit_debit_type": "credit"Credit Debit Typeicredit = funds in; debit = funds out. }}Documentation for this step
Obtain one Account TransactionsStatic Bre-B KeysAccount Balance CreditNotifications & Subscriptions
Step 6 of 14
Deposits
Reconciliation
Reconcile the Static-Key Deposit
Static-key deposits have no Money Movement, so reconciliation is transaction-level: the account_id maps to the user, and the transaction id is your canonical reference. No API call — you read the transaction and update your ledger.
Mapping the API response from an earlier step onto Platform Wallet Ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Platform Wallet Ledger field | |
contents.0.account_id acc_PspUser12345 |
→ | user_account_ref account_id -> user_id via the onboarding mapping. |
contents.0.id trx_PspDep77012 |
→ | cobre_transaction_id Canonical reference for Cobre Key deposits (no mm_id). |
contents.0.amount 5000000 |
→ | deposit_amount_cents |
contents.0.metadata.key_value @Player1234 |
→ | deposit_key_value Cobre Key that received the deposit — maps to the user's registered key. |
contents.0.transaction_date 2026-06-26T13:10:21Z |
→ | deposited_at |
Step 7 of 14
Deposits
API step
Register the Payer for Direct Link
For a web deposit via PSE, register the player as an r2p counterparty (the payer). The email is used for the PSE bank-authentication redirect. Counterparties are reusable across sessions.
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfc3Rha2VfY29fMDEifQ.Qm9wZT3kR7nXcV2aL9pY8wH4tJ1gF6dZ |
| Content-Type | application/json |
Request body
{ "geo": "col",GeographyRequiredicol = Colombia. "type": "r2p",TypeRequiredir2p = Direct Link payer (PSE / Nequi / Bancolombia / Bre-B QR). "alias": "PSE payer - psp_user_12345",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 payer's full name. "counterparty_email": "player@example.co",EmailRequirediUsed for the PSE bank authentication redirect; must be valid or the payin fails. "counterparty_id_type": "cc",ID TypeRequirediIdentification type. "counterparty_id_number": "5334623427",ID NumberRequirediThe payer's identification number. "counterparty_phone": "+573123927834"PhoneRequirediPayer phone with country code. }}Response 201
{ "id": "cp_PayerPSE77012",IdiUnique Cobre identifier for this resource. "geo": "col",GeographyRequiredicol = Colombia. "type": "r2p",TypeRequiredir2p = Direct Link payer (PSE / Nequi / Bancolombia / Bre-B QR). "alias": "PSE payer - psp_user_12345",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "counterparty_email": "player@example.co",EmailRequirediUsed for the PSE bank authentication redirect; must be valid or the payin fails. "counterparty_fullname": "Juliana Restrepo",Full NameRequirediThe payer's full name. "counterparty_id_number": "5334623427",ID NumberRequirediThe payer's identification number. "counterparty_id_type": "cc",ID TypeRequirediIdentification type. "counterparty_phone": "+573123927834"PhoneRequirediPayer phone with country code. }, "created_at": "2026-06-26T13:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T13:20:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 8 of 14
Deposits
API step
Deposit via PSE (Direct Link)
On the player web wallet the player picks PSE and an amount. The platform creates a Direct Link Money Movement (source = the payer counterparty, destination = the player's Cobre Balance) and redirects them to the PSE payment link returned in the response.
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfc3Rha2VfY29fMDEifQ.Qm9wZT3kR7nXcV2aL9pY8wH4tJ1gF6dZ |
| Content-Type | application/json |
| idempotency | psp-dep-PSE-77012-001 |
Request body
{ "amount": 3000000,Amount (cents)RequirediDeposit amount in cents. 3000000 = $30,000.00 COP. "source_id": "cp_PayerPSE77012",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_PspUser12345",Destination IdiCobre id of the destination account or counterparty. "metadata": {MetadataiCustom key-value metadata attached to the resource. "r2p_rail": "pse",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "financial_institution_code": "1070",Your bankRequirediThe PSE financial-institution code of the player's bank. "description_to_payer": "Platform deposit",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "description_to_payee": "Platform deposit",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "redirect_url": "https://wallet.example.com/deposit/return"Redirect UrliOn a Checkout-created Money Movement this is the hosted checkout_url (links.cobre.co), not the merchant return URL from POST /checkouts. }, "external_id": "psp-dep-PSE-77012"External IdiYour own reference echoed by Cobre for reconciliation.}Response 201
{ "id": "mm_PseDep77012",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. "financial_institution_code": "1070",Your bankRequirediThe PSE financial-institution code of the player's bank. "payment_link": "https://registro.pse.com.co/PSENF/index.html?enc=psp77012",Payment LinkiRail-hosted URL the payer used to complete the payment (e.g. PSE). "description_to_payee": "Platform deposit",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "description_to_payer": "Platform deposit",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "r2p_rail": "pse",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "redirect_url": "https://wallet.example.com/deposit/return"Redirect UrliOn a Checkout-created Money Movement this is the hosted checkout_url (links.cobre.co), not the merchant return URL from POST /checkouts. }, "creator": "cli_psp_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": "psp-dep-PSE-77012",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. "type": "r2p_pse",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_PayerPSE77012",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_PspUser12345",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 3000000,Amount (cents)RequirediDeposit amount in cents. 3000000 = $30,000.00 COP. "created_at": "2026-06-26T13:22:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T13:22:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
After the player authenticates at their bank and PSE settles, Cobre delivers this. Credit the player's in-game balance and confirm the deposit by external_id. Cobre also credits the player's Cobre Balance (r2p_credit) — see the Transaction tab.
Handle each terminal state in your webhook listener. Status codes reference the <a href="https://docs.cobre.com/money-movement-statuses-2032280m0" target="_blank" rel="noopener">Money Movement Statuses</a> guide. Cobre Balance transactions are covered in the <b>Transaction</b> tab.
Funds settled successfully. No error code is set (NA in the status guide). Use this webhook to mark the payment as paid in your system.
Event
money_movements.status.completedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_PseDep77012Cmp",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-26T13:24:35Z",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_PseDep77012",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. "financial_institution_code": "1070",Financial Institution CodeiBank code the payer selected (PSE). See Colombian bank codes. "payment_link": "https://registro.pse.com.co/PSENF/index.html?enc=psp77012",Payment LinkiRail-hosted URL the payer used to complete the payment (e.g. PSE). "description_to_payee": "Platform deposit",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "description_to_payer": "Platform deposit",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "r2p_rail": "pse",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "redirect_url": "https://wallet.example.com/deposit/return"Redirect UrliOn a Checkout-created Money Movement this is the hosted checkout_url (links.cobre.co), not the merchant return URL from POST /checkouts. }, "creator": "cli_psp_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": "psp-dep-PSE-77012",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. "type": "r2p_pse",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_PayerPSE77012",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_PspUser12345",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 3000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T13:22:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T13:24:35Z"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_PseDep77012Cmp",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-26T13:24:35Z",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_PseDep77012",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. "financial_institution_code": "1070",Financial Institution CodeiBank code the payer selected (PSE). See Colombian bank codes. "payment_link": "https://registro.pse.com.co/PSENF/index.html?enc=psp77012",Payment LinkiRail-hosted URL the payer used to complete the payment (e.g. PSE). "description_to_payee": "Platform deposit",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "description_to_payer": "Platform deposit",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "r2p_rail": "pse",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "redirect_url": "https://wallet.example.com/deposit/return"Redirect UrliOn a Checkout-created Money Movement this is the hosted checkout_url (links.cobre.co), not the merchant return URL from POST /checkouts. }, "creator": "cli_psp_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": "psp-dep-PSE-77012",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. "type": "r2p_pse",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_PayerPSE77012",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_PspUser12345",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 3000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T13:22:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T13:24:35Z"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_PseDep77012Cmp",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-26T13:24:35Z",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_PseDep77012",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. "financial_institution_code": "1070",Financial Institution CodeiBank code the payer selected (PSE). See Colombian bank codes. "payment_link": "https://registro.pse.com.co/PSENF/index.html?enc=psp77012",Payment LinkiRail-hosted URL the payer used to complete the payment (e.g. PSE). "description_to_payee": "Platform deposit",Description To PayeeiDescription that appears on the credit in your Cobre Balance. "description_to_payer": "Platform deposit",Description To PayeriPayer-facing description. On Checkout this is checkout_item. "r2p_rail": "pse",R2p RailiRequest-to-Pay rail the payer chose (pse, nequi, bancolombia, breb). "redirect_url": "https://wallet.example.com/deposit/return"Redirect UrliOn a Checkout-created Money Movement this is the hosted checkout_url (links.cobre.co), not the merchant return URL from POST /checkouts. }, "creator": "cli_psp_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": "psp-dep-PSE-77012",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. "type": "r2p_pse",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "cp_PayerPSE77012",Source IdiCobre id of the source account or counterparty. "destination_id": "acc_PspUser12345",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 3000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T13:22:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T13:24:35Z"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_PseDep7701Cr",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-26T13:24:35Z",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_PseDep77012Cr",IdiUnique Cobre identifier for this resource. "type": "r2p_credit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "account_id": "acc_PspUser12345",Account IdiCobre Balance account id affected by the event. "amount": 3000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 3000000,Current BalanceiCobre field at "content.current_balance" in this payload. "currency": "COP",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "credit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-06-26T13:24:35Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T13:24:35Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "sender_bank_code": "1070",Sender Bank CodeiMetadata field "sender_bank_code" attached to the resource. "money_movement_id": "mm_PseDep77012",Money Movement IdiMoney Movement that generated this balance transaction. "description": "Platform deposit",DescriptioniHuman-readable label or note. "sender_name": "",Sender NameiMetadata field "sender_name" attached to the resource. "r2p_method": "pse",R2p MethodiR2P channel for r2p_credit transactions (e.g. pse). "tracking_key": "",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "sender_id": ""Sender IdiMetadata field "sender_id" attached to the resource. } }}
Step 9 of 14
Withdrawals
API step
Verify the Withdrawal Bre-B Key
Before paying out, confirm the player's withdrawal Bre-B key belongs to them. The col_key_ownership_1 model checks the key against the holder's ID in Colombia's directory.
POST
https://api.cobre.co/v1/account_verifications
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfc3Rha2VfY29fMDEifQ.Qm9wZT3kR7nXcV2aL9pY8wH4tJ1gF6dZ |
| Content-Type | application/json |
Request body
{ "model": "col_key_ownership_1",ModelRequiredicol_key_ownership_1 = confirm the key belongs to the declared ID. "verification_request": {Verification RequestiInput fields sent to the verification model. "key_value": "@PlayerPay99",Bre-B keyRequirediThe player's withdrawal Bre-B key. "account_holder_id_number": "5334623427"Holder IDRequirediThe player's identification number; must match the key owner. }, "external_id": "psp-wd-77012-verify"External IDiYour reference for this verification.}Response 201
{ "id": "av_Psp77012",IdiUnique Cobre identifier for this resource. "creator_id": "cli_psp_co_01",Creator IdiCobre field at "creator_id" in this payload. "model": "col_key_ownership_1",ModelRequiredicol_key_ownership_1 = confirm the key belongs to the declared ID. "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "verification_request": {Verification RequestiInput fields sent to the verification model. "key_value": "@PlayerPay99",Bre-B keyRequirediThe player's withdrawal Bre-B key. "account_holder_id_number": "5334623427"Holder IDRequirediThe player's identification number; must match the key owner. }, "status": {StatusiLifecycle status object for the resource or movement. "state": "processing",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "",CodeiProvider or Cobre status code when the state is failed or rejected. "description": ""DescriptioniHuman-readable detail for the current status. }, "external_id": "psp-wd-77012-verify",External IDiYour reference for this verification. "created_at": "2026-06-26T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T14:00:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 10 of 14
Withdrawals
API step
Retrieve Beneficiary Key Verification Result
Poll the Account Verification by id until status.state is completed. Continue with the payout only when verification_response.verification_result is matched; route unmatched or failed results to manual review.
GET
https://api.cobre.co/v1/account_verifications/av_Psp77012
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfc3Rha2VfY29fMDEifQ.Qm9wZT3kR7nXcV2aL9pY8wH4tJ1gF6dZ |
Response 200
{ "id": "av_Psp77012",Verification IDRequirediThe av_… identifier returned by the create response. "creator_id": "cli_psp_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": "@PlayerPay99",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": "psp-wd-77012-verify",External IdiYour own reference echoed by Cobre for reconciliation. "created_at": "2026-06-26T14:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T14:00:00Z",Updated AtiTimestamp of the last update (ISO 8601, UTC). "verification_response": {Verification ResponseiResult returned by the verification model. "verification_result": "matched"Ownership resultRequiredimatched confirms the key ownership check; unmatched or failed blocks the payout. }}
Step 11 of 14
Withdrawals
API step
Register the Payout Counterparty
Register the verified Bre-B key as a breb_key counterparty; this is the destination of the withdrawal Money Movement.
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfc3Rha2VfY29fMDEifQ.Qm9wZT3kR7nXcV2aL9pY8wH4tJ1gF6dZ |
| Content-Type | application/json |
Request body
{ "geo": "col",GeographyRequiredicol = Colombia. "type": "breb_key",TypeRequiredibreb_key routes a payout to a Bre-B key. "alias": "Payout - psp_user_12345",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "key_value": "@PlayerPay99",Bre-B keyRequirediThe verified withdrawal key. "counterparty_email": "player@example.co"EmailiPlayer email. }}Response 201
{ "id": "cp_Payout77012",IdiUnique Cobre identifier for this resource. "geo": "col",GeographyRequiredicol = Colombia. "type": "breb_key",TypeRequiredibreb_key routes a payout to a Bre-B key. "alias": "Payout - psp_user_12345",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "key_value": "@PlayerPay99",Bre-B keyRequirediThe verified withdrawal key. "key_type": "alphanumeric",Key TypeiCobre field at "metadata.key_type" in this payload. "counterparty_email": "player@example.co"EmailiPlayer email. }, "created_at": "2026-06-26T14:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T14:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 12 of 14
Withdrawals
API step
Withdraw via Bre-B
The player requests a cash-out to their Bre-B key. The platform creates a payout Money Movement from the player's Cobre Balance (checker_approval false — instant withdrawal). For maker–checker payouts, set checker_approval true per the Money Movements Approval guide. Bre-B settles in real time, 24/7.
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfc3Rha2VfY29fMDEifQ.Qm9wZT3kR7nXcV2aL9pY8wH4tJ1gF6dZ |
| Content-Type | application/json |
| idempotency | psp-wd-77012-001 |
Request body
{ "amount": 2000000,Amount (cents)RequirediWithdrawal amount in cents. 2000000 = $20,000.00 COP. "source_id": "acc_PspUser12345",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_Payout77012",Destination IdiCobre id of the destination account or counterparty. "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Platform withdrawal"NoteiDescription carried on the Money Movement. }, "external_id": "psp-wd-77012"External IdiYour own reference echoed by Cobre for reconciliation.}Response 201
{ "id": "mm_Wd77012Lc",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": "Platform withdrawal"NoteiDescription carried on the Money Movement. }, "creator": "cli_psp_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": "psp-wd-77012",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_PspUser12345",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_Payout77012",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 2000000,Amount (cents)RequirediWithdrawal amount in cents. 2000000 = $20,000.00 COP. "created_at": "2026-06-26T14:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T14:10:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
When the Bre-B payout settles, Cobre delivers this. Debit the player's in-game balance and mark the withdrawal paid by external_id. Funds were locked with a breb_debit during processing — a failed/rejected/canceled payout would post a breb_credit compensation credit (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_Wd77012Cmp",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-26T14:10: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_Wd77012Lc",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": "Platform withdrawal",DescriptioniHuman-readable label or note. "tracking_key": "77012481001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "key_value": "@PlayerPay99",Key ValueiBre-B key value (e.g. @merchant123). "beneficiary_account_number": "@PlayerPay99"Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. }, "creator": "cli_psp_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": "psp-wd-77012",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_PspUser12345",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_Payout77012",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 2000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T14:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T14:10: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 |
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_Wd77012Cmp",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-26T14:10: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_Wd77012Lc",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": "Platform withdrawal",DescriptioniHuman-readable label or note. "tracking_key": "77012481001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "key_value": "@PlayerPay99",Key ValueiBre-B key value (e.g. @merchant123). "beneficiary_account_number": "@PlayerPay99"Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. }, "creator": "cli_psp_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": "psp-wd-77012",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_PspUser12345",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_Payout77012",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 2000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T14:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T14:10: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 |
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_Wd77012Cmp",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-26T14:10: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_Wd77012Lc",IdiUnique Cobre identifier for this resource. "status": {StatusiLifecycle status object for the resource or movement. "state": "rejected",StateiCurrent lifecycle state (e.g. completed, failed, rejected). "code": "R018",CodeiProvider or Cobre status code when the state is failed or rejected. "description": "Payment rejected due invalid key."DescriptioniHuman-readable label or note. }, "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Platform withdrawal",DescriptioniHuman-readable label or note. "tracking_key": "77012481001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "key_value": "@PlayerPay99",Key ValueiBre-B key value (e.g. @merchant123). "beneficiary_account_number": "@PlayerPay99"Beneficiary Account NumberiMetadata field "beneficiary_account_number" attached to the resource. }, "creator": "cli_psp_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": "psp-wd-77012",External IdiYour own reference echoed by Cobre for reconciliation. "checker_approval": false,Checker ApprovaliWhen true, Cobre pauses at pending_approval and locks source funds until an approval/denial decision via Money Movement Approvals API. "mm_approval_id": "",Mm Approval IdiMoney Movement Approval id (mma_…) when checker_approval is true — used for the decision endpoint. "type": "breb",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "col",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_PspUser12345",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_Payout77012",Destination IdiCobre id of the destination account or counterparty. "currency": "cop",CurrencyiISO currency code (e.g. cop, mxn). "amount": 2000000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-26T14:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-26T14:10:48Z"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_Wd77012LcLk",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-26T14:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "trx_Wd77012LcLk",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_PspUser12345",Account IdiCobre Balance account id affected by the event. "amount": -2000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 7000000,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-26T14:10:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T14:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "beneficiary_account_number": "@PlayerPay99",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": "Platform withdrawal",DescriptioniHuman-readable label or note. "money_movement_id": "mm_Wd77012Lc",Money Movement IdiMoney Movement that generated this balance transaction. "tracking_key": "77012481001"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_Wd77012LcLk",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-26T14:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "content": {ContentiEvent-specific payload — same layout as the GET response for that resource. "id": "trx_Wd77012LcLk",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_PspUser12345",Account IdiCobre Balance account id affected by the event. "amount": -2000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 7000000,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-26T14:10:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T14:10:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "beneficiary_account_number": "@PlayerPay99",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": "Platform withdrawal",DescriptioniHuman-readable label or note. "money_movement_id": "mm_Wd77012Lc",Money Movement IdiMoney Movement that generated this balance transaction. "tracking_key": "77012481001"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_Wd77012LcCp",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-26T14:10: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_Wd77012LcCp",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_PspUser12345",Account IdiCobre Balance account id affected by the event. "amount": 2000000,AmountiAmount in cents — the last two digits are decimals. "previous_balance": 0,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 2000000,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-26T14:10:48Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-06-26T14:10:48Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Platform withdrawal",DescriptioniHuman-readable label or note. "money_movement_id": "mm_Wd77012Lc",Money Movement IdiMoney Movement that generated this balance transaction. "tracking_key": "77012481001"Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). } }}Documentation for this step
Create a Money MovementMoney Movements ApprovalBre-B PayoutsMoney Movement Statuses
Step 13 of 14
Reconciliation
API step
Generate the Cobre Balance Statement
Generate a Cobre Balance Statement for the user's account to reconcile every credit and debit — Cobre Key deposits, Direct Link deposits, and payouts — against your wallet ledger in one file.
POST
https://api.cobre.co/v1/reports
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfc3Rha2VfY29fMDEifQ.Qm9wZT3kR7nXcV2aL9pY8wH4tJ1gF6dZ |
| Content-Type | application/json |
Request body
{ "resource": "accounts",ResourceRequirediaccounts = account statement. "layout": "cobre_balance_statements_v1",LayoutRequirediStatement layout. "metadata": {MetadataiCustom key-value metadata attached to the resource. "account_id": "acc_PspUser12345",AccountRequirediThe user's Cobre Balance. "statement_date": "2026-06"PeriodRequirediPeriod (YYYY-MM). }}Response 201
{ "id": "repo_Psp77012",IdiUnique Cobre identifier for this resource. "resource": "accounts",ResourceRequirediaccounts = account statement. "start_date": "2026-06-01T00:00:00Z",Start DateiCobre field at "start_date" in this payload. "end_date": "2026-06-30T23:59:59Z",End DateiCobre field at "end_date" in this payload. "file_name": "2026-06_accounts_repo_Psp77012_acc_PspUser12345",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_PspUser12345",AccountRequirediThe user's Cobre Balance. "statement_date": "2026-06"PeriodRequirediPeriod (YYYY-MM). }, "sensitive_data": false,Sensitive DataiCobre field at "sensitive_data" in this payload. "requested_at": "2026-07-01T00:00:01Z",Requested AtiCobre field at "requested_at" in this payload. "created_at": "2026-07-01T00:01:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 14 of 14
Reconciliation
Reconciliation
Reconcile to the Wallet Ledger
The close: map the statement onto your wallet ledger. Combined with the per-deposit transaction reconciliation and the per-Money-Movement webhooks, every credit and debit is accounted for.
Mapping the Cobre report from an earlier step onto Platform Wallet Ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Platform Wallet Ledger field | |
id repo_Psp77012 |
→ | statement_reference |
file_name 2026-06_accounts_repo_Psp77012_acc_PspUser12345 |
→ | statement_file |
metadata.account_id acc_PspUser12345 |
→ | wallet_account account_id -> user_id via the onboarding mapping. |
end_date 2026-06-30T23:59:59Z |
→ | period_close_date |