Integrate with Our API

How do I begin?

PPE provides you with two independent environments. This setup allows your technical team to experiment freely before processing real transactions.

Testing environment (Sandbox)

You can start using it once your account has been created. This environment is intended for testing, making necessary adjustments, and using all the API's features. Use this environment to test and integrate your application.

Dashboard portal: https://dev.dash.proveedordepagos.mx/login

API: https://dev.api.proveedordepagos.mx

Production environment

This is the actual operating environment to start receiving cash payments and notifications.

To ensure the stability of your platform, access to this environment requires successfully completing the Technical Certification (Test Matrix) detailed in our Integration tab.

Flowchart for receiving payments from Oxxo

We show you how the payment process works for your end customers.

Steps

In the credit application, the user selects the option:

Credit payment → Payment via OXXO.
The application generates a barcode associated with the credit and the amount to be paid.
The user goes to any OXXO store.
He goes to the cashier and asks to pay for a service.
The user shows the barcode to the cashier.
The OXXO cashier scans the barcode.
The OXXO system displays the following on the screen:
- Payment provider
- Loan amount to be paid
- Service payment fee
The cashier asks the user to confirm the payment details.
The user performs:
- The payment of the loan amount
- The payment of the commission due to OXXO
The cashier gives the user the payment receipts (tickets).
The payment is reflected in approximately 30 minutes as a discount applied to the credit balance.

** Keep your ticket for future reference

Integration Guide

This section details the mandatory steps to set up your test environment and validate your integration before going into production.

1. Direct Communication Channel

To ensure a smooth integration, the PPE team will enable a dedicated WhatsApp group for your project.

2. Obtaining Credentials

Once the communication channel is established, you will receive your access keys for the Sandbox (Test Environment):

Username
Password

3. Webhook and Notification Configuration

In order for your system to react to payment events, we need to connect your server to our Sandbox.

Requirement: Generate a Webhook URL and an authentication token on your server.
Action: Share this information in the WhatsApp group so our team can register you in the system.
Simulation: Since no real money is processed in Sandbox, our team will manually simulate payments so that you receive notifications (HTTP POST) on your endpoint.

Additional requirements: Add our IP addresses to your whitelist to ensure communication is not disrupted.

For added security, please request the IP address via the WhatsApp group.

4. Certification and Transition to Production

To ensure the stability of the integration, it is necessary to successfully complete a testing cycle:

Goal: To perform 4 successful tests in Sandbox.
Validation: Once the 4 operations are confirmed, the technical team will authorize the deployment to production and will give you the final credentials.

MINIMUM TESTING REQUIRED TO GO TO PRODUCTION

Send a payment reference without a credit number.
Send a payment reference without a payment amount.
Send a payment reference with an amount of $1,200.00
Send a payment reference with an amount of $2,501.00
Create the barcode correctly.

How to run tests in a sandbox?

Follow this workflow to validate that your system correctly receives our payment notifications.

Real-time support : If you get stuck at any step, write to us directly in the WhatsApp group and our technical team will assist you.

Execution Flow

Webhook Validation: Before starting, please confirm that you have already provided us with your Webhook URL and Security Token. Without these, you will not receive payment confirmations.
Reference Generation: Create a payment reference using our API.
See the section: Create a payment reference to view the necessary parameters.
Simulation Request: Send the generated reference number to the WhatsApp group.
A PPE agent will manually process the payment simulation in our test system.
Notification Confirmation: Verify in your logs or database that the notification (HTTP POST) has reached your endpoint and that your system has processed it correctly.

SOFOM Payment Services

Proveedor de Pagos Electrónicos (PPE) offers services created for our clients:

Generate a token
Create a payment reference
Notify payment received
Obtain a report of payments made by your customers
Obtain the balance of payments made by your customers
Learn about PPE response codes.

Request Reference

This request requires an authentication token (JWT Bearer).
Generate your token in the Generate a token tab before continuing.

Learn how to create a payment reference so your customers can make their payments at any Oxxo store in Mexico.

Request

POST {URL}/payments/reference

Successful Response

Unsuccessful Response – HTTP Code 400

Example request

{

"success": false,

" message": "A reference already exists for the entered data."

}

{

"loanNumber": "2",

"paymentAmount": 5000,

"paymentNumber": 1,

"totalPayments": 6

}

Successful Response

{

"success": true,

"reference": "780000020000605000002024072910"

}

Unsuccessful Response – HTTP Code 400

