Step 1 of 7
Configuration
API step
Authenticate
Exchange API credentials for a short-lived Bearer token (~20 minutes). Every later call in this flow reuses the same token string.
POST
https://api.cobre.co/v1/auth
Headers
| Content-Type | application/json |
Request body
{ "user_id": "cli_mex_lender_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.eyJzdWIiOiJjbGlfbWV4X2xlbmRlcl8wMSJ9.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 Disbursement Events
Register your HTTPS listener for Money Movement lifecycle events and balance debits. Prefer webhooks over polling; verify each delivery with HMAC-SHA256 using event-timestamp and event-signature.
POST
https://api.cobre.co/v1/subscriptions
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbWV4X2xlbmRlcl8wMSJ9.Mx7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "url": "https://lender.example.mx/webhooks/cobre",Notification URLiYour backend endpoint that receives Cobre POST notifications. "description": "SPEI disbursement 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": "WHmxSpei9xZ"Signature keyiSecret you provide; Cobre HMAC-signs payloads for verification.}Response 201
{ "id": "sub_MxSpei01",IdiUnique Cobre identifier for this resource. "url": "https://lender.example.mx/webhooks/cobre",Notification URLiYour backend endpoint that receives Cobre POST notifications. "description": "SPEI disbursement 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 payloads for verification. "created_at": "2026-06-28T10:00:00Z"Created AtiTimestamp when the resource was created (ISO 8601, UTC).}
Step 3 of 7
Account Verification
API step
Verify CLABE Ownership
Before disbursing, confirm the borrower's 18-digit CLABE matches the declared RFC or CURP via mex_acc_ownership_1. The create call returns processing — never treat processing as authorization to pay.
POST
https://api.cobre.co/v1/account_verifications
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbWV4X2xlbmRlcl8wMSJ9.Mx7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "model": "mex_acc_ownership_1",Modelimex_acc_ownership_1 validates CLABE ownership in 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 IDiBorrower's RFC or CURP as declared on the loan. "account_holder_id_type": "rfc"ID typeirfc or curp — must match the id number format. }, "external_id": "loan_000123_verify"External IDiYour loan/borrower reference for audit (traceability).}Response 201
{ "id": "av_MxVer0001",IdiUnique Cobre identifier for this resource. "creator_id": "cli_mex_lender_01",Creator IdiCobre field at "creator_id" in this payload. "model": "mex_acc_ownership_1",Modelimex_acc_ownership_1 validates CLABE ownership in Mexico. "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 IDiBorrower's RFC or CURP as declared on the loan. "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": "loan_000123_verify",External IDiYour loan/borrower reference for audit (traceability). "created_at": "2026-06-28T10:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-28T10:05:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 4 of 7
Account Verification
API step
Retrieve Verification Result
Poll until status.state is completed. Only disburse when verification_result is matched; route failed or unmatched results to manual review.
GET
https://api.cobre.co/v1/account_verifications/av_MxVer0001
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbWV4X2xlbmRlcl8wMSJ9.Mx7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
Request body
{}Response 200
{ "id": "av_MxVer0001",Verification IDiav_… from the create response. "creator_id": "cli_mex_lender_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 = safe to proceed; unmatched or unresolved = block payout. }, "status": {StatusiLifecycle status object for the resource or movement. "state": "completed",StatusiMust be completed before disbursement. "code": "",CodeiProvider or Cobre status code when the state is failed or rejected. "description": ""DescriptioniHuman-readable detail for the current status. }, "external_id": "loan_000123_verify",External IdiYour own reference echoed by Cobre for reconciliation. "created_at": "2026-06-28T10:05:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-28T10:12:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 5 of 7
Loan Disbursement
API step
Create CLABE Counterparty
Register the verified borrower 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.eyJzdWIiOiJjbGlfbWV4X2xlbmRlcl8wMSJ9.Mx7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
Request body
{ "geo": "mex",GeographyiGeography code (e.g. col = Colombia, mex = Mexico). "type": "clabe",Typeiclabe for standard SPEI loan disbursement to a bank account. "alias": "Borrower loan_000123",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "account_number": "706180303700100011",CLABEiBank account or CLABE number for the counterparty. "counterparty_fullname": "Maria Garcia Lopez",Full nameiLegal or display name of the counterparty beneficiary. "counterparty_id_type": "rfc",ID typeiType of identification document for the counterparty (e.g. nit, cc, rfc). "counterparty_id_number": "XAXX010101000"ID numberiIdentification number for the counterparty. }}Response 201
{ "id": "cp_MxBorrow01",IdiUnique Cobre identifier for this resource. "geo": "mex",GeographyiGeography code (e.g. col = Colombia, mex = Mexico). "type": "clabe",Typeiclabe for standard SPEI loan disbursement to a bank account. "alias": "Borrower loan_000123",AliasiDisplay name that helps identify it and clarify its purpose. "metadata": {MetadataiCustom key-value metadata attached to the resource. "account_number": "706180303700100011",CLABEiBank account or CLABE number for the counterparty. "counterparty_fullname": "Maria Garcia Lopez",Full nameiLegal or display name of the counterparty beneficiary. "counterparty_id_type": "rfc",ID typeiType of identification document for the counterparty (e.g. nit, cc, rfc). "counterparty_id_number": "XAXX010101000"ID numberiIdentification number for the counterparty. }, "created_at": "2026-06-28T10:15:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-28T10:15:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}
Step 6 of 7
Loan Disbursement
API step
Disburse Loan via SPEI
Send approved loan principal from your MXN Cobre Balance to the borrower's CLABE counterparty. Amount is in cents (100000 = MXN 1,000.00). SPEI metadata requires a numeric reference (≤7 digits). Reuse the same idempotency header when retrying a timed-out POST — valid 24h.
POST
https://api.cobre.co/v1/money_movements
Headers
| Authorization | Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbGlfbWV4X2xlbmRlcl8wMSJ9.Mx7Kp3nQ9xY2mLd8vBw1aF6cR0eH4tJ5gZ |
| Content-Type | application/json |
| idempotency | 123456789 |
Request body
{ "amount": 100000,Amount (cents)i100000 cents = MXN 1,000.00. "source_id": "acc_MxnLender01",Source balanceiCobre id of the source account or counterparty. "destination_id": "cp_MxBorrow01",Destination counterpartyiCobre id of the destination account or counterparty. "metadata": {MetadataiCustom key-value metadata attached to the resource. "description": "Loan disbursement",DescriptioniOptional SPEI description, max 40 characters. "reference": "1234567"SPEI referenceiNumeric reference, 1–7 digits — required for SPEI payouts. }, "external_id": "loan_000123"External ID (loan)iYour loan id — primary reconciliation join key.}Response 201
{ "id": "mm_SpeiLoan123",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": "Loan disbursement",DescriptioniOptional SPEI description, max 40 characters. "reference": "1234567"SPEI referenceiNumeric reference, 1–7 digits — required for SPEI payouts. }, "creator": "cli_mex_lender_01",CreatoriAPI client id that created this resource. "external_id": "loan_000123",External ID (loan)iYour loan id — 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_MxnLender01",Source balanceiCobre id of the source account or counterparty. "destination_id": "cp_MxBorrow01",Destination counterpartyiCobre id of the destination account or counterparty. "currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn). "amount": 100000,Amount (cents)i100000 cents = MXN 1,000.00. "created_at": "2026-06-28T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-28T10:20:00Z"Updated AtiTimestamp of the last update (ISO 8601, UTC).}Webhook outcomes — Money movement
SPEI completed — mark the loan disbursed on your ledger using external_id. Persist tracking_key and cep_url from metadata for audit and SPEI receipt 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_SpeiLoan123Cmp",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-28T10: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_SpeiLoan123",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": "Loan disbursement",DescriptioniHuman-readable label or note. "reference": "1234567",ReferenceiPayment reference echoed in metadata for reconciliation. "tracking_key": "20240624mmbgu7gkQwofrb9o",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_mex_lender_01",CreatoriAPI client id that created this resource. "external_id": "loan_000123",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_MxnLender01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_MxBorrow01",Destination IdiCobre id of the destination account or counterparty. "currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn). "amount": 100000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-28T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-28T10: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_SpeiLoan123Cmp",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-28T10: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_SpeiLoan123",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": "Loan disbursement",DescriptioniHuman-readable label or note. "reference": "1234567",ReferenceiPayment reference echoed in metadata for reconciliation. "tracking_key": "20240624mmbgu7gkQwofrb9o",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_mex_lender_01",CreatoriAPI client id that created this resource. "external_id": "loan_000123",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_MxnLender01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_MxBorrow01",Destination IdiCobre id of the destination account or counterparty. "currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn). "amount": 100000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-28T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-28T10: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_SpeiLoan123Cmp",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-28T10: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_SpeiLoan123",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": "Loan disbursement",DescriptioniHuman-readable label or note. "reference": "1234567",ReferenceiPayment reference echoed in metadata for reconciliation. "tracking_key": "20240624mmbgu7gkQwofrb9o",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_mex_lender_01",CreatoriAPI client id that created this resource. "external_id": "loan_000123",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_MxnLender01",Source IdiCobre id of the source account or counterparty. "destination_id": "cp_MxBorrow01",Destination IdiCobre id of the destination account or counterparty. "currency": "mxn",CurrencyiISO currency code (e.g. cop, mxn). "amount": 100000,AmountiAmount in cents — the last two digits are decimals. "created_at": "2026-06-28T10:20:00Z",Created AtiTimestamp when the resource was created (ISO 8601, UTC). "updated_at": "2026-06-28T10:22:30Z"Updated AtiTimestamp of the last update (ISO 8601, UTC). }}
Step 7 of 7
Reconciliation
Reconciliation
Reconcile the SPEI Disbursement
Match the completion webhook to your loan 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 Loan ledger. No API call is made — this step closes the loop in your own system.
| Cobre field & value | Loan ledger field | |
content.external_id loan_000123 |
→ | loan_id Primary join key — your loan record id. |
content.id mm_SpeiLoan123 |
→ | cobre_mm_id Canonical Money Movement id from Cobre. |
content.metadata.tracking_key 20240624mmbgu7gkQwofrb9o |
→ | 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 |
→ | disbursement_status Map completed → FUNDED; failed/rejected/returned → review. |
content.amount 100000 |
→ | disbursed_amount_cents |