Transactions
The EPAS client library offers several transaction methods.
Each transaction is synchronous, so the method will return when the transaction is complete. This can take some time, since it involves waiting for a card to be presented, waiting for PIN entry, etc.
Some of the methods in IClientApp will be called while the transaction is in progress. Similarly some of the optional handler methods will be called, if defined. All these methods will be called from a different thread to the one that is executing the transaction so there is no risk of deadlock in the callback mechanism.
Examples of transaction flows are found here: transaction flows
Transaction types
The payment application supports the following transaction types:
- Purchase
- Cash Advance
- Refund
- Reversal
Purchase transactions
For purchase transactions are a few different methods available:
Basic purchase, goods value specified only
ApiResult Purchase(decimal purchaseAmount, out TransactionResponse response)
This is the simplest way to start a purchase transaction. The purchaseAmount parameter contains the goods value in the configured currency. There is no cashback in this method.
If the method returns ApiResult.OK then the result of the transaction is given in the response parameter
Basic purchase using an alternative payment method, goods value specified only
ApiResult Purchase(decimal purchaseAmount, string paymentMethod, out TransactionResponse response)
If a specific alternative payment method is wanted for the transaction, this can be requested by submitting alternativePaymentMethodName on top of the purchaseAmount parameter, which contains the goods value in the configured currency. There is no cashback in this method.
If the requested alternative payment method is not available on the terminal, the transaction will be
aborted. Available alternative payment methods can change over time and also differ between
terminals depending on which methods are available. There is currently no function to get a list of available
alternative payment methods from the terminal. At the moment (Q1 2022) we have Swish and Klarna
in Sweden, and soon Vipps will be available in Norway and MobilePay in Denmark and Finland
See alternative payment methods for more information.
Purchase with all amounts specified, i.e. goods value and cashback value
ApiResult Purchase(PurchaseTransactionAmounts transactionAmounts, out TransactionResponse response)
The Purchase method starts a purchase transaction with all the transaction amounts specified in the transactionAmounts parameter.
Note that if the cashback amount is zero then this is functionally identical to a basic purchase.
Purchase with no amount
ApiResult PurchaseBeforeAmount(out TransactionResponse response)
This method starts a purchase transaction before the amounts are known. The cardholder will be able to present a card and enter a PIN, and the terminal will then wait for the amounts to be supplied via SendPurcaseAmounts.
The terminal will then prompt the cardholder to accept the amount.
Note: The amounts can be sent any time after the transaction is started. It does not have to be sent at a specific stage in the transaction sequence.
Cash Advance transactions
ApiResult CashAdvance(decimal cashAmount, out TransactionResponse response)
This method starts a cash advance transaction for the specified cashAmount value. If the method returns
ApiResult.OK then the result of the transaction is given in the response parameter.
Note: the terminal must be configured to allow cash advance transactions.
Note: cash advance transactions only work with card payments.
Refund transactions
Refunds of card payments
ApiResult Refund(decimal refundAmount, out TransactionResponse response)
This method starts a refund transaction of a card purchase for the specified refundAmount value.
Note: the receipt layout and contents for a refund transaction are different to those of a purchase transaction see here.
Note: if the original purchase was done using an alternative payment method, the refund has to be done with the same payment method. This is due to money laundry prevention regulations.
Refunds of alternative payment methods
ApiResult Refund(decimal refundAmount, out TransactionResponse response)
Reversals
ApiResult ReverseLastTransaction(string transactionReference, out TransactionResponse response)
A reversal is a request to cancel the most recent transaction. A transaction can only be reversed if it was approved.
If the method returns ApiResult.OK then the result of the transaction is given in the response parameter.
Transaction response
All transactions, if executed correctly, will provide a response in an instance of the TransactionResponse class.
Alternative payment methods
For purchase and refund, there is also a posibillity for the ERC to request a specific non-card payment method. For more information, see alternative payment methods.
Aborting a transaction
ApiResult RequestTransactionAbort()
All transactions methods are synchronous, i.e. the method will return when the transaction is complete. There may be situations where the transaction must be cancelled, e.g. if the customer changes their mind and walks away.
To do this, the ECR can call the RequestTransactionAbort method from a different thread (since the transaction thread is blocked at this stage until a response arrives). This method will send an abort request to the terminal.
There is no response to the abort request. Instead, the transaction will be cancelled, if possible, and the transaction response will be sent back when the terminal has processed the abort request and has completed the transaction.
Note that it is possible for the abort request to be received in the terminal at a point where it is too late to be processed. The ECR should, therefore, always correctly process the transaction result and the receipts, and should not assume that the transaction will definitely be aborted just because the request was sent.
Card handling
ApiResult EnableCardReaders(bool enable, out EnableReadersResponse response)
The EnableCardReaders requests will, if successful, enable or disable the terminal’s chip and magnetic card readers before a transaction is launched. If the enable parameter is true then the request is to enable the card readers. If false, the request is to disable the card readers.
If the method returns ApiResult.OK then the response parameter contains the terminal’s response to the enable card readers request.
When the card readers are enabled then cards will be processed in the same way as if there was a transaction in progress, i.e. the ECR will get card notifications and loyalty card processing (see loyalty card processing) will operate as normal.
The terminal will go as far as it can through the normal processes until it needs to know what transaction is involved, at which point it will wait for a transaction to be requested.
The ECR can, therefore, use the EnableCardReaders method to do loyalty card functions such as registration, checking a balance, etc. Then once the card is processed it would call EnableCardReaders with the enable parameters set to false to close the card readers again. The CardStatus events (see CardStatus) will allow the ECR to prompt for card removal if desired.