> ## 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.

# Accept cash payments in Mexico

> Create a cash Payment Intent with the Fintoc API to accept cash payments in Mexico at convenience stores, and reconcile them via webhook.

You can accept cash payments from customers in Mexico. Customers pay by providing a reference (number or barcode) at more than 13,000 available locations. Fintoc notifies you after the customer completes the payment.

You can offer cash in three ways:

* **Payment Links**: If your organization has cash enabled, your [Payment Links](https://docs.fintoc.com/guides/payments/payment-links.md) offer cash automatically.
* **Checkout Sessions**: Add `cash` to `payment_method_types` when you create an `MXN` [Checkout Session](https://docs.fintoc.com/guides/payments/accept-a-payment.md). Your customer chooses to pay in cash on the Fintoc-hosted checkout page.
* **Payment Intent API**: Create a cash `PaymentIntent` directly and show the reference to your customer, as described in this guide.

## Offer cash in a Checkout Session

Include `cash` in `payment_method_types` on its own, or combine it with `card` and `bank_transfer`. You can't combine `cash` with `installments`.

**Server**

```bash theme={null}
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 responds with the session object, including `cash` in `payment_method_types`:

```json theme={null}
{
  "id": "cs_li5531onlFDi235",
  "object": "checkout_session",
  "mode": "test",
  "status": "created",
  "amount": 250000,
  "currency": "MXN",
  "created_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"
  ]
}
```

To have Fintoc send the cash voucher to your customer, include `customer_email` or `customer_phone` (E.164 format, for example `+525512345678`) when you create the session. You can also set `payment_method_options.cash.notification_preferences` with the same options described in [Configure voucher notifications](#configure-voucher-notifications). Fintoc copies the phone number and preferences to the cash payment when your customer chooses cash. If `customer_phone` isn't in E.164 format, Fintoc returns an `invalid_phone` error.

If your customer's card or bank transfer payment fails and `cash` is available in the session, your customer can retry the payment in cash from the same checkout.

To finish the integration, follow the [Accept a payment](https://docs.fintoc.com/guides/payments/accept-a-payment.md) guide.

## Offer cash in a Payment Link

If your organization has cash enabled, every `MXN` [Payment Link](https://docs.fintoc.com/guides/payments/payment-links.md) you create offers cash. You don't need to send any extra parameter. Your customer sees a **Paga en efectivo** option next to the other payment methods and can generate a voucher to pay at the store.

Fintoc doesn't show the cash option when:

* No store accepts the Payment Link's amount.
* Your organization's checkout session lasts less than the time your customer needs to pay in cash.

## Create a payment

Using your secret key, create a `PaymentIntent` on your server with an `amount`, `currency` (`MXN` only for cash payments), and `payment_type: "cash"`.

```bash theme={null}
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"
  }'
```

```javascript Node theme={null}
// 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'
  }
});
```

```python theme={null}
# 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'
    }
)
```

| Parameter | Example | Explanation |
| - | - | - |
| `amount` | `2476` | Positive integer in the smallest currency unit. For MXN, `2476` represents MXN 24.76. The minimum for cash payments is `2000` (MXN 20.00). |
| `currency` | `MXN` | Three-letter ISO 4217 currency code. Cash payments support `MXN`. |
| `payment_type` | `cash` | Payment type for the `PaymentIntent`. Use `cash` for cash payments. |
| `customer_email` | `name@example.com` | Optional email address of your customer. Fintoc can send the voucher to this address. |
| `customer_phone` | `+525512345678` | Optional phone number of your customer in E.164 format. Fintoc can send the voucher to this number by WhatsApp. Fintoc ignores values that aren't in E.164 format. |
| `payment_type_options.cash.notification_preferences` | `{ "channels": ["email", "phone"] }` | Optional settings that control how Fintoc sends the voucher to your customer. See [Configure voucher notifications](#configure-voucher-notifications). |
| `metadata` | `{ "order": "987654321" }` | Optional set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. |
| `expires_at` | `2025-12-18T23:59:59` | Optional ISO timestamp (UTC) that indicates when the payment will expire and no longer be available for the consumer to be paid. By default, payments expire after 3 days. |

## Response when creating a Payment Intent for a cash payment

After making the request, Fintoc responds with the Payment Intent with the status `created`, including `payment_type_options.cash` with the cash payment reference:

```json theme={null}
{
  "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"
}

