Store Management

Overview

Stores are the organizational units that sit beneath merchants in the Surfboard hierarchy. Every terminal, whether physical or online, is registered under a store. This guide covers the full store lifecycle: creating in-store and online stores, retrieving store details, updating store information, verifying domains for online payments, listing terminals, and deactivating stores you no longer need.

A default store is often created automatically during merchant onboarding. Both merchants and partners can create additional stores at any time through the API or the Partner Portal.

Prerequisites

• A registered partner and merchant in the Surfboard system
• Your partnerId and merchantId
• API credentials (API key and API secret)

Create an In-Store (Physical) Store

Use the Create Store endpoint to add a new physical store under a merchant. The store will be assigned a unique storeId on creation.

POST /partners/:partnerId/merchants/:merchantId/stores

Request

{
  "storeName": "Stockholm Flagship",
  "email": "flagship@example.com",
  "phoneNumber": {
    "code": 46,
    "number": "701234567"
  },
  "address": "Drottninggatan 10",
  "city": "Stockholm",
  "zipCode": "103 16",
  "country": "SE"
}

Key Request Parameters

Parameter	Type	Required	Description
storeName	string	Yes	Name of the store
email	string	No	Store email. Mandatory for online payment support
phoneNumber.code	number	Yes	International dialing code (e.g., 46 for Sweden)
phoneNumber.number	string	Yes	Phone number, 5-15 digits
address	string	Yes	Address line 1
city	string	Yes	City name
zipCode	string	Yes	Postal code
country	string	Yes	Two-letter ISO country code (e.g., SE)
acquirerMID	string	No	Acquirer Merchant ID, required for PF partners with store-based acquiring

Response

The response includes the new storeId along with the full store object:

{
  "status": "SUCCESS",
  "data": {
    "storeId": "store-abc-123",
    "merchantId": "merchant-xyz-789",
    "name": "Stockholm Flagship",
    "address": {
      "addressLine1": "Drottninggatan 10",
      "city": "Stockholm",
      "countryCode": "SE",
      "postalCode": "103 16"
    },
    "phone": "+46701234567",
    "email": "flagship@example.com"
  },
  "message": "Store created successfully"
}

Create an Online Store

Online stores require additional properties in the onlineInfo object to enable e-commerce payment acceptance. You can either create a new online store directly or update an existing physical store to add online capabilities.

POST /partners/:partnerId/merchants/:merchantId/stores

Request

{
  "storeName": "Web Store",
  "email": "webstore@example.com",
  "phoneNumber": {
    "code": 46,
    "number": "701234567"
  },
  "address": "Drottninggatan 10",
  "city": "Stockholm",
  "zipCode": "103 16",
  "country": "SE",
  "onlineInfo": {
    "merchantWebshopURL": "https://shop.example.com",
    "paymentPageHostURL": "https://shop.example.com/payment",
    "termsAndConditionsURL": "https://shop.example.com/terms",
    "privacyPolicyURL": "https://shop.example.com/privacy"
  }
}

Online Info Parameters

Parameter	Type	Required	Description
onlineInfo.merchantWebshopURL	string	Yes	The merchant’s webshop URL
onlineInfo.paymentPageHostURL	string	No	Payment page URL. Required for SDK mode integration
onlineInfo.termsAndConditionsURL	string	Yes	URL to terms and conditions (must include refund policy)
onlineInfo.privacyPolicyURL	string	Yes	URL to the privacy policy

When an online store is created, the response includes two domain verification keys:

• merchantURLDomainVerficationKey — used to verify ownership of the webshop domain
• paymentPageURLDomainVerficationKey — used to verify the payment page domain (if provided)

You must complete domain verification before the store is approved for online payments.

Domain Verification

After creating an online store, verify that you own the domains you provided. This is a two-step process: publish the verification key, then trigger the check.

Step 1: Publish the Verification Keys

