| Document Information | |
|---|---|
| File: | ATIONet - Dynamic QR Code Payments |
| 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. |
- Overview
- QR code Payments squence
- Dynamic QR Code Payments Implementation
- API Documentation
- Error handling
- Messages samples
Ationet fleet Mobile payments - Dynamic QR allows to generate the dynamic QR code from their Billing POS/System for a specific order/bill and must pass the order-specific information such as Dispatch ID, Order Amount, etc. while generating the code. The customer can scan this QR to make a payment and the POS's Backend can check the transaction status using the Dispatch ID.
Note: A customer-facing screen is required, which will show the dynamically generated QR to him in order to be able to
scan it and generate the sale.
- Customer chooses the goods/service in a store and shows the intent to the cashier for Ationet Driver App payment.
- Cashier creates an order with the bill amount and a unique Dispatch ID in the POS system.
- POS’s backend server Create QR Code and displays it to the Customer on the consumer-facing screen.
- Customer scans QR code via Ationet Driver App.
- POS’s backend server automatically starts polling the Transaction status every 8 times/minute using Dispatch ID.
The section describes the integration steps required to integrate ATIONet's Dynamic QR Code Payments with billing POS to accept contactless payment from your customer using the Ationet Driver App payment.
You must required your keys from ATIONET
- POS's Backend Key: A unique secret key used to secure encryption of every request. This needs to be kept on server-side and should not be shared with anyone.
Note: Never share your secret POS's Backend Key with anyone.
POS's Backend only encodes the minimum sale information in QR, it is the one that comes from site controller when generating a sale. The rest of the plot information is completed by the POS's Backend. The following table describes each field in the table, its description and its origin.
Important: the request body have to be in JSON format. QR image must be free text type.
| Name | Type | Origin | Description |
|---|---|---|---|
|
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 |
It must be requested from 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) Is the product description |
|
ImageRequired |
bool |
Site controller or POS Backend |
If you send it true, the response will return the property `image` with the QR Image enconde in base 64. By default is false. |
In Create method section you can find a request body sample in Json format.
When the QR code is generated for an specific transaction, the POS's Backend Get The Transaction status with a polling process using the Transaction status API. You have to do the polling ussing IdDispatch.
Polling : Setup a polling process after regular intervals using the Transaction Status API.
To get the best results out of a status query, you should check the status 8 times/minute.
When the QR code is generated for an specific transaction, the customer scans that QR code and pays using Ationet Driver App. The customer is notified about the payment status on their Ationet Driver App after the successful completion of payment. If you want to implement a new client app you can check the specification of the create sale api.
Note: Customers cannot change the Transaction amount in their app on scanning the particular order QR code.
| Name | Description |
|---|---|
|
Post Paid Created |
The sale data is received and the Transaction is created |
|
Post Paid Read |
The Customer scan the QR Code image |
|
Post Paid Confirmed |
The Customer confirm the QR Payment and the Transaction is approved |
|
Prompting Needed |
Validation rules are required |
|
Prompting Sent |
Rules are sent |
|
Post Paid Cancelled |
The Customer refuse the QR Payments |
|
Transaction Refused |
The Transaction is refuse by Payment processor |
|
Cancelled By MPPA |
The Transaction es cancelled by time out |
Post completion of integration in your staging environment, it is mandatory to test the integration before moving into the live environment with production. Below points should be taken care of during the integration of the flow:
- The Transaction status should be verified through the Transaction Status API in the payment flow.
- The Dispacht ID passed to Ationet should be unique.
- The amount must not contain more than 2 decimal points, comma, or any special characters.
- Dispatch ID parameter is mandatory for creating QR.
Production URL: ationetmobilepayment-appshost.azurewebsites.net
QA URL: ationetmobilepayment-appshost-test.azurewebsites.net
Receive the sale's information. Returns the Transaction's Id, the QR Type, the URL to do the Sale and the QR Code Image encode in base 64 format.
The IdDispatch sent should be unique.
WARNING: You have 120 secs to confirm the payment. After that the Transaction won't available.
This method require basic auth through header. Example
Basic user:pass.
URL: /api/PostPaid/Create
Method: HttpPost
body {
"Sale": {
"IdDispatch":"string",
"PumpNumber": "string",
"TerminalIdentification": "string",
"ProductCode": "string",
"ProductUnitPrice": double,
"ProductAmount": double,
"ProductQuantity": double,
"ProductDescription": "string"
},
"ImageRequired": bool
}
You can check the description values in STEP 2 Create Dynamic QR Code section.
Header:
Content-Type: application/json; charset=utf-8
content-encoding: gzip
body {
"transactionId":"string",
"qrData":"string",
"image":"string",
"mpqrType":int
}
Response properties description
"IdTransaction": The transaction Id.
"qrData": Contains the data to be enconde in a QR Image.
"image": The Qr Image enconde in base 64 or a empty value.
"mpqrType": Is the QR Image type. By default the number 2 indicates that image is for Dynamic QR.
Return a Transaction information.
This method require basic auth through header. Example
Basic user:pass.
URL: /api/PostPaid/GetTransactionStatus
Method: HttpPost
Body { "idDispatch": "string" }
| Name | Description |
|---|---|
|
idDispatch |
Is the Transaccion Id |
Header:
Content-Type: application/json; charset=utf-8
content-encoding: gzip
body
{
"AuthorizationCode": "string",
"ResponseCode": "string",
"ResponseMessage": "string",
"customerData": {},
"TransactionStatus":
{
"name":"string",
"id": int
}
}
Receive the idDispatch. Returns the Sale information.
This method require basic auth through header. Example
Basic user:pass.
URL: /api/PostPaid/SalePaymentRequest/{IdDispatch}
Method: HttpGet
| Name | Description |
|---|---|
|
IdDispatch |
Is the Dispatch Id |
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"
}
Create a Sale. Receive the transaction id and the primaryTrack from driver.
This method require basic auth through header. Example
Basic user:pass.
URL: /api/PostPaid/ProcessSalePayment
Method: HTTPPost
Body { "idTransaction": "string", "primaryTrack": "string" }
| Name | Description |
|---|---|
|
id |
The transacction Id. |
|
primaryTrack |
The driver identifier |
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"
}
}
Refuse the payment request for a sale as long as its status is Post Paid Read. Receive the Transaction ID
This method require basic auth through header. Example
Basic user:pass.
URL: /api/PostPaid/RefusePaymentRequest
Method: HTTPPost
Body { "idTransaction": "string" }
| Name | Description |
|---|---|
|
idTransaction |
The transacction Id. |
Header:
Content-Type: application/json; charset=utf-8
content-encoding: gzip
body { "AuthorizationCode": "string", "ResponseCode": "string", "ResponseMessage": "string", "TransactionId": "string" }
Success/failure exits on the Interface API will be handled via HTTP status codes.
Successful request will get a HTTP 200 and the resulting response.
Failure to process the request will be indicated by an HTTP 400’s range status code. The body will contain a single JSON-formatted item with the “ResponseCode”, “ResponseMessage” and “ResponseError” fields.
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": {
"PromptEngineHours": "true",
"MinEngineHours": "66",
"ContractMode": "2"
},
"transactionStatus": {
"name": "Post Paid Prompting Needed",
"id": 26
}
}
api/PostPaid/ProccessSale/?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"
}
{}