Card terminals

The register records the payment: the card brand and the last 4 digits. The card itself is charged by your merchant account, on your processor's terminal. When the card was taken through a connected terminal (below), a void or a refund in ParallelPOS goes back to the card through the processor. A card run standalone has nothing for ParallelPOS to call: the refund is booked here, and you return the money on your terminal.

There are two ways to get the card details into the register:

• Standalone — the cashier runs the card on the terminal, then taps Credit Card in the register and picks the brand and last 4. Works with any terminal from any processor. Nothing to set up.
• Auto-capture — the register sends the amount to the terminal, the customer taps, and the brand and last 4 fill in by themselves. Needs a partner ParallelPOS can drive (below). The charge is made from our server; your key never sits on the till — the settings page shows only its last four characters.

Stripe Terminal

1. In dashboard.stripe.com → Terminal → Readers, register the reader (WisePOS E or Reader S700) to a location.
2. Under Developers → API keys, copy the secret key (sk_live_…). A test key (sk_test_…) drives Stripe's simulated readers.
3. In ParallelPOS, My Account → Entity → Card Terminal: provider Stripe Terminal, paste the secret key, press Test connection and pick the reader it lists (tmr_…). Tick Enable, save.

Square Terminal

1. Pair the Square Terminal to your Square account (Square dashboard → Devices).
2. In developer.squareup.com → your application → Credentials, copy the production access token. Use the sandbox token with Environment: Sandbox to test.
3. In ParallelPOS: provider Square Terminal, paste the token, press Test connection and pick the device (device:…). Tick Enable, save.

Clover

ParallelPOS drives a Clover device directly through Clover's cloud (REST Pay Display). There is no key to copy: you sign in to Clover from ParallelPOS, and the sale prompt appears on the Clover device at the register.

1. The Clover device (Flex, Mini, Station Duo, Station Solo…) is registered to your Clover merchant account and online, and Cloud Pay Display is installed on the merchant from the Clover App Market. ParallelPOS connects to Clover merchants in the United States and Canada.
2. On the Card Terminal card — My Account → Integration Settings for one entity, or My Account → Entity → CC Merchant & Bank Fees for every entity — set the provider to Clover and press Connect Clover. Sign in to Clover with the merchant's owner or admin login and approve ParallelPOS. You come back to the same card, on the same ParallelPOS address you started from, and it finishes the connection with your ParallelPOS sign-in: it then says Connected with the merchant's last four. Only the admin who pressed Connect can finish it, so stay signed in to ParallelPOS while you sign in to Clover; a sign-in that comes back to anyone else connects nothing.
3. Press Test connection: it lists the devices on that merchant. Pick the one at this register (its serial). Tick Enable, save.

• The customer pays on the Clover device, and Clover takes the payment in full there and then. If the sale then does not go through at the register (the cart changed, the sale was refused), ParallelPOS gives the money back by itself: it voids the payment inside Clover's 25-minute window, or refunds it after.
• A card that approves only part of the amount (a prepaid or gift card) is voided straight away, and the cashier takes another payment.
• A payment that comes back with more money than the sale (a tip, or a surcharge the device added) is voided the same way, because the sale cannot record money it does not know about. If your Clover device adds a surcharge or asks for a tip, turn that off for ParallelPOS sales.
• Debit cash back is turned off for ParallelPOS sales. If a device gives it anyway, only the sale's amount is refunded to the card — the cash back stays charged, because the customer may already have the cash — and the register tells the cashier the customer is owed that cash if they have not had it.
• Cancel at the register stops the prompt on the device. If the customer had already paid, the payment is given back and the register says so.
• When the register's own wait runs out while the customer is still finishing on the device (a signature, a second check of the card), it waits a little longer for the device's answer rather than asking for another card. If the payment still lands after the register gave up, it is given back by itself a few minutes later.
• Clover devices can take a card offline and send it later. ParallelPOS turns that off for its own sales: a payment the device has not sent cannot be confirmed at the register.
• Refunds and voids go back to the card through Clover, on the device: it must be online and not in the middle of another customer when a refund is sent. A refund that gets no answer is retried under the same request, so nothing is refunded twice. A void Clover has sent but not yet confirmed shows as pending until it does, and a void Clover could not complete is refunded instead.
• Disconnect on the same card removes the connection from ParallelPOS. To revoke it on Clover's side too, uninstall ParallelPOS from the merchant's apps in the Clover dashboard.
• "The Clover sign-in has expired" means Clover no longer accepts the saved sign-in (it was revoked, or unused for a long time). Press Connect Clover again — nothing else is lost.
• If the entity is later connected to a different Clover merchant, refunds of sales the old merchant took are given back on that merchant's own Clover dashboard. ParallelPOS never sends them to the new one.

Any other processor — the bridge

