Accept an OXXO payment
Learn how to accept OXXO, a common payment method in Mexico.
Caution
Stripe automatically presents your customers payment method options by evaluating their currency, payment method restrictions, and other parameters. We recommend that you configure your payment methods from the Stripe Dashboard using the instructions in Accept a payment.
If you want to continue manually configuring the payment methods you present to your customers with Checkout, use this guide. Otherwise, update your integration to configure payment methods in the Dashboard.
OXXO is a single use payment method where customers are required to take additional steps to complete their payment. Customers pay by providing an OXXO voucher with a generated number and cash payment at an OXXO convenience store.
Determine compatibility![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
A Checkout Session must satisfy all of the following conditions to support OXXO payments:
- Prices for all line items must be in the same currency. If you have line items in different currencies, create separate Checkout Sessions for each currency.
- You can only use one-time line items (recurring subscription plans are not supported).
Accept a payment![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Note
Build an integration to accept a payment with Checkout before using this guide.
Use this guide to learn how to enable OXXO—it shows the differences between accepting a card payment and using OXXO.
Enable OXXO as a payment method![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
When creating a new Checkout Session, you need to:
- Add
oxxo
to the list ofpayment_
method_ types - Make sure all your
line_
use theitems mxn
currency.
Additional payment method options![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
You can specify an optional expires_
parameter in the payment method options for your Session
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_
to 2, the OXXO voucher will expire on Wednesday at 23:59 America/Mexico_City (UTC-6) time. The expires_
parameter can be set from 1 to 7 days. The default is 3 days.
Redirect to Stripe hosted voucher page![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
After submitting the Checkout form successfully, the customer is redirected to the hosted_
. The customer can find the barcode or print the OXXO voucher from the hosted voucher page. You can locate the hosted_
in payment_intent.next_action.oxxo_display_details.
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 Print button
- Brand color—used as the background color
Fulfill your orders![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Because OXXO is a delayed notification payment method, you need to use a method such as webhooks to monitor the payment status and handle order fulfillment. Learn more about setting up webhooks and fulfilling orders.
The following events are sent when the payment status changes:
Event Name | Description | Next steps |
---|---|---|
The customer has successfully submitted the Checkout form. Stripe has generated the OXXO voucher. You can choose to email the | Wait for the customer to pay the OXXO voucher. | |
checkout.session.async_payment_succeeded | The customer has successfully paid the OXXO. The PaymentIntent transitions to succeeded . | Fulfill the goods or services that the customer purchased. |
checkout.session.async_payment_failed | The OXXO voucher has expired, or the payment has failed for some other reason. The PaymentIntent returns to a status of requires_ . | Contact the customer via email and request that they place a new order. |
Test your integration![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
When testing your Checkout integration, select OXXO as the payment method and click the Pay button.
Description | |
---|---|
| Simulates an OXXO voucher which a customer pays after 3 minutes and the Example: [email protected] |
| Simulates an OXXO voucher which a customer pays immediately and the Example: [email protected] |
| Simulates an OXXO voucher which expires before a customer pays and the The Example: [email protected] |
| Simulates an OXXO voucher which expires before a customer pays and the The Example: [email protected] |
| Simulates an OXXO voucher which expires before a customer pays and the Example: [email protected] |