OXXO
Learn how to accept OXXO, a common payment method in Brazil.
OXXO is a Mexican chain of convenience stores with thousands of locations across Latin America and represents nearly 20% of online transactions in Mexico. OXXO allows customers to pay bills and online purchases in-store with cash.
To complete a transaction, customers receive a voucher that includes a reference number for the transaction. Customers then bring their vouchers to an OXXO store to make a cash payment.
Payment type | Cash-based |
Market | Mexico |
Customers currencies | MXN |
Processing currencies | MXN |
Settlement currencies | EUR |
Refunds | No |
Step 1. Make a transaction request
From your server, make a POST /payment_preauthorize request.
https://sandbox.payabl.com/pay/backoffice/payment_preauthorize
Include in the request parameters below:
The below parameters are mandatory for OXXO.
merchantid
: The merchant identification number.orderid
: The field orderid is optional and exclusively for the merchant's convenience.amount
: The amount field contains the transaction’s total amount. This is the amount that will be transmitted to the authorizing system.currency
: The currency field contains the alphanumeric currency code for the transaction, according to ISO 4217, e.g. MXN.payment_method
: The payment method id - 130 (or 126, please check with tech support).signature
: The signature field contains a 40-figure hexadecimal value. This signature value is a checksum designed to protect the merchant account from unauthorized access.country
: Customer country in ISO Alpha-2 format. Supported countries: MEX.email
: The customer's email address.custom2
: The name of payment method - oxxo.nationalid
: Consumer’s national id, has to satisfy the following regular expression: RFC: 13 chars, ex: MAMB780915969; CURP: 18 chars.nationaltype
: User's identification type RFC or CURP.
You can see a full list of parameters in Pre-Authorization.
Request example
/pay/backoffice/payment_preauthorize&merchantid=gateway_test&amount=1.23¤cy=MXN&
orderid=Payabl-Test&language=en&gender=&lastname=Mann&street=Office+11A,+Swepco+Court,+Griva+Digeni+80&
zip=60322&city=Frankfurt&country=DEU&customerid=&salutation=&title=&firstname=Muster&company=&
birthday=&house=&postbox=&state=&[email protected]&phone=&fax=&mobile=&customerip=&custom1=&
custom2=oxxo&custom3=&url_return=http://dev-sim-ng.inatec.local/~simdad/InatecResponse/redirect_
response.php&url_success=http://dev-sim-ng.inatec.local/~simdad/InatecResponse/success.php&url_failed=
http://dev-sim-ng.inatec.local/~simdad/InatecResponse/failed.php¬ification_url=https://api.
powercash.de/simulation/billing_response.php&payment_method=130&nationaltype=RFC&nationalid=MAMB780915969&
subject=test+subject&content=test+content&signature=9fcd61c385cc4007fc23c0f30899d57cc08883f9
Step 2. Handle the redirect
To complete the payment, you need to redirect the customer to the correct URL in the response.
Response
transactionid=105352763&transid=105352763&status=2000&errormessage=pending&errmsg=pending&amount=1.23&
price=1.23¤cy=MXN&orderid=Payabl-Test&user_id=787410&redirect_url=https://checkout-test.pagsmile.
com/checkout?prepay_id=NC9sSmpiUzRCWkprQVYxbGZzS0lSbHFlVy9DQk16QTVtZ0lNaGtzeWRsTT0=-BeFB7e8D
Step 3. Transaction states
If the customer successfully paid by using the OXXO invoice, you will receive a notification with confirmation.
Notification example with error:
payment_state=FAILED
type=order&errorcode=-66183&orderid=Payabl-Test&security=5984241734ee557792fd0f6434ab49222a2c3c3598e3
b68f535ea4cd92adac54&errormessage=Wrong+national+type&transactionid=105352778×tamp=1693228579
If the customer initiated the transaction but never completed it, you will receive a failed notification with payment_state=EXPIRED
"type=order&errorcode=-5003&security=97c048b264eea474ff0c44e0eb170818bb1707122c93e7d45d1e738964218588&psp_transaction_id=50619689039&errormessage=Payment+aborted+by+customer&payment_state=EXPIRED&transactionid=215438993&acquirer_id=3b8f1192-cca8-4c79-a795-a095af6c0c56×tamp=1666098500&payment_method=130&method_name=OXXO&orderid=Payabl-Test" "https://www.notification_url"
Notification example with Success
payment_method=130&transactionid=105352763×tamp=1693227607&payment_state=credited&type=capture&
errorcode=0&orderid=Payabl-Test&errormessage=&security=d9a86737f2b843ec2cb264af52bd324312d4982337873dd165efb5b94decaf97
Updated 10 months ago