Plugins & SDKsReferencias APIAyudaForoReunión TécnicaFAQs

Smart Accounts

❗️

ADVERTENCIA

ESTA SECCIÓN SE ENCUENTRA EN MANTENIMIENTO POR LO QUE SE IRA CORRIGIENDO PROXIMAMENTE SI ES NECESARIO. GRACIAS POR SU COMPRESIÓN.

Esta implementación está diseñada para integrar puntos de venta que requieran realizar ventas con diferentes storeId dentro de una terminal usando un grupo de SmartAccount.

Pasos para seguir para realizar la integración con diferentes stores dentro de la terminal:

Para poder realizar una venta, reimpresión o cancelación es necesario primero solicitar la autorización a los servicios mediante una consulta al servidor y obtener un token de acceso o access_token. El servicio de autorización empleado es OAuth 2.0, el cuál permite autorizar una aplicación de manera estándar, fácil y segura.

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.

Puntos a tener en cuenta

  • El access_token se debe solicitar solo la primera vez que se desea autorizar la aplicación, las siguientes veces se debe emplear el refresh_token
  • El access_token tiene una duración de 12 horas (43199 segundos). Después de que expire, se debe solicitar un nuevo access_token como se menciona en el punto anterior.
  • Las credenciales generadas deben mantenerse seguras en todo momento para evitar que alguien haga mal uso de tu cuenta. No compartas tus credenciales en lugares públicos ni por medios poco seguros.

Ambientes

SANDBOX URL BASE:
http://nubeqa.netpay.com.mx:3334

PRODUCCIÓN URL BASE:
https://suite.netpay.com.mx/gateway

Estructura de una petición
POST /oauth-service/oauth/token

Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {{Auth_string}}

Body
grant_type={{grant_type}}&username={{username}}&password={{password}}

Ejemplo de solicitud / respuesta

****A continuación, se muestra un ejemplo de una petición para solicitar el access_token por primera vez, la renovación mediante el refresh_token y los diferentes mensajes de respuesta.

Solicitud por primera vez:

Ejemplo en cURL:

curl --location --request POST 'http://nubeqa.netpay.com.mx:3334/oauth-service/oauth/token'
--header 'Content-Type: application/x-www-form-urlencoded'
--header 'Authorization: Basic dHJ1c3RlZC1hcHA6c2VjcmV0'
--form 'grant_type=password'
--form 'username=Nacional'
--form 'password=netpay'

Respuestas

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.

Sucess:

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

Actualización de token vencido
Una vez el primer access_token generado ha llegado a su vida útil, es necesario solicitar uno nuevo. Para ello, se debe solicitar un nuevo access_token válido mediante el refresh_token.

Ahora, en el {grant_type} se debe enviar el valor refresh_token de la petición.

curl -L -X POST 'http://nubeqa.netpay.com.mx:3334/oauth-service/oauth/token'
-H 'Content-Type: application/x-www-form-urlencoded'
-H 'Authorization: Basic {{Auth_string}}'
--data-urlencode 'grant_type=refresh_token'
--data-urlencode 'refresh_token={{refresh_token}}'

Venta

Para esta integración se requiere ingresar en los parámetros de entrada el campo "isSmartAccounts" el cual contendrá un valor del tipo Boolean se debe asignar “true” para que el servicio de smartAccountLogin detecte el número de store (Solo funcionara para storeid que se encuentren en grupos de smart Accounts de lo contrario no hará el cambio y podría ocurrir un error en la sesión de la terminal)

Servicio: {{base_url}}/integration-service/transactions/sale

Headers:

Content-Type application/json
Authorization Bearer {{access_token}}

Ejemplo de un request de venta con smart Account activado:

Nota: En el header de authorization se debe enviar el access_token obtenido con el endpoint de autorización. 

{
   "traceability": {
 
   },
   "amount": 1.01,
   "serialNumber": "0821000119",
   "storeId": "455311",
   "isSmartAccounts":"true"
}

Respuesta del servicio 

{
   "code": "00",
   "message": "Mensaje enviado exitosamente"
}

Reimpresión

{{base_url}}/integration-service/transactions/reprint

Requerimientos: Tener un order id de una venta

Para realizar una reimpresión usando el servicio de reprint , se debe agregar el campo de isSamrtAccount, de lo contrario no hará el cambio de storeId en la terminal, tomando el que actualmente esté configurado de manera predeterminada.

Ejemplo de request de una reimpresión:

"traceability": {
   },
   "orderId": "200624084826-0821000119",
   "serialNumber": "0821000119",
   "storeId": "455311",
   "isSmartAccounts":"true"
}

Respuesta del servicio

{
   "code": "00",
   "message": "Mensaje enviado exitosamente"
}

Cancelación

Requerimientos: Tener un order id de una venta y que la fecha sea del mismo día que se requiera cancelar.

