Self-Hosted Checkout - Surfboard Payments

Overview

The Self-Hosted Checkout (Online SDK) lets you embed payment fields directly in your website while Surfboard handles PCI compliance and payment processing. You get full control over the look and feel of your checkout page.

Surfboard renders secure input fields inside your page using the Online SDK. You control the layout, branding, and customer experience.

Prerequisites

Create a developer account at the Developer Portal
Complete onboarding (merchant and store setup)
Register a terminal with the type set to SelfHostedPage
Note the terminal’s publicKey from the registration response

Tip: You can retrieve the terminal’s public key later using the Fetch Terminal by ID API. It is returned as terminalPublicKey in the response.

Initializing the SDK

To initialize the SDK, you need three parameters:

publicKey — From terminal registration
orderId — From the Create Order API response
nonce — From the Create Order response (serves as access control)

// Set up error handling
SurfboardOnlineSDK.errorCallback((code, message) => {
    console.error(`Error [${code}]: ${message}`);
});

// Listen for payment status changes
SurfboardOnlineSDK.paymentStatusCallback = function (data) {
    // data.paymentStatus: 'PAYMENT_INITIATED' | 'PAYMENT_COMPLETED' |
    //   'PAYMENT_CANCELLED' | 'PAYMENT_FAILED' | 'PAYMENT_PROCESSING'
    console.log("Payment status:", data.paymentStatus);
};

// Initialize
SurfboardOnlineSDK.initialiseOnlineSDK({
    publicKey: "YOUR_PUBLIC_KEY",
    orderId: "YOUR_ORDER_ID",
    nonce: "YOUR_NONCE",
});

To re-initialize for a different order without a full page reload:

SurfboardOnlineSDK.remountOnlineSDK({
    publicKey: "YOUR_PUBLIC_KEY",
    orderId: "NEW_ORDER_ID",
    nonce: "NEW_NONCE",
});

Error Codes

Error Code	Message	Category
—	Surfboard SDK cannot function in the given environment	FATAL
—	Surfboard SDK initialisation failed	FATAL
—	Public key validation failed	FATAL
—	Invalid Order ID	FATAL
—	Invalid Nonce	FATAL
401	Invalid or Expired Link	FATAL

Available Data Objects

After successful initialization, the SDK exposes data objects on SurfboardOnlineSDK:

order — Order details, line items, and payment methods
merchant — Merchant name and organization number
branding — Colors, fonts, logos for your checkout styling
store — Store contact info, privacy policy, and terms URLs
paymentMethods — Supported payment methods for this terminal
customer — Customer details, saved cards, and addresses

Warning: You are required to display the store contact information, privacy policy, and terms and conditions on your payment page.

Payment Flow

Updating Customer Information

Most payment methods require customer information. Provide it via the SDK or include it when creating the order.

Payment Method	Required Fields
Card	Email, Phone, Address
Klarna	Email, Phone, Address, Shipping Address (physical goods)
Apple Pay	Email, Name, Phone, Postal Address

await SurfboardOnlineSDK.order.addCustomerInformation({
    name: "Jane Doe",
    email: "jane@example.com",
    phone: { countryCode: "+46", number: "701234567" },
    billingAddress: {
        addressLine1: "Main Street 1",
        city: "Stockholm",
        postalCode: "11122",
        countryCode: "SE",
    },
});

Tip: Include the customer address in the Create Order API request when you have it. This pre-fills the address so the customer does not need to enter it manually.

Card Payments

Mount the card input fields in your page:

<div id="card-details"></div>

SurfboardOnlineSDK.mount({
    mountCardWidget: "card-details",
});

// When the customer clicks "Pay":
await SurfboardOnlineSDK.order.initiatePayments("CARD");

Swish Payments

const paymentAttempt = await SurfboardOnlineSDK.order.initiatePayments("NSWISH");

// For mobile: redirect to Swish app
const redirectUrl = paymentAttempt.getSwishAppRedirectUrl("https://your-site.com/callback");

