Solution Overview
axept® Connect is a hosted web application which provides a RESTful API for integration. It acts as an intermediary between your Electronic Point of Sale system and the axept® PRO application running on your terminal estate.
Requirements
You will need several pieces of information to be able to connect to axept® Connect.
In all cases below, the values will be different between the TEST and LIVE environments.
| Detail | Usage | Description |
|---|---|---|
| Merchant ID | Mandatory | This is the unique identifier representing the merchant within the environment. It is provided to you through the order / on boarding process. |
| Key ID | Mandatory | This is the ID allocated to the merchant using the authentication key generation process. To generate / obtain this, use the functionality available in the OCC portal. More detail can be found in the Key Management section. |
| Key | Mandatory | This is the key / password generated using the authentication key generation process and associated with the Key ID. To generate this, use the functionality available in the OCC portal. DNA Payments do not store the generated value and cannot recover it, so it is your responsibility to record the generated value. This is sensitive data. You are advised to store this securely within your infrastructure. |
| Merchant Store ID(s) | Conditional | This is the unique identifier representing a given merchant store or location within the environment. It is provided to you through the order / on boarding process. |
| Client Store ID(s) | Conditional | This is a merchant specific ID that is associated with the Merchant Store ID, which can be used instead of the Merchant Store ID to identify the merchant store / location. This information must be recorded within the system, normally through the order / on-boarding process. |
| Either Merchant Store ID OR Client Store ID must be used | ||
| Device Serial Number(s) | Optional | This is the serial number of the physical device. It is normally on a label on the back of the device. This information must be recorded within our system, normally through the order / on-boarding process. |
| Webhook URL | Optional | This is your merchant defined URL we will use to inform you of the result of the processed transaction. This must be a HTTPS address. |
| Webhook Public RSA Signature Key | Optional | This is the public RSA key that corresponds to the private key that DNA Payments will use to digitally sign messages. You need to use this to authenticate and parse any Webhook responses you are sent. |
| Merchant ID | Conditional | This is the unique identifier representing the merchant within the system. It is provided to the merchant through the order / on boarding process. Required if using webhooks. |
Transaction Flows
There are two main flows when using the service to perform transactions: Direct to Terminal or Terminal Lookup. Both flows have the option to use the webhook mechanism or to periodically request for the transaction result to obtain the result of the transaction.
Using Direct to Terminal, your solution PUSHes the transaction to the specified terminal. The transaction is started automatically on the designated terminal.
Using Terminal Lookup, your solution PUSHes the transaction to our server, and any of the terminals at the store then PULLs the transaction down from the server to start it.
Direct to Terminal Flow
This flow allows you to specify the terminal that is intended to process the transaction. To utilise this flow, the device serial number must be known and provided. Whether the webhook approach is being utilised or not, the main transaction flow remains the same. The primary difference between the two flows is focused on the result retrieval approach:
Figure 1 - Direct to Terminal using Webhook Flow
Figure 2 - Direct to Terminal without using Webhook Flow
| Stage | Details | ||||
|---|---|---|---|---|---|
| 1. | Your POS system initiates a transaction by sending the transaction details to axept® Connect Cloud. | ||||
| 2. | axept® Connect receives and validates the request. Providing the request is valid, the system determines whether the device is a known device. If this is the case, the system sends the details of the transaction to the device. If the device is offline, the details will be queued for delivery as soon as the device returns to being back online. | ||||
| 3. | If the webhook is not being used, your POS system should periodically request the result of the transaction. The result status will transition from open, when the transaction is first initiated, to in progress, when the terminal locks the transaction, and finally to complete, when the terminal finishes processing the transaction. | ||||
| 4. | axept® Pro receives the transaction details, validates them, and then requests that axept® Connect locks the transaction. | ||||
| 5. | axept® Pro receives the locked transaction details, validates them, and then starts the transaction. | ||||
| 6. | The transaction is processed to completion as normal in axept® Pro. The terminal informs axept® Connect of the result. | ||||
| 7. | axept® Connect receives the result of the transaction, validates, and then processes the details. What it does next depends on whether or not the webhook is being used:
| ||||
| 8. | You POS system receives the result and completes the transaction in accordance with the received details. |
Terminal Lookup Flow
This flow allows any of your terminals to look up and retrieve the transaction details of the transaction to process. To utilise this flow, the device serial number must not be provided. Whether the webhook approach is being utilised or not, the main transaction flow remains the same. The primary difference between the two flows is focused on the result retrieval approach:
Figure 1 - Terminal Lookup using Webhook Flow
Figure 2 - Terminal Lookup without using Webhook Flow
| Stage | Details | ||||
|---|---|---|---|---|---|
| 1. | The merchant’s POS system initiates a transaction by sending the transaction details to axept Connect Cloud. | ||||
| 2. | axept® Connect receives and validates the request. Providing the request is valid, the system determines whether the device is a known device. If this is the case, the system sends the details of the transaction to the device. If the device is offline, the details will be queued for delivery as soon as the device returns to being back online. | ||||
| 3. | If the webhook is not being used, your POS system should periodically request the result of the transaction. The result status will transition from open, when the transaction is first initiated, to in progress, when the terminal locks the transaction, and finally to complete, when the terminal finishes processing the transaction. | ||||
| 4. | Using the axept® PRO terminal at the specified store, the operator uses the menu system to view all open transactions. | ||||
| 5. | The terminal retrieves the list of all open transactions for the merchant store and for the merchant where no store has been associated with the transaction. It will also retrieve any transactions deemed to be in progress and locked against the current device. | ||||
| 6. | The operator views the available information and selects the required transaction. The terminal requests that axept® Connect Cloud locks the transaction, associating the transaction with the device and merchant store. | ||||
| 7. | axept® PRO receives the transaction details, validates them, and then starts the transaction. | ||||
| 8. | The transaction is processed to completion as normal in axept® PRO. The terminal informs axept® Connect Cloud of the result. | ||||
| 9. | axept® Connect receives the result of the transaction, validates, and then processes the details. What it does next depends on whether or not the webhook is being used:
| ||||
| 10. | Your POS system receives the result and completes the transaction in accordance with the received details. |
Transaction Retention
axept® Connect stores transaction information independently of any other DNA Payments systems. This data is only used for transaction processing through axept® Connect Cloud, as as such we will automatically tidy this data.
Any transactions which are marked as expired will be removed periodically. You can set the expiration date for a transaction in your request, otherwise a default value is used.