The keys are returned when the store is created, and you can fetch them again at any time with Fetch Store Domains:

GET /partners/:partnerId/merchants/:merchantId/stores/:storeId/online

Each entry in domains carries the domain name to verify and its verificationKey. Publish each key in one of two ways.

Option A: DNS TXT record

Add the verification key as a TXT record in the domain’s DNS configuration.

Option B: HTTPS file

If you can serve pages on the domain but can’t edit its DNS, serve the key from a well-known file instead. This suits platforms that host a merchant’s custom domain while the DNS stays with the merchant’s own provider: you can publish the file for every merchant automatically, with no action from them.

Serve the file on the same host as the URL you registered on the store:

https://<your-domain>/.well-known/sb-domain-verification.txt

If the store’s URL is https://www.example.com, serve it at https://www.example.com/.well-known/sb-domain-verification.txt. Serving it on the root domain, https://example.com/.well-known/sb-domain-verification.txt, also works. You only need one of the two.

• The URL you serve it on must return 200 directly over HTTPS, with no redirect. If your root domain redirects to www, serve the file on the www host.
• Serve it as plain text (Content-Type: text/plain), not JSON.
• The body is the verification key with its sb-domain-verification-key= prefix.
• If the store has two keys (webshop and payment page) on the same domain, put both in the same file, one per line.

sb-domain-verification-key=7fd242dd862a9f9f74ae11d62216f5729a5e5600e00b8d44300db41b4efcce68

Check it before you trigger verification:

curl -i https://www.example.com/.well-known/sb-domain-verification.txt

The response should be 200 with content-type: text/plain and the key in the body.

Step 2: Trigger Verification

Surfboard checks pending domains automatically every 6 hours, through either method, so a store waiting for verification is picked up without further action once the record or file is live. To verify right away, call:

POST /partners/:partnerId/merchants/:merchantId/stores/:storeId/verify

{
  "domainType": "MERCHANT_WEBSHOP_URL"
}

The domainType value specifies which domain to verify. Use MERCHANT_WEBSHOP_URL for the webshop domain or PAYMENT_PAGE_HOST_URL for the payment page domain.

Check Verification Status

You can retrieve the current domain verification status at any time:

GET /partners/:partnerId/merchants/:merchantId/stores/:storeId/online

Once verification succeeds, the store enters an internal approval process. After approval, the store can take online payments.

Default Online Terminals

Creating an online store provisions two online terminals automatically: a PaymentPage terminal, used for payment links and hosted checkout, and a MerchantInitiated terminal, used for backend charges against a stored token. You do not register either one — list the store’s terminals to pick up their IDs. They exist as soon as the store does, but cannot take a payment until the domains verify and the store is approved.

SelfHostedPage and iFrame terminals are not provisioned. Register those with the Register Online Terminal endpoint when you need them:

POST /merchants/:merchantId/stores/:storeId/online-terminals

{
  "onlineTerminalMode": "SelfHostedPage"
}

Fetch Store Details

Retrieve complete information about a specific store, including its status and online onboarding status.

GET /partners/:partnerId/merchants/:merchantId/stores/:storeId

Response

{
  "status": "SUCCESS",
  "data": {
    "storeId": "store-abc-123",
    "merchantId": "merchant-xyz-789",
    "name": "Web Store",
    "status": "ACTIVE",
    "onlineOnboardingStatus": "APPROVED",
    "address": {
      "addressLine1": "Drottninggatan 10",
      "city": "Stockholm",
      "countryCode": "SE",
      "postalCode": "103 16"
    },
    "phone": "+46701234567",
    "email": "webstore@example.com",
    "onlineInfo": {
      "merchantWebshopURL": "https://shop.example.com",
      "paymentPageHostURL": "https://shop.example.com/payment",
      "termsAndConditionsURL": "https://shop.example.com/terms",
      "privacyPolicyURL": "https://shop.example.com/privacy"
    }
  },
  "message": "Store details fetched successfully"
}

