| Document Information | |
|---|---|
| File: | ATIONet - Dynamic QR Code Payments |
| Doc Version: | 1.0 |
| Release Date: | 02, September 2021 |
| Author: | ATIONet LLC |
| Change Log | ||
|---|---|---|
| Ver. | Date | Change Summary |
| 1.0 | 02/September/2021 | Initial version. |
- Overview
- ATIONet Configuration
- Site System Implementation guide
- ATIONet PFEP Fleet Mobile Payment Api
- EXTERNAL PFEP Fleet Mobile Payment Api
This Implementation Guide is intended to guide petroleum convenience retailers and their associated vendors when implementing mobile payment solutions consistent with
ISO 12812.
Note: ISO 12812 is document that will provide requirements, guidance and use cases for all stakeholders in the mobile payments arena.
This section outlines the logical entities, including location options, for Mobile Payment and identifies possible physical architectures. The term “entity” is used in this document to differentiate logical processing functionality without regard to its physical location in an implementation.
Mobile Payment Application (MPA): This entity is a software application embedded in a Mobile Device or downloaded by a consumer onto a Mobile Device, such as a smart
phone or tablet, which enables mobile payments for in-store and forecourt transactions.
Mobile Payment Processing Application (MPPA): This entity is an application provided by the Mobile Payment Processor (MPP) not on the Mobile Device that is responsible for
interfacing between the Token Vault or Token/Trusted Service Provider, the MPA, the Site System, the Payment Front End Processor (PFEP), and the Loyalty Front End Processor (LFEP) in order to authorize transactions.
Payment Front End Processor (PFEP): This entity is a host that facilitates the authorization of payment transactions between the MPPA or the Site System and the
Issuer networks. The standard does not dictate the processing that is performed by the PFEP for each payment method. This entity is sometimes referred to as the Front End
Processor (FEP).
Site System: This entity encompasses the site equipment and components (hardware and software) and may perform the function of local card processing business rules,
such as consumer prompting, local velocity checking and receipt formatting and printing. Examples of site systems include Point of Sale (POS), Outside Sales Processor
(OSP), Electronic Payment Server (EPS) and Forecourt Device Controller (FDC).
Note: MOBILE PAYMENT API is the common interface through which the MPA sends and receives requests from the MPPA. The description, you can read about the methods and how to consume in API Section.
- Mobile Payment Application (MPA) is activated by consumer.
- MPA determines location and fueling point.
- MPA sends information to MPPA as an Authorization Request.
- MPPA optionally sends a Mobile Pump Reserve Request to the Site System to reserve the fueling point.
- Site System responds to the Mobile Pump Reserve Request.
- The MPPA sends a Mobile Auth Request to the Site System. If generated, the validation code in the payload.
- The PFEP (through the site system) sends the Mobile Auth Response to the MPPA.
- The MPPA sends a Mobile Auth Request to Site Systen.
- The Site Systen response to MPPA with a Mobile Auth Response.
- MPPA sends an Authorizacion Response to MPA
- Mobile Begin Fueling Response is sent from MPPA to Site System.
- Site System sends a Mobile Loyalty Award Request message to give the MPPA the opportunity to adjust the rewards. This message is always sent after fueling as the final amount is not determined until fueling is complete.
- The MPPA sends a response to the Site System with the additional rewards information.
- Site System sends Mobile Finalize Request to MPPA with completion information.
- MPPA sends Completion Request to PFEP.
- PFEP send Completion Response message to MPPA.
- MPPA sends Mobile Finalize Response to Site System. Note: If additional or updated receipt information is included in this response, the Site System may need to regenerate the receipt information.
- Site System sends receipt information to the MPPA.
- MPPA sends receipt information to MPA.
- Site System prints the receipt (if applicable).
- MPPA sends a receipt response back to the Site System.
In ATIONet rules refer to limits that can be configured by the company and associated to different entities. Inside this view you can consult, create or edit rules. When the entiti have a request rule, if the Customer send a Pre authorization, ATIONET will respond by requesting additional information in order to approve it. Here you can read more about Rules.
In case the PFEP requires additional information, the Transaction will be left with the status of Prompting Needed waiting for the client to send the required information, which should be sent to the PromptPreauthorizations endPoint. You can find the information requested by the PFEP using the GetTransaction endpoint, it will be found in the PaymentProcessorMessage property.
WARNING: The time to send the response is 300 seconds (5 minutes). After this time the transaction will NOT be available.
- Customer sends an Authorization Request
- Pump Reserve is sended
- Pump Reserve accepted
- Authorization Requested is send to PFEP
- PFEP response requesting Prompts
- Customer complete the Prompts
- The PFEP accept the Prompts
- Fuel point at site is Authorized
- Fueling starts
- Complete
The requested rules can be as many as the client has configured in his Network or Company. Next you have the available keys that could be requested.
"PromptPrimaryPin": "string",
"PromptSecondaryTrack": "string",
"PromptOdometer": "string",
"PromptDriverId": "string",
"PromptVehicleId": "string",
"PromptTruckUnitNumber": "string",
"PromptTrailerNumber": "string",
"PromptEngineHours": "string",
"PromptMiscellaneous": "string"
Note: The value always be "true"
In some cases, like the Odometer or EngineHours, the rule may request a minimum and / or a range of values. For example:
"PromptOdometer": "true",
"LastOdometer": "140",
"MinOdometer": "150",
"MaxOdometer": "1000",
PromptPreauthorizations endpoint should be consumed in order to response the Rule Request. The Transaction Id must be included in addition to the requested rules.
For each rule, you should respond with the name of the rule and its respective value. The Response Names are:
"PrimaryPin": "string",
"SecondaryTrack": "string",
"Odometer": "string",
"DriverId": "string",
"VehicleId": "string",
"TruckUnitNumber": "string",
"TrailerNumber": "string",
"EngineHours": "string",
"Miscellaneous": "string"
- Send a Preauthorization request using MobilePayments endPoint
- Yo will Receive the Transaction ID
- Get Transaction status using GetTransaction endPoint
- The Transaction status is Prompting Needed
- Check the paymentProcessorMessage property. It contains the Prompt Request information
- Send a PromptPreauthorizations request using PromptPreauthorizations endPoint
- Check the Transaction status again.
- Transaction status now is Authorization accepted
In the Sites menu, in the site that you want to start operating with Mobile Payments, you must update the information of the cell phone payment mode and add the FullyIntegraded type.
Once this is done you will be able to generate the QR code to paste on the pump. It should generate one per pump and each one must create introducing the Pump Code.
If you wish, you can generate the image of the QR code on your own on any QR code generation page, we recommend https://www.the-qrcode-generator.com/
To do your own QR Code Image you have to enter the site code and the pump number as shown below:
PumpCode:1 SiteCode:1524
Important: If you make you own QR Code image, you have to enter the text like a plain text.
You can read more about QR in the Static QR Image section.
In the Terminals/Cotrollers menu You have to create a new Terminal of the type AN-MobilePayment.
Static QR Image is a photo that is pasted in the Pump and contains the pump Number and the Site code, it's mandatory data to do a Transacction. Below is an image as an example
Using the ATIONet Mobile Driver App, the Customer can read the Imagen QR and do a Transaction more easier.
- The customer arrives at the service station and chooses a free pump
- Customer open the ATIONet mobile driver app and select Pay
- Choses Scan the QR code using his cell phone option
- Customer scans the QR code and get the site info
- Finally, chooses Fuel and amount and touch confirm to approve Transaction
Note: The QR code Image must be of the type free text.
Commander will provide a ConfigClient screen for configuration of Mobile Payments. These details will be provided by MPPA to commander. The screen will provide for configuration options for Site Details, and host configurations and connectivity parameters. The image below is an example. Some Mobile Payments
Processing Applications might require more information than others.
Note: The values in the image are for example. You must request the corresponding values from ATIONet.
Values to set:
Adapter: VFI_Mobile_V2
Program Name: The name of the Host configuration, we recomend use MPPA_PBL
Merchant ID: 1277
Store ID: The Site code from Ationet
Adress(IPv4 Format/Domain Name): 137.135.40.113
Port: 5560
Heartbeat Frecuency: 45
Hearbeat Time Unit: Seconds
Outdoor PreAuthorization Timeout (In Secs) 180
Site initiated Loyalty: Never Allow Site Entered Loyalty
We recommended check the conection status after complete configuration.
After completing the configuration, if all the entered values are correct, you should see the status of the site created online.
To be able to check this, go to the menu Tools -> Helpdesk Diagnostic -> Payment
| Site configuration Information | Description |
|---|---|
|
Enable Host |
Enable/Disable messaging to this particular host. If the box is not checked messages will not be sent to this particular host. |
|
Adapter |
Mobile payment APIs used by commander for communication with MPPA. |
|
Program Name |
Program name as defined by MPPA. |
|
Authentication Type |
Authentication mode supported by MPPA for that adapter. |
|
Host IP address |
IP address will be used by commander for communication with MPPA. |
|
Port |
Service Port will be used by commander for communication with MPPA. |
|
SSL Enabled |
Commander uses this Boolean for SSL communication or no-SSL communication between commander and MPPA. |
|
Site Terminal ID |
This number is supplied by MPPA as terminal identification number. |
|
Merchant ID |
Merchant Id given to the store by the MPPA. |
|
Location ID |
Location ID is given by the MPPA which identifies a site of a merchant during on boarding process. |
|
Settlement Employee Number |
Number used by commander for settlement with MPPA. |
|
Settlement Passcode |
Password used during settlement assigned by MPPA. |
| Site Initiated Loyalty | Description |
|---|---|
|
Never Allow Site Entered Loyalty |
If this option is selected, the site will be restricted to accepting loyalty only from the site or only from the MPPA. If a transaction already contains loyalty (i.e. the consumer has swiped a loyalty card prior to starting the mobile transaction) the MobileReserve / Auth will be rejected. This enforces that mobile loyalty and site entered loyalty cannot co-exist. |
|
Allow Site Entry i.e., Swiped Loyalty Card |
Both Mobile loyalty and site card swipe loyalty are allowed and Mobile payments can be tendered at DCR. |
|
Allow Site Entered Loyalty if no Mobile Loyalty |
|
The first two digits of the response code identify the message pair type. The last 3 digits is the error identifier for the status. A ‘good’ status is always represented as 00000 regardless of the message type.
| Message Type | Response Code | Message Code | Overall Result | Description |
|---|---|---|---|---|
|
All |
00000 |
Success |
Success |
Message was successfully processed. |
|
All |
00001 |
Generic Error |
Failure |
An unexpected error has occurred while processing the request message. |
|
All |
00001 |
Generic Error |
MissingMandatoryData |
Mandatory data is missing from the request header. |
|
MobileAuth |
02001 |
Generic Error |
Failure |
Unexpected error while processing the MobileAuthRequest data. |
|
MobileAuth |
02001 |
Generic Error |
MissingMandatoryData |
Mandatory data is missing from the MobileAuthRequest |
|
MobileAuth |
02002 |
Invalid info in MobileTxnInfo element |
Failure |
The header info matches an already processed transaction. |
|
MobileAuth |
02002 |
Invalid info in MobileTxnInfo element |
MissingMandatoryData |
The header is missing mandatory data to complete Auth processing. |
|
MobileAuth |
02003 |
POS or Fueling Position in use |
Failure |
The targeted fueling position is already in use. (Unused) |
|
MobileAuth |
02004 |
POS or Fueling Position in use |
Failure |
The Commander was unable to process the authorization request. Communication with the POS or fueling position has been lost. |
|
MobileAuth |
02005 |
Unknown POS or Fueling Position |
Failure |
The targeted fueling position is not configured.(Unused) |
|
MobileCancel |
04001 |
Generic Error |
Failure |
Unexpected error while trying to cancel the transaction. It is likely too late in the transaction to honor. |
|
MobileCancel |
04003 |
04003 |
Failure |
The Commander is beyond the point to honor a cancel request. |
|
MobileCancel |
04004 |
Invalid state - dispenser is fueling |
Failure |
Cancel occurred while dispensing fuel. |
|
MobileCancel |
04005 |
Invalid Dispenser number |
Failure |
The targeted fueling position does not match the original authorized fueling position. |
|
MobileCancel |
04006 |
Invalid payment/auth information |
Failure |
The payment info does not match the original payment info. |
|
MobileCancel |
04007 |
Unknown transaction or authorization |
Failure |
There is no active transaction to cancel matching the provided header. |
|
MobileCancel |
04008 |
04008 |
Failure |
Unexpectedly failed to cancel |
|
MobilePumpReserve |
06001 |
Generic Error |
Failure |
Unexpected pump reserve failure |
|
MobilePumpReserve |
06001 |
Generic Error |
MissingMandatoryData |
Data mandatory to handling the pump reserve request is not present. |
|
MobilePumpReserve |
06002 |
Invalid info in MobileTxnInfo element |
Failure |
The header information(UMTI) was present in an already processed transaction. |
|
MobilePumpReserve |
06002 |
Invalid info in MobileTxnInfo element |
MissingMandatoryData |
Data required to reserve a fueling position is missing from the request message. |
|
MobilePumpReserve |
06003 |
Fueling Position in use |
Failure |
The dispenser is not ready to reserve for a mobile transaction. It is in use or handling configuration updates. |
|
MobilePumpReserve |
06004 |
Fueling Position inaccessible/offline |
Failure |
The targeted dispenser is configured, but offline. |
|
MobilePumpReserve |
06005 |
Unknown POS or Fueling Position |
Failure |
The targeted dispenser is not configured. |
|
MobileTransactionData |
13001 |
Generic Error |
MissingMandatoryData |
The transaction data request is missing data required for processing. |
|
MobileTransactionData |
13002 |
Invalid Transaction Data Header |
Failure |
This is a duplicate transaction for an already processed transaction, or the transaction does not exist on the system. |
This specification is intended to document ATIONet’s fleet Mobile Payment API messaging format and related features required for usarage. The following sections provide descriptions of the messages themselves, the expected behaviour for each supported transaction type and a common ground for the functionality of each relevant item.
IMPORTANT:
ATIONetis the PFEP that facilitates the authorization of payment transactions between the MPPA and the Issuer networks. Fleet Mobile payment Api with External PFEP are available here.
ATIONet’s fleet Mobile Payment API It is responsible for creating pre-authorizations, obtaining information on a Transaction and Canceling a pre-authorization, as long as it meets the requirements to do so.
API URI: https://ationetmobilepayment-appshost.azurewebsites.net/
| Name | Ver. | Description | |
|---|---|---|---|
| Initial | Change | ||
|
MobilePayments |
1.0 |
Used to validate a sale request, return the Transaction ID. If the Sale already exists, returns the ID. |
|
|
PromptPreauthorizations |
1.0 |
Used to send Prompts when MobilePayments required it. |
|
|
PreAuthorizedPayments |
1.0 |
Used to do a sale request with external approval, returns Transaction ID. |
|
|
GetTransaction |
1.0 |
Returns a Sale information. |
|
|
Cancel |
1.1 |
Cancels a Sale. |
|
This section describe the message structure for each API Method available, as well as the responses messages for each one.
Create a Sale with Ationet authorization. The sale creation recibes an ID, if this ID already exists then the method returns the Sale's Id.
URL: /api/MobilePayments
Method: POST
Body: { "siteCode":"string", "pumpNumber": integer, "fuelCode": "string", "amount": double, "primaryTrack": string, "terminalCode": "string", "mobilePaymentMode": integer, "potencyKeyId": "string" , "externalReferanceID":"string" }
Header:
Content-Type: application/json; charset=utf-8
content-encoding: gzip
Body: { “TransactionId”:”StringValue” }
Receive a Transaction ID and a CustomerData that contais the Prompts required to approve a PreAuthorization.
URL: /api/MobilePayments/PromptPreauthorizations
Method: POST
Body:
{
"idTransaction": "string",
"customerData": {
"PrimaryPin": "string",
"SecondaryTrack": "string",
"Odometer": "string",
"DriverId": "string",
"VehicleId": "string",
"TruckUnitNumber": "string",
"TrailerNumber": "string",
"EngineHours": "string",
"Miscellaneous": "string"
}
}
Note: customerData only must contains Prompts Requested.
Header:
Content-Type: application/json; charset=utf-8
content-encoding: gzip
Body: { }
URL: /api/MobilePayments/GetTransaction/{id}
Method: GET
Body: { "id": "string" }
Header:
Content-Type: application/json; charset=utf-8
content-encoding: gzip
Body: {
"id":"string",
"siteCode":"string",
"primaryTrack":"string",
"odometer": double,
"terminalIdentification":"string",
"transactionSequenceNumber":integer,
"state_Name":"string",
"state_Id":integer,
"paymentProcessorReferenceId":"string",
"paymentProcessorMessage":"string",
"siteSystemMessage":"string",
"fuelPointNumber":integer,
"paymentMethod":"string",
"requestedAmount":double,
"authorizedAmount":double,
"dispatchedAmount":double,
"dispatchedQuantity":double,
"productCode":"string",
"productDescription":"string",
"productUnitPrice":double,
"unitMeasure":"string",
"createDateTime":"string",
"updateDateTime":"string"
"idDispatch":"string"
}
Cancels a Sale that is in course as long as your status is correct. In the following diagram you can check all cancellable transaction statuses - Transaction states sequence diagram on Cancelation Request.
URL: /api/MobilePayments/Cancel
Method: POST
Body:{ “TransactionId”:”StringValue” }
{
"transactionId": "StringValue",
"isSuccessCanceled": bool,
"responseCode": "StringValue",
"responseMessage": "StringValue"
}
Header:
Content-Type: application/json; charset=utf-8
content-encoding: gzip
Body:{ ”transactionId”: ”StringValue”, ”isSuccessCanceled”: ”bool”, ”responseCode"”: ”string”, ”responseMessage”: ”string” }
This section describe through a table all parameters from request.
| Method | Paramether | Type | Description |
|---|---|---|---|
|
MobilePayments |
siteCode |
string |
The site code |
|
MobilePayments |
pumpNumber |
integer |
The pump number |
|
MobilePayments |
fuelCode |
string |
The fuel code |
|
MobilePayments |
amount |
double |
Number of liters of fuel to dispatch |
|
MobilePayments |
primaryTrack |
string |
The number associated with the card |
|
MobilePayments |
terminalCode |
string |
The terminal code |
|
MobilePayments |
mobilePaymentMode |
integer |
The operation mode Code. It can be for 1 for Fullintegrated |
|
MobilePayments |
potencyKeyId |
string |
The Transaction's ID |
|
PreAuthorizedPayments |
externalReferenceID |
string |
Authorization reference ID |
|
GetTransaction | Cancel |
id |
string |
Transaction ID |
|
PromptPreauthorizations |
customerData |
Object |
Contains the Prompt Rules |
Success/failure exits on the Native Transaction Protocol 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.
This section describe through a table all states that a sale can have.
| State name | ID | Message |
|---|---|---|
|
Created |
1 |
Created |
|
PreauthorizationAccepted |
2 |
Preauthorization Accepted |
|
PreauthorizationRejected |
3 |
Preauthorization Rejected |
|
FuelPointAuthorizationRequested |
4 |
FuelPoint Authorization Requested |
|
PumpReserveAccepted |
5 |
Site System Accept Pump Reserve |
|
PumpReserveRefused |
6 |
Site System not Accept Pump Reserve |
|
FuelPointAuthorized |
7 |
Fuel Point Authorized |
|
CanceledByFuelPoint |
8 |
Canceled By Fuel Point |
|
Fueling |
9 |
Fueling |
|
Complete |
10 |
Complete |
|
CompleteFailed |
11 |
Complete Failed |
|
CancelationRequested |
12 |
Cancelation Requested |
|
CanceledByUser |
13 |
Canceled By User |
|
CanceledBySiteSystem |
14 |
Canceled By Site System |
|
FuelPointDeauthorizationRequested |
15 |
Fuel Point Deauthorization Requested |
|
SessionError |
16 |
Session not available |
|
UnknownError |
17 |
Unknown error when trying to connect with session |
|
SiteSystemError |
18 |
Site System Generic error |
|
SiteSystemError |
19 |
Cancelled By MPPA |
|
PromptingNeeded |
25 |
Prompting Needed |
|
PromptingSent |
27 |
Prompting Sent |
|
PromptingSuccess |
28 |
Prompting Success |
|
TransactionRefused |
28 |
Transaction Refused |
Both methos response the same codes.
| Code | Description |
|---|---|
|
200 |
Success |
|
400 |
Bad request |
| Code | Response | Response body Code | Response body Message |
|---|---|---|---|
|
200 |
Success |
00000 |
Successfully Canceled |
|
200 |
Success |
-10000 |
Invalid state - Transaction not updated |
|
200 |
Success |
04001 |
Invalid state - Transaction status is alredy cancel |
|
200 |
Success |
02001 |
Cancel by Generic error |
|
200 |
Success |
04003 |
Invalid state - dispenser is fueling |
|
200 |
Success |
04004 |
Invalid state - Transaction status is completed |
|
200 |
Success |
04007 |
Unknow transaction or authorization |
|
200 |
Success |
04008 |
Invalid state - Cancelation is alredy requested |
|
200 |
Success |
04009 |
Invalid state - dispenser is fueling |
|
200 |
Success |
04010 |
Transacion canceled by Session not available |
|
200 |
Success |
04011 |
Transacion canceled by unknow error |
|
400 |
Bad request |
- |
- |
Request Example
{
"siteCode": "1524",
"pumpNumber": 1,
"fuelCode": "3",
"amount": 9,
"primaryTrack": "0000000000001",
"terminalCode": "S2G321",
"mobilePaymentMode": 1,
"potencyKeyId": "5734cbb9-f78f-4ad4-aa87-79ed95181c5a"
}
Response Example
{
"transactionId": "5734cbb9-f78f-4ad4-aa87-79ed95181c5a"
}
Request Example
{
"id": 5734cbb9-f78f-4ad4-aa87-79ed95181c5a
}
Response Example
{
"id": "5734cbb9-f78f-4ad4-aa87-79ed95181c5a",
"siteCode": "1524",
"primaryTrack": "0000000000001",
"odometer": 0,
"terminalIdentification": null,
"transactionSequenceNumber": 17565,
"state_Name": "Site System not Accept Pump Reserve",
"state_Id": 6,
"paymentProcessorReferenceId": null,
"paymentProcessorMessage": null,
"siteSystemMessage": "Fueling Position inaccessible/offline",
"fuelPointNumber": 1,
"paymentMethod": "AtionetPrepaid",
"requestedAmount": 9,
"authorizedAmount": 0,
"dispatchedAmount": 0,
"dispatchedQuantity": 0,
"productCode": null,
"productDescription": null,
"productUnitPrice": 0,
"unitMeasure": null,
"createDateTime": "2021-09-03T13:43:16.6157799",
"updateDateTime": "2021-09-03T13:43:24.5466667"
}
Request Example
{
"transactionId": "5664cbb9-f78f-4ad4-aa87-79ed95181c5a"
}
Response Example
{
"transactionId": "5664cbb9-f78f-4ad4-aa87-79ed95181c5a",
"isSuccessCanceled": true,
"responseCode": "0",
"responseMessage": "Successfully Canceled"
}
Request Example
{
"idTransaction": "e0593f2d-e54a-4153-829e-ecdafb3f96055",
"customerData": {
"EngineHours": "5"
}
}
Response Example
{ }