Para realizar una cancelación del tipo smart Accounts, seria de la misma forma en que se realiza una cancelación por push simple, solamente añadiendo el parámetro isSmartAccount. A continuación se presenta un ejemplo.

Servicio:

{{base_url}}/integration-service/transactions/cancel

Body Request:

{
   "traceability": {
   },
   "orderId": "200623160129-0821000119",
   "serialNumber": "0821000119",
   "storeId": "455311",
   "isSmartAccounts":"true"
}

Respuesta del servicio

{
   "code": "00",
   "message": "Mensaje enviado exitosamente"
}

Ejemplos:

Venta: Al momento de accionar la venta desde el punto con uno de los stores ligados al smart account la terminal recibirá la petición para realizar el cobro.

Paso 1:La terminal espera el medio de pago

272

Paso 2: Se ingresa la tarjeta a la terminal y si la transacción es exitosa y la tarjeta no requiere NIP se mostrará la leyenda de “Venta normal Aprobada”

Nota: En caso de que la tarjeta tenga NIP se mostrará la pantalla de ingresar Nip el cliente ingresa los 4 dígitos presione el botón verde y continuará con el flujo.

268

En caso de que la tarjeta no tenga Nip se mostrará la pantalla de “Ingrese su firma”

268

Paso 3: La terminal mostrará el ticket de venta para el comercio, y posteriormente la del cliente.

268 271

Reimpresión de un ticket de venta aprobado o cancelado, al momento de accionar la reimpresión desde el punto con uno de los stores ligados al smart account, la terminal recibirá la petición para re-impmir el ticket.

Reimpresión venta aprobada:

269

Reimpresión venta cancelada:

267

Cancelación: Al momento de accionar la cancelación desde el punto con uno de los stores ligados al smart account la terminal recibirá la petición para realizar la cancelación:

Paso 1 : La petición de cancelación llega a la terminal y envía mensaje de “Cancelación Su transacción ha sido aprobada”

270

Paso 2: La terminal arroja ticket de cancelación con el store indicado desde la petición del punto de venta.

269

Realizar una venta utilizando el store id del comercio bloqueado

En caso de que se envíe una petición con un store id que está bloqueado la terminal mostrará el siguiente mensaje “Usuario no válido”.

273

Json de respuesta:

{
  "affiliation": "1234567",
  "applicationLabel": "MasterCard",
  "arqc": "123ABCDE5220AAA0",
  "aid": "A00000000000101",
  "amount": "0.01",
  "authCode": "002001",
  "bankName": "SANTANDER",
  "cardExpDate": "02/24",
  "cardType": "C",
  "cardTypeName": "MASTERCARD",
  "cityName": "Monterrey NUEVO LEON",
  "responseCode": "00",
  "hasPin": false,
  "hexSign": "00000100000001DA00031CFF02FF02D2E71EEDAD20FF023CA8E0000009E0000000408687C3A711A0FF023BC8D1751898FF02B5D3CB23D53FF02496DCCC9EC56180FF020D7D921BB51184F9A4BC48C0FF0222025536EC6E748646BC4BA1F6F8FF023EC9B45BCB14C23FDB92F773DD4773DEB6FF022802673BB1A0FF02A920EA73C8F9FF021B80B5E9E8F28919DFED917F3B95722D8FF020D9D1FDFB01C65EBCCAEFF020E3BD0874B34FF029708FF023F3BD0FFF023DA5B820FF02574D92D760FF02F54630FBF04D7910940ADCFF0222629F0C4549DCC9A3037A6A0992889E806D3170E4FF02B9C53F1D9ABF98412A5CCD3D8B3CBC9744AD7CAF71E0CB35B11F80F948000DE74811701814AF0E80FF02FC58FF02F2E936FF02FD18A0FF026C40FF02CBDEFF02C410FF022980FF02C0FF0260FA8FF022797D8FF02C7EB70FF021B960CFF02C0DD08FF024C05A1BF4F02F840FF02FF02FF02",
  "isQps": 0.0,
  "message": "Transacción exitosa",
  "moduleCharge": "2",
  "moduleLote": "1",
  "customerName": "NOMBRE CLIENTE",
  "terminalId": "0100000001",
  "orderId": "191203000001-0010000001",
  "preAuth": "0",
  "preStatus": 0.0,
  "promotion": "0",
  "rePrintDate": "1.1.3",
  "rePrintMark": "MASTER",
  "reprintModule": "C",
  "cardNumber": "1234",
  "storeName": "Netpay",
  "streetName": "Centro",
  "ticketDate": "DIC. 03, 19 10:40:46 ",
  "tipAmount": "0.0",
  "tipLessAmount": "0.01",
  "transDate": "2019-12-03 10:38:25.CST",
  "transType": "A",
  "transactionCertificate": "01ABCA111001CC001",
  "traceability": {}
}