> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Pagos en efectivo (Solo México)
> Aprende a usar la API de Payment Intent para crear un pago en efectivo
Puedes aceptar pagos en efectivo de clientes en México usando la API de Payment Intent. Los clientes pagan proporcionando una referencia (número o código de barras) en cualquiera de las +13.000 ubicaciones disponibles. Fintoc te notifica cuando el pago se completa.
## Crea un pago
Usando tu Secret Key, crea un `Payment Intent` en tu servidor con un `amount`, `currency` (solo MXN para pagos en efectivo) y `payment_type: "cash"`.
```curl theme={null}
curl --request POST \
--url https://api.fintoc.com/v1/payment_intents \
--header 'Authorization: sk_live_0000000000000000' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data
'{
"amount": 1000,
"currency": "MXN",
"payment_type": "cash",
"metadata": {
"order": "#987654321"
},
"expires_at": "2025-12-18T23:599"
}'
```
```node theme={null}
// You need to install Fintoc's Node SDK first: https://docs.fintoc.com/docs/accept-a-payment-copy#optional-install-our-backend-sdk
const paymentIntent = await fintoc.paymentIntents.create({
amount: 1000,
currency: 'mxn',
customer_email: 'name@example.com',
payment_type: 'cash',
expires_at: '1753148236',
metadata: {
order: '987654321'
}
});
```
```python theme={null}
# You need to install Fintoc's Python SDK first: https://docs.fintoc.com/docs/accept-a-payment-copy#optional-install-our-backend-sdk
payment_intent = client.payment_intents.create(
amount=1000,
currency='mxn',
customer_email='name@example.com',
payment_type='cash',
expires_at='1753148236',
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` | Moneda que se usa para el pago. Actualmente solo soportamos MXN para pagos en efectivo. |
| `payment_type` | `["cash"]` | Tipo de pago disponible para el cliente. |
| `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` | 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 responderá con el Payment Intent con el estado `created` incluyendo `payment_type_options.cash` que contiene la información de la referencia del pago en efectivo:
```json theme={null}
{
"id": "pi_BO381oEATXonG6bj",
"object": "payment_intent",
"amount": 1000,
"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"
}
},
"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. |
### 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.
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:
* [Lista completa de ubicaciones](http://assets.fintoc.com/cash_assets/available_locations)
* [Lista de ubicaciones para montos superiores a 5.000,00 MXN](http://assets.fintoc.com/cash_assets/available_locations_without_amount_limit)
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 de monto por ubicación**
Algunas 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](/es/docs/resources/webhooks-walkthrough) 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.
```json theme={null}
{
"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": 1000,
"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 es exitoso | 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](/es/reference/payments-api/cash/cash-payment-intents-expire) como en el ejemplo a continuación:
```curl curl theme={null}
curl --request POST \
--url https://api.fintoc.com/v1/payment_intents/{id}/expire \
--header 'Authorization: sk_live_0000000000000000' \
--header 'accept: application/json'
```
```node theme={null}
const paymentIntent = await fintoc.paymentIntents.expire('pi_000000000');
```
```python theme={null}
payment_intent = client.payment_intents.expire('pi_00000000000')
```
Después de expirado, tu cliente no podrá pagar usando la referencia.
# Prueba tu integración
Para simular un pago en efectivo exitoso o expirado, puedes usar uno de los siguientes montos al crear el Payment Intent de `payment_type: cash`
| **Monto** | **Resultado final** |
| ----------------------------- | ------------------- |
| Cualquier valor excepto 50000 | succeeded |
| 50000 | expired |
En modo de prueba, el escenario `succeeded` tiene 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](/es/reference/payments-api/cash/cash-payment-intents-expire) o esperar al final del tiempo de expiración para recibir el evento `payment_intent.expired`.