Card-on-File Functionality in POS

When adding a "card to file", a token is retrieved from the card provider and stored centrally in a Token vault within the EFT Extension for LS Pay. This token can only be used for the purpose that it was created for, meaning that a token created for purchases cannot be used for creating recurring payments.

Note: Before creating a token in LS Central, a member needs to have been created and selected in the POS.

Token Vault

The tokens are stored in a central Token Vault, and before you start using this functionality you must configure the Token Vault. As of LS Central version 29.0, the Token Vault is provided by the EFT Extension for LS Pay rather than by LS Central itself. So the Token Vault Setup needs to be configured again as the previous Token Storage Setup page in LS Central is discontinued.

Note: The Cards on File page described below only shows tokens when the Token Vault is configured for local storage.

When a Card-on-file token is created, information about the token is also stored. This information includes the purpose of the token, the token type, and more.

Usage in POS

Two operations are needed to use the Card-on-file functionality: Add Card to File and Card On File.

Add Card To File

This operation sends a request to the card provider through LS Pay to request a new token. When the token is created, its type and usage needs to be decided and by default the POS sends information to create a purchase token that can be used to pay for ad-hoc items.

These tokens cannot be used, for example, for recurring payments, late fees, or any other type of payments. If you need to create different types of tokens, you do that through customization using events that have already been added to the POS functionality.

Card on File

If the member has more than one token in the Token storage, the POS displays a lookup list where the cashier must select which tokens to use. One of the tokens is always the default token and is displayed as the default token in this list.

The payment will go through as a normal card payment, with the same information stored in the payment lines and the same kind of receipts created and printed as if a normal card payment had been used.

Note: Before card-on-file can be used at any store, the POS Lookups, POS buttons, and Token Vault Setup storage mode must be configured for the environment. For steps, see How to: Configure cards on file at POS.

Managing cards on file for a member

Staff in BackOffice can view and manage the cards a member has on file from the Cards on File action on the member's contact card, or on the activity contact card in Bookings. From there, you can set a card as the member's default card, or activate or deactivate a card. For steps, see How to: View and manage cards on file for a member.

Events

There are already events that the POS have implemented during the Card-on-file functionality where the information about the token itself can be changed or looked at.

When LS Central version 25.0 was released, this list of events was correct:

OnBeforeGetTokenValuesForCreateToken
OnBeforeCheckingMemberCardNoInValidateCardOnFile
OnBeforeValidateCardOnFile
OnBeforeCreatingTokenInSendPaymentTokenToStorageV2
OnBeforeSendingPaymentTokenToStorage
OnAfterSendingPaymentTokenToStorage
OnBeforeGetPaymentTokenFromStorage
OnAfterGetPaymentTokenFromStorage
OnBeforeSelectTokenToUseForPayment
OnAfterSelectTokenToUseForPayment
OnAfterAddCardToFileExecuted
OnAfterCardOnFilePressed
OnAfterCardOnFileExecuted

Note: As of LS Central version 29.0, there are two Card Payment Engines the events listed above are only applicable to a POS that is using the Legacy Card Payment Engine.

Note: As of LS Central version 29.0, the GetTokenEntry, SetMemberCardToken, GetMemberCardToken, and DeleteMemberCardToken web services are deprecated and only return an error. SetTokenEntryV2 and GetContractTokens still work but are deprecated pending removal. All six are kept temporarily so that older POS versions keep working against a 29.x head office, but they are planned for removal in a future version.

Note: In any and all customizations any communications with the Token Vault should be done through the EFT Extension for LS Pay API which uses the Token Vault Setup to decide if it should store the Tokens locally or remotely.