Servicios Cashout
Con la finalidad de ofrecer a los clientes una forma de retiro de efectivo rápido y sin complicaciones, Openpay expone los servicios Cashout de Paynet que permiten interactuar directamente con las cadenas de tiendas de conveniencia al momento de realizar retiros de efectivo.
En está guía te explicamos detalladamente la manera en que funcionan nuestros servicios para que puedas integrarlos de forma sencilla y rápida, y de esta forma tus sistemas queden conectados con la red Paynet.
Pasos de flujo
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. Adicionalmente realiza la validación de la referencia para indentificar si se requiere validación por PIN.
- El comercio efectúa la validación de la referencia correspondiente en caso de ser autorizada (sin validación por PIN) o pre autorizada (con validación por PIN) el comercio envía a Openpay un código de autorización, adicionalmente si la referencia requiere validación por PIN el comercio envía el número de identificación personal 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. Si la operación es acepta también se devuelve si se requiere evaluación por PIN.
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.
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 de retiro de efectivo, el endpoint sería:
https://sandbox-api.paynet.com.mx/v1/mzdtln0bmtms6o3kck8f/cashout/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.
Integración de servicios Paynet.
Para que la cadena pueda interactuar con Paynet y procesar los retiro de efectivo, es necesarío integrar los siguientes servicios:
- Servicio de autorización de retiro de efectivo
- Servicio de autorización con PIN de retiro de efectivo
- Servicio de confirmación de retiro de efectivo
Servicio de autorización de retiro de efectivo
El servicio de autorización de retiro de efectivo será llamado cuando un cliente intente 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.
Petición de Autorizació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 | 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. |
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/authorization HTTP/1.1
Content-Type: application/json
{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"reference":"OPENPAY00FUCDZDQ9",
"amount":100.00,
"operationDate":1509053135780,
"chainTransactionId":170911001
}
Ejemplo usando curl:
curl https://sandbox-api.paynet.com.mx/v1/{CHAIN_ID}/cashout/authorization \
-H "Content-type: application/json" \
-d '{
"idGroup":555,
"idChain":1,
"idStore":1292,
"idPos":1,
"idEmployee":2,
"reference":"OPENPAY00FUCDZDQ9",
"amount":100.00,
"operationDate":1509053135780,
"chainTransactionId":170911001
}' \
-X POST
Respuesta del servicio de autorización 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. |
preAuthorization | Numérico | Número de pre autorización de la transacción. |
pinValidation | Booleano | Indica si se requiere PIN de validación en el flujo. |
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,
"preAuthorization":"124242",
"pinValidation":"false",
"responseCode":0,
"descriptionCode":"Success"
}
Ejemplo de respuesta fallida:
{
"requestId":"trtj1wlpg5wrhfaqlh9r",
"operationDate":1505171988,
"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. |