OXXO

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 - 126.
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.
You can see a full list of parameters in Pre-Authorization.

Request example

/powercash21-3-2/backoffice/payment_preauthorize&merchantid=ala&amount=112&currency=MXN&orderid=Payabl-Test&language=en&gender=M&lastname=Mann&street=An+der+Welle+4&zip=60322&city=Frankfurt&country=MEX&customerid=&salutation=Herr&title=&firstname=Muster&company=Payabl&birthday=07071971&house=19&postbox=&state=HE&email=test%40inatec.com&phone=XXXXXXXXXX8501&fax=&mobile=&customerip=127.0.0.1&custom1=&custom2=oxxo&custom3=&url_return=http%3A%2F%2Fdev-sim-ng.inatec.local%2F%7Esimdad%2FInatecResponse%2Fredirect_response.php&url_success=http%3A%2F%2Fdev-sim-ng.inatec.local%2F%7Esimdad%2FInatecResponse%2Fsuccess.php&url_failed=http%3A%2F%2Fdev-sim-ng.inatec.local%2F%7Esimdad%2FInatecResponse%2Ffailed.php&notification_url=https%3A%2F%2Fapi.powercash.de%2Fsimulation%2Fbilling_response.php&payment_method=126&signature=3fadec60c849a5f6b4ecd5771f3c747e13087afa

Step 2. Handle the redirect

To complete the payment, you need to redirect the customer to the correct URL in the response.

Response

transactionid=215438989&transid=215438989&status=2000&errormessage=pending&errmsg=pending&amount=112&price=112&currency=MXN&orderid=Payabl-Test&payment_method=126&user_id=289765&redirect_url=https%3A%2F%2Fapi.gateway.payretailers.com%2Fv2%2Fpublic%2Ftransactions%2Fgateway%2F5da8277a-39fe-42b6-8a06-daab30242383

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

"payretailers_method_name=OXXO&acquirer_id=fc85ba54-0fb4-44bc-beb5-77e6e34fdf24&type=order&payment_method=126&errorcode=-5002&security=9eb76236569e666e159a0b2c1dda70f1b1c5a8b2a0390f3e3fe4013a39a381d6&orderid=Payabl-Test&transactionid=215438991&errormessage=Payment+failed&timestamp=1666098226&payment_state=FAILED&psp_transaction_id=50619481931" "https://www.notification_url"

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&timestamp=1666098500&payment_method=126&payretailers_method_name=OXXO&orderid=Payabl-Test" "https://www.notification_url"

Payouts

The method allows merchants to send funds to a bank account via wire transfer. In order for this to be done, the merchant needs to submit the bank details of the customer.

N.B.: Payouts can only be sent to the banks of this list: https://bank-codes.es/swift-code/mexico/

Field	Value Format	Accepted Values
merchantid	String	[A-Z][0-9]
amount	Float	0.00
currency	String	BRL
orderid	String	[0-9]
language	String	en
lastname	String	[A-Z]
street	String	*
zip	String	[A-Z][0-9]
city	String	[A-Z]
country	String	Country Code
firstname	String	[A-Z]
state	String	[A-Z]
email	String	[A-Z][0-9][-&_]@[A-Z][0-9].[A-Z]
custom1 ### optional ###	String	*
custom2 ### optional ###	String	*
custom3 ### mandatory payment reason ###	String	*
payment_method	String	126 Payment Method Id
phone	String	[0-9]
bankname	String	Bank Name
accountnumber	String	[A-Z][0-9]
testmode ### only for testing ###	String	true
testmodecallbackstatus ### only for testing ###	String	[PENDING-PROCESSED-ACCEPTED-FINISHED-ERROR]
signature	String	*

Request string:

POST /powercash21-3-2/backoffice/payment_cft

merchantid=ala&amount=70&currency=MXN&orderid=Inatec-Test&language=en&lastname=Mann&street=Address+4&zip=60322&city=City&country=MEX&firstname=Muster&state=HE&email=test%40inatec.com&custom1=&custom2=&custom3=payment+reason&payment_method=126&phone=43543435435&bankname=341&accountnumber=0001&testmode=true&testmodecallbackstatus=FINISHED&nationalid=00183562658&signature=f3527a736f94e971dc8d91e2466f549f6aba996c

Response:

transactionid=215439108&transid=215439108&status=2000&errormessage=pending&errmsg=pending&amount=70&price=70&currency=MXN&orderid=Inatec-Test&payment_method=126

1.1 Error

transactionid=215439106&transid=215439106&status=-1320&errormessage=National%20Id%20wrong%20or%20missing&errmsg=National%20Id%20wrong%20or%20missing&amount=70&price=70&currency=MXN&orderid=Inatec-Test&payment_method=126

1.2 Pending

"transactionid=215437556&transid=215437556&status=2000&errormessage=pending&errmsg=pending&amount=1230&price=1230&currency=MXN&orderid=Inatec-Test&payment_method=126""

Notification:

2.1 Notification example with Error: