Stripe Terminal setup

Bitta Retail POS takes integrated card-present payments through Stripe Terminal readers and phone payments through QR Pay, a Stripe Checkout page shown as a QR code on the tender screen. Setup has four parts: the Stripe secret key, a reader for each register, the card tender that records the payments, and the optional QR Pay switch. A Simulated provider runs the same flow with no hardware and no real charges, for demos and testing. Card data never enters Business Central: the reader and Stripe handle the card, and Bitta Retail POS stores only Stripe object IDs and a status.

Prerequisites

• The BAA POS - Admin permission set. Only a Bitta Retail POS administrator can change payment credentials.
• A Stripe account and its secret key, which starts with sk_, from Developers > API keys in the Stripe dashboard.
• For card payments: a Stripe Terminal reader registered in your Stripe dashboard. Registration happens in Stripe; Business Central stores only the resulting reader ID, which starts with tmr_.
• An active tender method of type Card. Setup creates CARD; see Tender methods setup.
• Outbound requests to Stripe allowed for the extension. In a sandbox environment, extensions need Allow HttpClient Requests turned on in Extension Management before they can call external services.

Turn on Stripe card payments

1. Open POS Setup and expand the Card Payments (EFT) FastTab.
2. Set EFT Provider to Stripe. The choices are None, Stripe and Simulated; None turns integrated card payments off.
3. Set Integrated Card Tender Code to the active Card tender method that records Stripe card payments. Leave it blank to disable card-present payments.
4. Leave Stripe Currency Code blank to charge in USD, or enter the ISO currency code Stripe charges should be created in. The field can be edited only while EFT Provider is Stripe.

5. Choose Set Stripe API Key, paste the key into Secret Key and choose OK. The message "Stripe API key saved." confirms it.

The key is stored in Isolated Storage for the current company and is never displayed again. The Stripe API Key field on the FastTab only shows whether a key is set. Clear Stripe API Key removes it; Stripe card and QR payments then stay unavailable until a key is stored again, and they never switch to Simulated on their own.

Payment Poll Failure Limit (1 to 10, default 3) and Payment Poll Failure Window (sec) (30 to 600, default 120) control how many temporary status-check failures the register tolerates before it marks a payment for review. A payment marked for review is not declined; it stays open until it is resolved, for example from Card Transactions on POS Setup.

Assign a reader to each terminal

1. Search for POS Terminals and enter the reader ID (tmr_...) in EFT Terminal ID for each terminal with a reader. Reader IDs are case-sensitive.
2. Leave EFT Terminal ID blank for terminals without a reader. While the provider is Simulated, leave it blank for approvals or set it to sim_decline for declines; see Test with the Simulated provider.

A terminal without a reader cannot take Stripe card payments; the cashier sees "This terminal has no EFT Terminal ID configured, so it cannot take Stripe card payments." The card tender must also be offered at that terminal. If you hide tenders per terminal with tender overrides, keep the integrated card tender visible.

Turn on QR Pay

QR Pay creates a Stripe Checkout session for the amount still due and shows it as a QR code. The customer scans it and pays on their own phone, with a card, Apple Pay or Google Pay; no reader is involved.

1. In the QR Pay group of the Card Payments (EFT) FastTab, select QR Pay Enabled.
2. Set QR Pay Tender Method Code to an active Card tender method.
3. Optionally enter QR Pay Success URL, a page the customer's phone opens after paying. Leave it blank to show Stripe's own confirmation page.

The register offers QR Pay only when EFT Provider is Stripe with a stored key, or Simulated. With None or a Stripe provider without a key, the QR Pay button stays hidden.

Test with the Simulated provider

Set EFT Provider to Simulated to run card and QR payments end to end with no reader and no real charges. The demo data selects Simulated when no provider is set. Integrated Card Tender Code, QR Pay Enabled and QR Pay Tender Method Code still need to be filled in before the Pay card and QR Pay buttons appear. Switch to Stripe and store a key before going live. Run the scenarios below before go-live.

Run them in an evaluation company, such as the demo company created by Try Bitta Retail POS with Demo Data, never in a company that takes real payments. For the QR scenarios, turn on QR Pay Enabled and choose a Card tender method in QR Pay Tender Method Code. On POS Terminals, the EFT Terminal ID of the test terminal controls the card outcome: leave it blank for approvals, or set it to sim_decline for declines.

You need a cashier with BAA POS - User to run sales, and a supervisor or administrator (BAA POS - Supervisor or BAA POS - Admin) for the refund and reconciliation scenarios. See POS user permissions.

How the Simulated provider answers

The Simulated provider drives the same tender screen, Card Payment and QR Payment dialogs, EFT transaction records, booking and recovery logic as Stripe, but makes no network calls and charges nothing.

