Developers Guides
Developer guides
Step-by-step integration guides for every Surfboard payment channel, from SDK setup to production. Each one opens with a prompt you can paste straight into your coding agent.
How can I help you integrate today?
Start with a path
Pick what you are building and get the guides in the order to read them, on one page or as one markdown file for your coding agent. Every path opens with getting access.
- 01 Food & Beverage Restaurant and café POS: your app on the terminal, tips, split bills, receipts at the counter, and payment links for orders taken online. Open the path
- 02 Retail Store POS on Surfboard terminals: product catalog with barcodes and stock, a compliant cash register for Sweden, returns, gift cards and receipts. Open the path
- 03 Hospitality Hotels and venues: a deposit online, the balance at reception, pre-authorisation and later capture, stored cards for no-shows, and invoices for corporate guests. Open the path
- 04 SoftPOS only Tap to Pay on iPhone and Android with no hardware: your app beside the CheckoutX app on the same device, then orders, refunds and receipts from your own app. Open the path
-
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.
-
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.
-
EMV Terminal Integration
Integrate traditional card-present terminals through Surfboard's unified API. From account setup to live payments in one guide.
-
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 -- from a native app or a browser-based POS.
-
Customer Identification on Card Tap
Recognise a returning customer from the card they tap, before the payment runs. Apply their discount, points or price list to the open order, then take the money.
-
Payment Page
Take online payments on a Surfboard-hosted checkout page. Create an online store, verify its domains, create an order against the PaymentPage terminal it comes with, and redirect the customer or send them the link.
-
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.
-
Tokens
Turn a card used once into a card you can charge again. Enable tokenization on an order, fetch the token it produced, and store it for subscriptions, repeat purchases and refunds.
-
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.
-
Create Order Error Codes
Reference of error codes returned by the create order and initiate payment flows, with notes on when each is thrown and how to handle it.
-
Capture a Payment
Finalize a previously authorized payment by capturing funds. Covers delay capture and pre-authorization flows with step-by-step API examples.
-
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.
-
Void a Payment
Reverse a completed payment before settlement. Voiding stops funds from transferring to the merchant's account, avoiding incorrect transactions.
-
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.
-
Partial Payments
Split an order across multiple payment methods or transactions. Accept card, cash, and Swish in any combination to settle a single order.
-
Service Providers & Split Payouts
Route a share of each payment to a third party with Surfboard Flow. Onboard a service provider, link it to a merchant, and set the split on the order.
-
B2B Invoices
Bill a business buyer on payment terms instead of charging a card. Create an order paid with B2BINV, distribute the invoice as an e-invoice or by email, and credit it when the goods come back.
-
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.
-
Payment Lifecycle
Manage the full payment lifecycle from order creation through capture, void, cancel, and refund operations using the Surfboard Payments API.
-
Recurring Payments
Implement subscription billing and recurring charges using tokenization, recurring payment configuration, and Merchant Initiated Transactions.
-
Device Registration
Register a terminal to a store before it can take payments or receive a partner POS app. Covers rotating codes, QR/registration links, pre-shipped codes, and in-app registration for SoftPOS.
-
Terminal & Device Management
Manage payment terminals and devices via the Surfboard API. Register in-store and online terminals, configure settings, and handle device operations.
-
Receipts
Generate, email, print, and customise receipts for in-store transactions using the Surfboard Receipts API.
-
Receipt Printing
How to print a receipt on a terminal with a built-in printer or on the FinPrinter: let Surfboard render it from a template, or build the layout yourself and send ESC/POS to a terminal. How to choose, and how to set up each.
-
ESC/POS Printing
Send custom ESC/POS receipts to any Surfboard terminal using the UTF-8 contract: opt in with one field, get validated payloads and consistent output across current and legacy hardware.
-
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.
-
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.
-
Order and Return Terminals
Get hardware to your merchants and back again. Order terminals during onboarding or later, track the shipment by webhook, and raise a return when a device is no longer needed.
-
POS Templates
Decide what the till shows and in what order. Lay out product categories, payment methods and terminals per store, and switch layouts automatically by time of day.
-
Merchant Onboarding
Create a merchant application through the Partner API and hand the merchant a prefilled web KYB link. Registry lookup, automatic business classification, people and signing, application status, and store setup.
-
Store Management
Create, update, verify, and manage in-store and online stores using the Surfboard Payments Store APIs.
-
Account & Service Provider Management
Create merchant and partner accounts, manage user roles, register service providers, and configure external notifications via the Surfboard API.
-
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.
-
Build Your Own ECR
Turn your ERP or business system into a compliant point of sale for Sweden. Product catalog, fiscal cash register with control unit, Skatteverket declaration, shifts, cash handling, orders, receipts, and Z-reports on the Surfboard platform.
-
Settlements & Reporting
Retrieve settlement reports, view adjustments, manage merchant charges, and register customer profiles for reconciliation and billing.
-
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.
-
Transactions and Reports
Retrieve, filter and search transactions, and read a monthly report the way finance does. Covers why net sales and payout never match and how to reconcile a period end to end.
-
AI Product Images and Branding
Turn a phone photo into a usable product image and a website into a branded portal. Two endpoints that remove the design work from onboarding a merchant.
-
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.
-
API Conventions
The rules that hold across every Surfboard endpoint: authentication, the response envelope, amounts and currencies, identifiers, dates, pagination and environments.