Use the terminal standalone — it is the normal way most shops run. If your processor or integrator offers a cloud API for the terminal, they can host a small bridge that ParallelPOS's server calls. Every call carries your key as Authorization: Bearer <key>, goes to a public https URL, and never follows a redirect.

POST <endpoint> with {"amount": 4.89, "amount_cents": 489, "currency": "USD", "reference": "…", "charge_id": "…"}. Answer {"status": "approved", "brand": "visa", "last4": "4242", "ref": "<your payment id>"} — or "approved": true. Anything without an explicit verdict is not booked as a card sale.

A public https URL that leads somewhere other than both charge endpoints (primary and secondary — compared by where the path leads, so a trailing ?, ./ or a change of case is the same URL), with no #fragment. With one, every refund and void of a sale the bridge charged — and a charge whose sale never landed — is sent to it:

POST <refund endpoint>, header Idempotency-Key: <refund_id>, body {"action": "refund", "charge_id": "…", "payment_ref": "<the ref you answered at charge>", "reference": "…", "amount": 4.89, "amount_cents": 489, "currency": "USD", "refund_id": "pprf…", "unwind": false, "reason": "ParallelPOS order #123 (refund)"}.

• Answer {"status": "refunded" | "voided" | "pending" | "declined", "refund_ref": "<your refund id>", "message": "…"}.
• unwind: true means the whole sale is being reversed, the amount is the full charge and nothing has been refunded on it yet — you may void instead, and answer voided. Never answer voided to a request without it.
• The same refund_id is sent again when ParallelPOS retries a refund it got no answer for: answer a repeated refund_id with the outcome of the first request, never refund it twice. Until that refund is answered, no other refund of the same charge is sent.
• Only declined — or an HTTP 4xx other than 408, 409, 425 and 429, or a 501 — means nothing was refunded: the operator is then offered other ways to give the money back. Use it only when that is true. Any other word (failed, rejected and denied included), a 2xx without one of the four words, a redirect (3xx), a timeout, a 408 / 409 / 425 / 429 or any other 5xx is treated as unknown: the refund may have reached the card, so nothing is booked and only a retry is offered.
• An answer of approved — the charge endpoint's word — is treated as a misrouted request: nothing is booked, nothing more is sent to that refund URL until it is changed, and the operator is told to check for an extra charge.
• A charge whose sale never landed is released with refund id pprel… and unwind: true; after a declined, the next try is a new id (pprel…-1, -2), and after three the operator is told to refund it on the processor's dashboard.

GET <refund endpoint>?charge_id=…&payment_ref=…[&refund_id=…] answering {"refunded_cents": 489, "refunds": [{"refund_id": "pprf…", "status": "refunded"}]} — the total refunded on that payment so far. ParallelPOS reads it before every refund, so a refund that reached the card but whose answer was lost is booked rather than sent twice, and it follows a pending refund to its end — listing the refund_id is what lets it do so. Answer 404 if you do not support it; a pending refund nobody can follow is put in front of the shop's admins after a day.

USB swipe reader (optional)

A keyboard-style magstripe reader (MagTek Dynamag, ID Tech MiniMag) plugged into the till fills in the brand and last 4 when the Card Details sheet is open. It does not charge the card — the terminal still does that.

If a charge does not go through

• A decline shows on the terminal and is usually the bank — retry, or another card. The register then offers the Card Details sheet so the sale can still be recorded by hand.
• "Not ready" on the Card Terminal card names what is missing (a key, the reader id). Press Test connection: it lists the readers the partner sees with the key you saved.
• If the terminal is down, untick Enable and carry on standalone; nothing else changes.
• "The saved key can no longer be read" means the key on file was sealed with a server key that has since changed. Paste the key again and save — nothing else is lost. Until then nothing is charged or refunded with it, and an approval that needs releasing waits.

If a refund fails after it was sent

Some refunds are accepted by the processor and settle later (Square often answers "pending"). ParallelPOS checks every ten minutes. If the processor then fails the refund — a closed card account, a lost card, a merchant balance too low to cover it — the order stays booked as refunded but the customer has not been paid. The shop's admins and managers get a bell, and Order Management lists the refund at the top of the page until it is made good.

• Send it to the card again — a new refund to the same card, for the same amount. Offered while the entity still uses that processor.
• Give it back in cash — from the drawer of the till you have open; that drawer's close expects that much less cash.
• Returned on the dashboard — you refunded it on the processor's own dashboard or terminal.

Before anything is sent or booked, the processor is asked what it has refunded. Stripe and Square are read refund by refund: a refund redone on their dashboard since is booked as that — and followed, if it is still settling — and nobody is paid twice. A custom bridge gives only a total, which after a declined refund cannot tell a redo from the declined one; then, and whenever the processor cannot be read or shows money ParallelPOS has not booked, you are asked to check the dashboard and tick that you did before cash is handed over. Each failed refund can be made good once, and only by someone who may refund orders.