Intégrate con nuestra API | Proveedor de pagos electrónicos

La información necesaria para integrar ppe a tu negocio

¿Cómo empiezo?

PPE pone a su disposición dos entornos independientes. Este esquema permite a su equipo técnico experimentar con total libertad antes de procesar transacciones reales.

Entorno de pruebas (Sandbox)

Podrás empezar a utilizarla cuando se haya creado tu cuenta, este ambiente está destinado para realizar las pruebas y ajustes necesarios y utilizar todas las funcionalidades de la API. Utiliza este ambiente para probar e integrar tu aplicación.

Portal dashboard: https://dev.dash.proveedordepagos.mx/login

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

Entorno de producción

Es el ambiente operativo real para empezar a recibir pagos en efectivo y recibir notificaciones.

Para garantizar la estabilidad de su plataforma, el acceso a este entorno requiere completar satisfactoriamente la Certificación Técnica (Matriz de Pruebas) detallada en nuestra pestaña Integración.

Flujo para recibir pagos de Oxxo

Te mostramos cómo funciona el proceso de pago para tus clientes finales.

Pasos

En la aplicación de crédito, el usuario selecciona la opción:

Pago de crédito → Pago por OXXO.
La aplicación genera un código de barras asociado al crédito y al monto a pagar.
El usuario acude a cualquier tienda OXXO.
Se dirige a la caja y solicita realizar el pago de un servicio.
El usuario muestra el código de barras al cajero.
El cajero de OXXO escanea el código de barras.
El sistema de OXXO muestra en pantalla:
- Proveedor de pagos
- Monto del crédito a pagar
- Comisión por pago de servicio
El cajero solicita al usuario confirmar los datos del pago.
El usuario realiza:
- El pago del monto del crédito
- El pago de la comisión correspondiente a OXXO
El cajero entrega al usuario los comprobantes (tickets) del pago.
El pago se refleja aproximadamente en 30 minutos como un descuento aplicado al saldo del crédito

** Conservar ticket para aclaraciones

Guía de integración

Esta sección detalla los pasos obligatorios para configurar tu entorno de pruebas y validar tu integración antes de pasar a producción.

1. Canal de Comunicación Directa

Para garantizar una integración fluida, el equipo de PPE habilitará un grupo de WhatsApp dedicado a tu proyecto.

2. Obtención de Credenciales

Una vez establecido el canal de comunicación, recibirás tus llaves de acceso para el Sandbox (Entorno de pruebas) :

Username (Usuario)
Password (Contraseña)

3. Configuración de Webhooks y Notificaciones

Para que tu sistema pueda reaccionar a los eventos de pago, necesitamos conectar tu servidor con nuestro Sandbox.

Requisito: Genera una URL de Webhook y un Token de autenticación en tu servidor.
Acción: Comparte estos datos en el grupo de WhatsApp para que nuestro equipo los de alta en el sistema.
Simulación: Dado que en Sandbox no se procesa dinero real, nuestro equipo simulará los pagos manualmente para que recibas las notificaciones (HTTP POST) en tu endpoint.

Requisitos extra: Agrega nuestras direcciones IP a tu "Lista Blanca" (Whitelist) para que la comunicación no falle.

Para mayor seguridad solicita la IP por el grupo de whatsApp.

4. Certificación y Paso a Producción

Para asegurar la estabilidad de la integración, es necesario completar con éxito un ciclo de pruebas:

Meta: Realizar las pruebas exitosas en Sandbox.
Validación: Una vez confirmadas las operaciones, el equipo técnico autorizará el despliegue a producción y te entregará las credenciales definitivas.

PRUEBAS MÍNIMAS PARA PODER PASAR A PRODUCCIÓN

Enviar una referencia de pago sin número de crédito.
Enviar una referencia de pago sin monto de pago.
Enviar una referencia de pago con un monto de $1,200.00
Enviar una referencia de pago con un monto de $2,501.00
Crear el código de barras correctamente

