Sign in Talk to us Free trial
Free trial

Design and software studio
Colour

Connect Stripe Terminal card readers

Add a Stripe card reader from your own Stripe account, switch on the Card readers connection and take a card payment on an invoice in person.

For
Owner
Hosting
Any hosting
Devices
Web browser
Business
All businesses

Checked against Pop Dispatch 0.1.0

A card reader lets a customer pay an invoice in person. The reader belongs to your own Stripe account, and the money goes to you. You tell Pop Dispatch which reader to use by its reader ID, switch on the connection and test it.

Before you start #

  • Only the owner adds or removes readers and switches the connection on.
  • You have a Stripe account with a Terminal reader set up, and your Stripe secret key is saved in Settings, Online payments. See "Connect your own Stripe account for card payments".
  • The reader is switched on and online.

Steps #

  1. In your Stripe dashboard, open the reader's page. Copy the reader ID. It starts with tmr_.
  2. In Pop Dispatch, open Settings, then Connections. Find the card "Card readers (Stripe Terminal)". Its "Still needed:" line lists any missing setup.
  3. Under "Card readers", fill in the form "Add a card reader". Type the "Reader ID" (the tmr_ ID shown on the reader's page in your Stripe dashboard) and a "Name", such as Front desk. Choose "Add a card reader". The reader appears in the "Card readers" table with its Name, Reader ID and when it was Added. Pop Dispatch asks Stripe about the reader first, so the ID has to belong to your account.
  4. Tick "Switch on Card readers (Stripe Terminal)". The switch works once the Stripe key is saved and a reader is added. A message confirms: "Card readers (Stripe Terminal) is on."
  5. Choose "Test connection". The message reads "Stripe accepted your key and can list your card readers." when all is well.
  6. To take a payment, start a reader charge on an invoice that has a balance, naming the reader. The reader asks for the card. The charge shows Waiting until the customer pays, then Paid or Failed, and a paid charge is recorded once as a payment on the invoice.
  7. To refund it, use the same steps as any card payment. Open the invoice and use "Refund or credit note". The refund goes back through Stripe, because the payment keeps its Stripe reference.
  8. To stop using a reader, choose "Remove reader" beside it in the table and confirm. A reader with charges on file stays on the list.
Technical details
  • Routes: GET and POST /terminal/readers, DELETE /terminal/readers/:id (owner writes); POST /invoices/:id/terminal-charge with reader_id and an optional amount_cents; GET /terminal/charges/:id refreshes a charge and records the payment once it is paid.
  • The reader ID is used rather than a location address, because Stripe asks for an address when you register a new reader there.
  • Charges are made as card-present payment intents on your own Stripe account. A paid charge is recorded once, with the payment intent as the reference, so it can be refunded.
  • Reader charges are refused until the Stripe Terminal connection is on: "Card readers are off. Turn on the Stripe Terminal connection in Settings, Connections."
  • The console's invoice page shows no button for a reader charge in this release. Start the charge through the route above.

If something goes wrong #

  • "A reader id starts with tmr_ and is shown on the reader's page in the Stripe dashboard.": copy the ID again from Stripe.
  • "Check the reader id and that it belongs to your Stripe account.": the ID is from another account, or has a typing error.
  • "That reader is already added.": it is in the table.
  • "The reader did not accept the charge. Check it is switched on and online.": switch the reader on, check its network and start the charge again.
  • "This reader has charges on file, so it stays on the list.": a reader with payments cannot be removed.
  • "This invoice has nothing left to pay.": the invoice is paid or void.