INTEGRATION
CHARGES
DISPUTES & FRAUD
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.
Card-Present Fields
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.
Charge Type
An example POS charge type can be seen below:
intent
within thetype
object indicates what type of transaction is being performed. This is typically purchase for regular brick-and-mortar sales and reservation for Travel & Entertainment transaction types where the final amount is likely to change.cardEntry
andorder
are always terminal and counter respectively, for card-present transaction types.terminalEntryMode
indicates how the card was read by the terminal, such as chip or contactless.
Card Data
Other than the card
some additional information is required from the card-terminal interaction for card-present transactions:
track2Data
: the Track2 data from the card's magnetic stripe should be submitted if available.emvData
: the EMV data from the card should be submitted unaltered when received from the terminal.cardSequenceNumber
: the card sequence number, if personalized on the card, should also be included in the request.
Online PIN
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:
block
should contain the encrypted PIN block as received and encrypted from the terminal.format
indicates the encryption format (almost alwaysISO-0
).zoneId
is an additional tool to split the security zones between multiple (regional) instances of the connection between the Silverflow and client's platform, assigned by Silverflow.keyId
is the identifier of the PIN encryption key as loaded in the Cloud HSM, assigned by Silverlow.
Terminal
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.
type
indicates what kind of terminal is being used in the transaction, which could be a regular POS device (POS), a Mobile POS device (mPOS), which is typically a smaller external PIN-pad or dongle connecting to a mobile device, or a software-only terminal (SoftPOS) installed on a mobile device.id
is the terminal identifier, which is submitted in the message to the card network and needs to be unique within the domain of the acquirer.attended
indicates whether this is an attended or an unattended terminal.capabilities
is an array that should contain all the entry modes the terminal supports including additional features such asoneTap
.
Terminal Actions
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:
terminalAction
could also be returned in the response:requestPin
in combination withauthorizationIsoFields.responseCode
65 (for Mastercard single tap transaction) or 1A (for Visa SCA transaction) and when issuer indicates that the transaction should be retried with online PIN (pinBlock
).switchInterface
could be triggered during a contactless transaction withauthorizationIsoFields.responseCode
65 (for Mastercard) or 70 (for Visa) and when issuer indicates that the transaction should be retried with contact interface. Terminal should display similar message to cardholder.
Single Tap
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.
Issuer scripts
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
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
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:
Creating a charge with the
clearingMode
set to manual and theamount.value
should contain the amount of the goods/services. Providing the amount including gratuity asamount.value
in the request to the Manually Clear Charge endpoint.Creating a charge providing the amount including gratuity as
amount.value
in the request when calling Create POS Charge endpoint.
Merchandise Return
Referenced Refund
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.
Unreferenced Refund
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.
Reversals
Technical Reversal
In the case card declines an issuer approved transaction, technical reversal will be triggered.
Merchant Reversal
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.
Hardware Security Module (HSM)
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.