Skip to main content
Esta guía explica cómo recolectar un método de pago de tu cliente para luego mandar cargos automáticos que se realicen sin su intervención. Los cargos automáticos te permiten cobrar a tus clientes de forma recurrente o puntual sin que ellos tengan que autorizar cada transacción individualmente. Una vez que tienes un método de pago enlazado a un cliente, puedes hacer cargos sin intervención del usuario.
Los cargos automáticos requieren que el cliente haya proporcionado previamente su consentimiento y un método de pago válido.

​
1. Crea un cliente

El primer paso es crear un cliente en tu sistema. Este cliente será quien proporcionará el método de pago para los cargos automáticos.
POST /v1/customers
{
  "input": {
    "name": "María González",
    "username": "12345",
    "email": "[email protected]",
    "phoneNumber": "+525555123456"
  }
}

​
2. Recolecta un método de pago

Antes de realizar cargos automáticos, el cliente debe proporcionar un método de pago válido (tarjeta de crédito/débito o cuenta bancaria). Este paso se realiza a través del Portal de Clientes, donde se le solicita al usuario que guarde su método de pago para cargos futuros. Tienes 2 opciones para recolectar un método de pago:
  1. En una sesión de pago (PaymentSession)
  2. En una sesión de inscripción

​
Opción 1: En una sesión de pago (PaymentSession)

POST /v1/payment-sessions
{
  "input": {
    "returnUrl": "https://miapp.com/success",
    "cancelUrl": "https://miapp.com/declined",
    "customer": {
      "name": "Mariana López",
      "externalId": "1337"
    },
    "expiresAt": "2025-04-22T15:47:15.250Z",
    "description": "Mensualidad",
    "amount": 239000,
    "currency": "MXN"
  }
}

​
Opción 2: En una sesión de inscripción

Las sesiones de inscripción te permiten recolectar métodos de pago sin realizar un cobro inmediato. Esta opción es ideal para configurar suscripciones o periodos de prueba.
Las sesiones de inscripción son una característica experimental y pueden estar sujetas a cambios.
POST /v1/setup-sessions
{
  "input": {
    "customer": {
      "name": "María González",
      "externalId": "12345",
      "email": "[email protected]",
      "phoneNumber": "+525555123456"
    },
    "displayMode": "CUSTOMER_PORTAL",
    "returnUrl": "https://miapp.com/exito",
    "cancelUrl": "https://miapp.com/cancelado"
  }
}
Consulta la guía completa de sesiones de inscripción para aprender cómo implementar esta funcionalidad paso a paso.

​
3. Obtén los métodos de pago del cliente

Una vez que el cliente ha guardado un método de pago, puedes consultarlos para obtener el paymentMethodId que necesitarás para realizar cargos automáticos. 
GET /v1/customers/{customerId}/payment_methods

​
Ejemplo de respuesta

Respuesta
[
  {
    "id": "pm_clvqmr51j000408jyhcth2rjy",
    "createdAt": "2025-01-15T20:30:00.000Z",
    "updatedAt": "2025-01-15T20:30:00.000Z",
    "customerId": "cus_1234567890",
    "type": "CARD",
    "confirmed": true,
    "default": true,
    "expired": false,
    "cardDetail": {
      "id": "crd_1234567890",
      "createdAt": "2025-01-15T20:30:00.000Z",
      "updatedAt": "2025-01-15T20:30:00.000Z",
      "expiryMonth": 12,
      "expiryYear": 2028,
      "cardholder": "MARIA GONZALEZ",
      "bin": "424242",
      "last4": "4242",
      "brand": "visa",
      "issuer": "BANCOMER",
      "isCorporate": false,
      "country": "MX",
      "funding": "credit"
    },
    "bankAccount": null
  },
  {
    "id": "pm_clvqmr51j000408jyhcth2abc",
    "createdAt": "2025-01-10T15:20:00.000Z",
    "updatedAt": "2025-01-10T15:20:00.000Z",
    "customerId": "cus_1234567890",
    "type": "MEXICAN_BANK_ACCOUNT",
    "confirmed": true,
    "default": false,
    "expired": false,
    "cardDetail": null,
    "bankAccount": {
      "id": "ba_1234567890",
      "createdAt": "2025-01-10T15:20:00.000Z",
      "updatedAt": "2025-01-10T15:20:00.000Z",
      "bankCode": "012",
      "bankName": "BBVA México",
      "customerId": "cus_1234567890",
      "country": "MX",
      "verified": true,
      "clabeLast": "5678",
      "clabeFirst": "0123"
    }
  }
]

