StoreCashierDocumentation Free 1.6.6 Pro 1.5.6 Apps 1.5.0

Card readers PRO

Connect a card terminal to the POS so card payments are taken from the register and recorded automatically: Stripe Terminal, Square Terminal, SumUp Solo, Adyen, Mollie, Viva.com, Helcim and Dojo are built in, any terminal with an HTTP API can be added as a Custom terminal without code, and every other card machine works as a Standalone terminal where the cashier records the approval code.

Where: Inventory Management → Accounting → Card Readers (devices) and → Card Readers → Transactions
Card Readers list with a standalone terminal
Accounting → Card Readers.

How it works#

  1. You add a device: a name, the provider type, the business location, the payment account the money is deposited to, and the provider's keys.
  2. Cashiers allowed to use it get a Card reader tab in the POS payment dialog (Payment dialog).
  3. Integrated readers: the POS sends the amount to the terminal, polls the provider until the card is approved, declined or cancelled, then saves the sale. Standalone: the cashier keys the amount into the terminal and records the approval code.
  4. Every attempt is a row in the Transactions log. An approved payment is booked to the device's deposit account as a "Card reader" payment of the sale with the reference (payment ID, approval code, card brand and last 4 digits), and an order note is added.
  5. Refunds go back to the card through the provider (where supported) from a sell return or from the log.
Security: API keys and tokens are stored encrypted, are never shown again (the form says "Saved: •••• — leave blank to keep"), and are removed from logged provider responses. Paste them only into this form. The site needs HTTPS and must be allowed to make outgoing HTTPS connections to the provider (port 443).

Permissions#

Store Staff permission (Card Readers)Allows
View devices & transactionsSee the device list and the transactions log.
Add / edit devices & provider keysAdd, edit, activate / deactivate and delete devices; test connections. Also includes viewing and refunds.
Take card reader payments at the POSShows the Card reader tab (also needs Use POS register). Managers always have it.
Change the deposit account at the POSPick another payment account for a reader that allows it. Managers always.
Refund / void card paymentsRefund to the card from a sell return or the log; void unused payments.

A cashier also needs access to the reader's location and to its payment account (Store Staff → locations / accounts), unless allowed to override the account.

Add a card reader#

Add Card Reader form with Standalone terminal selected
Add Card Reader — Standalone terminal.
FieldWhat it doesExample
Name *What cashiers see in the POS.Front counter S710
Type / providerThe driver: Standalone terminal, Stripe Terminal, Square Terminal, SumUp Solo (Cloud API), Adyen (Terminal API, cloud), Mollie point-of-sale terminal, Viva.com Cloud Terminal, Helcim Smart Terminal, Dojo (Pay at Counter), Custom terminal (HTTP API). The provider settings box below changes with it, with its description, country / currency notes and a Provider documentation link.Stripe Terminal
Business locationWhere the reader is used. "All locations" = every location.Nova Mart – Downtown
Deposit to payment account *Account that receives the card money (e.g. an account named after the provider, so it shows what will be paid out). Must be open.Stripe
StatusActive readers appear in the POS; Inactive are hidden but keep their history.Active
Cashiers with permission may change the deposit account at the POSUnlocks the account selector in the POS for users with that permission. In the list the account shows "changeable".Off
Staff who may use this readerTick POS staff members. None ticked = every cashier with "Take card reader payments". Administrators and managers can always use every reader.
NotesInternal note.
Provider settingsKeys and options of the selected provider (below).

Click Save card reader ("Card reader saved."). Errors are listed at the top, e.g. "Enter a name for the card reader.", "Choose the payment account the card payments are deposited to." Changing the provider of a saved device removes its old key.

Setup per provider#

Standalone terminal (any card machine)#

For Clover, PayPal Zettle, PAX, Verifone, Ingenico, bank terminals… that are not connected to the website.

  • Terminal model / provider (optional) — e.g. "Verifone V240m — City Bank".
  • Require the approval code from the terminal slip — the POS then refuses to record without a code ("Enter the approval code from the terminal slip.").

At the POS: key the amount into the terminal, when approved type the approval code (and optionally brand and last 4 digits) and click Payment approved — record it. Refunds and voids are done on the terminal; StoreCashier marks a voided payment as "Voided — void it on the terminal too".

Stripe Terminal#

Add Card Reader form with Stripe Terminal settings
Stripe Terminal settings: secret key, Terminal location, reader, register a new reader, Test connection.

