Payment Page - Surfboard Payments

Overview

The Payment Page is the simplest way to accept online payments with Surfboard. Instead of building your own checkout form, you redirect customers to a Surfboard-hosted payment page. The customer completes payment there and is redirected back to your site.

This approach requires minimal frontend work — you only need to create an order via the API and redirect the customer to the returned payment link.

Prerequisites

Before accepting payments with the Payment Page:

Create a developer account at the Developer Portal
Complete onboarding (merchant and store setup)
Register a terminal with the type set to PaymentPage

Payment Types

There are two primary types of payments:

Customer Initiated Transaction (CIT): Transactions initiated by customers on your webshop, such as e-commerce purchases.
Merchant Initiated Transaction (MIT): Transactions initiated by the merchant, such as subscription charges.

Note: MIT payments can only be processed by terminals set to MerchantInitiated. See the Server-to-Server API guide for details on MIT.

Payment Process

Step 1: Create an Order

Create an order using the Create Order API. On success, you receive a payment link to share with the customer.

POST /merchants/:merchantId/orders
{
  "terminal$id": "YOUR_TERMINAL_ID",
  "orderLines": [
    {
      "id": "ITEM-001",
      "name": "Annual Subscription",
      "quantity": 1,
      "amount": {
        "total": 99900,
        "currency": "752"
      }
    }
  ],
  "controlFunctions": {
    "initiatePaymentsOptions": {
      "paymentMethod": "CARD",
      "amount": 99900
    }
  }
}

Control Fields

The Payment Page supports additional control fields for fine-grained payment control:

Field	Description
`delayCapture`	Set to `true` to capture payment later after authorisation. Default: `false`.
`enforceTokenization`	Override tokenisation config — control whether the card is saved for future use.
`enforce3DSecure`	Whether the customer goes through 3D Secure verification.
`paymentPageValidFor`	How long the payment link is valid. Default: one day.
`lockToPaymentMethod`	Force the customer to use a specific payment method.
`authMode`	`PREAUTH` or `AUTH`. Default: `AUTH`. If `PREAUTH`, `delayCapture` is set to `true` automatically.
`redirectUrl`	URL to redirect to after successful payment. Includes `orderId` as a query param.
`failureRedirectUrl`	URL to redirect to after failed payment. Includes `orderId` as a query param.
`generateShortLink`	Set to `true` to get a shortened payment URL. Default: `false`.

Recurring Payment Fields

For subscription-based payments, include these additional fields:

Field	Description
`subscriptionAmountType`	`FIXED` or `VARIABLE`
`maxAmount`	Maximum amount in minor units (for variable subscriptions)
`frequency`	`daily`, `weekly`, `monthly`, `quarterly`, `annually`, `unscheduled`, etc.
`numberOfPayments`	Total expected payments for this subscription
`uniqueReference`	Unique reference for the recurring order

Step 2: Check Order Status

Monitor the order status using the Fetch Order Status API. When the status changes to PAYMENT_COMPLETED or PAYMENT_CANCELLED, you can view the transaction details.

You can also receive real-time updates via webhook notifications — configure them in the Developer Portal Console.

Integration Flow

Here is the typical integration flow:

Customer clicks “Pay” on your website
Your backend calls the Create Order API
You redirect the customer to the paymentUrl from the response
Customer completes payment on the Surfboard-hosted page
Customer is redirected to your redirectUrl (or failureRedirectUrl)
Your backend verifies the order status via the API or webhook

Tip: Always verify the order status server-side after redirect. Do not rely solely on the redirect URL to confirm payment success.

Reference

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.

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.

Overview

Prerequisites

Payment Types

Payment Process

Step 1: Create an Order

Control Fields

Recurring Payment Fields

Step 2: Check Order Status

Integration Flow

Reference

Other Guides

Ready to get started?