Store status values: ACTIVE, DEACTIVATED, BLOCKED, INACTIVE. Online onboarding status values: APPROVED, INITIATED, FAILED.

List All Stores

Retrieve every store registered under a merchant to get a complete overview.

GET /partners/:partnerId/merchants/:merchantId/stores

The response returns an array of store objects, each with the same structure as the single-store response above.

Update Store Details

Modify an existing store’s name, contact information, address, or add online capabilities. Send only the fields you want to change.

PUT /partners/:partnerId/merchants/:merchantId/stores/:storeId

Request

{
  "storeName": "Stockholm Flagship - Updated",
  "email": "new-email@example.com",
  "phoneNumber": {
    "code": 46,
    "number": "709876543"
  }
}

All parameters are optional. You can also add onlineInfo to convert a physical store into an online store. Note that online info can only be added once.

If you add onlineInfo during an update, the response will include the domain verification keys, and you must complete domain verification as described above.

Fetch Store Terminals

Retrieve all terminals registered under a specific store. You can optionally filter by terminal type.

GET /partners/:partnerId/merchants/:merchantId/stores/:storeId/terminals

Optional query parameter: terminalType (e.g., surfpad, PaymentPage, SelfHostedPage, MerchantInitiated).

Response

{
  "status": "SUCCESS",
  "data": [
    {
      "terminalId": "terminal-001",
      "terminalType": "PaymentPage",
      "terminalStatus": "ACTIVE",
      "storeId": "store-abc-123",
      "terminalName": "Online Checkout",
      "startDate": "2025-06-15T10:00:00Z"
    },
    {
      "terminalId": "terminal-002",
      "terminalType": "MerchantInitiated",
      "terminalStatus": "ACTIVE",
      "storeId": "store-abc-123",
      "startDate": "2025-06-15T10:00:00Z"
    }
  ],
  "message": "Terminals fetched successfully"
}

This is the call that hands you the IDs of the PaymentPage and MerchantInitiated terminals an online store comes with. An online store returns both from the moment it is created, alongside any physical or SDK terminals you registered yourself.

Terminal types include: surfpad, surftouch, surfprint, checkoutPro, checkoutX, PaymentPage, SelfHostedPage, MerchantInitiated, printer, surftester.

Terminal statuses: REGISTERED, ACTIVE, IN_ACTIVE, DE_REGISTERED.

Deactivate a Store

Remove a store that is no longer needed. You can deactivate immediately or schedule deactivation for a future date.

DELETE /partners/:partnerId/merchants/:merchantId/stores/:storeId

Optional query parameter: deactivationDate in yyyy-mm-dd format. If omitted, the store is deactivated immediately.

Important: A store can only be deactivated if it has no terminals registered to it. If active terminals exist, you must first delink them or move them to another store under the same merchant. Remember that an online store carries its two default terminals, PaymentPage and MerchantInitiated, so the terminal list is never empty by default — deactivate those before you deactivate the store.

Response

{
  "status": "SUCCESS",
  "message": "Store deactivated successfully"
}

API Quick Reference

Operation	Method	Endpoint
Create store	POST	/partners/:partnerId/merchants/:merchantId/stores
Fetch store details	GET	/partners/:partnerId/merchants/:merchantId/stores/:storeId
List all stores	GET	/partners/:partnerId/merchants/:merchantId/stores
Update store	PUT	/partners/:partnerId/merchants/:merchantId/stores/:storeId
Verify domain	POST	/partners/:partnerId/merchants/:merchantId/stores/:storeId/verify
Fetch domain status	GET	/partners/:partnerId/merchants/:merchantId/stores/:storeId/online
Fetch store terminals	GET	/partners/:partnerId/merchants/:merchantId/stores/:storeId/terminals
Deactivate store	DELETE	/partners/:partnerId/merchants/:merchantId/stores/:storeId