{

"success": false,

" message": "A reference already exists for the entered data."

}

Get operations

This request requires an authentication token (JWT Bearer).
Generate your token in the Generate a token tab before continuing.

Learn how to obtain payments made by your customers within a date range.

GET {URL}/sofomes/get-operations?from={Start date}&to={End date}

Request

GET {URL}/sofomes/get-operations?from={Fecha inicial}&to={Fecha final}

Successful Response

ACCEPTED: Order paid at Oxxo

NOTIFIED: Order paid at Oxxo and notified to Webhook

REVERSED: Order cancelled

Example request

/sofomes/get-operations?from=2025-01-01&to=2025-02-28

Successful Response

{

"paymentReport": [

{

"client": "780300000000020100000202410233",

"tranDate": "2024-10-23T12:40:55",

"cashMachine": 2,

"entryMode": "021",

"cashierId": "COBEJO9109015",

"ticket": 712630,

"amount": 1000.00,

"adminDate": "2024-10-23",

"store": "10GUD50CUD",

"status": "ACCEPTED"

}

]

"paymentsTotal": 22500.00

}

Unsuccessful Response – HTTP Code 500

[ ]

Get Balance

This request requires an authentication token (JWT Bearer).
Generate your token in the Generate a token tab before continuing.

Learn the method to successfully obtain the current balance of payments made by your customers at any Oxxo store in Mexico.

Request

GET {URL}/sofomes/get-balance

Successful Response

Example request

/sofomes/get-balance

Successful Response

{

"totalBalance": 54000,

"totalRefounds": 2600.00,

"totalCommissions": 560

}

Unsuccessful Response – HTTP Code 500

Objeto vacío

[ ]

Generate Token

Method to generate a token using a username and password created when the SOFOM account is registered.

POST {URL}/login

Input Data

Output Data

Example request

{

"username" : "myUser",

"password" :"myPass"

}

Response

{

"access_token": "eyJhbGciOiJIUzI1OiJ1.eyJzdWIiOiJ1c2VyU21mb20wMSIsIm5iZiI6MTcyMjUzMTUyMiwicm1sZXMiOltdLCJpc3MiOiJwcGUtc21mb20t cGF5bWVudHMtYXBpIiwiZXhwIjoxNzIyNTM1MTIyLCJpYXQiOjE3MjI1MzE1MjJ9.BmRWruyfcBhaBMAlNTyeRopOIE8rmj1LTSOJn1q-i90",

"token_type": "Bearer",

"expires_in": 3600,

"username": "myUser"

}

Token Security and Validity
Due to security and data protection protocols, each generated token has a limited validity period:
Duration: 3,600 seconds (1 hour).

Expiration: Once this time has elapsed, the token will be automatically invalidated, and requests will return a 401 Unauthorized error.

Renewal: You do not need to wait for the token to expire; your system can request a new one at any time using this same endpoint.

API

All communication between the client and the API is done exclusively through HTTPS, guaranteeing the encryption of information in transit using SSL/TLS.

How is communication between the client and the API ensured?

What type of authentication does the API use?

The API uses token-based authentication (JWT Bearer).

This mechanism allows the client to be identified and validated using a JWT token that represents their identity and permissions.

Are there tools to simulate payments in the test environment?

No. There is currently no automated tool to simulate referral payments in a test environment.
Testing must be performed manually using the workflows available in the provided test environment.

What type of authentication does the API use?

The API uses token-based authentication (JWT Bearer).

This mechanism allows the client to be identified and validated using a JWT token that represents their identity and permissions.

Payment Reference

What happens when a payment reference is created?

The first time a reference is created, the API returns the reference number.
In subsequent attempts with the same data, the API will indicate that the reference was already created, without generating a new one.

What values should be sent in paymentNumber and totalPayments when the credit involves a single payment?

If the loan involves a single payment, the value of paymentNumber must be 1 and the value of totalPayments must also be 1, indicating that it is a single payment.

Is the payment reference unique?

Yes. The reference is unique.

Does the reference have an expiration date?

The generated references are valid until the end of the calendar day in which they were created (23:59:59 hrs). For example: if you generate a reference on March 25th at 23:00 hrs, it will expire at 23:59 hrs on the same day.

Can I generate multiple references for the same user on the same day?

Yes. Each reference is a unique and independent payment slip, so you can create as many as you need for the same client.

What happens if the reference is not used?

If not used, the reference expires at the end of the day (23:59 hrs) and is invalidated for payment.