Account & Service Provider Management
Create merchant and partner accounts, manage user roles, register service providers, and configure external notifications via the Surfboard API.
Overview
The Surfboard API provides administrative endpoints for managing accounts, service providers, and notification subscriptions. With these APIs you can:
- Create user accounts for merchants and partners with role-based access control
- Register service providers under a partner and track their onboarding lifecycle
- Query service providers linked to a merchant or partner
- Subscribe to notifications for automated report delivery via email, Slack, or SFTP
User Accounts & Roles
Every account is assigned a role that controls access. The role field is optional when creating accounts.
| Role | Description |
|---|---|
SUPER_ADMIN | Full access to all features and settings. Typically the account owner. |
ADMIN | Can manage resources, invite users, and configure integrations. |
USER | Read access with limited operational permissions. |
Create a Merchant Account
POST /merchants/{merchantId}/accounts{ "email": "admin@merchant.com", "role": "ADMIN" }| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address. An invitation is sent to this address. |
role | string | No | SUPER_ADMIN, ADMIN, or USER. Defaults if omitted. |
Returns { "status": "SUCCESS", "message": "..." } on success.
Create a Partner Account
Uses the same request body and response format, scoped to the partner:
POST /partners/{partnerId}/accounts{ "email": "admin@partner.com", "role": "ADMIN" }Service Provider Management
Service providers are third-party entities that participate in transaction processing, revenue sharing, or value-added services. Partners register them, track onboarding, and query them at both partner and merchant level.
Register a Service Provider
Submit a new application. The response includes an applicationId and a webKybUrl for KYB verification.
POST /partners/{partnerId}/service-providers{
"country": "SE",
"organisation": { "corporateId": "3532007322" },
"controlFields": { "isServiceProvider": true }
}| Parameter | Type | Required | Description |
|---|---|---|---|
country | string | Yes | Two-letter ISO country code (e.g., SE, NO, DK). |
organisation.corporateId | string | Yes | Corporate identification number. |
controlFields.isServiceProvider | boolean | Yes | Must be true. |
Response:
{
"status": "SUCCESS",
"data": {
"applicationId": "app-abc123",
"webKybUrl": "https://kyb.surfboardpayments.com/application/app-abc123"
},
"message": "Service provider application created"
}Share the webKybUrl with the service provider so they can complete KYB.
List All Applications
Retrieve all service provider applications, optionally filtered by lifecycle stage.
GET /partners/{partnerId}/service-providers/applications?applicationType=ONBOARDING| Query Parameter | Type | Description |
|---|---|---|
applicationType | string | ONBOARDING, RENEWAL, or ONBOARDING,RENEWAL. Defaults to ONBOARDING. |
Response returns an array of application objects:
{
"status": "SUCCESS",
"data": [{
"applicationId": "app-abc123",
"country": "SE",
"corporateId": "3532007322",
"applicationStatus": "APPLICATION_SUBMITTED",
"createdAt": "2025-06-15T10:30:00Z",
"lastUpdatedAt": "2025-06-16T08:00:00Z",
"legalName": "Acme Services AB"
}]
}Check Application Status
GET /partners/{partnerId}/service-providers/applications/{applicationId}{
"status": "SUCCESS",
"data": {
"onboardingStatus": "COMPLETED",
"applicationStatus": "MERCHANT_CREATED",
"serviceProviderId": "sp-789xyz"
}
}The serviceProviderId is null while pending and populated once approved.
Fetch Service Providers for a Partner
GET /partners/{partnerId}/service-providers{
"status": "SUCCESS",
"data": {
"serviceProviders": [{
"serviceProviderId": "sp-789xyz",
"corporateId": "3532007322",
"name": "Acme Services AB",
"email": "contact@acmeservices.com",
"address": { "addressLine1": "Birger Jarlsgatan 10", "city": "Stockholm", "countryCode": "SE", "postalCode": "114 34" },
"phoneNumber": { "code": "46", "number": "812345678" }
}]
}
}Fetch Service Providers for a Merchant
Same response structure as above, scoped to the merchant: GET /merchants/{merchantId}/service-providers
External Notifications
Subscribe to automated event reports delivered via email, Slack, or SFTP. At least one channel is required per subscription.
Subscribe to Reports
POST /merchants/{merchantId}/notifications/reports
POST /partners/{partnerId}/notifications/reports{
"event": "DAILY_FILE_TRANSFER",
"email": "finance@merchant.com",
"slackUrl": "https://hooks.slack.com/services/T00/B00/xxx",
"sftpInfo": {
"host": "sftp.merchant.com",
"user": "surfboard-reports",
"port": 22,
"remoteDirectory": "/reports/daily",
"separator": ","
}
}Response returns a notificationId per channel. For SFTP, a publicKey is included — add it to your server’s authorized keys.
{
"status": "SUCCESS",
"data": [
{ "notificationId": "notif-001", "NotificationChannel": "EMAIL" },
{ "notificationId": "notif-002", "NotificationChannel": "SLACK" },
{ "notificationId": "notif-003", "NotificationChannel": "SFTP", "publicKey": "ssh-rsa AAAA..." }
]
}Fetch Existing Notifications
Retrieve configured subscriptions with optional filters (event, notificationChannel, notificationId):
GET /merchants/{merchantId}/notifications
GET /partners/{partnerId}/notificationsUnsubscribe
Remove a subscription by its ID:
DELETE /merchants/{merchantId}/notifications/{notificationId}
DELETE /partners/{partnerId}/notifications/{notificationId}Returns { "status": "SUCCESS", "message": "..." } on success.
API Quick Reference
| Operation | Method | Endpoint |
|---|---|---|
| Create merchant account | POST | /merchants/{merchantId}/accounts |
| Create partner account | POST | /partners/{partnerId}/accounts |
| Register service provider | POST | /partners/{partnerId}/service-providers |
| List SP applications | GET | /partners/{partnerId}/service-providers/applications |
| Check SP application status | GET | /partners/{partnerId}/service-providers/applications/{applicationId} |
| Fetch SPs for partner | GET | /partners/{partnerId}/service-providers |
| Fetch SPs for merchant | GET | /merchants/{merchantId}/service-providers |
| Subscribe merchant reports | POST | /merchants/{merchantId}/notifications/reports |
| Subscribe partner reports | POST | /partners/{partnerId}/notifications/reports |
| Fetch merchant notifications | GET | /merchants/{merchantId}/notifications |
| Fetch partner notifications | GET | /partners/{partnerId}/notifications |
| Unsubscribe merchant | DELETE | /merchants/{merchantId}/notifications/{notificationId} |
| Unsubscribe partner | DELETE | /partners/{partnerId}/notifications/{notificationId} |
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 & Notifications
Receive real-time event notifications via webhooks, email, Slack, and SFTP. Subscribe to payment events and settlement reports 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.
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.