Introduction

OXXO PAY is a convenient cash payment method in Mexico that simplifies transactions. It generates unique serial code vouchers, eliminating the need for printing. Simply present the code at any of the 14,695 OXXO branches for real-time verification and immediate payment processing. This innovative e-commerce solution, introduced by OXXO and Conekta, streamlines cash payments for businesses while providing real-time notifications.

Supported Countries

• Mexico

Supported Currencies

• MXN

Payment (Deposit) Flow

Follow these steps to perform a payment using Nuvei REST API integration:

1. Generate a sessionToken

Press here for details.

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters including:

• userTokenId
• amount
• currency: “MXN“
• paymentOption.alternativePaymentMethod class containing:
  • paymentMethod: “apmgw_OXXO_PAY“
• deviceDetails class containing: ipAddress
• billingAddress class containing: firstName, lastName,  country, email, phone
  • country: “MX”
  • phone – Must be a valid Mexico phone number.

Example /payment Request

{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "MXN",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_OXXO_PAY"
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "phone": "528880466555",
    "country": "MX",
    "email": "[email protected]"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}

The response generates and returns a redirect URL (redirectUrl) to redirect the customer to the payment page, as well as a UPO (userPaymentOptionId) for use in future transactions.

Example /payment Response

{
  "internalRequestId": 980209708,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "979047831696752006",
  "merchantSiteId": "217268",
  "version": "1.0",
  "clientRequestId": "20240403090237",
  "sessionToken": "b259e996-d82d-44d7-9f75-44aa17f4d5bf",
  "clientUniqueId": "20180327175242",
  "orderId": "431524878",
  "userTokenId": "TestToken",
  "paymentOption": {
    "redirectUrl": "https://cdn-int.safecharge.com/safecharge_resources/v1/oxxo_pay.html?amount=150.00&currency=MXN&currencySymbol=%24&language=EN&merchantName=Safecharge+Test&reference=98000017710610",
    "userPaymentOptionId": "107113088",
    "card": {}
  },
  "transactionStatus": "REDIRECT"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Example Payment DMN with Status=APPROVED

...'ppp_status=OK&Status=APPROVED&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43114361&userid=&merchant_unique_id=&customData=&productId=&first_name=Fname&last_name=Lname&email=john.smith%40safecharge.com&currency=MXN&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Sancho+el+fuerte+15&address2=&country=Mexico&state=&city=Madrid&zip=&phone1=00525512345678&phone2=&phone3=&client_ip=93.146.254.172&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Conekta+MX-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=MX&shippingState=&shippingCity=%24%7BSCityU%7D&shippingAddress=%24%7BSAddressU%7D&shippingZip=%24%7BSZipU%7D&shippingFirstName=%24%7BSFirstNameU%7D&shippingLastName=%24%7BSLastNameU%7D&shippingPhone=00525512345678&shippingCell=%24%7BSCellU%7D&shippingMail=%24%7BSEmailU%7D&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=186111&merchant_status=&action=&requestVersion=&message=APPROVED&merchantLocale=&unknownParameters=&payment_method=apmgw_OXXO_PAY&ID=&merchant_id=5416795427517477813&responseTimeStamp=2024-05-27.13%3A49%3A09&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&userPaymentOptionId=2153232561&TransactionID=2610000000000029109&externalTransactionId=ord_2w16BnVVGYNb2HMJc&APMReferenceID=00A0AFF23B31146954BA939795EE8C95&orderTransactionId=24488981&totalAmount=10.00&dynamicDescriptor=hristo+descriptor&item_name_1=NA&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&shippingCounty=%24%7BSCountyU%7D&type=DEPOSIT&clientRequestId=20240527164814&relatedTransactionId=&sessionId=a4f0e72b36f990cdc71d56f5c309&responsechecksum=ab732168a9394dc6d78b6d431e629d9f1d01b1d00b0ba8d5c6ff6b8a9963c215&advanceResponseChecksum=76c80190ac9bb1a8ade958a62a47aeb4effea9e068d03e027ee0cce84d5ea8d0',

Example Payment DMN with Status=PENDING

...'ppp_status=PENDING&Status=PENDING&ExErrCode=0&ErrCode=0&errApmCode=0&errApmDescription=&errScCode=0&errScDescription=&Reason=&ReasonCode=0&PPP_TransactionID=43114361&userid=&merchant_unique_id=&customData=&productId=&first_name=Fname&last_name=Lname&email=john.smith%40safecharge.com&currency=MXN&customField1=&customField2=&customField3=&customField4=&customField5=&customField6=&customField7=&customField8=&customField9=&customField10=&customField11=&customField12=&customField13=&customField14=&customField15=&invoice_id=&address1=Sancho+el+fuerte+15&address2=&country=Mexico&state=&city=Madrid&zip=&phone1=00525512345678&phone2=&phone3=&client_ip=93.146.254.172&nameOnCard=&cardNumber=&bin=&noCVV=&acquirerId=&acquirerBank=Conekta+MX-PI&expMonth=&expYear=&Token=&tokenId=&AuthCode=&AvsCode=&Cvv2Reply=&shippingCountry=MX&shippingState=&shippingCity=%24%7BSCityU%7D&shippingAddress=%24%7BSAddressU%7D&shippingZip=%24%7BSZipU%7D&shippingFirstName=%24%7BSFirstNameU%7D&shippingLastName=%24%7BSLastNameU%7D&shippingPhone=00525512345678&shippingCell=%24%7BSCellU%7D&shippingMail=%24%7BSEmailU%7D&total_discount=0.00&total_handling=0.00&total_shipping=0.00&total_tax=0.00&buyButtonProductBundleId=&merchant_site_id=186111&merchant_status=&action=&requestVersion=&message=PENDING&merchantLocale=&unknownParameters=&payment_method=apmgw_OXXO_PAY&ID=&merchant_id=5416795427517477813&responseTimeStamp=2024-05-27.13%3A48%3A28&buyButtonProductId=&webMasterId=&appliedPromotions=&uniqueCC=&transactionType=Sale&externalEmail=&cardCompany=&eci=&userPaymentOptionId=2153232561&TransactionID=2610000000000029109&externalTransactionId=ord_2w16BnVVGYNb2HMJc&APMReferenceID=00A0AFF23B31146954BA939795EE8C95&orderTransactionId=24488981&totalAmount=10.00&dynamicDescriptor=hristo+descriptor&item_name_1=NA&item_number_1=&item_amount_1=10.00&item_quantity_1=1&item_discount_1=0.00&item_handling_1=0.00&item_shipping_1=0.00&feeAmount=&amountWithoutFee=&houseNumber=&customCurrency=&shippingCounty=%24%7BSCountyU%7D&type=DEPOSIT&clientRequestId=20240527164814&relatedTransactionId=&sessionId=a4f0e72b36f990cdc71d56f5c309&responsechecksum=23dcf6a0713222e426a7f9eb9564ee898d204dd7959c74abfa65cf1cd230fcb3&advanceResponseChecksum=edf993fac75ac4d1c4dd88d943b47b4e68577fd7c44adf4aa6152335c4d3ff89',

Payout (Withdrawal) Flow

To perform a payout with OXXO PAY, you need to create a UPO, which represents the customer’s bank account details, with the /addUPOAPM method before sending the /payout request:

1. Register a userTokenId

A userTokenId is a field in the Nuvei system containing the user’s identifier in the merchant system.

If you do not have a userTokenId registered in the Nuvei system for this user, then register one by sending a /createUser request, including email, countryCode, firstName, and lastName.

Example /createUser Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "userTokenId":"<unique user identifier in merchant system>",
  "email":"[email protected]",
  "countryCode":"MX",
  "firstName":"John",
  "lastName":"Smith",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example /createUser Response

{
  "userId":78403498,
  "internalRequestId":552360538,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20221108130736"
}

The request registers the userTokenId (userId) in the Nuvei system, which is needed to generate a userPaymentOptionId in the next step.

2. Create the UPO

Create a UPO by sending an /addUPOAPM request and include:

• userTokenId – The unique user identifier in your system.
• paymentMethodName: “apmgw_OXXO_PAY“

Example /addUPOAPM Request

{
  "merchantSiteId": "<your merchantSiteId>",
  "merchantId": "<your merchantId>",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "timeStamp": "<YYYYMMDDHHmmss>",
  "paymentMethodName": "apmgw_OXXO_PAY",
  "checksum": "<calculated checksum>"
}

The request returns an encrypted userPaymentOptionId representing the user’s APM account details.

Example /addUPOAPM Response

{
  "userPaymentOptionId":83458468,
  "internalRequestId":553078068,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"2439523627382132721",
  "merchantSiteId":"224428",
  "version":"1.0",
  "clientRequestId":"20221109154215"
}

3. Send a /payout Request

Send a /payout request and include the userPaymentOptionId, which contains the user’s previously stored APM account details. Press here for an example.

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

User Experience

Deposit

1. The user is redirected to the OXXO PAY website, where a reference code and payment instructions appear.
   English (Sandbox Environment)
   
   English (Production)
   Spanish (Sandbox)
2. The user makes the payment at an OXXO store using the reference code.
   The user receives an instant notification of the completed payment.

Withdrawal

1. User selects the OXXO PAY payment method and enters the amount.
2. The withdrawal request is created.
3. Merchant can process the withdrawal using REST API or back office.
4. After the withdrawal is processed, the user receives an email with instructions.
   Spanish (Sandbox)
   
   The withdrawal expires after 48 hours and cannot be changed. Receiving the withdrawal through the merchant might be subject to fees.

Testing

Testing deposits requires a valid Mexico phone number. It must contain at least 10 digits – the area code/lada plus the eight-digit phone number, and preferably the country code (52).
Transactions in the sandbox environment are automatically approved.