​
Campos importantes

  • id: El identificador del método de pago que usarás en el campo paymentMethodId al realizar cargos.
  • type: El tipo de método de pago (CARD para tarjetas o MEXICAN_BANK_ACCOUNT para cuentas bancarias).
  • default: Indica si es el método de pago predeterminado del cliente.
  • confirmed: Indica si el método de pago ha sido confirmado con al menos un pago exitoso.
  • expired: Indica si el método de pago ha expirado (solo aplica para tarjetas).
  • cardDetail: Detalles de la tarjeta (cuando type es CARD).
  • bankAccount: Detalles de la cuenta bancaria (cuando type es MEXICAN_BANK_ACCOUNT).
El método de pago con default: true será el que se use automáticamente en las suscripciones si no se especifica uno diferente.

​
4. Realiza un cargo automático

Una vez que tienes un cliente con un método de pago válido, puedes realizar cargos automáticos usando el endpoint de pagos.
El endpoint de pagos (/v1/payments) se encuentra actualmente en etapa beta y puede estar sujeto a cambios.

​
Ejemplo de solicitud

POST /v1/payments
{
  "input": {
    // El monto a cobrar (en centavos)
    "amount": 399900,
    "currency": "MXN",
    "description": "Mensualidad",
    // El ID de un método de pago (tarjeta o cuenta bancaria)
    "paymentMethodId": "pm_1234567890",
    "customerId": "cus_1234567890",
    // Este campo es importante para que el cargo se intente de forma inmediata
    "makeAttempt": true,
    // Campos arbitrarios que serán registrados en el objeto Payment
    "meta": {
      "orderId": "order_1234567890",
      "serviceType": "subscription"
    }
  }
}

​
Campos relevantes

  • amount: El monto a cobrar en centavos. Por ejemplo, $3,999.00 MXN = 399900 centavos.
  • paymentMethodId: El identificador del método de pago previamente recolectado del cliente.
  • customerId: El identificador del cliente al que se le realizará el cargo.
  • description: Una descripción clara del concepto que se está cobrando.
  • makeAttempt: Si es true, se hará el intento de cargo al enviar la petición. Si es false, se creará el pago pero no se hará el intento de cargo.
  • metadata: Información adicional que quieras asociar con el pago para tu referencia.

​
Posibles respuestas

​
Intento exitoso

Cuando el cargo es exitoso, verás la propiedad attempt.success como true.
Respuesta (intento exitoso)
{
    "payment": {
        "id": "p_1234567890",
        "createdAt": "2025-01-15T21:00:00.000Z",
        "amount": 399900,
        "currency": "MXN",
        "type": "CARD",
        "status": "COMPLETED",
        "description": "Mensualidad",
        "paymentMethodId": "pm_1234567890",
        "customerId": "cus_1234567890",
        "meta": {
            "orderId": "order_1234567890",
            "serviceType": "subscription"
        },
    },
    "attempt": {
      "id": "pa_1234567890",
      "createdAt": "2025-01-15T21:00:00.000Z",
      "success": true,
      "scheduled": false,
      "wasAttemptedByOrganization": true,
      "errorType": null,
      "attemptNumber": 1
    },
    "customer": {
      "id": "cus_1234567890",
      "name": "Alicia Ríos",
      "email": "[email protected]",
      "phoneNumber": "<número_de_celular>",
      "username": "12345",
      "meta": {}
    }
}

​
Intento fallido

Para identificar un cargo fallido, debes revisar el campo success. Puedes obtener el motivo del rechazo usando el campo errorType del objeto attempt.
Toma en cuenta que cuando un intento es fallido, el código HTTP de la respuesta será 200
Respuesta (intento fallido)
{
    "payment": {
        "id": "p_1234567890",
        "createdAt": "2025-01-15T21:00:00.000Z",
        "amount": 399900,
        "currency": "MXN",
        "type": "CARD",
        "status": "INCOMPLETE",
        "description": "Mensualidad",
        "paymentMethodId": "pm_1234567890",
        "customerId": "cus_1234567890",
        "meta": {
            "orderId": "order_1234567890",
            "serviceType": "subscription"
        },
    },
    "attempt": {
      "id": "pa_1234567890",
      "createdAt": "2025-01-15T21:00:00.000Z",
      "success": false,
      "scheduled": false,
      "wasAttemptedByOrganization": true,
      "errorType": "INSUFFICIENT_FUNDS",
      "attemptNumber": 1
    },
    "customer": {
      "id": "cus_1234567890",
      "name": "Alicia Ríos",
      "email": "[email protected]",
      "phoneNumber": "<número_de_celular>",
      "username": "12345",
      "meta": {}
    }
}

