Oxxo Pay is offered by Oxxo, one of the largest convenience store chains in the country. Oxxo Pay allows customers to make various types of payments at Oxxo stores, such as bills, and online purchases. The end customer receives a reference number/barcode, which they can take to any Oxxo store to complete the transaction. At the store, customers present the reference number/barcode to the cashier, who reads it and collects the payment. The customer can then receive a receipt as proof of payment. Oxxo Pay provides a convenient and widely accessible payment option for individuals who do not have access to credit cards or prefer to make cash payments. PPRO can offer to our customers two options when using Oxxo Pay as a payment method:

  • A complete solution: PPRO generates and hosts a complete page containing all elements (PPRO voucher).
  • Reference number: gives the merchant full flexibility to build his own Oxxo Pay checkout page based on a Reference number.

Payment Method Properties

Available country codesMX
Processing (Presentation) currenciesMXN
Settlement currenciesMXN
Consumer currenciesMXN
Channel member tagoxxopay
Scheme name in the settlement fileOxxo Pay
Minimum transaction amountMXN 1,00
Maximum transaction amountMXN 10000,00
Session timeout5 days.

It can be set in the payment request.
RefundFull, partial and multiple partial refunds are all available.
Refund ValidityT + 365 days
ChargebackNo
Integration TypeAsynchronous
SandboxPPRO-hosted

