Last updated: 17 September 2026 | Change log

OXXO

OXXO is a popular cash payment method in Mexico, allowing customers to pay for online purchases at any of the 20,000+ OXXO convenience stores nationwide.

Note

Make yourself familiar with our API principles to ensure a resilient integration.

Product overview

Why use Oxxo

This payment option is ideal for customers without bank accounts or credit cards. Your customers are presented with an OXXO voucher with a unique barcode on your checkout page. They can use this voucher at any of the OXXO stores to pay in cash. Once the payment is processed, you are notified, and the order is confirmed. OXXO is widely used for e-commerce, bill payments, and digital services, making it a trusted and efficient solution for cash-based transactions.

Feature summary

Payment type	Country	Currencies	Recurring	Reversals	Partial reversals	Disputes
Post-pay voucher	Mexican	MXN	❌	❌	❌	❌

Minimum transaction value: 10.00 MXN
Maximum transaction value: 10,000 MXN
Voucher validity: min. 1 day, maximum 30 days

Get started

Use our API reference and set your headers.

Request

POST https://try.access.worldpay.com/apmPayments

Example request

{
  "transactionReference": "Memory265-13/08/1876",
  "orderReference": "apm-order-12345",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "method": "ach",
    "narrative": {
      "line1": "MindPalace"
    },
    "value": {
      "amount": 750,
      "currency": "USD"
    },
    "paymentInstrument": {
      "type": "direct",
      "accountType": "checking",
      "accountNumber": "01234567890123456",
      "routingNumber": "012345678",
      "checkNumber": "012345678901234",
      "companyName": "Worldpay",
      "billingAddress": {
        "address1": "8500 Governors Hill Drive",
        "address2": "Symmes Township",
        "postalCode": "45249",
        "city": "Ohio",
        "state": "US-OH",
        "countryCode": "US"
      }
    },
    "customer": {
      "firstName": "John",
      "lastName": "Johnson",
      "customerId": "43424",
      "email": "john@example.com"
    }
  }
}

Parameters

transactionReferencestring, [ 1 .. 64 ] characters^[a-zA-Z0-9\-_/!@#$%()*=.:;?\[\]{}~+]*$required

For Bizum transactions, please follow this extra regex [a-zA-Z0-9]{4,12}

orderReferencestring, [ 1 .. 64 ] characters^[a-zA-Z0-9\-_/!@#$%()*=.:;?\[\]{}~+]*$

A reference that you can apply to one or more payments according to your business needs. You may reuse the same reference across multiple payments, for example where:

the total amount for a single order is split across multiple payments
you use a single reference for each payment in a recurring agreement or split shipment scenario

merchantobject(MerchantV2)required

instructionobject(InstructionV2)required

Response

Example response

{
  "errorName": "bodyDoesNotMatchSchema",
  "message": "The json body provided does not match the expected schema",
  "validationErrors": [
    {
      "errorName": "fieldHasInvalidValue",
      "message": "Field is mandatory",
      "jsonPath": "$.instruction.value.amount"
    }
  ]
}

Schema

paymentIdstring

The identifier of the payment resource.

lastEventstring

Enum:"authorized""cancelFailed""cancelled""cancelRequested""sentForSettlement""sentForAuthorization""settlementFailed""chargebackReversed""chargedBack""disputeExpired"

_linksobject(Links)

Links to resources related to the request.

_actionsobject(ActionsV2)

redirectstring

The URL to redirect your customer to, or a QR code in Base64 to show to your customer, in order to complete the transaction.

commandIdstring

An action ID generated by us, identifying a single merchant interaction.

Example:"cmdYNdIHBPJwbkjLiykzTx0"

paymentInstrumentAll others (object) or PayPal (object) or SEPA DD (object) or Klarna (recurring) token (object)(PaymentInstrument)

One of:

Payment instrument for: ACH, Alipay China, Alipay Hong Kong, Alipay Plus, BANCOMAT Pay, Bancontact, Bizum, BLIK, EFT, Euteller, iDEAL guest, iDEAL recurring, Klarna, Klarna (recurring), Konbini, Multibanco, MyBank, Open Banking, PaysafeCard, Pix, Przelewy24, SafetyPay, Satispay, Swish, Trustly, China UnionPay, WeChat Pay.

transactionCodestring

For Pix payments - display to your customer for them to copy and paste in the Pix app.

For Swish payments - use this value as the {token} in the custom URL scheme: swish://paymentrequest?token={token}&callbackurl={callbackURL}. This will prompt the app to open, allowing your customer to complete their payment.

Example:"IZQ3iUfePwiWiwldJlipl8NGVA7w5IUg"

Errors

Check out our API reference for more responses or error codes.

Next steps

Manage your OXXO payment