In this section, we use a typical example to help you understand how to approach integration of the Payment Device SDK into your payment solution. The majority of payments will be processed in the same way, as shown in the following Transaction Diagram.

Compliance and security policy require that live cards should only be used with devices purchased as production devices. Similarly, test cards should only be used with devices purchased as test devices.

Transaction Diagram

Figure 1 shows the flow of a typical EMV transaction from your perspective as the integrator. For simplicity, the diagram assumes that the PIN is correct and no further authentication is required.

After calling the startTransaction() method, the Client application must listen for the following events:

Mandatory

• signatureVerification – Fired during a transaction authorization when cardholder signature verification is required.
• transactionFinished – Fired when the transaction is completed on the PIN pad.
• userNotification – BBPOS Chipper 2X BT and ID TECH VP3350 only. Fired when a prompt is required to be shown to the customer.
• applicationSelection – BBPOS Chipper 2X BT and ID TECH VP3350 only. Fired when POS requires the customer to select the card application they wish to complete the transaction with.

Optional or Configuration Dependent

• transactionUpdate – Fired throughout the transaction to update the POS software on the progress of the transaction.
• signatureCapture – Mandatory when digital signature capture is supported. Fired when digital signature needs to be supplied.

To mark an authorized transaction for settlement, call confirmTransaction() at the end of the transaction authorization, after the transactionFinished event is fired.

The Payment Device SDK does not auto-confirm (capture) transactions. Approved transactions must be confirmed for settlement in order to obtain the funds. If the funds for an approved transaction are not settled for reasons such as goods issue failure then the transaction should be voided.

Transaction Result

Once a standalone transaction is complete the result is returned by the SDK. This will be one of the following:

• APPROVED
• DECLINED
• VOIDED

A typical transaction requires:

1. Online authorisation from the acquirer
2. Authorisation by the terminal (including the result of signature verification)

A transaction must be approved in both stages for the transaction result to be approved otherwise it will be declined. The acquirer might approve the transaction partially, in which case the transaction will be partially approved and the partially approved amount will be returned in the transaction result.

Transaction State

The state of the transaction will be one of the following:

• Uncommitted
• Committed
• Void
• Uncommitted void
• Delayed

If the online authorisation is declined, the transaction will always be declined and its state will be uncommitted.

However, if the online authorisation is approved or partially approved the value of the state depends on whether the transaction is approved by the terminal. If it is approved by the terminal, the result will be approved and the transaction must be committed with a call to confirmTransaction() so the funds for the transaction will be settled or voided using a call to voidTransaction().

If the transaction is approved online but declined by the terminal, the result will be declined and the transaction will be automatically voided.

A transaction state of Delayed is returned when a transaction performs delayed online processing. In this case the transaction never goes online and an encoded request will be returned in the transaction finished event which can be processed using another integration.