Start Transaction
Start Transaction is used to register a transaction with axept Connect Cloud. The same operation is used irrespective of whether the intended flow is Direct to Terminal or Terminal lookup.
POST /transaction
URLs
An HTTP POST should be sent to the above URLs with the below Header:
| POST /transaction - Header Parameters | |||
|---|---|---|---|
| Field Name | State | Data Type | Description |
| Authorization | Mandatory | String | This field should be populated with the bearer token returned in the Authentication step. The format is ["Bearer "][Bearer Token] e.g. Bearer eyJhbGciOiJIUzI1NiIsIn... (truncated) Note the space between "Bearer" and the token. |
POST /transaction Parameters
The HTTP POST should contain the following fields:
| POST /transaction Body | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Field Name | State | Data Type | Description | ||||||||
| uti | Mandatory | GUID | Unique transaction Id, provided by your EPOS solution. This allows you to identify transactions uniquely in axept® Cloud Connect without receiving any response. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 128-bit Integer | ||||||||
| webHookUrl | Optional | String | The fully qualified secure URL that you wish to receive webhook notifications to. The presence of this field denotes whether or not the Webhook will be invoked. Format: Begins with https:// & Max 250 chars. | ||||||||
| tid | Conditional | String | Direct to Terminal Flow ONLY The Serial Number for the terminal you wish to send the transaction to. Omitting this field indicates you will be using the Terminal Lookup flow. | ||||||||
| expirationDate | Optional | String | UTC Date when the transaction will expire in ISO 8601-1:2019 format. Value must be in the future and no more than 365 days from the current date and time. | ||||||||
| reference | Optional | String | Reference assigned by the POS to the transaction. This field will be displayed in transaction reporting and is useful for reconciliation. It must not include any personally identifiable information e.g. vehicle registration, cardholder name etc. This field is restricted to alphanumeric characters only, max 50 chars. | ||||||||
| merchantStoreId | Conditional | Integer | Terminal Look-up Flow ONLY DNA Payments issued identifier for the merchant’s store. Setting this means that only devices licensed to that store will be able to process the transaction. | ||||||||
| clientStoreId | Conditional | Integer | Client issued identifier for the merchant’s store. Setting this means that only devices licensed to that store will be able to process the transaction. If using clientStoreId then these must have been supplied to DNA Payments in advance. | ||||||||
| Either Merchant Store ID OR Client Store ID can be used, but not both. | |||||||||||
| transType | Mandatory | String |
| ||||||||
| amountTrans | Mandatory | Integer | Amount of the transaction in minor units. Value must be greater than 0. | ||||||||
| amountGratuity | Optional | Integer | Amount of Gratuity in minor units. Used only where the POS has already determined the Gratuity amount. SALE only. | ||||||||
| amountCashback | Optional | Integer | Amount of Cashback in minor units. Used only where the POS has already determined the Cashback amount. SALE only. | ||||||||
| language | Optional | String | The IETF language to be used. Default is English. | ||||||||
| disablePrinting | Optional | Boolean | Default = false. Setting this to true will prevent the terminal from printing any receipts. | ||||||||
| posSignatureCheck | Optional | Boolean | Default = false. Setting this to true will enable the posActionStatus to update, if required, based on whether a CVM Signature Check is required. See posActionStatus entry in the GET/transaction section for more information on this. | ||||||||
| GratuityPrompt | Optional | Integer | Default = 0. If included in the transaction request body you can prompt axept® PRO on how you want it to handle gratuity for the transaction. The options are:
| ||||||||
Transaction Response
A successful response will be 200 - OK with the below body:
| POST /transaction Response | ||
|---|---|---|
| Field Name | Data Type | Description |
| uti | GUID | The Unique transaction Id, provided by your EPOS solution. |
note
No further transaction information will be returned by axept® Cloud Connect. You can discern the status of this transaction either via a GET transaction request on the next page, or via a response from the Webhook.
Best Practice
There is nothing to stop you from queueing up transactions in the order the request was sent, one after the other, due to the design of the Terminal Look-up flow. However, when dealing with the Direct to Terminal flow, this could very quickly become confusing and cause an issue. If you are using the Direct to Terminal flow then the best thing to do would be to not allow the EPOS to send any further transactions until you have a definitive outcome on the first transaction:
- If there is a delay in axept® PRO receiving a transaction, utilise the `POST`/Cancel and `DELETE`/Transaction requests to stop the initial transaction before sending another request.
- Make sure you are polling and checking both the `status` for a `"Complete"` value and/or the `transactionExpired` field for a value of `true` or `false` before making a decision about proceeding with another transaction.