Stripe Integration

Stripe powers card payments in FlexotiumPOS. Setup requires a Stripe account, a Stripe Terminal reader, and configuration of an API key and webhook.

Prerequisites

  • A Stripe account (stripe.com)
  • A Stripe Terminal reader (e.g. BBPOS WisePOS E or Stripe Reader S700)
  • The FlexotiumPOS server must be accessible via HTTPS for webhook delivery

Step 1 — Add your Stripe API keys

  1. Log in to your Stripe dashboard and go to Developers → API keys
  2. Copy your Publishable key and Secret key
  3. In FlexotiumPOS, go to Settings → Integrations → Stripe
  4. Paste both keys and click Save

Step 2 — Configure the webhook

  1. In Stripe, go to Developers → Webhooks → Add endpoint
  2. Enter your webhook URL: https://your-domain.com/api/webhooks/stripe
  3. Select the following events:
    • payment_intent.succeeded
    • payment_intent.payment_failed
    • terminal.reader.action_succeeded
    • terminal.reader.action_failed
  4. Copy the Signing Secret and paste it into FlexotiumPOS under the Stripe integration settings

Test mode vs. live mode

Stripe provides test API keys (prefixed sk_test_) and live API keys (prefixed sk_live_). Always use test mode first to validate the integration before switching to live.

In test mode, use Stripe's test card numbers:

  • 4242 4242 4242 4242 — successful payment
  • 4000 0000 0000 9995 — declined payment

Supported payment types

  • Contactless (tap) — Visa, Mastercard, Amex, Apple Pay, Google Pay
  • Chip and PIN
  • Magnetic stripe (fallback)

Reconciliation

Stripe payments are automatically reconciled in FlexotiumPOS. Each card transaction has a stripe_payment_intent_id visible on the transaction detail page, allowing you to cross-reference with Stripe's dashboard.

Troubleshooting

| Error | Likely cause | Fix | |-------|-------------|-----| | Reader not found | Reader not registered to your Stripe account | Register via Stripe dashboard | | Webhook signature invalid | Wrong signing secret | Re-copy from Stripe Webhooks page | | Payment captured but not recorded | Webhook delivery failed | Check webhook logs in Stripe; retry delivery | | Card declined | Customer card issue | Ask customer to try another card |