Transaction Flow

  1. On the merchant's checkout page, the consumer selects OXXO Pay as their preferred payment method.
  2. The consumer is presented with a voucher containing the amount, reference number and a barcode, as well as information about the payment.
  3. The consumer prints the voucher or writes down the reference number.
  4. The consumer is redirected back to the merchant.
  5. At one of the supported locations, the consumer presents the voucher/reference number.
  6. OXXO calls PPRO to confirm the voucher data.
  7. PPRO confirms the voucher is valid and returns its details (amount, expiry data, merchant and customer data.
  8. The cashier charges the end-customer according to the information received.
  9. The end-customer makes the payment and gets the physical receipt (proof of purchase).
  10. OXXO notifies PPRO about the payment.
  11. PPRO respond to OXXO acknowledging the notification.
  12. A 10 minutes window is opened for the final payment confirmation (in case of some system error on OXXO side, OXXO will send a notification to PPRO and the payment is reversed)
  13. Without any error within the 10 minutes window, PPRO can confirm the payment was successful as its final status.
  14. The merchant is notified of the payment status and can release the product/ship the goods.

OXXO Integration

Specific input parameters for the TRANSACTION call

Field NameM/O/CTypeDescription
specin.consumeraddressOString (utf-8)Account holder address
specin.consumeremailMString (utf-8)RFC compliant email address of the account holder
specin.dynamicdescriptorMString (utf-8)Description of the barcode
specin.expirationdateOString (utf-8)Due date in format yyyy-MM-dd. Defaults to now + 5 days
transientin.merchantlogourlOString (utf-8)The URL of the logo to be displayed on the payment page. If not set, it defaults to the PPRO logo. Max logo size: W=1200, H=627. Max URL characters is 255

For standard input parameters, see Input parameters for the TRANSACTION call.

🚧

Important

  • This payment method requires the real account holder value for the accountholdername parameter.
  • The amount should be provided in cents.
  • Merchant details must be provided on the merchant onboarding, as this payment method requires it for every transaction. PPRO will add the data based on the information provided on onboarding:
Field NameTypeDescription
merchantNameString (utf-8)Merchant name, free text
merchantTypeString (utf-8)Merchant type, free text
merchantPhoneNumberString (utf-8)Merchant phone, numeric
merchantEmailString (utf-8)RFC compliant email address of the
merchant

Specific output parameters for the TRANSACTION call

Field NameTypeDescription
SPECOUT.BARCODEString (utf-8)The numeric barcode of the OXXO Pay document
SPECOUT.DOCUMENTIMAGEString (utf-8)A ready-to-use image that does not need to be formatted in the appropriate barcode format. This enables you to make your own checkout flow or send the barcode via another medium, such as email
REDIRECTURLString (utf-8)The URL of the OXXO document. Only for successful requests

For standard output parameters, see Output parameters for the TRANSACTION call.

Specific input parameters for the REFUND call

Refunds are performed by a bank transfer to the target account. For Anti Money Laundering reasons PPRO needs to verify the name of the account holder which will receive the refund, this is normally done by validating a bank statement supplied by the receiver. This should be sent to [email protected] when the refund is requested.

Field NameM/OTypeDescription
specin.accountnumberMnumericConsumer’s bank account number
specin.bankagencyMnumericConsumer’s bank agency number
specin.banknameMutf-8Consumer’s bank name (minimum length of two characters)

TRANSACTION call input

tag=oxxopay
&txtype=TRANSACTION
&countrycode=MX
&currency=MXN
&amount=10000
&merchanttxid=CkNWCBH4Wx4s
&login=johndoe
&password=wXBrpVporFVjGO4R
&contractid=JOHNDOECONTRACT
&channel=testchannel
&accountholdername=John%20Doe
&specin.dynamicdescriptor=BarcodeDescription
&specin.consumerEmail=john.doe%40gmail.com
&specin.expirationDate=2024-04-02
&transientin.merchantLogoUrl=http://logo-address.com/logo.png

TRANSACTION call output

STATUS=PENDING
&TXID=140253888920
&MERCHANTTXID=1718202791
&FUNDSSTATUS=NOT_EXPECTED
&FLAGS=
&RAND3581893664=e170c406ca95cc0db567aec0084a70f9bba27022
&ERRMSG=
&CHANNEL=testchannel
&TAG=oxxopay
&REDIRECTSECRET=RbQo9tBFpbjEBDlNdV1cVfEAln2uiWAj
&SPECOUT.BARCODE=9101402538889202
&SPECOUT.DOCUMENT=https://r2.girogate.de/oxxo-pay/barcodes/9100022732148733/page
&SPECOUT.DOCUMENTIMAGE=https://r2.girogate.de/oxxo-pay/barcodes/9100022732148733/image

Branding guidelines

Click here to download logos and other useful branding information.

Additional information

  • OXXO Domestic Processing (Mexico) supports 60 characters of text for the payment description passed in SPECIN.DYNAMICDESCRIPTOR.
  • If you want to create a self-hosted OXXO barcode presentation page, add the following text to help guide the consumer when paying the OXXO slip:
  • NOTA: Este código de pago es único y sólo es válido para esta compra, si necesitas hacer más compras/pagos debes comunícate con "Merchant Name" para generar otro código.
  • Replace "Merchant Name" with the name of the merchant presenting the slip (if this is technically possible).

🚧

Important

The account holder's name passed in the request has to be in the format , with a minimum length of two characters per name. Multiple first names are ok. Valid examples are “John Dorian”, “William Charles Dickinson” (where “William Charles” will be the first name, and “Dickinson” the last). If these conditions are not met, the system will not accept the request.

Scenarios for using the specin.duedate parameter

Setting a value for specin.duedate does not affect the default timeout of 5 days for the payment. The following use cases apply:

specin.duedate value is lower than the timeout value
In this use case, you define a more aggressive due date. If the value of specin.duedate is lower than the timeout value, a consumer not paying by the due date will not affect when PPRO sends a timeout. PPRO still sends the timeout at 5 days, as defined above.

We recommend you track the due date expiring based on the local timezone on the desired day at 23:59:59. Ignore the PPRO timeout.

specin.duedate value is greater than the timeout value
In this use case, you define a less aggressive due date. If the value of specin.duedate is greater than the timeout value, PPRO will still send the timeout message at 5 days, as defined above. This means that a consumer may successfully pay after the PPRO timeout is sent. This causes a scenario where PPRO sends a second notification to the notification URL indicating a payment's success. This is the "succeeded after failed" scenario.

We recommend you track the due date expiring based on the local timezone on the desired day at 23:59:59. Ignore the PPRO timeout.