LS Pay For Business Central EFT Extension
In this article
LS Pay For Business Central EFT Extension
Intergration
Prerequisites
- LS Pay Service installed and running.
- At least one EFT device set up in the LS Pay Service.
Note: There is a Mock device available for testing purposes which returns pre-programmed responses without connecting to a payment terminal. For most transaction amounts it returns an approved response, however it also has a list of trigger amounts to trigger specific types of responses:
| Amount | Response |
|---|---|
| 103.01 | Authorization Status Declined |
| 103.02 | Authorization Status Cancelled |
| 93.01 | Amount verification |
| 93.02 | Signature verification |
| 101.01-101.10 | Transaction Status Error |
- Business Central version 23 or higher.
- EFT Extension installed on the Business Central instance.
- At least one EFT device set up in the EFT Device List in Business Central.
EFT Extension
The purpose of this extension is to create a connection to the LS Pay Service in AL Code. The main entry point to payments in the EFT Extension is the LSCEFT Payment Entry Point codeunit.
Getting Started
Device handling
A page to create and manage EFT Devices called EFT Device List is included in the EFT Extension.
However, integrators need to design and implement their own method for selecting on which EFT Device a transaction should be performed.
- This is typically be the first step in the integration process. There are various to implement this, here are some examples:
- Create a settings page to select a device from the EFT Device table and saving it to a user, instance or POS profile.
- Create a dialog to select the device from the EFT Device table when initiating a transaction.
Transaction requests
The next step is to write methods for generating the transaction requests. Below is a short example with the minimum data required to perform a payment with most payment providers.
Transaction responses
The final step in the process is to write a method to handle the transaction response.
This includes first checking the Transaction Status to determine whether the transaction successfully completed without errors.
Note: Even if the Transaction Status is Success, the transaction itself still may have been declined. Therefore the next step is checking the authorization status of the transaction to determine whether it was approved or declined, then handling registering the payment based on the authorization status.
Error handling and recovery
If an error occurs during a transaction and no response is received, most payment providers offer the ability to recover the result of the transaction. To recover, call StartOperation with Transaction Type = Get Last Transaction. The recovery state of a Card Entry is tracked in its Recovery Status field (None, Recovery needed, Recovered, Failed). When recovery succeeds, Recovered Card Entry ID points to the recovered entry.
Note: StartRecovery in the LSCEFT Payment Entry Point codeunit is obsolete since version 1.1.2.0. Use StartOperation with Get Last Transaction instead.
Terminal offline handling
If a Purchase returns Authorization Status TerminalOffline, the EFT Extension can automatically retry it as an offline-authorized transaction (Transaction Type Offline, linked to the original entry through Original Card Entry ID). The behavior is set per device with the Terminal Offline Handling field on the EFT Device Card:
| Value | Behavior |
|---|---|
| No Handling | Return the TerminalOffline result to the caller. |
| Try Offline | Retry as an offline transaction automatically. |
| Ask User | Ask the user whether to try an offline authorization first. |
This only applies to Purchase. The Card Entry returned to the caller is the latest one (the offline attempt, if one was made).
Token Vault
The EFT Extension includes a Token Vault that securely stores payment tokens and links each token to an owning record (a table number plus the record's SystemId). Use the public codeunit LSCEFT Token Vault, which is the only supported entry point. Every procedure returns a Boolean and sets a ResponseCode and ErrorText.
| Procedure | Description |
|---|---|
| SetToken | Store a token. If DefaultToken is true, it becomes the record's only default token. |
| GetToken | Get a record's default token (optional PSP filter). Falls back to any active token. |
| GetTokens | List a record's active tokens (optional PSP filter). An empty result is success. |
| GetTokenByEntryNo | Get one token by its Entry No. (ignores Active). |
| UpdateToken | Replace the mutable fields of a token, by Entry No. |
Response codes: 0000 success, 0050 token already exists for the same linked record (SetToken only), 0098 communication or other error. The same token value may be stored against different records.
Storage is configured on the Token Vault Setup page. In Local mode the tokens are stored in the same Business Central database. In Remote mode the calls are forwarded to a central Business Central server running Local mode, through the Token Vault web service (SOAP or OData V4, Basic or OAuth authentication). Use Test Connection on the setup page to verify a Remote setup. Setup must be valid before any token can be written.
Using a vault token in a payment
Set Token Entry No. on the request to the vault token's Entry No. The EFT Extension then fills any blank token fields on the request from the token, and fills blank card fields (Card Number, Card Issuer, Card Issuer ID, PAR) on the resulting Card Entry when the payment provider did not return them. Values you set yourself always win. A vault lookup that fails (token not found, setup invalid, remote error) is ignored and never affects the payment.
Transaction popup dialog
A Javascript popup dialog is automatically shown during an transaction. For many payment providers it shows update messages about the status of a transaction (Examples:
- Processing Request,
- Insert Card
- Enter PIN
- Processing Response
- Transaction Approved
After a transaction is finished, it shows the result (Examples: Approved, Declined, Cancelled, Error).
It will also handle any type of verification that may be required such as signature verification.
Setting the EFT dialog language
The EFT dialog localizes the error popup based on the user's Business Central session language. No EFT-specific configuration is required – the extension forwards the session language to the dialog automatically on every request.
How to change it
Each user controls their own language:
- In Business Central, click the settings (gear) icon in the top-right.
- Open My Settings.
- Change the Language field to the desired language (e.g. Swedish (Sweden)).
- Click OK and reload the page when prompted.
The new language takes effect on the next EFT transaction.
Supported languages
| Language | Behavior |
|---|---|
| English | Default. Always available. |
| Swedish | Fully translated. |
| Other | Falls back to English automatically. No error, no missing text. |
Additional languages can be added on the JS dialog side without any change to the AL extension – once a translation file ships, AL is already sending the correct code.
What gets translated
Only the user-facing error message shown in the error popup is localized. The technical [ErrorCode] shown in the expandable detailed-error section is intentionally left untranslated – it is the stable identifier support uses when reading screenshots and logs.
For administrators
The language is read from the current session via GlobalLanguage() and sent as Settings.LanguageCode (BCP-47 format, e.g. "sv-SE") on every EFT request. There is no device-level or company-level override; changing the language requires changing the BC user's session language in My Settings.
Syncing EFT Devices
Instead of creating each EFT Device by hand, use the Sync EFT Devices action on the EFT Device List page. It queries the payment engine for the terminals it exposes (using the Get All Payment Plugins operation) and creates an EFT Device card for each one.
- Open the EFT Device List and choose Sync EFT Devices.
- Select the Payment engine (LS Pay Service, Hardware Station or LS Appshell), the Currency Code to assign to the new devices, and the host and HTTPS setting for the selected engine. LS Appshell needs no host.
- A list of the discovered terminals is shown, marking the ones that already exist as EFT Devices. Choose OK to create all the new ones, or Cancel to abort.
Notes:
- Existing EFT Devices are never modified. A terminal is matched to an existing device by its ID.
- For Hardware Station only terminals of type EFT are listed. Other Hardware Station device types are ignored.
- Each new device gets the engine, host and HTTPS settings and currency code entered in step 2, and its description is set to the terminal name. Review the other settings on each new EFT Device card afterwards.
Receipts
Some payment providers return receipts (card slips) with a transaction response, and the X and Z report operations return report receipts. The EFT Extension stores these and formats them for printing, but it does not print them. The integrator sends the formatted lines to a printer.
How receipts are stored
Each receipt is stored as a record in LSCEFT Receipt Header with its text in LSCEFT Receipt Lines, both linked to the transaction through Card Entry ID.
| LSCEFT Receipt Header field | Description |
|---|---|
| ID | Unique ID (GUID) of the receipt. |
| Card Entry ID | The Card Entry the receipt belongs to. |
| Receipt Type | Enum LSCEFT Receipt Type. Possible values: None, Merchant, Customer, X Report, Z Report. The enum is extensible. |
| Print output type | Enum LSCEFT Receipt Print Type. Possible values: Separate receipt, Embedded. |
| Mandatory To Print | Whether the receipt has to be printed. |
| Discard after printing | Copied from Discard Print Slips on the EFT Device. |
| Printed, Print Date Time | Whether and when the receipt was printed. |
| LSCEFT Receipt Lines field | Description |
|---|---|
| Receipt Header ID | The receipt the line belongs to. |
| Print Order | Order of the line on the receipt. |
| Receipt Line | The line text (Text[2048]). |
| Font Size | Enum LSCEFT Receipt Font Size. Possible values: SMALL, MEDIUM, LARGE, BIG. |
| Font Weight | Enum LSCEFT Receipt Font Weight. Possible values: NORMAL, BOLD. |
Preparing receipts for printing
Call PrepareReceiptsForPrinting in the LSCEFT Payment Entry Point codeunit after a transaction. It returns false if the Card Entry has no receipts or formatting fails.
The formatting adds an empty line before and two after the receipt text, and a cut command at the end. Which formatting is used depends on the Receipt Type:
| Receipt Type | Formatter |
|---|---|
| Merchant, Customer | LSCEFT Format Receipt CardSlip |
| X Report, Z Report | LSCEFT Format Receipt Report |
| None | LSCEFT Format Receipt None (does nothing) |
To use your own formatting, implement the LSCEFT IFormat Receipt interface (PrepareReceiptLines and FormatReceipt) and use the overload of PrepareReceiptsForPrinting that takes an IFormatReceipt parameter.
Related device settings
| EFT Device field | Description |
|---|---|
| Print Slips Using | Enum LSCEFT Print Slips Using. Possible values: Hardware Station, Card Terminal. |
| Discard Print Slips | Sets Discard after printing on the stored receipts. |
| Print Device ID | ID of the print device to use. |
Tables
The two most important tables of the EFT Extension is LSCEFT Request Entity (request) and LSCEFT Card Entry (response).
LSCEFT Request Entity
A temporary table containing all the request data needed to initiate a transaction.
Notes:
- The label Conditionally Mandatory refers to that some fields are required for certain payment providers (see LS Pay's payment provider documentation for details), otherwise optional.
- The label Check Feature Flag refers to that some optional fields are not always supported, it is indicated by the feature flag of the plugin whether or not the field is supported.
| Parameter name | Type | Description | Mandatory | Feature Flag |
| ID (Primary Key) | Integer | Auto-increment Id field, no need to set a value. | No, auto-created | |
| Client Transaction ID | Text[256] | A unique ID to identify the transaction. Format requirements differ slightly between payment providers. Interface LSCEFT IClient Transaction ID Handling is used to generate the ID. LSCEFT Trans ID GUID is the default implementation which generates a GUID with special characters removed. To generate other formats of IDs, create a class inheriting the LSCEFT IClient Transaction ID Handling interface and make sure it's selected on the EFT Device profile. | No, auto-created | |
| Device ID | Code[20] | The ID of the EFT Device that should receive the request. Use RequestTemp.SetDevice(DeviceRec.ID) to set the Device ID | Mandatory | |
| Merchant Order ID | Text[128] | ID to link multiple transactions within the same order. | Mandatory | |
| POS ID | Text[128] | ID of the POS initiating the transaction. | Mandatory | |
| Store ID | Text[100] |
A unique identifier for a store. For stores that are part of a chain and share the same name, includes additional information such as the location to ensure uniqueness. Example: Store named Fresh Mart located in Reykjavik, Store ID Fresh Mart Reykjavik. |
Mandatory | |
| Transaction Type | Enum LSCEFT Transaction Type |
Specifies the type of the transaction. Possible values are: None, Purchase, Void, Refund, Offline, PreAuth, Cancel-PreAuth, Update-PreAuth, Finalize-PreAuth, Add Card To File, X-Report, Z-Report, Activate Gift Card, Initialize Gift Card, Add Value Gift Card, Balance Inquiry Gift Card, Close Gift Card, Deactivate Gift Card, Start Session, Finish Session, Get Last Transaction, Reprint Last, Get Token, Create Token, Create Payment Link, Disable Payment Link, Finalize Payment Link, Print Receipt, Get Plugin Features, Get All Payment Plugins, Get Card Details, Get Card Data. Which types are available depends on the payment provider and payment engine (LS Pay Service or Hardware Station); see the payment provider documentation. |
Mandatory | |
| Currency Code | Code[10] |
The currency used in the transaction. Follows the ISO 4217 standard (example: USD, EUR, ISK). The EFT Extension automatically adds the currency code set in the EFT Device profile by default if this is not set in the request. |
Mandatory | |
| Amount To Be Paid | Decimal | The transaction's total amount (incl. VAT, Cashback, Surcharge and Tip) | Mandatory | |
| VAT Amount | Decimal | The transaction's tax amount. | Check Feature Flag | IsTaxFromPOS |
| Cashback Amount | Decimal | The transaction's cashback amount. | Check Feature Flag | IsCashbackFromPOS |
| Surcharge Amount | Decimal | The transaction's surcharge amount. | Check Feature Flag | IsSurchargeFromPOS |
| Tip Amount | Decimal | The transaction's tip amount. | Check Feature Flag | IsTipFromPOS |
| Point Amount | Decimal | Specifies the amount of points used in transaction. | Conditionally Mandatory | |
| Tender Type | Enum LSCEFT Tender Type |
Specifies the tender to be used by the customer. Possible values are:
|
Conditionally Mandatory | |
| Original Card Entry ID | Integer | References the original card entry in cases when the current transaction needs a reference. For example when refunding or voiding transactions or finalizing pre-authorizations. | Mandatory for void, referenced refund and finalize/ update/ cancel pre-auth | |
| Additional ID | Text[2048] | Additional transaction ID provided by some payment providers for finalizing or reverting transactions. | No, auto-added by setting the "Original Card Entry ID" field | |
| Staff ID | Text[128] | ID of the staff member initiating the transaction. | Conditionally Mandatory | |
| Alternative Payment Type | Enum LSCEFT Alt Payment Type |
Specifies that an alternative payment type is requested. Possible values are:
|
Check Feature Flag | IsQR |
| Payment Schedule Type | Enum LSCEFT Payment Schedule Type |
Specifies whether the payment is completed instantly, in installments or deferred. Possible values are:
|
Conditionally Mandatory | |
| Payment Authorization Type | Enum LSCEFT Payment Auth Type |
Specifies the payment authorization method requested. Possible values are:
|
Check Feature Flag | IsManualEntryFromPOS, IsMOTOFromPOS, IsOfflinePossible |
| Ask Gratuity | Boolean | Specifies whether the payment terminal should ask for gratuity. | Check Feature Flag | IsTipOnTerminal |
| Enable PLB | Boolean | Specifies whether product level blocking should be enabled. | Check Feature Flag | IsProductLevelBlocking |
| Force Flag | Boolean | Specifies that a transaction should be forced through when a dual payment has been rejected. | Check Feature Flag | IsForceFlagPossible |
| QR Code | Text[2048] | QR code scanned by an external device that will be used to complete the transaction. | Check Feature Flag | IsQR |
| Card Verification Number | Text[256] | Card verification number, consisting of a three or four digit number to verify the cardholder. Only used for gift cards. | Conditionally Mandatory | |
| Token ID | Text[128] | Token/cardholder identifier, this is not the payment token. | Mandatory for token creation requests. Check Feature Flag. | IsTokenEFT |
| Token Value | Text[512] | Token used to complete transaction. | Mandatory for token transactions. Check Feature Flag. | IsTokenEFT |
| Token Initiator | Enum LSCEFT Token Initiator | Specifies who is initiating using or creating a token. Possible values are: Unknown, Cardholder, Merchant. | Mandatory for token creation requests. Check Feature Flag. | IsTokenEFT |
| Token Initiator Reason | Enum LSCEFT Token Initiator Reason | Specifies the reason for creating a token. Possible values are: Unknown, Unscheduled, Recurring, Installments, IndustryPractice. | Mandatory for token creation requests. Check Feature Flag. | IsTokenEFT |
| Token Type | Enum LSCEFT Token Type |
Specifies what a token will be used for (in cases of creating tokens) or what it is being used for (in cases of token transactions). Possible values are:
|
Mandatory for token creation requests. Check Feature Flag. | IsTokenEFT |
| Number Of Installments | Integer | Number of payments in the installment plan. | Mandatory for installment payments. Check Feature Flag. | IsInstallmentFromPOS |
| Current Installment Index | Integer | Index of the current installment being paid. | Mandatory for installment payments. Check Feature Flag. | IsInstallmentFromPOS |
| First Amount | Decimal | Payment amount of the first payment in the installment plan. | Mandatory for installment payments. Check Feature Flag. | IsInstallmentFromPOS |
| Other Amount | Decimal | Payment amount of payments after the first payment in an installment plan. | Mandatory for installment payments. Check Feature Flag. | IsInstallmentFromPOS |
| PaymentLinkExpirationDate | DateTime | The time that the payment link expires. | If not sent in, payment provider will set the default value | |
| PaymentLinkId | Text[2048] | Represents the ID of the payment link. | Mandatory for all Payment Link Transactions except Create Payment Link | |
| CardNumber | Text[256] | Card number, used by operations that take card data as input. | No | |
| Card Expiry Date | Text[128] | Card expiry date. | No | |
| Card Issuer | Text[128] | Name of the card issuer or application. | No | |
| Card Issuer ID | Text[128] | ID of the card issuer or application. | No | |
| Token Entry No. | Integer | Entry No. of a token in the Token Vault (see Token Vault). When set, blank token fields (Token ID, Token Value, Token Initiator, Token Initiator Reason, Token Type) are filled from the vault token. Values set by the caller are never overwritten. | No | IsTokenEFT |
| Token PSP Reference | Text[128] | Token identifier supplied by the payment provider. | No | IsTokenEFT |
| Token Caller Reference | Text[128] | Reference owned by the POS (for example a shopper reference). | No | IsTokenEFT |
| Notification Display Text, Notification Display Text 1, Notification Display Text 2, AdditionalDisplayText | Text[250] | Text shown on the terminal or in the dialog for operations that display a notification. | No | |
| Notification Entry Method | Enum LSCEFT Entry Method | Entry method used for notification operations. Possible values: Any, None, Unknown, Swipe, Tap, Insert. | No | |
| PrinterConfig | Text[2048] | Printer configuration for operations that print. | No | |
| Receipt Header ID | Guid | Receipt header used by print operations. | No | |
| Card Entry Handling | Enum LSCEFT Card Entry Handling | Implementation of LSCEFT ICard Entry Handling. The default implementation is LSCEFT Card Entry Default. It handles initializing a Card Entry using fields from the Request Entity table and inserting a time stamp after a transaction is finalized. The enum can optionally be extended if additional fields are required. Possible values: Default Handling. | No, auto-added | |
| Https | Boolean | Specifies whether or not https communication is enabled. Configured in EFT Device Card. | No, auto-added by setting the "Original Card Entry ID" field | |
| Host | Text[100] | Specifies the host address of the LS Pay Service. Example: localhost:5050 (no https:// or http:// included). Configured in EFT Device Card. | No, auto-added by setting the "Original Card Entry ID" field | |
| Request Log ID | Integer | Foreign key to "LSCEFT Request Log" | No, auto-added | |
| Sender | Enum LSCEFT Request Sender | Extensible enum to identify the source of the SenderID described below. | No | |
| SenderID | RecordId |
Sender ID can be used to connect a card entry request to a primary key of the order/transaction that is being paid for or to the entity that is sending the payment f.ex:
This value can be connected to the Sender field or be a standalone value. The EFT functionality does not use this value, it is purely informational for the user of the EFT Extension. |
LSCEFT Card Entry
Contains the current status and/or the result of the requested transaction. A Card Entry record is created immediately upon sending a request to the EFT Extension.
| Parameter name | Type | Description | Feature Flag |
| ID (Primary Key) | Integer | Auto-increment ID field, no need to set a value. | |
| POS ID | Text[128] | Unique ID of the instance of the POS. | |
| Device ID | Code[20] | ID of the EFT Device that performed the transaction. | |
| Transaction Type | Enum LSCEFT Transaction Type | Specifies the type of the transaction (Purchase, Refund, Void). | |
| Transaction Status | Enum LSCEFT Transaction Status |
Specifies the current status of the transaction (None, Success or Error).
Whether recovery is needed is tracked separately in the Recovery Status field. |
|
| EFT Message | Text[256] | A message from the payment provider. Can be used to display a message to the user. Localization depends on the payment provider. | |
| Error Code | Enum LSCEFT Error Code |
Error code. Set to None when no error occurred. Possible values:
|
|
| Error Message | Text[256] | Short error message that can be displayed to user. This message will be shown in the popup dialog that appears during a transaction if an error occurs. | |
| Detailed Error Message | Text[1024] | Detailed error message for debugging purposes. | |
| Total Amount | Decimal | Specifies the transaction's total amount (incl. VAT, Cashback, Surcharge and Tip) | |
| Tax Amount | Decimal | Specifies the transaction's tax amount. | IsTaxFromPOS |
| Cashback Amount | Decimal | Specifies the transaction's cashback amount. | IsCashbackFromPOS, IsCashbackOnTerminal |
| Surcharge Amount | Decimal | Specifies the transaction's surcharge amount. | IsSurchargeFromPOS |
| Tip Amount | Decimal | Specifies the transaction's tip amount. | IsTipFromPOS, IsTipOnTerminal |
| Currency Code | Code[10] | Specifies the currency used in the transaction. Follows the ISO 4217 standard. | |
| Tender Type | Text[128] | Specifies the tender used by the customer. Possible values: Unknown, Credit, Debit, GiftCard, Cash, Voucher, EBT, EBTCash, CMR, FSA, Cheque, Deferred | |
| Verification Method | Enum LSCEFT Verification Method | Specifies the verification method used Possible values are: None, Signature, Online PIN, Offline PIN, Online PIN and signature, Offline PIN and signature, Unknown. | |
| Authorization Status | Enum LSCEFT Authorization Status |
Specifies the authorization result of the transaction Possible values:
|
|
| Alternative Payment Type | Enum LSCEFT Alt Payment Type |
Payment types other than card or mobile. Possible values:
|
|
| Payment Schedule Type | Enum LSCEFT Payment Schedule Type |
Indicates when payment/s should be captured. Possible values:
|
|
| Payment Authorization Type | Enum LSCEFT Payment Auth Type | Payment authorizations that need to be indicated by the POS before a transaction starts. Possible values: Normal, ManualEntry, MOTO, MailOrder, PhoneOrder, Offline, PaymentLink. | |
| Recovery Status | Enum LSCEFT Recovery Status | Recovery state of the entry. Possible values: None, Recovery needed, Recovered, Failed. | |
| Recovered Card Entry ID | Integer | ID of the Card Entry created by recovering this entry. | |
| Voided | Boolean | Set on the original entry when it has been voided. | |
| Recovery Attempt | DateTime | Date and time when a recovery of a failed request was attempted. | |
| Recovered Entry No. | Integer | Entry No. of the Card Entry that this Entry is trying to recover. | |
| Auth Code | Text[128] | Authorization code of the transaction. | |
| Additional ID | Text[2048] | Additional transaction ID provided by some payment providers for finalizing or reverting transactions. | |
| EFT Transaction ID | Text[128] | Transaction ID provided by some payment providers for finalizing or reverting transactions. | |
| Batch No. | Text[128] | Specifies the batch number of the transaction. | |
| EFT Transaction Date Time | Text[128] | Timestamp provided by the payment provider. Format depends on the payment provider. | |
| POS Transaction Date Time | DateTime | Timestamp generated by the EFT Extension at the end of all transactions. Is always the current date and time set in the operating system. Is called in LSCEFT ICard Entry Handling. FinalizeCardEntry. | |
| Merchant Order ID | Text[128] | An ID provided by the merchant (POS) to link multiple payment transactions within the same order. | |
| Card Number | Text[128] | Specifies the masked card number of the card used by the customer. | |
| Card Expiry Date | Text[128] | Specifies the expiry date of the card used by the customer. | |
| Card Issuer | Text[128] | Specifies the name of the card issuer or application used by the customer. | |
| Card Issuer ID | Text[128] | Specifies the ID of the card issuer or application of the card used by the customer. | |
| Cardholder | Text[256] | Name of the cardholder, when provided by the payment provider. | |
| PAR | Text[128] | Payment Account Reference. | |
| Entry Method | Enum LSCEFT Entry Method | How the card was read. Possible values: Any, None, Unknown, Swipe, Tap, Insert. | |
| Card Read Result, Card Read Data, Card Data | Enum LSCEFT Card Read Result / Text[2048] | Result and data returned by the Get Card Details / Get Card Data operations. Card Read Result possible values: Success, Error, FurtherInformationNeeded, SignatureVerificationNeeded, VoiceAuthenticationNeeded, CashBackConfirmationNeeded, VerifyCardData, CardDataNeeded. | |
| GiftCard Verification Method | Enum LSCEFT GCVerification Method | Verification method used for a gift card transaction. Possible values: Keyed, Swiped, Unknown. | |
| Gift Card Available Amount | Decimal | Remaining balance of a gift card. | |
| Session Response | Enum LSCEFT Session Response | Result of Start Session / Finish Session operations. Possible values: Success, StartingSessionUnsuccessful, FinishSessionUnsuccessful, SessionAlreadyStarted, NoSessionStarted, NotSupported. | |
| Discovered Plugins | Blob | Payment plugins returned by Get All Payment Plugins. | |
| Client Transaction ID | Text[256] | Transaction ID provided by the merchant (POS). | |
| Token ID | Text[128] | Cardholder or payment token ID. | IsTokenEFT |
| Token Value | Text[512] | Token used to perform payments. Contains the created token if token creation request is successful. | IsTokenEFT |
| Token Initiator | Enum LSCEFT Token Initiator | Indicates who is initiating using or creating a token (cardholder or merchant). | IsTokenEFT |
| Token Initiator Reason | Enum LSCEFT Token Initiator Reason | Indicates the reason for creating a token. | IsTokenEFT |
| Token Type | Enum LSCEFT Token Type | Indicates what a token will be used for (in cases of creating tokens) or what it is being used for (in cases of token payments). | IsTokenEFT |
| Token Entry No. | Integer | Entry No. of the linked Token Vault token. | IsTokenEFT |
| Token PSP Reference | Text[128] | Token identifier supplied by the payment provider. | IsTokenEFT |
| Token Caller Reference | Text[128] | Reference owned by the POS. | IsTokenEFT |
| Payment Link ID | Text[256] | Represents the ID of the payment link. | |
| Payment Link Url | Text[1024] | Represents the URL of the payment link that the user will use to complete the payment. | |
| Payment Link Expiration Date | DateTime | The time that the payment link expires. | |
| Payment Link Status | Enum LSCEFT Payment Link Status | The status of the payment link. Possible values: Unknown, Active, Completed, Expired, PaymentPending. | |
| Original Card Entry ID | Integer | This is a reference to the original transaction when doing Finalize/Cancel/Update preauth / Refund / Void. Uses the primary key called ID in LSCEFT Card Entry. | |
| Sender | Enum LSCEFT Request Sender |
Extensible enum to identify the source of the SenderID described below. This field is not mandatory. |
|
| SenderID | RecordId |
Sender ID can be used to connect a card entry request to a primary key of the order/transaction that is being paid for or to the entity that is sending the payment f.ex:
This value can be connected to the Sender field or be a standalone value. The EFT functionality does not use this value, it is purely informational for the user of the EFT Extension. This field is not mandatory. |
Payment Link
You can send the following transaction type in the Request Entity table; Create Payment Link and Disable Payment Link.
- Create Payment Link: Creates the payment link that needs to be sent to the customer usually with email. EFT Extension will create a new Card Entry with authorization status as Pending.
- When the customer has paid with the link, the EFT Extension will listen to the response from a BC Web Service that needs to be setup in the LS Pay admin portal and setup in a BC environment.
- The EFT Extension will automatically create a new Card Entry with Transaction Type equal to Finalize Payment Link, on the instance where the Web Service is hosted. Now there are two card entries one is Pending but the other is approved/declined. They are both connected to the same MerchantOrderId.
Example:
local procedure CreatePaymentLink(var CustomerEmail: Text[80]; SalesHeaderRec: Record "Sales Header";
Amount: Decimal; DeviceRec: Record "LSCEFT Device"): Record "LSCEFT Card Entry"
var
RequestTemp: Record "LSCEFT Request Entity";
PaymentLinkCardEntry: Record "LSCEFT Card Entry";
EFTExt_EntryPoint: Codeunit "LSCEFT Payment Entry Point";
begin
RequestTemp.SetDevice(DeviceRec.ID);
RequestTemp."Merchant Order ID" := Format(SalesHeaderRec.RecordId);
RequestTemp."Pos ID" := 'Pos01';
RequestTemp."Store ID" := 'Fresh Mart';
RequestTemp."Transaction Type" := "LSCEFT Transaction Type"::"Create Payment Link";
RequestTemp.PopulateAmounts(Abs(Amount), 0);
RequestTemp.PaymentLinkExpirationDate := CurrentDateTime() + (1 * 86400000);
// Send request to LS Pay Service to create payment link
EFTExt_EntryPoint.StartOperation(RequestTemp, PaymentLinkCardEntry);
if PaymentLinkCardEntry."Transaction Status" <> "LSCEFT Transaction Status"::Success then begin
Message('Failed to create payment link.');
exit(PaymentLinkCardEntry);
end;
// Send payment link email to customer
if not SendPaymentLinkEmail(CustomerEmail, PaymentLinkCardEntry."Payment Link Url") then begin
Message('Failed to send payment link email to %1.', CustomerEmail);
end;
Message('Payment link for amount %1 sent to %2', RequestTemp."Amount To Be Paid", CustomerEmail);
exit(PaymentLinkCardEntry);
end;
Payment Link Web Service events
OnBeforeShouldSaveFinalizePaymentLinkCardEntry(var CardEntry: Record "LSCEFT Card Entry"; var CheckIfCreatePaymentLinkExists: Boolean)
Notifies that the EFT Extension is about to check if it should save the Card Entry in case users want to make changes to the card entry before saving. Determines whether the finalize payment link card entry should be saved. CheckIfPendingCreatePaymentLinkExists is default false, if CheckIfPendingCreatePaymentLinkExists is changed to true, it checks for an existing pending create payment link entry. It also checks to ensure there is not already a finalize payment link entry for the same payment link ID. If either condition fails, it returns false to prevent saving the card entry.
OnAfterPaymentLinkResponsePosted(CardEntry: Record "LSCEFT Card Entry")
Trigger event for further processing after creating the Card Entry line from the payment link response.
Setting up the Payment Link Web Service
The LS Pay Service will receive webhooks from payment providers when a payment link authorization has been completed. To forward this webhook from the LS Pay Service to Business Central, a web service must be published in Business Central and the LS Pay Service must be configured to send requests to it.
The EFT Extension registers this web service automatically on install and on upgrade, so in most cases no manual setup is required. The registration is:
- Object Type: Codeunit, Object ID: 71558513 (LSCEFT Webhook Receiver)
- Service Name: EFTWebhookReceiver
- Published: true
Registration is idempotent – if a web service with that name already exists it is left untouched, so any existing registration keeps working. Use this exact name (EFTWebhookReceiver) as the Web Service Name in the LS Pay Admin UI.
In your Business Central instance where the EFT Extension is installed:
- Confirm the web service is present: search for "Web Services" and look for EFTWebhookReceiver.
- Assign a user for the web service by opening their user card and copying their web service access key.
- Make sure the user has the necessary permission (LSCEFT permission set) to receive web service requests.
Registering the web service manually (only if it is missing)
If the automatic registration did not run – for example on an environment that pre-dates this feature and has not been upgraded since – publish it by hand:
- Search for "Web Services"
- Click "New":
- Object Type: "Codeunit"
- Object ID: "71558513"
- Service Name: "EFTWebhookReceiver"
- Published: true
- Save and exit the "Web Services" page
Configuration in LS Pay Admin UI
Access the Business Central web service configuration through the LS Pay Admin UI settings panel.
General Settings
| Field | Description | Required |
|---|---|---|
| Deployment Type | Select SaaS (Cloud) or On-Premises | Yes |
| Web Service Name | The name of the OData web service in Business Central. Defaults to EFTWebhookReceiver (registered automatically by the EFT Extension). | Yes |
| Company Name | The exact company name as configured in Business Central | Yes |
SaaS Configuration
For Business Central SaaS (cloud) deployments, set Deployment Type to SaaS, then configure the following:
Authentication Settings
| Field | Description | Required | Example |
|---|---|---|---|
| Client ID | Azure AD application (client) ID | Yes | 87654321-4321-4321-4321-abcdef123456 |
| Client Secret | Azure AD application secret | Yes | [Your secret value] |
| Tenant ID | Your Azure AD tenant ID (GUID) | Yes | 12345678-1234-1234-1234-123456789abc |
| Environment Name | BC environment name | Yes | LSRetailTest |
Advanced Settings (Optional)
| Field | Description | Default Value |
|---|---|---|
| Base URL | BC API base URL | https://api.businesscentral.dynamics.com |
| Token Endpoint | Azure AD OAuth endpoint | https://login.microsoftonline.com |
| Token Scope | OAuth scope for BC API | https://api.businesscentral.dynamics.com/.default |
Note: Leave advanced settings at their default values unless instructed by Microsoft support or your BC administrator.
On-Premises Configuration
For on-premises Business Central installations, set Deployment Type to On-Prem, then configure the following:
Server Settings
| Field | Description | Required | Example |
|---|---|---|---|
| Server Name | BC server hostname or IP address | Yes | localhost or bc-server.company.local or 192.168.1.100 |
| Instance Name | BC server instance name | Yes | BC260 |
| Use HTTPS | Whether BC instance is running on SSL | Yes | Yes |
| OData Port | Port for OData services | Yes | 9058 (default for https) or 9048 (default for http) |
Authentication Type
Select your authentication method:
Basic Authentication
| Field | Description | Required | Example |
|---|---|---|---|
| Domain Name | Windows domain name | (if domain user) | COMPANY |
| Username | BC web service username | Yes | BCWebUser |
| Password | BC web service password | Yes | [Your password] or [Your web service access key] |
OAuth Authentication
| Field | Description | Required | Example |
|---|---|---|---|
| Client ID | Azure AD application (client) ID | Yes | 87654321-4321-4321-4321-abcdef123456 |
| Client Secret | Azure AD application (client) secret | Yes | [Your secret value] |
| Tenant ID | Azure AD tenant ID (GUID) | Yes | 98765432-1234-4321-1234-qwerty123456 |
| Token Endpoint | OAuth token URL | Yes | https://login.microsoftonline.com |
| Token Scope | API scope | Yes | https://api.businesscentral.dynamics.com/.default |