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?
-
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.
-
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.
-
Online Payment Link
Take a payment on the web without a checkout page of your own. Create an online store, verify its domains, create an order against the PaymentPage terminal it comes with, and send the customer the link it returns.
-
Payment Page
Redirect customers to a Surfboard-hosted checkout page. The fastest way to accept online payments with minimal integration effort.
-
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.
-
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.
-
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
Set up merchants and stores on the Surfboard platform. Walk through the full onboarding flow from merchant creation to KYB completion 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.
-
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.