// For web: display QR code
const qrData = paymentAttempt.getSwishQRData;

Apple Pay

<div id="apple-pay"></div>

SurfboardOnlineSDK.mount({
    mountApplePayWidget: "apple-pay",
});
// Payment is initiated automatically when the customer clicks the Apple Pay button

For Apple Pay, you must host the domain association file at /.well-known/apple-developer-merchantid-domain-association on your domain.

Klarna

await SurfboardOnlineSDK.order.addCustomerInformation({
    phone: { countryCode: "+46", number: "701234567" },
    name: "Jane Doe",
    email: "jane@example.com",
    billingAddress: {
        city: "Stockholm",
        postalCode: "11122",
        countryCode: "SE",
        addressLine1: "Main Street 1",
    },
});

await SurfboardOnlineSDK.order.initiatePayments("KLARNA");

Payment Error Codes

Code	Message	Category
ON_009	Phone number required for Swish payment	Non Fatal
ON_010	Payment method not supported for this order	Non Fatal
ON_011	Payment already completed	Non Fatal
ON_012	Error initiating payment — retry	Non Fatal
ON_013	Unknown error — page reload may help	Non Fatal
ON_016	Invalid card details	Non Fatal
ON_017	Email required for this payment	Non Fatal
ON_018	Billing address required for this payment	Non Fatal

Reference

React Sample App for a complete working example
Create Order API
Fetch Terminal API
Developer Portal

Other Guides

in-store

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.

in-store

Android SoftPOS SDK

Turn Android devices into payment terminals with the Surfboard Android SoftPOS SDK. Complete integration guide from setup to production.

in-store

EMV Terminal Integration

Integrate traditional card-present terminals through Surfboard's unified API. From account setup to live payments in one guide.

online

Payment Page

Redirect customers to a Surfboard-hosted checkout page. The fastest way to accept online payments with minimal integration effort.

in-store

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.

online

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.

online

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.

online

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.

online

Payment Lifecycle

Manage the full payment lifecycle from order creation through capture, void, cancel, and refund operations using the Surfboard Payments API.

online

Capture a Payment

Finalize a previously authorized payment by capturing funds. Covers delay capture and pre-authorization flows with step-by-step API examples.

in-store

Terminal & Device Management

Manage payment terminals and devices via the Surfboard API. Register in-store and online terminals, configure settings, and handle device operations.

online

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.

online

Webhooks & Notifications

Receive real-time event notifications via webhooks, email, Slack, and SFTP. Subscribe to payment events and settlement reports for merchants and partners.

online

Recurring Payments

Implement subscription billing and recurring charges using tokenization, recurring payment configuration, and Merchant Initiated Transactions.

online

Void a Payment

Reverse a completed payment before settlement. Voiding stops funds from transferring to the merchant's account, avoiding incorrect transactions.

in-store

Receipts

Generate, email, print, and customise receipts for in-store transactions using the Surfboard Receipts API.

online

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.

online

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.

in-store

Tips Configuration

Configure tipping on Surfboard payment terminals at the merchant, store, or terminal level using a hierarchical override model.

in-store

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.

online

Partial Payments

Split an order across multiple payment methods or transactions. Accept card, cash, and Swish in any combination to settle a single order.

in-store

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.

online

Store Management

Create, update, verify, and manage in-store and online stores using the Surfboard Payments Store APIs.

online

Gift Cards & Promotions

Issue and manage gift cards, track transactions, and create marketing promotions using the Surfboard Payments APIs.

online

Product Catalog

Create and manage product catalogs, products, variants, inventory levels, and analytics through the Catalog API.

online

Settlements & Reporting

Retrieve settlement reports, view adjustments, manage merchant charges, and register customer profiles for reconciliation and billing.

online

Account & Service Provider Management

Create merchant and partner accounts, manage user roles, register service providers, and configure external notifications via the Surfboard API.

online

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.

online

Client Auth Tokens

Generate client-side authentication tokens for secure API access from browsers and mobile apps without exposing your API key or secret.

online

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.

Create Sandbox Account All Guides