Cash Payments (Mexico Only)

You can accept cash payments from customers in Mexico by using the Payment Intent API. Customers pay by providing a reference (number or barcode) at any of the +13,000 locations available. Fintoc notifies you when the payment is completed.

Create a payment

Using your Secret Key, create a Payment Intent on your server with an amount, currency(only MXN for Cash Payments) and 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",
    "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',
  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',
    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.
`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 the payment_type_options.cash containing the information of the Cash Payment reference:

{
  "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"
    }
  },
  "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.

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. Example of voucher based on the amount of the payment:

If you want to show customized instructions to your customer, you can also use barcode_url, reference_number and images of the lists of locations:

We recommend prioritizing the barcode as the preferred method of presentation at the location, as it enables a faster payment process compared to dictating the reference number.

Maximum Amount Limit by LocationSome locations only accept payments up to 5,000.00 MXN, while others have no maximum limit. You should display specific logos and a list of all locations based on the payment amount, as shown in the example voucher above.

Handle post-payments 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 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.

{
  "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 Payments is successfull	Complete the customers’s order
`payment_intent.expired`	Sent when the Cash Payments is expired and not available anymore 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 like in the example below:

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')

After expired, your customer will not be able to pay using the reference.

Test your integration

To simulate a successful or expired Cash Payment, you can use one of the following amounts when creating the Payment Intent of payment_type: cash

Amount	Final Result
Any value except 50000	succeeded
50000	expired

In test mode, the succeeded scenario have 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 or wait for the end of the expiration time to receive the payment_intent.expired event.

Home

Resources

Payments

Transfers

Movements

Cash Payments (Mexico Only)

Create a payment

Response when creating a Payment Intent for a Cash Payment

Handle post-payments events

Expire a payment in progress

Test your integration

​Create a payment

​Response when creating a Payment Intent for a Cash Payment

​Share the reference and instructions to pay with your customer

​Handle post-payments events

​Expire a payment in progress

​Test your integration

Create a payment

Response when creating a Payment Intent for a Cash Payment

Share the reference and instructions to pay with your customer

Handle post-payments events

Expire a payment in progress

Test your integration