Servicios Paynet
Con la finalidad de ofrecer a los clientes un servicio rápido y sin complicaciones, Openpay expone el API Paynet que permiten interactuar directamente con las cadenas de tiendas de conveniencia al momento de procesar pagos o retiros.
En está guía te explicamos detalladamente la manera en que funcionan nuestros servicios para que puedas integrarlos de forma sencilla y rapida, y de esta manera tus sistemas queden conectados con la red Paynet.
API Endpoints
La API REST de Paynet tiene un ambiente de pruebas (sandbox) y un ambiente de producción. La siguientes URIs forman la base de los endpoints para los ambientes soportados:
Pruebas, URI base:
https://sandbox-api.paynet.com.mx
Producción, URI base:
https://production-api.paynet.com.mx
Un endpoint completo esta formado por la URI base del ambiente, el identificador de la cadena y el recurso.
Por ejemplo, para enviar una petición de autorización, el endpoint sería:
https://sandbox-api.paynet.com.mx/v1/mzdtln0bmtms6o3kck8f/authorization
Para crear una petición completa es necesaria envíar las cabeceras HTTP correctas y la información en formato JSON.
Autenticación
Para realizar peticiones a la API de Paynet, es necesario enviar la llave de API (API Key) en todas tus llamadas a nuestros servidores. La llave será generada y entregada por Openpay.
Para la autenticación al API debes usar autenticación de acceso básica, donde la llave de API es el nombre de usuario. La contraseña no es requerida y debe dejarse en blanco por fines de simplicidad.
Pasos de flujo de Pago
El proceso de autorización de una referencia sigue los pasos descritos a continuación:

- El cliente acude a realizar un pago a una tienda de tu cadena.
- La cadena solicita la autorización del pago a los servicios Paynet.
- Openpay realiza una validación online con los servicios autorizadores de los comercios si es que se requiere.
- El comercio efectúa la validación de la referencia correspondiente e informa a Paynet si se autoriza o se rechaza la operación.
- Openpay responderá a tu tienda si la transacción debe ser aceptada o rechazada.
En caso de haber algún problema al realizar la autorización del pago, es posible ejecutar el proceso de cancelación el cual se describe a continuación:

- El cliente acude a realizar un pago en cualquier tienda de tu cadena.
- La cadena solicita la autorización del pago a los servicios Paynet.
- La tienda pierde la comunicación con Paynet.
- La tienda realiza la petición de Cancelación.
- Paynet realiza la validación de la petición de cancelación y responde si ha sido cancelada o no la transacción.
Pasos de flujo de Retiro
El proceso de autorización de un retiro de efectivo sigue los pasos descritos a continuación:

- El cliente acude a realizar un retiro de efectivo a una tienda de tu cadena con una referencia.
- La cadena solicita la autorización del retiro de efectivo a través de los servicios Cashout de Paynet.
- Openpay realiza una validación online con los servicios autorizadores de los comercios.
- El comercio efectúa la validación de la referencia correspondiente en caso de ser pre autorizada el comercio envía a Openpay un código de pre autorización, adicionalmente el comercio envía un número de identificación personal (PIN) vía SMS al cliente.
- Openpay responderá a tu tienda el código de pre autorización si el retiro de efectivo debe ser aceptado o el rechazo de la operación.
El proceso de autorización con PIN del retiro de efectivo se describe en los siguientes pasos:

- El cliente recibe el SMS con el número de identificación personal (PIN)
- La cadena solicita la autorización con PIN del retiro de efectivo a los servicios Cashout de Paynet.
- Openpay realiza una validación online del código de pre autorización y el PIN con los servicios autorizadores de los comercios.
- El comercio realiza la validación del código de pre autorización y el PIN en caso de ser autorizada el comercio envía un código de autorización.
- Openpay responderá a tu tienda el código de autorización si el retiro de efectivo debe ser efectuado o el rechazo de la operación.
El proceso de confirmación del retiro de efectivo se describe en los siguientes pasos:

