Step 1 of 7
Configuration
API step
Authenticate
Exchange API credentials for a short-lived Bearer token (~20 minutes). Attach the same token string to 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_01",User IDiAPI user id issued by Cobre (cli_…). "secret": "sk_live_Mx9pQ2rL7v"SecretiAPI secret from key creation — never log or expose client-side.}Response 201
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19teF8wMSJ9.Mx7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ",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 7
Configuration
API step
Subscribe to Payout Events
Register webhooks for Money Movement lifecycle events and balance debits on your MXN Cobre Balance. Verify deliveries with HMAC-SHA256 (event-timestamp + event-signature). Include returned for Mexico SPEI reversals.
POST
https://api.cobre.co/v1/subscriptions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19teF8wMSJ9.Mx7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "url": "https://yourplatform.mx/webhooks/cobre",Notification URLiHTTPS endpoint that receives Cobre POST notifications. "description": "MX SPEI payout lifecycle",DescriptioniLabel for this subscription in the Cobre portal. "events": [EventsiList of webhook event types this subscription listens to. "money_movements.status.initiated", "money_movements.status.processing", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected", "money_movements.status.returned", "accounts.balance.debit" ], "event_signature_key": "WHmxGen9xZ"Signature keyiSecret you provide; Cobre HMAC-signs each delivery.}Response 201
{ "id": "sub_MxGenSpei1",IdiUnique Cobre identifier for this resource. "url": "https://yourplatform.mx/webhooks/cobre",Notification URLiHTTPS endpoint that receives Cobre POST notifications. "description": "MX SPEI payout lifecycle",DescriptioniLabel for this subscription in the Cobre portal. "events": [EventsiList of webhook event types this subscription listens to. "money_movements.status.initiated", "money_movements.status.processing", "money_movements.status.completed", "money_movements.status.failed", "money_movements.status.rejected", "money_movements.status.returned", "accounts.balance.debit" ], "event_signature_key": "******9xZ",Signature keyiSecret you provide; Cobre HMAC-signs each delivery. "created_at": "2026-07-02T10:00:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 3 of 7
Account Verification
API step
Verify CLABE Ownership
Best practice before a first SPEI payout: use mex_acc_ownership_1 to confirm the 18-digit CLABE belongs to the declared RFC or CURP. The create response is processing — never treat processing as authorization to pay. Use mex_acc_details_1 only when you need account metadata without an ownership check.
POST
https://api.cobre.co/v1/account_verifications
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19teF8wMSJ9.Mx7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "model": "mex_acc_ownership_1",Modelimex_acc_ownership_1 = ownership model — CLABE must match declared identity. "verification_request": {Verification RequestiInput fields sent to the verification model. "account_number": "706180303700100011",CLABEi18-digit CLABE account number. "account_type": "clabe",Account typeiclabe for standard SPEI bank accounts. "account_holder_id_number": "XAXX010101000",Holder IDiPayee RFC or CURP as declared in your system. "account_holder_id_type": "rfc"ID typeirfc or curp — must match the id number format. }, "external_id": "payout_ref_001_verify"External IDiYour payout or payee reference for audit traceability.}Response 201
{ "id": "av_MxGen0001",IdiUnique Cobre identifier for this resource. "creator_id": "cli_demo_mx_01",Creator IdiCobre field at "creator_id" in this payload. "model": "mex_acc_ownership_1",Modelimex_acc_ownership_1 = ownership model — CLABE must match declared identity. "geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "verification_request": {Verification RequestiInput fields sent to the verification model. "account_number": "706180303700100011",CLABEi18-digit CLABE account number. "account_type": "clabe",Account typeiclabe for standard SPEI bank accounts. "account_holder_id_number": "XAXX010101000",Holder IDiPayee RFC or CURP as declared in your system. "account_holder_id_type": "rfc"ID typeirfc or curp — must match the id number format. }, "verification_response": {},Verification ResponseiResult returned by the verification model. "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": "payout_ref_001_verify",External IDiYour payout or payee reference for audit traceability. "created_at": "2026-07-02T10:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-02T10:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 4 of 7
Account Verification
API step
Retrieve Verification Result
Poll GET until status.state is completed. Proceed with 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_MxGen0001
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19teF8wMSJ9.Mx7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
Response 200
{ "id": "av_MxGen0001",Verification IDiav_… from the create response. "creator_id": "cli_demo_mx_01",Creator IdiCobre field at "creator_id" in this payload. "model": "mex_acc_ownership_1",ModeliVerification model identifier (region- and rail-specific). "geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "verification_request": {Verification RequestiInput fields sent to the verification model. "account_number": "706180303700100011",Account NumberiBank account or CLABE number for the counterparty. "account_type": "clabe",Account TypeiCobre field at "verification_request.account_type" in this payload. "account_holder_id_number": "XAXX010101000",Account Holder Id NumberiCobre field at "verification_request.account_holder_id_number" in this payload. "account_holder_id_type": "rfc"Account Holder Id TypeiCobre field at "verification_request.account_holder_id_type" in this payload. }, "verification_response": {Verification ResponseiResult returned by the verification model. "verification_result": "matched"Ownership resultimatched = CLABE ownership confirmed; unmatched = block payout. }, "status": {StatusiLifecycle status object for the resource or movement. "state": "completed",StatusiMust be completed before creating the 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": "payout_ref_001_verify",External IdiYour own reference echoed by Cobre for reconciliation. "created_at": "2026-07-02T10:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-02T10:12:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 5 of 7
SPEI Payout
API step
Create CLABE Counterparty
Register the verified payee bank account as a Mexico CLABE counterparty. Normalize accents in counterparty_fullname — special characters are not allowed.
POST
https://api.cobre.co/v1/counterparties
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19teF8wMSJ9.Mx7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "geo": "mex",Geographyimex for Mexico counterparties. "type": "clabe",Typeiclabe for standard SPEI payout to a bank account. "alias": "Payee payout_ref_001",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "account_number": "706180303700100011",CLABEiSame 18-digit CLABE verified in the ownership step. "counterparty_fullname": "Maria Garcia Lopez",Full nameiLegal name of the payee — no special characters. "counterparty_id_type": "rfc",ID typeiMust match the ID used in account verification. "counterparty_id_number": "XAXX010101000"ID numberiRFC or CURP matching the ownership verification request. }}Response 201
{ "id": "cp_MxPayee01",IdiUnique Cobre identifier for this resource. "geo": "mex",Geographyimex for Mexico counterparties. "type": "clabe",Typeiclabe for standard SPEI payout to a bank account. "alias": "Payee payout_ref_001",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "account_number": "706180303700100011",CLABEiSame 18-digit CLABE verified in the ownership step. "counterparty_fullname": "Maria Garcia Lopez",Full nameiLegal name of the payee — no special characters. "counterparty_id_type": "rfc",ID typeiMust match the ID used in account verification. "counterparty_id_number": "XAXX010101000"ID numberiRFC or CURP matching the ownership verification request. }, "created_at": "2026-07-02T10:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-02T10:15:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 6 of 7
SPEI Payout
API step
Pay via SPEI
Send funds from your MXN Cobre Balance to the CLABE counterparty over SPEI. Amount is integer cents (500000 = MXN 5,000.00). SPEI metadata requires a numeric reference (1–7 digits). Reuse the idempotency header on retries — valid 24h.
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfZGVtb19teF8wMSJ9.Mx7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
| idempotency | 987654321 |
Request body
{ "amount": 500000,Amount (cents)i500000 cents = MXN 5,000.00. "source_id": "acc_FundingMx01",Source balanceiYour MXN Cobre Balance funding account. "destination_id": "cp_MxPayee01",Destination counterpartyicp_… of the verified CLABE counterparty. "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Vendor payment",DescriptioniOptional SPEI description, max 40 characters. "reference": "7654321"SPEI referenceiNumeric reference, 1–7 digits — required for SPEI. }, "external_id": "payout_ref_001"External IDiYour payout reference — primary reconciliation join key.}Response 201
{ "id": "mm_SpeiGen001",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": "Vendor payment",DescriptioniOptional SPEI description, max 40 characters. "reference": "7654321"SPEI referenceiNumeric reference, 1–7 digits — required for SPEI. }, "creator": "cli_demo_mx_01",CreatoriAPI client id that created this resource. "external_id": "payout_ref_001",External IDiYour payout reference — primary reconciliation join key. "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": "spei",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_FundingMx01",Source balanceiYour MXN Cobre Balance funding account. "destination_id": "cp_MxPayee01",Destination counterpartyicp_… of the verified CLABE counterparty. "currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn). "amount": 500000,Amount (cents)i500000 cents = MXN 5,000.00. "created_at": "2026-07-02T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-02T10:20:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
SPEI completed — mark the payout settled on your ledger using external_id. Persist tracking_key and cep_url from metadata for audit and CEP download.
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
money_movements.status.completedHeaders
| Content-Type | application/json |
Example payload
{ "id": "ev_SpeiGen001Cmp",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-02T10:22: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": "mm_SpeiGen001",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": "Vendor payment",DescriptioniHuman-readable label or note. "reference": "7654321",ReferenceiPayment reference echoed in metadata for reconciliation. "tracking_key": "20240702mmbgu7gkQwofrb9o",Tracking KeyiBre-B tracking key for the payment. "cep_url": "https://cep.banco.com/download"Cep UrliMetadata field "cep_url" attached to the resource. }, "creator": "cli_demo_mx_01",CreatoriAPI client id that created this resource. "external_id": "payout_ref_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": "spei",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_FundingMx01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_MxPayee01",Destination IdiCobre id of the destination account or counterparty. "currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn). "amount": 500000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-02T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-02T10:22:30Z"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_SpeiGen001Cmp",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-02T10:22: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": "mm_SpeiGen001",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": "Vendor payment",DescriptioniHuman-readable label or note. "reference": "7654321",ReferenceiPayment reference echoed in metadata for reconciliation. "tracking_key": "20240702mmbgu7gkQwofrb9o",Tracking KeyiBre-B tracking key for the payment. "cep_url": "https://cep.banco.com/download"Cep UrliMetadata field "cep_url" attached to the resource. }, "creator": "cli_demo_mx_01",CreatoriAPI client id that created this resource. "external_id": "payout_ref_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": "spei",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_FundingMx01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_MxPayee01",Destination IdiCobre id of the destination account or counterparty. "currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn). "amount": 500000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-02T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-02T10:22:30Z"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_SpeiGen001Cmp",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-02T10:22: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": "mm_SpeiGen001",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": "Vendor payment",DescriptioniHuman-readable label or note. "reference": "7654321",ReferenceiPayment reference echoed in metadata for reconciliation. "tracking_key": "20240702mmbgu7gkQwofrb9o",Tracking KeyiBre-B tracking key for the payment. "cep_url": "https://cep.banco.com/download"Cep UrliMetadata field "cep_url" attached to the resource. }, "creator": "cli_demo_mx_01",CreatoriAPI client id that created this resource. "external_id": "payout_ref_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": "spei",TypeiResource or movement type as defined by the Cobre API for this rail/product (e.g. breb_credit for Cobre Key payins). "geo": "mex",GeoiGeography code (e.g. col = Colombia, mex = Mexico). "source_id": "acc_FundingMx01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_MxPayee01",Destination IdiCobre id of the destination account or counterparty. "currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn). "amount": 500000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-07-02T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-07-02T10:22:30Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}
Step 7 of 7
Reconciliation
Reconciliation
Reconcile the SPEI Payout
Match the completion webhook to your platform ledger on external_id and mm_id. Cross-check the MXN balance debit via GET /accounts/{acct_id}/transactions. For D+1 close, export SPEI movements with POST /reports.
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.external_id payout_ref_001 |
→ | payout_reference Primary join key — your payout id. |
content.id mm_SpeiGen001 |
→ | cobre_mm_id |
content.metadata.tracking_key 20240702mmbgu7gkQwofrb9o |
→ | spei_tracking_key SPEI network tracking key — store for audit. |
content.metadata.cep_url https://cep.banco.com/download |
→ | spei_receipt_url CEP (Comprobante Electrónico de Pago) download URL. |
content.status.state completed |
→ | payout_status Map completed → PAID; failed/rejected/returned → review. |
content.amount 500000 |
→ | paid_amount_cents |