Skip to content
Create account or Sign in
The Stripe Docs logo
/
Create accountSign in
OverviewUpgrade your integration
Online payments
OverviewFind your use caseUse Managed Payments
In-person payments
Payment Methods
Payment scenarios
Beyond payments

Accept an OXXO payment

Learn how to accept OXXO, a common payment method in Mexico.

Caution

The content of this section refers to a Legacy product. You should use the Accept a payment guide for the most recent integration path instead. While Stripe still supports this product, this support might end if the product is deprecated.

Stripe users in Mexico can accept OXXO payments from customers in Mexico by using the Payment Intents and Payment Methods APIs. Customers pay by providing an OXXO voucher with a generated number and cash payment at an OXXO convenience store. Stripe notifies you when the payment is completed.

What you're building

Set up Stripe
Server-side

First, you need a Stripe account. Register now.

Use our official libraries for access to the Stripe API from your application:

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Create a PaymentIntent
Server-side

Stripe uses a PaymentIntent object to represent your intent to collect payment from a customer, tracking state changes from OXXO voucher creation to payment completion.

Create a PaymentIntent on your server with an amount and the mxn currency (OXXO doesn’t support other currencies). If you already have an integration using the Payment Intents API, add oxxo to the list of payment method types for your PaymentIntent.

Command Line
curl
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "amount"=1099 \
  -d "currency"="mxn" \
  -d "payment_method_types[]"="oxxo"

Retrieve the client secret

The PaymentIntent includes a client secret that the client side uses to securely complete the payment process. You can use different approaches to pass the client secret to the client side.

Retrieve the client secret from an endpoint on your server, using the browser’s fetch function. This approach is best if your client side is a single-page application, particularly one built with a modern front-end framework such as React. Create the server endpoint that serves the client secret:

main.rb
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

And then fetch the client secret with JavaScript on the client side:

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Additional payment method options

You can specify an optional expires_after_days parameter in the payment method options for your PaymentIntent that sets the number of calendar days before an OXXO voucher expires. For example, if you create an OXXO voucher on Monday and you set expires_after_days to 2, the OXXO voucher will expire on Wednesday at 23:59 America/Mexico_City (UTC-6) time. The expires_after_days parameter can be set from 1 to 7 days. The default is 3 days.

Collect payment method details
Client-side

Create a payment form on your client to collect the required billing details from the customer:

FieldValue
nameThe full name (first and last) of the customer. The first name and last name must each be a minimum of two characters.
emailThe full email address of the customer.
checkout.html
<form id="payment-form">
  <div class="form-row">
    <label for="name">
      Name
    </label>
    <input id="name" name="name" required>
  </div>

  <div class="form-row">
    <label for="email">
      Email
    </label>
    <input id="email" name="email" required>
  </div>

  <!-- Used to display form errors. -->
  <div id="error-message" role="alert"></div>

  <button id="submit-button">Pay with OXXO</button>
</form>

Submit the payment to Stripe
Client-side

When a customer clicks to pay with OXXO, use Stripe.js to submit the payment to Stripe. Stripe.js is our foundational JavaScript library for building payment flows.

Include the Stripe.js script on your checkout page by adding it to the head of your HTML file.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Create an instance of Stripe.js with the following JavaScript on your checkout page.

client.js
// Set your publishable key. Remember to switch to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Use stripe.confirmOxxoPayment and the client secret of the PaymentIntent object that you created in Step 2 to submit the customer’s billing details.

Upon confirmation, Stripe will automatically open a modal to display the OXXO voucher to your customer.

client.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const result = await stripe.confirmOxxoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
        },
      },
    });
  // Stripe.js will open a modal to display the OXXO voucher to your customer
  // This async function finishes when the customer closes the modal

  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  }
});

Note

stripe.confirmOxxoPayment may take several seconds to complete. During that time, disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error, show it to the customer, re-enable the form, and hide the waiting indicator.

