Skip to main content
OXXO PAY

OXXO Pay is a widely-used payment method in Mexico, supported by EBANX, which allows customers to complete online purchases using cash. It works by generating a payment voucher with a barcode that customers can take to any OXXO convenience store to pay in person. It is popular among consumers who prefer cash payments and those who don’t use traditional banking methods, offering a simple and secure way to shop online in Mexico. It also expands the reach for merchants to cater to a broader customer base.

Requirements​

  • API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
  • Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters.

How it works​

  • Customer chooses OXXO pay - During checkout, your customer selects OXXO Pay as the payment method.
  • Generate payment voucher - EBANX generates a payment voucher that includes a barcode, the amount to be paid, and the expiration date.
  • Customer pays at OXXO store - Your customer visits any OXXO store, presents the barcode (either printed or on their mobile device), and pays in cash or with a debit/credit card.
  • Payment confirmation - Once the payment is made, it is processed, and EBANX receives confirmation. Payment confirmation can take up to 3 business days.
  • Merchant notified - EBANX notifies you of the completed payment, allowing you to fulfill your order.

Instructions​

Follow the steps below.

  1. Select your environment

    Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

    https://sandbox.ebanx.com/ws/direct

  2. Define your parameters

    OXXO PAY operates as a voucher-based payment method, so you will need to redirect your customer to a page displaying the voucher. To obtain this redirection link, call the ws/direct endpoint with the required parameters.


    Defining API parameters

    You must provide required parameters for payment requests. These parameters ensure successful completion of transactions.

    Essential parameters

    • payment.payment_type_code - Specifies the payment method to be used for the transaction.
    • payment.currency_code - Three-letter code of the payment currency.
    • payment.amount_total - Total amount to be charged.

    Additional parameters

    • EBANX Integration Key - Used to authenticate and authorize API requests.
    • Customer Information
      • Includes details such as the customer name, email, address and document number (Depends on the requirements of the payment method or local regulations).
      • While not mandatory for all countries or payment methods, providing this information can enhance security and increase the likelihood of successful processing.
    • Additional Context - Extra data for specific methods or countries.

    To learn more about API parameters, please refer to the
    API Reference Guide chevron_right

    At the API Reference Guide, select Mexico and OXXO PAY from the dropdown menues.

  3. Sample request

    Use the following example to initiate a request.

    curl -X POST \
      --location 'https://sandbox.ebanx.com/ws/direct' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "{{your_ebanx_integration_key}}",
        "operation": "request",
        "payment": {
          "name": "Juan Garcia",
          "email": "juangarcia@example.com",
          "phone_number": "0405777687",
          "country": "mx",
          "payment_type_code": "oxxopay", // Set to 'oxxopay'
          "merchant_payment_code": "0x0W28D03-T04",
          "currency_code": "MXN",
          "amount_total": "6000"
        }
      }'

  4. Sample response

    A successful request will return a JSON response like the example below. The voucher link will be located in the payment.voucher_url parameter.

    {
      "payment": {
        "hash": "5f68bfcae62babf1a16e6cdc258816c060eec0936740e4c5",
        "country": "mx",
        "merchant_payment_code": "0x0W28D03-T04",
        "order_number": null,
        "status": "PE",
        "status_date": null,
        "open_date": "2020-09-21 14:59:22",
        "confirm_date": null,
        "transfer_date": null,
        "amount_br": "6000.00",
        "amount_ext": "6000.00",
        "amount_iof": "0.00",
        "amount_ext_requested": "6000.00",
        "currency_rate": "1.0000",
        "currency_ext": "MXN",
        "due_date": "2020-09-24",
        "instalments": "1",
        "payment_type_code": "oxxopay",
        "voucher_url": "https://sandbox.ebanxpay.com/print/voucher/execute?hash=5f68bfcae62babf1a16e6cdc258816c060eec0936740e4c5",
        "pre_approved": false,
        "capture_available": null
      },
      "status": "SUCCESS"
    }
    When Displaying OXXO PAY barcode
    • Barcode Type: Use Code 128 (Variants C and D) or Interleaved 2 of 5.
    • Barcode Size: The barcode should be between 1cm x 4cm and 6cm in size.

    At this stage, the payment will appear as pending (PE) in your
    EBANX Dashboardchevron_right

  5. Redirect customer to the returned URL

    Redirect your customer to the URL provided in the voucher_url parameter. Once redirected, they will see an voucher similar to the one below:

    OxxoPAY

  6. Monitor payment for status changes

    Notifications

    Status

    • After receiving a notification that status has changed, retrieve the payment status.

    • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will eventually change to cancelled (CA).

  7. Congratulations!

    You have succesfully integrated OXXO PAY.

    For more information, refer to the
    Direct API reference guidechevron_right

Resources​

Use the following resources when testing in your sandbox environment.

Globe Icon

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right
Mock Data Icon

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right
Debit Card Icon

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: