Acepta pagos en efectivo en México

Puedes aceptar pagos en efectivo de clientes en México. Los clientes pagan proporcionando una referencia (número o código de barras) en más de 13.000 ubicaciones disponibles. Fintoc te notifica cuando el cliente completa el pago. Puedes ofrecer efectivo de tres formas:

Links de pago: Si tu organización tiene efectivo habilitado, tus Links de pago ofrecen efectivo automáticamente.
Checkout Sessions: Agrega cash a payment_method_types al crear una Checkout Session en MXN. Tu cliente elige pagar en efectivo en la página de checkout alojada por Fintoc.
API de Payment Intent: Crea un PaymentIntent en efectivo directamente y muestra la referencia a tu cliente, como se describe en esta guía.

Ofrece efectivo en una Checkout Session

Incluye cash en payment_method_types por sí solo, o combínalo con card y bank_transfer. No puedes combinar cash con installments. Servidor

curl --request POST "https://api.fintoc.com/v2/checkout_sessions" \
    --header "Authorization: YOUR_TEST_SECRET_API_KEY" \
    --header "Content-Type: application/json" \
    --data-raw '{
      "amount": 250000,
      "currency": "MXN",
      "success_url": "https://merchant.com/success",
      "cancel_url": "https://merchant.com/cancel",
      "payment_method_types": ["card", "bank_transfer", "cash"]
    }'

Fintoc responde con el objeto de la sesión, incluyendo cash en payment_method_types:

{
  "id": "cs_li5531onlFDi235",
  "object": "checkout_session",
  "mode": "test",
  "status": "created",
  "amount": 250000,
  "currency": "MXN",
  "created_at": "2024-06-04T15:32:46.721Z",
  "updated_at": "2024-06-04T15:32:46.721Z",
  "success_url": "https://merchant.com/success",
  "cancel_url": "https://merchant.com/cancel",
  "redirect_url": "https://pay.fintoc.com/checkout/cs_li5531onlFDi235",
  "metadata": {},
  "payment_method_types": [
    "card",
    "bank_transfer",
    "cash"
  ]
}

Para que Fintoc envíe el voucher de efectivo a tu cliente, incluye customer_email o customer_phone (formato E.164, por ejemplo +525512345678) al crear la sesión. También puedes definir payment_method_options.cash.notification_preferences con las mismas opciones descritas en Configura las notificaciones del voucher. Fintoc copia el teléfono y las preferencias al pago en efectivo cuando tu cliente elige efectivo. Si customer_phone no está en formato E.164, Fintoc responde con un error invalid_phone. Si el pago con tarjeta o transferencia bancaria de tu cliente falla y cash está disponible en la sesión, tu cliente puede reintentar el pago en efectivo desde el mismo checkout. Para completar la integración, sigue la guía Aceptar un pago.

Ofrece efectivo en un Link de pago

Si tu organización tiene efectivo habilitado, cada Link de pago en MXN que crees ofrece efectivo. No necesitas enviar ningún parámetro adicional. Tu cliente ve la opción Paga en efectivo junto a los otros métodos de pago y puede generar un voucher para pagar en la tienda. Fintoc no muestra la opción de efectivo cuando:

Ninguna tienda acepta el monto del Link de pago.
La sesión de checkout de tu organización dura menos que el tiempo que tu cliente necesita para pagar en efectivo.

Crea un pago

Usando tu clave secreta, crea un PaymentIntent en tu servidor con un amount, currency (solo MXN para pagos en efectivo) y payment_type: "cash".

curl --request POST \
  --url https://api.fintoc.com/v1/payment_intents \
  --header 'Authorization: YOUR_TEST_SECRET_API_KEY' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "amount": 2476,
    "currency": "MXN",
    "customer_email": "name@example.com",
    "customer_phone": "+525512345678",
    "payment_type": "cash",
    "metadata": {
      "order": "987654321"
    },
    "expires_at": "2025-12-18T23:59:59"
  }'

Node

// Install Fintoc's Node SDK before running this example: https://github.com/fintoc-com/fintoc-node

const paymentIntent = await fintoc.paymentIntents.create({
  amount: 2476,
  currency: 'MXN',
  customer_email: 'name@example.com',
  customer_phone: '+525512345678',
  payment_type: 'cash',
  expires_at: '2025-12-18T23:59:59',
  metadata: {
    order: '987654321'
  }
});

# Install Fintoc's Python SDK before running this example: https://github.com/fintoc-com/fintoc-python

payment_intent = client.payment_intents.create(
    amount=2476,
    currency='MXN',
    customer_email='name@example.com',
    customer_phone='+525512345678',
    payment_type='cash',
    expires_at='2025-12-18T23:59:59',
    metadata={
        'order': '987654321'
    }
)

