OXXO Pay
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 codes | MX |
Processing (Presentation) currencies | MXN |
Settlement currencies | MXN |
Consumer currencies | MXN |
Channel member tag | oxxopay |
Scheme name in the settlement file | Oxxo Pay |
Minimum transaction amount | MXN 1,00 |
Maximum transaction amount | MXN 10000,00 |
Session timeout | 5 days. It can be set in the payment request. |
Refund | Full, partial and multiple partial refunds are all available. |
Refund Validity | T + 365 days |
Chargeback | No |
Integration Type | Asynchronous |
Sandbox | PPRO-hosted |
Transaction Flow
- On the merchant's checkout page, the consumer selects OXXO Pay as their preferred payment method.
- The consumer is presented with a voucher containing the amount, reference number and a barcode, as well as information about the payment.
- The consumer prints the voucher or writes down the reference number.
- The consumer is redirected back to the merchant.
- At one of the supported locations, the consumer presents the voucher/reference number.
- OXXO calls PPRO to confirm the voucher data.
- PPRO confirms the voucher is valid and returns its details (amount, expiry data, merchant and customer data.
- The cashier charges the end-customer according to the information received.
- The end-customer makes the payment and gets the physical receipt (proof of purchase).
- OXXO notifies PPRO about the payment.
- PPRO respond to OXXO acknowledging the notification.
- 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)
- Without any error within the 10 minutes window, PPRO can confirm the payment was successful as its final status.
- 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 Name | M/O/C | Type | Description |
---|---|---|---|
specin.consumeraddress | O | String (utf-8) | Account holder address |
specin.consumeremail | M | String (utf-8) | RFC compliant email address of the account holder |
specin.dynamicdescriptor | M | String (utf-8) | Description of the barcode |
specin.expirationdate | O | String (utf-8) | Due date in format yyyy-MM-dd. Defaults to now + 5 days |
transientin.merchantlogourl | O | String (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 Name Type Description merchantName
String (utf-8) Merchant name, free text merchantType
String (utf-8) Merchant type, free text merchantPhoneNumber
String (utf-8) Merchant phone, numeric merchantEmail
String (utf-8) RFC compliant email address of the
merchant
Specific output parameters for the TRANSACTION call
Field Name | Type | Description |
---|---|---|
SPECOUT.BARCODE | String (utf-8) | The numeric barcode of the OXXO Pay document |
SPECOUT.DOCUMENTIMAGE | String (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 |
REDIRECTURL | String (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 Name | M/O | Type | Description |
---|---|---|---|
specin.accountnumber | M | numeric | Consumer’s bank account number |
specin.bankagency | M | numeric | Consumer’s bank agency number |
specin.bankname | M | utf-8 | Consumer’s bank name (minimum length of two characters) |
TRANSACTION call input
tag=oxxopay
&txtype=TRANSACTION
&countrycode=MX
¤cy=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.
Updated 2 months ago