Accept OXXO payments

Buyer experience

Know before you code

Note: The integration steps for implementing alternative payment methods are similar. If you've integrated another alternative payment method before, you can likely reuse that code with adjustments for this payment method.

• Use Postman to explore and test PayPal APIs.

1. Add PayPal JavaScript SDK

Add or update the JavaScript SDK script on your web page.

1<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&components=buttons,payment-fields,marks,funding-eligibility&enable-funding=oxxo&currency=MXN"></script>

This table lists the parameters you pass to the JavaScript SDK.

See additional, optional parameters.

2. Render payment mark

You can use a mark integration for payment fields components to present the payment method options to the buyer as radio buttons.

1paypal.Marks({
2    fundingSource: paypal.FUNDING.OXXO
3}).render('#oxxo-mark')

3. Render payment fields

Payment fields offer easy integration to collect payment information from buyers. Fields dynamically render based on the selected funding source and you can customize the fields to align with your brand.

The OXXO payment fields collect first name, last name, and email.

If there are validation errors in the input fields, they'll show on the click of the button.

1paypal.PaymentFields({
2  fundingSource: paypal.FUNDING.OXXO,
3  /* style object (optional) */
4  style: {
5    /* customize field attributes (optional) */
6    variables: {},
7    /* set custom rules to apply to fields classes (optional) */
8    rules: {},
9  },
10  fields: {
11    /* fields prefill info (optional) */
12    name: {
13      value: "John Doe",
14    },
15    email: {
16      value: "jdoe@example.com",
17    },
18  }
19})
20.render("#oxxo-container")

Note: A multipage checkout integration is also available. This might be applicable for German merchants to comply with the 2012 Button Solution or others with a multipage checkout experience.

For style parameters, please reference this style page: Custom style for payment fields

4. Render payment button

paypal.Buttons({
  fundingSource: paypal.FUNDING.OXXO,
  style: {
    label: "pay",
  },
  createOrder() {
    return fetch("/my-server/create-paypal-order", {
      method: "post",
      // use the "body" param to optionally pass additional order information
      // like product skus and quantities
      body: JSON.stringify({
        cart: [
          {
            sku: "YOUR_PRODUCT_STOCK_KEEPING_UNIT",
            quantity: "YOUR_PRODUCT_QUANTITY",
          },
        ],
      }),
    })
    .then((response) => response.json())
    .then((order) => order.id);
  },
  onApprove(data) {
    return fetch("/my-server/capture-paypal-order", {
      method: "post",
      body: JSON.stringify({
        orderID: data.orderID
      })
    })
    .then((response) => response.json())
    .then((orderData) => {
      // Successful capture! For dev/demo purposes:
      console.log('Capture result', orderData, JSON.stringify(orderData, null, 2));
      const transaction = orderData.purchase_units[0].payments.captures[0];
      console.log('Transaction Status:',  transaction.status);
      console.log('Transaction ID:', transaction.id);
      // When ready to go live, remove the alert and show a success message within this page. For example:
      // const element = document.getElementById('paypal-button-container');
      // element.innerHTML = '<h3>Thank you for your payment!</h3>';
      // Or go to another URL:  window.location.href = 'thank_you.html';
    });
  },
  onCancel(data, actions) {
    /* Incomplete checkout. Buyer closed the window before order confirmation. */
    /* Show a message to restart the checkout process. */
    console.log(`Order Canceled - ID: ${data.orderID}`);
  },
  onError(err) {
    console.error(err);
  }
}).render("#oxxo-btn");

Use paypal.Buttons().isEligible() to check if the funding source is eligible.

1var mark = paypal.Marks({
2  fundingSource: paypal.FUNDING.OXXO
3})
4var fields = paypal.PaymentFields({
5  fundingSource: paypal.FUNDING.OXXO,
6})
7var button = paypal.Buttons({
8  fundingSource: paypal.FUNDING.OXXO
9})
10if(button.isEligible()) {
11  mark.render('#oxxo-mark');
12  fields.render("#oxxo-container");
13  button.render("#oxxo-btn");
14}

createOrder

Implement the createOrder function to allow the JavaScript SDK to submit buyer information and set up the transaction on the click of the button.

Note: OXXO requires orders to be created in a currency of MXN.

Use your server-side Create order call to set up the details of a one-time transaction including the amount, line item detail, and more.

If order creation fails, the Orders API can return an error in the console.

After order creation, orders are confirmed with buyer-selected payment source. If the order cannot be processed with the selected payment source, the relevant errors are returned in the console.

onCancel

Implement the optional onCancel() function to show a cancellation page or return to the shopping cart.

onError

Implement the optional onError() function to handle errors and display generic error message or page to the buyers. This error handler is a catch-all. Errors at this point aren't expected to be handled beyond showing a generic error message or page.

5. Handle webhook events

A webhook handler is a script you create on your server that completes specific actions on webhooks that hit your listener URL.

• CHECKOUT.ORDER.APPROVED - Listen for this webhook to retrieve order details, including the BARCODE_URL for the voucher. Use this URL to send the voucher in emails or to display it again. Order capture is performed automatically. No additional code required.
• PAYMENT.CAPTURE.PENDING - The funds for this payment were not yet credited to the payee's PayPal account. The buyer has not yet completed the transaction.
• PAYMENT.CAPTURE.COMPLETED - The funds for this payment were credited to the payee's PayPal account. The buyer completed the transaction and goods can be delivered.
• PAYMENT.CAPTURE.DENIED - The funds could not be captured. The buyer did not complete the transaction before the voucher's expiration.

See Subscribe to checkout webhooks for more information.

Here are some additional resources as you create webhook handler code:

• Webhook Management API - Manage webhooks, list event notifications, and more.
• Webhook events
  • Checkout webhook events - Checkout buyer approval-related webhooks.
  • Order webhook events - Other order-related webhooks.
• Show order details endpoint - Determine the status of an order.

Sample integration

See a sample OXXO integration in the PayPal GitHub repository.