```

| Parameter | Example | Explanation |
| :- | :- | :- |
| `voucher_url` | `https://cash.fintoc.com/voucher/6614622682371910296083739445` | The URL for the voucher with instructions on how to complete the payment. |
| `barcode_url` | `https://assets.fintoc.com/cash_assets/sandbox_barcode` | The URL for the barcode image of the reference number. |
| `reference_number` | `6614622682371910296083739445` | Cash payment reference number. |
| `notification_preferences` | `{ "channels": ["phone"], "send_voucher": true, "send_reminders": true }` | The voucher notification settings Fintoc applies to the payment, including the defaults for any value you didn't send. |

### Share the reference and instructions to pay with your customer

After creating the payment, share the voucher with your customer for clear instructions on how to complete the payment at one of the available locations.

> [!NOTE]
>
> **Fintoc can send the voucher automatically to your customer**
>
> When you create a cash payment through the API, Fintoc sends the voucher as soon as the payment is created. Fintoc sends it by email to `customer_email` and by WhatsApp to `customer_phone`, depending on the channels in `notification_preferences`. Fintoc doesn't send the voucher if you turned off voucher notifications in your preferences or if your account suppresses customer communications. In `test` mode, Fintoc also sends real messages, so use an email address and phone number you control.
>
> You can still share the voucher through your own channels or build your own instructions with the fields below.

### Configure voucher notifications

Use `notification_preferences` to choose how Fintoc sends the voucher to your customer. Send it in `payment_type_options.cash` when you create a Payment Intent:

```json theme={null}
{
  "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
      }
    }
  }
}
```