When an OXXO voucher is created successfully, the value of the returned PaymentIntent’s status property is requires_action. Check the status of a PaymentIntent in the Dashboard or by inspecting the status property on the object. If the OXXO voucher was not created successfully, inspect the returned error to determine the cause (for example, invalid email format).

Optional: Email voucher link to your customer

Stripe sends a payment_intent.requires_action event when an OXXO voucher is created successfully. If you need to email your customers the voucher link, you can retrieve the PaymentIntent to get the link upon receiving the event. The hosted_voucher_url field in payment_intent.next_action.oxxo_display_details contains the link to the voucher.

Optional: Customize your voucher

Stripe allows customization of customer-facing UIs on the Branding Settings page.

The following brand settings can be applied to the voucher:

  • Icon – your brand image and public business name
  • Accent color—used as the color of the Copy Number button
  • Brand colour – used as the background colour

Handle post-payment events
Server-side

OXXO is a delayed notification payment method, so funds are not immediately available. Customers might not pay for the OXXO voucher at an OXXO convenience store immediately after checking out.

Stripe sends a payment_intent.succeeded event on the next business day (Monday through Friday excluding Mexican holidays) for each OXXO voucher that was paid. Use the Dashboard or build a webhook handler to receive these events and run actions (for example, sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow).

After the expiry date, the PaymentIntent’s status transitions to processing and the customer can no longer pay for the expired OXXO voucher. If the OXXO voucher was not paid for before 23:59 America/Mexico_City (UTC-6) on the expiry date, Stripe sends a payment_intent.payment_failed event within 10 calendar days after the expiry date (in most cases, this event is sent within 7 calendar days). For example, if the OXXO voucher expires on 1 September, this event is sent by 10 September at the latest.

EventDescriptionNext steps
payment_intent.requires_actionThe OXXO voucher is created successfully.Wait for the customer to pay for the OXXO voucher.
payment_intent.processingThe customer can no longer pay for the OXXO voucher.Wait for the payment to succeed or fail.
payment_intent.succeededThe customer paid for the OXXO voucher before expiration.Fulfill the goods or services that the customer purchased.
payment_intent.payment_failedThe customer did not pay for the OXXO voucher before expiration.Contact the customer through email or push notification and request another payment method.

Receive events and run business actions

Manually

Use the Stripe Dashboard to view all your Stripe payments, send email receipts, handle payouts, or retry failed payments.

Custom Code

Build a webhook handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

Test the integration

In a sandbox, set payment_method.billing_details.email to the following values when you call stripe.confirmOxxoPayment to test different scenarios.

EmailDescription

{any_prefix}@{any_domain}

Simulates an OXXO voucher which a customer pays after 3 minutes and the payment_intent.succeeded webhook arrives after about 3 minutes. In production, this webhook arrives after 1 business day.

Example: fulano@test.com

{any_prefix}succeed_immediately@{any_domain}

Simulates an OXXO voucher which a customer pays immediately and the payment_intent.succeeded webhook arrives within several seconds. In production, this webhook arrives after 1 business day.

Example: succeed_immediately@test.com

{any_prefix}expire_immediately@{any_domain}

Simulates an OXXO voucher which expires before a customer pays and the payment_intent.payment_failed webhook arrives within several seconds.

The expires_after field in next_action.oxxo_display_details is set to the current time regardless of what the expires_after_days parameter in payment method options is set to.

Example: expire_immediately@test.com

{any_prefix}expire_with_delay@{any_domain}

Simulates an OXXO voucher which expires before a customer pays and the payment_intent.payment_failed webhook arrives after about 3 minutes.

The expires_after field in next_action.oxxo_display_details is set to 3 minutes in the future regardless of what the expires_after_days parameter in payment method options is set to.

Example: expire_with_delay@test.com

{any_prefix}fill_never@{any_domain}

Simulates an OXXO voucher which expires before a customer pays and the payment_intent.payment_failed webhook arrives after 1 business day and 2 calendar days. In production, this webhook arrives at the same time as in testmode.

Example: fill_never@test.com

