Transactions initiated from POS device
Primary transactions
Request types
For primary transactions initiated from a physical device (terminal) the following request types need to be used:
- PaymentTerminalSaleTransaction
- PaymentTerminalCreditTransaction,
- PaymentTerminalPreAuthTransaction
For secondary transactions such as linked refunds and reversals the standard secondary request types have to be used. Alternatively, you can use the order ID to perform a secondary transaction.
Important note
Sensitive data such as card number and PIN must be sent encrypted to our gateway. For more information about encryption as well as MAC'ing please refer to: link
Relevant elements
Transactions initiated from a physical device must contain additional data elements:
terminalRequestData
| Element | Description | Presence |
|---|---|---|
posEntryMode | Actual method used to enter the cardholder account number and card expiration date. | Mandatory |
offlineVerificationMethod | The Offline verification Method indicates what method was successfully performed on the terminal to assess the authenticity of the cardholder at POS device. | Mandatory |
cardholderPresentIndicator | Indicates whether the cardholder is physically present or not present during the transaction. Default value: true | Optional |
cardPresentIndicator | Specifies if the actual payment card is present at the time of the transaction. This is typically used to differentiate between card-present and card-not-present transactions. Default value: true | Optional |
singleTapPinPerformed | Indicates if single Tap Pin was performed after scheme response. Default value false | Optional |
offlineIndicator | Specifies if the transaction was processed offline. Useful for situations where network connectivity is intermittent or unavailable. Default value | Optional |
onlineReason | The 'onlineReason' field within the 'terminalRequestData' object specifies the reason why a card-present transaction is being processed online. The values of this field assist the processing system in understanding why the transaction is not occurring offline (i.e., directly at the terminal), enabling more accurate transaction processing and risk assessment. | Optional |
attendanceContext | Specifies the attendance condition during the transaction - ATTENDED if the transaction was supervised by a staff member, Default value: ATTENDED | Optional |
emvData | Electronic Verification Method data. This field is mandatory if 'posEntryMode' is either 'contactless' or 'contact'. Required EMV tags can vary per scheme. Format: Base64 encode string. | Conditional |
approvalCode | If terminal has approved the transaction in offline mode, then 6-digit approval code (also known as authorization code) must be sent by the request. | Conditional |
pointOfSaleDevice
| Element | Description | Presence |
|---|---|---|
terminalProvider | The vendor that provided the terminal to merchant. | Mandatory |
serialNumber | The unique identifier assigned by the manufacturer to the POS device or terminal. | Mandatory |
softwareProvider | The entity that provides the software running on the POS device or terminal. | Optional |
softwareVersion | The version number of the software installed on the POS device or terminal. | Optional |
capabilities | see capabilities | - |
model | The specific model or version of the POS device or terminal. | Mandatory |
capabilities
| Element | Description | Presence |
|---|---|---|
cardholderVerificationCapabilities | Specifies the different capabilities the point-of-sale (POS) device or terminal has for verifying a cardholder's authenticity. | Mandatory |
cardReadingCapabilities | Indicates the various methods by which the device can read card information | Mandatory |
terminalType | Indicates the type of the terminal based on its functionalities and usage | Optional |
pinCapability | Describes the capability of the device to accept PIN entry for transactions | Mandatory |
features | Additional features that are available on the used POS Device. More values to be added in the future. | Optional |
paymentCard (ref as PaymentCardWithTrackData)
This object encapsulates PaymentCard data and contanis track1, track2 and track3 data.
| Eelement | Description | Presence |
|---|---|---|
number | Payment card number. Can also be an IBAN for Sepa Direct Debit transactions. | Mandatory |
expiryDate | Expiry date of the used card printed on the card. | Optional |
securityCode | Card verification value/number. | Optional |
brand | Brand of the useed card. Can be sent in case of dual branded card to determine the chosen brand | Optional |
bic | Bank identifier code (BIC) for Sepa Direct Debit. | Optional |
bankCode | Bank code for Sepa Direct Debit. | Optional |
cardFunction | Used to send the type of card such as CREDIT, DEBIT or PREPAID | Optional |
cardholderName | Name of the cardholder. Note - Only supported with request payload. | Optional |
bin | 6 or 8 digit Bank Identification Number of the used card (depending of the length of the card) | Optional |
last4 | The last 4 numbers of a payment card. | Optional |
One of:track1track2track3 | Contains the track of data encoded on the magnetic strip of the card. | Optional |
Response handling
For transactions initiated from a terminal the gateway sends the standardized responses.
See: link
In case of successful transaction (HTTP code 200) the response may include EMV data that was included by the issuer in the response.
| Element | Description | Presence |
|---|---|---|
emvData | It includes the EMV data from the issuer response and it is Base64 encoded. Tags that will be mapped to the response (if present): 8A, issuerAuthorizationResponseCode8A 91, issuerAuthenticationData91 71, issuerScriptTemplate171 72, issuerScriptTemplate272 | Conditional |
Besides, you would need to analyze processor.requiredActionOnTerminal in order to decide whether the customer will need to enter the PIN without new card read or enter the PIN with new card read.
More details: link
Secondary transactions
If you want to start a secondary transaction such as void (reversal), preauthorization completion (postauthorization) or return (linked refund) you can use the same endpoints as for ECOM transactions.
For secondary transactions initiated from a physical device (terminal) the following request types need to be used:
The following values can be applied be applied for secondary transactions using IPG Order ID (see: submitsecondarytransactionfromorder) or IPG Transaction ID (see: submitsecondarytransaction)
- PostAuthTransaction
- VoidTransaction
- VoidPreauthTransactions
- ReturnTransaction
- PreAuthSecondaryTransaction
These are the minimum objects that need to be included:
transactionAmount.totaltransactionAmount.currencyterminalRequestData- In case of reversal:
reversalReason
ReversalReason
In case of a technical reversal (or auto void) terminal needs to include the reason for the reversal.
This reason can be sent in secondary transactions with request type 'VoidTransaction' and will get forwarded to the authorization system.
| Element | Description | Presence |
|---|---|---|
reversalReason | Reason set by the terminal to cancel the referenced transaction. | Conditional |
Other useful information
Deferred Authorisation
In order to flag a transaction as a deferred authorisation you will need to include the object order.additionalDetails.ipgDeferredAuth into the request.
Updated about 1 month ago
