Skip to main content

OXXO

  POST https://api-sandbox.letpay.io/oxxo/simple

Overview​

OXXO is a widely-used voucher payment method in Mexico that enables customers to pay for online goods and services using cash. The transaction flow begins when a customer selects OXXO at checkout and generates a payment voucher containing a barcode and reference number. To complete the purchase, the customer presents this voucher at any of the 20,000+ OXXO convenience stores nationwide and pays the amount in cash. As a cash-upfront payment method, OXXO is critical for reaching Mexico's entire consumer base, including the large segment of the population that is unbanked or prefers not to share financial data online. For merchants, all payments are secure and irreversible once paid, which completely eliminates the risk of chargebacks.

Reference Checkout UI OXXO​

Reference UI - OXXO - Part 1Reference UI - OXXO - Part 1

OXXO Generated​

Reference UI - OXXO - Part 2Reference UI - OXXO - Part 2

Reference Checkout UI OXXO Email​

Upon successful creation of a payment order via the API, an automated confirmation email is sent to the address provided in the person.email field of your request. This email contains a copy of the payment instructions for the user's convenience.

Reference UI - OXXO - Part 3 - EmailReference UI - OXXO - Part 3 - Email

OXXO Flow​

Request Body​

  • contract_id (required/string): Merchant's contract id.
  • reference_id (required/string/max 45 chars): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
  • notification_url (required/string): URL to post callbacks to this payment.
  • ip_address (optional/string): Remote IP Address(IPv4/IPv6). It should be the IP address from the buyer's device.
  • payment (required/object): The payment data:
    • amount (float/required): Total amount of the payment. Value must have a maximum of two decimal places.
    • asset (optional/string): Reference code for asset for the sale's amount. Default: MXN.
    • currency (required/string): Currency code in ISO-4217.
    • country (required/string): Country code in ISO 3166-2.
    • oxxo (optional/object): The Oxxo payment data:
      • expiration_date (optional/date/YYYY-MM-DD): Expiration date (if not informed system will assume 5 days of current date).
      • description (optional/string): This is a message that goes attached to the transaction and will show at the recipient's bank statement.
      • logo (optional/string): The HTTP/Data URL of your logo (must be JPG or PNG format and it is recommended to be proportional to 200 x 45 pixels). If omitted, no logo will be displayed.
  • person (required/object): The person data:
    • full_name (required/string): Person’s full name.
    • email (required/string): Person’s email provided to the merchant.
  • extra_data (optional/JSON): Any data pertinent to the merchant.

Response Body​

  • transaction_status (string): Current status of the payment.
  • payment_token (string): Unique payment identification for this payment.
  • reference_id (string): External code created by the merchant to reference this payment (e.g. order number).
  • barcode_png_gzip_base_64 (string): Base64 zipped PNG image representation of Oxxo barcode.
  • pdf_gzip_base_64 (string): Payment confirmation in Base64 zipped PDF format.
  • barcode (string): Text string containing barcode to pay this payment.
  • amount (string): Amount of this payment.
  • refresh_token (string): Updated access token for future calls.
  • totals (object): The payment totals:
    • amount (float): Amount in default region asset.
    • asset (string): Asset used in this amount.
    • original_amount (float): Amount as informed by merchant.
    • original_asset (string): Asset used in this originalAmount.
    • customer_fees (float): Total calculated fee assigned to customer.
    • customer_amount (float): Total amount for customer (amount + customer_fees).
  • customer_fees (object): List of incident customer fees and respective values.

Authorization​

AUTHORIZATIONAPI Key
KeyX-Auth-Token
ValueMY_ACCESS_TOKEN

Body Raw(json)​

json
{
    "contract_id": "MY_CONTRACT_ID",
    "reference_id": "MY_REFERENCE_ID",
    "notification_url": "https://my.notification.url/callback/",
    "ip_address": "0.0.0.0",
    "payment": {
        "amount": 123.45,
        "asset": "MXN",
        "currency": "MXN",
        "country": "MX",
        "oxxo": {
            "expiration_date": "2024-12-31",
            "description": "Payment via OXXO",
            "logo": "data:image/png;base64,BASE64_ENCODED_IMAGE"
        }
    },
    "person": {
        "full_name": "Alice Sonnentag",
        "email": "[email protected]"
    },
    "extra_data": {
        "my-conciliation-number": "xxxxxx"
    }
}

Example Request​

Example Request​

200 - Success
    curl --location 'https://api-sandbox.letpay.io/oxxo/simple' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN' \
    --data-raw '{
        "contract_id": "MY_CONTRACT_ID",
        "reference_id": "MY_REFERENCE_ID",
        "notification_url": "https://my.notification.url/callback/",
        "ip_address": "0.0.0.0",
        "payment": {
            "amount": 123.45,
            "asset": "MXN",
            "currency": "MXN",
            "country": "MX",
            "oxxo": {
                "expiration_date": "2024-12-31",
                "description": "Payment via OXXO",
                "logo": "data:image/png;base64,BASE64_ENCODED_IMAGE"
            }
        },
        "person": {
            "full_name": "Alice Sonnentag",
            "email": "[email protected]"
        },
        "extra_data": {
            "my-conciliation-number": "xxxxxx"
        }
    }'

Example Response​

Header
  Content-Type: application/json
Body
    {
      "transaction_status": "PROCESSING",
      "payment_token": "0196e128-c6c7-4249-9f20-21a4c2eb1506",
      "reference_id": "MY_REFERENCE_ID",
      "barcode_png_gzip_base_64": "BASE64_ZIPPED_PNG",
      "pdf_gzip_base_64": "BASE64_ZIPPED_PDF",
      "barcode": "64000012578123060900025032",
      "amount": "123.45",
      "refresh_token": "MY_ACCESS_TOKEN",
      "totals": {
        "amount": 123.45,
        "original_amount": 123.45,
        "original_asset": "MXN",
        "customer_fees": 0,
        "customer_amount": 123.45,
        "asset": "MXN"
      },
      "customer_fees": {}
    }