DocumentaciónAPIDevToolsRecipesTarjetas de PruebasEstado del ServicioChangelog
Documentación
Iniciar Sesión

Cargo Recurrente

Reutilización de CLABE para Cargos Recurrentes con Checkout

Permite a tus clientes usar la misma CLABE para múltiples pagos SPEI a través del Checkout Component

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.2.0+json'

2. Crea un Customer

Primero debes crear un cliente que tendrá asociada la referencia SPEI recurrente.

curl --request POST \
  --url https://api.conekta.io/customers \
  --header 'accept: application/vnd.conekta-v2.2.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_2ztR5QVktcPxj6UGm",
    "object": "customer",
    "created_at": 1776367851,
    "corporate": false,
    "custom_reference": ""
}
🚧

Importante:

Guarda el id del customer, lo necesitarás en los siguientes pasos.

3. Crea una referencia SPEI recurrente

Ahora debes crear un payment source de tipo spei_recurrent para el cliente. Esta será la CLABE que se reutilizará en múltiples órdenes.

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

Respuesta:

{
    "id": "off_ref_2ztR9SXUwoqbxhqa1",
    "object": "payment_source",
    "type": "spei_recurrent",
    "reference": "646180111802075448",
    "created_at": 1776368168,
    "parent_id": "cus_2ztR5QVktcPxj6UGm",
    "bank": "STP"
}
📘

El valor de reference (CLABE) 646180111802075448 se reutilizará en las órdenes.

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

Al crear un order con el parámetro reuse_customer_clabe: true y el objeto checkout, el sistema usará la CLABE de la referencia recurrente del cliente en el Checkout Component en lugar de generar una nueva.

Campos requeridos:

  • reuse_customer_clabe: true - Habilita la reutilización de la CLABE
  • customer_info.customer_id - El ID del customer creado previamente (OBLIGATORIO)
  • checkout.type: "Integration" - Tipo de checkout
  • checkout.allowed_payment_methods: ["bank_transfer"] - Habilita transferencias
curl --request POST \
  --url https://api.conekta.io/orders \
  --header 'accept: application/vnd.conekta-v2.2.0+json' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer key_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "currency": "MXN",
    "reuse_customer_clabe": true,
    "customer_info": {
      "customer_id": "cus_2ztR5QVktcPxj6UGm"
    },
    "line_items": [{
      "name": "Suscripción Mensual",
      "unit_price": 50000,
      "quantity": 1
    }],
    "checkout": {
      "type": "Integration",
      "allowed_payment_methods": ["bank_transfer"]
    }
  }'

Respuesta:

{
    "livemode": true,
    "amount": 50000,
    "currency": "MXN",
    "payment_status": null,
    "amount_refunded": 0,
    "split_payment": null,
    "customer_info": {
        "email": "[email protected]",
        "phone": "+5215555555555",
        "name": "Juan Perez",
        "corporate": false,
        "customer_id": "cus_2ztR5QVktcPxj6UGm",
        "date_of_birth": null,
        "national_id": null,
        "object": "customer_info",
        "customer_custom_reference": null
    },
    "shipping_contact": null,
    "channel": {
        "segment": "Checkout",
        "checkout_request_id": "348ccf9f-8f1a-4a78-aa5f-8374b18efff6",
        "checkout_request_type": "Integration",
        "original_checkout_request_type": null,
        "original_checkout_request_id": null,
        "id": "channel_2ztRAvAXLw8rW2pQ7"
    },
    "fiscal_entity": null,
    "checkout": {
        "id": "348ccf9f-8f1a-4a78-aa5f-8374b18efff6",
        "name": "ord-2ztRAuRhpjaCsm9ug",
        "livemode": true,
        "emails_sent": 0,
        "success_url": "",
        "failure_url": "",
        "payments_limit_count": null,
        "paid_payments_count": 0,
        "sms_sent": 0,
        "status": "Issued",
        "type": "Integration",
        "recurrent": false,
        "starts_at": 1776319200,
        "expires_at": 1776578399,
        "allowed_payment_methods": [
            "bank_transfer"
        ],
        "exclude_card_networks": [],
        "needs_shipping_contact": false,
        "monthly_installments_options": [],
        "monthly_installments_enabled": false,
        "redirection_time": null,
        "force_3ds_flow": false,
        "plan_id": null,
        "metadata": {},
        "can_not_expire": false,
        "three_ds_mode": null,
        "max_failed_retries": null,
        "object": "checkout",
        "is_redirect_on_failure": false,
        "on_demand_enabled": false
    },
    "object": "order",
    "id": "ord_2ztRAuRhpjaCsm9ug",
    "metadata": {
        "reuse_customer_clabe": true
    },
    "is_refundable": false,
    "processing_mode": null,
    "created_at": 1776368284,
    "updated_at": 1776368284,
    "line_items": {
        "object": "list",
        "has_more": false,
        "total": 1,
        "data": [
            {
                "name": "Suscripción Mensual",
                "description": null,
                "unit_price": 50000,
                "quantity": 1,
                "sku": null,
                "tags": null,
                "brand": null,
                "type": null,
                "object": "line_item",
                "id": "line_item_2ztRAuRhpjaCsm9ue",
                "parent_id": "ord_2ztRAuRhpjaCsm9ug",
                "metadata": {},
                "antifraud_info": {}
            }
        ]
    },
    "shipping_lines": null,
    "tax_lines": null,
    "discount_lines": null,
    "charges": null
}
📘