OptionalDisplay the OXXO details to your customer
Client-side

We recommend relying on Stripe.js to handle displaying the OXXO voucher with confirmOxxoPayment. However, you can also manually display the voucher to your customers.

You can specify handleActions: false when calling stripe.confirmOxxoPayment in step 4 to indicate that you will handle the next action to display the OXXO details to your customer.

client.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const result = await stripe.confirmOxxoPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
        },
      },
    }, {handleActions: false},
  );

  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  } else {
    // An OXXO voucher was successfully created
    const amount = result.paymentIntent.amount;
    const currency = result.paymentIntent.currency;

    const details = result.paymentIntent.next_action.oxxo_display_details;
    const number = details.number;
    const expires_after = details.expires_after;

    // Handle the next action by displaying the OXXO details to your customer

    // You can also use the generated hosted voucher
    const hosted_voucher_url = result.paymentIntent.next_action.oxxo_display_details.hosted_voucher_url;
  }
});

Include, at minimum, the following:

DetailDescription

OXXO logo

Display the OXXO logo on the voucher. You can download the logo here.

NumberLocate the number on the PaymentIntent object at next_action.oxxo_display_details.number.
Expiry dateLocate the UNIX timestamp after which the OXXO voucher expires on the PaymentIntent at next_action.oxxo_display_details.expires_after.
AmountThe amount to be collected.
CurrencyOXXO vouchers are always in Mexican pesos.
BarcodeGenerate the barcode from the number using Code 128. The barcode should be approximately 7.5 cm wide when printed. For mobile displays, make sure the barcode can be zoomed in. This will help the OXXO convenience store cashier scan the barcode. You can use an external library such as JSBarcode.
Payment instructionsThe payment instructions for the customer. See the English and Spanish translations below.

OXXO payment instructions

OXXO payment instructions:

  1. Give the voucher to the cashier to scan the barcode.
  2. Provide cash payment to the cashier.
  3. After the payment is complete, keep the receipt of your payment for your records.
  4. For any questions or clarification, please contact the merchant.
HTML
CSS
JavaScript
No results
<!-- Include a library for generating OXXO bar codes, such as JsBarcode -->
<!-- <script src="https://cdn.jsdelivr.net/jsbarcode/3.6.0/barcodes/JsBarcode.code128.min.js"></script> -->

<div class="result-oxxo">
  <img width="100px" src="/images/payments/oxxo.png">
  <div class="amount">MX <span class="order-amount"></span></div>
  <div>Expires <span class="oxxo-expiry-date"></span></div>
  <div class="oxxo-display"></div>

  <button onclick="window.print()">Print</button>

  <div class="instructions">
    Instructions to pay your OXXO:
    <ol>
      <li><p>Give the voucher to the cashier to scan the barcode.</p></li>
      <li><p>Provide cash payment to the cashier.</p></li>
      <li><p>After the payment is complete, keep the receipt of your payment for your records.</p></li>
      <li><p>For any questions or clarification, please contact the merchant.</p></li>
    </ol>
  </div>
</div>

Customers will typically print out the OXXO voucher to bring to an OXXO convenience store. You can provide an easy print button and/or email the OXXO voucher to the customer. Try printing the OXXO voucher yourself to check the barcode size (which should be approximately 7.5 cm wide).

OptionalSend payment instruction emails

You can enable OXXO payment instruction emails on the Email Settings page in the Dashboard. Once enabled, Stripe sends payment instruction emails upon PaymentIntent confirmation. The emails contain the OXXO number and a link to the Stripe hosted voucher page.

Note

In testing environments, instruction emails are only sent to email addresses linked to the Stripe account.

Expiration and cancellation

OXXO vouchers expire after the expires_after UNIX timestamp and a customer can’t pay an OXXO voucher once it has expired. OXXO vouchers can’t be cancelled before expiry.

After an OXXO voucher expires, the PaymentIntent’s status changes to requires_payment_method. At this point, you can confirm the PaymentIntent with another payment method or cancel.