Stripe smart readers (BBPOS WisePOS E, Stripe Reader S700 / S710…) driven from the POS; no app is installed on the reader. Available where Stripe Terminal is offered (US, CA, UK, EU, AU, NZ, SG, JP…).

  1. In the Stripe Dashboard create a Terminal location (Terminal → Locations → New location) with your shop address.
  2. Developers → API keys: copy the Secret key (sk_live_…, test sk_test_…), or better create a restricted key (rk_…) with write access to PaymentIntents, Terminal (readers and locations) and Refunds.
  3. Create a payment account for card money in Accounting → List Accounts, e.g. "Stripe".
  4. Add Card Reader: Type Stripe Terminal, location, deposit account "Stripe", Status Active.
  5. Paste the key into Stripe secret key. A key that does not look like one is refused: "That does not look like a Stripe secret key (sk_test_… / sk_live_… / rk_…)."
  6. Stripe Terminal location (optional) — click Load locations and pick it (ids start with tml_); it is used to register readers and to filter the reader list.
  7. Reader: on the reader open Settings → Generate pairing code. Under Register a new reader type the Registration code, a Reader label and click Register reader ("Reader … registered and selected — save the card reader."). Already registered? Click Load readers and pick it (ids start with tmr_).
  8. Test connection — shows whether the key works and the reader is online, e.g. "Reader "Front counter" is online."
  9. Save card reader, then give cashiers the permission.

Test mode: with a sk_test_ key and a test location, register the code simulated-wpe to create a simulated WisePOS E (no hardware). In the POS the reader shows a Test mode tag and the buttons Simulate card (approve) / Simulate card (decline). Amounts are sent in the smallest currency unit. Card refunds go back through Stripe (full or partial).

Square Terminal#

Square Terminal provider settings
Square Terminal settings.
SettingWhat to enter
Access token *Personal or OAuth token (EAAA…) with PAYMENTS_WRITE, PAYMENTS_READ, DEVICE_CREDENTIAL_MANAGEMENT and MERCHANT_PROFILE_READ.
EnvironmentSandbox (test) or Production (live).
Square location ID *L… from Square Dashboard → Account & Settings → Locations. Needed to pair a Terminal.
Terminal device ID *Load devices from the account, or Pair a new device with the code shown on the Terminal (Pair device).

US, CA, UK, AU, JP. The currency must be the Square location's currency. Sandbox device ids from the Square docs simulate approvals, cancellations and timeouts (up to 25.00). Supports refunds.

SumUp Solo (Cloud API)#

SumUp provider settings
SumUp Solo settings.
SettingWhat to enter
API key *sup_sk_…
Affiliate key *Required by the Cloud API for reader checkouts (SumUp Developer → Affiliate Keys).
Affiliate app ID *e.g. com.example.pos
Merchant code *M…
This is a SumUp sandbox merchant account (test mode)Tick for a sandbox account (Virtual Solo, no hardware).
Reader ID *Load devices, or Pair a new device with the pairing code shown on the Solo.

EU, UK, US, BR, CL, CO, PE and more; the currency must be your SumUp account currency. The reader must be online and on its home screen. Supports refunds.

Adyen (Terminal API, cloud)#

SettingWhat to enter
API key *Key with the Cloud Device API role (Customer Area → Developers → API credentials).
Merchant account *Your Adyen merchant account name.
EnvironmentTest, Live — Europe, Live — United States, Live — Australia, Live — East / Northeast Asia.
Sale ID (POS system name)Default "StoreCashier".
Terminal POIID *Model-serial of the terminal, e.g. S1F2-000158….

Worldwide, most currencies (amounts in major units). Test with an Adyen test terminal. Supports refunds.

Mollie point-of-sale terminal#

API key * (test_… / live_… — test mode follows the key) and the Terminal ID (term_…, or Load devices). A "pointofsale" payment is created for the terminal; the sale is saved when Mollie reports it paid. EU merchants; EUR, GBP, CHF, DKK, NOK, SEK, PLN, CZK. Supports refunds.

Viva.com Cloud Terminal#

POS API client ID *, POS API client secret * (create "POS API" credentials in Viva self-care), Environment Demo (test) / Live, Cash register ID (default StoreCashier) and the Terminal ID (or Load devices). Card terminals and "Viva Terminal" app devices; EU and UK merchants (EUR, GBP, PLN, RON, CZK, HUF, SEK, DKK, BGN…). Supports refunds.

Helcim Smart Terminal#

API token * (API access configuration with Processing permission "PositiveTransaction" or higher — refunds need "Admin"), This is a Helcim developer test account, and the Device code (4 characters shown on the terminal). Put the terminal in API mode first. Canada (CAD) and USA (USD) only. A running payment is cancelled on the terminal itself. Supports refunds.

