| Document Information | |
|---|---|
| File: | ATIONET - Pagos con código QR dinámico |
| Doc Version: | 1.0 |
| Release Date: | 26, August 2021 |
| Author: | ATIONet LLC |
| Change Log | ||
|---|---|---|
| Ver. | Date | Change Summary |
| 1.0 | 26/August/2021 | Initial version. |
- Visión general
- Secuencia de pagos con código QR
- Implementación de pagos con código QR dinámico
- Documentación de API
- Manejo de errores
- Mensajes de ejemplo
Ationet fleet Mobile payments - Dynamic QR permite generar el código QR dinámico desde su POS/Sistema de facturación para un pedido/factura específico para lo cual se debe pasar la información específica del pedido, como el Dispatch ID, el monto del pedido, etc., mientras se genera la imagen del código QR. El cliente puede escanear este QR para realizar un pago y el Backend del POS puede verificar el estado de la transacción utilizando el ID de envío.
Nota: Se requiere una pantalla orientada al cliente, que le mostrará el QR generado dinámicamente para poder
escanearlo y generar la venta.
- El cliente elige los productos/servicios en una tienda y muestra la intención de pago usando la aplicación Ationet Driver.
- El cajero crea un pedido con el monto de la factura y un Dispatch ID único en el sistema POS.
- El servidor backend de POS crea un código QR y se lo muestra al cliente en la pantalla de cara al consumidor.
- El cliente escanea el codigo QR usando Ationet Driver App.
- El servidor de backend de POS comienza a sondear automáticamente el estado de la transacción 8 veces por minuto utilizando el Dispatch ID.
La sección describe los pasos de integración necesarios para integrar los pagos con código QR dinámico de ATIONet con el punto de venta de facturación para aceptar pagos sin contacto de su cliente mediante la aplicación Ationet Driver.
- Clave de backend de POS: una clave secreta única que se utiliza para asegurar el cifrado de cada solicitud. Esto debe mantenerse en el lado del servidor y no debe compartirse con nadie.
Debe solicitar sus claves a ATIONET.
Nota: Nunca comparta la clave secreta de backend de su POS con nadie.
El Backend de POS solo codifica la información mínima de venta en la imagen QR, ésta información es la que proviene del controlador del sitio (Site controller) al generar una venta. El resto de la información de la trama se completa con el Backend del POS. La siguiente tabla describe cada campo en la tabla, su descripción y su origen.
Importante: La trama debe estar en formato JSON. La imagen del código QR debe ser de tipo texto libre.
| Nombre | Tipo | Origen | Descripción |
|---|---|---|---|
|
IDDispatch |
(string) Guid |
Site controller or POS Backend |
XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |
|
PumpNumber |
string |
Site controller |
“00”-“99” |
|
TerminalIdentification |
string |
Site controller/POS IdentificationAtionet |
Debe solicitarse a ATIONet |
|
ProductCode |
string |
Site controller |
“0”-“9999” |
|
ProductUnitPrice |
double |
Site controller |
xxx.xx |
|
ProductAmount |
double |
Site controller |
xxxxxxx.xx |
|
ProductQuantity |
double |
Site controller |
xxxxxxx.xx |
|
ProductDescription |
string |
Site controller |
(OPCIONAL) La descripción del producto. |
|
ImageRequired |
bool |
Site controller or POS Backend |
Si se verdadero la respuesta devolverá el campo image con la imagen de código Qr codificada en base 64. Por defecto es falso |
En la seccion Ejemplo método Crear puede encontrar un ejemplo de como es la trama en formato Json.
Cuando se genera el código QR para una Transacción específica, el backend del POS obtiene el estado de la transacción con un proceso de sondeo mediante la Api de estado de una Transaccion. Este sondeo se realiza utilizando el IdDispatch.
Sondeo: Configure un proceso de sondeo en intervalos regulares utilizando la API de estado de transacción. Para obtener los mejores resultados de una consulta de estado, debe verificar el estado 8 veces por minuto.
Cuando se genera el código QR para una transacción específica, el cliente escanea ese código QR y paga mediante la aplicación Ationet Driver. Se notifica al cliente sobre el estado del pago en su aplicación Ationet Driver después de completar con éxito el pago. Si desea implementar una nueva aplicación de cliente, puede verificar la especificación de API Crear venta.
Nota: Los clientes no pueden cambiar el monto de la transacción en su aplicación al escanear el código QR del pedido en particular.
| Nombre | Descripción |
|---|---|
|
Post Paid Created |
Se reciben los datos de la venta y se crea la Transacción |
|
Post Paid Read |
El Cliente escanea el código QR |
|
Post Paid Confirmed |
El Cliente confirma el código QR y la transacción es aprobada |
|
Prompting Needed |
Se deben enviar reglas adicionales |
|
Prompting Sent |
Se han enviado las reglas |
|
Post Paid Cancelled |
El Cliente rechaza el pago |
|
Transaction Refused |
La Transaccion es rechazada por el Procesador de pagos |
|
Cancelled By MPPA |
La Transaccion se vence por time out |
Una vez finalizada la integración en su entorno de ensayo, es obligatorio probar la integración antes de pasar a un entorno en producción. Los siguientes puntos deben tenerse en cuenta durante el flujo integración:
- El estado de la Transacción debe verificarse a través de la API de estado de la transacción en el flujo de pago.
- El Dispacht ID enviado a to ATIONet debe ser único.
- La cantidad no debe contener más de 2 puntos decimales, comas o caracteres especiales.
- El parámetro Dispatch ID es obligatorio para crear la imagen con código QR.
URL Productiva: ationetmobilepayment-appshost.azurewebsites.net
URL QA: ationetmobilepayment-appshost-test.azurewebsites.net
Recibe la información de la venta. Devuelve en la respuesta el Id de Transaccion, el tipo de Imagen de código QR, la url para generar la venta, y una imagen del código QR codificada en base 64.
El IdDispatch enviado deberá ser único.
ADVERTENCIA: usted tiene 120 segundos desde el momento de la creacion de la transaccion para confirmar la venta. Pasado este tiempo la transacción no estara disponible para realizar el pago.
Éste método requiere autenticacion a través del encabezado. Deberá ser de tipo basica. ejemplo:
Basic usuario:clave
URL: /api/PostPaid/Create
Method: HTTPost
body {
"Sale": {
"IdDispatch":"string",
"PumpNumber": "string",
"TerminalIdentification": "string",
"ProductCode": "string",
"ProductUnitPrice": double,
"ProductAmount": double,
"ProductQuantity": double,
"ProductDescription": "string"
},
"ImageRequired": bool
}
Puede consultar la descripcion de los valores en la sección PASO 2 Crear código QR dinámico
Header:
Content-Type: application/json; charset=utf-8
content-encoding: gzip
body {
"IdTransaction":"string",
"qrData":"string",
"image":"string",
"mpqrType":int
}
Descripcion de las propiedades de respuesta
"IdTransaction": Es el Id de la Transacción.
"qrData": Contieniene la información a ser codificada en la imagen de código QR.
"image": La imagén de codigo Qr codificada en base 64 o un valor vacio.
"mpqrType": Es el tipo de Imagen de codigo QR. Por defecto es 2, indicando que se trata de una Imagen de Código QR Dinámica.
Obtiene el estado de una Transacción.
Éste método requiere autenticacion a través del encabezado. Deberá ser de tipo basica. ejemplo:
Basic usuario:clave
URL: /api/PostPaid/GetTransactionStatus
Method: HTTPost
Body { "idDispatch": "string" }
| Nombre | Descripción |
|---|---|
|
idDispatch |
Es el identificador de la transacción |
Header:
Content-Type: application/json; charset=utf-8
content-encoding: gzip
body
{
"AuthorizationCode": "string",
"ResponseCode": "string",
"ResponseMessage": "string",
"customerData": {},
"TransactionStatus":
{
"name":"string",
"id": int
}
}
Recibe el id el Id dispatch. Devuelve la informacion completa de la venta
Éste método requiere autenticacion a través del encabezado. Deberá ser de tipo basica. ejemplo:
Basic usuario:clave
URL: /api/PostPaid/SalePaymentRequest/{IdDispatch}
Method: HTTPGet
| Nombre | Descripción |
|---|---|
|
IdDispatch |
Es el Id de despacho. |
Header:
Content-Type: application/json; charset=utf-8
content-encoding: gzip
{
"idTransaction": "string",
"saleContent": {
"productCode": "string",
"productAmout": double,
"productUnitPrice": double,
"productQuantity": double,
"productDescription": "string"
},
"content": "string"
}
Crea una venta. Recibe el Id de Transacción y el primaryTrack del conductor.
Éste método requiere autenticacion a través del encabezado. Deberá ser de tipo basica. ejemplo:
Basic usuario:clave
URL: /api/PostPaid/ProcessSalePayment
Method: HTTPPost
Body { "idTransaction": "string", "primaryTrack": "string" }
| Nombre | Descripción |
|---|---|
|
idTransaction |
Es el Id de la transacción. |
|
primaryTrack |
Es el identificador del conductor. |
Header:
Content-Type: application/json; charset=utf-8
content-encoding: gzip
body
{
"AuthorizationCode": "string",
"ResponseCode": "string",
"ResponseMessage": "string",
"IdTransaction": "string",
"CustomerData": {
"PromptPrimaryPin": "string",
"PromptSecondaryTrack": "string",
"PromptOdometer": "string",
"LastOdometer": "string",
"MinOdometer": "string",
"MaxOdometer": "string"
"PromptDriverId": "string",
"PromptVehicleId": "string",
"PromptTruckUnitNumber": "string",
"PromptTrailerNumber": "string",
"PromptEngineHours": "string",
"PromptMiscellaneous": "string"
}
}
Rechaza la solicitud de Pago de una venta siempre y cuando el estado de la misma sea Post Paid Read. Recibe el Id de la Transaccion
Éste método requiere autenticacion a través del encabezado. Deberá ser de tipo basica. ejemplo:
Basic usuario:clave
URL: /api/PostPaid/RefusePaymentRequest
Method: HTTPPost
Body { "idTransaction": "string" }
| Nombre | Descripción |
|---|---|
|
idTransaction |
Es el Id de la transacción. |
Header:
Content-Type: application/json; charset=utf-8
content-encoding: gzip
Éste metodo devuelve una respuesta satisfactoria si pudo cancelar la venta (200 Ok). Devuelve Bad Request indicando en el campo message el motivo por el cual no pudo cancelar la transaccion.
Las salidas exitosas / fallidas en la API de la interfaz se manejarán a través de códigos de estado HTTP.
La solicitud exitosa obtendrá un HTTP 200 y la respuesta resultante.
Si no se procesa la solicitud, se indicará mediante un código de estado de rango HTTP 400. El cuerpo contendrá un solo elemento con formato JSON con los campos "ResponseCode", "ResponseMessage" y "ResponseError".
body:
{
"sale": {
"IdDispatch":"de1ae20c-858c-4989-a334-43992df5c45c",
"PumpNumber": "1",
"TerminalIdentification": "S2G321",
"ProductCode": "1",
"ProductUnitPrice": 1,
"ProductAmount": 10,
"ProductDescription": "SUPER",
"productQuantity": 299
},
"imageRequired": true
}
{
"idTransaction": "9e19d7a7-34c3-400e-8fb6-d7fe9ff5d55e",
"qrData": "https://ationetmobilepayment-appshost-test.azurewebsites.net/api/PostPaid/SalePaymentRequest/?IdDispatch=de1ae20c-858c-4989-a334-43992df5c45c",
"image": "iVBORw0KGgoAAAANSUhEUgAABRQAAAUUCAYAAACu5p7oAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAP+lSURBVHhe7NhRqizZtiPR1/9OV3XADvjGxA3lXC",
"mpqrType": 2
}
{
"idDispatch": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
{
"authorizationCode": "050808166",
"responseCode": "40500",
"responseMessage": "Solicitud requerida",
"customerData": {
"PromptOdometer": "true",
"ContractMode": "2"
},
"transactionStatus": {
"name": "Post Paid Prompting Needed",
"id": 26
}
}
api/PostPaid/SalePaymentRequest/?IdDispatch=a11be318-07dd-4318-bcc3-41704c54c995
{
"idTransaction": "624b8dc0-dfd5-46d3-b13a-61a4aac784af",
"saleContent": {
"productCode": "1",
"productAmout": 10.00,
"productUnitPrice": 1.00,
"productQuantity": 299.00,
"productDescription": "SUPER"
},
"content": "{\"ProcessingMode\":\"1\",\"SystemModel\":\"MOBILE\",\"SystemVersion\":\"NB\",\"TransactionCode\":\"200\",\"EntryMethod\":\"S\",\"ApplicationType\":\"FCS\",\"AccountType\":\"1\",\"MessageFormatVersion\":1.3,\"CurrencyCode\":\"ARS\",\"DeviceTypeIdentifier\":4,\"TransactionSequenceNumber\":0,\"LocalTransactionDate\":20211019,\"LocalTransactionTime\":140632,\"SiteCode\":null,\"TransactionAmount\":10,\"PrimaryTrack\":null,\"IdDispatch\":\"c421eea9-5b04-40ff-b857-67dfc71866d0\",\"PumpNumber\":\"1\",\"TerminalIdentification\":\"S2G321\",\"ProductCode\":\"1\",\"ProductUnitPrice\":1,\"ProductAmount\":10,\"ProductQuantity\":10,\"ProductDescription\":null}"
}
{ "idDispatch": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "primaryTrack": "00000001" }
{
"idTransaction": "3f34bdf9-15e2-4ef4-9134-f5a53ac360a8",
"authorizationCode": "035657109",
"responseCode": "40500",
"responseMessage": "Solicitud requerida",
"customerData": {
"PromptEngineHours": "true",
"MinEngineHours": "66",
"ContractMode": "2"
}
}
{
"idTransaction": "480ba3a1-ea50-48c8-911a-e0474af9a3da"
}
{}