API REFERENCE

Netpay cuenta con diferentes productos y servicios enfocados a diferentes segmentos del mercado. Contamos con soluciones para pagos con tarjeta presente, tarjeta no presente y servicios de facturación.

Actualmente se utiliza un API para cada aplicación y todas ellas están basadas en los principios REST. Nuestras APIs devuelven respuestas codificadas en formato JSON y utilizan códigos de respuesta HTTP estandares.

Puedes operar en el ambiente de pruebas donde ningún cobro será real o puedes operar en el ambiente de producción donde los cargos serán reales, debitando el saldo de la cuenta del cliente. Para cambiar entre ambientes únicamente debes cambiar la url base, configurar los accesos de cada ambiente y en caso de que se requiera cambiar entre versiones de aplicación.

Terminal Smart API

El API de la terminal punto de venta Smart te permite conectar tus aplicaciones con la terminal para realizar cobros a tus clientes con tarjetas presentes.

Nuestra API está desarollada en torno a las necesidades de un negocio respecto a sistemas de cobro con tarjeta presente. El API te permiritá realizar ventas con o sin meses sin intereses, cancelaciones y reimpresión de ticket de una venta realizada.

Puedes reviar nuestra guía de integración de la terminal punto de venta Smart, la cuál te guiará paso a paso para poder tener la terminal conectada a tu sistema.

Integrar la terminal Netpay Smart es tan sencillo como consumir servicios REST desde tu software. Los siguientes pasos te ayudarán a potenciar tu software punto de venta con la terminal Smart:

1. Adquirir una terminal para realizar el desarollo y pruebas.
2. Crear una cuenta de desarrollador para obtener credenciales de prueba.
3. Seguir la guía para realizar la integración.
4. Certificar tu integración.
5. Alta de comercio.
6. Go Live.

A continuación se detalla cada enpoint necesario a consumir así como los valores necesarios, tipo de dato y longitud de cada uno.

Ambientes

SANDBOX:

URL BASE https://sandbox.netpay.com.mx

PRODUCCIÓN:

URL BASE https://suite.netpay.com.mx

Autorización

Es necesario autorizar la aplicación para obtener un token de acceso o access_token el cuál nos permitirá consumir los demás servicios que se verán más adelante. Puedes seguir la guía sobre autorización para información más detallada.

Para obtener un access_token es necesario contar con los siguientes datos:  

• {Auth_string} : Cadena de texto codificado enviado en los headers de la petición.
• {grant_type} : Es la manera en la que una aplicación obtiene un access_token.
• {username} : usuario para solicitar un access_token.
• {password} : contraseña para solicitar un access_token.

Ver: Obtener datos de acceso para OAuth

POST /gateway/oauth-service/oauth/token

Headers

Body

Respuesta

Se pueden obtener diferentes mensajes de respuesta dependiendo la situación.

• SUCCESS: Se obtendrá la siguiente respuesta con un access_token y refresh_token válido si las credenciales enviadas han sido las correctas.
• UNAUTHORIZED: Se obtendrá la siguiente respuesta si el {Auth_string} enviado está incorrecto o ha sido deshabilitado.
• MISSING GRANT TYPE: Se obtendrá la siguiente respuesta si el {grant_type} no se ha enviado en la petición.
• UNSUPPORTED GRANT TYPE: Se obtendrá la siguiente respuesta si el {grant_type} enviado en la petición es incorrecto.
• INVALID USERNAME OR PASSWORD: Se obtendrá la siguiente respuesta si el {username} o {password} enviado en la petición es incorrecto.

NOTA: el access_token y refresh_token se han recortado para efectos ilustrativos. En la práctica ambos tokens son de una longitud mayor variable.

{
    "access_token": "CI6IkpXVCJ9wianReyJhdWQiOlsib2F1dGgyX2lkIl0sInVzZX",
    "token_type": "bearer",
    "refresh_token": "mlkLnJtei45NUBnbWFpbC5jb20iLCJzY6ImRhd_3yghIRLnew",
    "expires_in": 43199,
    "scope": "read write",
    "jti": "32116378-023b-9331-0920-ff1e2e200601"
}

{
    "timestamp": "2020-02-19T15:21:21.347+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized",
    "path": "/oauth/token"
}

{
    "error": "invalid_request",
    "error_description": "Missing grant type"
}

{
    "error": "unsupported_grant_type",
    "error_description": "Unsupported grant type: example"
}

{
    "error": "unauthorized",
    "error_description": "Invalid username or password."
}

Solicitud de venta

Para realizar una transacción de venta, es necesario consumir el servicio de VENTA, el cuál enviará la petición a la terminal para que sea procesada. Puedes revisar la guía sobre como solicitar una venta para información más detallada.

Para que la terminal pueda recibir y procesar la información, la aplicación debe estar en la pantalla principal, de lo contrario, la solicitud no será desplegada en la terminal.

POST /gateway/integration-service/transactions/sale

Headers

Body

{
    "serialNumber": "{serialNumber}",
    "amount": {amount},
    "storeId": "{storeId}",
    "traceability": {}
}

A continuacón, se muestran los diferentes parametros que se pueden enviar en el endpoint VENTA

Cancelacion

A veces, es necesario cancelar una transacción realizada. La cancelación se puede realizar desde el punto de venta consumiendo el servicio de CANCELACIÓN. Puedes revisar la guía sobre cómo cancelar una venta para información más detallada.

NOTA: la cancelación únicamente aplica para transacciónes realizadas en el mismo día en que se desea realizar la cancelación.

POST /gateway/integration-service/transactions/cancel

Headers

Body

{
    "serialNumber": "{serialNumber}",
    "orderId": "{orderId}",
    "storeId": "{storeId}",
}

Reimpresion

Es importante implementar el servicio de REIMPRESIÓN para poder brindar una copia al cliente o al negocio en caso de que se requiera y por algún motivo no se cuente con los tickets impresos durante la venta. Puedes consultar una guía con más detalles sobre la reimpresión.

POST /gateway/integration-service/transactions/reprint

Headers

Body

{
    "serialNumber": "{serialNumber}",
    "orderId": "{orderId}",
    "storeId": "{storeId}",
}