Step 1 of 5
Configuration
API step
Authenticate
Exchange API credentials for a short-lived Bearer token (~20 minutes). Reuse the same token string on every later call in this flow.
POST
https://api.cobre.co/v1/auth
Headers
| Content-Type | application/json |
Request body
{ "user_id": "cli_demo_co_statickey01",User IDRequirediAPI user id issued by Cobre (cli_…). "secret": "sk_live_CoSk4jN7pQ2v"SecretRequirediAPI secret from key creation — treat like a password.}Response 201
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19zdGF0aWNrZXkwMSJ9.CoSk9xM3nR8yQ1lTd7vBw2aF5cP0eH4tJ6gZ",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 5
Configuration
API step
Subscribe to Payin Events
Register webhooks for the Cobre Key lifecycle and Cobre Balance credits. Static Bre-B Key payins are passive — no Money Movement is created. Subscribe to cobre_keys.status.registered/failed and accounts.balance.credit (breb_credit on arrival). Verify deliveries with HMAC-SHA256.
POST
https://api.cobre.co/v1/subscriptions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19zdGF0aWNrZXkwMSJ9.CoSk9xM3nR8yQ1lTd7vBw2aF5cP0eH4tJ6gZ |
| Content-Type | application/json |
Request body
{ "url": "https://yourplatform.co/webhooks/cobre",Notification URLRequirediHTTPS endpoint that receives Cobre POST notifications. "description": "Static Bre-B Key payin lifecycle",DescriptioniLabel for this subscription in the Cobre portal. "events": [EventsiList of webhook event types this subscription listens to. "cobre_keys.status.registered", "cobre_keys.status.failed", "accounts.balance.credit" ], "event_signature_key": "WHsk9xZ"Signature keyRequirediSecret you provide; Cobre HMAC-signs each delivery.}Response 201
{ "id": "sub_StaticKeyPayin01",IdiUnique Cobre identifier for this resource. "url": "https://yourplatform.co/webhooks/cobre",Notification URLRequirediHTTPS endpoint that receives Cobre POST notifications. "description": "Static Bre-B Key payin lifecycle",DescriptioniLabel for this subscription in the Cobre portal. "events": [EventsiList of webhook event types this subscription listens to. "cobre_keys.status.registered", "cobre_keys.status.failed", "accounts.balance.credit" ], "event_signature_key": "******9xZ",Signature keyRequirediSecret you provide; Cobre HMAC-signs each delivery. "created_at": "2026-08-19T09:00:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 3 of 5
Static Key Payin
API step
Create the Static Bre-B Key
Register a static Bre-B key on your COP Cobre Balance — a persistent, reusable identifier payers can send funds to. Creation is asynchronous: do not publish the key to payers until cobre_keys.status.registered arrives with the final key_value. Use key_config open_input to choose your own value, or random/name/id for a Cobre-generated one.
POST
https://api.cobre.co/v1/accounts/acc_StaticKeyCop01COP Cobre BalanceRequirediPath parameter — the balance the static key will credit./keys
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19zdGF0aWNrZXkwMSJ9.CoSk9xM3nR8yQ1lTd7vBw2aF5cP0eH4tJ6gZ |
| Content-Type | application/json |
Request body
{ "alias": "Platform collection key",Key aliasiDisplay name that helps identify it and clarify its purpose. "key_config": "open_input",Key configRequirediopen_input lets you supply your own alphanumeric value. "open_input": "platformpayin001"Custom key valueRequirediAlphanumeric value used to name the key — required only when key_config is open_input.}Response 201
{ "id": "key_StaticPayin001",IdiUnique Cobre identifier for this resource. "key_value": "",Key ValueiBre-B key value (e.g. @merchant123). "source_id": "acc_StaticKeyCop01",Source IdiCobre id of the source account or counterparty. "alias": "Platform collection key",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-08-19T09:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-08-19T09:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook delivered
cobre_keys.status.registeredBre-B registration completed — store key_value and publish it to payers. Map key_id and acc_StaticKeyCop01 to the collection point this key represents.
Headers
| Content-Type | application/json |
Payload
{ "id": "ev_KeyStaticRegistered",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-08-19T09:07: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_StaticPayin001",IdiUnique Cobre identifier for this resource. "key_value": "@platformpayin001",Key ValueiBre-B key value (e.g. @merchant123). "source_id": "acc_StaticKeyCop01",Source IdiCobre id of the source account or counterparty. "alias": "Platform collection 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-08-19T09:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-08-19T09:07:30Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}
Step 4 of 5
Static Key Payin
API step
Static Bre-B Key Credit
A payer sends COP via Bre-B to @platformpayin001. Cobre credits acc_StaticKeyCop01 with a breb_credit transaction — reconcile using metadata.key_value. No Money Movement is created for this rail.
GET
https://api.cobre.co/v1/accounts/acc_StaticKeyCop01COP Cobre BalanceRequirediPath parameter — Cobre Balance where the static key credit posts./transactions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19jb19zdGF0aWNrZXkwMSJ9.CoSk9xM3nR8yQ1lTd7vBw2aF5cP0eH4tJ6gZ |
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_StaticPayin001",Transaction IDiUnique Cobre identifier for this resource. "type": "breb_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_StaticKeyCop01",Account IdiCobre Balance account id affected by the event. "amount": 5000000,Amount creditediAmount in cents — the last two digits are decimals. "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",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-08-19T14:30:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-08-19T14:30:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "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 payin",DescriptioniHuman-readable label or note. "sender_name": "Juliana Restrepo",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": "@platformpayin001",Key valueiThe Cobre Key value that received the credit — primary join key to attribute the payin. "sender_id": "5334623427"Sender IdiMetadata field "sender_id" attached to the resource. } } ]}Webhook delivered
accounts.balance.creditFires when the Bre-B credit posts on acc_StaticKeyCop01. Map metadata.key_value (@platformpayin001) to the collection point this key represents.
Headers
| Content-Type | application/json |
Payload
{ "id": "ev_StaticPayin001",IdiUnique Cobre identifier for this resource. "event_key": "accounts.balance.credit",Event KeyiWebhook subscription key (e.g. money_movements.status.completed). "created_at": "2026-08-19T14:30: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_StaticPayin001",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-08-19T14:30: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. "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 payin",DescriptioniHuman-readable label or note. "sender_name": "Juliana Restrepo",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": "@platformpayin001",Key ValueiBre-B key value (e.g. @merchant123). "sender_id": "5334623427"Sender IdiMetadata field "sender_id" attached to the resource. }, "account_id": "acc_StaticKeyCop01",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. }}
Step 5 of 5
Reconciliation
Reconciliation
Reconcile the Static Key Payin
Match the accounts.balance.credit webhook to your platform ledger using metadata.key_value to attribute the credit to the collection point this key represents. No Money Movement exists — reconciliation is transaction-level on acc_StaticKeyCop01. Because the key is reused across many payers, this rail identifies WHO/WHAT the credit belongs to, not a per-transaction invoice — use a Money Movement–creating rail when per-transaction matching is required.
Mapping the webhook payload from an earlier step onto Platform ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Platform ledger field | |
content.metadata.key_value @platformpayin001 |
→ | static_key_reference Primary join key — maps key_StaticPayin001 (@platformpayin001) to the collection point on your ledger. |
content.id trx_StaticPayin001 |
→ | cobre_transaction_id |
content.amount 5000000 |
→ | received_amount_cents |
content.metadata.sender_name Juliana Restrepo |
→ | payer_name Informational only — this rail identifies the key, not the payer; do not reconcile on name + amount alone. |