¿Cómo ejecutar las pruebas en Sandbox?

Sigue este flujo de trabajo para validar que tu sistema recibe correctamente nuestras notificaciones de pago.

Soporte en tiempo real: Si te detienes en cualquier paso, escríbenos directamente en el grupo de WhatsApp y nuestro equipo de programadores especializados, te asistirá.

Flujo de Ejecución

Validación de Webhook: Antes de iniciar, confirma que ya nos proporcionaste tu URL de Webhook y el Token de seguridad. Sin esto, no recibirás las confirmaciones de pago.
Generación de Referencia: Crea una referencia de pago utilizando nuestra API.
Envía el número de referencia generado al grupo de WhatsApp.
Se procesará manualmente la simulación de pago en nuestro sistema de pruebas.
Confirmación de Notificación: Verifica que haya llegado a tu endpoint y que tu sistema la haya procesado correctamente. Para más información consulta Referencia de API.

Servicios de Pagos en Efectivo en Todo México

Proveedor de Pagos Electrónicos (PPE) pone a tu disposición dos servicios creados para nuestros clientes:

Genera un token
Crea una referencia de pago
Notificar pago recibido
Obtener un reporte de los pagos realizados por tus clientes
Obtener el saldo de los pagos realizados por tus clientes
Conoce los códigos de respuesta de PPE

Solicitar Referencia de pago en efectivo en las Tiendas Oxxo

Esta petición requiere un token de autenticación (JWT Bearer).
Genera tu token en la pestaña Generar un token antes de continuar.

Conoce el método para crear una referencia de pago para que tus clientes puedan realizar sus pago en cualquier tienda Oxxo de México.

Petición

POST {URL}/payments/reference

Respuesta exitosa

Respuesta no exitosa Http code 400

Ejemplo de petición

payments/reference

{

"loanNumber": "2",

"paymentAmount":5000,

"paymentNumber": 1,

"totalPayments": 6

}

Respuesta exitosa

{

"success": true,

"reference": "780000020000605000002024072910"

}

Respuesta no exitosa Http code 400

{

"success": false,

"message": "Ya existe una referencia para los datos ingresados."

}

Obtener los pagos realizados por tus clientes

Esta petición requiere un token de autenticación (JWT Bearer).
Genera tu token en la pestaña Generar un token antes de continuar.

Conoce el método para obtener los pagos realizados por tus clientes en un rango de fechas.

Petición

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

Respuesta exitosa

ACCEPTED: Orden pagada en Oxxo

NOTIFIED: Orden pagada en Oxxo y notificada a Webhook

REVERSED: Orden cancelada

Ejemplo de petición

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

Respuesta exitosa

{

"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

}

Respuesta no exitosa Http code 500

Array vacío

[ ]

Obtener balance de los pagos realizados por tus clientes de forma exitosa en Oxxo

Esta petición requiere un token de autenticación (JWT Bearer).
Genera tu token en la pestaña Generar un token antes de continuar.

Conoce el método para para que puedas obtener el balance actual de los pagos realizados por tus clientes de forma exitosa en cualquier tienda Oxxo de México.

Petición

GET {URL}/sofomes/get-balance

Respuesta exitosa

Ejemplo de petición

/sofomes/get-balance

Respuesta exitosa

{

"totalBalance": 54000,

"totalRefounds": 2600.00,

"totalCommissions": 560

}

Respuesta no exitosa Http code 500

Objeto vacío

[ ]

Notificar pago recibido (webhook)

Webhook para notificar que oxxo ha recibido pago de una referencia asociado a la sofom.

Datos de Entrada

Ejemplo

url/{token}

Petición

