API Documentation

Use the Cobrofácil API and SDKs to receive SPEI bank transfers in your own application by assigning a unique CLABE to each of your customers.

Overview

The problem

Cobrofácil lets your platform receive customer payments through standard SPEI transfers without relying on manual reconciliation, where all payments are received into a single bank account and finance teams must review bank statements, identify each transfer sender, and match incoming funds against customer records, orders, invoices, or account balances. This manual process can become tedious and error-prone.

The solution

To automate this process, each customer can be assigned a unique SPEI CLABE, which works as a virtual bank account. These virtual accounts are recognized by the Mexican banking system and can receive transfers from any bank connected to SPEI, the national real-time payment network operated by the Bank of Mexico, Mexico's central banking authority.

The typical use case is wallet funding, order payments, subscription collections, account recharges, loan repayments, or any workflow where customers need to transfer funds to your business from a Mexican bank account.

When you create a customer through our API, Cobrofácil creates:

• A customer record.
• An internal accounting account associated with that customer.
• A unique SPEI CLABE assigned exclusively to that customer.
• A permanent relationship between your customer identifier and the assigned CLABE.

You can optionally provide your own external customer ID when creating the customer. This lets you keep a direct relationship between your own records, such as a user ID, account ID, or CRM reference, and the customer account managed by Cobrofácil.

Once the customer has an assigned CLABE, they can send a SPEI transfer from any Mexican bank. Cobrofácil receives, validates, and reconciles the transfer. After the payment is fully processed, Cobrofácil sends a webhook notification to your system with the transaction details so your application can apply the funds automatically.

At the end of the settlement cycle, accumulated funds can be transferred from your Cobrofácil balance to your registered bank account through the payout process. This is similar to how payment service providers receive funds, notify your system in real time, and later settle balances to your bank account.

Integration flow

1. Create a customer

Your application creates a customer through the Cobrofácil API or one of the official SDKs. During this request, you may include your own external_reference to link the Cobrofácil customer with your internal customer record.

Cobrofácil returns the assigned SPEI CLABE in the API response. Display this CLABE to the customer as their payment destination.

2. Customer sends a SPEI transfer

The customer initiates a standard SPEI transfer from their bank to the CLABE assigned to them.

Because each customer has a unique receiving CLABE, Cobrofácil can associate incoming funds with the correct customer without requiring payment references or manual reconciliation.

3. Cobrofácil verifies the payment

When the transfer reaches the assigned CLABE, Cobrofácil validates and reconciles the transaction, verifies the settlement status, and records the payment in the customer's accounting account.

Once the transaction is confirmed, Cobrofácil generates a webhook notification.

4. Your system receives the webhook

The webhook contains the payment information your application needs to process the business action, including the customer reference, amount, SPEI tracking key, payer information, receiving CLABE, settlement timestamp, and transaction identifiers.

Your application can use the webhook to:

• Credit funds to a customer wallet.
• Mark an order as paid.
• Activate a subscription.
• Apply a payment to an outstanding balance.
• Record a loan repayment.
• Update an internal ledger or accounting system.

5. Settle funds to your bank account

As customer payments are received, incoming transfers accumulate in your Cobrofácil balance until the next payout action takes place. You can review incoming and payout transfers in the SPEI Transfers view, which also provides the payout action button.

By default, Cobrofácil processes automated payouts every day at 6:00 PM in the business's local timezone, as configured in the Business Settings page. You can adjust the payout time according to the tenant's operational preference, and all scheduled processes run using the timezone defined for the business. Through the payout process, Cobrofácil transfers accumulated funds to your registered bank account.

Simulated incoming transfers

To trigger webhooks and make the integration process easier in the sandbox environment, you can simulate incoming transfers before receiving real SPEI payments.

Webhook endpoints must be configured before Cobrofácil can deliver event notifications to your system. The next section explains where to add and test them.

Open the STP integration settings and go to the Simulación de ingresos tab. Select the account that should receive the simulated income, enter the amount you want to test, and run the simulation.

Before simulating incoming payments, we strongly recommend setting up webhooks because they are part of the integrated payment workflow. Read the Webhooks section for more information. Cobrofácil will create a simulated incoming transfer for the selected account and trigger the corresponding webhook to your system, letting you validate your webhook handling, customer matching, and business logic during development.

Webhooks

You can add webhook endpoints in the Webhooks settings module. Each webhook should point to an endpoint in your system that can receive Cobrofácil event notifications.

During development, you can use an external inspection service such as webhook.site to receive and inspect webhook payloads before connecting your production endpoint.

After adding a webhook, use the Enviar evento de prueba test action to send a webhook ping. This helps confirm that Cobrofácil can reach your endpoint and that your system is receiving requests correctly.