IPED

In this article

Life cycle

Core functions

Progress update

Cancel

Other methods

PED stands for Payment Entry Device and is normally used when the payment device is an external device outside the hardware the POS system is using.

Life cycle

These functions are used in maintaining the life cycle of a transaction:

  • StartSession(string transactionId)
  • FinishSession()

Some PSPs use sessions to keep track of each sale, so the POS needs to be able to handle sessions for it to work for every PSP. Some transactions can be made with many requests within each session activated.

Example: A sale amounts to $100 in total, the sale is to be paid with two cards, for example a $50 on a debit card and $50 on a credit card.

Copy 
// Start a single session
StartSessionAsync(transactionId);
// Now a purchase function on card, one or many
PurchaseAsync(); // for the debit card
PurchaseAsync(); // for the credit card
// End the session
FinishSessionAsync();

The following image shows a single session with one payment. It is possible to put as many transactions as needed between StartSession and FinishSession.

Payment sequence

Note: It is not neccasary to make many transactions within each session. If tenderline management is not needed, each transaction can be wrapped with Start/Finish-Session, with a unique ID. If other functionality is needed, like line item management, that would be included within a single session.

Copy 
// Start a single session
StartSessionAsync(transactionId);
// Create line item to be displayed
AddLineItems()
AddLineItems()
// Now a purchase function on card, one or many
PurchaseAsync(); // for the debit card
PurchaseAsync(); // for the credit card
// End the session, all line item data will be removed as a part of the FinishSession function
FinishSessionAsync();

Core functions

  • Purchase
    • Purchase is a core function in LS Pay, the one most used. When calling a payment function in LS Pay, an object of the type PurchaseRequest is sent.
  • Void
    • Void is managed differently between PSPs. Some allow voiding a transaction within a day, others only for the last transaction. All allow void for a payment request and some for a refund request. When calling a void function in LS Pay, an object of the type VoidRequest is sent.
  • Refund
    • Refund is handled in the same manner as a purchase and can in most cases be voided. The refund request includes a field for the original IDs and some PSPs link former payment authorization by the number given. When calling a refund function in LS Pay, an object of the type RefundRequest is sent.
  • GetLastTransaction
    • LS Pay provides a specific function to call for the last transaction sent to the PED.

For more detailed information see the API documentation.

Example

After the connection to the terminal is made (see LS Pay - EAManagement), it is possible to send in a transaction. The following examples show the process through a few steps.

Step 1: Create an instance of IEFTManagement (eft)

Copy 
eft = eam.GetEFT();

Step 2: Start a session, the clientId is any identifier made on the client side (Unique ID):

Copy 
((IPED)eft).StartSessionAsync(clientId);

Step 3: Create the transaction (Purchase):

Copy 
private static async Task<TransactionResponse> PurchaseAsync(int clientId)
{
      // Create the request
    var paymentRequest = new PaymentRequest()
    {
      TransactionId = clientId.ToString(),
      AmountBreakdown = new AmountBreakdown()
      {
        TotalAmount = 20.00M,
        CurrencyCode = CurrencyCode.USD // or any given default currency
      }
    }

    // Make the transaction
    if(eft is IPED)
    {
        var response = await ((IPED)eft).PurchaseAsync(paymentRequest);
    }
    // In this response object you can find all the information you need.
    return response;
}

Note: Remember to try and catch, the eft.PurchaseAsync can throw various exceptions of the type EngineException or others derived of that type.

Step 4: Finally, finish the Session:

Copy 
((IPED)eft).FinishSessionAsync();

The response object TransactionResponse includes all details, as mentioned in the Response part of the Response and Request Objects article.

Progress update

The POS can subscribe to a progress update event in the IPED interface EFTProgressUpdate. Through that event, all messages from the terminal can be displayed in the UI while the progress is active.

Cancel

In the ICancel interface there is a function called CancelAsync, and when that function is called the ongoing transaction is canceled.
Note: This is not always possible, but varies between PSPs. If, for example, the terminal has sent the payment response to the host, it may not work and cannot be canceled.

The final response, however, comes back from the original sent transaction, not the Cancel request. The CancelAsync function does not guarantee that the transaction will be canceled, and it is necessary to wait for the answer from the original request and see what that one returns. Also, not all plugins allow the cancel action from the POS.

Other methods

There are more methods available in the PED interface. Take a look at the interface and the API documentation for more information.