Dojo (Pay at Counter)#

Secret API key * (sk_sandbox_… / sk_prod_…), Software house ID and Reseller ID (sandbox: softwareHouse1 / reseller1; production: the IDs assigned by Dojo), and the Terminal ID (or Load devices). UK, Ireland, Spain, Italy (GBP / EUR). Supports refunds.

Custom terminal (HTTP API)#

Custom terminal HTTP API settings with start request, response mapping, polling, cancel and refund
Custom terminal: describe the requests, no code needed.

For any terminal or payment gateway with an HTTP API. You describe the requests in four steps:

SectionSettings
Device / terminal IDUsed as {device_id}. Sandbox / test endpoint marks payments as test.
Headers (used for every request)Add header: name, value (placeholders allowed) and Secret (stored encrypted, never shown again, never logged — use it for API keys).
1. Start the paymentMethod, URL (must be https://; plain http only for localhost / private network IPs), Body type (JSON, Form x-www-form-urlencoded, No body), Body template, Timeout (seconds).
2. Read the responsePath to the transaction ID, Path to the status, Approved values, Declined values, Pending values (comma separated), optional paths to a message, approval code, card brand and card last 4 / masked number.
3. Status polling (optional)URL (leave empty when the start response is final), method, interval (seconds).
4. Cancel and refund (optional)Cancel URL / method / body; Refund URL / method / body ({amount} = refund amount). Without them, cancel and refund on the terminal.

Placeholders: {amount} (12.50), {amount_minor} (1250), {currency}, {reference}, {device_id}, {description}, {location}, {txn_id} (polling / cancel / refund). Test request really sends the start request with the Test amount and shows the response — point it at a sandbox URL. Export configuration / Import configuration copy the setup between sites (secret header values are never exported).

Local network terminals: a website on the internet cannot reach a terminal in your shop's network. Saving a device with a local address shows a warning; use the provider's cloud API URL instead.

Transactions log#

Card Reader Transactions log
Accounting → Card Readers → Transactions.

Filters: card reader, status, From / To. Columns: Date, Card reader, Amount, Card (brand •••• last4), Reference (payment / intent ID, approval code), Account, Sale (with "not in a sale" for unused ones), Cashier, Status, Refunded, Actions (Open order, Sale payments, Sell return, Refund to card…, Void payment). Test payments carry a Test tag.

StatusMeaning
PendingCreated, not yet sent / answered.
Waiting for cardThe terminal shows the amount.
ProcessingThe card is being processed.
ApprovedPaid (used in a sale, or waiting to be used).
Declined / failedNot paid; nothing was charged.
CancelledCancelled at the POS or on the terminal.
VoidedAn approved payment that was not used in a sale and was voided (standalone: void it on the terminal too).
RefundedFully refunded to the card (partial refunds show in the Refunded column).

Refunds#

  • From a sell return (recommended): Sales & POS → Sell Return of the sale, enter the Refund Amount, choose the reader's account as Refund From Account and tick Also refund the Refund Amount to the customer's card through Stripe (up to …). Stock, accounts and the card all match. If the return is waiting for approval the card is refunded after approval from the Transactions log. Standalone payments: "refund it on the card terminal, then record the refund here".
  • From the Transactions log: Refund to card… with the amount ("This only refunds the card through the provider. Record the sell return / refund in StoreCashier as well so stock and account balances stay correct.").
  • Void: an approved payment that never became a sale can be voided from the POS ("Approved card payments not used in a sale yet") or the log — refunded in full to the card for integrated providers.

Refunds are limited to the amount not yet refunded ("You can refund at most …"), and two refunds of the same payment at the same time are blocked.

Deactivate or delete a reader#

Actions in the list: Edit, Activate / Deactivate, Delete. A reader with transactions cannot be deleted ("set it to inactive instead") so the history stays complete.

Troubleshooting#

ProblemWhat to do
Cashier has no Card reader tabGive "Take card reader payments at the POS", make the reader Active, assign it to the POS location (or All locations), check "Staff who may use this reader", and the cashier's access to the deposit account.
Reader offlineCheck its Wi-Fi / cellular / Ethernet, restart it, then Test connection.
Registration code rejected (Stripe)Generate a new code (they expire) and select a Terminal location. Live keys need a real reader; test keys use simulated-wpe.
"The card was declined"Ask for another card or method; nothing was charged.
Timeout / cURL error 28The web host blocks outgoing connections; ask them to allow HTTPS (443) to the provider API. Settings → System Status helps diagnose.