Cargo recurrente

Si cobras a un mismo cliente de forma periódica (mensualidades, renovaciones, abonos) y quieres que en el Checkout siempre pague con la misma referencia de efectivo, crea tus órdenes con el parámetro reuse_customer_cash_reference: true. Cuando el cliente elija efectivo en el Checkout, verá su referencia recurrente en lugar de una referencia nueva.

Es el equivalente en efectivo del cargo recurrente con transferencia. Si creas los cargos directamente por API, sin Checkout, consulta Reutilización de referencia recurrente de efectivo.

Cómo funciona

sequenceDiagram
    participant Dev as Tu servidor
    participant Conekta
    participant Cliente as Cliente (Checkout)
    participant Tienda as Tienda / BBVA
    Dev->>Conekta: POST /customers/:id/payment_sources (cash_recurrent)
    Conekta-->>Dev: Referencia recurrente del cliente
    Dev->>Conekta: POST /orders (checkout + reuse_customer_cash_reference: true)
    Conekta-->>Dev: Orden con checkout.id (sin cargos todavía)
    Cliente->>Conekta: Elige Efectivo en el Checkout
    Conekta-->>Cliente: Muestra su referencia recurrente
    Tienda->>Conekta: Pago con la referencia y el monto de la orden
    Conekta-->>Dev: Webhooks charge.paid / order.paid

1. Creas la referencia recurrente una sola vez. Se guarda como un payment source de tipo cash_recurrent en el cliente.
2. Creas una orden con Checkout por cada cobro, con reuse_customer_cash_reference: true y el customer_id.
3. El cliente elige Efectivo en el Checkout. En ese momento se crea el cargo, con la referencia recurrente del cliente y el monto de la orden.
4. El cliente paga en tienda con su referencia de siempre, y Conekta te notifica el pago por webhook.

La referencia recurrente no se modifica: pagar o cancelar una orden no la desactiva, y puedes seguir usándola en órdenes nuevas.

Requisitos

• Tus llaves privadas → API Keys de pruebas y API Keys de producción.
• Una integración de Checkout funcionando → Cargo único.
• Un webhook configurado para recibir las confirmaciones de pago → Configurar un webhook.
• Si usas BBVA como red de efectivo, tu cuenta debe tener configurado un convenio recurrente de BBVA. Si no lo tienes, contacta a tu ejecutivo de Conekta.

1. Añade tu llave privada y versión del API

• Tu API key en el header de autenticación: --header 'Authorization: Bearer key_xxxxxxxxxxxxxxxxxxxxxxxx'
• La versión del API en el header accept: 'accept: application/vnd.conekta-v2.3.0+json'

2. Crea un Customer

Primero crea el cliente que tendrá asociada la referencia de efectivo recurrente.

curl --request POST \
  --url https://api.conekta.io/customers \
  --header 'accept: application/vnd.conekta-v2.3.0+json' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer key_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "name": "Juan Perez",
    "email": "[email protected]",
    "phone": "+5215555555555"
  }'

Respuesta:

{
    "livemode": true,
    "name": "Juan Perez",
    "email": "[email protected]",
    "phone": "+5215555555555",
    "id": "cus_2xHJayvPVd3BpmdC7",
    "object": "customer",
    "created_at": 1790633700,
    "corporate": false,
    "custom_reference": ""
}

3. Crea la referencia de efectivo recurrente

Crea un payment source de tipo cash_recurrent para el cliente. Esta es la referencia que se reutilizará en todas sus órdenes.

curl --request POST \
  --url https://api.conekta.io/customers/cus_2xHJayvPVd3BpmdC7/payment_sources \
  --header 'accept: application/vnd.conekta-v2.3.0+json' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer key_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "type": "cash_recurrent"
  }'

Respuesta:

{
  "id": "off_ref_2xHJayvPVd3BpmdC8",
  "object": "payment_source",
  "provider": "Cash",
  "type": "cash_recurrent",
  "reference": "10001XXXXXXXXXXX0104",
  "barcode": "10001XXXXXXXXXXX0104",
  "barcode_url": "https://barcode/url.png",
  "expires_at": 0,
  "created_at": 1790633754,
  "parent_id": "cus_2xHJayvPVd3BpmdC7",
  "agreements": [
    {
      "provider": "bbva_cash_in",
      "agreement": "2409526"
    }
  ]
}

Para conocer más sobre la referencia cash_recurrent, consulta Cargo recurrente en efectivo con Direct API.

4. Crea una orden con Checkout y reutilización de la referencia

Al crear un order con reuse_customer_cash_reference: true y el objeto checkout, el Checkout mostrará la referencia recurrente del cliente en lugar de generar una nueva.

Campos requeridos:

• reuse_customer_cash_reference: true: habilita la reutilización de la referencia.
• customer_info.customer_id: el ID del customer creado en el paso 2 (obligatorio).
• checkout.type: "Integration": tipo de checkout.
• checkout.allowed_payment_methods: ["cash"]: habilita efectivo.