| Parameter | Type | Explanation |
| :- | :- | :- |
| `channels` | array of strings | Channels Fintoc uses to send the voucher. Accepts `email` and `phone`. If you omit it, Fintoc uses `phone` when you send `customer_phone`. Otherwise, Fintoc uses `email` when you send `customer_email`. |
| `send_voucher` | boolean | Whether Fintoc sends the voucher when the payment is created. Defaults to `true` when you send `customer_email` or `customer_phone`. |
| `send_reminders` | boolean | Whether Fintoc sends payment reminders while the payment is pending. See [Payment reminders](#payment-reminders). Defaults to `true` when you send `customer_email` or `customer_phone`. |

Fintoc validates the preferences when you create the payment:

* If `channels` includes `email` without `customer_email`, or `phone` without `customer_phone`, Fintoc returns a `missing_parameter` error.
* If `send_voucher` or `send_reminders` is `true` and you don't send any contact, Fintoc returns a `missing_parameter` error.
* If `channels` is empty or includes a value other than `email` or `phone`, Fintoc returns an `invalid_param_value` error.

To send the voucher only by email even if you have the customer's phone, set `channels` to `["email"]`. To stop Fintoc from sending the voucher for a payment, set `send_voucher` to `false`.

#### Payment reminders

When `send_reminders` is `true`, Fintoc reminds your customer to pay a pending cash payment. Fintoc sends reminders at 10:00 and 19:00 (Mexico City time) through the same `channels` it uses for the voucher. Your customer receives up to 2 reminders per channel.

Fintoc doesn't send a reminder when:

* The payment is in `test` mode.
* The payment was created less than 6 hours ago.
* The payment expires in less than 30 minutes.
* Your account suppresses customer communications.

To turn off reminders for a payment, set `send_reminders` to `false`.

Example of a cash payment voucher:

![Cash payment voucher with the amount, available stores, and barcode.](https://mintcdn.com/fintoc-49b8bee8/3f51gOnwUSpWMLlq/images/cash-payment-voucher.svg?fit=max\&auto=format\&n=3f51gOnwUSpWMLlq\&q=85\&s=2f22c09bd9a988ff31692aafe51d8557)

If you build your own payment instructions, use `barcode_url` and `reference_number`. Prioritize the barcode so your customer doesn't need to dictate the reference number at the store.

The following table lists the Pespay chains, their maximum payment amounts, and the fees charged to the payer. All amounts are in Mexican pesos (MXN):

| Chain | Maximum payment amount (MXN) | Fee charged to the payer (MXN) |
| :- | -: | -: |
| 7 Eleven | 5,000.00 | 14.00 |
| Farmacias del Ahorro | 5,000.00 | 12.00 |
| Soriana | 10,000.00 | 10.00 |
| Super Kiosko | 6,500.00 | 12.00 |
| Waldos | 5,000.00 | 12.00 |
| Walmart (Walmart, Bodega Aurrerá, Sam's, and Walmart Express) | 10,000.00 | 12.00 |
| Chedraui (not yet available) | 10,000.00 | 10.00 |
| Circle K (not yet available) | 5,000.00 | 12.00 |
| Extra (not yet available) | 5,000.00 | 12.00 |

> [!NOTE]
>
> **Maximum amount limit by location**
>
> Show only the available chains that accept your payment amount. Each chain's maximum appears in the table above.

## Handle post-payment events

Once a Payment Intent is completed, handle the payment result using the events sent by the webhooks to complete the payment in your backend.

Fintoc sends a `payment_intent.succeeded` event when the payment is successfully completed. Use the [webhook guide](https://docs.fintoc.com/guides/resources/webhooks-walkthrough) to receive these events and run actions, such as sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

```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": 2476,
    "currency": "MXN",
    "status": "succeeded"
  }
}
```

You should handle the following events when using our Payment Initiation product:

| Event | Description | Action |
| :- | :- | :- |
| `payment_intent.succeeded` | Sent when the cash payment succeeds. | Complete the customer's order. |
| `payment_intent.expired` | Sent when the cash payment expires and is no longer available to be paid. | Cancel the order and inform the customer. |

## Expire a payment in progress

If needed, you can expire a payment that is in the `created` status using the Payment Intent [expire endpoint](https://docs.fintoc.com/api/payments-api/cash/cash-payment-intents-expire.md) like in the example below:

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

```javascript Node theme={null}
const paymentIntent = await fintoc.paymentIntents.expire('pi_000000000');
```

```python theme={null}
payment_intent = client.payment_intents.expire('pi_00000000000')
```

After the payment expires, your customer can no longer pay using the reference.

## Refunds

Fintoc doesn't support refunds for cash payments. If you [create a refund](https://docs.fintoc.com/api/payments-api/refunds/refunds-create.md) for a cash payment, Fintoc responds with a `403 Forbidden` error with the code `payment_method_not_refundable`. You also can't refund a cash payment from the [Dashboard](https://dashboard.fintoc.com). To return money to a customer who paid in cash, use a channel outside of Fintoc refunds.

## Test your integration

To simulate a successful or expired cash payment, use one of the following amounts when creating the `PaymentIntent` with `payment_type: "cash"`:

| Amount | Final result |
| - | - |
| Any value except `50000` | `succeeded` |
| `50000` | `expired` |

In test mode, the `succeeded` scenario delivers an immediate webhook notification of the `payment_intent.succeeded` event.

For the `expired` scenario, the Payment Intent goes to the `created` status, so you can test the endpoint to [expire a Payment Intent](https://docs.fintoc.com/api/payments-api/cash/cash-payment-intents-expire.md) or wait for the end of the expiration time to receive the `payment_intent.expired` event.
