Card-Present

​The Create POS Charge endpoint allows the clients to submit card-present charges completed with a physical payment terminal with a single API call. These types of charges require additional fields specific to card-present transactions, which are retrieved from the card-terminal interaction, such as the Track2 data, the EMV data, and optionally an encrypted PIN block. In order to properly format the messages submitted to the card networks, additional information about the terminal and its capabilities also needs to be submitted.

The additional fields needed in the Create POS Charge endpoint will be highlighted below including some additional explanation to better map the fields received from the payment terminal to the correct fields in the API request.

An example POS charge type can be seen below:

Other than the card some additional information is required from the card-terminal interaction for card-present transactions:

In certain scenarios the terminal requests a PIN. While in some cases this PIN request is handled offline between the card and the terminal there are also cases where the PIN request needs to go online for PIN validation by the issuer. One such example is for contactless transactions for high amounts.

In these cases the pinBlock should be submitted in the request:

The terminal object contains information about the capabilities and type of terminal being used. It is important to accurately set these fields in each request for the correct processing of card-present requests.

​In card-present transactions, not every transaction is concluded with a single request, in which case more than a single request-response cycle is needed. Therefore, the client should be aware of the following fields in the POS charge response:

When creating a POS charge, one of the terminal.capabilities is oneTap, which indicates the support of single tap functionality on the contactless interface of the terminal for Mastercard and Visa. In case that PIN is required in the subsequent transaction, this will be indicated by the terminalAction as described above.

It is important to set the optional property type.sequence to subsequent in the next transaction containing the PIN block. This will indicate to the issuer that this is the subsequent transaction and a follow-up from the initially declined transaction.

For EMV chip cards, script processing provides an option to the issuer for updating the data in the chip card, as part of transaction processing.

newEmvData can be present in chip transactions and contains the updated EMV data returned from the issuer. It is important to propagate the contents of this field back to the terminal.

Partial approval functionality allows businesses to handle transactions where the total amount exceeds the available balance on the cardholder's payment card. This is common for example with prepaid cards where the total balance left on the card is used, and the remainder of the amount due is paid through an alternative payment method. To properly communicate to the issuer that this functionality is supported on the terminal the allowPartialApproval boolean should be set to true on the POS charge request.

​​Gratuity allows businesses to seamlessly incorporate tipping options into their point of sale system, providing a convenient and flexible experience for their customers. When creating a charge, it is important to accurately calculate the amount, including both the cost of goods/services and any applicable gratuity, providing the total amount in amount.value. Supporting gratuity after authorization is allowed in certain regions for select MCCs. This can be achieved by:

Most commonly, a refund is initiated from a reference to the original transaction details. This is referred to as a referenced refund and is initiated by refunding on the original chargeKey by calling Refund endpoint.

When the original transaction identifier is not available, an unreferenced refund can be initiated by providing the details of the payment instrument by calling Create POS Charge endpoint and indicating type.intent is refund.

In the case card declines an issuer approved transaction, technical reversal will be triggered.

Merchant can choose to reverse a previously approved transaction if clearing has not happened.

Both type of reversals can be achieved by calling the Cancel Charge endpoint (if clearingMode is set to auto) or Reverse Charge endpoint (if clearingMode is set to manual) with the chargeKey as a path parameter. This will always revert the charge if the clearing file has not yet been constructed, and an authorization reversal will be performed. If the clearing file has already been submitted, our platform can no longer cancel the record and will not perform a refund, the refund endpoint will need to be called at this point in time.

Our platform makes use of a cloud HSM service, which is a scalable solution for the encryption of PIN blocks in card-present payment transactions. It utilizes HSMs that are certified to meet the Federal Information Processing Standards (FIPS) 140-2 level 3 security requirements. This ensures that the encryption and decryption of sensitive data, such as PIN blocks, is performed in a secure and tamper-proof manner and environment.

The cloud HSM generates and manages the encryption keys used to secure the data, adding an additional layer of security.

The cloud-based nature of this service allows for easy scalability, as additional HSMs can be added to the network as needed to support an increasing number of clients. This eliminates the need for our clients to invest in and maintain their own HSMs, making the service more cost-effective and efficient.