curl --request POST \
  --url https://api.conekta.io/orders \
  --header 'accept: application/vnd.conekta-v2.3.0+json' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer key_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "currency": "MXN",
    "reuse_customer_cash_reference": true,
    "customer_info": {
      "customer_id": "cus_2xHJayvPVd3BpmdC7"
    },
    "line_items": [{
      "name": "Mensualidad octubre",
      "unit_price": 50000,
      "quantity": 1
    }],
    "checkout": {
      "type": "Integration",
      "allowed_payment_methods": ["cash"]
    }
  }'

Respuesta (resumida):

{
  "livemode": true,
  "amount": 50000,
  "currency": "MXN",
  "id": "ord_2tXx9jDpCqIrjVKZ",
  "object": "order",
  "customer_info": {
    "customer_id": "cus_2xHJayvPVd3BpmdC7",
    "object": "customer_info"
  },
  "checkout": {
    "id": "348ccf9f-8f1a-4a78-aa5f-8374b18efff6",
    "type": "Integration",
    "status": "Issued"
  },
  "metadata": {
    "reuse_customer_cash_reference": true
  },
  "charges": null
}

¿Cuándo se asigna la referencia?

1. El cliente abre el Checkout con el checkout.id.
2. El cliente elige Efectivo como método de pago.
3. Conekta detecta que la orden tiene reuse_customer_cash_reference: true y un customer_id con referencia cash_recurrent, y crea el cargo con esa referencia.
4. El Checkout le muestra al cliente su referencia recurrente para que pague en tienda.

Si tu cuenta tiene varias redes de efectivo, el Checkout muestra la misma referencia en todas. En la tarjeta de BBVA aparece además el convenio recurrente, que el cliente necesita para pagar en cajeros BBVA.

En esta captura se muestra cómo el Checkout presenta la referencia recurrente del cliente: la misma referencia en BBVA (con su convenio recurrente) y en Conekta Efectivo.

5. Recibe la confirmación del pago

Cuando el cliente paga en tienda con su referencia, Conekta busca la orden pendiente creada con reuse_customer_cash_reference: true que tenga esa referencia y ese monto, y que no haya vencido. Esa orden se marca como pagada y recibes los eventos charge.paid y order.paid en tu webhook.

Las reglas de conciliación (monto exacto, varias órdenes pendientes con el mismo monto, pagos duplicados) son las mismas que con Direct API. Consulta Recibe la confirmación del pago.

6. Crea las siguientes órdenes

Para el siguiente cobro, repite el paso 4 con reuse_customer_cash_reference: true. No necesitas crear otra referencia.

curl --request POST \
  --url https://api.conekta.io/orders \
  --header 'accept: application/vnd.conekta-v2.3.0+json' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer key_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "currency": "MXN",
    "reuse_customer_cash_reference": true,
    "customer_info": {
      "customer_id": "cus_2xHJayvPVd3BpmdC7"
    },
    "line_items": [{
      "name": "Mensualidad noviembre",
      "unit_price": 50000,
      "quantity": 1
    }],
    "checkout": {
      "type": "Integration",
      "allowed_payment_methods": ["cash"]
    }
  }'

Manejo de errores

Consulta el detalle de cada error en Reutilización de referencia recurrente de efectivo y el catálogo completo en Códigos de error HTTP.

Error: customer_id faltante

{
  "details": [
    {
      "debug_message": "The \"customer_info attribute customer_id\" is missing.",
      "message": "El parametro customer_id es requerido.",
      "param": "customer_info.customer_id",
      "code": "conekta.errors.parameter_validation.customer_info.customer_id.missing"
    }
  ],
  "object": "error",
  "type": "parameter_validation_error",
  "log_id": "xxxxxxxxxxxxxxxxxxxx"
}

HTTP Status: 422 Unprocessable Entity

Error: referencia recurrente no encontrada

{
  "details": [
    {
      "debug_message": "Recurrent reference not found",
      "message": "Referencia recurrente no encontrada",
      "code": "conekta.errors.resource_not_found.processing.offline_recurrent_reference.not_found"
    }
  ],
  "object": "error",
  "type": "resource_not_found_error",
  "log_id": "xxxxxxxxxxxxxxxxxxxx"
}

HTTP Status: 404 Not Found

Solución: crea primero un payment source de tipo cash_recurrent para el cliente (paso 3).

Comportamiento por defecto

Si no envías reuse_customer_cash_reference o lo envías en false, cuando el cliente elija Efectivo en el Checkout se generará una referencia única nueva, distinta de su referencia recurrente, y en BBVA se usará el convenio de referencias únicas. Consulta Cargo único.

Relacionado

• Cargo único: cómo integrar el Checkout con efectivo.
• Cargo recurrente con transferencia: el mismo patrón para SPEI en Checkout.
• Reutilización de referencia recurrente de efectivo: el mismo flujo con Direct API, con el detalle de conciliación y errores.
• Configurar un webhook: para recibir charge.paid y order.paid.
• Autenticación de webhooks: verifica la firma de cada notificación.