- La cadena entrega el efectivo al cliente.
- La cadena envía la confirmación del retiro de efectivo a los servicios Cashout de Paynet.
- Openpay registra la confirmación del retiro de efectivo.
Integración de servicios Paynet.
Para que la cadena pueda interactuar con Paynet y procesar los pagos, es necesarío integrar los siguientes servicios:
- Servicio de autorización (Pago o retiro de efectivo)
- Servicio de reverso automático
- Servicio de confirmación de retiro de efectivo
Servicio de autorización
El servicio de autorización será llamado cuando un cliente intente realizar un pago o retiro de efectivo en la tienda. Paynet procesará la petición y responderá a la cadena el resultado de la autorización.
Petición de Autorización
La petición debe ser un HTTPS POST con contenido de tipo application/json, codificado en UTF-8.
El cuerpo de la petición contendrá un objeto JSON con los siguientes atributos:
Nombre | Tipo | Longitud | Requerido | Descripcion |
---|---|---|---|---|
idGroup | Numérico | 1 - 11 | Sí | Identificador de la cadena en Paynet |
idChain | Numérico | 1 - 11 | Sí | Identificador de la sub-agrupación de la cadena. |
idStore | Numérico | 1 - 11 | Sí | Identificador de la tienda donde se esta realizando el pago. |
idPos | Numérico | 1 - 11 | Sí | Identificador de la caja o punto de venta en donde se realiza el pago. |
idEmployee | Numérico | 1 - 11 | Sí | Identificador del empleado que realiza el cobro al cliente. |
chainTransactionId | Numérico | 1 - 45 | Sí | Identificador generado por la cadena asociada a la operación. |
reference | Alfanumérico | 1 - 40 | Sí | Referencia la cual esta asociada al pago o cuenta de depósito. |
amount | Numérico | 1 - 15 | Sí | El monto por el que se esta efectuando el pago. |
operationDate | Fecha | -- | Sí | La fecha y hora del pago efectuado, en formato Unix en milisegundos. |
sku | Numérico | 1 - 250 | No | Código del servicio el cual está siendo pagado. |
Serán ignorados los atributos que no esten listados en la tabla.
El orden de los atributos no importa.
Ejemplo de la petición HTTP:
POST https://sandbox-api.paynet.com.mx/v1/{CHAIN_ID}/payment HTTP/1.1
Content-Type: application/json
{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"reference":"OPENPAY00FUCDZDQ9",
"amount":10.00,
"operationDate":1509053135780,
"chainTransactionId":170911001,
"sku":34123412341234
}
Ejemplo usando curl:
curl https://sandbox-api.paynet.com.mx/v1/{CHAIN_ID}/payment \
-H "Content-type: application/json" \
-d '{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"reference":"OPENPAY00FUCDZDQ9",
"amount":10.00,
"operationDate":1509053135780,
"chainTransactionId":170911001,
"sku":34123412341234
}' \
-X POST
Respuesta del servicio de autorización
El servicio responderá HTTP 200 OK, con un cuerpo de tipo application/json con los siguientes campos:
Nombre | Tipo | Descripcion |
---|---|---|
transactionId | Alfanumérico | Identificador generado por Openpay de la operación en curso. |
chainTransactionId | Numérico | Identificador generado por la cadena asociada a la operación. |
authorization | Numérico | Número de autorización de la transacción. |
pinValidation | Booleano | Indica si se requiere código de validación para confirmar la transacción. |
requiresConfirmation | Booleano | Indica si requiere una petición adicional para confirmar la transacción |
operationType | Numérico | Indica el tipo de operación que se realizará: 1-Pago 2-Retiro. |
amount | Numérico | El monto correspondiente a la referencia. |
operationInstructions | Alfanumérico | Instrucciones que se deben mostrar en pantalla en el punto de venta. |
operationDate | Fecha | La fecha y hora de la transacción, en formato Unix en milisegundos. |
requestId | Alfanumérico | Identificador del la petición |
responseCode | Numérico | Código de respuesta |
descriptionCode | Cadena | Descripción del código de la respuesta. |
customerInstructions | Cadena | Instrucciones que se deben incluir en el ticket para que el cliente realice aclaraciones con el comercio a cerca del pago. |
Ejemplo de respuesta exitosa:
{
"transactionId":"trdhetcimds43arc9",
"chainTransactionId":170911001,
"authorization":"123442",
"pinValidation":"true",
"requiresConfirmation":"true",
"operationType":"1",
"amount":"150.00",
"operationInstructions":"PAGO COMPLETADO DE LA REFERENCIA OPENPAY00FUCDZDQ9 CON NO. DE AUTORIZACIÓN: 123442",
"operationDate":1505171988,
"requestId":"kuysdtcaygs67asd6",
"responseCode":0,
"descriptionCode":"Success",
"customerInstructions":"ESTIMADO CLIENTE PARA CUALQUIER DUDA O ACLARACION FAVOR DE COMUNICARSE A AL CORREO example@email.com O AL TELEFONO 0180012345678 "
}
Ejemplo de respuesta fallida:
{
"requestId":"kuysdtcaygs67asd6",
"operationDate":1505171988,
"chainTransactionId":170911001,
"responseCode":12,
"descriptionCode":"Transacción inválida."
}
Servicio de Reverso Automático de Pago
El servicio de reverso automático se utiliza únicamente en caso de que ocurra algún error y no se obtenga confirmación de la autorización de un pago para evitar inconcistencias entre la cadena y Openpay. En general deben enviarse los mismos datos de la autorización.
Es muy importante que en caso de ocurrir un error de conexión durante la autorización del pago, se debe lanzar posteriormente una petición de reverso utilizando los datos de la petición de autorización antes de reintentar el pago.
Petición de Reverso automático
La petición debe ser un HTTPS POST con contenido de tipo application/json, codificado en UTF-8.
El cuerpo de la petición contendrá un objeto JSON con los siguientes atributos:
Nombre | Tipo | Longitud | Requerido | Descripción |
---|---|---|---|---|
idGroup | Numérico | 1 - 11 | Sí | Identificador de la cadena en Paynet |
idChain | Numérico | 1 - 11 | Sí | Identificador de la sub-agrupación de la cadena. |
idStore | Numérico | 1 - 11 | Sí | Identificador de la tienda donde se está realizando el pago. |
idPos | Numérico | 1 - 11 | Sí | Identificador de la caja o punto de venta en donde se realiza el pago. |
idEmployee | Numérico | 1 - 11 | Sí | Identificador del empleado que realiza el cobro al cliente. |
chainTransactionId | Numérico | 1 - 45 | Sí | Identificador generado por la cadena asociada a la operación. |
reference | Alfanumérico | 1 - 40 | Sí | Referencia la cual esta asociada al pago o cuenta de depósito. |
amount | Numérico | 1 - 15 | Sí | El monto por el que se está efectuando el pago. |
operationDate | Fecha | -- | Sí | La fecha y hora del pago efectuado, en formato Unix en milisegundos. |
sku | Numérico | 1 - 250 | No | Código del servicio el cual está siendo pagado. |
authorization | Numérico | 1 - 20 | No | Número de autorización de la transacción de pago. |
Serán ignorados los atributos que no esten listados en la tabla.
No importa el orden de los atributos.
Ejemplo de la petición HTTP:
POST https://sandbox-api.paynet.com.mx.mx/v1/{CHAIN_ID}/reverse HTTP/1.1
Content-Type: application/json
{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"reference":"OPENPAY00FUCDZDQ9",
"amount":10.00,
"authorization":"9882347",
"operationDate":1509053135780,
"chainTransactionId":170911001,
"sku":34123412341234
}
Ejemplo usando curl:
curl https://sandbox-api.paynet.com.mx.mx/v1/{CHAIN_ID}/reverse \
-H "Content-type: application/json" \
-d '{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"reference":"OPENPAY00FUCDZDQ9",
"amount":10.00,
"authorization":"9882347",
"operationDate":1509053135780,
"chainTransactionId":170911001,
"sku":34123412341234
}' \
-X POST
Respuesta del servicio de reverso automático
El servicio responderá HTTP 200 OK, con un cuerpo de tipo application/json con los siguientes campos:
Nombre | Tipo | Descripción |
---|---|---|
requestId | Alfanumérico | Identificador del la petición |
chainTransactionId | Numérico | Identificador generado por la cadena asociada a la operación. |
authorization | Numérico | Número de autorización de la transacción. |
operationDate | Fecha | La fecha y hora del pago efectuado, en formato Unix en milisegundos. |
responseCode | Numérico | Código de respuesta |
descriptionCode | Cadena | Descripción del código de la respuesta. |
Ejemplo de respuesta exitosa:
{
"requestId":"kuysdtcaygs67asd6",
"operationDate":1509053135780,
"chainTransactionId":170911001,
"authorization":"124242",
"responseCode":0,
"descriptionCode":"Success"
}
Ejemplo de respuesta fallida:
{
"requestId":"kuysdtcaygs67asd6",
"operationDate":1509053135780,
"chainTransactionId":170911001,
"responseCode":12,
"descriptionCode":"Transacción inválida."
}
Servicio de autorización con PIN de retiro de efectivo
El servicio de autorización con PIN de retiro de efectivo será llamado cuando el cliente proporcione su código PIN para realizar una disposición de efectivo con su referencia en la tienda. Paynet procesará la petición y responderá a la cadena el resultado de la autorización del PIN.
Petición de Autorización con PIN de Retiro de Efectivo
La petición debe ser un HTTPS POST con contenido de tipo application/json, codificado en UTF-8.
El cuerpo de la petición contendrá un objeto JSON con los siguientes atributos:
Nombre | Tipo | Longitud | Requerido | Descripcion |
---|---|---|---|---|
idGroup | Numérico | 1 - 11 | Sí | Identificador de la cadena en Paynet |
idChain | Numérico | 1 - 11 | Sí | Identificador de la sub-agrupación de la cadena. |
idStore | Numérico | 1 - 11 | Sí | Identificador de la tienda donde se esta realizando el pago. |
idPos | Numérico | 1 - 11 | Sí | Identificador de la caja o punto de venta en donde se realiza el pago. |
idEmployee | Numérico | 1 - 11 | Sí | Identificador del empleado que realiza el cobro al cliente. |
transactionId | Alfanumérico | 1 - 45 | Sí | Identificador generado por Openpay de la operación en curso. |
chainTransactionId | Numérico | 1 - 45 | Sí | Identificador generado por la cadena asociada a la operación. |
reference | Alfanumérico | 1 - 40 | Sí | Referencia la cual esta asociada al pago o cuenta de depósito. |
preAuthorization | Alfanumérico | 1 - 40 | Sí | Número de pre autorización del comercio |
pin | Alfanumérico | 1 - 8 | Sí | Código personal PIN |
operationDate | Fecha | -- | Sí | La fecha y hora del pago efectuado, en formato Unix en milisegundos. |
Serán ignorados los atributos que no esten listados en la tabla.
No importa el orden de los atributos.
Ejemplo de la petición HTTP:
POST https://sandbox-api.paynet.com.mx/v1/{CHAIN_ID}/cashout/pinauthorize HTTP/1.1
Content-Type: application/json
{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"transactionId":"trtj1wlpg5wrhfaqlh9r",
"chainTransactionId":170911001,
"reference":"OPENPAY00FUCDZDQ9",
"preAuthorization":"123ABC",
"pin":"3409",
"operationDate":1509053135780
}
Ejemplo usando curl:
curl https://sandbox-api.paynet.com.mx/v1/{CHAIN_ID}/cashout/pinauthorize \
-H "Content-type: application/json" \
-d '{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"transactionId":"trtj1wlpg5wrhfaqlh9r",
"chainTransactionId":170911001,
"reference":"OPENPAY00FUCDZDQ9",
"preAuthorization":"123ABC",
"pin":"3409",
"operationDate":1509053135780
}' \
-X POST
Respuesta del servicio de autorización con PIN de retiro de efectivo
El servicio responderá HTTP 200 OK, con un cuerpo de tipo application/json con los siguientes campos:
Nombre | Tipo | Descripcion |
---|---|---|
transactionId | Alfanumérico | Identificador generado por Openpay de la operación en curso |
chainTransactionId | Numérico | Identificador generado por la cadena asociada a la operación. |
authorization | Numérico | Número de autorización de la transacción. |
operationDate | Fecha | La fecha y hora de la solicitud de retiro de efectivo, en formato Unix en milisegundos. |
responseCode | Numérico | Código de respuesta |
descriptionCode | Cadena | Descripción del código de la respuesta. |
Ejemplo de respuesta exitosa:
{
"transactionId":"trtj1wlpg5wrhfaqlh9r",
"operationDate":1505171988,
"chainTransactionId":170911001,
"authorization":"124242",
"responseCode":0,
"descriptionCode":"Success"
}
Ejemplo de respuesta fallida:
{
"requestId":"trtj1wlpg5wrhfaqlh9r",
"operationDate":1505171988,
"chainTransactionId":170911001,
"responseCode":12,
"descriptionCode":"Transacción inválida."
}
Servicio de confirmación de retiro de efectivo
El servicio de confirmación de retiro de efectivo será llamado cuando la cadena haya entregado el efectivo al cliente. Este servicio realiza la confirmación de la transacción de disposición de efectivo.
Petición de Confirmación de Retiro de Efectivo
La petición debe ser un HTTPS POST con contenido de tipo application/json, codificado en UTF-8.
El cuerpo de la petición contendrá un objeto JSON con los siguientes atributos:
Nombre | Tipo | Longitud | Requerido | Descripción |
---|---|---|---|---|
idGroup | Numérico | 1 - 11 | Sí | Identificador de la cadena en Paynet |
idChain | Numérico | 1 - 11 | Sí | Identificador de la sub-agrupación de la cadena. |
idStore | Numérico | 1 - 11 | Sí | Identificador de la tienda donde se está realizando el pago. |
idPos | Numérico | 1 - 11 | Sí | Identificador de la caja o punto de venta en donde se realiza el pago. |
idEmployee | Numérico | 1 - 11 | Sí | Identificador del empleado que realiza el cobro al cliente. |
transactionId | Alfanumérico | 1 - 45 | Sí | Identificador generado por Openpay de la operación en curso. |
chainTransactionId | Numérico | 1 - 45 | Sí | Identificador generado por la cadena asociada a la operación. |
reference | Alfanumérico | 1 - 40 | Sí | Referencia la cual esta asociada al pago o cuenta de depósito. |
authorization | Alfanumérico | 1 - 40 | Sí | Número de pre autorización del comercio |
pin | Alfanumérico | 1 - 8 | Sí | Código personal PIN |
operationDate | Fecha | -- | Sí | La fecha y hora del pago efectuado, en formato Unix en milisegundos. |
Serán ignorados los atributos que no esten listados en la tabla.
No importa el orden de los atributos.
Ejemplo de la petición HTTP:
POST https://sandbox-api.paynet.com.mx.mx/v1/{CHAIN_ID}/cashout/confirmation HTTP/1.1
Content-Type: application/json
{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"transactionId":"trtj1wlpg5wrhfaqlh9r",
"chainTransactionId":170911001,
"reference":"OPENPAY00FUCDZDQ9",
"authorization":"9882347",
"pin":"3409",
"operationDate":1509053135780
}
Ejemplo usando curl:
curl https://sandbox-api.paynet.com.mx.mx/v1/{CHAIN_ID}/cashout/confirmation \
-H "Content-type: application/json" \
-d '{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"transactionId":"trtj1wlpg5wrhfaqlh9r",
"chainTransactionId":170911001,
"reference":"OPENPAY00FUCDZDQ9",
"authorization":"9882347",
"pin":"3409",
"operationDate":1509053135780
}' \
-X POST
Respuesta del servicio de confirmación de retiro de efectivo
El servicio responderá HTTP 200 OK, con un cuerpo de tipo application/json con los siguientes campos:
Nombre | Tipo | Descripción |
---|---|---|
requestId | Alfanumérico | Identificador del la petición |
chainTransactionId | Numérico | Identificador generado por la cadena asociada a la operación. |
operationDate | Fecha | La fecha y hora del pago efectuado, en formato Unix en milisegundos. |
responseCode | Numérico | Código de respuesta |
descriptionCode | Cadena | Descripción del código de la respuesta. |
Ejemplo de respuesta exitosa:
{
"requestId":"kuysdtcaygs67asd6",
"operationDate":1509053135780,
"chainTransactionId":170911001,
"authorization":"124242",
"responseCode":0,
"descriptionCode":"Success"
}
Ejemplo de respuesta fallida:
{
"requestId":"kuysdtcaygs67asd6",
"operationDate":1509053135780,
"chainTransactionId":170911001,
"responseCode":12,
"descriptionCode":"Transacción inválida."
}
Códigos de respuesta
Los códigos de respuesta del servicio para la Autorización o la Cancelación son:
Código | Descripción | Causa |
---|---|---|
0 | Operación exitosa | Transacción autorizada. El pago en la tienda será aceptado. |
12 | Transacción inválida | Transacción rechazada. |
30 | Error de formato | El formato de la referencia es incorrecto. |
88 | Monto inválido | El monto de la transacción es inválido. |
93 | Adquiriente inválido | El sistema no reconoce la referencia. |
96 | Error de sistema | Ocurrió un error en el servicio |
Códigos de formas de pago
Los códigos de formas de pago son:
Código | Descripción |
---|---|
1 | Efectivo |
2 | Débito |
3 | Crédito |
4 | Monedero electrónico |