Change Logs
| General Document Information | |
|---|---|
| Version: | 2.2 |
| Version Status: | Definitive Edition |
| Date Version: | 29/02/2024 |
| Log | |||
|---|---|---|---|
| Version | Date | Description | Autor |
| 1.0 | 23/02/2024 | Initial version | Cabral, Matías |
| 2.0 | 29/02/2024 | Update document format, diagrams integrations, add diagrams sequence, add descriptions process | Yañez, Alexis |
| 2.1 | 07/03/2024 | Messaging was completed. Host validation diagram added. | Yañez, Alexis |
| 2.2 | 08/03/2024 | Updated diagrams to Lucidchart format | Yañez, Alexis |
| Distribution / ATIONET Approval | |||
|---|---|---|---|
| Version | Date | Approver / Role | Signature |
| 1.0 | dd/mmm/yyyy | Pending | |
| 2.0 | dd/mmm/yyyy | Pending | |
| 2.1 | dd/mmm/yyyy | Pending | |
| 2.2 | dd/mmm/yyyy | Pending |
Content
The purpose of this document is to specify in detail the integration with ATIONET Native protocol.
Is a technology platform for cloud services for service stations or fuel dispatch centers.
Ationet oversees verifying the possibility of fuel dispatch.
For this purpose, it applies different validations to determine whether the dispatch request received can be carried out.
We can separate the validations as follows:
- Validation of the request structure.
- Ensuring the integrity of the data received, validating that the information submitted by the consumer is valid for our subscription.
- Rules validation: this point is closely related to the configuration in the Ationet portal, where the user can determine whether a client must meet certain requirements to perform a dispatch. At the same time, he has the possibility to apply restrictions that allow / prevent fuel dispatching.
- Validates the user's current account is validated to determine if he/she has a balance to operate.
Once the structure and integrity of the information is assured, the combination of the rules applied, and the balance will result in the client's availability to operate.
Allows the creation and management of fleet programs, loyalty programs, gift cards, and other commercial platform products. The software authorizes transactions received from any third-party POS terminal or platform.
Third-party systems integrate with ATIONET via a set of APIs (Application Programming Interfaces). Each ATIONET’s API is described on a separate Protocol Specification. The complete documentation of ATIONET API’s is comprised of:
Covers financial transactions for transaction capture systems (payment terminals, site controllers and point of sale systems), including sales and refunds.
Describes a set of functions complementing the transaction-capture business, for example Batch or Shift Close. These functions enhance the capabilities of the integration, but their implementation is not mandatory.
Ationet has multiple environments to ensure to be able to perform the relevant tests at the time of integration. For this reason, Ationet has:
This environment is used for development, allowing to test the advances that are generated.
URL Environment: https://native-test.ationet.com/v1/auth
It is a more stable environment, which already contains a finalized version. It is used to test the developments in search of errors, prior to their passage to production.
URL Environment: https://native-beta.ationet.com/v1/auth
The productive version of Ationet.
URL Environment: https://native.ationet.com/v1/auth
All Transaction API messages share the same base structure with slight modifications depending on which TransactionCode you use. All requests must be made with a POST method and the body uses a JSON format, as well as their responses.
{
"FieldName":"StringValue",
"FieldName":"StringValue",
"FieldName": Value
}
Only one request is accepted on each message.
For detailed information about the request structure provided by Ationet, please visit our technical documentation.
You can also obtain a detailed description about the fields that compose the requests / responses, in this section of our technical documentation.
Likewise, if you wish to obtain details of each field and description of the response message provided by Ationet, please visit our technical documentation.
On the other hand, if you wish to obtain details on the obligatory nature of each field in the request/response messages, you can visit our technical documentation, which details this information in each type of message.
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.
Transactions intended to post a command, for example Authorizations and Pre-Authorizations will return a single JSON-formatted item with the Response Code and Response Text. The body of these responses will never be empty.
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.
Refer to Response Codes annex for a complete list of supported codes.
This section will detail the sequence of messages that must be followed to integrate with Ationet.
This diagram shows the complete flow, without alternative paths, to perform a successful transaction against Ationet in a pre-authorization operation.
In this case:
- The terminal / controller sends a pre-authorization to the Ationet host.
- Ationet accepts the pre-authorization either in whole or in part.
- The terminal / controller sends a completion to Ationet.
- Ationet accepts the completion.
- End of flow.
Send a request to the Host containing the TransactionCode with the value 100 indicating that it is a Pre-Authorization.
Other important fields to consider would be:
- TerminalIdentification
- TransactionSecuenceNumber
- PrimaryTrack
- TransactionAmount, ProductCode, ProductUnitPrice, ProductAmount, ProductQuantity
- LocalTransactionDate: local transaction date in yyyymmdd format
- LocalTransactionTime: local transaction time in hhmmss format
Corresponds to the case where a pre-authorization is requested and when a response is obtained, the pre-authorization flow ends.
Corresponds to the case where a pre-authorization is requested and Ationet requires additional information to authorize or reject it.
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 entity has a request rule, if the client sends a Pre-authorization and it does not contain the additional information configured to be requested, ATIONET will respond requesting such additional information to approve it.
The transaction will remain in Request Required status waiting for the customer to send the required information.
The following codes represents the ATIONet promptings needed as well:
| Name | Code |
|---|---|
| GeneralPromptingNeeded | 40500 |
| PrimaryTrackPinPromptingNeeded | 40501 |
| SecondaryTrackPinPromptingNeeded | 40502 |
| PrimaryTrackPinPromptingInvalid | 40503 |
| SecondaryTrackPinPromptingInvalid | 40504 |
| OdometerPromptingInvalid | 40506 |
| EngineHoursPromptingInvalid | 40507 |
Additionally, there are response codes that represent that the transaction has been rejected and that it is no longer possible to send more additional information (prompting) to complete the remaining information of the transaction.
| Name | Code |
|---|---|
| PromptingRetriesExceeded | 20500 |
| PrimaryTrackOutOfPinTries | 40508 |
| SecondaryTrackOutOfPinTries | 40509 |
| BlockedPrimaryTrackOutOfPinTries | 40510 |
| BlockedSecondaryTrackOutOfPinTries | 40511 |
To answer a request, it will be necessary to resend the original request (same TSN, date and time) including the requested fields in CustomerData.
At the protocol level, the information of the requests and their values are managed inside the CustomerData object. The required values will be requested with the following key: Prompt[Field], where [Field] can take any value needed (and there can be more than 1 in the same message).
In this appendix, you can obtain information on CustomerData to evaluate the response obtained.
This scenario contemplates communication problems in the pre-authorization request. It contemplates the case in which the request has not reached the Ationet Host, and in which the response provided by Ationet has not reached its destination.
In both cases it is necessary to proceed with a cancellation message, as detailed in the document.
If there is no response to the cancellation, a maximum of 3 consecutive cancellation retries must be made.
If there is still no response to the cancellation from the host, it is recommended to store the cancellation, so that it can be reattempted later.
In case Ationet responds to the cancellation, the flow MUST TERMINATE, regardless of whether the cancellation was authorized or not**. And it must be removed from the store and forward so that it is not sent again.**
On the other hand, when initiating a new pre-authorization, it is important that a new transaction sequence number is generated, to restart a new pre-authorization flow.
If you need to cancel a pre-authorization on demand (not due to technical problems), please review the Zero Completion implementation.
Please validate the cancellation message in this section of the document.
For information on the request, please visit the following link to the technical documentation.
For information on the response, please visit the following link to the technical documentation.
Once sent the Host will return a response, several of the data returned are the same structure as the request.
The fields we are most interested in are the AuthorizationCode to identify the transaction and the ResponseCode that indicates the result of the request.
The ResponseCode we expect is 00000 which indicates that the transaction was authorized.
If not authorized, the ResponseCode will be different and the ResponseText and LongResponseText fields will give us more information about the result obtained, as shown in the following extract from response.
We should also note that we may get response codes that indicate that Ationet is requesting additional data. This can be seen in the Sequence Diagram - Re Prompt.
Once we have an authorized Pre-Authorization, we can finalize the sale with a Completion.
The fields to highlight in this request are the TransactionCode in 120 that indicates that it is a Completion, and the fields that come directly from the response of the Pre-Authorization, mainly the AuthorizationCode that identifies the transaction.
For the rest of the fields, the terminal / controller should fill in as appropriate, such as amount dispatched, quantity dispatched, etc.
Upon receiving a response from Ationet for completion, the flow should be terminated, regardless of whether the response code is authorized or not.
This scenario contemplates communication problems in the request for completion. It contemplates the case where the request did not reach the Ationet Host, and where the response provided by Ationet did not reach its destination.
In both cases it is necessary to proceed with a cancellation message, as detailed in the document.
If there is no response to the cancellation, a maximum of 3 consecutive retries must be made.
If there is still no response from the host, it is recommended to store the cancellation, so that it can be reattempted later.
In case of a response from Ationet**, the flow MUST END**, regardless of whether the cancellation was authorized or not. And the cancellation must be removed from the store and forward so that it is not sent again.
Please validate the cancellation message in this section of the document.
This scenario describes the case where Ationet returns a conflict message when processing a completion.
This case occurs when Ationet received the completion message, did not receive a cancellation, and the completion is reported again.
In this case, Ationet will respond with HTTP Code 409 indicating that there is a conflict.
What to do, when receiving an HTTP Code 409 when sending a completion, is:
- Send a cancellation for that sale completion.
- Ensure that the cancellation was processed correctly (Receiving a 410 frame with Response Code 00000 (Authorized)).
- Resend the sale completion.
Please validate the cancellation message in this section of the document.
For information on the request, please visit the following link to the technical documentation.
For information on the response, please visit the following link to the technical documentation.
The host will return a response, again we need to check the ResponseCode
In the case that when sending a completion, the response is that it was not authorized, the transaction flow is terminated.
In case you wish to cancel a pre-authorization that has been authorized, it is necessary to send a completion with amounts/quantities dispatched in zero. This will allow Ationet to revert the balance reserved in the pre-authorization.
Ationet allows you to obtain the customer's available funds through the Balance Inquiry message.
The message has the same structure as a pre-authorization, except that the Transaction Code is 102.
This message behaves similarly to a pre-authorization, except that it does not perform the balance reservation.
On the other hand, it is important to remember that Ationet will return the AVAILABLE according to the conjunction of the rules that apply at the time of the query plus the balance availability in the current account.
The response will be a frame with Transaction Code 112.
The reasons for rejection in this message, obtained in the Response Code, may be caused by the following:
- Validation of the request structure
- Integrity of the data received.
In case the client does not have available, the transaction will exit with zero authorized amount.
In the case of a communication error, where you do not get a response from the Host, in this case you can retry the message.
For information on the request, please visit the following link to the technical documentation.
For information on the response, please visit the following link to the technical documentation.
Ationet allows to report a fuel dispatch without going through the pre-authorization flow. For this purpose, the sales message is available.
The terminal will send a sale message, and Ationet will run the rules engine, since the sale does not have an associated pre-authorization, so it is necessary to validate the rules.
The sale can be approved or rejected.
This scenario contemplates communication problems in the request for sale. It contemplates the case where the request did not reach the Ationet Host, and where the response provided by Ationet did not reach its destination.
In both cases it is necessary to proceed with a cancellation message, as detailed in the document.
If there is no response to the cancellation, a maximum of 3 consecutive retries must be made.
If there is still no response from the host, it is recommended to store the cancellation, so that it can be reattempted later.
In case of a response from Ationet**, the flow MUST END**, regardless of whether the cancellation was authorized or not. And the cancellation must be removed from the store and forward so that it is not sent again.
Please validate the cancellation message in this section of the document.
For information on the request, please visit the following link to the technical documentation.
For information on the response, please visit the following link to the technical documentation.
This message corresponds to a technical cancellation. It is used when there is a communication problem between the terminal / controller and the Ationet Host, to reverse the movements and be able to perform the flow again.
In the reauthorization and Completion messages, the flow for the use of this message was specified.
The basic flow is shown here, without considering the particularities detailed above.
For information on the request, please visit the following link to the technical documentation.
For information on the response, please visit the following link to the technical documentation.
This message allows you to reverse a Completion or Sale, returning the consumption, if the transaction has not been billed.
In case Ationet rejects the message because the transaction has already been billed, the transaction dispute flow should be followed to reverse the consumption from the Ationet portal.
In any other case, the flow should be given as terminated.
Ationet will provide the following response code if the transaction is billed, allowing to identify that a dispute is required to be made in the portal.
| Name | Code |
|---|---|
| TransactionAlreadyBilled | 13048 |
For information on the request, please visit the following link to the technical documentation.
For information on the response, please visit the following link to the technical documentation.
The terminal must implement a KeepAlive message to inform Ationet that it is operational, the structure of which is attached to this document.
This message should be sent every 1 to 3 hours. This time span must be configurable from the terminal.
Ationet will respond with an HTTP Status Code 200 to indicate that it is active.
Important: in this case, the controller to be used is the maintenance controller, so the URL should be formed as follows:
{URLEnvironment}/v1/maintenance
For information on the request, please visit the following link to the technical documentation.
For information on the response, please visit the following link to the technical documentation.