Nota importante: La CLABE recurrente 646180111802075448 no se genera en esta respuesta. El objeto charges será null hasta que el cliente acceda al Checkout Component usando el checkout.id (348ccf9f-8f1a-4a78-aa5f-8374b18efff6) y seleccione transferencia como método de pago.

¿Cuándo se genera la CLABE?

La CLABE recurrente se genera cuando:

  1. El cliente accede al Checkout Component usando el checkout.id
  2. El cliente selecciona Transferencia como método de pago en la interfaz del Checkout
  3. El sistema detecta que la orden tiene reuse_customer_clabe: true y un customer_id válido
  4. Se muestra al cliente la CLABE recurrente 646180111802075448 para que realice el pago

En esta captura se muestra cómo el Checkout presenta la CLABE recurrente al cliente cuando selecciona transferencia.


5. Crear órdenes subsecuentes

Para crear más órdenes con la misma CLABE, simplemente repite el paso 4 con el parámetro reuse_customer_clabe: true.

curl --request POST \
  --url https://api.conekta.io/orders \
  --header 'accept: application/vnd.conekta-v2.2.0+json' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer key_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "currency": "MXN",
    "reuse_customer_clabe": true,
    "customer_info": {
      "customer_id": "cus_2ztR5QVktcPxj6UGm"
    },
    "line_items": [{
      "name": "Renovación Anual",
      "unit_price": 500000,
      "quantity": 1
    }],
    "checkout": {
      "type": "Integration",
      "allowed_payment_methods": ["bank_transfer"]
    }
  }'

Respuesta:

{
  "id": "ord_2ztRBxYZpqrStuVw",
  "checkout": {
    "id": "9d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7g"
  },
  "charges": null
}
📘

Cada vez que el cliente acceda al Checkout y seleccione transferencia, verá la misma CLABE 646180111802075448.

Manejo de errores

Error: customer_id faltante

Si envías reuse_customer_clabe: true sin proporcionar customer_info.customer_id, recibirás:

curl --request POST \
  --url https://api.conekta.io/orders \
  --header 'accept: application/vnd.conekta-v2.2.0+json' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer key_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "currency": "MXN",
    "reuse_customer_clabe": true,
    "customer_info": {
      "name": "Juan Perez",
      "email": "[email protected]",
      "phone": "+5215555555555"
    },
    "line_items": [{
      "name": "Producto 1",
      "unit_price": 50000,
      "quantity": 1
    }],
    "checkout": {
      "type": "Integration",
      "allowed_payment_methods": ["bank_transfer"]
    }
  }'

Respuesta:

{
  "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 SPEI no encontrada

Si el cliente no tiene una referencia SPEI recurrente creada, recibirás:

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

Respuesta:

{
  "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 spei_recurrent para el cliente (ver paso 3).

Error: Tipo de dato inválido

Si envías reuse_customer_clabe con un valor que no es booleano (por ejemplo, un string), recibirás un error de validación:

{
  "details": [
    {
      "debug_message": "The \"reuse_customer_clabe\" parameter is invalid.",
      "message": "El parámetro reuse_customer_clabe es inválido.",
      "param": "reuse_customer_clabe",
      "code": "conekta.errors.parameter_validation.reuse_customer_clabe.invalid_datatype"
    }
  ],
  "object": "error",
  "type": "parameter_validation_error"
}

HTTP Status: 422 Unprocessable Entity

Comportamiento por defecto

Si no incluyes el parámetro reuse_customer_clabe o lo estableces en false, se generará una nueva CLABE única para cada orden:

curl --request POST \
  --url https://api.conekta.io/orders \
  --header 'accept: application/vnd.conekta-v2.2.0+json' \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer key_xxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "currency": "MXN",
    "customer_info": {
      "customer_id": "cus_2ztR5QVktcPxj6UGm"
    },
    "line_items": [{
      "name": "Compra única",
      "unit_price": 10000,
      "quantity": 1
    }],
    "checkout": {
      "type": "Integration",
      "allowed_payment_methods": ["bank_transfer"]
    }
  }'
📘

Cuando el cliente acceda al Checkout y seleccione transferencia, se generará una CLABE única diferente (por ejemplo 646180111812345678) en lugar de usar la referencia recurrente 646180111802075448.

Documentación relacionada:

Updated 3 days ago