Request	What the Simulated provider does
Card payment, EFT Terminal ID blank or any value except sim_decline	Accepts the payment; the first status check reports it succeeded, and capture succeeds. The card evidence recorded is a simulated Visa ending 4242.
Card payment, EFT Terminal ID = sim_decline	The first status check reports a decline with the code card_declined and the message "Your card was declined."
Cancel on the reader	Always accepted.
QR payment	Creates a simulated Stripe Checkout session with a placeholder payment link; the first status check reports it paid.
Cancel a QR payment	Always accepted; the simulated session is expired.
Refund	Always completes.

The Card Payment dialog makes its first status check about 1.5 seconds after it opens, and the QR Payment dialog about 2 seconds after. That window is when a cancel or an interruption can happen.

Acceptance scenarios

Run each scenario on a fresh sale and record the result.

ID	Scenario	How to run it	Expected result
EFT-SIM-01	Approved card payment	Tender, Pay card.	Status "Approved - press Done to continue."; after Done the sale completes with one captured card line.
EFT-SIM-02	Split cash and card	Tender, add a cash line for part of the total, then Pay card.	The card charges only the remainder; the sale completes with a cash line and a locked card line.
EFT-SIM-03	Declined card	Set EFT Terminal ID to sim_decline, then Pay card.	Status "Declined - press Done to close." with the failure message; after Done the tender screen reopens with "The external payment was not captured. The staged tender split is still available for review or retry."
EFT-SIM-04	Retry after decline	After EFT-SIM-03, clear EFT Terminal ID and choose Pay card again.	The retry is approved; the declined attempt stays in POS EFT Transactions as failed.
EFT-SIM-05	Cashier cancel	Pay card, then choose Cancel Payment immediately, before the first status check.	The Card Payment dialog closes and the tender screen reopens with "The external payment was not captured. The staged tender split is still available for review or retry."; the transaction shows as Cancelled in POS EFT Transactions and nothing is booked on the sale.
EFT-SIM-06	Dialog closed during payment	Pay card, then close the dialog with Escape before the first status check.	The reader action is cancelled on a best-effort basis; if the cancel did not land, the payment stays open and is resolved by reconciliation, never charged twice.
EFT-SIM-07	Browser closed during payment	Pay card, then close the browser tab before the first status check. Reopen POS Register on the same terminal. If it shows Register in use, wait for Register Lease Timeout (sec) (default 120) to pass and choose Retry.	The register resolves the open payment before sign-in, then shows "1 in-flight card payment(s) from an earlier session were resolved." The payment is captured and booked if the sale still expects it, otherwise voided.
EFT-SIM-08	QR payment	Tender, QR Pay.	The QR code and Payment Link show, then "Paid - press Done to continue."; after Done the sale completes.
EFT-SIM-09	QR cancel	QR Pay, then Cancel Payment before the first status check.	The QR Payment dialog closes, the session is expired, and the tender screen reopens with the not-captured message; nothing is booked.
EFT-SIM-10	Card refund	Return a sale paid with Pay card from its receipt.	The refund goes back to the original simulated charge and completes; the refund cannot exceed the original charge. See Returns and refunds.
EFT-SIM-11	Back-office reconcile	With a payment left open from another session, open POS EFT Transactions and choose Reconcile Open Transactions.	Open payments not held by a register are resolved; payments held by a register report that they can only be resolved on that terminal.

What the Simulated provider does not cover

The Simulated provider in a released app has no switch for timeouts, network failures, uncertain processor responses or pending refunds. Rehearse what you can of those paths against Stripe in test mode before go-live. The status-check retry budget that applies to them is set on POS Setup with Payment Poll Failure Limit (default 3) and Payment Poll Failure Window (sec) (default 120); once it is spent, the payment is marked for review instead of declined.

Evidence to keep

For each scenario, note the POS sale number, the payment line, the POS EFT Transactions entry and its status, and any EFT Attention entry. Keep secret keys and processor identifiers out of screenshots and test notes. Remember that a captured payment is not yet a ledger posting: Business Central documents are created when the sale posts at End of Day. See Tender settlement.

When every scenario passes, repeat EFT-SIM-01, EFT-SIM-03, EFT-SIM-05 and EFT-SIM-10 with Stripe in test mode, then with the physical reader, so a new failure points at the configuration or the hardware rather than the flow.

What the cashier sees

On the tender screen, the register shows Pay card when integrated card payments are configured and QR Pay when QR Pay is available. Pay card opens the Card Payment dialog while the reader takes the card; QR Pay opens QR Payment with the code and the instruction "Ask the customer to scan and pay on their phone". The full cashier flow, including recovery when a payment needs review, is in Card and QR payments.

What's next

Show stock levels on the register: Stock availability.