{

"eventType ": "PAYMENT_SUCCEEDED",

"transaction": {

"amount ": "5000",

"reference ": "410000020000605000002024072910",

"date ": "29/07/2024 14:11:01"

"message": null

}

Respuesta

(Header):

HTTP Status Code: 204

Generar Token

Método para generar token a partir de un usuario y contraseña que se genera cuando se da alta la sofom.

POST {URL}/login

Datos de entrada

Datos de salida

Ejemplo

{

"username" : "myUser",

"password" :"myPass"

}

Respuesta

{

"access_token": "eyJhbGciOiJIUzI1OiJ1.eyJzdWIiOiJ1c2VyU21mb20wMSIsIm5iZiI6MTcyMjUzMTUyMiwicm1sZXMiOltdLCJpc3MiOiJwcGUtc21mb20tcGF5bWVudHMtYXBpIiwiZXhwIjoxNzIyNTM1MTIyLCJpYXQiOjE3MjI1MzE1MjJ9.BmRWruyfcBhaBMAlNTyeRopOIE8rmj1LTSOJn1q-i90",

"token_type": "Bearer",

"expires_in": 3600,

"username": "myUser"

}

Seguridad y Vigencia del Token

Por protocolos de seguridad y protección de datos, cada token generado tiene una validez limitada:

Duración: 3600 segundos (1 hora).

Expiración: Una vez transcurrido este tiempo, el token será invalidado automáticamente y las peticiones devolverán un error 401 Unauthorized.

Renovación: No es necesario esperar a que el token expire; su sistema puede solicitar uno nuevo en cualquier momento mediante este mismo endpoint.

Matriz de certificación para recibir pagos en Oxxo

Para que tu empresa pueda pasar a producción deberá realizar las siguientes pruebas de forma exitosa:

Enviar una referencia de pago sin número de crédito.
Enviar una referencia de pago sin monto de pago.
Enviar una referencia de pago con un monto de $1,200.00
Enviar una referencia de pago con un monto de $2,501.00
Crear el código de barras correctamente.

API

Toda la comunicación entre el cliente y la API se realiza exclusivamente a través de HTTPS, garantizando el cifrado de la información en tránsito mediante SSL/TLS.

¿Cómo se asegura la comunicación entre el cliente y la API?

¿Qué tipo de autenticación utiliza la API?

La API utiliza autenticación basada en token (JWT Bearer).

Este mecanismo permite identificar y validar al cliente mediante un token JWT que representa su identidad y permisos.

¿Existen herramientas para simular pagos en el ambiente de pruebas?

No. Actualmente no existe una herramienta automática para simular el pago de referencias en el ambiente de pruebas.
Las pruebas deben realizarse de manera manual mediante los flujos disponibles en el entorno de pruebas proporcionado.

¿Qué formato de datos utiliza la API?

Por estándares de seguridad y rapidez, nuestra API opera exclusivamente con formato JSON.

Referencia de pago

¿Qué sucede cuando se crea una referencia de pago?

La primera vez que se crea una referencia, la API devuelve el número de referencia.
En intentos posteriores con los mismos datos, la API indicará que la referencia ya fue creada, sin generar una nueva.

¿Qué valores deben enviarse en paymentNumber y totalPayments cuando el crédito contempla un solo pago?

Si el crédito contempla un solo pago, el valor de paymentNumber debe ser 1 y el valor de totalPayments también debe ser 1, indicando que se trata de un pago único.

¿La referencia de pago es única?

Sí. La referencia es única.

¿La referencia tiene vigencia?

Las referencias generadas tienen vigencia hasta el final del día natural en que fueron creadas (23:59:59 hrs). Por ejemplo: si genera una referencia el 25 de marzo a las 23:00 hrs, esta expirará a las 23:59 hrs del mismo día.

¿Puedo generar múltiples referencias para un mismo usuario el mismo día?

Sí. Cada referencia es un folio de pago único e independiente, por lo que puedes crear todas las que necesites para un mismo cliente.

¿Qué pasa si no se utiliza la referencia?

Si no se utiliza, la referencia caduca al finalizar el día (23:59 hrs) y queda invalidada para el pago.