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 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 an encrypted PIN block optionally. Additional information about the terminal and capabilities must also be submitted to properly format the messages submitted to the card networks.

The additional fields needed in the Create POS Charge endpoint will be highlighted below, along with a further 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 specific 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 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 terminal type being used. Accurately setting these fields in each request is essential 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 essential 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 following transaction and a follow-up from the initially declined transaction.

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

newEmvData can be present in chip transactions and contains the updated EMV data from the issuer. It is essential 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 customers with a convenient and flexible experience. When creating a charge, it is essential 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:

Usually, a refund is initiated using a reference to the original transaction details. This is referred to as a referenced refund and is initiated by refunding the original chargeKey by calling the Refund endpoint.

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

A technical reversal should be triggered if the card declines an issuer-approved transaction.

Merchants can reverse a previously approved transaction if clearing has not happened.

Both reversals can be achieved by calling the Cancel Charge endpoint (if clearingMode is set to auto) or the 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.

Our platform uses a cloud HSM service, which is a scalable solution for encrypting 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 HSMs, making the service more cost-effective and efficient.