Skip to main content
OXXO is a cash payment method in Mexico that allows buyers to pay at physical OXXO convenience stores using a unique reference code. Due to being a physical payment method, there may be a delay in processing the payment.

​
Setup

To create an OXXO account, request credentials.

​
Credentials

When setting up OXXO in the dashboard, configure the following credentials:
  • Private key - The private key from OXXO.
  • Child company ID (optional) - The child company ID if applicable.
  • Webhook public key (optional) - The public key used to verify webhook signatures.
  • Approval URL (optional) - A custom frontend URL for rendering your own barcode page. See Custom voucher page below.
  • Company name (optional) - The company name displayed on the voucher.
  • RFC (optional) - The RFC (tax ID) displayed on the voucher.

​
Features

OXXO supports the following features:
  • Direct capture - Payments are captured immediately at the time of authorization
  • Transaction sync - Automatic synchronization of transaction status updates

​
Supported countries

OXXO supports transactions from buyers in MX.

​
Supported currencies

OXXO supports processing payments in MXN and USD.

​
Limitations

The following features are not supported by this connector:
  • Delayed capture - Authorizing a payment and capturing it later is not supported
  • Void - Canceling an authorized transaction before capture is not supported
  • Refunds - Full refunds are not supported
  • Partial refunds - Partial refunds are not supported
  • Partial capture - Capturing a portion of the authorized amount is not supported
  • Over capture - Capturing more than the authorized amount is not supported
  • Partial authorization - Accepting a partial amount is not supported
  • Payment method tokenization - Storing payment methods for future use is not supported
  • Zero auth - Zero-dollar verification transactions are not supported
  • Settlement reporting - Automatic settlement reporting is not supported
Additional limitations:
  • Cart items required - Cart items must be included with every transaction and must match the transaction amount. If they do not match, a single cart item for the correct amount replaces the original items.

​
Integration

The default integration for OXXO uses a hosted payment page where the charge is created once the buyer accepts. The payment reference expires after 7 days. Start by creating a new transaction with the following required fields. 
var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "MXN",
    Country = "MX",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "oxxo",
          RedirectUrl = "https://example.com/callback",
        }
      ),
  }
);
After the transaction is created, the status is set to processing. The payment reference expires after 7 days. 
{
  "type": "transaction",
  "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
  "payment_method": {
    "type": "payment-method",
    "approval_url": "https://cdn.gr4vy.com/connectors/..."
  },
  "method": "oxxo"
}
Redirect the buyer to the approval_url where they receive the OXXO payment reference. Once the buyer pays at an OXXO store and the payment is confirmed through a webhook, the transaction progresses to a capture_succeeded state.

​
Custom voucher page

By default, OXXO delays the charge until the buyer accepts on the hosted page. To charge upfront and render your own barcode page, set a custom approval URL either at the connection level (in the connector credentials) or per transaction using connection options. When a custom approval URL is set, the OXXO reference is appended as a query parameter, for example: https://merchant.com/voucher?reference=123456. 
var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "MXN",
    ConnectionOptions = new TransactionCreateConnectionOptions()
    {
      OxxoOxxo = new ConnectionOptionsOxxoOxxo()
      {
        ApprovalUrl = "https://merchant.com/voucher",
      },
    },
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "oxxo",
          RedirectUrl = "https://example.com/callback",
        }
      ),
  }
);

​
Required fields

OXXO requires the following buyer information with every transaction:
  • First name
  • Last name
  • Email address
  • Phone number

​
Webhooks

OXXO requires webhook setup to receive payment confirmations. Configure the webhook public key in the connector credentials to verify incoming webhook signatures.