OXXOPay

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.

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.
• phone: The customer's phone number without special symbols.
• custom2: The name of payment method - oxxopay.
• 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&currency=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&notification_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&currency=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&timestamp=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&timestamp=1666098500&payment_method=130&method_name=OXXO&orderid=Payabl-Test" "https://www.notification_url"

Notification example with Success

payment_method=130&transactionid=105352763&timestamp=1693227607&payment_state=credited&type=capture&
errorcode=0&orderid=Payabl-Test&errormessage=&security=d9a86737f2b843ec2cb264af52bd324312d4982337873dd165efb5b94decaf97