CheckoutX SoftPOS
Accept in-person payments on smartphones and tablets by pairing the CheckoutX app with your own POS app — a dual-app setup that requires no SDK integration.
Overview
CheckoutX SoftPOS is the fastest way to accept in-person payments on a smartphone or tablet without integrating an SDK. You install the CheckoutX app alongside your own POS app on the same device, and your app hands off transactions to CheckoutX through a native app switch.
Use this setup when you want contactless acceptance on consumer hardware but don’t want to embed and maintain a SoftPOS SDK inside your own app.
Two Ways to Accept Payments on Phones
Surfboard gives you two routes for in-person payments on iOS and Android. Pick the one that fits your product:
| Option | What you do | When to pick it |
|---|---|---|
| Tap to Pay on iPhone SDK / Android SoftPOS SDK | Embed the Surfboard SoftPOS SDK directly inside your own app | You want a single, branded app with full control over the checkout UX |
| CheckoutX SoftPOS (this guide) | Install the CheckoutX app next to your POS app and use Inter-App Integration to hand off transactions | You want to ship faster, avoid SDK maintenance, or already have a working POS app |
Both approaches run on the same Surfboard platform — the difference is only where the payment UI lives.
How It Works
- Install CheckoutX from the App Store (iOS) or Google Play (Android) on the device running your POS app.
- Register CheckoutX as a terminal once per device using the Inter-App flow.
- Initiate a payment from your POS app — CheckoutX opens, accepts the tap, and returns the result to your app.
The underlying registration, payment, and tag-scanning flows are all documented in the Inter-App Integration guide. CheckoutX SoftPOS is simply that flow running on a consumer phone or tablet instead of a dedicated terminal.
Setup
- Get a Surfboard account and register a store under your merchant.
- Download CheckoutX on the target device.
- Follow Inter-App Integration for terminal registration, payment, and tag-scanning deep link flows. The same API contract applies whether CheckoutX runs on a Surfboard terminal or on a phone in SoftPOS mode.
The Configure Call
Before the first payment — and whenever the device has been idle, rebooted, or has lost its server session — call CheckoutX’s configure route to prepare the terminal:
checkoutx://com.surfboard.checkoutx/configure?redirectUrl=REDIRECT_URLReplace REDIRECT_URL with your base64-encoded app URL. CheckoutX opens, establishes its connection to the Surfboard server, and returns to your app with isConfigured: true when ready.
Running configure before the first transaction of a session gives the smoothest first-payment experience. See Configure Terminal Before Payment in the Inter-App guide for full details.
Handling PS_0025 — Terminal Not Connected
When you initiate a payment on SoftPOS, you may occasionally see:
PS_0025: Terminal is not connected to server so unable to send transactionsIn these cases, run the configure call again and then re-initiate the payment. You can do this seamlessly on your end — the transaction may be slightly slower, but this is the easiest way to recover. No user action is needed.
This is specific to SoftPOS because consumer devices can go idle or lose their session to the server between transactions; a re-configure re-establishes the connection before the next payment.
Reference
- Inter-App Integration — full deep link flow
- Tap to Pay on iPhone SDK — iOS SDK alternative
- Android SoftPOS SDK — Android SDK alternative
Other Guides
Tap to Pay on iPhone SDK
Accept contactless payments directly on iPhone. Complete integration guide for Surfboard's iOS SoftPOS SDK -- from setup to production.
Android SoftPOS SDK
Turn Android devices into payment terminals with the Surfboard Android SoftPOS SDK. Complete integration guide from setup to production.
EMV Terminal Integration
Integrate traditional card-present terminals through Surfboard's unified API. From account setup to live payments in one guide.
Payment Page
Redirect customers to a Surfboard-hosted checkout page. The fastest way to accept online payments with minimal integration effort.
Inter-App Integration
Integrate your POS app with CheckoutX using native app switch. Register terminals, process payments, and scan NFC tags through a bi-directional deep link flow.
Self-Hosted Checkout
Embed a payment form directly in your web app with the Surfboard Online SDK. Full UI control with Surfboard handling PCI compliance.
Server-to-Server API
Process online payments entirely from your backend with Merchant Initiated Transactions. Full control over recurring payments, subscriptions, and tokenized card flows.
Create an Order
Learn how to create orders with line items, tax, customer details, and control functions. The starting point for accepting payments with the Surfboard API.
Merchant Onboarding
Set up merchants and stores on the Surfboard platform. Walk through the full onboarding flow from merchant creation to KYB completion and store setup.
Payment Lifecycle
Manage the full payment lifecycle from order creation through capture, void, cancel, and refund operations using the Surfboard Payments API.
Capture a Payment
Finalize a previously authorized payment by capturing funds. Covers delay capture and pre-authorization flows with step-by-step API examples.
Terminal & Device Management
Manage payment terminals and devices via the Surfboard API. Register in-store and online terminals, configure settings, and handle device operations.
Cancel a Payment
Stop an in-progress payment before it completes. Use cancellation when a customer abandons checkout or a payment needs to be halted mid-process.
Webhooks
Receive real-time event notifications via webhooks. Subscribe to order, payment, logistics, and merchant application events with automatic retries and signature verification.
Notification Subscriptions
Subscribe to persistent, account-level event notifications delivered via email, Slack, or SFTP. Receive settlement reports and operational alerts for merchants and partners.
Recurring Payments
Implement subscription billing and recurring charges using tokenization, recurring payment configuration, and Merchant Initiated Transactions.
Void a Payment
Reverse a completed payment before settlement. Voiding stops funds from transferring to the merchant's account, avoiding incorrect transactions.
Receipts
Generate, email, print, and customise receipts for in-store transactions using the Surfboard Receipts API.
Refund an Order
Process a full refund by creating a return order with negative quantities. Covers the complete refund flow with API examples and payment method requirements.
Partial Refund
Refund specific items or a reduced amount from a completed order. Process partial returns by creating a return order with only the items to be refunded.
Tips Configuration
Configure tipping on Surfboard payment terminals at the merchant, store, or terminal level using a hierarchical override model.
NFC Tag Reading
Use the NFC Reading API to create tag-reading sessions on payment terminals, scan NFC/RFID-tagged products, and retrieve scanned tag data.
Partial Payments
Split an order across multiple payment methods or transactions. Accept card, cash, and Swish in any combination to settle a single order.
Multi-Merchant Terminals
Set up shared payment terminals for multiple merchants using the Multi-Merchant Group API. Ideal for food courts, events, and co-located businesses.
Store Management
Create, update, verify, and manage in-store and online stores using the Surfboard Payments Store APIs.
Gift Cards & Promotions
Issue and manage gift cards, track transactions, and create marketing promotions using the Surfboard Payments APIs.
Product Catalog
Create and manage product catalogs, products, variants, inventory levels, and analytics through the Catalog API.
Settlements & Reporting
Retrieve settlement reports, view adjustments, manage merchant charges, and register customer profiles for reconciliation and billing.
Account & Service Provider Management
Create merchant and partner accounts, manage user roles, register service providers, and configure external notifications via the Surfboard API.
Payment Methods
Activate, deactivate, and list payment methods for a merchant. Manage card, Swish, Klarna, AMEX, Vipps, MobilePay, and more via the API or Partner Portal.
Client Auth Tokens
Generate client-side authentication tokens for secure API access from browsers and mobile apps without exposing your API key or secret.
Partner Branding
Configure white-label branding for terminals and payment pages. Set colors, fonts, logos, and cover images at the partner level via API or Partner Portal.
Ready to get started?
Create a sandbox account and start building your integration today.