​
Intento iniciado

Cuando el método de pago que se usa es de tipo DIRECT_DEBIT, el pago se creará con estado INITIATED y la propiedad attempt será null. En estos casos, para monitorear el resultado, debes usar un webhook de tipo PAYMENT_ATTEMPT_SUCCEEDED o PAYMENT_ATTEMPT_FAILED.
Esto solo aplica para pagos con domiciliación bancaria (tipo DIRECT_DEBIT). Los pagos con tarjeta de crédito o débito se procesan de forma inmediata.
Respuesta (intento iniciado)
{
    "payment": {
        "id": "p_1234567890",
        "createdAt": "2025-01-15T21:00:00.000Z",
        "amount": 399900,
        "currency": "MXN",
        "type": "CARD",
        "status": "INITIATED",
        "description": "Mensualidad",
        "paymentMethodId": "pm_1234567890",
        "customerId": "cus_1234567890",
        "meta": {
            "orderId": "order_1234567890",
            "serviceType": "subscription"
        },
    },
    // Este campo será null para pagos con domiciliación bancaria
    "attempt": null,
    "customer": {
      "id": "cus_1234567890",
      "name": "Alicia Ríos",
      "email": "[email protected]",
      "phoneNumber": "<número_de_celular>",
      "username": "12345",
      "meta": {}
    }
}

​
Formas de pago soportadas

Este endpoint soporta dos formas de pago, cada una con diferentes tiempos de procesamiento:
Lo que determina qué forma de pago se usa es el tipo del método de pago (PaymentMethod.type) que proporcionas en el campo paymentMethodId al mandar el pago.

​
Tarjetas de crédito/débito (CARD)

Los pagos con tarjeta de crédito o débito se procesan de forma inmediata. Obtienes la confirmación del resultado del pago en tiempo real a través de la respuesta de la petición a POST /v1/payments.

​
Domiciliación bancaria (DIRECT_DEBIT)

Los pagos mediante domiciliación bancaria (cuentas CLABE) no se confirman inmediatamente. El proceso funciona así:
  1. Al crear el pago: Recibes una respuesta con estado INITIATED
  2. Procesamiento: El cargo se envía al sistema bancario
  3. Confirmación: Debes esperar hasta el siguiente día hábil para obtener la respuesta definitiva (mediante webhooks)

​
Ejemplo de respuesta

{
    "payment": {
        "id": "p_1234567890",
        "createdAt": "2025-01-15T21:00:00.000Z",
        "amount": 399900,
        "currency": "MXN",
        "type": "DIRECT_DEBIT",
        "status": "INITIATED",
        "description": "Mensualidad",
        "paymentMethodId": "pm_1234567890",
        "customerId": "cus_1234567890",
        "meta": {
            "orderId": "order_1234567890",
            "serviceType": "subscription"
        },
    }
}
Para pagos con domiciliación bancaria, los webhooks son esenciales ya que no obtienes confirmación inmediata. Debes monitorear los eventos PAYMENT_ATTEMPT_SUCCEEDED y PAYMENT_ATTEMPT_FAILED para conocer el resultado final del cargo.

​
Estados del pago

Después de crear un cargo automático, el pago pasará por diferentes estados:
  • INCOMPLETE: El pago está siendo procesado por el sistema bancario.
  • COMPLETE: El pago se completó exitosamente.
  • INITIATED: El pago ha sido programado y está pendiente de procesamiento.
  • CANCELED: El pago fue cancelado; no se admitirá.

​
Monitoreo con webhooks

Para mantener tu integración sincronizada con el estado de los pagos, puedes suscribirte a los siguientes webhooks:

​
Eventos de intentos de pago

  • PAYMENT_ATTEMPT_SUCCEEDED: Se envía cuando un intento de cobro automático es exitoso.
  • PAYMENT_ATTEMPT_FAILED: Se envía cuando un intento de cobro automático falla, incluyendo el código de error correspondiente.

​
Eventos de métodos de pago

  • PAYMENT_METHOD_CREATED: Se envía cuando un cliente guarda un nuevo método de pago (tarjeta o cuenta bancaria) que podrás usar para cargos automáticos.
Consulta la documentación completa de webhooks para ver todos los eventos disponibles y sus estructuras.
Para casos de uso más complejos con pagos recurrentes programados, considera usar suscripciones con pagos definidos que ofrecen mayor flexibilidad y control.