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: 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": "1739858399"
  }'

Response when creating a Payment Intent for a Cash Payment

After making the request, Fintoc will respond with the Payment Intent with the status created including the payment_type_options.cashcontaining the information of the Cash Payment reference:

{
  "id": "pi_BO381oEATXonG6bj",
  "object": "payment_intent",
  "amount": 1000,
  "currency": "MXN",
  "status": "created",
  "transaction_date": "2025-02-15T15:24:15.474Z",
  "metadata": {
    "order": "#987654321"
  },
  "error_reason": null,
  "mode": "live",
  "expires_at": "2025-02-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-02-15T15:23:11.474Z"
}

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.

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:

• Complete list of locations
• List of locations for amount above 5,000.00 MXN

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 Location

Some 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-02-15T16:10:00.000Z",
  "data": {
    "id": "pi_BO381oEATXonG6bj",
    "object": "payment_intent",
    "amount": 1000,
    "currency": "MXN",
    "status": "succeeded"
  }
}

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

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 bellow:

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

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

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.