Skip to main content

OXXO

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

OXXO Flow​

Request Fields​

  • 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 Fields​

  • 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.
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": {}
    }