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_mx_payin01",User IDRequirediAPI user id issued by Cobre (cli_…). "secret": "sk_live_MxVc9pQ2rL7v"SecretRequirediAPI secret from key creation — treat like a password.}Response 201
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19teF9wYXlpbjAxIn0.MxVc7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ",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 Cobre Balance credits. Virtual CLABE payins are passive — no Money Movement is created. Subscribe to accounts.balance.credit (spei_credit on arrival). Verify deliveries with HMAC-SHA256.
POST
https://api.cobre.co/v1/subscriptions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19teF9wYXlpbjAxIn0.MxVc7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "url": "https://yourplatform.mx/webhooks/cobre",Notification URLRequirediHTTPS endpoint that receives Cobre POST notifications. "description": "Virtual CLABE payin lifecycle",DescriptioniLabel for this subscription in the Cobre portal. "events": [EventsiList of webhook event types this subscription listens to. "accounts.balance.credit" ], "event_signature_key": "WHvcMx9xZ"Signature keyRequirediSecret you provide; Cobre HMAC-signs each delivery.}Response 201
{ "id": "sub_VcPayin01",IdiUnique Cobre identifier for this resource. "url": "https://yourplatform.mx/webhooks/cobre",Notification URLRequirediHTTPS endpoint that receives Cobre POST notifications. "description": "Virtual CLABE payin lifecycle",DescriptioniLabel for this subscription in the Cobre portal. "events": [EventsiList of webhook event types this subscription listens to. "accounts.balance.credit" ], "event_signature_key": "******9xZ",Signature keyRequirediSecret you provide; Cobre HMAC-signs each delivery. "created_at": "2026-07-19T10:00:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 3 of 5
Virtual CLABE Payin
API step
Create Virtual CLABE Account Reference
Provision a Virtual CLABE linked to your MXN Cobre Balance for one end user or order. Share the returned value (18-digit CLABE) with the payer — inbound SPEI transfers credit your balance automatically. Create one reference per end-user sub-account or per payment intent.
POST
https://api.cobre.co/v1/account_references
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19teF9wYXlpbjAxIn0.MxVc7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "source_id": "acc_FundingMx01",MXN Cobre BalanceRequirediCobre Balance that receives Virtual CLABE SPEI credits. "type": "virtual_clabe_accounts",Reference typeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "alias": "End user payin - payin_ref_001"AliasiDisplay name that helps identify it and clarify its purpose.}Response 200
{ "id": "ref_EndUserMx01",IdiUnique Cobre identifier for this resource. "alias": "End user payin - payin_ref_001",AliasiDisplay name that helps identify it and clarify its purpose. "type": "virtual_clabe_accounts",Reference typeRequirediResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "value": "703013052111000038",ValueiCobre field at "value" in this payload. "source_id": "acc_FundingMx01",MXN Cobre BalanceRequirediCobre Balance that receives Virtual CLABE SPEI credits. "geo": "mex",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. "created_at": "2026-07-19T11:00:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-19T11:00:05Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 4 of 5
Virtual CLABE Payin
API step
Virtual CLABE SPEI Credit
The payer sends MXN via SPEI to the Virtual CLABE (703013052111000038). Cobre credits acc_FundingMx01 with spei_credit — reconcile using metadata.account_reference matching ref_EndUserMx01. No Money Movement is created.
GET
https://api.cobre.co/v1/accounts/acc_FundingMx01MXN Cobre BalanceRequirediPath parameter — Cobre Balance where Virtual CLABE SPEI credits post./transactions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19teF9wYXlpbjAxIn0.MxVc7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
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_VcPayin001",Transaction IDiUnique Cobre identifier for this resource. "type": "spei_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_FundingMx01",Account IdiCobre Balance account id affected by the event. "amount": 1500000,Amount creditediAmount in cents — the last two digits are decimals. "previous_balance": 5000000,Previous BalanceiCobre field at "contents.0.previous_balance" in this payload. "current_balance": 6500000,Current BalanceiCobre field at "contents.0.current_balance" in this payload. "currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn). "credit_debit_type": "credit",Credit Debit Typeicredit = funds in; debit = funds out. "transaction_date": "2026-07-19T14:30:00Z",Transaction DateiTimestamp when the transaction was posted (ISO 8601, UTC). "created_at": "2026-07-19T14:30:01Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "metadata": {MetadataiCustom key-value metadata attached to the resource. "reference": "91025",ReferenceiPayment reference echoed in metadata for reconciliation. "sender_name": "JUAN,PEREZ/GARCIA",Sender NameiMetadata field "sender_name" attached to the resource. "sender_clabe": "012180001234567890",Sender ClabeiMetadata field "sender_clabe" attached to the resource. "tracking_key": "20260719143000001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "description": "SPEI payin via Virtual CLABE",DescriptioniHuman-readable label or note. "account_reference": "703013052111000038"Account referenceiVirtual CLABE value — primary join key to attribute the credit to your end user or order. } } ]}Webhook delivered
accounts.balance.creditFires when the Virtual CLABE credit posts on acc_FundingMx01. Map metadata.account_reference to your end user or order (payin_ref_001).
Headers
| Content-Type | application/json |
Payload
{ "id": "ev_VcPayin001",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-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_VcPayin001",IdiUnique Cobre identifier for this resource. "type": "spei_credit",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "amount": 1500000,AmountiAmount in cents — the last two digits are decimals. "currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn). "date": "2026-07-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. "reference": "91025",ReferenceiPayment reference echoed in metadata for reconciliation. "sender_name": "JUAN,PEREZ/GARCIA",Sender NameiMetadata field "sender_name" attached to the resource. "sender_clabe": "012180001234567890",Sender ClabeiMetadata field "sender_clabe" attached to the resource. "tracking_key": "20260719143000001",Tracking KeyiNetwork tracking key for the payment (PSE ticket or Bre-B key). "description": "SPEI payin via Virtual CLABE",DescriptioniHuman-readable label or note. "account_reference": "703013052111000038"Account ReferenceiTransfer-In reference number used to reconcile incoming deposits. }, "account_id": "acc_FundingMx01",Account IdiCobre Balance account id affected by the event. "previous_balance": 5000000,Previous BalanceiCobre field at "content.previous_balance" in this payload. "current_balance": 6500000,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 Virtual CLABE Payin
Match the accounts.balance.credit webhook to your platform ledger using metadata.account_reference for end-user or order attribution. No Money Movement exists — reconciliation is transaction-level on acc_FundingMx01.
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.account_reference 703013052111000038 |
→ | virtual_clabe_reference Primary join key — maps ref_EndUserMx01 (703013052111000038) to payin_ref_001 on your ledger. |
content.id trx_VcPayin001 |
→ | cobre_transaction_id |
content.amount 1500000 |
→ | credited_amount_cents MXN credited to acc_FundingMx01 (1500000 = $15,000.00 MXN). |
content.account_id acc_FundingMx01 |
→ | mxn_balance_id |
content.metadata.tracking_key 20260719143000001 |
→ | spei_tracking_key Banxico tracking key — useful for support and bank traceability. |