Parámetro	Ejemplo	Explicación
`amount`	`2476`	Monto de dinero que debe pagarse. Se representa como un entero sin decimales en la unidad más pequeña posible de la moneda que estás usando. Un monto de MXN 24.76 se representa como 2476. El monto mínimo para un pago en efectivo es 2000 (20.00 MXN)
`currency`	`MXN`	Código ISO 4217 de tres letras de la moneda. Los pagos en efectivo soportan `MXN`.
`payment_type`	`cash`	Tipo de pago disponible para el cliente.
`customer_email`	`name@example.com`	Correo opcional de tu cliente. Fintoc puede enviar el voucher a esta dirección.
`customer_phone`	`+525512345678`	Teléfono opcional de tu cliente en formato E.164. Fintoc puede enviar el voucher a este número por WhatsApp. Fintoc ignora los valores que no están en formato E.164.
`payment_type_options.cash.notification_preferences`	`{ "channels": ["email", "phone"] }`	Configuración opcional que controla cómo Fintoc envía el voucher a tu cliente. Revisa Configura las notificaciones del voucher.
`metadata`	`{ "order": "987654321" }`	Conjunto opcional de pares clave-valor que puedes adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado.
`expires_at`	`2025-12-18T23:59:59`	Timestamp ISO opcional (UTC) que indica cuándo el pago expirará y dejará de estar disponible para que el consumidor lo pague. Por defecto, los pagos expiran después de 3 días.

Respuesta al crear un Payment Intent para un pago en efectivo

Después de hacer la solicitud, Fintoc responde con el Payment Intent en estado created, incluyendo payment_type_options.cash con la referencia del pago en efectivo:

{
  "id": "pi_BO381oEATXonG6bj",
  "object": "payment_intent",
  "amount": 2476,
  "currency": "MXN",
  "status": "created",
  "transaction_date": "2025-12-15T15:24:15.474Z",
  "metadata": {
    "order": "987654321"
  },
  "error_reason": null,
  "mode": "live",
  "expires_at": "2025-12-18T05:59:59.000Z",
  "payment_type": "cash",
  "payment_type_options": {
    "cash": {
      "reference_number": "6614622682371910296083739445",
      "barcode_url": "https://assets.fintoc.com/cash_assets/sandbox_barcode",
      "voucher_url": "https://cash.fintoc.com/voucher/6614622682371910296083739445",
      "notification_preferences": {
        "channels": ["phone"],
        "send_voucher": true,
        "send_reminders": true
      }
    }
  },
  "created_at": "2025-12-15T15:23:11.474Z"
}

Parámetro	Ejemplo	Explicación
`voucher_url`	`https://cash.fintoc.com/voucher/6614622682371910296083739445`	La URL del voucher con instrucciones para completar el pago.
`barcode_url`	`https://assets.fintoc.com/cash_assets/sandbox_barcode`	La URL de la imagen del código de barras del número de referencia.
`reference_number`	`6614622682371910296083739445`	Número de referencia del pago en efectivo.
`notification_preferences`	`{ "channels": ["phone"], "send_voucher": true, "send_reminders": true }`	La configuración de notificaciones del voucher que Fintoc aplica al pago, incluyendo los valores por defecto de lo que no enviaste.

Comparte la referencia y las instrucciones de pago con tu cliente

Después de crear el pago, comparte el voucher con tu cliente para que tenga instrucciones claras sobre cómo completar el pago en una de las ubicaciones disponibles.

Fintoc envía el voucher automáticamenteCuando creas un pago en efectivo por API, Fintoc envía el voucher apenas se crea el pago. Fintoc lo envía por correo a customer_email y por WhatsApp a customer_phone, según los canales de notification_preferences. Fintoc no envía el voucher si desactivaste las notificaciones del voucher en tus preferencias o si tu cuenta suprime las comunicaciones a clientes. En modo test, Fintoc también envía mensajes reales, así que usa un correo y un teléfono que controles.Igual puedes compartir el voucher por tus propios canales o armar tus propias instrucciones con los campos de abajo.

Configura las notificaciones del voucher

Usa notification_preferences para elegir cómo Fintoc envía el voucher a tu cliente. Envíalo en payment_type_options.cash al crear un Payment Intent:

{
  "amount": 2476,
  "currency": "MXN",
  "payment_type": "cash",
  "customer_email": "name@example.com",
  "customer_phone": "+525512345678",
  "payment_type_options": {
    "cash": {
      "notification_preferences": {
        "channels": ["email", "phone"],
        "send_voucher": true
      }
    }
  }
}

Parámetro	Tipo	Explicación
`channels`	arreglo de strings	Canales que Fintoc usa para enviar el voucher. Acepta `email` y `phone`. Si lo omites, Fintoc usa `phone` cuando envías `customer_phone`. Si no, Fintoc usa `email` cuando envías `customer_email`.
`send_voucher`	boolean	Indica si Fintoc envía el voucher al crear el pago. Por defecto es `true` cuando envías `customer_email` o `customer_phone`.
`send_reminders`	boolean	Indica si Fintoc envía recordatorios de pago mientras el pago está pendiente. Revisa Recordatorios de pago. Por defecto es `true` cuando envías `customer_email` o `customer_phone`.

Fintoc valida las preferencias al crear el pago:

Si channels incluye email sin customer_email, o phone sin customer_phone, Fintoc responde con un error missing_parameter.
Si send_voucher o send_reminders es true y no envías ningún contacto, Fintoc responde con un error missing_parameter.
Si channels está vacío o incluye un valor distinto de email o phone, Fintoc responde con un error invalid_param_value.

Para enviar el voucher solo por correo aunque tengas el teléfono del cliente, define channels como ["email"]. Para que Fintoc no envíe el voucher de un pago, define send_voucher como false.

Recordatorios de pago

Cuando send_reminders es true, Fintoc le recuerda a tu cliente que pague un pago en efectivo pendiente. Fintoc envía los recordatorios a las 10:00 y a las 19:00 (hora de Ciudad de México) por los mismos channels que usa para el voucher. Tu cliente recibe hasta 2 recordatorios por canal. Fintoc no envía un recordatorio cuando:

El pago está en modo test.
El pago se creó hace menos de 6 horas.
El pago expira en menos de 30 minutos.
Tu cuenta suprime las comunicaciones a clientes.

Para desactivar los recordatorios de un pago, define send_reminders como false. Ejemplo de voucher según el monto del pago:

Si quieres mostrar instrucciones personalizadas a tu cliente, también puedes usar barcode_url, reference_number e imágenes de las listas de ubicaciones:

Recomendamos priorizar el código de barras como el método preferido de presentación en la ubicación, ya que permite un proceso de pago más rápido en comparación con dictar el número de referencia.

Límite máximo por ubicaciónAlgunas ubicaciones solo aceptan pagos hasta 5.000,00 MXN, mientras que otras no tienen un límite máximo. Debes mostrar logos específicos y una lista de todas las ubicaciones según el monto del pago, como se muestra en el voucher de ejemplo anterior.

Maneja los eventos posteriores al pago

Una vez que un Payment Intent se completa, maneja el resultado del pago usando los eventos enviados por los webhooks para completar el pago en tu backend. Fintoc envía un evento payment_intent.succeeded cuando el pago se completa exitosamente. Usa la guía de webhooks para recibir estos eventos y ejecutar acciones, como enviar un correo de confirmación de orden a tu cliente, registrar la venta en una base de datos o iniciar un flujo de envío.

{
  "id": "evt_987654321",
  "type": "payment_intent.succeeded",
  "object": "event",
  "created_at": "2025-12-15T16:10:00.000Z",
  "data": {
    "id": "pi_BO381oEATXonG6bj",
    "object": "payment_intent",
    "amount": 2476,
    "currency": "MXN",
    "status": "succeeded"
  }
}

Debes manejar los siguientes eventos al usar nuestro producto de Iniciación de Pagos:

Evento	Descripción	Acción
`payment_intent.succeeded`	Enviado cuando el pago en efectivo se completa con éxito.	Completa la orden del cliente.
`payment_intent.expired`	Enviado cuando el pago en efectivo expira y ya no está disponible para pagarse.	Cancela la orden e informa al cliente.

Expirar un pago en progreso

Si lo necesitas, puedes expirar un pago que está en estado created usando el endpoint expire del Payment Intent como en el ejemplo a continuación:

curl --request POST \
     --url https://api.fintoc.com/v1/payment_intents/{id}/expire \
     --header 'Authorization: YOUR_TEST_SECRET_API_KEY' \
     --header 'accept: application/json'

Node

const paymentIntent = await fintoc.paymentIntents.expire('pi_000000000');

payment_intent = client.payment_intents.expire('pi_00000000000')

Después de que el pago expira, tu cliente ya no puede pagar usando la referencia.

Prueba tu integración

Para simular un pago en efectivo exitoso o expirado, usa uno de los siguientes montos al crear el PaymentIntent con payment_type: "cash":

Monto	Resultado final
Cualquier valor excepto `50000`	`succeeded`
`50000`	`expired`

En modo de prueba, el escenario succeeded entrega una notificación inmediata por webhook del evento payment_intent.succeeded. Para el escenario expired, el Payment Intent pasa al estado created, por lo que puedes probar el endpoint para expirar un Payment Intent o esperar al final del tiempo de expiración para recibir el evento payment_intent.expired.

​Ofrece efectivo en una Checkout Session

​Ofrece efectivo en un Link de pago

​Crea un pago

​Respuesta al crear un Payment Intent para un pago en efectivo

​Comparte la referencia y las instrucciones de pago con tu cliente

​Configura las notificaciones del voucher

​Recordatorios de pago

​Maneja los eventos posteriores al pago

​Expirar un pago en progreso

​Prueba tu integración

Ofrece efectivo en una Checkout Session

Ofrece efectivo en un Link de pago

Crea un pago

Respuesta al crear un Payment Intent para un pago en efectivo

Comparte la referencia y las instrucciones de pago con tu cliente

Configura las notificaciones del voucher

Recordatorios de pago

Maneja los eventos posteriores al pago

Expirar un pago en progreso

Prueba tu integración