DashboardHome
Guides
GuidesAPI ReferenceChangelog

Cash Payments (Mexico Only)

Learn how to use the Payment Intent API to create a Cash Payment

Suggest Edits

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"
  }'
ParameterExampleExplanation
amount2476Amount of money that needs to be paid. It's represented as an integer with no decimals in the smallest possible unit of the currency you are using.

An amount of MXN 24.76 is represented as 2476.
currencyMXNCurrency that is being used for the payment. We currently only support MXN for cash payments.
payment_type["cash", "bank_transfer"]Payment types available for the customer. bank_transferrepresents payments through bank transfers (CoDi, Transferencia SPEI).
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_at1739858399Optional 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.

📘

Maximum Amount Limit by Location

All locations accept cash payments of at least up to 5,000 MXN. Some locations allow payments up to 6,500 MXN, and others have no maximum limit. You can always request the most up-to-date list of supported locations and their corresponding limits.

Response when creating a Payment Intent for a Cash Payment

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

{
  "id": "pi_BO381oEATXonG6bj",
  "object": "payment_intent",
  "amount": 1000,
  "currency": "MXN",
  "status": "in_progress",
  "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": {
      "barcode_url": "https://pay.fintoc.com/cash/barcode/h0sonigds-asgdo-gdai",
      "reference_number": "41665889973299065612615982153709210"
    }
  },
  "created_at": "2025-02-15T15:23:11.474Z"
}
ParameterExampleExplanation
barcode_urlhttps://pay.fintoc.com/cash/barcode/h0sonigds-asgdo-gdaiThe URL for the barcode image of the reference number.
reference_number41665889973299065612615982153709210Cash payment reference number.

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:

EventDescriptionAction
payment_intent.succeededSent when the Cash Payments is successfullComplete the customers's order
payment_intent.expiredSent when the Cash Payments is expired and not available anymore to be paidCancel the order and inform the customer.

Expire a payment in progress

If needed, you can expire a payment that is in the in_progress 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

AmountFinal Result
Any value except 500succeeded
500expired

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

Updated 6 days ago