{ "totalEndpoints": 237, "lastUpdated": "2026-09-04", "apis": [ "AI API", "Adjustments API", "Admin Functions API", "Bin Ranges API", "Branding APIs", "Client Auth Tokens API", "Customers API", "Electronic Cash Register (ECR) V2 API", "Gift Cards API", "Logistics API", "Merchant Charge & Billing Plans", "Merchants API", "Notifications API", "Orders API", "Partners API", "Payment Methods API", "Payments API", "Product Catalog API", "Promotions API", "RFID API", "Receipts API", "Reporting APIs", "Service Providers API", "Stores API", "Templates API", "Terminals API", "Tips APIs", "Transactions API", "Webhooks API" ], "endpoints": [ { "title": "Fetch Billing Plan by ID", "slug": "billing-fetch-billing-plan-by-id", "description": "Fetches detailed information for a specific billing plan using its ID.", "api": "Merchant Charge & Billing Plans", "method": "GET", "path": "/partners/:partnerId/billing-plans/:id", "content": "# Fetch Billing Plan by ID\n\n## Overview\nFetches detailed information for a specific billing plan using its ID.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `id` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/billing-plans/:id\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `id` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/billing-plans/:id\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | Array containing the filtered billing plan details. |\n|     `billingPlanId` | `string` | Unique identifier for the billing plan. |\n|     `paymentMethod` | `string` | Payment method for which this plan applies. |\n|     `cardBrand` | `string` | Card brand for which this plan applies. |\n|     `terminalType` | `string` | Type of terminal for which this plan applies. |\n|     `planType` | `string` | Type of billing plan (FIXED, VARIABLE, or IC++). |\n|     `description` | `string` | Description of the billing plan. |\n|     `domesticDebitNonCommercial` | `number` | Percentage rate for domestic debit non-commercial transactions. |\n|     `domesticCreditNonCommercial` | `number` | Percentage rate for domestic credit non-commercial transactions. |\n|     `domesticDebitCommercial` | `number` | Percentage rate for domestic debit commercial transactions. |\n|     `domesticCreditCommercial` | `number` | Percentage rate for domestic credit commercial transactions. |\n|     `eeaDebitNonCommercial` | `number` | Percentage rate for EEA debit non-commercial transactions. |\n|     `eeaCreditNonCommercial` | `number` | Percentage rate for EEA credit non-commercial transactions. |\n|     `eeaDebitCommercial` | `number` | Percentage rate for EEA debit commercial transactions. |\n|     `eeaCreditCommercial` | `number` | Percentage rate for EEA credit commercial transactions. |\n|     `internationalDebitNonCommercial` | `number` | Percentage rate for international debit non-commercial transactions. |\n|     `internationalCreditNonCommercial` | `number` | Percentage rate for international credit non-commercial transactions. |\n|     `internationalDebitCommercial` | `number` | Percentage rate for international debit commercial transactions. |\n|     `internationalCreditCommercial` | `number` | Percentage rate for international credit commercial transactions. |\n|     `fixedPercentage` | `number` | Fixed percentage rate applied to transactions. |\n|     `fixedCost` | `number` | Fixed cost per transaction, in the smallest currency unit. |\n|     `minimumCeiling` | `number` | Minimum ceiling amount for transactions, in the smallest currency unit. |\n|     `vatPercentage` | `number` | VAT percentage applied to the billing plan. |\n|     `cardTypeFees` | `object` | Per-card-type rate overrides for the plan, keyed by card type. Empty when the plan has no per-card-type overrides. |\n|     `binRangeFees` | `array` | Rate overrides that apply to specific card BIN ranges. Empty when the plan has no BIN-range overrides. |\n| `message` | `string` | A message describing the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"billingPlanId\": \"PLAN_001\",\n \"paymentMethod\": \"CARD\",\n \"cardBrand\": \"VISA\",\n \"terminalType\": \"STANDARD\",\n \"planType\": \"FIXED\",\n \"description\": \"Standard billing plan\",\n \"domesticDebitNonCommercial\": 1.49,\n \"domesticCreditNonCommercial\": 1.59\n }\n ],\n \"message\": \"Billing plan retrieved successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to fetch billing plans for partner\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `id` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Partner Account", "slug": "admin-functions-create-partner-account", "description": "Create a new account for a partner with specified email and role permissions.", "api": "Admin Functions API", "method": "POST", "path": "/partners/:partnerId/accounts", "content": "# Create Partner Account\n\n## Overview\nCreate a new account for a partner with specified email and role permissions.\n\n## Prerequisites\n- Valid partner ID is required to create the account.\n- Authentication is required via `API-KEY` and `API-SECRET` headers.\n- The `API-KEY` and `API-SECRET` must be associated with an account that has sufficient privileges to create new partner accounts.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/accounts\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Query Parameters\nN/A\n\n### Request Body Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `email` | string | Yes | Email address for the new partner account. |\n| `role` | string | No | Role assigned to the account (e.g., ADMIN, SUPER_ADMIN, USER). If not provided, a default role might be assigned. |\n\n### Request Example\n```json\n{\n \"email\": \"admin@partner.com\",\n \"role\": \"ADMIN\"\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Initiate Signup sucessfull\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### TBD - Error Name\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"TBD\"\n}\n```\n**Description:** Error responses are TBD.\n\n## Notes\n- The `:partnerId` in the URL should be replaced with the actual ID of the partner for whom the account is being created.\n- Ensure that the email address provided is valid and accessible by the new partner account user.\n- If the `role` is not specified, a default role will be assigned to the new partner account. Check the system configuration for the default role value.\n\n---" }, { "title": "Create Token", "slug": "auth-create-token", "description": "Creates a token for a given externalUserID. The token must be passed via the authorization header as a bearer token in subsequent requests. ", "api": "Client Auth Tokens API", "method": "POST", "path": "/partners/:partnerId/token", "content": "# Create Token\n\n## Overview\nCreates a token for a given externalUserID. The token must be passed via the authorization header as a bearer token in subsequent requests.\n\n## Prerequisites\n- You need a valid `partnerId`.\n- Contact integrations@surfboard.se or via our Slack channel to get `providerId` and `providerCertificate` details.\n- You need a valid `API-KEY`, `API-SECRET` and `MERCHANT-ID`.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/token\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Request Body Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| providerId | string | Yes | Provider ID of the auth provider |\n| providerCertificate | string | Yes | Certificate of the auth provider |\n| externalUserId | string | Yes | ExternalUserId ID to be assigned to the user who requires auth token |\n| email | string | No | Email address of the user |\n\n### Request Example\n```json\n{\n \"providerId\": \"BB72CE2C-B160-4BFE-ACB9-3FC270260C33\",\n \"providerCertificate\": \"2c95c565604048d7998a034ccbd2fbb5\",\n \"externalUserId\": \"A8895CBBCC503F\"\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| data | object | Response data |\n| data.token | string | Auth Token that is valid for a given interval specified in validUntil |\n| data.validUntil | string | This provides the duration of the token in seconds. Once the expiry duration is reached, a new token needs to be fetched. It must be noted that Surfboard will change the duration of the token based on the running environment and its internal controls for fraud. |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"token\": \"4E306D4EDC9C48919671014D1125B61A4B12170F806F45D087ADD190A21869234F1D7D1D8A1547A0A38556739091BF09\",\n \"validUntil\": \"3600\"\n },\n \"message\": \"Auth token fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\nCurrently, no error responses are provided in the source JSON.\n*(Example Error Response Structure, adapt based on actual error scenarios)*\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid providerId\"\n}\n```\n**Description:** The `providerId` provided is not valid. Ensure the ID is correct and matches the value provided by Surfboard.\n\n## Notes\n- The generated token is restricted to perform calls limited to orders, payments and transactions.\n- Surfboard will change the duration of the token based on the running environment and its internal controls for fraud.\n---" }, { "title": "Fetch Adjustments", "slug": "adjustments-fetch-adjustments", "description": "Fetch all adjustments created under a merchant or store.", "api": "Adjustments API", "method": "GET", "path": "/adjustments/:id", "content": "# Fetch Adjustments\n\n## Overview\nFetch all adjustments created under a merchant or store. The `:id` in the URL supports both Merchant ID and Store ID. To fetch adjustments made under a certain date range, use `startDate` and `endDate` as query parameters.\n\n## Prerequisites\n- Valid API Key and Secret are required for authentication.\n- Merchant ID is required for identifying the merchant.\n- Ensure the specified Merchant ID or Store ID exists.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /adjustments/:id\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| Content-Type | application/json | No |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| startDate | string | Yes | Start date of the range in yyyy-mm-dd format. |\n| endDate | string | Yes | End date of the range in yyyy-mm-dd format. |\n\n### Request Example\n```json\n{\n \"startDate\": \"2023-01-01\",\n \"endDate\": \"2023-01-31\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| data | array | Response data containing adjustment information. |\n| data.adjustmentId | String | Adjustment ID of the adjustment. |\n| data.adjustmentType | String | Type of the adjustment. |\n| data.amount | String | Amount of the adjustment. |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": [\n\t\t{\n\t\t\t\"adjustmentId\": \"81efdbe975ebc800ff\",\n\t\t\t\"adjustmentType\": \"tips\",\n\t\t\t\"amount\": \"100\"\n\t\t}\n\t],\n\t\"message\": \"Adjustments fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Invalid Date Format\n```json\n{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Invalid date format\"\n}\n```\n**Description:** The `startDate` or `endDate` provided is not in the `yyyy-mm-dd` format. Ensure the date format is correct.\n\n#### 401 - Authentication Failed\n```json\n{\n\t\"status\": \"ERROR\",\n\t\"message\": \"Authentication failed\"\n}\n```\n**Description:** The API Key, API Secret or Merchant ID provided is incorrect or missing. Verify your authentication credentials.\n\n#### 404 - No Adjustments Found\n```json\n{\n\t\"status\": \"ERROR\",\n\t\"message\": \"No adjustments found\"\n}\n```\n**Description:** No adjustments were found for the specified Merchant ID/Store ID and date range. Check the provided IDs and date range for accuracy.\n\n## Notes\nThis endpoint supports pagination.\nThe `:id` parameter in the URL accepts both Merchant ID and Store ID.\n\n---" }, { "title": "Generate Branding Options", "slug": "ai-generate-branding-options", "description": "Generate AI-powered branding options and color schemes based on a website URL. Use this API to automatically create cohesive branding themes that match your business identity and enhance your merchant portal appearance.", "api": "AI API", "method": "POST", "path": "/ai/branding", "content": "# Generate Branding Options\n\n## Overview\nGenerate AI-powered branding options and color schemes based on a website URL. Use this API to automatically create cohesive branding themes that match your business identity and enhance your merchant portal appearance.\n\n## Prerequisites\n- An active account with API access.\n- API key, API secret, and merchant ID.\n- The target website must be publicly accessible.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /ai/branding\n```\n\n### Headers\n| Header | Value | Required |\n|--------|-------|----------|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Request Body Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| url | string | Yes | Website URL to analyze for branding inspiration and color scheme generation. |\n\n### Request Example\n```json\n{\n\t\"url\": \"https://example-company.com\"\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| data | object | Response data containing generated branding options. |\n| data.options | array | Array of branding option sets with metadata. |\n| data.options[].brandingOptions | array | Array of branding configuration options. |\n| data.options[].brandingOptions[].backgroundColor | string | Hex color code for the background color. |\n| data.options[].brandingOptions[].brandColor | string | Hex color code for the primary brand color. |\n| data.options[].brandingOptions[].accentColor | string | Hex color code for accent elements. |\n| data.options[].brandingOptions[].rectShape | string | Shape style for rectangular elements (e.g., 'rounded', 'square'). |\n| data.options[].brandingOptions[].fontType | string | Font family type for text elements (e.g., 'mono', 'serif', 'sans-serif'). |\n| data.options[].brandingOptions[].logoUrl | string | URL of the generated or suggested logo image. |\n| data.options[].brandingOptions[].iconUrl | string | URL of the generated or suggested icon image. |\n| data.options[].brandingOptions[].footerColor | string | Hex color code for footer elements. |\n| data.options[].metadata | object | Metadata about the AI generation process. |\n| data.options[].metadata.inputTokens | number | Number of input tokens used in the AI generation. |\n| data.options[].metadata.outputTokens | number | Number of output tokens generated by the AI. |\n| data.options[].metadata.outputType | string | Type of output generated (e.g., 'text', 'image'). |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": {\n\t\t\"options\": [\n\t\t\t{\n\t\t\t\t\"brandingOptions\": [\n\t\t\t\t\t{\n\t\t\t\t\t\t\"backgroundColor\": \"#FDFDFF\",\n\t\t\t\t\t\t\"brandColor\": \"#38488F\",\n\t\t\t\t\t\t\"accentColor\": \"#38488F\",\n\t\t\t\t\t\t\"rectShape\": \"rounded\",\n\t\t\t\t\t\t\"fontType\": \"mono\",\n\t\t\t\t\t\t\"logoUrl\": \"\",\n\t\t\t\t\t\t\"iconUrl\": \"\",\n\t\t\t\t\t\t\"footerColor\": \"#F0F0F2\"\n\t\t\t\t\t}\n\t\t\t\t],\n\t\t\t\t\"metadata\": {\n\t\t\t\t\t\"inputTokens\": 1043,\n\t\t\t\t\t\"outputTokens\": 85,\n\t\t\t\t\t\"outputType\": \"text\"\n\t\t\t\t}\n\t\t\t}\n\t\t]\n\t},\n\t\"message\": \"Branding generated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid URL provided.\"\n}\n```\n**Description:** The provided URL is malformed or not a valid website address. Ensure the URL is correctly formatted and accessible.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"AI generation failed due to an internal server error.\"\n}\n```\n**Description:** The AI service encountered an unexpected error during branding generation. Retry the request later. If the problem persists, contact support.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid API key, secret or merchant ID.\"\n}\n```\n**Description:** The API key, API secret, or merchant ID provided in the request headers are invalid or missing. Ensure that you have provided valid credentials in the request headers.\n\n## Notes\n- The AI algorithm will analyze the provided website's content, design, and color scheme to generate relevant branding options.\n- The quality of the generated branding depends on the complexity and richness of the website's visual elements.\n- LogoUrl and IconUrl might be empty strings when no appropriate image are found from the provided Url.\n\n---" }, { "title": "Create Billing Plans", "slug": "billing-create-billing-plans", "description": "Creates new billing plans for a partner. Billing plans define pricing structures for different payment methods, card brands, and terminal types.", "api": "Merchant Charge & Billing Plans", "method": "POST", "path": "/partners/:partnerId/billing-plans", "content": "# Create Billing Plans\n\n## Overview\nCreates new billing plans for a partner. Billing plans define pricing structures for different payment methods, card brands, and terminal types.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/billing-plans\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `plans` | `array` | Yes | Array of billing plan objects to create. |\n|     `id` | `string` | Yes | Unique identifier for the billing plan. |\n|     `cardBrand` | `string` | No | Card brand this plan's rates apply to. Leave unset to apply the plan across all supported brands. Possible values: `AMEX`, `DISCOVER`, `MASTERCARD`, `VISA`, `VISA_MC`. |\n|     `terminalType` | `string` | Yes | The kind of terminal this plan prices. Possible values: `STANDARD`, `SOFTPOS`, `ONLINE`. |\n|     `paymentMethod` | `string` | Yes | The payment method this plan prices. Possible values: `ACCTOACC`, `B2BINV`, `CARD`, `DCC_INSTORE`, `EPASSI`, `KLARNA`, `MOBILEPAY`, `SWISH`, `VIPPS`. |\n|     `planType` | `string` | Yes | How this plan prices transactions. Possible values: `FIXED`, `VARIABLE`, `IC++`. |\n|     `description` | `string` | Yes | Description of the billing plan. |\n|     `domesticDebitNonCommercial` | `number` | No | Percentage rate for domestic debit non-commercial transactions. |\n|     `domesticCreditNonCommercial` | `number` | No | Percentage rate for domestic credit non-commercial transactions. |\n|     `domesticDebitCommercial` | `number` | No | Percentage rate for domestic debit commercial transactions. |\n|     `domesticCreditCommercial` | `number` | No | Percentage rate for domestic credit commercial transactions. |\n|     `eeaDebitNonCommercial` | `number` | No | Percentage rate for EEA debit non-commercial transactions. |\n|     `eeaCreditNonCommercial` | `number` | No | Percentage rate for EEA credit non-commercial transactions. |\n|     `eeaDebitCommercial` | `number` | No | Percentage rate for EEA debit commercial transactions. |\n|     `eeaCreditCommercial` | `number` | No | Percentage rate for EEA credit commercial transactions. |\n|     `internationalDebitNonCommercial` | `number` | No | Percentage rate for international debit non-commercial transactions. |\n|     `internationalCreditNonCommercial` | `number` | No | Percentage rate for international credit non-commercial transactions. |\n|     `internationalDebitCommercial` | `number` | No | Percentage rate for international debit commercial transactions. |\n|     `internationalCreditCommercial` | `number` | No | Percentage rate for international credit commercial transactions. |\n|     `minimumCeiling` | `number` | No | Minimum ceiling amount for transactions. |\n|     `fixedCost` | `number` | No | Fixed cost amount per transaction. |\n|     `fixedPercentage` | `number` | No | Fixed percentage rate applied to transactions. |\n|     `vatPercentage` | `number` | No | VAT percentage applied to the billing plan. |\n|     `cardTypeFees` | `object` | No | Per-card-type rate overrides, keyed by card type. Each override may set fixedPercentage (0-100), fixedCost (smallest currency unit), and minimumCeiling (smallest currency unit). Use this to price specific card types differently from the plan's default rates. |\n|     `binRangeFees` | `array` | No | Rate overrides that apply only to card BIN ranges, letting you price specific issuing ranges differently from the plan's default rates. |\n\n### Request Example\n```json\n{\n \"plans\": [\n {\n \"id\": \"SP_NOK7\",\n \"paymentMethod\": \"CARD\",\n \"cardBrand\": \"DISCOVER\",\n \"terminalType\": \"STANDARD\",\n \"planType\": \"FIXED\",\n \"description\": \"Testing 2024\",\n \"fixedPercentage\": 13.4\n }\n ]\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Indicates if the request was 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message describing the outcome of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Billing plans created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to create billing plans\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Enhance Image", "slug": "ai-enhance-image", "description": "Enhance product images using AI-powered image processing. This API takes a product image URL and generates enhanced versions of the image. Choose between STANDARD mode for basic enhancements or SCENE mode for contextual scene generation.", "api": "AI API", "method": "POST", "path": "/ai/enhance-image", "content": "# Enhance Image\n\n## Overview\nEnhance product images using AI-powered image processing. This API takes a product image URL and generates enhanced versions of the image. Choose between STANDARD mode for basic enhancements or SCENE mode for contextual scene generation.\n\n## Prerequisites\n- A valid product image URL\n- An active account with access to the AI API.\n- Authentication via API Key, API Secret and Merchant ID\n- Ensure the image URL is publicly accessible.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /ai/enhance-image\n```\n\n### Headers\n| Header | Value | Required |\n|--------|-------|----------|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Request Body Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| productName | string | Yes | Name of the product to provide context for image enhancement. |\n| url | string | Yes | URL of the product image to be enhanced. |\n| mode | string | Yes | Enhancement mode to apply to the image. Possible values: `STANDARD`, `SCENE`. |\n\n### Request Example\n```json\n{\n\t\"productName\": \"Wireless Bluetooth Headphones\",\n\t\"url\": \"https://example.com/images/product-12345.jpg\",\n\t\"mode\": \"STANDARD\"\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| data | object | Response data containing enhanced image URLs. |\n| data.imageUrls | array | Array of URLs pointing to the enhanced product images. |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": {\n\t\t\"imageUrls\": [\n\t\t\t\"https://cdn.example.com/enhanced/image-abc123-v1.jpg\",\n\t\t\t\"https://cdn.example.com/enhanced/image-abc123-v2.jpg\",\n\t\t\t\"https://cdn.example.com/enhanced/image-abc123-v3.jpg\"\n\t\t]\n\t},\n\t\"message\": \"Image enhanced successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Invalid Request\n```json\n{\n \"status\": \"ERROR\",\n \"data\": null,\n \"message\": \"Invalid request parameters. Please check your input.\"\n}\n```\n**Description:** This error occurs when the request body is malformed or missing required parameters. Ensure all required parameters are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"data\": null,\n \"message\": \"Invalid API key or secret.\"\n}\n```\n**Description:** This error occurs when the provided API key or secret are invalid or do not have sufficient permissions. Verify your API credentials and ensure they are correctly configured.\n\n#### 404 - Image Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"data\": null,\n \"message\": \"Image not found at the provided URL.\"\n}\n```\n**Description:** The provided image URL could not be found. Ensure the URL is correct and the image is publicly accessible.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"data\": null,\n \"message\": \"An unexpected error occurred on the server.\"\n}\n```\n**Description:** This error indicates a server-side issue. Retry the request after a short delay. If the issue persists, contact support.\n\n## Notes\n- The API is rate limited. Please contact support for increasing the rate limit, if needed.\n- The processing time may vary depending on the image complexity and the selected mode.\n- Ensure the `url` parameter points to a valid and publicly accessible image. The image should be in a format compatible with standard web browsers (e.g., JPEG, PNG).\n- Selecting the `SCENE` mode will generate more computationally intensive results, so processing may take longer.\n---" }, { "title": "Create Merchant Charge", "slug": "billing-create-merchant-charge", "description": "Creates a new charge for a merchant. Partners can specify the charge details.", "api": "Merchant Charge & Billing Plans", "method": "POST", "path": "/partners/:partnerId/merchants/:merchantId/charges", "content": "# Create Merchant Charge\n\n## Overview\nCreates a new charge for a merchant. Partners can specify the charge details.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/merchants/:merchantId/charges\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `description` | `string` | Yes | A brief description of the charge. |\n| `currency` | `string` | Yes | Three-digit currency code |\n| `amount` | `number` | Yes | Charge amount in smallest currency units |\n| `vat` | `number` | No | Optional VAT amount. |\n| `billingDate` | `string` | No | Date on which the charge is effective, in yyyy-mm-dd format. |\n| `recurring` | `object` | No | If set, defines a recurring charge schedule including frequency and optional end date. |\n|     `frequency` | `string` | Yes | Specifies how frequently the charge will be billed. Possible values: `daily`, `twiceWeekly`, `weekly`, `tenDays`, `fortNightly`, `monthly`, `everyTwoMonths`, `trimester`, `quarterly`, `twiceYearly`, `annually`. |\n|     `billingEndDate` | `string` | No | Date in yyyy-mm-dd format specifying when to stop recurring charges. |\n\n### Request Example\n```json\n{\n \"description\": \"Fee\",\n \"currency\": \"752\",\n \"amount\": 5000000,\n \"vat\": 35,\n \"billingDate\": \"2025-02-11\",\n \"recurring\": {\n \"billingEndDate\": \"2025-02-12\",\n \"frequency\": \"daily\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Indicates if the request was 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data containing information about the created charge. |\n|     `chargeId` | `string` | Unique identifier for the newly created charge. |\n| `message` | `string` | A message describing the outcome of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"chargeId\": \"82eb21dbb4bcf80c46\"\n },\n \"message\": \"Merchant charge created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to create merchant charge for partner\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch All Merchant Charges", "slug": "billing-fetch-all-merchant-charges", "description": "Retrieves a list of all charges associated with a particular merchant. This includes both one-time and subscription-based charges.", "api": "Merchant Charge & Billing Plans", "method": "GET", "path": "/partners/:partnerId/merchants/:merchantId/charges", "content": "# Fetch All Merchant Charges\n\n## Overview\nRetrieves a list of all charges associated with a particular merchant. This includes both one-time and subscription-based charges.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants/:merchantId/charges\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/merchants/:merchantId/charges\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | An array of merchant charges. |\n|     `chargeId` | `string` | Unique identifier for the charge. |\n|     `subChargeId` | `string` | Identifier specifically tied to the sub-charge, usually the same as 'id' for single charges. |\n|     `merchantId` | `string` | The merchant ID to whom this charge applies. |\n|     `isSubscriptionCharge` | `boolean` | Indicates whether this charge is part of a subscription (recurring). |\n|     `description` | `string` | A brief text describing the charge. |\n|     `amount` | `number` | Charge amount in smallest currency units. |\n|     `vat` | `number` | VAT amount applied to this charge. |\n|     `status` | `string` | Current status of the charge, for example 'PENDING'. |\n|     `billingDate` | `string` | Date the charge is billed, in ISO 8601 format. |\n| `message` | `string` | A message describing the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"chargeId\": \"82ed1af7b38e080146\",\n \"subChargeId\": \"82ed1af7b38e080146\",\n \"merchantId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n \"isSubscriptionCharge\": true,\n \"description\": \"Fee\",\n \"amount\": 650000,\n \"vat\": 15,\n \"status\": \"PENDING\",\n \"billingDate\": \"2025-02-11T00:00:00.000Z\"\n },\n {\n \"chargeId\": \"82eb21dbb4bcf80c46\",\n \"subChargeId\": \"82ec36fee443f80f46\",\n \"merchantId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n \"isSubscriptionCharge\": true,\n \"description\": \"Fee\",\n \"amount\": 5000000,\n \"vat\": 35,\n \"status\": \"PENDING\",\n \"billingDate\": \"2025-02-09T00:00:00.000Z\"\n },\n {\n \"chargeId\": \"82eb21dbb4bcf80c46\",\n \"subChargeId\": \"82eb21dbb4bcf80c46\",\n \"merchantId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n \"isSubscriptionCharge\": true,\n \"description\": \"Fee\",\n \"amount\": 5000000,\n \"vat\": 35,\n \"status\": \"PENDING\",\n \"billingDate\": \"2025-02-08T00:00:00.000Z\"\n }\n ],\n \"message\": \"Merchant charges fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch merchant charges for partner.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Query Parameters for the supported paging parameters.\n\n---" }, { "title": "Create Merchant Account", "slug": "admin-functions-create-merchant-account", "description": "Create a new account for a merchant with specified email and role permissions.", "api": "Admin Functions API", "method": "POST", "path": "/merchants/:merchantId/accounts", "content": "# Create Merchant Account\n\n## Overview\nCreate a new account for a merchant with specified email and role permissions.\n\n## Prerequisites\n- A valid Merchant ID is required.\n- API Key and API Secret are needed for authentication.\n- The user must have administrative privileges to create merchant accounts.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /merchants/:merchantId/accounts\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Request Body Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| email | string | Yes | Email address for the new merchant account |\n| role | string | No | Role assigned to the account (e.g., ADMIN, SUPER_ADMIN, USER). Defaults to a standard user role if not provided. |\n\n### Request Example\n```json\n{\n \"email\": \"admin@merchant.com\",\n \"role\": \"ADMIN\"\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| message | string | A message that describes the status of the request |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Initiate Signup sucessfull\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid email format.\"\n}\n```\n**Description:** The email provided is not in a valid format. Ensure the email address is correctly formatted.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid API key or secret.\"\n}\n```\n**Description:** The API key or secret provided are incorrect or missing. Verify the API credentials.\n\n#### 403 - Forbidden\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Insufficient privileges to create merchant accounts.\"\n}\n```\n**Description:** The user does not have the necessary permissions to perform this action. Ensure the user has administrative privileges.\n\n#### 409 - Conflict\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Account with this email already exists.\"\n}\n```\n**Description:** An account with the provided email address already exists. Use a different email or reset the existing account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred on the server.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Contact support and provide details about the request.\n\n## Notes\n- The `role` parameter is optional. If not provided, the default user role will be assigned.\n- Ensure that the `MERCHANT-ID` in the header matches the merchant you are creating the account for.\n- Rate limiting may apply to this endpoint. Contact support for more details.\n\n---" }, { "title": "Fetch Billing Plans for Merchant", "slug": "billing-fetch-billing-plans-for-merchant", "description": "Retrieves billing plans specifically assigned to a merchant under a partner. This endpoint returns the billing plans that are applicable to the specified merchant.", "api": "Merchant Charge & Billing Plans", "method": "GET", "path": "/partners/:partnerId/merchants/:merchantId/plans", "content": "# Fetch Billing Plans for Merchant\n\n## Overview\nRetrieves billing plans specifically assigned to a merchant under a partner. This endpoint returns the billing plans that are applicable to the specified merchant.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants/:merchantId/plans\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/merchants/:merchantId/plans\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | Array of billing plan objects assigned to the merchant. |\n|     `billingPlanId` | `string` | Unique identifier for the billing plan. |\n|     `cardBrand` | `string` | Card brand for which this plan applies. |\n|     `terminalType` | `string` | Type of terminal for which this plan applies. |\n|     `paymentMethod` | `string` | Payment method for which this plan applies. |\n|     `planType` | `string` | Type of billing plan (FIXED or VARIABLE). |\n|     `description` | `string` | Description of the billing plan. |\n|     `domesticDebitNonCommercial` | `number` | Percentage rate for domestic debit non-commercial transactions. |\n|     `domesticCreditNonCommercial` | `number` | Percentage rate for domestic credit non-commercial transactions. |\n|     `domesticDebitCommercial` | `number` | Percentage rate for domestic debit commercial transactions. |\n|     `domesticCreditCommercial` | `number` | Percentage rate for domestic credit commercial transactions. |\n|     `eeaDebitNonCommercial` | `number` | Percentage rate for EEA debit non-commercial transactions. |\n|     `eeaCreditNonCommercial` | `number` | Percentage rate for EEA credit non-commercial transactions. |\n|     `eeaDebitCommercial` | `number` | Percentage rate for EEA debit commercial transactions. |\n|     `eeaCreditCommercial` | `number` | Percentage rate for EEA credit commercial transactions. |\n|     `internationalDebitNonCommercial` | `number` | Percentage rate for international debit non-commercial transactions. |\n|     `internationalCreditNonCommercial` | `number` | Percentage rate for international credit non-commercial transactions. |\n|     `internationalDebitCommercial` | `number` | Percentage rate for international debit commercial transactions. |\n|     `internationalCreditCommercial` | `number` | Percentage rate for international credit commercial transactions. |\n|     `minimumCeiling` | `number` | Minimum ceiling amount for transactions. |\n|     `fixedCost` | `number` | Fixed cost amount per transaction. |\n|     `fixedPercentage` | `number` | Fixed percentage rate applied to transactions. |\n|     `vatPercentage` | `number` | VAT percentage applied to the billing plan. |\n|     `cardTypeFees` | `object` | Per-card-type rate overrides for the plan, keyed by card type. Empty when the plan has no per-card-type overrides. |\n|     `binRangeFees` | `array` | Rate overrides that apply to specific card BIN ranges. Empty when the plan has no BIN-range overrides. |\n| `message` | `string` | A message describing the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"billingPlanId\": \"SP_SE_Fix119\",\n \"cardBrand\": \"VISA_MC\",\n \"terminalType\": \"STANDARD\",\n \"paymentMethod\": \"CARD\",\n \"planType\": \"FIXED\",\n \"description\": \"Billing Plan Description\",\n \"domesticDebitNonCommercial\": 1.19,\n \"domesticCreditNonCommercial\": 1.19,\n \"domesticDebitCommercial\": 1.19,\n \"domesticCreditCommercial\": 1.19,\n \"eeaDebitNonCommercial\": 1.19,\n \"eeaCreditNonCommercial\": 1.19,\n \"eeaDebitCommercial\": 1.19,\n \"eeaCreditCommercial\": 1.19,\n \"internationalDebitNonCommercial\": 1.19,\n \"internationalCreditNonCommercial\": 1.19,\n \"internationalDebitCommercial\": 1.19,\n \"internationalCreditCommercial\": 1.19,\n \"minimumCeiling\": 0.99,\n \"fixedCost\": 0,\n \"fixedPercentage\": 0,\n \"vatPercentage\": 0\n }\n ],\n \"message\": \"Billing plans for the merchant fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to fetch billing plans for merchant\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Billing Plans", "slug": "billing-fetch-billing-plans", "description": "Retrieves all billing plans associated with a partner. Returns detailed information about each plan including pricing structures for different transaction types. Supports pagination through page number headers.", "api": "Merchant Charge & Billing Plans", "method": "GET", "path": "/partners/:partnerId/billing-plans", "content": "# Fetch Billing Plans\n\n## Overview\nRetrieves all billing plans associated with a partner. Returns detailed information about each plan including pricing structures for different transaction types. Supports pagination through page number headers.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/billing-plans\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `x-page-number` | `1` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/billing-plans\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | Array of billing plan objects. |\n|     `billingPlanId` | `string` | Unique identifier for the billing plan. |\n|     `cardBrand` | `string` | Card brand for which this plan applies. |\n|     `terminalType` | `string` | Type of terminal for which this plan applies. |\n|     `paymentMethod` | `string` | Payment method for which this plan applies. |\n|     `planType` | `string` | Type of billing plan (FIXED or VARIABLE). |\n|     `description` | `string` | Description of the billing plan. |\n|     `domesticDebitNonCommercial` | `number` | Percentage rate for domestic debit non-commercial transactions. |\n|     `domesticCreditNonCommercial` | `number` | Percentage rate for domestic credit non-commercial transactions. |\n|     `domesticDebitCommercial` | `number` | Percentage rate for domestic debit commercial transactions. |\n|     `domesticCreditCommercial` | `number` | Percentage rate for domestic credit commercial transactions. |\n|     `eeaDebitNonCommercial` | `number` | Percentage rate for EEA debit non-commercial transactions. |\n|     `eeaCreditNonCommercial` | `number` | Percentage rate for EEA credit non-commercial transactions. |\n|     `eeaDebitCommercial` | `number` | Percentage rate for EEA debit commercial transactions. |\n|     `eeaCreditCommercial` | `number` | Percentage rate for EEA credit commercial transactions. |\n|     `internationalDebitNonCommercial` | `number` | Percentage rate for international debit non-commercial transactions. |\n|     `internationalCreditNonCommercial` | `number` | Percentage rate for international credit non-commercial transactions. |\n|     `internationalDebitCommercial` | `number` | Percentage rate for international debit commercial transactions. |\n|     `internationalCreditCommercial` | `number` | Percentage rate for international credit commercial transactions. |\n|     `minimumCeiling` | `number` | Minimum ceiling amount for transactions. |\n|     `fixedCost` | `number` | Fixed cost amount per transaction. |\n|     `fixedPercentage` | `number` | Fixed percentage rate applied to transactions. |\n|     `vatPercentage` | `number` | VAT percentage applied to the billing plan. |\n|     `cardTypeFees` | `object` | Per-card-type rate overrides for the plan, keyed by card type. Empty when the plan has no per-card-type overrides. |\n|     `binRangeFees` | `array` | Rate overrides that apply to specific card BIN ranges. Empty when the plan has no BIN-range overrides. |\n| `message` | `string` | A message describing the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"billingPlanId\": \"ANCN_POS_PREMIUM_PLUS\",\n \"cardBrand\": \"VISA_MC\",\n \"terminalType\": \"STANDARD\",\n \"paymentMethod\": \"CARD\",\n \"planType\": \"VARIABLE\",\n \"description\": \"Billing Plan Description\",\n \"domesticDebitNonCommercial\": 0.49,\n \"domesticCreditNonCommercial\": 0.59,\n \"domesticDebitCommercial\": 1.95,\n \"domesticCreditCommercial\": 1.95,\n \"eeaDebitNonCommercial\": 0.49,\n \"eeaCreditNonCommercial\": 0.59,\n \"eeaDebitCommercial\": 1.95,\n \"eeaCreditCommercial\": 1.95,\n \"internationalDebitNonCommercial\": 1.95,\n \"internationalCreditNonCommercial\": 1.95,\n \"internationalDebitCommercial\": 1.95,\n \"internationalCreditCommercial\": 1.95,\n \"minimumCeiling\": 0,\n \"fixedCost\": 0.12,\n \"fixedPercentage\": 0,\n \"vatPercentage\": 0\n },\n {\n \"billingPlanId\": \"P_DKKVK_V149M000F000\",\n \"cardBrand\": \"VISA_MC\",\n \"terminalType\": \"STANDARD\",\n \"paymentMethod\": \"CARD\",\n \"planType\": \"FIXED\",\n \"description\": \"Billing Plan Description\",\n \"domesticDebitNonCommercial\": 1.49,\n \"domesticCreditNonCommercial\": 1.49,\n \"domesticDebitCommercial\": 1.49,\n \"domesticCreditCommercial\": 1.49,\n \"eeaDebitNonCommercial\": 1.49,\n \"eeaCreditNonCommercial\": 1.49,\n \"eeaDebitCommercial\": 1.49,\n \"eeaCreditCommercial\": 1.49,\n \"internationalDebitNonCommercial\": 1.49,\n \"internationalCreditNonCommercial\": 1.49,\n \"internationalDebitCommercial\": 1.49,\n \"internationalCreditCommercial\": 1.49,\n \"minimumCeiling\": 0,\n \"fixedCost\": 0,\n \"fixedPercentage\": 0,\n \"vatPercentage\": 0\n }\n ],\n \"message\": \"Partner billing plans fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to fetch billing plans for partner\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Query Parameters for the supported paging parameters.\n\n---" }, { "title": "Fetch Merchant Charge by ID", "slug": "billing-fetch-merchant-charge-by-id", "description": "Retrieves detailed information about a specific merchant charge, including subscription details, amount, VAT, frequency, and any associated sub-charges.", "api": "Merchant Charge & Billing Plans", "method": "GET", "path": "/partners/:partnerId/merchants/:merchantId/charges/:chargeId", "content": "# Fetch Merchant Charge by ID\n\n## Overview\nRetrieves detailed information about a specific merchant charge, including subscription details, amount, VAT, frequency, and any associated sub-charges.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `chargeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants/:merchantId/charges/:chargeId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `chargeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/merchants/:merchantId/charges/:chargeId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| `data` | `object` | Response data containing details of the requested merchant charge |\n|     `chargeId` | `string` | Unique identifier of the charge. |\n|     `isSubscriptionCharge` | `boolean` | Specifies if this charge is subscription-based (recurring). |\n|     `description` | `string` | A short description of the charge. |\n|     `amount` | `number` | Charge amount in smallest currency units. |\n|     `vat` | `number` | The VAT amount applied to this charge. |\n|     `frequency` | `string` | Specifies how frequently the charge will be billed. Possible values: `daily`, `twiceWeekly`, `weekly`, `tenDays`, `fortNightly`, `monthly`, `everyTwoMonths`, `trimester`, `quarterly`, `twiceYearly`, `annually`, `unscheduled`. |\n|     `billingDate` | `string` | Date the charge is billed, in ISO 8601 format. |\n|     `billingStartDate` | `string` | Start date of the recurring charge in ISO 8601 format. |\n|     `billingEndDate` | `string` | End date of the recurring charge in ISO 8601 format. |\n|     `subCharges` | `array` | Array of sub-charges associated with this main charge. |\n|         `subChargeId` | `string` | Unique identifier for this sub-charge. |\n|         `description` | `string` | A short text describing the sub-charge. |\n|         `amount` | `number` | Charge amount in smallest currency units |\n|         `vat` | `number` | VAT amount for this sub-charge. |\n|         `status` | `string` | Current status of the sub-charge. |\n|         `billingDate` | `string` | Date when this sub-charge was billed, in ISO 8601 format. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"chargeId\": \"82eb21dbb4bcf80c46\",\n \"isSubscriptionCharge\": true,\n \"description\": \"Fee\",\n \"amount\": 5000000,\n \"vat\": 35,\n \"frequency\": \"daily\",\n \"billingStartDate\": \"2025-02-18T00:00:00.000Z\",\n \"billingEndDate\": \"2025-02-20T00:00:00.000Z\",\n \"subCharges\": [\n {\n \"subChargeId\": \"82f1a47a1f97000446\",\n \"description\": \"Fee\",\n \"amount\": 650000,\n \"vat\": 15,\n \"status\": \"PENDING\",\n \"billingDate\": \"2025-02-18T00:00:00.000Z\"\n }\n ]\n },\n \"message\": \"Merchant charge fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch details of the merchant charge for partner.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `chargeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Branding for Merchant", "slug": "branding-create-branding-for-merchant", "description": "Create a branding configuration for customizable pages at merchant level", "api": "Branding APIs", "method": "PATCH", "path": "/merchants/:merchantId/branding", "content": "# Create Branding for Merchant\n\n## Overview\nCreate a branding configuration for customizable pages at merchant level\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /merchants/:merchantId/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `backgroundColor` | `string` | No | Background color for the page. |\n| `brandColor` | `string` | No | Primary brand color for your page. |\n| `footerColor` | `string` | No | Footer's background color on the page. |\n| `accentColor` | `string` | No | This is a secondary color that complements your brand color. |\n| `rectShape` | `string` | No | Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'. Possible values: `ROUNDED`, `PILL`, `EDGY`. |\n| `fontType` | `string` | No | Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'. Possible values: `serif`, `sans-serif`, `mono`. |\n| `logoUrl` | `string` | No | Logo that will be displayed on the page. |\n| `iconUrl` | `string` | No | Icon that will be displayed on the page. |\n| `primaryCoverImage` | `string` | No | Primary cover image that will be displayed on the page. |\n| `secondaryCoverImage` | `string` | No | Secondary cover image that will be displayed on the page. |\n\n### Request Example\n```json\n{\n \"backgroundColor\": \"#667085\",\n \"brandColor\": \"#697085\",\n \"accentColor\": \"#787085\",\n \"rectShape\": \"ROUNDED\",\n \"fontType\": \"sans-serif\",\n \"logoUrl\": \"https://res.cloudinary.com/image/surfboard-icon.svg\",\n \"iconUrl\": \"https://res.cloudinary.com/image/surfboard-icon.svg\",\n \"footerColor\": \"#CD5C5B\",\n \"primaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"secondaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Branding configuration set successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Remove Billing Plan by ID", "slug": "billing-remove-billing-plan-by-id", "description": "Removes one or more billing plans by their IDs for a specific partner.", "api": "Merchant Charge & Billing Plans", "method": "DELETE", "path": "/partners/:partnerId/billing-plans/:id", "content": "# Remove Billing Plan by ID\n\n## Overview\nRemoves one or more billing plans by their IDs for a specific partner.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `id` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /partners/:partnerId/billing-plans/:id\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `id` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message describing the outcome of the removal operation. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Billing plans removed from the partner successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to remove billing plans\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `id` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Merchant Charge", "slug": "billing-update-merchant-charge", "description": "Updates an existing charge for a merchant. Partners can modify the amount, VAT, and optionally adjust the recurring settings.", "api": "Merchant Charge & Billing Plans", "method": "PUT", "path": "/partners/:partnerId/merchants/:merchantId/charges/:chargeId", "content": "# Update Merchant Charge\n\n## Overview\nUpdates an existing charge for a merchant. Partners can modify the amount, VAT, and optionally adjust the recurring settings.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `chargeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /partners/:partnerId/merchants/:merchantId/charges/:chargeId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `chargeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `amount` | `number` | Yes | Updated amount in minor currency units. |\n| `vat` | `number` | No | Optional updated VAT amount. |\n| `recurring` | `object` | No | Updated recurring schedule. Billing end date and updateType can be specified here. |\n|     `updateType` | `string` | Yes | Indicates the type of the update. Possible values: `onlyNext`, `lifeTime`, `current`. |\n|     `billingEndDate` | `string` | No | Date in yyyy-mm-dd format specifying the new end date for the recurring charge. |\n\n### Request Example\n```json\n{\n \"amount\": 650000,\n \"vat\": 15,\n \"recurring\": {\n \"updateType\": \"onlyNext\",\n \"billingEndDate\": \"2025-10-23\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Indicates if the request was 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message describing the outcome of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Updated merchant charge for partner successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to update merchant charge for partner\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `chargeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Branding for Partner", "slug": "branding-create-branding-for-partner", "description": "Create a branding configuration for customizable pages at partner level", "api": "Branding APIs", "method": "PATCH", "path": "/partners/:partnerId/branding", "content": "# Create Branding for Partner\n\n## Overview\nCreate a branding configuration for customizable pages at partner level\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /partners/:partnerId/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `backgroundColor` | `string` | No | Background color for the page. |\n| `brandColor` | `string` | No | Primary brand color for your page. |\n| `footerColor` | `string` | No | Footer's background color on the page. |\n| `accentColor` | `string` | No | This is a secondary color that complements your brand color. |\n| `rectShape` | `string` | No | Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'. Possible values: `ROUNDED`, `PILL`, `EDGY`. |\n| `fontType` | `string` | No | Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'. Possible values: `serif`, `sans-serif`, `mono`. |\n| `logoUrl` | `string` | No | Logo that will be displayed on the page. |\n| `iconUrl` | `string` | No | Icon that will be displayed on the page. |\n| `primaryCoverImage` | `string` | No | Primary cover image that will be displayed on the page. |\n| `secondaryCoverImage` | `string` | No | Secondary cover image that will be displayed on the page. |\n\n### Request Example\n```json\n{\n \"backgroundColor\": \"#667085\",\n \"brandColor\": \"#697085\",\n \"accentColor\": \"#787085\",\n \"rectShape\": \"ROUNDED\",\n \"fontType\": \"sans-serif\",\n \"logoUrl\": \"https://res.cloudinary.com/image/surfboard-icon.svg\",\n \"iconUrl\": \"https://res.cloudinary.com/image/surfboard-icon.svg\",\n \"footerColor\": \"#CD5C5B\",\n \"primaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"secondaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Branding configuration set successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Branding for Store", "slug": "branding-create-branding-for-store", "description": "Create a branding configuration for customizable pages at store level", "api": "Branding APIs", "method": "PATCH", "path": "/merchants/:merchantId/stores/:storeId/branding", "content": "# Create Branding for Store\n\n## Overview\nCreate a branding configuration for customizable pages at store level\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /merchants/:merchantId/stores/:storeId/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `backgroundColor` | `string` | No | Background color for the page. |\n| `brandColor` | `string` | No | Primary brand color for your page. |\n| `footerColor` | `string` | No | Footer's background color on the page. |\n| `accentColor` | `string` | No | This is a secondary color that complements your brand color. |\n| `rectShape` | `string` | No | Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'. Possible values: `ROUNDED`, `PILL`, `EDGY`. |\n| `fontType` | `string` | No | Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'. Possible values: `serif`, `sans-serif`, `mono`. |\n| `logoUrl` | `string` | No | Logo that will be displayed on the page. |\n| `iconUrl` | `string` | No | Icon that will be displayed on the page. |\n| `primaryCoverImage` | `string` | No | Primary cover image that will be displayed on the page. |\n| `secondaryCoverImage` | `string` | No | Secondary cover image that will be displayed on the page. |\n\n### Request Example\n```json\n{\n \"backgroundColor\": \"#667085\",\n \"brandColor\": \"#697085\",\n \"accentColor\": \"#787085\",\n \"rectShape\": \"ROUNDED\",\n \"fontType\": \"sans-serif\",\n \"logoUrl\": \"https://res.cloudinary.com/image/surfboard-icon.svg\",\n \"iconUrl\": \"https://res.cloudinary.com/image/surfboard-icon.svg\",\n \"footerColor\": \"#CD5C5B\",\n \"primaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"secondaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Branding configuration set successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Branding for Terminal", "slug": "branding-create-branding-for-terminal", "description": "Create a branding configuration for customizable pages at terminal level", "api": "Branding APIs", "method": "PATCH", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId/branding", "content": "# Create Branding for Terminal\n\n## Overview\nCreate a branding configuration for customizable pages at terminal level\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /merchants/:merchantId/stores/:storeId/terminals/:terminalId/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `backgroundColor` | `string` | No | Background color for the page. |\n| `brandColor` | `string` | No | Primary brand color for your page. |\n| `footerColor` | `string` | No | Footer's background color on the page. |\n| `accentColor` | `string` | No | This is a secondary color that complements your brand color. |\n| `rectShape` | `string` | No | Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'. Possible values: `ROUNDED`, `PILL`, `EDGY`. |\n| `fontType` | `string` | No | Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'. Possible values: `serif`, `sans-serif`, `mono`. |\n| `logoUrl` | `string` | No | Logo that will be displayed on the page. |\n| `iconUrl` | `string` | No | Icon that will be displayed on the page. |\n| `primaryCoverImage` | `string` | No | Primary cover image that will be displayed on the page. |\n| `secondaryCoverImage` | `string` | No | Secondary cover image that will be displayed on the page. |\n\n### Request Example\n```json\n{\n \"backgroundColor\": \"#667085\",\n \"brandColor\": \"#697085\",\n \"accentColor\": \"#787085\",\n \"rectShape\": \"ROUNDED\",\n \"fontType\": \"sans-serif\",\n \"logoUrl\": \"https://res.cloudinary.com/image/surfboard-icon.svg\",\n \"iconUrl\": \"https://res.cloudinary.com/image/surfboard-icon.svg\",\n \"footerColor\": \"#CD5C5B\",\n \"primaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"secondaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Branding configuration set successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Branding for Merchant", "slug": "branding-fetch-branding-for-merchant", "description": "Fetch existing branding configuration at merchant level.", "api": "Branding APIs", "method": "GET", "path": "/merchants/:merchantId/branding", "content": "# Fetch Branding for Merchant\n\n## Overview\nFetch existing branding configuration at merchant level.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/branding\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data |\n|     `backgroundColor` | `string` | Background color for the page. |\n|     `brandColor` | `string` | Primary brand color for your page. |\n|     `footerColor` | `string` | Footer's background color on the page. |\n|     `accentColor` | `string` | This is a secondary color that complements your brand color. |\n|     `rectShape` | `string` | Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'. |\n|     `fontType` | `string` | Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'. |\n|     `logoUrl` | `string` | Logo that will be displayed on the page. |\n|     `iconUrl` | `string` | Icon that will be displayed on the page. |\n|     `primaryCoverImage` | `string` | Primary cover image that will be displayed on the page. |\n|     `secondaryCoverImage` | `string` | Secondary cover image that will be displayed on the page. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"backgroundColor\": \"#F08080\",\n \"brandColor\": \"#0E44E1\",\n \"rectShape\": \"ROUNDED\",\n \"fontType\": \"serif\",\n \"accentColor\": \"#F08080\",\n \"logoUrl\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"iconUrl\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"footerColor\": \"#CD5C5B\",\n \"primaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"secondaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\"\n },\n \"message\": \"Fetched Branding successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Branding for Store", "slug": "branding-fetch-branding-for-store", "description": "Fetch existing branding configuration at store level.", "api": "Branding APIs", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/branding", "content": "# Fetch Branding for Store\n\n## Overview\nFetch existing branding configuration at store level.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/branding\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data |\n|     `backgroundColor` | `string` | Background color for the page. |\n|     `brandColor` | `string` | Primary brand color for your page. |\n|     `footerColor` | `string` | Footer's background color on the page. |\n|     `accentColor` | `string` | This is a secondary color that complements your brand color. |\n|     `rectShape` | `string` | Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'. |\n|     `fontType` | `string` | Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'. |\n|     `logoUrl` | `string` | Logo that will be displayed on the page. |\n|     `iconUrl` | `string` | Icon that will be displayed on the page. |\n|     `primaryCoverImage` | `string` | Primary cover image that will be displayed on the page. |\n|     `secondaryCoverImage` | `string` | Secondary cover image that will be displayed on the page. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"backgroundColor\": \"#F08080\",\n \"brandColor\": \"#0E44E1\",\n \"rectShape\": \"ROUNDED\",\n \"fontType\": \"serif\",\n \"accentColor\": \"#F08080\",\n \"logoUrl\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"iconUrl\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"footerColor\": \"#CD5C5B\",\n \"primaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"secondaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\"\n },\n \"message\": \"Fetched Branding successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Branding for Partner", "slug": "branding-fetch-branding-for-partner", "description": "Fetch existing branding configuration at partner level.", "api": "Branding APIs", "method": "GET", "path": "/partners/:partnerId/branding", "content": "# Fetch Branding for Partner\n\n## Overview\nFetch existing branding configuration at partner level.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/branding\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data |\n|     `backgroundColor` | `string` | Background color for the page. |\n|     `brandColor` | `string` | Primary brand color for your page. |\n|     `footerColor` | `string` | Footer's background color on the page. |\n|     `accentColor` | `string` | This is a secondary color that complements your brand color. |\n|     `rectShape` | `string` | Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'. |\n|     `fontType` | `string` | Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'. |\n|     `logoUrl` | `string` | Logo that will be displayed on the page. |\n|     `iconUrl` | `string` | Icon that will be displayed on the page. |\n|     `primaryCoverImage` | `string` | Primary cover image that will be displayed on the page. |\n|     `secondaryCoverImage` | `string` | Secondary cover image that will be displayed on the page. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"backgroundColor\": \"#F08080\",\n \"brandColor\": \"#0E44E1\",\n \"rectShape\": \"ROUNDED\",\n \"fontType\": \"serif\",\n \"accentColor\": \"#F08080\",\n \"logoUrl\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"iconUrl\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"footerColor\": \"#CD5C5B\",\n \"primaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"secondaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\"\n },\n \"message\": \"Fetched Branding successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Branding for Terminal", "slug": "branding-fetch-branding-for-terminal", "description": "Fetch existing branding configuration at terminal level.", "api": "Branding APIs", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId/branding", "content": "# Fetch Branding for Terminal\n\n## Overview\nFetch existing branding configuration at terminal level.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId/branding\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data |\n|     `backgroundColor` | `string` | Background color for the page. |\n|     `brandColor` | `string` | Primary brand color for your page. |\n|     `footerColor` | `string` | Footer's background color on the page. |\n|     `accentColor` | `string` | This is a secondary color that complements your brand color. |\n|     `rectShape` | `string` | Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'. |\n|     `fontType` | `string` | Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'. |\n|     `logoUrl` | `string` | Logo that will be displayed on the page. |\n|     `iconUrl` | `string` | Icon that will be displayed on the page. |\n|     `primaryCoverImage` | `string` | Primary cover image that will be displayed on the page. |\n|     `secondaryCoverImage` | `string` | Secondary cover image that will be displayed on the page. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"backgroundColor\": \"#F08080\",\n \"brandColor\": \"#0E44E1\",\n \"rectShape\": \"ROUNDED\",\n \"fontType\": \"serif\",\n \"accentColor\": \"#F08080\",\n \"logoUrl\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"iconUrl\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"footerColor\": \"#CD5C5B\",\n \"primaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\",\n \"secondaryCoverImage\": \"https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6\"\n },\n \"message\": \"Fetched Branding successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Remove Branding for Merchant", "slug": "branding-remove-branding-for-merchant", "description": "Removes the existing branding configuration at the merchant level.", "api": "Branding APIs", "method": "DELETE", "path": "/merchants/:merchantId/branding", "content": "# Remove Branding for Merchant\n\n## Overview\nRemoves the existing branding configuration at the merchant level.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /merchants/:merchantId/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message describing the outcome of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Configuration deleted successfully for id [8113d3f8403b380409] and type MERCHANT\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Remove Branding for Partner", "slug": "branding-remove-branding-for-partner", "description": "Removes the existing branding configuration at the partner level.", "api": "Branding APIs", "method": "DELETE", "path": "/partners/:partnerId/branding", "content": "# Remove Branding for Partner\n\n## Overview\nRemoves the existing branding configuration at the partner level.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /partners/:partnerId/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message describing the outcome of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Configuration deleted successfully for id [8113d3f8403b380409] and type PARTNER\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Remove Branding for Store", "slug": "branding-remove-branding-for-store", "description": "Removes the existing branding configuration at the store level.", "api": "Branding APIs", "method": "DELETE", "path": "/merchants/:merchantId/stores/:storeId/branding", "content": "# Remove Branding for Store\n\n## Overview\nRemoves the existing branding configuration at the store level.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /merchants/:merchantId/stores/:storeId/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message describing the outcome of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Configuration deleted successfully for id [8113d3f8403b380409] and type STORE\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Remove Branding for Terminal", "slug": "branding-remove-branding-for-terminal", "description": "Removes the existing branding configuration at the terminal level.", "api": "Branding APIs", "method": "DELETE", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId/branding", "content": "# Remove Branding for Terminal\n\n## Overview\nRemoves the existing branding configuration at the terminal level.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /merchants/:merchantId/stores/:storeId/terminals/:terminalId/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message describing the outcome of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Configuration deleted successfully for id [833b9e1cf983580704] and type TERMINAL\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Add Customer Details", "slug": "customers-add-customer-details", "description": "Creates a new customer profile with personal information, addresses, contact details, and associated payment cards. Use this API to register new customers and store their comprehensive information for future transactions and customer management.", "api": "Customers API", "method": "POST", "path": "/customers", "content": "# Add Customer Details\n\n## Overview\nCreates a new customer profile with personal information, addresses, contact details, and associated payment cards. Use this API to register new customers and store their comprehensive information for future transactions and customer management.\n\n## Prerequisites\n- An active merchant account.\n- API Key, API Secret, and Merchant ID are required for authentication.\n- Content-Type header must be set to application/json.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /customers\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Query Parameters\n*No query parameters for this endpoint.*\n\n### Request Body Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| firstName | string | No | Customer's first name. |\n| middleName | string | No | Customer's middle name. |\n| lastName | string | No | Customer's surname or last name. |\n| birthDate | string | No | Customer's date of birth in YYYY/MM/DD format. |\n| countryCode | string | No | Two-letter ISO country code representing the customer's country, in uppercase. |\n| gender | string | No | Customer's gender. |\n| address | array | No | Array of customer addresses for different purposes (shipping, billing, etc.). |\n\n#### address Array Properties\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| address[].careOf | string | No | Care of information for the address. |\n| address[].addressLine1 | string | Yes | First line of the customer's address. |\n| address[].addressLine2 | string | No | Second line of the customer's address. |\n| address[].addressLine3 | string | No | Third line of the customer's address. |\n| address[].city | string | Yes | City of the customer's address. |\n| address[].countryCode | string | Yes | Two-letter ISO country code for the address, in uppercase. |\n| address[].postalCode | string | Yes | Postal code of the customer's address. |\n| address[].role | string | No | Purpose of the address (e.g., 'shipping', 'billing'). |\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| emails | array | No | Array of customer email addresses with their respective roles. |\n\n#### emails Array Properties\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| emails[].email | string | Yes | Customer's email address. |\n| emails[].role | string | Yes | Role or purpose of the email address. |\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| phoneNumbers | array | No | Array of customer phone numbers with their respective roles. |\n\n#### phoneNumbers Array Properties\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| phoneNumbers[].phoneNumber | object | Yes | Customer's phone number details. |\n\n##### phoneNumbers[].phoneNumber Object Properties\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| phoneNumbers[].phoneNumber.code | string | Yes | International dialing code for the phone number. |\n| phoneNumbers[].phoneNumber.number | string | Yes | Phone number without the country code. |\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| phoneNumbers[].role | string | No | Role or purpose of the phone number (e.g., 'own', 'work', 'home'). |\n| cardIds | array | No | Array of payment card identifiers associated with the customer. |\n\n### Request Example\n```json\n{\n\t\"firstName\": \"John\",\n\t\"middleName\": \"Doe\",\n\t\"birthDate\": \"1940/03/04\",\n\t\"countryCode\": \"SE\",\n\t\"address\": [\n\t\t{\n\t\t\t\"careOf\": \"second address at 3:40\",\n\t\t\t\"addressLine1\": \"second address at 3:40\",\n\t\t\t\"addressLine2\": \"3rd west street\",\n\t\t\t\"addressLine3\": \"B-Block\",\n\t\t\t\"city\": \"Ølstykke Stenløse\",\n\t\t\t\"countryCode\": \"SE\",\n\t\t\t\"postalCode\": \"99 999\",\n\t\t\t\"role\": \"shipping\"\n\t\t}\n\t],\n\t\"phoneNumbers\": [\n\t\t{\n\t\t\t\"phoneNumber\": {\n\t\t\t\t\"code\": \"91\",\n\t\t\t\t\"number\": \"9876543210\"\n\t\t\t},\n\t\t\t\"role\": \"own\"\n\t\t}\n\t],\n\t\"cardIds\": [\n\t\t\"824c514bfe001805f0\",\n\t\t\"827a63468b993801f0\",\n\t\t\"827a63460b99380df0\"\n\t]\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| data | object | Response data containing the created customer information. |\n\n#### data Object Properties\n| Parameter | Type | Description |\n|---|---|---|\n| data.customerId | string | Unique identifier assigned to the newly created customer. |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": {\n\t\t\"customerId\": \"83018337960e2802f7\"\n\t},\n\t\"message\": \"Added customer successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### *No error responses provided in the JSON data.*\n\n## Notes\n- Ensure all required fields are present in the request body for successful customer creation.\n- The `countryCode` should be in uppercase, following the two-letter ISO standard.\n---" }, { "title": "Fetch Customer Details by ID", "slug": "customers-fetch-customer-details-by-id", "description": "Retrieves customer information using the customer ID. Use this API to get detailed customer profile including personal information, addresses, contact details, and associated payment cards for customer management and transaction processing.", "api": "Customers API", "method": "GET", "path": "/customers/:customerId", "content": "# Fetch Customer Details by ID\n\n## Overview\nRetrieves customer information using the customer ID. Use this API to get detailed customer profile including personal information, addresses, contact details, and associated payment cards for customer management and transaction processing.\n\n## Prerequisites\n- API Key and Secret: You must have a valid API key and secret to access this endpoint.\n- Merchant ID: You must have a valid Merchant ID.\n- Authentication: Authenticate using your API key, API secret, and Merchant ID in the headers.\n- Customer ID: You must have the ID of the customer you want to retrieve.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /customers/:customerId\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Query Parameters\nN/A\n\n### Request Body Parameters\nN/A\n\n### Request Example\n```json\n// No request body needed for GET request.\n// Ensure the customerId is provided in the URL path.\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| data | object | Response data containing comprehensive customer information. |\n| data.firstName | string | Customer's first name. |\n| data.middleName | string | Customer's middle name. |\n| data.lastName | string | Customer's surname or last name. |\n| data.birthDate | string | Customer's date of birth. |\n| data.gender | string | Customer's gender. |\n| data.countryCode | string | Two-letter ISO country code representing the customer's country. |\n| data.address | array | Array of customer addresses. |\n| data.address.careOf | string | Care of information for the address. |\n| data.address.addressLine1 | string | First line of the customer's address. |\n| data.address.addressLine2 | string | Second line of the customer's address. |\n| data.address.addressLine3 | string | Third line of the customer's address. |\n| data.address.city | string | City of the customer's address. |\n| data.address.countryCode | string | Two-letter ISO country code for the address. |\n| data.address.postalCode | string | Postal code of the customer's address. |\n| data.address.role | string | Purpose of the address (e.g., 'shipping', 'billing'). |\n| data.emails | array | Array of customer email addresses. |\n| data.emails.email | string | Customer's email address. |\n| data.emails.role | string | Role or purpose of the email address. |\n| data.phoneNumbers | array | Array of customer phone numbers. |\n| data.phoneNumbers.phoneNumber | object | Customer's phone number details. |\n| data.phoneNumbers.phoneNumber.code | string | International dialing code for the phone number. |\n| data.phoneNumbers.phoneNumber.number | string | Phone number without the country code. |\n| data.phoneNumbers.role | string | Role or purpose of the phone number. |\n| data.cardIds | array | Array of payment card identifiers associated with the customer. |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"countryCode\": \"SE\",\n \"address\": [\n {\n \"careOf\": \"second address at 3:40\",\n \"addressLine1\": \"second address at 3:40\",\n \"addressLine2\": \"3rd west street\",\n \"addressLine3\": \"B-Block\",\n \"city\": \"Ølstykke Stenløse\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"99 999\",\n \"role\": \"shipping\"\n }\n ],\n \"emails\": [],\n \"phoneNumbers\": [\n {\n \"phoneNumber\": {\n \"code\": \"91\",\n \"number\": \"9876543210\"\n },\n \"role\": \"own\"\n }\n ],\n \"cardIds\": [\n \"824c514bfe001805f0\",\n \"827a63468b993801f0\",\n \"827a63460b99380df0\"\n ]\n },\n \"message\": \"Fetched customer details successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid customer ID format\"\n}\n```\n**Description:** The customer ID provided in the URL is not in the correct format. Ensure the customer ID is a valid integer or UUID.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized: Missing or invalid API key\"\n}\n```\n**Description:** The API key is missing or invalid. Ensure the `API-KEY` header is present and contains a valid API key. Check your API credentials.\n\n#### 403 - Forbidden\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Forbidden: Insufficient permissions\"\n}\n```\n**Description:** The API key does not have the necessary permissions to access this endpoint. Contact your administrator to request the required permissions.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Customer not found\"\n}\n```\n**Description:** The customer with the provided ID does not exist. Verify the customer ID is correct.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Internal server error\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try again later. If the problem persists, contact support with the request details.\n\n## Notes\n- The `customerId` in the URL path is case-sensitive.\n- Ensure that the `Content-Type` header is set to `application/json`.\n- Empty arrays will be returned for `emails`, `phoneNumbers`, and `cardIds` if no data is available.\n---" }, { "title": "Create Gift Card", "slug": "gift-cards-create-gift-card", "description": "Creates a new gift card with specified type and configuration. Gift cards can be FUND type (with monetary value) or ENTITLEMENT type (with usage limits).", "api": "Gift Cards API", "method": "POST", "path": "/giftcards", "content": "# Create Gift Card\n\n## Overview\nCreates a new gift card with specified type and configuration. Gift cards can be FUND type (with monetary value) or ENTITLEMENT type (with usage limits).\n\n## Prerequisites\n- Merchant account must be set up.\n- API keys (api-key and api-secret) and merchant ID must be obtained.\n- Ensure you have the correct permissions to create gift cards.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /giftcards\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| Content-Type | application/json | Yes |\n| api-key | YOUR_API_KEY | Yes |\n| api-secret | YOUR_API_SECRET | Yes |\n| merchant-id | YOUR_MERCHANT_ID | Yes |\n\n### Request Body Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| cardType | string | Yes | Type of gift card to create. Possible values: `FUND`, `ENTITLEMENT`. `FUND`: Gift card with monetary value. `ENTITLEMENT`: Gift card with usage-based limits. |\n| amount | number | Conditional | Monetary amount for FUND type gift cards. Required when `cardType` is `FUND`. |\n| redemptionLimit | number | Conditional | Number of times the gift card can be used. Required when `cardType` is `ENTITLEMENT`. |\n| currency | string | Optional | Currency code for the gift card amount. |\n| name | string | Optional | Optional name for the gift card. |\n| accessControl | string | Optional | Access control level for the gift card. Possible values: `OPEN`, `RESTRICTED`. `OPEN`: Gift card can be used by anyone. `RESTRICTED`: Gift card has restricted access. |\n| expiryDate | string | Optional | Expiry date for the gift card in mm/dd/yyyy or mm-dd-yyyy format. |\n| note | string | Optional | Optional note or description for the gift card. |\n\n### Request Example\n```json\n{\n\t\"cardType\": \"FUND\",\n\t\"amount\": 100.00,\n\t\"currency\": \"SEK\",\n\t\"name\": \"Holiday Gift Card\",\n\t\"accessControl\": \"OPEN\",\n\t\"expiryDate\": \"12/31/2024\",\n\t\"note\": \"Happy Holidays!\"\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| data | object | Response data containing gift card details. |\n| data.giftCardId | string | Unique identifier for the created gift card. |\n| data.pan | string | Primary Account Number for the gift card. |\n| data.name | string | Name of the gift card. |\n| data.formats | object | Different format representations of the gift card. |\n| data.formats.qrCode | string | QR code representation of the gift card. |\n| data.formats.nfcData | string | NFC data for the gift card. |\n| data.formats.barcode | string | Barcode representation of the gift card. |\n| data.cardType | string | Type of the gift card (FUND or ENTITLEMENT). |\n| data.amount | number | Monetary amount for FUND type gift cards. |\n| data.redemptionLimit | number | Usage limit for ENTITLEMENT type gift cards. |\n| data.currency | string | Currency code for the gift card. |\n| data.accessControl | string | Access control level of the gift card. |\n| data.externalId | string | External identifier for the gift card. |\n| data.externalIdType | string | Type of external identifier. |\n| data.status | string | Current status of the gift card. |\n| data.shareableLink | string | Shareable link for the gift card. |\n| data.expiryDate | string | Expiry date of the gift card. |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": {\n\t\t\"giftCardId\": \"83a5aea0381600045c\",\n\t\t\"pan\": \"1504703347938280\",\n\t\t\"name\": \"Birthday Gift Card\",\n\t\t\"formats\": {\n\t\t\t\"qrCode\": \"undefinedVWwIYiYXCANr202512310200\",\n\t\t\t\"nfcData\": \"undefinedVWwIYiYXCANr202512310200\",\n\t\t\t\"barcode\": \"2877866156\"\n\t\t},\n\t\t\"cardType\": \"FUND\",\n\t\t\"amount\": 100,\n\t\t\"redemptionLimit\": 0,\n\t\t\"currency\": \"SEK\",\n\t\t\"accessControl\": \"OPEN\",\n\t\t\"externalId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n\t\t\"externalIdType\": \"MERCHANT\",\n\t\t\"status\": \"CREATED\",\n\t\t\"shareableLink\": \"https://slr.test.surfboard.se/afaa6fb5\"\n\t},\n\t\"message\": \"Gift card created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### TBD - Missing Mandatory Parameter\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Missing mandatory parameter: cardType\"\n}\n```\n**Description:** Occurs when a mandatory parameter, such as `cardType`, is missing from the request. Ensure all required parameters are included in the request body.\n\n#### TBD - Invalid Card Type\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid card type. Supported types are FUND and ENTITLEMENT.\"\n}\n```\n**Description:** Occurs when the `cardType` parameter has an invalid value. Make sure the value is either `FUND` or `ENTITLEMENT`.\n\n#### TBD - Missing Amount for FUND Card\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Amount is required for FUND type gift cards.\"\n}\n```\n**Description:** Occurs when `cardType` is set to `FUND` but the `amount` parameter is missing. Provide a valid `amount` when creating a `FUND` type gift card.\n\n#### TBD - Missing Redemption Limit for ENTITLEMENT Card\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Redemption limit is required for ENTITLEMENT type gift cards.\"\n}\n```\n**Description:** Occurs when `cardType` is set to `ENTITLEMENT` but the `redemptionLimit` parameter is missing. Provide a valid `redemptionLimit` when creating an `ENTITLEMENT` type gift card.\n\n#### TBD - Invalid API Key\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid API Key\"\n}\n```\n**Description:** Occurs when an invalid or expired API key is provided. Verify the API key and try again.\n\n---\n\n## Notes\n- The `externalId` and `externalIdType` parameters in the response provide a way to link the gift card to an external system.\n- The QR code, NFC data, and barcode formats of the gift card are provided for easy integration with different payment systems.\n- The expiry date format must be either mm/dd/yyyy or mm-dd-yyyy." }, { "title": "Get All Gift Cards", "slug": "gift-cards-get-all-gift-cards", "description": "Retrieves a paginated list of all gift cards for a merchant. Supports filtering by type and status.", "api": "Gift Cards API", "method": "GET", "path": "/giftcards", "content": "# Get All Gift Cards\n\n## Overview\nRetrieves a paginated list of all gift cards for a merchant. Supports filtering by type and status.\n\n## Prerequisites\n- Merchant must have an active account.\n- API keys and secrets are required for authentication.\n- Merchant ID is required to identify the merchant.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /giftcards\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `api-key` | Your API Key | Yes |\n| `api-secret` | Your API Secret | Yes |\n| `merchant-id` | Your Merchant ID | Yes |\n| `x-page-number` | Page number for pagination. Starts from 1. | Yes, for pagination |\n\n### Query Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `type` | string | No | Filter gift cards by type. Possible values: `FUND`, `ENTITLEMENT`. |\n| `status` | string | No | Filter gift cards by status. |\n\n### Request Example\n```json\n{\n \"headers\": {\n \"api-key\": \"YOUR_API_KEY\",\n \"api-secret\": \"YOUR_API_SECRET\",\n \"merchant-id\": \"YOUR_MERCHANT_ID\",\n \"x-page-number\": \"1\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | array | Array of gift card objects. |\n| `data[].giftCardId` | string | Unique identifier for the gift card. |\n| `data[].pan` | string | Primary Account Number for the gift card. |\n| `data[].name` | string | Name of the gift card. |\n| `data[].cardType` | string | Type of the gift card (FUND or ENTITLEMENT). |\n| `data[].amount` | number | Original monetary amount for FUND type gift cards. |\n| `data[].currentAmount` | number | Current remaining amount for FUND type gift cards. |\n| `data[].usageCount` | number | Number of times the gift card has been used. |\n| `data[].redemptionLimit` | number | Usage limit for ENTITLEMENT type gift cards. |\n| `data[].currency` | string | Currency code for the gift card. |\n| `data[].accessControl` | string | Access control level of the gift card. |\n| `data[].status` | string | Current status of the gift card. |\n| `data[].expiryDate` | string | Expiry date of the gift card. |\n| `data[].lastTransactionAt` | string | Timestamp of the last transaction. |\n| `data[].transactionCount` | number | Total number of transactions. |\n| `data[].totalRedeemed` | number | Total amount redeemed from the gift card. |\n| `message` | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"giftCardId\": \"83a2adb2fd9d58095c\",\n \"pan\": \"1802723955691673\",\n \"name\": \"Birthday Gift Card\",\n \"cardType\": \"FUND\",\n \"amount\": 100,\n \"currentAmount\": 100,\n \"usageCount\": 0,\n \"redemptionLimit\": 0,\n \"currency\": \"SEK\",\n \"accessControl\": \"OPEN\",\n \"status\": \"CREATED\",\n \"expiryDate\": \"2025-12-31T00:00:00.000Z\",\n \"transactionCount\": 0,\n \"totalRedeemed\": 0\n },\n {\n \"giftCardId\": \"83a2ac747d9d580b5c\",\n \"pan\": \"1167728279630112\",\n \"name\": \"Birthday Gift Card\",\n \"cardType\": \"FUND\",\n \"amount\": 100,\n \"currentAmount\": 100,\n \"usageCount\": 0,\n \"redemptionLimit\": 0,\n \"currency\": \"SEK\",\n \"accessControl\": \"OPEN\",\n \"status\": \"CREATED\",\n \"expiryDate\": \"2025-12-31T00:00:00.000Z\",\n \"transactionCount\": 0,\n \"totalRedeemed\": 0\n },\n {\n \"giftCardId\": \"83a256695d9d28025c\",\n \"pan\": \"1657679889602692\",\n \"name\": \"Birthday Gift Card\",\n \"cardType\": \"FUND\",\n \"amount\": 100,\n \"currentAmount\": 100,\n \"usageCount\": 0,\n \"redemptionLimit\": 0,\n \"currency\": \"SEK\",\n \"accessControl\": \"OPEN\",\n \"status\": \"CREATED\",\n \"expiryDate\": \"2025-12-31T00:00:00.000Z\",\n \"transactionCount\": 0,\n \"totalRedeemed\": 0\n }\n ],\n \"message\": \"Gift cards fetched\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Invalid or missing API key and/or API secret. Ensure that the `api-key` and `api-secret` headers are correctly set and that your API key has the necessary permissions.\n\n#### 403 - Forbidden\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Forbidden\"\n}\n```\n**Description:** The API key does not have permission to access this resource. Verify that your API key has the required roles and permissions for accessing gift cards.\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters\"\n}\n```\n**Description:** The request contains invalid parameters. Ensure all parameters are correctly formatted and meet the API's requirements. This can occur due to invalid filter parameters, such as an unsupported `type` or `status`.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Internal server error\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Use the `x-page-number` header for pagination. The first page is `x-page-number: 1`.\n- Filtering by `type` and `status` is optional but can improve performance by reducing the amount of data returned.\n- Ensure your API key, secret, and merchant ID are securely stored and never exposed in client-side code.\n\n---" }, { "title": "Get Gift Card Details", "slug": "gift-cards-get-gift-card-details", "description": "Retrieves detailed information for a specific gift card using its ID or PAN. Includes customer details, transaction history summary, and format representations.", "api": "Gift Cards API", "method": "GET", "path": "/giftcards/:id", "content": "# Get Gift Card Details\n\n## Overview\nRetrieves detailed information for a specific gift card using its ID or PAN. Includes customer details, transaction history summary, and format representations.\n\n## Prerequisites\n- API key and secret are required for authentication.\n- Merchant ID is required to identify the merchant making the request.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /giftcards/:id\n```\n\n### Headers\n| Header | Value | Required |\n|--------|-------|----------|\n| api-key | YOUR_API_KEY | Yes |\n| api-secret | YOUR_API_SECRET | Yes |\n| merchant-id | YOUR_MERCHANT_ID | Yes |\n\n### Query Parameters\nN/A\n\n### Request Body Parameters\nN/A\n\n### Request Example\n```json\n// Example request is constructed using path parameter \":id\"\n// No request body needed for GET requests\n// Sample URL: /giftcards/83a2adb2fd9d58095c\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| data | object | Detailed gift card information. |\n| data.giftCardId | string | Unique identifier for the gift card. |\n| data.pan | string | Primary Account Number for the gift card. |\n| data.name | string | Name of the gift card. |\n| data.cardType | string | Type of the gift card (FUND or ENTITLEMENT). |\n| data.amount | number | Original monetary amount for FUND type gift cards. |\n| data.currentAmount | number | Current remaining amount for FUND type gift cards. |\n| data.usageCount | number | Number of times the gift card has been used. |\n| data.redemptionLimit | number | Usage limit for ENTITLEMENT type gift cards. |\n| data.currency | string | Currency code for the gift card. |\n| data.accessControl | string | Access control level of the gift card. |\n| data.status | string | Current status of the gift card. |\n| data.expiryDate | string | Expiry date of the gift card. |\n| data.lastTransactionAt | string | Timestamp of the last transaction. |\n| data.transactionCount | number | Total number of transactions. |\n| data.totalRedeemed | number | Total amount redeemed from the gift card. |\n| data.customerDetails | object | Customer information associated with the gift card. |\n| data.customerDetails.customerId | string | Unique identifier for the customer. |\n| data.customerDetails.firstName | string | Customer's first name. |\n| data.customerDetails.middleName | string | Customer's middle name. |\n| data.customerDetails.surname | string | Customer's surname. |\n| data.customerDetails.countryCode | string | Customer's country code. |\n| data.customerDetails.emails | array | Array of customer email addresses. |\n| data.customerDetails.emails[].email | string | Customer email address. |\n| data.customerDetails.phoneNumbers | array | Array of customer phone numbers. |\n| data.customerDetails.phoneNumbers[].phoneNumber | object | Customer phone number details. |\n| data.customerDetails.phoneNumbers[].phoneNumber.countryCode | string | Phone number country code. |\n| data.customerDetails.phoneNumbers[].phoneNumber.number | string | Phone number. |\n| data.shareableLink | string | Shareable link for the gift card. |\n| data.formats | object | Different format representations of the gift card. |\n| data.formats.qrCode | string | QR code representation of the gift card. |\n| data.formats.nfcData | string | NFC data for the gift card. |\n| data.formats.barcode | string | Barcode representation of the gift card. |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": {\n\t\t\"giftCardId\": \"83a2adb2fd9d58095c\",\n\t\t\"pan\": \"1802723955691673\",\n\t\t\"name\": \"Birthday Gift Card\",\n\t\t\"cardType\": \"FUND\",\n\t\t\"amount\": 100,\n\t\t\"currentAmount\": 75,\n\t\t\"usageCount\": 2,\n\t\t\"redemptionLimit\": 0,\n\t\t\"currency\": \"SEK\",\n\t\t\"accessControl\": \"OPEN\",\n\t\t\"externalId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n\t\t\"externalIdType\": \"MERCHANT\",\n\t\t\"status\": \"ACTIVE\",\n\t\t\"expiryDate\": \"2025-12-31T00:00:00.000Z\",\n\t\t\"lastTransactionAt\": \"2024-11-15T10:30:00Z\",\n\t\t\"transactionCount\": 2,\n\t\t\"totalRedeemed\": 25,\n\t\t\"customerDetails\": {\n\t\t\t\"customerId\": \"83a2adb2fd9d58001c\",\n\t\t\t\"firstName\": \"John\",\n\t\t\t\"surname\": \"Doe\",\n\t\t\t\"countryCode\": \"SE\",\n\t\t\t\"emails\": [{\"email\": \"john.doe@example.com\"}],\n\t\t\t\"phoneNumbers\": [{\"phoneNumber\": {\"countryCode\": \"+46\", \"number\": \"701234567\"}}]\n\t\t},\n\t\t\"shareableLink\": \"https://slr.test.surfboard.se/afaa6fb5\",\n\t\t\"formats\": {\n\t\t\t\"qrCode\": \"undefinedVWwIYiYXCANr202512310200\",\n\t\t\t\"nfcData\": \"undefinedVWwIYiYXCANr202512310200\",\n\t\t\t\"barcode\": \"2877866156\"\n\t\t}\n\t},\n\t\"message\": \"Gift card details retrieved successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\nTBD\n\n## Notes\n- Replace `YOUR_API_KEY`, `YOUR_API_SECRET`, and `YOUR_MERCHANT_ID` with your actual credentials.\n- The `:id` path parameter can accept either the `giftCardId` or the `pan` of the gift card.\n\n---" }, { "title": "Get Gift Card Transactions", "slug": "gift-cards-get-gift-card-transactions", "description": "Retrieves a paginated list of transactions for a specific gift card. Supports filtering by transaction type.", "api": "Gift Cards API", "method": "GET", "path": "/giftcards/:giftCardId/transactions", "content": "# Get Gift Card Transactions\n\n## Overview\nRetrieves a paginated list of transactions for a specific gift card. Supports filtering by transaction type.\n\n## Prerequisites\n- API Key and API Secret are required for authentication.\n- A valid Merchant ID is required.\n- The `giftCardId` must be a valid gift card identifier.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /giftcards/:giftCardId/transactions\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `api-key` | Your API Key | Yes |\n| `api-secret` | Your API Secret | Yes |\n| `merchant-id` | Your Merchant ID | Yes |\n| `x-page-number` | Page number for pagination | No |\n\n### Query Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `transactionType` | string | No | Filter transactions by type. Possible values: `ISSUED`, `CREDIT`, `DEBIT`. |\n\n### Request Body Parameters\nN/A\n\n### Request Example\n```json\n{\n \"headers\": {\n \"api-key\": \"YOUR_API_KEY\",\n \"api-secret\": \"YOUR_API_SECRET\",\n \"merchant-id\": \"YOUR_MERCHANT_ID\",\n \"x-page-number\": \"1\"\n },\n \"queryParameters\": {\n \"transactionType\": \"DEBIT\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | array | Array of transaction objects. |\n| `data[].paymentId` | string | Unique identifier for the payment/transaction. |\n| `data[].transactionType` | string | Type of transaction (ISSUED, CREDIT, DEBIT). |\n| `data[].transactionAmount` | number | Amount involved in the transaction. |\n| `data[].currency` | string | Currency code for the transaction amount. |\n| `data[].valueBefore` | number | Gift card value before the transaction. |\n| `data[].valueAfter` | number | Gift card value after the transaction. |\n| `data[].orderId` | string | Associated order ID if applicable. |\n| `data[].merchantId` | string | Merchant ID associated with the transaction. |\n| `data[].storeId` | string | Store ID associated with the transaction. |\n| `data[].metadata` | object | Additional metadata for the transaction. |\n| `message` | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"paymentId\": \"83a2adb2fd9d58095d\",\n \"transactionType\": \"ISSUED\",\n \"transactionAmount\": 100,\n \"currency\": \"SEK\",\n \"valueBefore\": 0,\n \"valueAfter\": 100,\n \"merchantId\": \"83a2adb2fd9d58001a\",\n \"storeId\": \"83a2adb2fd9d58002b\"\n },\n {\n \"paymentId\": \"83a2adb2fd9d58095e\",\n \"transactionType\": \"DEBIT\",\n \"transactionAmount\": 25,\n \"currency\": \"SEK\",\n \"valueBefore\": 100,\n \"valueAfter\": 75,\n \"orderId\": \"83a2adb2fd9d58003c\",\n \"merchantId\": \"83a2adb2fd9d58001a\",\n \"storeId\": \"83a2adb2fd9d58002b\",\n \"metadata\": {\n \"terminalId\": \"83a2adb2fd9d58004d\",\n \"transactionDate\": \"2024-11-15T10:30:00Z\"\n }\n }\n ],\n \"message\": \"Gift card transactions retrieved successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid gift card ID\"\n}\n```\n**Description:** The provided gift card ID is invalid or not found. Ensure the gift card ID is correct.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid API Key or Secret\"\n}\n```\n**Description:** The API Key or Secret provided in the headers is incorrect or missing. Verify that the API Key and Secret are valid and properly included in the request headers.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** A server-side error occurred during the request processing. Try again later. If the problem persists, contact support.\n\n## Notes\n- The `x-page-number` header is used for pagination. If not provided, the first page is returned.\n- The `transactionType` query parameter allows filtering transactions by type. Valid values are `ISSUED`, `CREDIT`, and `DEBIT`.\n- If no transactions are found for the specified gift card, the `data` array will be empty.\n\n---" }, { "title": "Create Return", "slug": "logistics-create-return", "description": "Creates a return request for terminals using the API. This enhanced version allows for more detailed merchant information and multiple return order lines.", "api": "Logistics API", "method": "POST", "path": "/partners/:partnerId/logistics/returns", "content": "# Create Return\n\n## Overview\nCreates a return request for terminals using the API. This enhanced version allows for more detailed merchant information and multiple return order lines.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/logistics/returns\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantInfo` | `object` | Yes | Detailed merchant information for the return request. |\n|     `name` | `string` | Yes | Name of the merchant. |\n|     `email` | `string` | Yes | Email address of the merchant. |\n|     `phoneNumber` | `object` | Yes | Contact number of the merchant in code and number format. |\n|         `code` | `string` | Yes | International dialing code identifying the country or region. |\n|         `number` | `string` | Yes | Phone number. |\n|     `addressLine1` | `string` | Yes | First line of the merchant's address. |\n|     `addressLine2` | `string` | No | Second line of the merchant's address. |\n|     `addressLine3` | `string` | No | Third line of the merchant's address. |\n|     `countryCode` | `string` | Yes | Two-letter ISO country code in uppercase. |\n|     `postalNumber` | `string` | Yes | Postal code of the merchant's address. |\n|     `city` | `string` | Yes | City of the merchant's address. |\n| `returnOrderLines` | `array` | Yes | Array of return order line items. |\n|     `serial` | `string` | Yes | Serial number of the terminal to be returned. |\n|     `merchantId` | `string` | No | Unique identifier of the merchant. Provide both merchantId and terminalId for a registered terminal, or omit both to return an unregistered terminal. |\n|     `terminalId` | `string` | No | Unique identifier of the terminal. Provide both terminalId and merchantId for a registered terminal, or omit both to return an unregistered terminal. |\n|     `reasonForReturn` | `string` | Yes | Reason for the return. Possible values: `WARRANTY`, `NOT_USING_SERVICE`, `NON_WARRANTY_BROKEN`, `TECHNICAL_ISSUES`, `COMPATIBILITY_ISSUES`. |\n|     `stopBilling` | `boolean` | No | Whether to stop billing for this terminal. |\n|     `comment` | `string` | No | Additional comments regarding the return. |\n| `deliveryInstruction` | `string` | No | Delivery instructions for the carrier. |\n\n### Request Example\n```json\n{\n \"merchantInfo\": {\n \"name\": \"Demo Store\",\n \"email\": \"demo@example.com\",\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"123456789\"\n },\n \"addressLine1\": \"Demo Street 123\",\n \"addressLine2\": \"Building A\",\n \"addressLine3\": null,\n \"city\": \"Stockholm\",\n \"countryCode\": \"SE\",\n \"postalNumber\": \"12345\"\n },\n \"returnOrderLines\": [\n {\n \"serial\": \"TERM001234567\",\n \"terminalId\": \"816a0ff6bc0fb00404\",\n \"reasonForReturn\": \"NOT_USING_SERVICE\",\n \"stopBilling\": true,\n \"comment\": \"Device not working properly\"\n }\n ],\n \"deliveryInstruction\": \"Please call before delivery\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data |\n|     `returnId` | `number` | ID of the return request. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"returnId\": 80\n },\n \"message\": \"Return request created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Shipment", "slug": "logistics-create-shipment", "description": "Creates a shipment order for terminals and other accessories. Use this API to initiate an order to ship terminals and other accessories to merchants.", "api": "Logistics API", "method": "POST", "path": "/partners/:partnerId/merchants/:merchantId/shipment", "content": "# Create Shipment\n\n## Overview\nCreates a shipment order for terminals and other accessories. Use this API to initiate an order to ship terminals and other accessories to merchants.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/merchants/:merchantId/shipment\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `shippingAddress` | `object` | No | Input the shipping address for the products. If no address is specified, the merchant's address will be used as the default shipping address. |\n|     `name` | `string` | Yes | Full name of the receiver for the shipment. |\n|     `addressLine1` | `string` | Yes | The first line of the receiver's address. |\n|     `addressLine2` | `string` | No | The second line of the receiver's address. |\n|     `addressLine3` | `string` | No | The third line of the receiver's address. |\n|     `city` | `string` | Yes | City of the receiver |\n|     `countryCode` | `string` | Yes | Two-letter ISO country code of the receiver, in uppercase. |\n|     `postalCode` | `string` | Yes | Postal code of the receiver. |\n|     `phoneNumber` | `object` | No | Contact number of the receiver in code and number format. |\n|         `code` | `string` | Yes | International dialing code identifying the country or region. |\n|         `number` | `string` | Yes | Phone number. |\n|     `email` | `string` | No | Email address of the receiver. |\n|     `deliveryInstruction` | `string` | No | Delivery instructions for the carrier. |\n| `lineItems` | `array` | Yes | An array of products to be shipped. |\n|     `productId` | `string` | Yes | The SurfboardProductId of the product or group of products. This is unique to the partner. |\n|     `quantity` | `number` | Yes | Number of products or group of products to be shipped. |\n|     `billingPlanId` | `string` | No | Optional billing plan for the product or group of products chosen. If omitted, default plan will be chosen. |\n|     `replacementFor` | `string` | No | If this line item is placed as part of a replacement for an existing device, then the terminalId of the original device needs to be specified. We will supply the merchant with a waybill to return the old device. They can reuse the box which the new terminal comes in. |\n\n### Request Example\n```json\n{\n \"shippingAddress\": {\n \"name\": \"John Doe\",\n \"addressLine1\": \"Main Street 123\",\n \"addressLine2\": \"Building C\",\n \"addressLine3\": \"Building C\",\n \"city\": \"Stockholm\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"123 45\",\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"771890089\"\n },\n \"email\": \"developer@test.se\",\n \"deliveryInstruction\": \"XXX\"\n },\n \"lineItems\": [\n {\n \"productId\": \"12345\",\n \"quantity\": 1\n }\n ]\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'.. |\n| `data` | `object` | Response data |\n|     `orderId` | `string` | Order ID for the order. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"orderId\": \"81376ad8ebedf80310\"\n },\n \"message\": \"Order for shipping terminal successfully created\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Merchant Orders", "slug": "logistics-fetch-merchant-orders", "description": "Retrieves all orders placed for a specific merchant. Use this API to get the status and details of all orders for a particular merchant.", "api": "Logistics API", "method": "GET", "path": "/merchants/:merchantId/logistics/orders", "content": "# Fetch Merchant Orders\n\n## Overview\nRetrieves all orders placed for a specific merchant. Use this API to get the status and details of all orders for a particular merchant.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/logistics/orders\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/logistics/orders\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | Array of order objects for the merchant. |\n|     `orderId` | `string` | Unique identifier for the order. |\n|     `trackingUrl` | `string` | The tracking URL of the shipment. |\n|     `trackingCode` | `string` | The carrier's tracking code for the shipment. |\n|     `status` | `string` | Current status of the order. |\n|     `deliveryPartner` | `string` | The partner or carrier responsible for delivering the shipment. |\n|     `packages` | `array` | Array of package details in the order. |\n|         `productId` | `string` | The SurfboardProductId of the product. |\n|         `serialNumber` | `string` | Serial number of the device. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"orderId\": \"8190422d77e1400428\",\n \"trackingUrl\": \"\",\n \"trackingCode\": \"\",\n \"status\": \"ORDER_CANCELLED\",\n \"deliveryPartner\": \"DHL\",\n \"packages\": [\n {\n \"productId\": \"817361bb0a23400701\",\n \"serialNumber\": \"\"\n }\n ]\n },\n {\n \"orderId\": \"819118d10a3d900f28\",\n \"trackingUrl\": \"\",\n \"trackingCode\": \"\",\n \"status\": \"ORDER_CANCELLED\",\n \"deliveryPartner\": \"DHL\",\n \"packages\": [\n {\n \"productId\": \"817361bb0a23400701\",\n \"serialNumber\": \"\"\n }\n ]\n }\n ],\n \"message\": \"Orders fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Partner Orders", "slug": "logistics-fetch-partner-orders", "description": "Retrieves all orders placed by a partner for terminals and accessories. Use this API to get the status and details of all orders under a partner.", "api": "Logistics API", "method": "GET", "path": "/partners/:partnerId/logistics/orders", "content": "# Fetch Partner Orders\n\n## Overview\nRetrieves all orders placed by a partner for terminals and accessories. Use this API to get the status and details of all orders under a partner.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/logistics/orders\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/logistics/orders\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | Array of order objects. |\n|     `orderId` | `string` | Unique identifier for the order. |\n|     `trackingUrl` | `string` | The tracking URL of the shipment. |\n|     `trackingCode` | `string` | The carrier's tracking code for the shipment. |\n|     `merchantId` | `string` | Identifier of the merchant the order was placed for. |\n|     `deliveryPartner` | `string` | The partner or carrier responsible for delivering the shipment. |\n|     `status` | `string` | Current status of the order. |\n|     `packages` | `array` | Array of package details in the order. |\n|         `productId` | `string` | The SurfboardProductId of the product. |\n|         `serialNumber` | `string` | Serial number of the device. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"orderId\": \"8190422d77e1400428\",\n \"trackingUrl\": \"\",\n \"trackingCode\": \"\",\n \"merchantId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n \"status\": \"ORDER_CANCELLED\",\n \"deliveryPartner\": \"DHL\",\n \"packages\": [\n {\n \"productId\": \"817361bb0a23400701\",\n \"serialNumber\": \"\"\n }\n ]\n },\n {\n \"orderId\": \"819118d10a3d900f28\",\n \"trackingUrl\": \"\",\n \"trackingCode\": \"\",\n \"merchantId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n \"status\": \"ORDER_CANCELLED\",\n \"deliveryPartner\": \"DHL\",\n \"packages\": [\n {\n \"productId\": \"817361bb0a23400701\",\n \"serialNumber\": \"\"\n }\n ]\n }\n ],\n \"message\": \"Orders fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Returns", "slug": "logistics-get-returns", "description": "Retrieves return requests for a specific merchant using the API. Supports filtering by status and provides detailed return information.", "api": "Logistics API", "method": "GET", "path": "/partners/:partnerId/logistics/returns", "content": "# Get Returns\n\n## Overview\nRetrieves return requests for a specific merchant using the API. Supports filtering by status and provides detailed return information.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/logistics/returns\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `filter` | `string` | No | Filter returns by status. Possible values: `APPROVED`, `CREATED`. |\n\n### Pagination\n\nTo `filter` returns by status send in `filter` as query param\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/logistics/returns?filter=APPROVED\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | Array of return request objects. |\n|     `returnId` | `number` | Unique identifier for the return request. |\n|     `partnerId` | `string` | Unique identifier of the partner. |\n|     `merchantName` | `string` | Name of the merchant. |\n|     `merchantEmail` | `string` | Email address of the merchant. |\n|     `merchantPhone` | `string` | Phone number of the merchant. |\n|     `merchantAddressLine1` | `string` | First line of the merchant's address. |\n|     `merchantAddressLine2` | `string` | Second line of the merchant's address. |\n|     `merchantAddressLine3` | `string` | Third line of the merchant's address. |\n|     `merchantCity` | `string` | City of the merchant's address. |\n|     `merchantPostalNumber` | `string` | Postal code of the merchant's address. |\n|     `merchantCountryCode` | `string` | Country code of the merchant's address. |\n|     `deliveryInstruction` | `string` | Delivery instructions for the return. |\n|     `status` | `string` | Current status of the return request. Possible values: `APPROVED`, `CREATED`. |\n|     `returnOrderLines` | `array` | Array of return order line items. |\n|         `returnOrderlineId` | `number` | Unique identifier for the return order line. |\n|         `returnId` | `number` | ID of the parent return request. |\n|         `serial` | `string` | Serial number of the terminal. |\n|         `terminalId` | `string` | Unique identifier of the terminal. |\n|         `merchantId` | `string` | Unique identifier of the merchant. |\n|         `deviceModel` | `string` | Model of the device being returned. |\n|         `reasonForReturn` | `string` | Reason for the return. |\n|         `stopBilling` | `boolean` | Whether billing has been stopped for this terminal. |\n|         `comment` | `string` | Additional comments regarding the return. |\n|         `isUnregistered` | `boolean` | Whether this line was created for an unregistered terminal, one with no associated terminal or merchant. |\n| `message` | `string` | A message that describes the status of the request. |\n| `totalCount` | `number` | Total count of return requests matching the criteria. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"returnId\": 80,\n \"partnerId\": \"8113d3f8403b380409\",\n \"merchantName\": \"Demo Store\",\n \"merchantEmail\": \"demo@example.com\",\n \"merchantPhone\": \"+46123456789\",\n \"merchantAddressLine1\": \"Demo Street 123\",\n \"merchantAddressLine2\": \"Building A\",\n \"merchantAddressLine3\": \"\",\n \"merchantCity\": \"Stockholm\",\n \"merchantPostalNumber\": \"12345\",\n \"merchantCountryCode\": \"SE\",\n \"deliveryInstruction\": \"Please call before delivery\",\n \"status\": \"CREATED\",\n \"returnOrderLines\": [\n {\n \"returnOrderlineId\": 78,\n \"returnId\": 80,\n \"serial\": \"TERM001234567\",\n \"terminalId\": \"816a0ff6bc0fb00404\",\n \"merchantId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n \"deviceModel\": \"Surfpad\",\n \"reasonForReturn\": \"NOT_USING_SERVICE\",\n \"stopBilling\": true,\n \"comment\": \"Device not working properly\",\n \"isUnregistered\": false\n }\n ]\n }\n ],\n \"message\": \"Return requests gotten successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Query Parameters for the supported paging parameters.\n\n---" }, { "title": "Get Shipment Status", "slug": "logistics-get-shipment-status", "description": "Retrieves the status of the shipment order. Use this API to get the shipment status of ordered terminals and other accessories.", "api": "Logistics API", "method": "GET", "path": "/partners/:partnerId/merchants/:merchantId/shipment/:orderId", "content": "# Get Shipment Status\n\n## Overview\nRetrieves the status of the shipment order. Use this API to get the shipment status of ordered terminals and other accessories.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `orderId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants/:merchantId/shipment/:orderId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `orderId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/merchants/:merchantId/shipment/:orderId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'.. |\n| `data` | `object` | Response data |\n|     `orderStatus` | `string` | Describes the status of the shipment order for terminals and accessories. Possible values: `ORDER_PLACED`, `ORDER_SHIPPED`, `ORDER_COMPLETED`, `ORDER_PENDING_FOR_STOCK`. |\n|     `trackingUrl` | `string` | The tracking url of the shipment. |\n|     `trackingCode` | `string` | The carrier's tracking code for the shipment. |\n|     `deliveryPartner` | `string` | The partner or carrier responsible for delivering the shipment. |\n|     `packages` | `array` | Specifies information about the products included in the shipment. |\n|         `productId` | `string` | The SurfboardProductId of the product or group of products. This is unique to the partner |\n|         `serialNumber` | `string` | Serial number of the device. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"orderStatus\": \"ORDER_PENDING_FOR_STOCK\",\n \"trackingUrl\": \"\",\n \"trackingCode\": \"\",\n \"deliveryPartner\": \"DHL\",\n \"packages\": [\n {\n \"productId\": \"817361bb0a23400701\",\n \"serialNumber\": \"\"\n }\n ]\n },\n \"message\": \"Order status fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `orderId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Ship Terminals in Bulk", "slug": "logistics-ship-terminals-in-bulk", "description": "Creates bulk shipment orders for terminals and other accessories to partners. Use this API to initiate orders to ship multiple terminals and accessories in bulk.", "api": "Logistics API", "method": "POST", "path": "/partners/:partnerId/logistics/orders", "content": "# Ship Terminals in Bulk\n\n## Overview\nCreates bulk shipment orders for terminals and other accessories to partners. Use this API to initiate orders to ship multiple terminals and accessories in bulk.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/logistics/orders\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `shippingAddress` | `object` | No | Shipping address for the bulk order. |\n|     `name` | `string` | Yes | Full name of the receiver for the shipment. |\n|     `addressLine1` | `string` | Yes | The first line of the receiver's address. |\n|     `addressLine2` | `string` | No | The second line of the receiver's address. |\n|     `addressLine3` | `string` | No | The third line of the receiver's address. |\n|     `city` | `string` | Yes | City of the receiver. |\n|     `countryCode` | `string` | Yes | Two-letter ISO country code of the receiver, in uppercase. |\n|     `postalCode` | `string` | Yes | Postal code of the receiver. |\n|     `phoneNumber` | `object` | No | Contact number of the receiver in code and number format. |\n|         `code` | `string` | Yes | International dialing code identifying the country or region. |\n|         `number` | `string` | Yes | Phone number. |\n|     `email` | `string` | No | Email address of the receiver. |\n|     `deliveryInstruction` | `string` | No | Delivery instructions for the carrier. |\n| `lineItems` | `array` | Yes | An array of products to be shipped in bulk. |\n|     `productId` | `string` | Yes | The SurfboardProductId of the product or group of products. |\n|     `quantity` | `number` | Yes | Number of products or group of products to be shipped. |\n|     `billingPlanId` | `string` | No | Optional billing plan for the product or group of products chosen. |\n|     `replacementFor` | `string` | No | If this line item is placed as part of a replacement for an existing device, then the terminalId of the original device needs to be specified. |\n\n### Request Example\n```json\n{\n \"shippingAddress\": {\n \"name\": \"Jane Smith\",\n \"addressLine1\": \"456 Business Ave\",\n \"addressLine2\": \"Floor 2\",\n \"city\": \"Stockholm\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"12345\"\n },\n \"lineItems\": [\n {\n \"productId\": \"81bddf38fa28380101\",\n \"quantity\": 5,\n \"billingPlanId\": \"BP_001\",\n \"replacementFor\": \"82674cfdf77f500001\"\n }\n ]\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data |\n|     `orderId` | `string` | Order ID for the bulk order. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"orderId\": \"83992e47b219100f28\"\n },\n \"message\": \"Bulk logistic order created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Check Application Status", "slug": "merchants-check-application-status", "description": "Retrieves the status of a merchant onboarding application. After creating a merchant application, poll this endpoint to follow the application from APPLICATION_INITIATED to MERCHANT_CREATED, fetch the current web KYB link, and read the merchant ID and store ID once the merchant is live. The same IDs are also delivered through the webhook.", "api": "Merchants API", "method": "GET", "path": "/partners/:partnerId/merchants/:applicationId/status", "content": "# Check Application Status\n\n## Overview\nRetrieves the status of a merchant onboarding application. After creating a merchant application with the Create Merchant API, poll this endpoint to follow the application from `APPLICATION_INITIATED` to `MERCHANT_CREATED`. The response also carries the current web KYB link while the application is open, so you never need to store the link from the create call, and the merchant ID and store ID once the merchant is live. After the merchant is created, the same IDs are also available through the webhook.\n\n## Prerequisites\n- A partner account with Surfboard\n- An existing merchant application initiated through the Create Merchant API.\n- Authentication using API Key and API Secret.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants/:applicationId/status\n```\n\n### Headers\n| Header | Value | Required |\n|--------|-------|----------|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n\n### Path Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| `partnerId` | string | Your partner ID. |\n| `applicationId` | string | The application ID returned by the Create Merchant API. |\n\n### Query Parameters\nN/A\n\n### Request Body Parameters\nN/A\n\n### Request Example\n```json\n{\n \"headers\": {\n \"Content-Type\": \"application/json\",\n \"API-KEY\": \"YOUR_API_KEY\",\n \"API-SECRET\": \"YOUR_API_SECRET\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| data | object | Response data |\n| data.applicationId | string | The Application ID of the respective merchant returned by the Create Merchant API. |\n| data.webKybUrl | string | This is the link for the KYC session created for the merchant, which can be fetched for applications in state 'APPLICATION_INITIATED' or 'APPLICATION_PENDING_INFORMATION'. This URL will be returned for ISV(Independent Software Vendors) partners only. |\n| data.applicationStatus | string | Describes the status of the application. Possible values are described in the nested table below. |\n| data.merchantId | string | Merchant ID of the created merchant is returned when application status is 'MERCHANT_CREATED' |\n| data.storeId | string | Store ID of the store created under the merchant is returned when application status is 'MERCHANT_CREATED' |\n| data.billingPlans | array | Billing plans associated with the merchant application. |\n| data.billingPlans[].id | string | Unique identifier of the billing plan. |\n| data.billingPlans[].cardBrand | string | Card brand the billing plan applies to. |\n| data.billingPlans[].terminalType | string | Terminal type the billing plan applies to. |\n| data.billingPlans[].paymentMethod | string | Payment method the billing plan applies to. |\n| data.billingPlans[].planType | string | Type of the billing plan. |\n| data.billingPlans[].description | string | Human-readable description of the billing plan. |\n| data.onlineOnboardingStatus | string | Status of the online onboarding process for the merchant. Can be null if not applicable. |\n| data.paymentMethods | array | Payment methods configured for the merchant. |\n| data.paymentMethods[].paymentMethod | string | Name of the payment method, e.g. `CARD`, `SWISH`. |\n| data.paymentMethods[].enabledSchemes | array | Card schemes enabled for the method, e.g. `[\"VISA\", \"MASTERCARD\"]`. |\n| data.paymentMethods[].status | string | Status of the payment method for the merchant, e.g. `ACTIVE`. |\n| data.domainVerification | array | Domain verification records for the merchant's online store. Empty when the merchant has no online store or verification has not started. |\n| data.domainVerification[].domainName | string | Domain name being verified. |\n| data.domainVerification[].domainStatus | string | Verification status of the domain. |\n| data.domainVerification[].domainVerificationKey | string | Key the merchant uses to verify ownership of the domain. |\n| data.domainVerification[].verifyDomainType | string | Type of domain verification being performed. |\n| data.domainVerification[].isDomainVerified | boolean | Whether the domain has been verified. |\n| data.domainVerification[].verificationMethod | string | Method used to verify the domain. |\n| message | string | A message that describes the status of the request. |\n\n#### Possible values for `data.applicationStatus`:\n\n| Value | Description |\n|---|---|\n| APPLICATION_INITIATED | The application has been created, and the Web KYB URL has been generated. The merchant is now required to fill in necessary information through the Web KYB. |\n| APPLICATION_STARTED | The merchant has started filling in the Web KYB form but has not yet submitted it. |\n| APPLICATION_SUBMITTED | The merchant has finished filling in the Web KYB and submitted it for processing. |\n| APPLICATION_PENDING_INFORMATION | The application is still under processing, and additional data is required from the merchant. |\n| APPLICATION_SIGNED | All required signatories and beneficial owners (UBOs) have signed the application. |\n| APPLICATION_REJECTED | The application has been processed and rejected. |\n| APPLICATION_COMPLETED | The application has been processed and accepted. It is now pending merchant creation and onboarding. |\n| APPLICATION_EXPIRED | Each application is valid for 30 days. If there is no action during these 30 days, the KYB is treated as session expired. |\n| MERCHANT_CREATED | The merchant account has been created. At this stage, the Merchant ID and Store ID will be returned in the status call. |\n\n### Success Response Example\n\nWhile the merchant is still working through the web KYB:\n\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"applicationId\": \"845adba035abb00310\",\n \"webKybUrl\": \"https://onboarding.surfboard.se/845adba035abb00310?pi=…\",\n \"applicationStatus\": \"APPLICATION_SUBMITTED\",\n \"merchantId\": \"83af75d53169b0070e\",\n \"storeId\": \"845adbc0a3f2b00711\",\n \"onlineOnboardingStatus\": \"PENDING\",\n \"billingPlans\": [],\n \"paymentMethods\": [\n { \"paymentMethod\": \"card\", \"enabledSchemes\": [\"VISA\", \"MASTERCARD\"], \"status\": \"ACTIVE\" }\n ],\n \"domainVerification\": []\n },\n \"message\": \"Application status fetched successfully\"\n}\n```\n\nOnce the merchant is live:\n\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"applicationId\": \"81409507c1a5f00110\",\n \"applicationStatus\": \"MERCHANT_CREATED\",\n \"merchantId\": \"81412e2e4102f80f0e\",\n \"storeId\": \"81412e3c3b1090060f\",\n \"onlineOnboardingStatus\": \"PENDING_VERIFICATION\",\n \"billingPlans\": [\n {\n \"id\": \"81412e3c3b1090060f\",\n \"cardBrand\": \"VISA\",\n \"terminalType\": \"sb_terminal_c\",\n \"paymentMethod\": \"CARD\",\n \"planType\": \"TRANSACTION\",\n \"description\": \"Standard Transaction Plan\"\n }\n ],\n \"paymentMethods\": [\n { \"paymentMethod\": \"CARD\", \"enabledSchemes\": [\"VISA\", \"MASTERCARD\"], \"status\": \"ACTIVE\" },\n { \"paymentMethod\": \"SWISH\", \"enabledSchemes\": [], \"status\": \"ACTIVE\" }\n ],\n \"domainVerification\": [\n {\n \"domainName\": \"shop.example.se\",\n \"domainStatus\": \"VERIFIED\",\n \"domainVerificationKey\": \"sb-verify-81412e3c3b\",\n \"verifyDomainType\": \"DNS\",\n \"isDomainVerified\": true,\n \"verificationMethod\": \"TXT_RECORD\"\n }\n ]\n },\n \"message\": \"Application status fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"data\": null,\n \"message\": \"Invalid Application ID\"\n}\n```\n**Description:** The provided Application ID is invalid or does not exist. Ensure the Application ID is correct and corresponds to an existing application.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"data\": null,\n \"message\": \"Invalid API Key or API Secret\"\n}\n```\n**Description:** The API Key or API Secret provided in the request headers is invalid. Verify that the API Key and API Secret are correct and properly configured for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"data\": null,\n \"message\": \"Partner not found\"\n}\n```\n**Description:** The specified Partner ID does not exist. Double-check that the provided Partner ID is correct.\n\n## Notes\n- The current onboarding link for an application is always available from this endpoint, so there is no need to create a second application to recover a lost link. Each Create Merchant call creates a new application.\n- The `webKybUrl` is only returned for ISV (Independent Software Vendors) partners and only while the application is open to the merchant, i.e. in the 'APPLICATION_INITIATED' or 'APPLICATION_PENDING_INFORMATION' states.\n- The Merchant ID and Store ID are returned only when the application status is 'MERCHANT_CREATED'. Billing plans, payment methods and domain verification records fill in as the merchant is configured.\n- Each application is valid for 30 days. If there is no action during these 30 days, the KYB is treated as session expired, and the status will be 'APPLICATION_EXPIRED'.\n\n---" }, { "title": "Create Merchant", "slug": "merchants-create-merchant", "description": "As a partner, use the Create Merchant API to start a merchant onboarding programmatically and receive a ready-to-use web KYB link. Pre-enter the merchant's details and Surfboard resolves the company's registry data, classifies the business into a merchant category, and returns a link that is already populated. The merchant only adds their bank account, any category-specific documents, and the signatures.", "api": "Merchants API", "method": "POST", "path": "/partners/:partnerId/merchants", "content": "# Create Merchant\n\n## Overview\nAs a partner, use the Create Merchant API to start a merchant onboarding programmatically and receive a ready-to-use web onboarding link (**web KYB**) that you hand to the merchant to finish.\n\nWhen you pre-enter the merchant's details, Surfboard does two things before returning the link:\n\n1. **Registry prefill** -- the company's registry data (legal name, address, directors and beneficial owners where available) is resolved from the national business registry for the merchant's country.\n2. **Business classification (MCC)** -- the free-text `businessDescription` is classified into a merchant category, which in turn determines the exact documents the merchant must supply (for example a taxi licence or association statutes) and any category-specific questions.\n\nThe link that comes back is therefore already populated. The merchant only has to add what a partner cannot know for them: their **bank account** details, any **required documents** for their business category, and the **signing** (identity verification and e-signature) of the signatories and beneficial owners.\n\nIf any part of the prefill cannot be resolved, the call still succeeds and returns a working link. The merchant simply fills those sections in the web KYB flow as normal. Prefill is an accelerator, never a blocker.\n\nYou can also display products (terminals, accessories and so on from Surfboard) for your merchants to choose, set product pricing plans, show the product catalogue, pre-select products, and create the merchant's first store in the same call.\n\n## Prerequisites\n- Partner account with API key and secret.\n- Authentication is required using the `API-KEY` and `API-SECRET` headers.\n- Ensure the partner ID is correctly included in the URL.\n- Merchant applications in test and demo environments are configured for automatic approval.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/merchants\n```\n\n### Path Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| `partnerId` | string | Your partner ID. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThe body has three parts:\n\n- `country` and `organisation` -- who the merchant is. Required.\n- `controlFields` -- how the onboarding should behave (store, acquirer, flags). Optional.\n- `controlFields.preEnteredInformation` -- the data you prefill on the merchant's behalf. Optional, but this is what unlocks the accelerated flow.\n\n#### Top level\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `country` | string | Yes | Merchant's country of registration as a two-letter ISO code in uppercase. One of `SE`, `NO`, `DK`, `FI`, `IE`. |\n| `localeSelected` | string | No | UI language for the web KYB link, e.g. `sv`, `da`, `fi`, `en`. Defaults to the country's language. |\n| `organisation` | object | Yes | The legal entity. See below. |\n| `multiMerchantId` | string | No | Attach this merchant to an existing multi-merchant group. |\n| `controlFields` | object | No | Onboarding configuration. See below. |\n\n#### `organisation`\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `corporateId` | string | Yes | National company or organisation number. Format is validated per `country`. |\n| `legalName` | string | Conditional | Registered legal name. Resolved from the registry if omitted. Mandatory for a PF partner. |\n| `mccCode` | string | Conditional | A specific merchant category code, if you already know it. Otherwise it is derived from `businessDescription`. Mandatory for a PF partner. |\n| `address` | object | Conditional | Registered address. Resolved from the registry if omitted. Mandatory for a PF partner. |\n|     `careOf` | string | No | Name of the addressee that is accepting the correspondence for the intended recipient. |\n|     `addressLine1` | string | Yes | Address of the organisation. |\n|     `addressLine2` | string | No | Address of the organisation. |\n|     `addressLine3` | string | No | Address of the organisation. |\n|     `city` | string | Yes | City where the organisation is located. |\n|     `countryCode` | string | Yes | Two-letter ISO country code in uppercase, representing the country where the organisation is located. |\n|     `postalCode` | string | Yes | Postal code of the organisation. |\n| `phoneNumber` | object | No | Contact number of the organisation in code and number format, e.g. `{ \"code\": \"46\", \"number\": \"701234567\" }`. |\n|     `code` | string | Yes | International dialing code identifying the country or region. |\n|     `number` | string | Yes | Phone number. |\n| `email` | string | Conditional | Company contact email. Mandatory for a PF partner. |\n\n#### `controlFields`\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `store` | object | No | Create the merchant's first store in the same call. See `controlFields.store` below. |\n| `preEnteredInformation` | object | No | Prefilled purpose, people and trading details. See `controlFields.preEnteredInformation` below. |\n| `acquirerConfig` | object | Conditional | Card-acquiring configuration. **Only applicable to payment facilitator (PF) programmes and direct-merchant onboarding.** Values are provided by Surfboard for your programme; leave unset otherwise. |\n|     `currency` | string | No | Currency code for the acquirer configuration (e.g. `SEK`, `EUR`). |\n|     `acquirer` | string | No | Name of the acquirer (e.g. `nets`, `swedbank`). |\n|     `acquirerMID` | string | No | Acquirer merchant ID for transaction processing. |\n|     `acquirerIID` | string | No | Acquirer institution ID. |\n| `merchantConfig` | object | No | Configuration settings for the merchant. |\n|     `settlementFrequency` | string | No | Payout cadence. One of `daily`, `twiceWeekly`, `weekly`, `tenDays`, `fortNightly`, `monthly`, `everyTwoMonths`, `trimester`, `quarterly`, `twiceYearly`. Further values on request. |\n|     `serviceProvider` | array | No | Service provider fee split for the merchant. See the [Service Providers API](https://developers.surfboardpayments.com/api/service-providers). |\n|         `serviceProviderId` | string | Yes | Unique identifier of the service provider. |\n|         `deductApplicableTransactionFee` | boolean | No | Whether to deduct applicable transaction fees from the service provider's share. |\n|         `amount` | object | No | Fee structure for the service provider. |\n|             `percentage` | string | No | Percentage-based fee. |\n|             `fixed` | number | No | Fixed fee amount. |\n|             `adjustmentTypes` | array | No | Adjustment types the share is taken from, e.g. `[\"TIPS\"]`. |\n| `transactionPricingPlan` | string | No | Billing or pricing plan ID used to calculate transaction cost. Defaults to your programme's default plan. If more than one billing plan exists it is mandatory to send this value. |\n| `displayProducts` | array | No | Hardware or product IDs to show in the catalogue step. |\n|     `productId` | string | Yes | Product ID of a product to display. |\n|     `pricingPlans` | array | No | A list of strings specifying the billing plan for a merchant, based on the monthly price for a terminal and the duration in months. The specific plan details are provided by Surfboard. |\n| `preSelectProducts` | array | No | Products pre-added to the merchant's basket. These products are shipped as part of the onboarding process without further input from the merchant. |\n|     `productId` | string | Yes | Product ID of a product selected for delivery to the merchant. |\n|     `pricingPlanId` | string | No | Billing plan for the product, based on the monthly price for a terminal and the duration in months. |\n|     `quantity` | string | No | Quantity of the product. |\n| `linkUsers` | string[] | No | Existing user IDs to link to the new merchant. |\n| `generateShortLink` | boolean | No | Also return a shortened onboarding link. Default `false`. |\n| `redirectUrl` | string (URL) | No | Where to send the merchant after they finish the web KYB. |\n| `showProductCatalogue` | boolean | No | Whether the merchant sees the hardware or product step. **Requires the product catalogue to be enabled for your programme**; defaults to your programme setting. |\n| `directMerchantCreation` | boolean | No | Create the merchant directly rather than as an onboarding application. **Only applicable if your programme has a direct acquirer agreement**; leave unset otherwise. |\n| `disableFields` | object | No | Lock sections against merchant edits. |\n|     `onlineInfo` | boolean | No | When `true`, locks the website and e-commerce URLs and **requires** `store.onlineInfo` (with `merchantWebshopURL`, `termsAndConditionsURL`, `privacyPolicyURL`) in the same request. |\n| `paymentMethods` | object | No | Configuration for payment methods to be enabled for the merchant. |\n|     `card` | object | No | Card payment method configuration. Can be a boolean to enable or disable, or an object with specific settings. |\n|         `billingPlan` | string | No | Billing plan for card payments. |\n|         `mId` | string | No | Merchant ID for card payments. |\n|         `scheme` | array | Yes | Array of supported card schemes. Possible values: `visa`, `mastercard`. |\n|     `amex` | object | No | American Express payment method configuration. Can be a boolean to enable or disable, or an object with specific settings. |\n|         `mId` | string | Yes | American Express merchant ID. Required when configuring AMEX. |\n|     `swish` | object | No | Swedish mobile payment method configuration. Can be a boolean to enable or disable, or an object with specific settings. |\n|         `billingPlan` | string | No | Billing plan for Swish payments. |\n|         `swishNumber` | string | No | Optional Swish number for the payment method configuration. |\n|     `klarna` | object | No | Buy now, pay later payment method configuration. Can be a boolean to enable or disable, or an object with specific settings. |\n|         `billingPlan` | string | No | Billing plan for Klarna payments. |\n|         `mId` | string | No | Klarna merchant ID. |\n|         `klarnaPricingPlan` | string | No | Klarna pricing plan configuration. |\n|         `username` | string | Yes | Klarna account username. Required when configuring Klarna. |\n|         `password` | string | Yes | Klarna account password. Required when configuring Klarna. |\n|     `b2binv` | object | No | B2B invoice payment method configuration. Can be a boolean to enable or disable, or an object with specific settings. |\n|         `billingPlan` | string | No | Billing plan for B2B invoice payments. |\n|         `clientId` | string | No | Client ID for the B2B invoice payment method. |\n|         `clientSecretKey` | string | No | Client secret key for the B2B invoice payment method. |\n|     `acc2acc` | object | No | Account-to-account transfer payment method configuration. Can be a boolean to enable or disable, or an object with specific settings. |\n|         `billingPlan` | string | No | Billing plan for account-to-account payments. |\n|         `mId` | string | No | Merchant ID for account-to-account transfers. |\n|     `vipps` | boolean | No | Norwegian mobile payment method. Set to `true` to enable Vipps. |\n|     `mobilepay` | boolean | No | Danish mobile payment method. Set to `true` to enable MobilePay. |\n\n#### `controlFields.store`\n\nInclude this to create the merchant's first store during onboarding.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `name` | string | Yes (if `store` present) | Store or trading name. |\n| `email` | string | No | Store contact email. |\n| `phoneNumber` | object | No | Contact number of the store in code and number format. |\n|     `code` | string | Yes | International dialing code identifying the country or region. |\n|     `number` | string | Yes | A string of numbers ranging from 0-9 with a length of 5-15 characters. |\n| `address` | object | Yes (if `store` present) | The address of the store. |\n|     `careOf` | string | No | Name of the addressee that is accepting the correspondence for the intended recipient. |\n|     `addressLine1` | string | Yes | Address of the store. |\n|     `addressLine2` | string | No | Address of the store. |\n|     `addressLine3` | string | No | Address of the store. |\n|     `city` | string | Yes | City where the store is located. |\n|     `countryCode` | string | Yes | Two-letter ISO country code in uppercase, representing the country where the store is located. |\n|     `postalCode` | string | Yes | Postal code of the store. |\n| `onlineInfo` | object | No | E-commerce details. Required to start accepting online payments. |\n|     `merchantWebshopURL` | string | Yes | The web shop URL of the merchant. |\n|     `paymentPageHostURL` | string | No | The URL of the payment page. Required for integrating online payments using SDK mode. |\n|     `termsAndConditionsURL` | string | Yes | The URL of the terms and conditions of the merchant's web shop. It has to contain the refund policy. |\n|     `privacyPolicyURL` | string | Yes | The URL of the privacy policy of the merchant. |\n|     `googlePayMerchantId` | string | No | The Google Pay merchant ID of the merchant. |\n| `paymentChannels` | object | No | Where the merchant takes payments. At least one channel must be `true`. |\n|     `physical` | boolean | Yes | The merchant takes payments in person. |\n|     `online` | boolean | Yes | The merchant takes payments online. |\n|     `physicalSharePercent` | number | No | Share of turnover taken in person (1-99). Only meaningful when **both** channels are used. |\n\n#### `controlFields.preEnteredInformation`\n\nEverything here is optional; supply what you know. Supplying `businessDescription` is what triggers automatic category (MCC) classification.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `businessDescription` | string | No | What the merchant will **primarily use the payment solution for**: the specific activity that will generate card transactions (what and where they actually take payment for), **not** the general company purpose. E.g. *\"Selling coffee and pastries at our café\"*. Drives automatic category (MCC) classification, which sets the required documents and category questions. |\n| `applicant` | object | No | The main contact. See People below. |\n| `signatories` | array | No | Additional authorised signatories. See People below. |\n| `ubos` | array | No | Additional beneficial owners (UBOs). See People below. |\n| `chairpersons` | array | No | Chairpersons. See People below. |\n| `openingInfo` | object | No | Opening pattern. See Trading details below. |\n| `giftcards` | object | No | Only if the merchant sells gift cards. See Trading details below. |\n| `prePayments` | object | No | Only if the merchant takes prepayments. See Trading details below. |\n| `fundsInfo` | object | No | Expected turnover profile. See Trading details below. |\n\n##### People\n\nYou may prefill the people involved. **When you supply a person, give at least their `name` and `email`.** A person can hold more than one role.\n\n> **Who receives a signing link:** signing invitations go only to the people who must sign, i.e. the **signatories** and **beneficial owners (UBOs)**. Being the `applicant` or a `chairperson` alone does not trigger a signing link; that person signs only if they are also a signatory or UBO.\n\n**`applicant`** -- the main contact (object):\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `email` | string | Yes (if `applicant` present) | Applicant's email. Receives a signing invitation only if the applicant is a signatory or beneficial owner. |\n| `name` | string | Recommended | Applicant's full name. |\n| `isSignatory` | boolean | No | Is an authorised signatory. |\n| `isUbo` | boolean | No | Is a beneficial owner (UBO). |\n| `isChairman` | boolean | No | Is the chairperson. |\n| `ownershipPercent` | number | No | Ownership percentage (0-100). **Only relevant when `isUbo` is `true`.** |\n| `ownershipType` | string | No | `direct` or `indirect` (owned via another company). **Only relevant when `isUbo` is `true`.** |\n| `entityName` | string | Conditional | The intermediary company through which ownership is held. **Required if `ownershipType` is `indirect`.** Applies only to a beneficial owner. |\n\n> The three ownership fields (`ownershipPercent`, `ownershipType`, `entityName`) describe beneficial ownership and only apply when the applicant is a UBO (`isUbo: true`). Omit them for a person who is only a signatory or chairperson.\n\n**`signatories`** -- additional authorised signatories (array of objects):\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `name` | string | Yes | Signatory's full name. |\n| `email` | string | Yes | Signatory's email. Receives a signing invitation. |\n\n**`ubos`** -- additional beneficial owners (array of objects):\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `name` | string | Yes | Owner's full name. |\n| `email` | string | Yes | Owner's email. Receives a signing invitation. |\n| `ownershipPercent` | number | No | Ownership percentage (0-100). |\n| `ownershipType` | string | No | `direct` or `indirect` (via another company). |\n| `entityName` | string | Conditional | Intermediary company name. **Required if `ownershipType` is `indirect`.** |\n\n**`chairpersons`** -- chairpersons (array of objects):\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `name` | string | Yes | Chairperson's full name. |\n| `email` | string | Yes | Chairperson's email. No signing link unless they are also a signatory or UBO. |\n\n##### Trading details\n\n**`openingInfo`** -- opening pattern (object). Backend rules: `isOpenAllYear` and `isSeasonalOpen` must be **opposite** (exactly one `true`); if not open all year, `monthsOpen` is required; if `isStoreOpenAtNight` is `true`, `reasonForOpeningAtNight` is required.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `isOpenAllYear` | boolean | Yes (if `openingInfo` present) | Open year-round. |\n| `isSeasonalOpen` | boolean | Yes (if `openingInfo` present) | Seasonal. Must be the opposite of `isOpenAllYear`. |\n| `monthsOpen` | number[] | Conditional | Months open (1-12). Required when not open all year. |\n| `isStoreOpenAtNight` | boolean | Yes (if `openingInfo` present) | Trades at night. |\n| `reasonForOpeningAtNight` | string | Conditional | Required when `isStoreOpenAtNight` is `true`. |\n\n**`giftcards`** -- only if the merchant sells gift cards (object):\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `revenueSharePercent` | number | Yes (if `giftcards` present) | Percentage share of the merchant's yearly revenue that comes from gift-card sales (0-100). |\n| `averageValidDays` | number | Yes (if `giftcards` present) | Average validity period of a gift card, in days. |\n\n**`prePayments`** -- only if the merchant takes prepayments (object):\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `salesPercentPerYear` | number | Yes (if `prePayments` present) | Percentage of yearly sales taken as prepayment (0-100). |\n| `averageDeliveryTimeInDays` | number | Yes (if `prePayments` present) | Average time between payment and delivery of goods or services, in days. |\n\n**`fundsInfo`** -- expected turnover profile (object):\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `averageTransactionValuePerDay` | number | Yes (if `fundsInfo` present) | Average value transacted per day. |\n| `estimatedAmountPerYear` | number | Yes (if `fundsInfo` present) | Estimated annual card turnover. |\n| `priceOfMostExpensiveItemSold` | number | Yes (if `fundsInfo` present) | Price of the single most expensive item or service. |\n| `estimatedAmountPerTransaction` | number | Yes (if `fundsInfo` present) | Average transaction value. |\n| `estimatedFrequencyOfTransactions` | string | Yes (if `fundsInfo` present) | Transaction frequency. One of `DAILY` (multiple times per day), `WEEKLY` (a few times per week), `MONTHLY` (a few times per month), `YEARLY` (a few times per year). |\n| `estimatedNoOfDailyTransactions` | number | Conditional | Average number of sales per day. Mandatory when `estimatedFrequencyOfTransactions` is `DAILY`. |\n\n### Request Example\n\nA Danish café, prefilled by the partner. The registry resolves the legal name and address from the corporate ID; the business description classifies the merchant and picks its required documents; the applicant is both signatory and sole direct owner, with a second, indirect owner listed under `ubos`.\n\n```json\n{\n \"country\": \"DK\",\n \"localeSelected\": \"da\",\n \"organisation\": {\n \"corporateId\": \"12345678\"\n },\n \"controlFields\": {\n \"generateShortLink\": true,\n \"store\": {\n \"name\": \"Havnens Café\",\n \"email\": \"hello@havnenscafe.dk\",\n \"phoneNumber\": { \"code\": \"45\", \"number\": \"31234567\" },\n \"address\": {\n \"addressLine1\": \"Havnegade 12\",\n \"city\": \"København\",\n \"countryCode\": \"DK\",\n \"postalCode\": \"1058\"\n },\n \"paymentChannels\": { \"physical\": true, \"online\": true, \"physicalSharePercent\": 80 }\n },\n \"preEnteredInformation\": {\n \"businessDescription\": \"Selling coffee, pastries and light lunches at our harbourside café.\",\n \"applicant\": {\n \"email\": \"owner@havnenscafe.dk\",\n \"name\": \"Mette Jensen\",\n \"isSignatory\": true,\n \"isUbo\": true,\n \"ownershipPercent\": 100,\n \"ownershipType\": \"direct\"\n },\n \"ubos\": [\n {\n \"name\": \"Lars Holm\",\n \"email\": \"lars@example.dk\",\n \"ownershipPercent\": 0,\n \"ownershipType\": \"indirect\",\n \"entityName\": \"Holm Holding ApS\"\n }\n ],\n \"openingInfo\": {\n \"isOpenAllYear\": true,\n \"isSeasonalOpen\": false,\n \"monthsOpen\": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],\n \"isStoreOpenAtNight\": false,\n \"reasonForOpeningAtNight\": \"\"\n },\n \"giftcards\": { \"revenueSharePercent\": 15, \"averageValidDays\": 365 },\n \"fundsInfo\": {\n \"averageTransactionValuePerDay\": 4000,\n \"estimatedAmountPerYear\": 1200000,\n \"priceOfMostExpensiveItemSold\": 250,\n \"estimatedAmountPerTransaction\": 95,\n \"estimatedFrequencyOfTransactions\": \"DAILY\"\n }\n }\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | string | Status of the request: `SUCCESS` or `ERROR`. |\n| `message` | string | A message that describes the status of the request. |\n| `data` | object | Response data. |\n|     `applicationId` | string | ID of the onboarding application. Use it to check status. |\n|     `webKybUrl` | string | The link to hand to the merchant to complete onboarding. Treat it as sensitive: it grants access to the application. |\n|     `shortLinkUrl` | string | Shortened link, present when `generateShortLink` was `true`. |\n|     `validUntil` | string | Link expiry timestamp (ISO 8601). |\n|     `merchantId` | string | ID of the merchant record. |\n|     `storeId` | string | ID of the created store, when `store` was supplied. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Merchant application created successfully.\",\n \"data\": {\n \"applicationId\": \"845adba035abb00310\",\n \"webKybUrl\": \"https://onboarding.surfboard.se/845adba035abb00310?pi=…\",\n \"shortLinkUrl\": \"https://sb.fyi/abcd12\",\n \"validUntil\": \"2026-12-01T00:00:00.000Z\",\n \"merchantId\": \"83af75d53169b0070e\",\n \"storeId\": \"845adbc0a3f2b00711\"\n }\n}\n```\n\n## What the merchant completes\n\nAfter you create the application, the merchant opens `webKybUrl` and, because you prefilled the rest, only needs to:\n\n1. **Confirm the prefilled company and people**, already populated from the registry and your data.\n2. **Add their bank account** for settlement.\n3. **Upload any required documents** for their business category, determined automatically from `businessDescription`.\n4. **Complete signing**: each signatory and beneficial owner verifies their identity and e-signs.\n\nTrack progress with the [Check Application Status](https://developers.surfboardpayments.com/api/merchants) endpoint. When it reaches `MERCHANT_CREATED`, the merchant is live.\n\n## Error Responses\n\nOn failure the response is `{ \"status\": \"ERROR\", \"message\": \"\" }`.\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"data\": null,\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required fields, or a validation rule was broken (for example `isOpenAllYear` and `isSeasonalOpen` both `true`, an `indirect` owner without `entityName`, or `disableFields.onlineInfo` without `store.onlineInfo`). Review the request parameters and ensure all required fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"data\": null,\n \"message\": \"Invalid API key or secret.\"\n}\n```\n**Description:** The API key or secret is invalid. Verify that the API key and secret are correct and properly included in the request headers.\n\n#### 403 - Forbidden\n```json\n{\n \"status\": \"ERROR\",\n \"data\": null,\n \"message\": \"Insufficient permissions.\"\n}\n```\n**Description:** The partner does not have sufficient permissions to create a merchant. Contact Surfboard support to request the necessary permissions.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"data\": null,\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the error persists, contact Surfboard support.\n\n## Notes\n- **Prefill.** Registry data and category classification are resolved as part of the create call, so the returned link is already populated. If either cannot be resolved, the call still returns a valid link and the merchant completes those sections manually.\n- **Documents are category-driven.** The `businessDescription` sets the merchant category, which sets exactly which documents are mandatory (e.g. taxi licence, association statutes) and any category-specific questions. You do not specify documents in the request.\n- **Prefill is additive.** Anything you omit is simply collected from the merchant in the flow; nothing you prefill is discarded.\n- **One application per call.** Each call creates a new application, so avoid duplicate calls for the same merchant. The current link for an application is always available from the Check Application Status endpoint.\n- Conditional fields are required depending on the partner type (PF partner, direct merchant). For PF partners, providing organisation details and acquirer configuration is mandatory.\n- Make sure country codes are always in uppercase.\n- Merchant applications in test and demo environments are configured for automatic approval.\n\n---" }, { "title": "Fetch All Merchant Applications", "slug": "merchants-fetch-all-merchant-applications", "description": "Retrieves a list of all merchants applications with a specific partner.", "api": "Merchants API", "method": "GET", "path": "/partners/:partnerId/applications", "content": "# Fetch All Merchant Applications\n\n## Overview\nRetrieves a list of all merchants applications with a specific partner.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/applications\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/applications\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| `data` | `array` | Response data |\n|     `applicationId` | `String` | The Application ID used to uniquely identify a merchant's application. |\n|     `applicationStatus` | `string` | Describes the status of the application. Possible values: `APPLICATION_INITIATED`, `APPLICATION_SUBMITTED`, `APPLICATION_PENDING_INFORMATION`, `APPLICATION_SIGNED`, `APPLICATION_REJECTED`, `APPLICATION_COMPLETED`, `MERCHANT_CREATED`. |\n|     `corporateId` | `String` | Corporate ID of the respective merchant. |\n|     `country` | `String` | Two-letter ISO country code in uppercase, representing the primary location of the merchant. |\n|     `createdAt` | `String` | Date of application creation in ISO string format |\n|     `lastUpdatedAt` | `String` | Date of last updation recorded with the merchant application in ISO string format |\n|     `webKybUrl` | `String` | The Web KYB URL generated for the application. |\n|     `legalName` | `String` | Legal name of the organization associated with the application. |\n|     `endDate` | `String` | Date on which the application period ends, in ISO string format. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"applicationId\": \"816e0b8aabe6580310\",\n \"country\": \"SE\",\n \"corporateId\": \"1234567898\",\n \"applicationStatus\": \"MERCHANT_CREATED\",\n \"createdAt\": \"2023-07-10T07:17:41.489Z\",\n \"lastUpdatedAt\": \"2023-07-10T07:17:41.519Z\",\n \"webKybUrl\": \"https://surfkyb.com/816e0b8aabe6580310\",\n \"legalName\": \"Year Zero Press AB\",\n \"endDate\": \"2024-07-10T07:17:41.519Z\"\n },\n {\n \"applicationId\": \"816e0983abe6580a10\",\n \"country\": \"DK\",\n \"applicationStatus\": \"APPLICATION_INITIATED\",\n \"createdAt\": \"2023-07-10T07:00:23.106Z\",\n \"lastUpdatedAt\": \"2023-07-10T07:00:23.106Z\",\n \"webKybUrl\": \"https://surfkyb.com/816e0983abe6580a10\"\n }\n ],\n \"message\": \"Applications of partner fetched successfully with partnerId: 8113d3f8403b380409.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Query Parameters for the supported paging parameters.\n\n---" }, { "title": "Create Multi-merchant Group", "slug": "merchants-create-multi-merchant-group", "description": "Creates a multi-merchant group. Partners can use this API to create a multi-merchant group that enables multiple merchants to use the same terminal. Individual merchants are tagged to this group, enabling access to all the terminals registered in this group.", "api": "Merchants API", "method": "POST", "path": "/partners/:partnerId/multi-merchant", "content": "# Create Multi-merchant Group\n\n## Overview\nCreates a multi-merchant group. Partners can use this API to create a multi-merchant group that enables multiple merchants to use the same terminal. Individual merchants are tagged to this group, enabling access to all the terminals registered in this group.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/multi-merchant\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `country` | `string` | Yes | Two-letter ISO country code, in uppercase e.g 'SE', 'DK', 'NO'. |\n| `postalCode` | `string` | Yes | Postal code of the multi-merchant group's address. |\n| `name` | `string` | No | Name of the Multi-merchant group. |\n| `email` | `string` | No | Email address of the Multi-merchant group. |\n\n### Request Example\n```json\n{\n \"country\": \"SE\",\n \"postalCode\": \"123456\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request 'SUCCESS' \\| 'ERROR'. |\n| `data` | `object` | Response data |\n|     `applicationId` | `string` | This is the applicationId that you will use to track the status of the create multi-merchant group request. |\n|     `merchantId` | `string` | Multi-merchant ID. |\n|     `storeId` | `string` | Multi-merchant store ID. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"applicationId\": \"81376ad8ebedf80310\",\n \"merchantId\": \"81660b596c7fd0000e\",\n \"storeId\": \"81660b59434440030f\"\n },\n \"message\": \"Multi Merchant created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch All Merchant Contracts", "slug": "merchants-fetch-all-merchant-contracts", "description": "Retrieves the list of all contracts under the specific merchant.", "api": "Merchants API", "method": "GET", "path": "/merchants/:merchantId/contracts", "content": "# Fetch All Merchant Contracts\n\n## Overview\nRetrieves the list of all contracts under the specific merchant.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/contracts\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/contracts\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| `data` | `array` | Response data |\n|     `contractId` | `String` | The contract ID used to identify a contract. |\n|     `type` | `String` | Denotes type of the merchant contract. Possible values: `MERCHANT_AGREEMENT`. |\n|     `status` | `String` | Denotes the status of the merchant contract. It can be either 'ACTIVE' or 'INACTIVE' |\n|     `contractLink` | `String` | Link for the merchant contract. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"contractId\": \"81d9b757ea31c0013d\",\n \"type\": \"MERCHANT_AGREEMENT\",\n \"status\": \"ACTIVE\",\n \"contractLink\": \"https://storage.googleapis.com/test\"\n }\n ],\n \"message\": \"Fetched merchant agreement contracts successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch All Merchants", "slug": "merchants-fetch-all-merchants", "description": "Retrieves a list of all merchants associated with a specific partner. Partners can use this API to get information regarding all their sub-merchants.", "api": "Merchants API", "method": "GET", "path": "/partners/:partnerId/merchants", "content": "# Fetch All Merchants\n\n## Overview\nRetrieves a list of all merchants associated with a specific partner. Partners can use this API to get information regarding all their sub-merchants.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/merchants\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| `data` | `array` | Response data |\n|     `merchantId` | `String` | Merchant ID of the merchant. |\n|     `partnerId` | `String` | The Partner ID of the partner with whom the merchant is affiliated. |\n|     `merchantName` | `String` | Name of the merchant. |\n|     `merchantLanguage` | `String` | Preferred language selected by the merchant. |\n|     `merchantLogoUrl` | `String` | Merchant logo URL. |\n|     `email` | `String` | Email address of the merchant. |\n|     `companyId` | `String` | Company ID of the merchant. |\n|     `countryCode` | `String` | Two-letter ISO country code in uppercase, representing the primary location of the merchant. |\n|     `mccCode` | `String` | Merchant Category Code (MCC) of the merchant. |\n|     `createdAt` | `String` | Timestamp at which the merchant was created. |\n|     `totalNumberOfTransaction` | `String` | The total number of transactions performed. |\n|     `totalAmountOfTransaction` | `String` | The total amount of money involved in all transactions, in the smallest currency unit. |\n|     `lastTransactionAt` | `String` | The timestamp of the last transaction in ISO format. |\n|     `phoneNumber` | `String` | The contact phone number related to the merchant. |\n|     `totalSales` | `String` | Total value of sales transactions for the merchant, in the smallest currency unit. |\n|     `totalRefunds` | `String` | Total value of refunded transactions for the merchant, in the smallest currency unit. |\n|     `currencyCode` | `String` | Three-digit ISO currency code, representing the supported currency for the merchant. Returned only when the merchant has a payment-facilitator account. Can be any one of the following: ‘208’ \\| ‘978’ \\| ‘752’. |\n|     `acquirerMID` | `String` | Denotes the Acquirer MID for onboarding merchants through payment institution partners (PF or Acquirer). Returned only when the merchant has a payment-facilitator account. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"merchantId\": \"8248db4c5c8dd0130e\",\n \"partnerId\": \"8113d3f8403b380409\",\n \"merchantName\": \"Raynor LLC\",\n \"merchantLanguage\": \"sv\",\n \"merchantLogoUrl\": \"https://storage.googleapis.com/logo-raynor.png\",\n \"email\": \"sathish@surfboard.se\",\n \"companyId\": \"5590890439\",\n \"countryCode\": \"SE\",\n \"mccCode\": 8021,\n \"createdAt\": \"2024-06-06 06:03:49.125\",\n \"totalNumberOfTransaction\": \"11\",\n \"totalAmountOfTransaction\": \"2200\",\n \"lastTransactionAt\": \"2024-08-22 07:58:35.310568\",\n \"phoneNumber\": \"4623423423\",\n \"totalSales\": \"2200\",\n \"totalRefunds\": \"0\",\n \"currencyCode\": \"752\",\n \"acquirerMID\": \"gkjb4ug3KAUP\"\n },\n {\n \"merchantId\": \"81a25a0b304ed0070e\",\n \"partnerId\": \"8113d3f8403b380409\",\n \"merchantName\": \"Conroy, Hane\",\n \"merchantLanguage\": \"en\",\n \"merchantLogoUrl\": \"https://storage.googleapis.com/logo-conroy.png\",\n \"email\": \"conroy@gmail.com\",\n \"countryCode\": \"SE\",\n \"mccCode\": 5812,\n \"createdAt\": \"2022-11-04 13:41:46.81\",\n \"totalNumberOfTransaction\": \"1877\",\n \"totalAmountOfTransaction\": \"774628102\",\n \"lastTransactionAt\": \"2024-07-15 09:23:09.816546\",\n \"phoneNumber\": \"+468787870484\",\n \"totalSales\": \"774628102\",\n \"totalRefunds\": \"12000\",\n \"currencyCode\": \"752\",\n \"acquirerMID\": \"kpIy8YO3ycKyhKR\"\n }\n ],\n \"message\": \"Successfully fetched merchants details\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Query Parameters for the supported paging parameters.\n\n---" }, { "title": "Fetch All Multi-Merchant Groups", "slug": "merchants-fetch-all-multi-merchant-groups", "description": "Fetch all existing multi-merchant groups under a partner.", "api": "Merchants API", "method": "GET", "path": "/partners/:partnerId/multi-merchants", "content": "# Fetch All Multi-Merchant Groups\n\n## Overview\nFetch all existing multi-merchant groups under a partner.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/multi-merchants\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/multi-merchants\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| `data` | `array` | Response data |\n|     `multiMerchantId` | `String` | Multimerchant ID of the multi-merchant group. |\n|     `multiMerchantName` | `String` | Name of the multi-merchant group. |\n|     `countryCode` | `String` | Two-letter ISO country code in uppercase, representing the primary location of the multi-merchant group. |\n|     `postalCode` | `string` | Postal code of the multi-merchant. |\n|     `merchants` | `array` | List of merchants present under a multi-merchant group. |\n|         `merchantId` | `String` | Merchant ID of the merchant. |\n|         `merchantName` | `String` | Name of the merchant. |\n|         `countryCode` | `String` | Two-letter ISO country code in uppercase, representing the primary location of the merchant. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"multiMerchantId\": \"817544218dd838050e\",\n \"multiMerchantName\": \"Multi Merchant one\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"12345\",\n \"merchants\": [\n {\n \"merchantId\": \"817544960dd838040e\",\n \"merchantName\": \"Test Merchant one\",\n \"countryCode\": \"SE\"\n },\n {\n \"merchantId\": \"8175449a8dd8380d0e\",\n \"merchantName\": \"Test Merchant two\",\n \"countryCode\": \"SE\"\n }\n ]\n },\n {\n \"multiMerchantId\": \"81701e32ff5690020e\",\n \"multiMerchantName\": \"Multi Merchant two\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"12346\"\n }\n ],\n \"message\": \"Multi merchant groups fetched successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Query Parameters for the supported paging parameters.\n\n---" }, { "title": "Fetch Merchant Details", "slug": "merchants-fetch-merchant-details", "description": "Retrieves information for a specific merchant. As a partner you can use this API to get information regarding your sub-merchants", "api": "Merchants API", "method": "GET", "path": "/partners/:partnerId/merchants/:merchantId", "content": "# Fetch Merchant Details\n\n## Overview\nRetrieves information for a specific merchant. As a partner you can use this API to get information regarding your sub-merchants\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants/:merchantId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/merchants/:merchantId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| `data` | `object` | Response data |\n|     `merchantId` | `String` | Merchant ID of the merchant. |\n|     `merchantType` | `string` | Classification of the merchant account within Surfboard. Possible values: `STANDARD`, `DYNAMIC_MERCHANT`, `MARKETPLACE_MERCHANT`, `PF_MERCHANT`, `PF_TEST_MERCHANT`, `PARTNER_MERCHANT`, `TEST_MERCHANT`, `DEACTIVATED_MERCHANT`, `ISV_MERCHANT`, `BLOCKED_MERCHANT`. |\n|     `partnerId` | `String` | The Partner ID of the partner with whom the merchant is affiliated. |\n|     `currencyCode` | `Number` | Three-digit ISO currency code, representing the supported currency for the merchant. Can be any one of the following: ‘208’ \\| ‘978’ \\| ‘752’. |\n|     `merchantName` | `String` | Name of the merchant. |\n|     `merchantLanguage` | `String` | Preferred language selected by the merchant. |\n|     `merchantLogoUrl` | `String` | Merchant logo URL. |\n|     `email` | `String` | Email address of the merchant. |\n|     `companyId` | `String` | Company ID of the merchant. |\n|     `countryCode` | `String` | Two-letter ISO country code in uppercase, representing the primary location of the merchant. |\n|     `mccCode` | `String` | Merchant Category Code (MCC) of the merchant. |\n|     `address` | `object` | Physical address of the merchant. |\n|         `careOf` | `string` | Name of the addressee that is accepting the correspondence for the intended recipient. |\n|         `addressLine1` | `string` | Address of the merchant. |\n|         `addressLine2` | `string` | Address of the merchant. |\n|         `addressLine3` | `string` | Address of the merchant. |\n|         `city` | `string` | City where the merchant is located. |\n|         `countryCode` | `string` | Two-letter ISO country code in uppercase, representing the location of the merchant. |\n|         `postalCode` | `string` | Postal code of the merchant. |\n|     `createdAt` | `String` | Timestamp at which the merchant was created. |\n|     `totalNumberOfTransaction` | `String` | Total number of transactions performed by the merchant. |\n|     `totalAmountOfTransaction` | `String` | Denotes the total monetary value of all transactions performed by the merchant. |\n|     `lastTransactionAt` | `String` | Timestamp of the last transaction in ISO 8601 format represented as 'YYYY-MM-DDTHH:mm:ss.sssZ'. |\n|     `phoneNumber` | `String` | Phone number of the merchant. |\n|     `acquirerMID` | `String` | Denotes the Acquirer MID for onboarding merchants through payment institution partners(PF or Acquirer). |\n|     `totalSales` | `string` | Total value of sales transactions for the merchant, in the smallest currency unit. |\n|     `totalRefunds` | `string` | Total value of refunded transactions for the merchant, in the smallest currency unit. |\n|     `analytics` | `object` | Aggregated sales and refund counts for the current and previous month. |\n|         `countOfSales` | `number` | Total number of sales transactions recorded for the merchant. |\n|         `countOfRefunds` | `number` | Total number of refund transactions recorded for the merchant. |\n|         `currentMonthSale` | `number` | Value of sales in the current month, in the smallest currency unit. |\n|         `previousMonthSale` | `number` | Value of sales in the previous month, in the smallest currency unit. |\n|         `currentMonthCountOfSale` | `number` | Number of sales in the current month. |\n|         `previousMonthCountOfSale` | `number` | Number of sales in the previous month. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"merchantId\": \"81fa6b2d8d5dc8040e\",\n \"partnerId\": \"8113d3f8403b380409\",\n \"merchantName\": \"Conroy Hane and Parker\",\n \"merchantLanguage\": \"se\",\n \"merchantLogoUrl\": \"https://firebasestorage.googleapis.com/v0/b/firebase-test-2e49.appspot.com/o/files%2F8113d3f8403b380409%2FlogoUrl_1749127943794_emoji.png?alt=media&token=61077942-b4b3-482d-bd4d-1e3526486b7e\",\n \"email\": \"ashinisb@surfboard.se\",\n \"companyId\": \"5590520507\",\n \"countryCode\": \"SE\",\n \"mccCode\": 1520,\n \"phoneNumber\": \"917676576569\",\n \"merchantType\": \"STANDARD\",\n \"currencyCode\": \"752\",\n \"acquirerMID\": \"gfprLY1dyAQO\",\n \"address\": {\n \"careOf\": \"chennai\",\n \"addressLine1\": \"Stockholm\",\n \"addressLine2\": \"Diya ssssssTowers\",\n \"addressLine3\": \"process\",\n \"city\": \"Sweden\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"22331\"\n }\n },\n \"message\": \"Successfully fetched merchant details \"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Transaction Analytics", "slug": "merchants-fetch-transaction-analytics", "description": "Retrieves aggregated transaction analytics for a specific merchant. This can include analytics by store, terminal, date range, card brand, and more.", "api": "Merchants API", "method": "GET", "path": "/merchants/:merchantId/analytics", "content": "# Fetch Transaction Analytics\n\n## Overview\nRetrieves aggregated transaction analytics for a specific merchant. This can include analytics by store, terminal, date range, card brand, and more.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/analytics\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | No | Provide store ID to filter analytics for a specific store. |\n| `terminalId` | `string` | No | Provide terminal ID to filter analytics for a specific terminal. |\n| `startDate` | `string` | No | Start of the date range in yyyy-mm-dd format. |\n| `endDate` | `string` | No | End of the date range in yyyy-mm-dd format. |\n| `orderType` | `string` | No | Type of order to filter by. Possible values are 'purchase' and 'return'. |\n| `terminalType` | `string` | No | Type of terminal to filter results. Possible values: `surfpad`, `surftouch`, `surfprint`, `checkoutPro`, `checkoutX`, `softpos`, `PaymentPage`, `SelfHostedPage`, `MerchantInitiated`. |\n| `paymentMethod` | `string` | No | Payment method to filter analytics. |\n| `posEntryMode` | `string` | No | POS entry mode to filter by. |\n| `cardBrand` | `string` | No | Card brand to filter by. |\n| `currency` | `string` | No | Three digit numeric or ISO code representing currency. |\n| `groupBy` | `object` | No | Use this object to group analytics by store, terminal, etc. For example, groupBy[storeId]=true. |\n|     `storeId` | `boolean` | No | Set to true to group results by store. |\n|     `terminalId` | `boolean` | No | Set to true to group results by terminalId. |\n|     `orderType` | `boolean` | No | Set to true to group results by orderType. |\n|     `terminalType` | `boolean` | No | Set to true to group results by terminalType. |\n|     `paymentMethod` | `boolean` | No | Set to true to group results by paymentMethod. |\n|     `cardBrand` | `boolean` | No | Set to true to group results by cardBrand. |\n|     `posEntryMode` | `boolean` | No | Set to true to group results by posEntryMode. |\n|     `timeSegments` | `string` | No | Segments the analytics by time. Possible values are 'DAILY', 'WEEKLY', 'MONTHLY', 'QUARTERLY', 'YEARLY'.for example groupBy[timeSegments]=DAILY. |\n\n### Pagination\n\nTo filter analytics by date range, send in `startDate` and `endDate` as query params. You can also use additional query parameters like `storeId`, `terminalId`, `orderType`, etc. Grouping the results can be controlled via the `groupBy` object in the query.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/analytics?terminalId=YOUR_TERMINAL_ID&startDate=2024-01-01&endDate=2024-02-01\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | An array of analytics objects, each containing aggregated transaction information. |\n|     `currency` | `string` | The currency code for the transactions, typically a three-digit numeric code. |\n|     `storeId` | `string` | The store ID the transactions belong to. Present when results are grouped by this dimension. |\n|     `terminalId` | `string` | The terminal ID from which the transactions were made. |\n|     `terminalType` | `string` | Specifies the type of terminal. |\n|     `orderType` | `string` | The type of order. |\n|     `paymentMethod` | `string` | The payment method used. |\n|     `cardBrand` | `string` | The brand of the card, if paymentMethod is 'CARD'. This may be empty if no card brand applies. |\n|     `posEntryMode` | `string` | The POS entry mode used for the transactions. Present when results are grouped by this dimension. |\n|     `timeSegments` | `string` | The date/time segment in which these transactions occurred. |\n|     `orderTransactionCount` | `string` | Number of transactions that match this grouping or filter. |\n|     `totalTransactionAmount` | `number` | Aggregate sum of transaction amounts (in minor currency units) for this group. |\n| `message` | `string` | A message describing the status or outcome of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"currency\": \"752\",\n \"storeId\": \"82dd3f7c6a2ab00e03\",\n \"terminalId\": \"82dd3f9aad1ec80f04\",\n \"terminalType\": \"sb_terminal_c\",\n \"orderType\": \"PURCHASE\",\n \"paymentMethod\": \"CARD\",\n \"cardBrand\": \"VISA\",\n \"posEntryMode\": \"CONTACTLESS\",\n \"timeSegments\": \"2025-01-21 00:00:00\",\n \"orderTransactionCount\": \"1\",\n \"totalTransactionAmount\": 150\n },\n {\n \"currency\": \"752\",\n \"storeId\": \"82dd3f7c6a2ab00e03\",\n \"terminalId\": \"82dd3f9aad1ec80f04\",\n \"terminalType\": \"sb_terminal_c\",\n \"orderType\": \"PURCHASE\",\n \"paymentMethod\": \"CARD\",\n \"cardBrand\": \"MASTERCARD\",\n \"posEntryMode\": \"CONTACTLESS\",\n \"timeSegments\": \"2025-01-21 00:00:00\",\n \"orderTransactionCount\": \"3\",\n \"totalTransactionAmount\": 450\n }\n ],\n \"message\": \"Transaction Analytics Data queried successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Query Parameters for the supported paging parameters.\n\n---" }, { "title": "Update Merchant Details", "slug": "merchants-update-merchant-details", "description": "Updates the merchant details. You can use this API to edit the merchant name, preferred language, email address, merchant logo URL, and phone number of a merchant.", "api": "Merchants API", "method": "PUT", "path": "/partners/:partnerId/merchants/:merchantId", "content": "# Update Merchant Details\n\n## Overview\nUpdates the merchant details. You can use this API to edit the merchant name, preferred language, email address, merchant logo URL, and phone number of a merchant.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /partners/:partnerId/merchants/:merchantId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantName` | `string` | No | Name of the merchant. |\n| `merchantLanguage` | `string` | No | Preferred language for the merchant, as a two-letter language code, for example 'sv' or 'en'. |\n| `email` | `string` | No | Email address of the merchant. |\n| `merchantLogoUrl` | `string` | No | Merchant logo URL. |\n| `phoneNumber` | `object` | No | Contact number of the merchant in code and number format |\n|     `code` | `number` | No | International dialing code identifying the country or region. |\n|     `number` | `string` | No | A string of numbers ranging from 0-9 with a length of 5-15 characters. |\n\n### Request Example\n```json\n{\n \"merchantName\": \"Conroy Hane and Parker\",\n \"merchantLanguage\": \"sv\",\n \"email\": \"test@gmail.com\",\n \"phoneNumber\": {\n \"code\": 46,\n \"number\": \"771890089\"\n },\n \"merchantLogoUrl\": \"https://storage.googleapis.com/merchant-logo.png\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request 'SUCCESS' \\| 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Successfully updated the merchant details.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch External Notifications for Merchant", "slug": "notifications-fetch-external-notifications-for-merchant", "description": "Retrieves all external notifications configured for a merchant. Supports filtering by event type, notification channel, and notification ID", "api": "Notifications API", "method": "GET", "path": "/merchants/:merchantId/notifications", "content": "# Fetch External Notifications for Merchant\n\n## Overview\nRetrieves all external notifications configured for a merchant. Supports filtering by event type, notification channel, and notification ID\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/notifications\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\n\nTo filter notifications by specific criteria, send `event`, `notificationChannel`, or `notificationId` as query params.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `event` | `string` | No | Filter by event type. Possible values: `DAILY_REPORTS`, `MONTHLY_REPORTS`, `PAYMENT_COMPLETED`, `DAILY_FILE_TRANSFER`, `WEEKLY_FILE_TRANSFER`, `MONTHLY_FILE_TRANSFER`. |\n| `notificationChannel` | `string` | No | Filter by notification channel. Possible values: `EMAIL`, `SLACK`, `SFTP`. |\n| `notificationId` | `string` | No | Filter by notification ID |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/notifications?event=WEEKLY_FILE_TRANSFER¬ificationChannel=SFTP¬ificationId=839cfe66fe08b00bf3\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| `data` | `array` | Array of notification objects |\n|     `notificationId` | `string` | Unique identifier for the notification |\n|     `event` | `string` | Event type for the notification. Possible values: `DAILY_REPORTS`, `MONTHLY_REPORTS`, `PAYMENT_COMPLETED`, `DAILY_FILE_TRANSFER`, `WEEKLY_FILE_TRANSFER`, `MONTHLY_FILE_TRANSFER`. |\n|     `notificationChannel` | `string` | Channel used for notification delivery |\n|     `address` | `object` | Address configuration for the notification |\n|         `url` | `string` | URL for webhook notifications |\n|         `email` | `string` | Email address for email notifications |\n|         `host` | `string` | SFTP host address |\n|         `remoteDirectory` | `string` | SFTP remote directory |\n|         `user` | `string` | SFTP username |\n|         `port` | `number` | SFTP port number |\n|         `publicKey` | `string` | SFTP public key |\n|         `separator` | `string` | CSV field separator |\n|         `paymentStatuses` | `array` | Payment statuses the SFTP report is filtered to, when configured |\n|         `paymentTypes` | `array` | Payment types the SFTP report is filtered to, when configured |\n|         `includeColumns` | `array` | Columns included in the SFTP report, when configured |\n|     `status` | `string` | Status of the notification subscription |\n| `message` | `string` | A message that describes the status of the request |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"notificationId\": \"839cfe66fe08b00bf3\",\n \"event\": \"WEEKLY_FILE_TRANSFER\",\n \"notificationChannel\": \"SFTP\",\n \"address\": {\n \"host\": \"192.168.0.211\",\n \"user\": \"surfboard-test\",\n \"port\": 8080,\n \"publicKey\": \"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDPrhFN05QsXZPVGn3uHpRih3bJrRARfvqvyZ5RuRG78YXiVjfHszckpzcay7uF6fsMQes8ky4RGywHs7UfhWbXhu5EDE/swZzTtu8TRVmRhIL6K1o8VKFEEJat3+UgwgrkdKHpUyld3r2doNcViHDiBTiVW4O4JR98/XHrhR7Ge9EPxE/iVwyur+YREtt3RKdZV3d+NG+4WFRqaq70lM13z0u1lACP8PRl4dyRbjrpGoMGq2zDSvyerzS6fKg7jm1UBOt4wznu8pjIE+A+9xiNvzpnxG1q4GxwpRq8e8AY5WIvpngOpaiifEObAGWnauvWnenPwV/yvudTwK4bFQBV surfboard-test@192.168.0.211\",\n \"separator\": \",\",\n \"paymentStatuses\": [\n \"PAYMENT_COMPLETED\"\n ],\n \"paymentTypes\": [\n \"PURCHASE\",\n \"RETURN\"\n ],\n \"includeColumns\": [\n \"ADJUSTMENTS\"\n ]\n },\n \"status\": \"REGISTERED\"\n },\n {\n \"notificationId\": \"839d223b9df16805f3\",\n \"event\": \"PAYMENT_COMPLETED\",\n \"notificationChannel\": \"EMAIL\",\n \"address\": {\n \"email\": \"merchant@example.com\"\n },\n \"status\": \"SUBSCRIBED\"\n }\n ],\n \"message\": \"External notification for MERCHANT_ID: m_iWGri3XAyTmkbKYsYtV47 fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid notificationChannel. Must be one of: EMAIL, SLACK, SFTP\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Subscribe to Merchant Reports", "slug": "notifications-subscribe-to-merchant-reports", "description": "Subscribe to receive automated notifications for merchant events. You must provide at least one notification channel: email, slackUrl, or sftpInfo to create a notification subscription. This endpoint supports multiple notification channels including EMAIL, SLACK, and SFTP.", "api": "Notifications API", "method": "POST", "path": "/merchants/:merchantId/notifications/reports", "content": "# Subscribe to Merchant Reports\n\n## Overview\nSubscribe to receive automated notifications for merchant events. You must provide at least one notification channel: email, slackUrl, or sftpInfo to create a notification subscription. This endpoint supports multiple notification channels including EMAIL, SLACK, and SFTP.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /merchants/:merchantId/notifications/reports\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `event` | `string` | Yes | The event type to subscribe to for notifications. Possible values: `DAILY_REPORTS`, `MONTHLY_REPORTS`, `PAYMENT_COMPLETED`, `DAILY_FILE_TRANSFER`, `WEEKLY_FILE_TRANSFER`, `MONTHLY_FILE_TRANSFER`. |\n| `email` | `string` | No | Email address for notification delivery (optional) |\n| `slackUrl` | `string` | No | Slack webhook URL for notification delivery (optional) |\n| `sftpInfo` | `object` | No | SFTP configuration for receiving notification reports |\n|     `host` | `string` | Yes | SFTP server hostname or IP address |\n|     `user` | `string` | Yes | Username for SFTP authentication |\n|     `port` | `number` | No | SFTP server port (default: 22) |\n|     `hostKey` | `string` | No | SFTP server host key for secure connection |\n|     `remoteDirectory` | `string` | No | Remote directory path for file delivery |\n|     `separator` | `string` | No | Field separator for CSV reports. Possible values: `COMMA`, `SEMICOLON`, `PIPE`, `TAB`. |\n|     `paymentStatuses` | `array` | No | Restrict the report to payments with these statuses. Accepts a subset of PAYMENT_COMPLETED and PAYMENT_FAILED. |\n|     `paymentTypes` | `array` | No | Restrict the report to these payment types, letting you control whether refunds are included. Accepts PURCHASE and RETURN. |\n|     `includeColumns` | `array` | No | Choose which columns appear in the CSV report. Accepts individual column names or group tokens such as ADJUSTMENTS. |\n\n### Request Example\n```json\n{\n \"event\": \"DAILY_FILE_TRANSFER\",\n \"slackUrl\": \"https://surfboardworkspace.slack.com/archives/C039RL0LS8M\",\n \"email\": \"john@gmail.com\",\n \"sftpInfo\": {\n \"host\": \"192.168.0.211\",\n \"user\": \"surfboard-test\",\n \"port\": 8080,\n \"hostKey\": \"AAAAB3NzaC1yc2EAAAADAQABAAABgQDVjVZBKMAFE3z4m1M6xVpudb+Wcal1kAfzdpOsi64cXjBdK2VS0cuI38htYHGXhpqQ2z/XbYZ2ZfPUkzL/P0IV7Kec22ohLNSN3+r9r3jjB/EU9S46ApuHzloEFnSlPVT5xQA2d09Rs40iMjRp3hfov4pwNPwlav0ikLafSvPWZ2bUfsWq/vNdhnNGBd0au59qIAHrphkF5oyRQUjC5kssSuwZXo2GWC0zHuT06h3/t21BJMoQT4cJ2AEw5Cfvq/cUtSAUKsWaz++0wgyYBOYnYGHpxype+6c7x8gRkuAeuSyj/CdDG39CMSKLsf35CSr7bH8Tsmm6VuIPFwTr8FloGdVwthQiSOPDn15kQXeEiksmzeIMKilgpEWIxp1pgYgtrOefAXp+aoKSqNw+ccvUhiVwIpo2BXxM+l3douJMy2B7A29R+VvwOGDV1zbiYrxjbpDHqMpLjOo5vckj/YYyvHn32nnmb92Hl+A1+b9om1c/y/RN2aRgz6tgmPxhhVU=\",\n \"paymentStatuses\": [\n \"PAYMENT_COMPLETED\"\n ],\n \"paymentTypes\": [\n \"PURCHASE\",\n \"RETURN\"\n ],\n \"includeColumns\": [\n \"ADJUSTMENTS\"\n ]\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| `data` | `array` | Array of notification subscription data |\n|     `notificationId` | `string` | Unique identifier for the notification subscription |\n|     `NotificationChannel` | `string` | Type of notification channel (e.g., SLACK, SFTP, EMAIL) |\n|     `publicKey` | `string` | Public key for SFTP authentication (only present for SFTP channels) |\n| `message` | `string` | A message that describes the status of the request |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"notificationId\": \"839dd1b8113ff809f3\",\n \"NotificationChannel\": \"EMAIL\"\n },\n {\n \"notificationId\": \"839dd1b8113ff819f3\",\n \"NotificationChannel\": \"SLACK\"\n },\n {\n \"notificationId\": \"839dd1b8113ff82af3\",\n \"NotificationChannel\": \"SFTP\",\n \"publicKey\": \"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCfGfO3kOLdYji5R6GNI8lvfyI5MgpQY43OF+HwAqgF96L6hg1jG/Nu58bToPZoaf+lkqp+/MDNGTIeRfMkR+3g1Q2sgZ3jGvN3lErvfbbnYGx7qDzfyMCg7i9VneVOJb4fxoSRzbja2ZG7XxbSzBPvzGky38AKqBq5EysO8/FnA6I9SNCMPcyaEq3Rs33kGjcBthOxc3X+3dRvKt0GU77xtt0tWl7vP/DHXj9m32kcjNN2647i/oRoAiM58fhtsU3UM5TQGYn6WJ0/su7X5JnBy2+WktotJvfzF7ri2Q+R5Ac7kem5g17wdMPgICaz1sDY6haxI3TuDOe8ZVybfV6T surfboard-test@34.88.179.4\"\n }\n ],\n \"message\": \"External notification for MERCHANT_ID: m_iWGri3XAyTmkbKYsYtV47 registered successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid SFTP event: \\\"PAYMENT_COMPLETED\\\". Accepted: DAILY_FILE_TRANSFER, WEEKLY_FILE_TRANSFER, MONTHLY_FILE_TRANSFER\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch External Notifications for Partner", "slug": "notifications-fetch-external-notifications-for-partner", "description": "Retrieves all external notifications configured for a partner. Supports filtering by event type, notification channel, and notification ID", "api": "Notifications API", "method": "GET", "path": "/partners/:partnerId/notifications", "content": "# Fetch External Notifications for Partner\n\n## Overview\nRetrieves all external notifications configured for a partner. Supports filtering by event type, notification channel, and notification ID\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/notifications\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\n\nTo filter notifications by specific criteria, send `event`, `notificationChannel`, or `notificationId` as query params.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `event` | `string` | No | Filter by event type. Possible values: `MERCHANT_ONBOARDED`, `ONLINE_STORE_ONBOARDED`, `TERMINAL_REGISTERED`, `LOGISTICS_TERMINAL_SHIPPED`, `DAILY_FILE_TRANSFER`, `WEEKLY_FILE_TRANSFER`, `MONTHLY_FILE_TRANSFER`. |\n| `notificationChannel` | `string` | No | Filter by notification channel. Possible values: `EMAIL`, `SLACK`, `SFTP`. |\n| `notificationId` | `string` | No | Filter by notification ID |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/notifications?event=WEEKLY_FILE_TRANSFER¬ificationChannel=SFTP¬ificationId=839cfe66fe08b00bf3\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| `data` | `array` | Array of notification objects |\n|     `notificationId` | `string` | Unique identifier for the notification |\n|     `event` | `string` | Event type for the notification. Possible values: `MERCHANT_ONBOARDED`, `ONLINE_STORE_ONBOARDED`, `TERMINAL_REGISTERED`, `LOGISTICS_TERMINAL_SHIPPED`, `DAILY_FILE_TRANSFER`, `WEEKLY_FILE_TRANSFER`, `MONTHLY_FILE_TRANSFER`. |\n|     `notificationChannel` | `string` | Channel used for notification delivery |\n|     `address` | `object` | Address configuration for the notification |\n|         `url` | `string` | URL for webhook notifications |\n|         `email` | `string` | Email address for email notifications |\n|         `host` | `string` | SFTP host address |\n|         `remoteDirectory` | `string` | SFTP remote directory |\n|         `user` | `string` | SFTP username |\n|         `port` | `number` | SFTP port number |\n|         `publicKey` | `string` | SFTP public key |\n|         `separator` | `string` | CSV field separator |\n|         `paymentStatuses` | `array` | Payment statuses the SFTP report is filtered to, when configured |\n|         `paymentTypes` | `array` | Payment types the SFTP report is filtered to, when configured |\n|         `includeColumns` | `array` | Columns included in the SFTP report, when configured |\n|     `status` | `string` | Status of the notification subscription |\n| `message` | `string` | A message that describes the status of the request |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"notificationId\": \"839cfe66fe08b00bf3\",\n \"event\": \"WEEKLY_FILE_TRANSFER\",\n \"notificationChannel\": \"SFTP\",\n \"address\": {\n \"host\": \"192.168.0.211\",\n \"user\": \"surfboard-test\",\n \"port\": 8080,\n \"publicKey\": \"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDPrhFN05QsXZPVGn3uHpRih3bJrRARfvqvyZ5RuRG78YXiVjfHszckpzcay7uF6fsMQes8ky4RGywHs7UfhWbXhu5EDE/swZzTtu8TRVmRhIL6K1o8VKFEEJat3+UgwgrkdKHpUyld3r2doNcViHDiBTiVW4O4JR98/XHrhR7Ge9EPxE/iVwyur+YREtt3RKdZV3d+NG+4WFRqaq70lM13z0u1lACP8PRl4dyRbjrpGoMGq2zDSvyerzS6fKg7jm1UBOt4wznu8pjIE+A+9xiNvzpnxG1q4GxwpRq8e8AY5WIvpngOpaiifEObAGWnauvWnenPwV/yvudTwK4bFQBV surfboard-test@192.168.0.211\",\n \"separator\": \",\",\n \"paymentStatuses\": [\n \"PAYMENT_COMPLETED\"\n ],\n \"paymentTypes\": [\n \"PURCHASE\",\n \"RETURN\"\n ],\n \"includeColumns\": [\n \"ADJUSTMENTS\"\n ]\n },\n \"status\": \"REGISTERED\"\n },\n {\n \"notificationId\": \"839d223b9df16805f3\",\n \"event\": \"ONLINE_STORE_ONBOARDED\",\n \"notificationChannel\": \"EMAIL\",\n \"address\": {\n \"email\": \"partner@example.com\"\n },\n \"status\": \"SUBSCRIBED\"\n }\n ],\n \"message\": \"External notification for PARTNER_ID: 8113d3f8403b380409 fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid notificationChannel. Must be one of: EMAIL, SLACK, SFTP\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Subscribe to Partner Notifications", "slug": "notifications-subscribe-to-partner-notifications", "description": "Subscribe to receive automated notifications for partner events. You must provide at least one notification channel: email, slackUrl, or sftpInfo to create a notification subscription. This endpoint supports multiple notification channels including EMAIL, SLACK, and SFTP.", "api": "Notifications API", "method": "POST", "path": "/partners/:partnerId/notifications/reports", "content": "# Subscribe to Partner Notifications\n\n## Overview\nSubscribe to receive automated notifications for partner events. You must provide at least one notification channel: email, slackUrl, or sftpInfo to create a notification subscription. This endpoint supports multiple notification channels including EMAIL, SLACK, and SFTP.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/notifications/reports\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `event` | `string` | Yes | The event type to subscribe to for notifications. Possible values: `MERCHANT_ONBOARDED`, `ONLINE_STORE_ONBOARDED`, `TERMINAL_REGISTERED`, `LOGISTICS_TERMINAL_SHIPPED`, `DAILY_FILE_TRANSFER`, `WEEKLY_FILE_TRANSFER`, `MONTHLY_FILE_TRANSFER`. |\n| `email` | `string` | No | Email address for notification delivery (optional) |\n| `slackUrl` | `string` | No | Slack webhook URL for notification delivery (optional) |\n| `sftpInfo` | `object` | No | SFTP configuration for receiving notification reports |\n|     `host` | `string` | Yes | SFTP server hostname or IP address |\n|     `user` | `string` | Yes | Username for SFTP authentication |\n|     `port` | `number` | No | SFTP server port (default: 22) |\n|     `hostKey` | `string` | No | SFTP server host key for secure connection |\n|     `remoteDirectory` | `string` | No | Remote directory path for file delivery |\n|     `separator` | `string` | No | Field separator for CSV reports. Possible values: `COMMA`, `SEMICOLON`, `PIPE`, `TAB`. |\n|     `paymentStatuses` | `array` | No | Restrict the report to payments with these statuses. Accepts a subset of PAYMENT_COMPLETED and PAYMENT_FAILED. |\n|     `paymentTypes` | `array` | No | Restrict the report to these payment types, letting you control whether refunds are included. Accepts PURCHASE and RETURN. |\n|     `includeColumns` | `array` | No | Choose which columns appear in the CSV report. Accepts individual column names or group tokens such as ADJUSTMENTS. |\n\n### Request Example\n```json\n{\n \"event\": \"DAILY_FILE_TRANSFER\",\n \"slackUrl\": \"https://surfboardworkspace.slack.com/archives/C039RL0LS8M\",\n \"email\": \"john@gmail.com\",\n \"sftpInfo\": {\n \"host\": \"192.168.0.211\",\n \"user\": \"surfboard-test\",\n \"port\": 8080,\n \"hostKey\": \"AAAAB3NzaC1yc2EAAAADAQABAAABgQDVjVZBKMAFE3z4m1M6xVpudb+Wcal1kAfzdpOsi64cXjBdK2VS0cuI38htYHGXhpqQ2z/XbYZ2ZfPUkzL/P0IV7Kec22ohLNSN3+r9r3jjB/EU9S46ApuHzloEFnSlPVT5xQA2d09Rs40iMjRp3hfov4pwNPwlav0ikLafSvPWZ2bUfsWq/vNdhnNGBd0au59qIAHrphkF5oyRQUjC5kssSuwZXo2GWC0zHuT06h3/t21BJMoQT4cJ2AEw5Cfvq/cUtSAUKsWaz++0wgyYBOYnYGHpxype+6c7x8gRkuAeuSyj/CdDG39CMSKLsf35CSr7bH8Tsmm6VuIPFwTr8FloGdVwthQiSOPDn15kQXeEiksmzeIMKilgpEWIxp1pgYgtrOefAXp+aoKSqNw+ccvUhiVwIpo2BXxM+l3douJMy2B7A29R+VvwOGDV1zbiYrxjbpDHqMpLjOo5vckj/YYyvHn32nnmb92Hl+A1+b9om1c/y/RN2aRgz6tgmPxhhVU=\",\n \"paymentStatuses\": [\n \"PAYMENT_COMPLETED\"\n ],\n \"paymentTypes\": [\n \"PURCHASE\",\n \"RETURN\"\n ],\n \"includeColumns\": [\n \"ADJUSTMENTS\"\n ]\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| `data` | `array` | Array of notification subscription data |\n|     `notificationId` | `string` | Unique identifier for the notification subscription |\n|     `NotificationChannel` | `string` | Type of notification channel (e.g., SLACK, SFTP, EMAIL) |\n|     `publicKey` | `string` | Public key for SFTP authentication (only present for SFTP channels) |\n| `message` | `string` | A message that describes the status of the request |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"notificationId\": \"839dd1b8113ff809f3\",\n \"NotificationChannel\": \"EMAIL\"\n },\n {\n \"notificationId\": \"839dd1b8113ff819f3\",\n \"NotificationChannel\": \"SLACK\"\n },\n {\n \"notificationId\": \"839dd1b8113ff82af3\",\n \"NotificationChannel\": \"SFTP\",\n \"publicKey\": \"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCfGfO3kOLdYji5R6GNI8lvfyI5MgpQY43OF+HwAqgF96L6hg1jG/Nu58bToPZoaf+lkqp+/MDNGTIeRfMkR+3g1Q2sgZ3jGvN3lErvfbbnYGx7qDzfyMCg7i9VneVOJb4fxoSRzbja2ZG7XxbSzBPvzGky38AKqBq5EysO8/FnA6I9SNCMPcyaEq3Rs33kGjcBthOxc3X+3dRvKt0GU77xtt0tWl7vP/DHXj9m32kcjNN2647i/oRoAiM58fhtsU3UM5TQGYn6WJ0/su7X5JnBy2+WktotJvfzF7ri2Q+R5Ac7kem5g17wdMPgICaz1sDY6haxI3TuDOe8ZVybfV6T surfboard-test@34.88.179.4\"\n }\n ],\n \"message\": \"External notification for PARTNER_ID: 8113d3f8403b380409 registered successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid event: \\\"DAILY_REPORTS\\\". Accepted: MERCHANT_ONBOARDED, ONLINE_STORE_ONBOARDED, TERMINAL_REGISTERED, LOGISTICS_TERMINAL_SHIPPED\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Unsubscribe Notification for Merchant", "slug": "notifications-unsubscribe-notification-for-merchant", "description": "Unsubscribe from a specific notification for a merchant. This endpoint removes the notification subscription identified by the notification ID", "api": "Notifications API", "method": "DELETE", "path": "/merchants/:merchantId/notifications/:notificationId", "content": "# Unsubscribe Notification for Merchant\n\n## Overview\nUnsubscribe from a specific notification for a merchant. This endpoint removes the notification subscription identified by the notification ID\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `notificationId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /merchants/:merchantId/notifications/:notificationId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `notificationId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| `message` | `string` | A message that describes the status of the request |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"External notification unsubscribed successfully for the given ID [m_iWGri3XAyTmkbKYsYtV47] and external alert ID [839d12501df1680cf3]\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to cancel external notification subscription.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `notificationId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Unsubscribe Notifications for Partner", "slug": "notifications-unsubscribe-notifications-for-partner", "description": "Unsubscribe from a specific notification for a partner. This endpoint removes the notification subscription identified by the notification ID", "api": "Notifications API", "method": "DELETE", "path": "/partners/:partnerId/notifications/:notificationId", "content": "# Unsubscribe Notifications for Partner\n\n## Overview\nUnsubscribe from a specific notification for a partner. This endpoint removes the notification subscription identified by the notification ID\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `notificationId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /partners/:partnerId/notifications/:notificationId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `notificationId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR' |\n| `message` | `string` | A message that describes the status of the request |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"External notification unsubscribed successfully for the given ID [8113d3f8403b380409] and external alert ID [839d12501df1680cf3]\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to cancel external notification subscription.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `notificationId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Add Receipt Information", "slug": "orders-add-receipt-information", "description": "This API allows you to store cash register details for receipts.", "api": "Orders API", "method": "PUT", "path": "/orders/:orderId/receipt", "content": "# Add Receipt Information\n\n## Overview\nThis API allows you to store cash register details for receipts.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `orderId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /orders/:orderId/receipt\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | No | Merchant the receipt belongs to. |\n| `sequenceNumber` | `string` | No | Receipt sequence number. |\n| `cashRegisterName` | `string` | No | Name of the cash register. |\n| `controlUnitSerialNumber` | `string` | No | Serial number of the fiscal control unit. |\n| `cashierName` | `string` | No | Name of the cashier. |\n| `customerName` | `string` | No | Name of the customer on the receipt. |\n\n### Request Example\n```json\n{\n \"merchantId\": \"825a376eeed1200600\",\n \"sequenceNumber\": \"1234567\",\n \"cashRegisterName\": \"Test\",\n \"controlUnitSerialNumber\": \"1234567\",\n \"cashierName\": \"Amanda\",\n \"customerName\": \"Tom\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request 'SUCCESS' \\| 'ERROR'. |\n| `message` | `string` | Status message of the request is displayed. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Receipt data updated successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `orderId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Cancel an Order", "slug": "orders-cancel-an-order", "description": "Cancels a specific order. Use this API to cancel any created order using its Order ID. However, you cannot cancel orders that are already completed.", "api": "Orders API", "method": "DELETE", "path": "/orders/:orderId", "content": "# Cancel an Order\n\n## Overview\nCancels a specific order. Use this API to cancel any created order using its Order ID. However, you cannot cancel orders that are already completed.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `orderId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /orders/:orderId\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Order cancelled successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `orderId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Online Orders", "slug": "orders-fetch-online-orders", "description": "This API retrieves a list of all online orders created under a terminal.", "api": "Orders API", "method": "GET", "path": "/orders/:terminalId/online", "content": "# Fetch Online Orders\n\n## Overview\nThis API retrieves a list of all online orders created under a terminal.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /orders/:terminalId/online\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `array` | Response data. |\n|     `orderId` | `string` | Id of the order. |\n|     `status` | `string` | Status of the order. |\n|     `terminalId` | `string` | Id of the payment terminal. |\n|     `totalOrderAmount` | `string` | Total order value. |\n|     `currency` | `string` | Type of currency. |\n|     `paymentPageUrl` | `string` | This is the URL of the payment page. |\n|     `nonceId` | `string` | Single-use identifier issued for the order's online payment session. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"orderId\": \"825a37cb9e2048070b\",\n \"status\": \"PENDING\",\n \"terminalId\": \"825a376eeed1200604\",\n \"totalOrderAmount\": \"450\",\n \"currency\": \"SEK\",\n \"paymentPageUrl\": \"https://pay.beta.surfboard.se/825a37cb9e2048070b?pi=w60wGmUUE-k5XN1iT1RyYo-TzaiUl8wsIyO9IEZf4KE-wmDDnl-cxJ4IWkhnCqRvuk6P1WRPDaZP23_LevN0G5JqG_hDgZI9dEn4ooF3ELZMUHiE-ocL_LGc4nT1Cbuv&add=IzNDMkEyMSB8Q0FSRA==\",\n \"nonceId\": \"825a37cd2f1048090c\"\n },\n {\n \"orderId\": \"825a37ca1e20480e0b\",\n \"status\": \"PENDING\",\n \"terminalId\": \"825a376eeed1200604\",\n \"totalOrderAmount\": \"450\",\n \"currency\": \"SEK\",\n \"paymentPageUrl\": \"https://pay.beta.surfboard.se/825a37ca1e20480e0b?pi=gav_crJ4iqayHI05XyMgNdVbTW78QmRMJGm5QFaN0vCvydZfzw8_KQ9j5dd90Yf-OLEq72cpN905QNRXGVki4jxdmvDTPoW8RTNFIC_TPqiCcV80rdpXIuR1Tw6El8PI&add=IzNDMkEyMSB8Q0FSRA==\",\n \"nonceId\": \"825a37cb6e10480f0d\"\n }\n ],\n \"message\": \"Fetched online orders successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Order", "slug": "orders-create-order", "description": "The createOrder API lets you create and pay for an order in a single call—supporting purchases, returns, and multiple payment methods for faster checkout.", "api": "Orders API", "method": "POST", "path": "/orders", "content": "# Create Order\n\n## Overview\nThe createOrder API lets you create and pay for an order in a single call—supporting purchases, returns, and multiple payment methods for faster checkout.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /orders\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminal$id` | `string` | Yes | ID of the checkout or payment terminal |\n| `referenceId` | `string` | No | External reference ID for the order |\n| `comments` | `string` | No | Additional comments or notes for the order |\n| `customer` | `object` | No | Customer details for the order |\n|     `customerId` | `string` | No | Unique identifier for the customer |\n|     `person` | `object` | No | Personal information of the customer |\n|         `id` | `string` | No | Person identifier. |\n|         `name` | `object` | No | Full name of the customer |\n|             `firstName` | `string` | No | First name of the customer |\n|             `middleName` | `string` | No | Middle name of the customer |\n|             `lastName` | `string` | No | Last name of the customer |\n|         `email` | `string` | No | Email address of the customer |\n|         `phoneNumber` | `object` | No | Phone number of the customer |\n|             `code` | `string` | Yes | International dialing code (Eg., 46 for Sweden without '+') |\n|             `number` | `string` | Yes | National subscriber number (digits only) |\n|         `birthDate` | `string` | No | Date of birth in YYYY-MM-DD format |\n|         `personalNumber` | `string` | No | Personal identification number |\n|         `coordinationNumber` | `string` | No | Coordination number |\n|         `countryResidence` | `string` | No | Country of residence of the customer |\n|         `gdNumber` | `string` | No | Government-issued identification number of the customer |\n|     `company` | `object` | No | Company information for corporate purchases |\n|         `id` | `string` | No | Company identifier. |\n|         `vatId` | `string` | No | VAT ID of the company |\n|         `poDetails` | `string` | No | Purchase order details for the company |\n|         `companyName` | `string` | No | Company display name. |\n|         `registrationNumber` | `string` | No | Company registration number. |\n|         `gln` | `string` | No | GLN of the buyer's e-invoice department, used to route e-invoices. |\n| `billing` | `object` | No | Billing contact and address |\n|     `name` | `object` | No | Full name of the billing contact |\n|         `firstName` | `string` | No | First name of the billing contact |\n|         `middleName` | `string` | No | Middle name of the billing contact |\n|         `lastName` | `string` | No | Last name of the billing contact |\n|     `email` | `string` | No | Billing email |\n|     `phoneNumber` | `object` | No | Phone number for billing |\n|         `code` | `string` | Yes | International dialing code (Eg., 46 for Sweden without '+') |\n|         `number` | `string` | Yes | National subscriber number (digits only) |\n|     `address` | `object` | No | Billing address |\n|         `careOf` | `string` | No | Care of / attention |\n|         `addressLine1` | `string` | Yes | Primary address line |\n|         `addressLine2` | `string` | No | Address line 2 |\n|         `addressLine3` | `string` | No | Address line 3 |\n|         `city` | `string` | Yes | City name |\n|         `postalCode` | `string` | Yes | Postal/ZIP code |\n|         `countryCode` | `string` | Yes | Country code (ISO 3166-1 alpha-2) |\n| `shipping` | `object` | No | Shipping contact and address |\n|     `name` | `object` | No | Full name of the shipping contact |\n|         `firstName` | `string` | No | First name of the shipping contact |\n|         `middleName` | `string` | No | Middle name of the shipping contact |\n|         `lastName` | `string` | No | Last name of the shipping contact |\n|     `email` | `string` | No | Recipient email |\n|     `phoneNumber` | `object` | No | Phone number for shipping |\n|         `code` | `string` | Yes | International dialing code (Eg., 46 for Sweden without '+') |\n|         `number` | `string` | Yes | National subscriber number (digits only) |\n|     `address` | `object` | No | Shipping address |\n|         `careOf` | `string` | No | Care of / attention |\n|         `addressLine1` | `string` | Yes | Primary address line |\n|         `addressLine2` | `string` | No | Address line 2 |\n|         `addressLine3` | `string` | No | Address line 3 |\n|         `city` | `string` | Yes | City name |\n|         `postalCode` | `string` | Yes | Postal/ZIP code |\n|         `countryCode` | `string` | Yes | Country code (ISO 3166-1 alpha-2) |\n| `orderLines` | `array` | Yes | List of items in the order |\n|     `id` | `string` | Yes | Order line identifier |\n|     `externalItemId` | `string` | No | External order line identifier |\n|     `name` | `string` | Yes | Product name |\n|     `categoryId` | `string` | No | Product category identifier |\n|     `description` | `string` | No | Line item description |\n|     `quantity` | `number` | Yes | Quantity ordered. A negative value indicates a refund. |\n|     `amount` | `object` | Yes | Pricing details for the line item |\n|         `regular` | `number` | Yes | Regular price amount in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|         `campaign` | `number` | No | Campaign/discount amount in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|         `shipping` | `number` | No | Shipping amount for this item in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|         `total` | `number` | Yes | Total line amount in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|         `currency` | `string` | Yes | Currency (numeric ISO 4217 as string) |\n|         `tax` | `array` | No | Tax breakdown |\n|             `amount` | `number` | Yes | Tax amount |\n|             `percentage` | `number` | Yes | Tax rate percentage |\n|             `type` | `string` | Yes | Tax type (e.g., VAT) |\n|     `unit` | `string` | No | Unit of measure. The possible values are 'm' , 'mm' , 'cm' , 'km' , 'in' , 'ft' , 'mi' , 'kg' , 'g' , 'mg' , 'lb' , 'oz' , 'l' , 'ml' , 'cu. m' , 'gal' , 'pt' , 'fl oz' , 'W' , 'kW' , 'kWh' , 'sq m' , 'sq km' , 'sq ft' , 'h' , 'min' , 's' , 'days' , 'wk' , 'mn' , 'yr' , 'nos'. |\n|     `gtin` | `string` | No | Global Trade Item Number |\n|     `imageUrl` | `string` | No | Image URL for the product |\n|     `brand` | `string` | No | Brand name |\n|     `purchaseOrderId` | `string` | No | Mandatory purchase order identifier if it's a return item. |\n|     `promotionApplied` | `string` | No | Product promotional campaign identifier. |\n|     `metadata` | `object` | No | Arbitrary metadata for the line |\n|     `storeId` | `string` | No | Store identifier |\n|     `purchasePaymentId` | `string` | No | Purchase payment identifier associated with the order line |\n| `totalOrderAmount` | `object` | No | Total amount details of the order. |\n|     `regular` | `number` | Yes | Total regular order amount in the smallest currency unit (e.g., 10 SEK is represented as 1000) |\n|     `campaign` | `number` | No | Total campaign or discount amount applied to the order in the smallest currency unit |\n|     `total` | `number` | Yes | Overall payable order amount in the smallest currency unit (regular - campaign + shipping + tax) |\n|     `currency` | `string` | Yes | Order currency represented as a numeric ISO 4217 code (e.g., '752' for SEK) |\n|     `tax` | `array` | No | Order-level tax breakdown across applied tax categories |\n|         `amount` | `number` | Yes | Total tax amount for the order in the smallest currency unit |\n|         `percentage` | `number` | Yes | Applied tax rate percentage |\n|         `type` | `string` | Yes | Type of tax applied (e.g., VAT, GST) |\n| `date` | `string` | No | Order date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00). If not specified, the current date is used. |\n| `metadata` | `object` | No | Arbitrary key-value style metadata items |\n| `adjustments` | `array` | No | Order-level adjustments |\n|     `type` | `string` | Yes | Adjustment type |\n|     `value` | `number` | Yes | Adjustment value |\n|     `metadata` | `object` | No | Arbitrary key-value style metadata items. |\n| `controlFunctions` | `object` | No | Advanced order/payment control configuration |\n|     `cancelPreviousPendingOrder` | `boolean` | No | Set as true when you want to cancel all previous pending orders |\n|     `orderLineLevelCalculation` | `boolean` | No | Set this to true to apply campaign and shipping at row level. The total will be calculated as total = ((regular * quantity) - campaign) + shipping. Default is set to false. |\n|     `serviceProviders` | `array` | No | External service providers participating in the transaction |\n|         `serviceProviderId` | `string` | Yes | Service provider identifier |\n|         `amount` | `object` | No | Share/fee configuration |\n|             `percentage` | `number` | No | Percentage share |\n|             `fixed` | `number` | No | Fixed share amount |\n|             `adjustmentTypes` | `array` | No | Allowed adjustment types for this provider as an array of string. |\n|     `initiatePaymentsOptions` | `object` | No | Parameters for initiating payment |\n|         `paymentMethod` | `string` | No | Payment method to use |\n|         `amount` | `number` | No | Amount to charge in smallest currency units. |\n|         `paymentMethodParams` | `object` | No | Method-specific parameters |\n|             `tokenId` | `string` | No | Saved payment token ID |\n|             `bic` | `string` | No | The BIC (Bank Identifier Code) is an ISO 9362 standard that uniquely identifies a bank in cross-border transactions. It is mandatory for the ACC2ACC payment method. |\n|             `swishMode` | `string` | No | Swish mode (e.g., ECOM) |\n|             `payeePhoneNumber` | `object` | No | Mandatory phone number for SWISH payments. |\n|                 `code` | `string` | Yes | International dialing code (Eg., 46 for Sweden without '+') |\n|                 `number` | `string` | Yes | National subscriber number (digits only) |\n|             `giftCard` | `object` | No | Gift card payment details |\n|                 `giftCardId` | `string` | No | Gift card identifier |\n|                 `giftCardRedemptionMode` | `string` | No | Redemption mode (e.g., WALLET) |\n|             `invoice` | `object` | No | Invoice payment configuration |\n|                 `invoiceDistribution` | `string` | No | Distribution channel (e.g., EMAIL) |\n|                 `contractReference` | `string` | No | Contract reference identifier |\n|                 `debtCollectionEnabled` | `boolean` | No | Enable debt collection |\n|                 `dueDate` | `string` | No | Due date or relative duration (e.g., 30d) |\n|                 `invoicePaymentMethods` | `array` | No | Allowed payment methods for invoice |\n|                 `reminder` | `boolean` | No | Enable reminders |\n|         `serialSplitPaymentsMode` | `array` | No | An array of amounts in smallest currency unit to split the payment. The order of the amounts in the array will determine the order of the split payments. |\n|         `refundProcessingParams` | `object` | No | Parameters for processing refunds |\n|             `purchasePaymentId` | `string` | No | Original purchase payment ID |\n|             `refundReason` | `string` | No | Reason for refund (as provided) |\n|             `otherReason` | `string` | No | Other reason details |\n|     `tipsMode` | `string` | No | Tips configuration (STANDARD \\| ROUNDUP \\| NONE) |\n|     `cardStatementDescriptor` | `string` | No | Statement descriptor text |\n|     `includeAdjustmentsForRefund` | `boolean` | No | Applies for return orders on whether to include the adjustments as part of the refund or not. The default value is true. For partial returns, by default the first order will have includeAdjustments set to true and for the rest as false. |\n|     `lockToPaymentMethods` | `array` | No | An array of payment methods locked in. All available payment methods are supported. For example, ['CARD', 'KLARNA'] |\n|     `tapBeforeAmount` | `boolean` | No | If true, requires the customer to tap the card before the amount is entered, ensuring amount confirmation prior to payment. |\n|     `delayCapture` | `boolean` | No | Allows capture at a later time. |\n|     `delayPayout` | `string` | No | Delays the final amount paid out to the merchant after all deductions, in the format numbers + 'm' \\| 'h' \\| 'd' . |\n|     `fulfillmentDate` | `string` | No | Planned fulfillment date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00) |\n|     `callBackUrl` | `string` | No | This is a dynamic callback URL that is used to perform webhook calls in relation to the order and payment. |\n|     `throwErrorIfTerminalInactiveFor` | `number` | No | Threshold in ms if the respective terminal has been inactive for the given time frame. |\n|     `clearingCutOff` | `string` | No | Clearing cutoff configuration in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00) |\n|     `currency` | `string` | No | Order currency override |\n|     `authMode` | `string` | No | It can be either PRE-AUTH or AUTH. By default it is set to AUTH. If PRE-AUTH is selected delayCapture is automatically set to true. |\n|     `receipt` | `object` | No | Receipt handling options |\n|         `autoPrintReceipt` | `boolean` | No | Auto-print setting |\n|         `autoSendReceiptIfEmailAvailable` | `boolean` | No | Auto-send if email present |\n|         `sequenceNumber` | `string` | No | Receipt sequence number |\n|         `cashRegisterName` | `string` | No | Cash register name |\n|         `controlUnitSerialNumber` | `string` | No | Control unit serial number |\n|         `receiptRedirectURL` | `string` | No | Receipt redirect URL |\n|         `cashierName` | `string` | No | Cashier name |\n|         `promotionsToDisplay` | `array` | No | Promotions to display on receipt |\n|     `surcharges` | `object` | No | A record of additional fees or charges applied to the transaction, keyed by unique identifiers. |\n|         `domestic` | `object` | No | Surcharges for domestic transactions (same country). |\n|             `consumer` | `object` | No | Surcharges for consumer cards in domestic transactions. |\n|                 `debit` | `object` | No | Surcharge definitions for consumer debit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units (e.g., 100 = 1.00). |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge (e.g., 1.5 = 1.5%). |\n|                 `credit` | `object` | No | Surcharge definitions for consumer credit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|             `corporate` | `object` | No | Surcharges for corporate cards in domestic transactions. |\n|                 `debit` | `object` | No | Surcharge definitions for corporate debit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|                 `credit` | `object` | No | Surcharge definitions for corporate credit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|         `international` | `object` | No | Surcharges for international transactions (outside the merchant’s country). |\n|             `consumer` | `object` | No | Surcharges for consumer cards in international transactions. |\n|                 `debit` | `object` | No | Surcharge definitions for consumer debit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|                 `credit` | `object` | No | Surcharge definitions for consumer credit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|             `corporate` | `object` | No | Surcharges for corporate cards in international transactions. |\n|                 `debit` | `object` | No | Surcharge definitions for corporate debit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|                 `credit` | `object` | No | Surcharge definitions for corporate credit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|         `eea` | `object` | No | Surcharges for EEA (European Economic Area) transactions. |\n|             `consumer` | `object` | No | Surcharges for consumer cards in EEA transactions. |\n|                 `debit` | `object` | No | Surcharge definitions for consumer debit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|                 `credit` | `object` | No | Surcharge definitions for consumer credit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|             `corporate` | `object` | No | Surcharges for corporate cards in EEA transactions. |\n|                 `debit` | `object` | No | Surcharge definitions for corporate debit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|                 `credit` | `object` | No | Surcharge definitions for corporate credit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|     `readTags` | `string` | No | This field denotes the type of NFC reading allowed on the terminal for the order. Possible values: `NONE`, `SINGLE`, `MULTIPLE_EDITABLE`, `MULTIPLE_NONEDITABLE`. |\n|     `ecrEnabled` | `boolean` | No | Whether ECR (electronic cash register) mode is enabled. |\n|     `online` | `object` | No | Online payment/link settings |\n|         `enforceTokenization` | `boolean` | No | Denotes whether the card is tokenised for a future transaction or not. |\n|         `paymentPageValidFor` | `string` | No | Default validity of the payment page in format , where unit is 'm' \\| 'h' \\| 'd' (e.g., '15m', '2h', '3d'). |\n|         `enforce3DSecure` | `boolean` | No | Force 3-D Secure authentication when available. |\n|         `relaxed3ds` | `boolean` | No | Allow relaxed 3-D Secure handling. |\n|         `addressRequirements` | `boolean` | No | Require an address on the payment page. |\n|         `redirectUrl` | `string` | No | Redirect URL after the online transaction completes successfully. The orderId will be appended as a query parameter. |\n|         `accountNameVerification` | `string` | No | Account-name verification mode applied during the payment. |\n|         `errorIfTokenizationFails` | `boolean` | No | If true, fail the flow when card tokenization cannot be completed. |\n|         `failureRedirectUrl` | `string` | No | Redirect URL when the transaction fails. The orderId will be appended as a query parameter. |\n|         `tokenisationIfPossible` | `boolean` | No | Attempts tokenization when supported, without failing the flow if tokenization is unavailable. |\n|         `subscription` | `boolean` | No | Marks this as a subscription/recurring-capable order. |\n|         `payButtonType` | `string` | No | UI pay button label/type used on the payment page. Possible values: `ADD_MONEY`, `BOOK`, `CHECKOUT`, `CONTINUE`, `CONTRIBUTE`, `DONATE`, `ORDER`, `PAY`, `RENT`, `SUPPORT`, `TIP`, `TOP_UP`. |\n|         `generateShortLink` | `boolean` | No | If true, generates a short URL for the payment page. Default is false. |\n|         `generateOnlineLinkWith` | `string` | No | The terminal identifier used to generate the online payment link. |\n|         `recurring` | `object` | No | Encompasses all controls related to recurring payments. |\n|             `subscriptionAmountType` | `string` | No | Determines the type of the subscription amount for order. Possible values: `fixed`, `variable`. |\n|             `maxAmount` | `number` | No | Maximum amount for the order in the lowest currency unit (only valid for variable subscription amounts). |\n|             `frequency` | `string` | Yes | Frequency of the recurring collection. 'daily' \\| 'twiceWeekly' \\| 'weekly' \\| 'tenDays' \\| 'fortNightly' \\| 'monthly' \\| 'everyTwoMonths' \\| 'trimester' \\| 'quarterly' \\| 'twiceYearly' \\| 'annually' \\| 'unscheduled'. |\n|             `numberOfPayments` | `number` | No | Total number of payments expected for this order. |\n|             `uniqueReference` | `string` | No | A unique reference for the recurring order. |\n|             `validation` | `string` | No | The validation type for the recurring order, possible values are 'validated' \\| 'notValidated'. |\n|         `currency` | `string` | No | Currency as a numeric ISO 4217 code (string), e.g., '752' for SEK. |\n|         `selfCardCharging` | `boolean` | No | Allow the customer to self-charge their card. |\n|     `taxHandlingStrategy` | `object` | No | Tax calculation strategy |\n|         `treatAmountAsTaxExclusive` | `boolean` | No | Prices exclude tax |\n|         `taxTreatmentStrategy` | `string` | No | Rounding strategy configuration |\n\n### Request Example\n```json\n{\n \"terminal$id\": \"8386af3b0f71b80b04\",\n \"orderLines\": [\n {\n \"id\": \"TERM123\",\n \"name\": \"Nike Shoes\",\n \"quantity\": 1,\n \"amount\": {\n \"regular\": 500,\n \"campaign\": 0,\n \"shipping\": 0,\n \"total\": 500,\n \"currency\": \"752\",\n \"tax\": [\n {\n \"amount\": 20,\n \"percentage\": 20,\n \"type\": \"VAT\"\n }\n ]\n }\n }\n ],\n \"controlFunctions\": {\n \"initiatePaymentsOptions\": {\n \"paymentMethod\": \"CARD\"\n }\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `orderId` | `string` | Order ID of the order created. |\n|     `paymentId` | `string` | A payment ID assigned to each payment instance. Ensure that this ID is stored securely and tied to an identifiable entity until payment completion. |\n|     `interAppJWT` | `string` | This key can be used in the inter-app flow to be passed in as part of the app switch. This is an optional key that can improve inter-app transaction initiation performance. This is currently only functional for CARD payments. |\n|     `nonce` | `string` | The authorization key required to process online payments through a SelfHostedPage terminal. |\n|     `paymentPageLink` | `string` | This is the payment page link where payments can be made, applicable to both PaymentPage and iFrame terminals. |\n|     `shortLinkUrl` | `string` | Short link to the payment page URL when generateShortLink is set to true. |\n|     `invoiceDetails` | `object` | Invoice details for the payment when applicable. |\n|         `invoiceId` | `number` | Unique identifier for the invoice. |\n|         `invoicePdfUrl` | `string` | URL to download the invoice PDF. |\n|         `iban` | `string` | International Bank Account Number for the invoice. |\n|         `accountHolderName` | `string` | Name of the account holder for the invoice. |\n|         `bic` | `string` | Bank Identifier Code for the invoice. |\n|         `bankgiro` | `string` | Bankgiro number for the invoice. |\n|         `ocr` | `string` | OCR reference number for the invoice payment. |\n|     `paymentUrl` | `string` | Direct URL for payment processing. |\n|     `qr` | `string` | QR code data for payment. |\n|     `qrData` | `string` | Raw QR code data for payment processing. |\n|     `qrVisibleFor` | `string` | Duration for which the QR code remains visible. |\n|     `qrLink` | `string` | Link to the QR code for payment. |\n|     `klarnaClientToken` | `string` | Client token for Klarna payment processing. |\n|     `paymentToken` | `string` | Token for payment processing. |\n|     `sveaInitiationParams` | `object` | Initiation parameters for Svea payment processing. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"orderId\": \"8381a26eae26f0900b\",\n \"paymentId\": \"8381a26eae26f2af06\",\n \"interAppJWT\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvaWQiOiI4MzgxYTI2ZWFlMjZmMDkwMGIiLCJ0aWQiOiI4MzNjZWI4MjQwNGU3MDBiMDQiLCJwaWQiOiI4MzgxYTI2ZWFlMjZmMmFmMDYiLCJwbSI6IkNBU0giLCJhIjoxMDAwMCwiYyI6Ijc1MiIsImNvbnRyb2xGdW5jdGlvbnNFbmNvZGVyIjoiMCIsImlzc3VlZEJ5Ijoic2IucHMiLCJpYXQiOjE3NTg2NDk5NDk3MzN9.3pp94sCLJ_AnfkTmgcEhqv2HnGkxwXD3-ckP-TQGA94\"\n },\n \"message\": \"Order created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n---" }, { "title": "Fetch Order Adjustments", "slug": "orders-fetch-order-adjustments", "description": "Fetch all adjustments created under an order.", "api": "Orders API", "method": "GET", "path": "/orders/:orderId/adjustments", "content": "# Fetch Order Adjustments\n\n## Overview\nFetch all adjustments created under an order.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `orderId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /orders/:orderId/adjustments\n```\n\n### Query Parameters\nTo fetch adjustments made under a certain date range send in startDate and endDate as query params\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `startDate` | `string` | No | Start of the date range to filter adjustments by, in yyyy-mm-dd format. Applied only when endDate is also sent. |\n| `endDate` | `string` | No | End of the date range to filter adjustments by, in yyyy-mm-dd format. Applied only when startDate is also sent. |\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `array` | Response data. |\n|     `adjustmentId` | `string` | Adjustment ID of the adjustment. |\n|     `transactionId` | `string` | Transaction the adjustment is associated with. |\n|     `orderId` | `string` | Order the adjustment belongs to. |\n|     `adjustmentType` | `string` | Type of the adjustment |\n|     `amount` | `number` | Amount of the adjustment. |\n|     `currency` | `string` | Currency of the adjustment amount. |\n|     `metadata` | `object` | Free-form metadata for the adjustment. |\n|     `createdAt` | `string` | Timestamp when the adjustment was created. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"adjustmentId\": \"81efdbe975ebc800ff\",\n \"transactionId\": \"8267defa6150700b48\",\n \"orderId\": \"82674cfdf77f500001\",\n \"adjustmentType\": \"tips\",\n \"amount\": 100,\n \"currency\": \"SEK\",\n \"metadata\": {},\n \"createdAt\": \"2026-06-22T07:39:02.812Z\"\n }\n ],\n \"message\": \"Adjustments fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `orderId` is part of the URL path and must be a valid identifier.\n- This endpoint supports pagination via the `page` and `size` query parameters.\n\n---" }, { "title": "Fetch Order By Id", "slug": "orders-fetch-order-by-id", "description": "Retrieves the details of an existing order using its Order Id.", "api": "Orders API", "method": "GET", "path": "/orders/:orderId", "content": "# Fetch Order By Id\n\n## Overview\nRetrieves the details of an existing order using its Order Id.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `orderId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /orders/:orderId\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Contains the respective order details. |\n|     `terminal$id` | `string` | ID of the checkout or payment terminal |\n|     `referenceId` | `string` | External reference ID for the order |\n|     `comments` | `string` | Additional comments or notes for the order |\n|     `customer` | `object` | Customer details for the order |\n|         `customerId` | `string` | Unique identifier for the customer |\n|         `person` | `object` | Personal information of the customer |\n|             `id` | `string` | Person identifier. |\n|             `name` | `object` | Full name of the customer |\n|                 `firstName` | `string` | First name of the customer |\n|                 `middleName` | `string` | Middle name of the customer |\n|                 `lastName` | `string` | Last name of the customer |\n|             `email` | `string` | Email address of the customer |\n|             `phoneNumber` | `object` | Phone number of the customer |\n|                 `code` | `string` | International dialing code (Eg., 46 for Sweden without '+') |\n|                 `number` | `string` | National subscriber number (digits only) |\n|             `birthDate` | `string` | Date of birth in YYYY-MM-DD format |\n|             `personalNumber` | `string` | Personal identification number |\n|             `coordinationNumber` | `string` | Coordination number |\n|             `countryResidence` | `string` | Country of residence of the customer |\n|             `gdNumber` | `string` | Government-issued identification number of the customer |\n|         `company` | `object` | Company information for corporate purchases |\n|             `id` | `string` | Company identifier. |\n|             `vatId` | `string` | VAT ID of the company |\n|             `poDetails` | `string` | Purchase order details for the company |\n|             `companyName` | `string` | Company display name. |\n|             `registrationNumber` | `string` | Company registration number. |\n|             `gln` | `string` | GLN of the buyer's e-invoice department, used to route e-invoices. |\n|     `billing` | `object` | Billing contact and address |\n|         `name` | `object` | Full name of the billing contact |\n|             `firstName` | `string` | First name of the billing contact |\n|             `middleName` | `string` | Middle name of the billing contact |\n|             `lastName` | `string` | Last name of the billing contact |\n|         `email` | `string` | Billing email |\n|         `phoneNumber` | `object` | Phone number for billing |\n|             `code` | `string` | International dialing code (Eg., 46 for Sweden without '+') |\n|             `number` | `string` | National subscriber number (digits only) |\n|         `address` | `object` | Billing address |\n|             `careOf` | `string` | Care of / attention |\n|             `addressLine1` | `string` | Primary address line |\n|             `addressLine2` | `string` | Address line 2 |\n|             `addressLine3` | `string` | Address line 3 |\n|             `city` | `string` | City name |\n|             `postalCode` | `string` | Postal/ZIP code |\n|             `countryCode` | `string` | Country code (ISO 3166-1 alpha-2) |\n|     `shipping` | `object` | Shipping contact and address |\n|         `name` | `object` | Full name of the shipping contact |\n|             `firstName` | `string` | First name of the shipping contact |\n|             `middleName` | `string` | Middle name of the shipping contact |\n|             `lastName` | `string` | Last name of the shipping contact |\n|         `email` | `string` | Recipient email |\n|         `phoneNumber` | `object` | Phone number for shipping |\n|             `code` | `string` | International dialing code (Eg., 46 for Sweden without '+') |\n|             `number` | `string` | National subscriber number (digits only) |\n|         `address` | `object` | Shipping address |\n|             `careOf` | `string` | Care of / attention |\n|             `addressLine1` | `string` | Primary address line |\n|             `addressLine2` | `string` | Address line 2 |\n|             `addressLine3` | `string` | Address line 3 |\n|             `city` | `string` | City name |\n|             `postalCode` | `string` | Postal/ZIP code |\n|             `countryCode` | `string` | Country code (ISO 3166-1 alpha-2) |\n|     `orderLines` | `array` | List of items in the order |\n|         `id` | `string` | Order line identifier |\n|         `externalItemId` | `string` | External order line identifier |\n|         `name` | `string` | Product name |\n|         `categoryId` | `string` | Product category identifier |\n|         `description` | `string` | Line item description |\n|         `quantity` | `number` | Quantity ordered. A negative value indicates a refund. |\n|         `amount` | `object` | Pricing details for the line item |\n|             `regular` | `number` | Regular price amount in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|             `campaign` | `number` | Campaign/discount amount in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|             `shipping` | `number` | Shipping amount for this item in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|             `total` | `number` | Total line amount in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|             `currency` | `string` | Currency (numeric ISO 4217 as string) |\n|             `tax` | `array` | Tax breakdown |\n|                 `amount` | `number` | Tax amount |\n|                 `percentage` | `number` | Tax rate percentage |\n|                 `type` | `string` | Tax type (e.g., VAT) |\n|         `unit` | `string` | Unit of measure. The possible values are 'm' , 'mm' , 'cm' , 'km' , 'in' , 'ft' , 'mi' , 'kg' , 'g' , 'mg' , 'lb' , 'oz' , 'l' , 'ml' , 'cu. m' , 'gal' , 'pt' , 'fl oz' , 'W' , 'kW' , 'kWh' , 'sq m' , 'sq km' , 'sq ft' , 'h' , 'min' , 's' , 'days' , 'wk' , 'mn' , 'yr' , 'nos'. |\n|         `gtin` | `string` | Global Trade Item Number |\n|         `imageUrl` | `string` | Image URL for the product |\n|         `brand` | `string` | Brand name |\n|         `purchaseOrderId` | `string` | Mandatory purchase order identifier if it's a return item. |\n|         `purchasePaymentId` | `string` | Purchase payment identifier associated with the order line. |\n|         `promotionApplied` | `string` | Product promotional campaign identifier. |\n|         `metadata` | `object` | Arbitrary metadata for the line |\n|         `storeId` | `string` | Store identifier |\n|     `totalOrderAmount` | `object` | Total amount details of the order. |\n|         `regular` | `number` | Total regular order amount in the smallest currency unit (e.g., 10 SEK is represented as 1000) |\n|         `campaign` | `number` | Total campaign or discount amount applied to the order in the smallest currency unit |\n|         `total` | `number` | Overall payable order amount in the smallest currency unit (regular - campaign + shipping + tax) |\n|         `currency` | `string` | Order currency represented as a numeric ISO 4217 code (e.g., '752' for SEK) |\n|         `tax` | `array` | Order-level tax breakdown across applied tax categories |\n|             `amount` | `number` | Total tax amount for the order in the smallest currency unit |\n|             `percentage` | `number` | Applied tax rate percentage |\n|             `type` | `string` | Type of tax applied (e.g., VAT, GST) |\n|     `date` | `string` | Order date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00). If not specified, the current date is used. |\n|     `metadata` | `object` | Arbitrary key-value style metadata items |\n|     `adjustments` | `array` | Order-level adjustments |\n|         `type` | `string` | Adjustment type |\n|         `value` | `number` | Adjustment value |\n|         `metadata` | `object` | Arbitrary key-value style metadata items. |\n|         `adjustmentId` | `string` | Unique identifier of the adjustment. |\n|     `controlFunctions` | `object` | Advanced order/payment control configuration |\n|         `cancelPreviousPendingOrder` | `boolean` | Set as true when you want to cancel all previous pending orders |\n|         `orderLineLevelCalculation` | `boolean` | Set this to true to apply campaign and shipping at row level. The total will be calculated as total = ((regular * quantity) - campaign) + shipping. Default is set to false. |\n|         `serviceProviders` | `array` | External service providers participating in the transaction |\n|             `serviceProviderId` | `string` | Service provider identifier |\n|             `amount` | `object` | Share/fee configuration |\n|                 `percentage` | `number` | Percentage share |\n|                 `fixed` | `number` | Fixed share amount |\n|                 `adjustmentTypes` | `array` | Allowed adjustment types for this provider as an array of string. |\n|         `initiatePaymentsOptions` | `object` | Parameters for initiating payment |\n|             `paymentMethod` | `string` | Payment method to use |\n|             `amount` | `number` | Amount to charge in smallest currency units. |\n|             `paymentMethodParams` | `object` | Method-specific parameters |\n|                 `tokenId` | `string` | Saved payment token ID |\n|                 `swishMode` | `string` | Swish mode (e.g., ECOM) |\n|                 `giftCard` | `object` | Gift card payment details |\n|                     `giftCardId` | `string` | Gift card identifier |\n|                     `giftCardRedemptionMode` | `string` | Redemption mode (e.g., WALLET) |\n|                 `invoice` | `object` | Invoice payment configuration |\n|                     `invoiceDistribution` | `string` | Distribution channel (e.g., EMAIL) |\n|                     `contractReference` | `string` | Contract reference identifier |\n|                     `debtCollectionEnabled` | `boolean` | Enable debt collection |\n|                     `dueDate` | `string` | Due date or relative duration (e.g., 30d) |\n|                     `invoicePaymentMethods` | `array` | Allowed payment methods for invoice |\n|                     `reminder` | `boolean` | Enable reminders |\n|             `serialSplitPaymentsMode` | `array` | An array of amounts in smallest currency unit to split the payment. The order of the amounts in the array will determine the order of the split payments. |\n|             `refundProcessingParams` | `object` | Parameters for processing refunds |\n|                 `purchasePaymentId` | `string` | Original purchase payment ID |\n|                 `refundReason` | `string` | Reason for refund (as provided) |\n|                 `otherReason` | `string` | Other reason details |\n|         `tipsMode` | `string` | Tips configuration (STANDARD \\| ROUNDUP \\| NONE) |\n|         `cardStatementDescriptor` | `string` | Statement descriptor text |\n|         `includeAdjustmentsForRefund` | `boolean` | Applies for return orders on whether to include the adjustments as part of the refund or not. The default value is true. For partial returns, by default the first order will have includeAdjustments set to true and for the rest as false. |\n|         `lockToPaymentMethods` | `array` | An array of payment methods locked in. All available payment methods are supported. For example, ['CARD', 'KLARNA'] |\n|         `tapBeforeAmount` | `boolean` | If true, requires the customer to tap the card before the amount is entered, ensuring amount confirmation prior to payment. |\n|         `delayCapture` | `boolean` | Allows capture at a later time. |\n|         `delayPayout` | `string` | Delays the final amount paid out to the merchant after all deductions, in the format numbers + 'm' \\| 'h' \\| 'd' . |\n|         `fulfillmentDate` | `string` | Planned fulfillment date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00) |\n|         `callBackUrl` | `string` | This is a dynamic callback URL that is used to perform webhook calls in relation to the order and payment. |\n|         `throwErrorIfTerminalInactiveFor` | `number` | Threshold in ms if the respective terminal has been inactive for the given time frame. |\n|         `clearingCutOff` | `string` | Clearing cutoff configuration in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00) |\n|         `currency` | `string` | Order currency override |\n|         `authMode` | `string` | It can be either PRE-AUTH or AUTH. By default it is set to AUTH. If PRE-AUTH is selected delayCapture is automatically set to true. |\n|         `receipt` | `object` | Receipt handling options |\n|             `autoPrintReceipt` | `boolean` | Auto-print setting |\n|             `autoSendReceiptIfEmailAvailable` | `boolean` | Auto-send if email present |\n|             `sequenceNumber` | `string` | Receipt sequence number |\n|             `cashRegisterName` | `string` | Cash register name |\n|             `controlUnitSerialNumber` | `string` | Control unit serial number |\n|             `receiptRedirectURL` | `string` | Receipt redirect URL |\n|             `cashierName` | `string` | Cashier name |\n|             `promotionsToDisplay` | `array` | Promotions to display on receipt |\n|         `surcharges` | `object` | A record of additional fees or charges applied to the transaction, keyed by unique identifiers. |\n|             `domestic` | `object` | Surcharges for domestic transactions (same country). |\n|                 `consumer` | `object` | Surcharges for consumer cards in domestic transactions. |\n|                     `debit` | `object` | Surcharge definitions for consumer debit cards. |\n|                         `fixedAmount` | `number` | A flat surcharge amount in minor currency units (e.g., 100 = 1.00). |\n|                         `fixedPercentage` | `number` | A percentage-based surcharge (e.g., 1.5 = 1.5%). |\n|                     `credit` | `object` | Surcharge definitions for consumer credit cards. |\n|                         `fixedAmount` | `number` | A flat surcharge amount in minor currency units. |\n|                         `fixedPercentage` | `number` | A percentage-based surcharge. |\n|                 `corporate` | `object` | Surcharges for corporate cards in domestic transactions. |\n|                     `debit` | `object` | Surcharge definitions for corporate debit cards. |\n|                         `fixedAmount` | `number` | A flat surcharge amount in minor currency units. |\n|                         `fixedPercentage` | `number` | A percentage-based surcharge. |\n|                     `credit` | `object` | Surcharge definitions for corporate credit cards. |\n|                         `fixedAmount` | `number` | A flat surcharge amount in minor currency units. |\n|                         `fixedPercentage` | `number` | A percentage-based surcharge. |\n|             `international` | `object` | Surcharges for international transactions (outside the merchant’s country). |\n|                 `consumer` | `object` | Surcharges for consumer cards in international transactions. |\n|                     `debit` | `object` | Surcharge definitions for consumer debit cards. |\n|                         `fixedAmount` | `number` | A flat surcharge amount in minor currency units. |\n|                         `fixedPercentage` | `number` | A percentage-based surcharge. |\n|                     `credit` | `object` | Surcharge definitions for consumer credit cards. |\n|                         `fixedAmount` | `number` | A flat surcharge amount in minor currency units. |\n|                         `fixedPercentage` | `number` | A percentage-based surcharge. |\n|                 `corporate` | `object` | Surcharges for corporate cards in international transactions. |\n|                     `debit` | `object` | Surcharge definitions for corporate debit cards. |\n|                         `fixedAmount` | `number` | A flat surcharge amount in minor currency units. |\n|                         `fixedPercentage` | `number` | A percentage-based surcharge. |\n|                     `credit` | `object` | Surcharge definitions for corporate credit cards. |\n|                         `fixedAmount` | `number` | A flat surcharge amount in minor currency units. |\n|                         `fixedPercentage` | `number` | A percentage-based surcharge. |\n|             `eea` | `object` | Surcharges for EEA (European Economic Area) transactions. |\n|                 `consumer` | `object` | Surcharges for consumer cards in EEA transactions. |\n|                     `debit` | `object` | Surcharge definitions for consumer debit cards. |\n|                         `fixedAmount` | `number` | A flat surcharge amount in minor currency units. |\n|                         `fixedPercentage` | `number` | A percentage-based surcharge. |\n|                     `credit` | `object` | Surcharge definitions for consumer credit cards. |\n|                         `fixedAmount` | `number` | A flat surcharge amount in minor currency units. |\n|                         `fixedPercentage` | `number` | A percentage-based surcharge. |\n|                 `corporate` | `object` | Surcharges for corporate cards in EEA transactions. |\n|                     `debit` | `object` | Surcharge definitions for corporate debit cards. |\n|                         `fixedAmount` | `number` | A flat surcharge amount in minor currency units. |\n|                         `fixedPercentage` | `number` | A percentage-based surcharge. |\n|                     `credit` | `object` | Surcharge definitions for corporate credit cards. |\n|                         `fixedAmount` | `number` | A flat surcharge amount in minor currency units. |\n|                         `fixedPercentage` | `number` | A percentage-based surcharge. |\n|         `readTags` | `string` | This field denotes the type of NFC reading allowed on the terminal for the order. Possible values: `NONE`, `SINGLE`, `MULTIPLE_EDITABLE`, `MULTIPLE_NONEDITABLE`. |\n|         `ecrEnabled` | `boolean` | Whether ECR (electronic cash register) mode is enabled. |\n|         `online` | `object` | Online payment/link settings |\n|             `enforceTokenization` | `boolean` | Denotes whether the card is tokenised for a future transaction or not. |\n|             `paymentPageValidFor` | `string` | Default validity of the payment page in format , where unit is 'm' \\| 'h' \\| 'd' (e.g., '15m', '2h', '3d'). |\n|             `enforce3DSecure` | `boolean` | Force 3-D Secure authentication when available. |\n|             `relaxed3ds` | `boolean` | Allow relaxed 3-D Secure handling. |\n|             `addressRequirements` | `boolean` | Require an address on the payment page. |\n|             `redirectUrl` | `string` | Redirect URL after the online transaction completes successfully. The orderId will be appended as a query parameter. |\n|             `accountNameVerification` | `string` | Account-name verification mode applied during the payment. |\n|             `errorIfTokenizationFails` | `boolean` | If true, fail the flow when card tokenization cannot be completed. |\n|             `failureRedirectUrl` | `string` | Redirect URL when the transaction fails. The orderId will be appended as a query parameter. |\n|             `tokenisationIfPossible` | `boolean` | Attempts tokenization when supported, without failing the flow if tokenization is unavailable. |\n|             `subscription` | `boolean` | Marks this as a subscription/recurring-capable order. |\n|             `payButtonType` | `string` | UI pay button label/type used on the payment page. Possible values: `ADD_MONEY`, `BOOK`, `CHECKOUT`, `CONTINUE`, `CONTRIBUTE`, `DONATE`, `ORDER`, `PAY`, `RENT`, `SUPPORT`, `TIP`, `TOP_UP`. |\n|             `generateShortLink` | `boolean` | If true, generates a short URL for the payment page. Default is false. |\n|             `generateOnlineLinkWith` | `string` | The terminal identifier used to generate the online payment link. |\n|             `recurring` | `object` | Encompasses all controls related to recurring payments. |\n|                 `subscriptionAmountType` | `string` | Determines the type of the subscription amount for order. Possible values: `fixed`, `variable`. |\n|                 `maxAmount` | `number` | Maximum amount for the order in the lowest currency unit (only valid for variable subscription amounts). |\n|                 `frequency` | `string` | Frequency of the recurring collection. 'daily' \\| 'twiceWeekly' \\| 'weekly' \\| 'tenDays' \\| 'fortNightly' \\| 'monthly' \\| 'everyTwoMonths' \\| 'trimester' \\| 'quarterly' \\| 'twiceYearly' \\| 'annually' \\| 'unscheduled'. |\n|                 `numberOfPayments` | `number` | Total number of payments expected for this order. |\n|                 `uniqueReference` | `string` | A unique reference for the recurring order. |\n|                 `validation` | `string` | The validation type for the recurring order, possible values are 'validated' \\| 'notValidated'. |\n|             `currency` | `string` | Currency as a numeric ISO 4217 code (string), e.g., '752' for SEK. |\n|             `selfCardCharging` | `boolean` | Allow the customer to self-charge their card. |\n|         `taxHandlingStrategy` | `object` | Tax calculation strategy |\n|             `treatAmountAsTaxExclusive` | `boolean` | Prices exclude tax |\n|             `taxTreatmentStrategy` | `string` | Rounding strategy configuration |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"terminal$id\": \"8386af3b0f71b80b04\",\n \"referenceId\": \"838f324b016d7009\",\n \"date\": \"2025-10-14T07:39:02.812Z\",\n \"adjustments\": [\n {\n \"adjustmentId\": \"838f324b016d703e36\",\n \"type\": \"TIPS\",\n \"value\": 100\n }\n ],\n \"orderLines\": [\n {\n \"id\": \"TERM123NAL\",\n \"name\": \"Nike Shoes\",\n \"quantity\": 1,\n \"amount\": {\n \"regular\": 500,\n \"total\": 500,\n \"currency\": \"752\",\n \"tax\": [\n {\n \"amount\": 20,\n \"percentage\": 20,\n \"type\": \"VAT\"\n }\n ]\n }\n }\n ],\n \"totalOrderAmount\": {\n \"regular\": 500,\n \"total\": 600,\n \"currency\": \"752\"\n },\n \"controlFunctions\": {\n \"cancelPreviousPendingOrder\": false,\n \"orderLineLevelCalculation\": false\n }\n },\n \"message\": \"Order fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `orderId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Order Status", "slug": "orders-fetch-order-status", "description": "Retrieves the status of the given order. Use this API to obtain information about the current status of the order including the respective payment and transaction details.", "api": "Orders API", "method": "GET", "path": "/orders/:orderId/status", "content": "# Fetch Order Status\n\n## Overview\nRetrieves the status of the given order. Use this API to obtain information about the current status of the order including the respective payment and transaction details.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `orderId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /orders/:orderId/status\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `orderStatus` | `string` | Describes the status of the order. Possible values: `PENDING`, `PAYMENT_COMPLETED`, `PAYMENT_CANCELLED`, `PARTIAL_PAYMENT_COMPLETED`, `PAYMENT_PROCESSED`. |\n|     `payments` | `array` | Retrieves the status of all payments related to the order. |\n|         `paymentId` | `string` | Unique identifier of the payment |\n|         `paymentStatus` | `string` | Describes the status of the payment. Possible values: `PAYMENT_INITIATED`, `PAYMENT_PROCESSING`, `PAYMENT_PROCESSED`, `PAYMENT_COMPLETED`, `PAYMENT_FAILED`, `PAYMENT_CANCELLED`. |\n|         `failureReason` | `string` | Indicates the reason of the payment failure if it is available. You can refer to Concepts → Payments for a complete list of payment failure reasons. |\n|         `paymentMethod` | `string` | Denotes the payment method used. |\n|         `amount` | `number` | Amount involved with the payment attempt. |\n|     `paymentIds` | `array` | An array of successful Payment Id(s) related to an order. Payment Ids are available once order reaches 'PAYMENT_COMPLETED' or 'PARTIAL_PAYMENT_COMPLETED' state. |\n|     `transactions` | `array` | Retrieves all transaction details for the order. This information is only available when orderStatus is 'PAYMENT_COMPLETED' or 'PARTIAL_PAYMENT_COMPLETED' |\n|         `transactionId` | `string` | Transaction ID of the transaction. |\n|         `merchantId` | `string` | Merchant ID of the merchant who performed the transaction. |\n|         `storeId` | `string` | Store ID of the store in which the transaction was performed |\n|         `terminalId` | `string` | Terminal ID of the checkout or payment terminal from which the transaction was performed. |\n|         `orderId` | `string` | Order ID of the order for which the transaction was performed. |\n|         `paymentId` | `string` | Payment ID of the transaction. |\n|         `referenceId` | `string` | Reference ID of the transaction. |\n|         `rrn` | `string` | Displays the Retrieval Reference Number(RRN) of the transaction. RRN is a key to uniquely identify a card transaction based on the ISO 8583 standard. |\n|         `amount` | `string` | Amount involved in the transaction, either received or refunded by the merchant, in the minor unit of the currency. For example, 10 SEK is 1000 in amount. |\n|         `currency` | `string` | Three digit numeric code representing the currency of the transaction. |\n|         `method` | `string` | The method in which the transaction was carried out. The payment method currently supported is 'CARD'. |\n|         `type` | `string` | Type of the transaction. It can be either 'purchase' or 'return. |\n|         `orderSummary` | `string` | Specifies a short summary of the order. Usually contains the initial line items included in the order. |\n|         `timestamp` | `string` | Timestamp of the transaction in ISO 8601 format represented as 'YYYY-MM-DDTHH:mm:ss.sssZ'. |\n|         `voided` | `boolean` | A boolean value that denotes if the transaction has been voided or not. |\n|         `issuerCountry` | `string` | Country of the card issuer. |\n|         `interchangeDomain` | `string` | Interchange domain of the transaction. It can be Domestic \\| Intraregional-EEA \\| Interregional-Non-EEA. |\n|         `cardCategory` | `string` | Denotes the card category, which can be Consumer \\| Commercial. |\n|         `cardUsage` | `string` | Denotes the card type, whether it is Debit, Credit or Prepaid. |\n|         `fee` | `string` | The fee collected for each transaction. Fee associated with your settlements are determined by the billing plan you have chosen. These costs may include transaction fees, processing charges, and any additional fees specified in your subscription plan. |\n|         `settlementStatus` | `string` | Denotes the status of the settlement. Possible values: `PROCESSED`, `SETTLED`, `NOT_SETTLED`, `ERROR`. |\n|         `payout` | `string` | Payout is the final amount Surfboard credits to the merchant's bank account. This represents the merchant's actual earnings, which are then transferred to their bank account. |\n|         `settlementRef` | `string` | Reference Id for the payout which includes this transaction. |\n|         `settlementDate` | `string` | Date of the settlement for the transaction. Date in ISO string format. |\n|         `truncatedPan` | `string` | The last four digits of the PAN (Primary Account Number) from the card used for the transaction. |\n|         `cardLabel` | `string` | The designated label of the card brand for the transaction, often referred to as the AID (Application Identifier) Label. |\n|         `posEntryMode` | `string` | Indicates the mode of entry for the card during the transaction, which is based on EMV specifications. This determines whether the card was used in a contact or contactless manner. |\n|         `issuerApplication` | `string` | Specifies the payment application used in the transaction. Usually present when cards with both Debit and Credit facility are used. |\n|         `terminalVerificationResult` | `string` | Specifies the additional results if the transaction underwent EMV terminal verification. |\n|         `aid` | `string` | Specifies the Application Identifier (AID) associated with the card used for the transaction. |\n|         `customerResponseCode` | `string` | A two-character response code of the transaction. For all approved transactions, this code is '00'. |\n|         `cvmMethod` | `string` | Indicates the Card Holder Verification Method (CVM) used in the transaction. |\n|         `cvmMethodDescription` | `string` | Specifies the cvmMethod applied for the provided CARD transaction. |\n|         `authMode` | `string` | Indicates the authentication mode of the payment. This can be either 'ISSUER' or 'CARD'. |\n|         `cardBrand` | `string` | Denotes the brand of card used for the transaction. This is an optional normalized field available only for CARD payments. Eg., VISA, MASTERCARD, AMEX. |\n|     `orderLines` | `array` | List of items in the order |\n|         `id` | `string` | Unique identifier of the order line. |\n|         `name` | `string` | Display name of the actor, or null. |\n|         `quantity` | `number` | Quantity ordered. A negative value indicates a refund. |\n|         `amount` | `object` | Pricing details for the order line. |\n|             `regular` | `number` | Regular price amount in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|             `total` | `number` | Total line amount in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|             `currency` | `string` | ISO currency code of the amount. |\n|         `purchasePaymentId` | `string` | Original purchase payment ID |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"orderStatus\": \"PAYMENT_COMPLETED\",\n \"payments\": [\n {\n \"paymentId\": \"838a071326f1330706\",\n \"paymentStatus\": \"PAYMENT_COMPLETED\",\n \"paymentMethod\": \"CARD\",\n \"amount\": 200\n }\n ],\n \"transactions\": [\n {\n \"transactionId\": \"838a071326f1333319\",\n \"merchantId\": \"8280577d677b18050e\",\n \"terminalId\": \"828057b63d8e480804\",\n \"orderId\": \"838a071326f130950b\",\n \"paymentId\": \"838a071326f1330706\",\n \"rrn\": \"526506000001\",\n \"amount\": \"200\",\n \"currency\": \"752\",\n \"method\": \"CARD\",\n \"type\": \"PURCHASE\",\n \"timestamp\": \"2025-10-08T07:25:11.144Z\",\n \"voided\": false,\n \"settlementStatus\": \"NOT_SETTLED\",\n \"truncatedPan\": \"0010\",\n \"posEntryMode\": \"07\",\n \"customerResponseCode\": \"00\",\n \"cvmMethodDescription\": \"No CVM\",\n \"authMode\": \"ISSUER\",\n \"cardBrand\": \"VISA\"\n }\n ],\n \"orderLines\": [\n {\n \"id\": \"838a071326f1330707\",\n \"name\": \"Sample Product\",\n \"quantity\": 2,\n \"amount\": {\n \"regular\": 10000,\n \"total\": 20000,\n \"currency\": \"752\"\n },\n \"purchasePaymentId\": \"838a071326f1330706\"\n }\n ],\n \"paymentIds\": [\n \"838a071326f1330706\"\n ]\n },\n \"message\": \"Fetched order status successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `orderId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Tokens from Order", "slug": "orders-fetch-tokens-from-order", "description": "Fetch all tokenized card information collected for online orders.", "api": "Orders API", "method": "GET", "path": "/orders/:orderId/tokens", "content": "# Fetch Tokens from Order\n\n## Overview\nFetch all tokenized card information collected for online orders.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `orderId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /orders/:orderId/tokens\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `array` | Response data. |\n|     `cardBrand` | `string` | Denotes the brand of the card. E.g. VISA, MASTERCARD, AMEX. |\n|     `cardholderName` | `string` | Name of the card holder. |\n|     `tokenId` | `string` | Tokenized card information. |\n|     `createdAt` | `string` | Date of tokenization in ISO string format. |\n|     `expiryMonth` | `number` | Expiration month of the card. |\n|     `expiryYear` | `number` | Expiration year of the card. |\n|     `truncatedPan` | `string` | The last four digits of the PAN (Primary Account Number) from the card. |\n|     `cardArt` | `string` | Denotes the visual images of the card. Eg., VISA, MASTERCARD, AMEX. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"cardBrand\": \"VISA\",\n \"cardholderName\": \"Tom\",\n \"tokenId\": \"822d544dc48c200308\",\n \"createdAt\": \"2024-04-25T11:22:24.845Z\",\n \"expiryMonth\": 7,\n \"expiryYear\": 2026,\n \"truncatedPan\": \"8907\",\n \"cardArt\": \"iVBORw0KGgoAAAANSUhEUgAAAUQAAA......\"\n },\n {\n \"cardBrand\": \"VISA\",\n \"cardholderName\": \"Sam\",\n \"tokenId\": \"822d544dc48c200308\",\n \"createdAt\": \"2024-04-25T11:22:24.845Z\",\n \"expiryMonth\": 5,\n \"expiryYear\": 2025,\n \"truncatedPan\": \"0987\",\n \"cardArt\": \"YAAAAAXNSR0IArs4c6QAAAARnQU1BA......\"\n }\n ],\n \"message\": \"Fetched the card information.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `orderId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Activate Payment Method", "slug": "payment-methods-activate-payment-method", "description": "Activates multiple payment methods for a merchant in a single request. Each payment method can be enabled with a boolean value or configured with specific settings using an object.", "api": "Payment Methods API", "method": "POST", "path": "/merchants/:merchantId/payment-methods", "content": "# Activate Payment Method\n\n## Overview\nActivates multiple payment methods for a merchant in a single request. Each payment method can be enabled with a boolean value or configured with specific settings using an object.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /merchants/:merchantId/payment-methods\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Optional merchant identifier for the payment method configuration. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | No | Optional store identifier to associate payment methods with a specific store. |\n| `terminalId` | `string` | No | Optional terminal (checkout) identifier to associate the payment methods with a specific terminal. |\n| `card` | `boolean` | No | Card payment method configuration. Set to true to enable card payments, or pass an object with a scheme array (visa, mastercard) to configure it in detail. |\n| `amex` | `boolean` | No | American Express payment method configuration. Set to true to enable AMEX payments, or pass an object with the AMEX merchant id (mId) to configure it. |\n| `swish` | `boolean` | No | Swedish mobile payment method configuration. Set to true to enable Swish payments. |\n| `klarna` | `boolean` | No | Buy now, pay later payment method configuration. Set to true to enable Klarna payments. |\n| `b2binv` | `boolean` | No | B2B invoice payment method configuration. Set to true to enable B2B invoice payments. |\n| `acc2acc` | `boolean` | No | Account to account transfer payment method configuration. Set to true to enable account to account transfers. |\n| `vipps` | `boolean` | No | Norwegian mobile payment method. Set to true to enable Vipps payment method. |\n| `mobilepay` | `boolean` | No | Danish mobile payment method. Set to true to enable MobilePay payment method. |\n\n### Request Example\n```json\n{\n \"card\": true,\n \"amex\": true,\n \"swish\": true,\n \"klarna\": true,\n \"b2binv\": true,\n \"acc2acc\": true,\n \"vipps\": true,\n \"mobilepay\": true\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | Array of payment method registration results. |\n|     `method` | `string` | The payment method name (e.g., 'amex', 'swish', 'card'). |\n|     `paymentMethodId` | `string` | Unique identifier assigned to the payment method (present on success). |\n|     `status` | `string` | Registration status for this payment method, either 'SUCCESS' or 'ERROR'. |\n|     `message` | `string` | Error message if registration failed (present on error). |\n| `message` | `string` | A message that describes the overall status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"method\": \"b2binv\",\n \"paymentMethodId\": \"838f499c1f7bf00c23\",\n \"status\": \"SUCCESS\"\n },\n {\n \"method\": \"card\",\n \"paymentMethodId\": \"82523116c63be80123\",\n \"status\": \"SUCCESS\"\n },\n {\n \"method\": \"swish\",\n \"status\": \"ERROR\",\n \"message\": \"PM_0010 - Register payment method failed: SWISH registration already exists.\"\n },\n {\n \"method\": \"acc2acc\",\n \"paymentMethodId\": \"838f499c1f7bf01c23\",\n \"status\": \"SUCCESS\"\n }\n ],\n \"message\": \"Processed payment method registrations\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Order", "slug": "orders-update-order", "description": "Updates the details of an existing order. This API allows you to modify order information while retaining the same Order ID as the original order. Once a payment has been initiated for the order, further updates are no longer permitted.", "api": "Orders API", "method": "PUT", "path": "/orders/:orderId", "content": "# Update Order\n\n## Overview\nUpdates the details of an existing order. This API allows you to modify order information while retaining the same Order ID as the original order. Once a payment has been initiated for the order, further updates are no longer permitted.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `orderId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /orders/:orderId\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminal$id` | `string` | Yes | ID of the checkout or payment terminal |\n| `referenceId` | `string` | No | External reference ID for the order |\n| `comments` | `string` | No | Additional comments or notes for the order |\n| `customer` | `object` | No | Customer details for the order |\n|     `customerId` | `string` | No | Unique identifier for the customer |\n|     `person` | `object` | No | Personal information of the customer |\n|         `id` | `string` | No | Person identifier. |\n|         `name` | `object` | No | Full name of the customer |\n|             `firstName` | `string` | No | First name of the customer |\n|             `middleName` | `string` | No | Middle name of the customer |\n|             `lastName` | `string` | No | Last name of the customer |\n|         `email` | `string` | No | Email address of the customer |\n|         `phoneNumber` | `object` | No | Phone number of the customer |\n|             `code` | `string` | Yes | International dialing code (Eg., 46 for Sweden without '+') |\n|             `number` | `string` | Yes | National subscriber number (digits only) |\n|         `birthDate` | `string` | No | Date of birth in YYYY-MM-DD format |\n|         `personalNumber` | `string` | No | Personal identification number |\n|         `coordinationNumber` | `string` | No | Coordination number |\n|         `countryResidence` | `string` | No | Country of residence of the customer |\n|         `gdNumber` | `string` | No | Government-issued identification number of the customer |\n|     `company` | `object` | No | Company information for corporate purchases |\n|         `id` | `string` | No | Company identifier. |\n|         `vatId` | `string` | No | VAT ID of the company |\n|         `poDetails` | `string` | No | Purchase order details for the company |\n|         `companyName` | `string` | No | Company display name. |\n|         `registrationNumber` | `string` | No | Company registration number. |\n|         `gln` | `string` | No | GLN of the buyer's e-invoice department, used to route e-invoices. |\n| `billing` | `object` | No | Billing contact and address |\n|     `name` | `object` | No | Full name of the billing contact |\n|         `firstName` | `string` | No | First name of the billing contact |\n|         `middleName` | `string` | No | Middle name of the billing contact |\n|         `lastName` | `string` | No | Last name of the billing contact |\n|     `email` | `string` | No | Billing email |\n|     `phoneNumber` | `object` | No | Phone number for billing |\n|         `code` | `string` | Yes | International dialing code (Eg., 46 for Sweden without '+') |\n|         `number` | `string` | Yes | National subscriber number (digits only) |\n|     `address` | `object` | No | Billing address |\n|         `careOf` | `string` | No | Care of / attention |\n|         `addressLine1` | `string` | Yes | Primary address line |\n|         `addressLine2` | `string` | No | Address line 2 |\n|         `addressLine3` | `string` | No | Address line 3 |\n|         `city` | `string` | Yes | City name |\n|         `postalCode` | `string` | Yes | Postal/ZIP code |\n|         `countryCode` | `string` | Yes | Country code (ISO 3166-1 alpha-2) |\n| `shipping` | `object` | No | Shipping contact and address |\n|     `name` | `object` | No | Full name of the shipping contact |\n|         `firstName` | `string` | No | First name of the shipping contact |\n|         `middleName` | `string` | No | Middle name of the shipping contact |\n|         `lastName` | `string` | No | Last name of the shipping contact |\n|     `email` | `string` | No | Recipient email |\n|     `phoneNumber` | `object` | No | Phone number for shipping |\n|         `code` | `string` | Yes | International dialing code (Eg., 46 for Sweden without '+') |\n|         `number` | `string` | Yes | National subscriber number (digits only) |\n|     `address` | `object` | No | Shipping address |\n|         `careOf` | `string` | No | Care of / attention |\n|         `addressLine1` | `string` | Yes | Primary address line |\n|         `addressLine2` | `string` | No | Address line 2 |\n|         `addressLine3` | `string` | No | Address line 3 |\n|         `city` | `string` | Yes | City name |\n|         `postalCode` | `string` | Yes | Postal/ZIP code |\n|         `countryCode` | `string` | Yes | Country code (ISO 3166-1 alpha-2) |\n| `orderLines` | `array` | Yes | List of items in the order |\n|     `id` | `string` | Yes | Order line identifier |\n|     `externalItemId` | `string` | No | External order line identifier |\n|     `name` | `string` | Yes | Product name |\n|     `categoryId` | `string` | No | Product category identifier |\n|     `description` | `string` | No | Line item description |\n|     `quantity` | `number` | Yes | Quantity ordered. A negative value indicates a refund. |\n|     `amount` | `object` | Yes | Pricing details for the line item |\n|         `regular` | `number` | Yes | Regular price amount in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|         `campaign` | `number` | No | Campaign/discount amount in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|         `shipping` | `number` | No | Shipping amount for this item in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|         `total` | `number` | Yes | Total line amount in the smallest currency unit (eg.,10 SEK is 1000 in amount) |\n|         `currency` | `string` | Yes | Currency (numeric ISO 4217 as string) |\n|         `tax` | `array` | No | Tax breakdown |\n|             `amount` | `number` | Yes | Tax amount |\n|             `percentage` | `number` | Yes | Tax rate percentage |\n|             `type` | `string` | Yes | Tax type (e.g., VAT) |\n|     `unit` | `string` | No | Unit of measure. The possible values are 'm' , 'mm' , 'cm' , 'km' , 'in' , 'ft' , 'mi' , 'kg' , 'g' , 'mg' , 'lb' , 'oz' , 'l' , 'ml' , 'cu. m' , 'gal' , 'pt' , 'fl oz' , 'W' , 'kW' , 'kWh' , 'sq m' , 'sq km' , 'sq ft' , 'h' , 'min' , 's' , 'days' , 'wk' , 'mn' , 'yr' , 'nos'. |\n|     `gtin` | `string` | No | Global Trade Item Number |\n|     `imageUrl` | `string` | No | Image URL for the product |\n|     `brand` | `string` | No | Brand name |\n|     `purchaseOrderId` | `string` | No | Mandatory purchase order identifier if it's a return item, i.e. a negative quantity. |\n|     `promotionApplied` | `string` | No | Product promotional campaign identifier. |\n|     `metadata` | `object` | No | Arbitrary metadata for the line |\n|     `storeId` | `string` | No | Store identifier |\n|     `purchasePaymentId` | `string` | No | Purchase payment identifier associated with the order line |\n| `totalOrderAmount` | `object` | No | Total amount details of the order. |\n|     `regular` | `number` | Yes | Total regular order amount in the smallest currency unit (e.g., 10 SEK is represented as 1000) |\n|     `campaign` | `number` | No | Total campaign or discount amount applied to the order in the smallest currency unit |\n|     `total` | `number` | Yes | Overall payable order amount in the smallest currency unit (regular - campaign + shipping + tax) |\n|     `currency` | `string` | Yes | Order currency represented as a numeric ISO 4217 code (e.g., '752' for SEK) |\n|     `tax` | `array` | No | Order-level tax breakdown across applied tax categories |\n|         `amount` | `number` | Yes | Total tax amount for the order in the smallest currency unit |\n|         `percentage` | `number` | Yes | Applied tax rate percentage |\n|         `type` | `string` | Yes | Type of tax applied (e.g., VAT, GST) |\n| `date` | `string` | No | Order date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00). If not specified, the current date is used. |\n| `metadata` | `object` | No | Arbitrary key-value style metadata items |\n| `adjustments` | `array` | No | Order-level adjustments |\n|     `type` | `string` | Yes | Adjustment type |\n|     `value` | `number` | Yes | Adjustment value |\n|     `metadata` | `object` | No | Arbitrary key-value style metadata items. |\n| `controlFunctions` | `object` | No | Advanced order/payment control configuration |\n|     `cancelPreviousPendingOrder` | `boolean` | No | Set as true when you want to cancel all previous pending orders |\n|     `orderLineLevelCalculation` | `boolean` | No | Set this to true to apply campaign and shipping at row level. The total will be calculated as total = ((regular * quantity) - campaign) + shipping. Default is set to false. |\n|     `serviceProviders` | `array` | No | External service providers participating in the transaction |\n|         `serviceProviderId` | `string` | Yes | Service provider identifier |\n|         `amount` | `object` | No | Share/fee configuration |\n|             `percentage` | `number` | No | Percentage share |\n|             `fixed` | `number` | No | Fixed share amount |\n|             `adjustmentTypes` | `array` | No | Allowed adjustment types for this provider as an array of string. |\n|     `initiatePaymentsOptions` | `object` | No | Parameters for initiating payment |\n|         `paymentMethod` | `string` | No | Payment method to use |\n|         `amount` | `number` | No | Amount to charge in smallest currency units. |\n|         `paymentMethodParams` | `object` | No | Method-specific parameters |\n|             `tokenId` | `string` | No | Saved payment token ID |\n|             `swishMode` | `string` | No | Swish mode (e.g., ECOM) |\n|             `payeePhoneNumber` | `object` | No | Mandatory phone number for SWISH payments. |\n|                 `code` | `string` | Yes | International dialing code (Eg., 46 for Sweden without '+') |\n|                 `number` | `string` | Yes | National subscriber number (digits only) |\n|             `giftCard` | `object` | No | Gift card payment details |\n|                 `giftCardId` | `string` | No | Gift card identifier |\n|                 `giftCardRedemptionMode` | `string` | No | Redemption mode (e.g., WALLET) |\n|             `invoice` | `object` | No | Invoice payment configuration |\n|                 `invoiceDistribution` | `string` | No | Distribution channel (e.g., EMAIL) |\n|                 `contractReference` | `string` | No | Contract reference identifier |\n|                 `debtCollectionEnabled` | `boolean` | No | Enable debt collection |\n|                 `dueDate` | `string` | No | Due date or relative duration (e.g., 30d) |\n|                 `invoicePaymentMethods` | `array` | No | Allowed payment methods for invoice |\n|                 `reminder` | `boolean` | No | Enable reminders |\n|         `serialSplitPaymentsMode` | `array` | No | An array of amounts in smallest currency unit to split the payment. The order of the amounts in the array will determine the order of the split payments. |\n|         `refundProcessingParams` | `object` | No | Parameters for processing refunds |\n|             `purchasePaymentId` | `string` | No | Original purchase payment ID |\n|             `refundReason` | `string` | No | Reason for refund (as provided) |\n|             `otherReason` | `string` | No | Other reason details |\n|     `tipsMode` | `string` | No | Tips configuration (STANDARD \\| ROUNDUP \\| NONE) |\n|     `cardStatementDescriptor` | `string` | No | Statement descriptor text |\n|     `includeAdjustmentsForRefund` | `boolean` | No | Applies for return orders on whether to include the adjustments as part of the refund or not. The default value is true. For partial returns, by default the first order will have includeAdjustments set to true and for the rest as false. |\n|     `lockToPaymentMethods` | `array` | No | An array of payment methods locked in. All available payment methods are supported. For example, ['CARD', 'KLARNA'] |\n|     `tapBeforeAmount` | `boolean` | No | If true, requires the customer to tap the card before the amount is entered, ensuring amount confirmation prior to payment. |\n|     `delayCapture` | `boolean` | No | Allows capture at a later time. |\n|     `delayPayout` | `string` | No | Delays the final amount paid out to the merchant after all deductions, in the format numbers + 'm' \\| 'h' \\| 'd' . |\n|     `fulfillmentDate` | `string` | No | Planned fulfillment date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00) |\n|     `callBackUrl` | `string` | No | This is a dynamic callback URL that is used to perform webhook calls in relation to the order and payment. |\n|     `throwErrorIfTerminalInactiveFor` | `number` | No | Threshold in ms if the respective terminal has been inactive for the given time frame. |\n|     `clearingCutOff` | `string` | No | Clearing cutoff configuration in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00) |\n|     `currency` | `string` | No | Order currency override |\n|     `authMode` | `string` | No | It can be either PRE-AUTH or AUTH. By default it is set to AUTH. If PRE-AUTH is selected delayCapture is automatically set to true. |\n|     `receipt` | `object` | No | Receipt handling options |\n|         `autoPrintReceipt` | `boolean` | No | Auto-print setting |\n|         `autoSendReceiptIfEmailAvailable` | `boolean` | No | Auto-send if email present |\n|         `sequenceNumber` | `string` | No | Receipt sequence number |\n|         `cashRegisterName` | `string` | No | Cash register name |\n|         `controlUnitSerialNumber` | `string` | No | Control unit serial number |\n|         `receiptRedirectURL` | `string` | No | Receipt redirect URL |\n|         `cashierName` | `string` | No | Cashier name |\n|         `promotionsToDisplay` | `array` | No | Promotions to display on receipt |\n|     `surcharges` | `object` | No | A record of additional fees or charges applied to the transaction, keyed by unique identifiers. |\n|         `domestic` | `object` | No | Surcharges for domestic transactions (same country). |\n|             `consumer` | `object` | No | Surcharges for consumer cards in domestic transactions. |\n|                 `debit` | `object` | No | Surcharge definitions for consumer debit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units (e.g., 100 = 1.00). |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge (e.g., 1.5 = 1.5%). |\n|                 `credit` | `object` | No | Surcharge definitions for consumer credit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|             `corporate` | `object` | No | Surcharges for corporate cards in domestic transactions. |\n|                 `debit` | `object` | No | Surcharge definitions for corporate debit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|                 `credit` | `object` | No | Surcharge definitions for corporate credit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|         `international` | `object` | No | Surcharges for international transactions (outside the merchant’s country). |\n|             `consumer` | `object` | No | Surcharges for consumer cards in international transactions. |\n|                 `debit` | `object` | No | Surcharge definitions for consumer debit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|                 `credit` | `object` | No | Surcharge definitions for consumer credit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|             `corporate` | `object` | No | Surcharges for corporate cards in international transactions. |\n|                 `debit` | `object` | No | Surcharge definitions for corporate debit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|                 `credit` | `object` | No | Surcharge definitions for corporate credit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|         `eea` | `object` | No | Surcharges for EEA (European Economic Area) transactions. |\n|             `consumer` | `object` | No | Surcharges for consumer cards in EEA transactions. |\n|                 `debit` | `object` | No | Surcharge definitions for consumer debit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|                 `credit` | `object` | No | Surcharge definitions for consumer credit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|             `corporate` | `object` | No | Surcharges for corporate cards in EEA transactions. |\n|                 `debit` | `object` | No | Surcharge definitions for corporate debit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|                 `credit` | `object` | No | Surcharge definitions for corporate credit cards. |\n|                     `fixedAmount` | `number` | No | A flat surcharge amount in minor currency units. |\n|                     `fixedPercentage` | `number` | No | A percentage-based surcharge. |\n|     `readTags` | `string` | No | This field denotes the type of NFC reading allowed on the terminal for the order. Possible values: `NONE`, `SINGLE`, `MULTIPLE_EDITABLE`, `MULTIPLE_NONEDITABLE`. |\n|     `ecrEnabled` | `boolean` | No | Whether ECR (electronic cash register) mode is enabled. |\n|     `online` | `object` | No | Online payment/link settings |\n|         `enforceTokenization` | `boolean` | No | Denotes whether the card is tokenised for a future transaction or not. |\n|         `paymentPageValidFor` | `string` | No | Default validity of the payment page in format , where unit is 'm' \\| 'h' \\| 'd' (e.g., '15m', '2h', '3d'). |\n|         `enforce3DSecure` | `boolean` | No | Force 3-D Secure authentication when available. |\n|         `relaxed3ds` | `boolean` | No | Allow relaxed 3-D Secure handling. |\n|         `addressRequirements` | `boolean` | No | Require an address on the payment page. |\n|         `redirectUrl` | `string` | No | Redirect URL after the online transaction completes successfully. The orderId will be appended as a query parameter. |\n|         `accountNameVerification` | `string` | No | Account-name verification mode applied during the payment. |\n|         `errorIfTokenizationFails` | `boolean` | No | If true, fail the flow when card tokenization cannot be completed. |\n|         `failureRedirectUrl` | `string` | No | Redirect URL when the transaction fails. The orderId will be appended as a query parameter. |\n|         `tokenisationIfPossible` | `boolean` | No | Attempts tokenization when supported, without failing the flow if tokenization is unavailable. |\n|         `subscription` | `boolean` | No | Marks this as a subscription/recurring-capable order. |\n|         `payButtonType` | `string` | No | UI pay button label/type used on the payment page. Possible values: `ADD_MONEY`, `BOOK`, `CHECKOUT`, `CONTINUE`, `CONTRIBUTE`, `DONATE`, `ORDER`, `PAY`, `RENT`, `SUPPORT`, `TIP`, `TOP_UP`. |\n|         `generateShortLink` | `boolean` | No | If true, generates a short URL for the payment page. Default is false. |\n|         `generateOnlineLinkWith` | `string` | No | The terminal identifier used to generate the online payment link. |\n|         `recurring` | `object` | No | Encompasses all controls related to recurring payments. |\n|             `subscriptionAmountType` | `string` | No | Determines the type of the subscription amount for order. Possible values: `fixed`, `variable`. |\n|             `maxAmount` | `number` | No | Maximum amount for the order in the lowest currency unit (only valid for variable subscription amounts). |\n|             `frequency` | `string` | Yes | Frequency of the recurring collection. 'daily' \\| 'twiceWeekly' \\| 'weekly' \\| 'tenDays' \\| 'fortNightly' \\| 'monthly' \\| 'everyTwoMonths' \\| 'trimester' \\| 'quarterly' \\| 'twiceYearly' \\| 'annually' \\| 'unscheduled'. |\n|             `numberOfPayments` | `number` | No | Total number of payments expected for this order. |\n|             `uniqueReference` | `string` | No | A unique reference for the recurring order. |\n|             `validation` | `string` | No | The validation type for the recurring order, possible values are 'validated' \\| 'notValidated'. |\n|         `currency` | `string` | No | Currency as a numeric ISO 4217 code (string), e.g., '752' for SEK. |\n|         `selfCardCharging` | `boolean` | No | Allow the customer to self-charge their card. |\n|     `taxHandlingStrategy` | `object` | No | Tax calculation strategy |\n|         `treatAmountAsTaxExclusive` | `boolean` | No | Prices exclude tax |\n|         `taxTreatmentStrategy` | `string` | No | Rounding strategy configuration |\n\n### Request Example\n```json\n{\n \"terminal$id\": \"8386af3b0f71b80b04\",\n \"orderLines\": [\n {\n \"id\": \"TERM123\",\n \"name\": \"Nike Shoes\",\n \"quantity\": 1,\n \"amount\": {\n \"regular\": 500,\n \"campaign\": 0,\n \"shipping\": 0,\n \"total\": 500,\n \"currency\": \"752\",\n \"tax\": [\n {\n \"amount\": 20,\n \"percentage\": 20,\n \"type\": \"VAT\"\n }\n ]\n }\n }\n ],\n \"controlFunctions\": {\n \"initiatePaymentsOptions\": {\n \"paymentMethod\": \"CARD\"\n }\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Order updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `orderId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Deactivate Payment Method", "slug": "payment-methods-deactivate-payment-method", "description": "Deactivates a specific payment method. Use this API to deactivate the payment method added to the merchant or store using its Payment Method ID.", "api": "Payment Methods API", "method": "DELETE", "path": "/merchants/:merchantId/payment-methods/:paymentMethodId", "content": "# Deactivate Payment Method\n\n## Overview\nDeactivates a specific payment method. Use this API to deactivate the payment method added to the merchant or store using its Payment Method ID.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `paymentMethodId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /merchants/:merchantId/payment-methods/:paymentMethodId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `paymentMethodId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Deactivated payment method successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to deactivate payment method\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `paymentMethodId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch All Payment Methods", "slug": "payment-methods-fetch-all-payment-methods", "description": "Retrieves a list of all payment methods activated for a specific merchant. You can use this API to get information regarding all the payment methods added for the merchant.", "api": "Payment Methods API", "method": "GET", "path": "/merchants/:merchantId/payment-methods", "content": "# Fetch All Payment Methods\n\n## Overview\nRetrieves a list of all payment methods activated for a specific merchant. You can use this API to get information regarding all the payment methods added for the merchant.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/payment-methods\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/payment-methods\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | Response data |\n|     `paymentMethodId` | `string` | PaymentMethod ID of the payment method. |\n|     `paymentMethod` | `string` | Specifies the payment method. It can be one of the following: 'AMEX', 'SWISH', or 'CARD’. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"paymentMethodId\": \"8235c0a33bd9800223\",\n \"paymentMethod\": \"SWISH\"\n },\n {\n \"paymentMethodId\": \"8235c0943bd9800023\",\n \"paymentMethod\": \"AMEX\"\n }\n ],\n \"message\": \"Fetched activated payment methods\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Payment Method Details", "slug": "payment-methods-fetch-payment-method-details", "description": "Retrieves information for a specific payment method. Use this API to get information regarding the payment method using its Payment Method ID.", "api": "Payment Methods API", "method": "GET", "path": "/merchants/:merchantId/payment-methods/:paymentMethodId", "content": "# Fetch Payment Method Details\n\n## Overview\nRetrieves information for a specific payment method. Use this API to get information regarding the payment method using its Payment Method ID.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `paymentMethodId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/payment-methods/:paymentMethodId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `paymentMethodId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/payment-methods/:paymentMethodId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data |\n|     `paymentMethodId` | `string` | PaymentMethod ID of the payment method. |\n|     `paymentMethod` | `string` | Specifies the payment method. It can be one of the following: 'AMEX', 'SWISH', or 'CARD’. |\n|     `status` | `string` | Status of the payment method, indicated as either ACTIVATED' or 'DEACTIVATED’. |\n|     `amexMID` | `string` | Returns AMEX MID for AMEX payment method. |\n|     `acquirerMID` | `string` | Returns the respective Acquirer MID for CARD payment method. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"paymentMethodId\": \"8235c0943bd9800023\",\n \"paymentMethod\": \"AMEX\",\n \"status\": \"ACTIVATED\",\n \"amexMID\": \"abcedefg\"\n },\n \"message\": \"Fetched payment method successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `paymentMethodId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Cancel a Payment", "slug": "payments-cancel-a-payment", "description": "Cancels the initiated payment. You can use this API to cancel the payment instance created. However, you cannot cancel a completed payment. If the payment is already completed, you can use the Void a Payment API to void the specific payment.", "api": "Payments API", "method": "DELETE", "path": "/payments/:paymentId", "content": "# Cancel a Payment\n\n## Overview\nCancels the initiated payment. You can use this API to cancel the payment instance created. However, you cannot cancel a completed payment. If the payment is already completed, you can use the Void a Payment API to void the specific payment.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `paymentId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /payments/:paymentId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `paymentStatus` | `string` | Describes the status of the payment. Possible values: `PAYMENT_COMPLETED`, `PAYMENT_FAILED`, `PAYMENT_CANCELLED`. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"paymentStatus\": \"PAYMENT_CANCELLED\"\n },\n \"message\": \"Payment cancelled successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `paymentId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Capture Payment", "slug": "payments-capture-payment", "description": "Use this API to complete the authorization and capture a payment while using the pre-auth flow or to capture a payment when the delayCapture flag is set.", "api": "Payments API", "method": "POST", "path": "/payments/:paymentId/capture", "content": "# Capture Payment\n\n## Overview\nUse this API to complete the authorization and capture a payment while using the pre-auth flow or to capture a payment when the delayCapture flag is set.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `paymentId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /payments/:paymentId/capture\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Payment captured successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `paymentId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Check Capture Status", "slug": "payments-check-capture-status", "description": "Retrieves the status of the capture payment request. Capture payments for delayed capture is an asynchronous request that is processed in batches. Once the initial capture request is made, make this call after approximately 30 minutes to get the response.", "api": "Payments API", "method": "GET", "path": "/payments/:paymentId/capture", "content": "# Check Capture Status\n\n## Overview\nRetrieves the status of the capture payment request. Capture payments for delayed capture is an asynchronous request that is processed in batches. Once the initial capture request is made, make this call after approximately 30 minutes to get the response.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `paymentId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /payments/:paymentId/capture\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /payments/:paymentId/capture\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `captureStatus` | `string` | Denotes the status of the capture request for payment. Possible values: `PENDING`, `SUCCESS`, `ERROR`. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"captureStatus\": \"SUCCESS\"\n },\n \"message\": \"Capture status fetched successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `paymentId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Initiate a Payment", "slug": "payments-initiate-a-payment", "description": "Initiates a payment for a specific order. Use this API to initiate a payment for the order created. The default method for processing the initiated payment is via card. Additional payment methods can be enabled using the Payment Methods API.", "api": "Payments API", "method": "POST", "path": "/payments", "content": "# Initiate a Payment\n\n## Overview\nInitiates a payment for a specific order. Use this API to initiate a payment for the order created. The default method for processing the initiated payment is via card. Additional payment methods can be enabled using the Payment Methods API.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /payments\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentMethod` | `string` | Yes | Specifies the method in which the payment is to be processed. Possible values: `CARD`, `CARD_NP`, `KLARNA`, `CTOKEN`, `GIFTCARD`, `SWISH`. |\n| `orderId` | `string` | Yes | Unique identifier of the order to initiate payment for. |\n| `terminalId` | `string` | No | Unique identifier of the terminal that initiates the payment, used for in-store and card-present flows. |\n| `amount` | `number` | No | Amount to charge in the smallest currency unit (e.g., 10 SEK is 1000). Use this to make partial payments on the order; defaults to the order total when omitted. |\n| `initialOrderReference` | `string` | No | Reference to an original order, used for follow-up or linked payments. |\n| `adjustments` | `array` | No | List of order-level monetary adjustments to apply to the payment. |\n|     `adjustmentAmount` | `number` | Yes | Mandatory monetary value of the adjustment in the smallest currency unit. |\n|     `amount` | `number` | No | Optional explicit monetary amount for the adjustment in the smallest currency unit, distinct from the mandatory adjustmentAmount. |\n|     `adjustmentType` | `string` | Yes | Type or category of the adjustment, such as tip or discount. |\n|     `metadata` | `object` | No | Arbitrary key/value metadata attached to the adjustment. |\n|     `createdBy` | `string` | No | Identifier of the actor who created the adjustment. |\n| `paymentMethodParams` | `object` | No | Method-specific parameters for the chosen payment method. |\n|     `tokenId` | `string` | No | Saved-card or payment token identifier to charge for tokenised card payments. |\n|     `bic` | `string` | No | The BIC (Bank Identifier Code) is an ISO 9362 standard that uniquely identifies a bank, used for account-to-account and bank payments. |\n|     `ip` | `string` | No | Customer IP address used as risk and fraud context. |\n|     `swishMode` | `string` | No | Swish flow variant or mode selector (e.g., ECOM). |\n|     `payeePhoneNumber` | `object` | No | Payee phone number for Swish payments. |\n|         `code` | `string` | Yes | International dialing code (e.g., 46 for Sweden without '+'). |\n|         `number` | `string` | Yes | National subscriber number. |\n|     `giftCardId` | `string` | No | Identifier of the gift card to redeem. |\n|     `invoice` | `object` | No | Invoice payment configuration. |\n|         `invoiceDistribution` | `string` | No | Channel used to deliver the invoice (e.g., EMAIL). |\n|         `contractReference` | `string` | No | Reference to the underlying contract or agreement. |\n|         `debtCollectionEnabled` | `boolean` | No | Whether unpaid invoices are sent to debt collection. |\n|         `dueDate` | `string` | No | Relative due date for the invoice as a chrono expression (e.g., 30d). |\n|         `invoicePaymentMethods` | `array` | No | Permitted payment methods for settling the invoice. Possible values: `BANK`, `DIRECT_BANK`, `CARD`. |\n|         `reminder` | `boolean` | No | Whether a payment reminder should be sent. |\n| `serialSplitPaymentsMode` | `array` | No | An array of amounts in smallest currency unit to split the payment. The order of the amounts in the array will determine the order of the split payments. |\n| `refundProcessingParams` | `object` | No | Refund metadata used when processing refunds. |\n|     `purchasePaymentId` | `string` | No | Identifier of the original purchase payment being refunded. |\n|     `refundReason` | `string` | No | Reason for the refund request. Possible values: `CUSTOMER_INITIATED_RETURN`, `SUSPECTED_MALFUNCTION`, `SUSPECTED_FRAUD`, `DUPLICATE_TRANSACTION`, `OTHER`. |\n|     `otherReason` | `string` | No | Free-text reason for the return request when it does not fall into any of the predefined categories. |\n| `language` | `string` | No | Client or SDK short language code (e.g., fi, no) used to resolve the Klarna session locale. |\n\n### Request Example\n```json\n{\n \"orderId\": \"838ca7fc6d7de9770b\",\n \"paymentMethod\": \"CARD\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `paymentId` | `string` | A payment ID assigned to each payment instance. Ensure that this ID is stored securely and tied to an identifiable entity until the payment completion. |\n|     `interAppJWT` | `string` | This key can be used in the inter-app flow to be passed in as part of the app switch. This is an optional key that can improve inter-app transaction initiation performance. This is currently only functional for CARD payments. |\n|     `paymentUrl` | `string` | Direct URL for payment processing. |\n|     `qr` | `string` | QR code data for payment. |\n|     `qrData` | `string` | Raw QR code data for payment processing. |\n|     `qrVisibleFor` | `string` | Duration for which the QR code remains visible. |\n|     `qrLink` | `string` | Link to the QR code for payment. |\n|     `klarnaClientToken` | `string` | Client token for Klarna payment processing. |\n|     `paymentToken` | `string` | Token for payment processing. |\n|     `sveaInitiationParams` | `string` | Initiation parameters for Svea payment processing. |\n|     `epassiInitiationParams` | `string` | Initiation parameters for Epassi payment processing. |\n|     `invoiceDetails` | `object` | Invoice details for the payment when applicable. |\n|         `invoiceId` | `number` | Unique identifier for the invoice. |\n|         `invoicePdfUrl` | `string` | URL to download the invoice PDF. |\n|         `iban` | `string` | International Bank Account Number for the invoice. |\n|         `accountHolderName` | `string` | Name of the account holder for the invoice. |\n|         `bic` | `string` | Bank Identifier Code for the invoice. |\n|         `bankgiro` | `string` | Bankgiro number to pay the invoice to. |\n|         `ocr` | `string` | OCR reference number to quote when paying the invoice. |\n|     `adjustmentsSummary` | `object` | Summary of the adjustments applied to the payment. |\n|         `totalAmount` | `number` | Total amount of all applied adjustments in the smallest currency unit. |\n|         `count` | `number` | Number of adjustments applied to the payment. |\n|         `adjustments` | `array` | Individual adjustments applied to the payment. |\n|             `amount` | `number` | Amount of the adjustment in the smallest currency unit. |\n|             `type` | `string` | Type or category of the adjustment, such as tip or discount. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"paymentId\": \"811f9bd48c6eb80c06\",\n \"interAppJWT\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvaWQiOiI4MzA0NDdkM2U3NGQwMDBiMGIiLCJ0aWQiOiI4MmZmN2MyNTgxNDhkODA1MDQiLCJwaWQiOiI4MzA0NGIzNzAzZmVkODAxMDYiLCJwbSI6IkNBUkQiLCJhIjoxMDAwLCJjIjoiNzUyIiwiY29udHJvbEZ1bmN0aW9uc0VuY29kZXIiOiIxIiwiaXNzdWVkQnkiOiJzYi5wcyIsImlhdCI6MTc0MjIyMTI5NDE1NH0.ftXsXUKmNl-ck47jXKPIa1WXbmH0gbiM8nUAOjBbb0U\",\n \"invoiceDetails\": {\n \"invoiceId\": 1024,\n \"invoicePdfUrl\": \"https://invoices.example.com/811f9bd48c6eb80c06.pdf\",\n \"iban\": \"SE3550000000054910000003\",\n \"accountHolderName\": \"Surfboard AB\",\n \"bic\": \"ESSESESS\",\n \"bankgiro\": \"5050-1055\",\n \"ocr\": \"1234567890123\"\n },\n \"adjustmentsSummary\": {\n \"totalAmount\": 100,\n \"count\": 1,\n \"adjustments\": [\n {\n \"amount\": 100,\n \"type\": \"tip\"\n }\n ]\n }\n },\n \"message\": \"Payment initiated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n\n---" }, { "title": "Void a Payment", "slug": "payments-void-a-payment", "description": "Voids a completed payment. If a merchant identifies an issue with a payment soon after it has been completed, use this API to promptly void the payment, thereby preventing potential issues arising from incorrect payments. Note that payment has to be in status 'PAYMENT_COMPLETED' and void triggered before 23:50 CET. For orders with delayCapture set to true, void can be initiated anytime before the capture call.", "api": "Payments API", "method": "PUT", "path": "/payments/:paymentId/void", "content": "# Void a Payment\n\n## Overview\nVoids a completed payment. If a merchant identifies an issue with a payment soon after it has been completed, use this API to promptly void the payment, thereby preventing potential issues arising from incorrect payments. Note that payment has to be in status 'PAYMENT_COMPLETED' and void triggered before 23:50 CET. For orders with delayCapture set to true, void can be initiated anytime before the capture call.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `paymentId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /payments/:paymentId/void\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `voidStatus` | `string` | Depicts the status of the void command. Possible values: `NOT_INITIATED`, `VOID_INITIATED`, `CANNOT_VOID`, `VOIDED`. |\n|     `message` | `string` | Message describing the outcome of the void request. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"voidStatus\": \"VOID_INITIATED\",\n \"message\": \"Void initiated successfully\"\n },\n \"message\": \"payment void status successfully retrieved from external API\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `paymentId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Add Related Products", "slug": "product-catalog-add-related-products", "description": "This API helps you to tag the product with other relatable products in the catalog.", "api": "Product Catalog API", "method": "POST", "path": "/catalog/:catalogId/products/:productId/related-products", "content": "# Add Related Products\n\n## Overview\nThis API helps you to tag the product with other relatable products in the catalog.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /catalog/:catalogId/products/:productId/related-products\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | Yes | Unique identifier of the store where the product exists. |\n| `relatedProducts` | `array` | Yes | An array of product Id's. |\n\n### Request Example\n```json\n{\n \"storeId\": \"8136a645a2c2d1bb0f\",\n \"relatedProducts\": [\n \"818f9fc43d0b580f01\"\n ]\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Related Products for merchant added successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Add Variant For Product", "slug": "product-catalog-add-variant-for-product", "description": "This API allows you to add a variant to an existing product in the product catalog.", "api": "Product Catalog API", "method": "POST", "path": "/catalog/:catalogId/products/:productId/variants", "content": "# Add Variant For Product\n\n## Overview\nThis API allows you to add a variant to an existing product in the product catalog.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /catalog/:catalogId/products/:productId/variants\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | Yes | Unique identifier of the store where the product exists. |\n| `variants` | `array` | Yes | Specifications of the product. |\n|     `name` | `string` | Yes | Name of the variant. |\n|     `description` | `string` | No | Description of the variant. |\n|     `popularity` | `number` | No | Popularity score of the variant. |\n|     `costPrice` | `number` | No | Cost price of the variant, in the smallest unit of the currency. |\n|     `sellingPrice` | `number` | No | Selling price of the variant, in the smallest unit of the currency. |\n|     `currencyCode` | `string` | No | It refers to the standardised code used to represent a specific currency. |\n|     `productImages` | `array` | No | An array of URLs showcasing the variant images. |\n|     `baseAttributes` | `array` | No | Variant attribute definitions for the variant. |\n|         `attributeLabel` | `string` | Yes | Human-readable label for the attribute, for example Color. |\n|         `attributeKey` | `string` | Yes | Machine key for the attribute, for example color. |\n|     `attributeValues` | `array` | Yes | Use to show the available variants of the products. |\n|         `attributeKey` | `string` | Yes | This refers to the category of the variant. |\n|         `displayName` | `string` | Yes | Name of the variant. |\n|         `value` | `string` | Yes | Value of the variant. |\n|     `variantProperties` | `object` | No | Free-form key/value properties describing the variant, such as size, weight or origin. |\n|     `metadata` | `object` | No | Free-form key/value metadata you can attach to the variant for your own use. |\n\n### Request Example\n```json\n{\n \"storeId\": \"8136a645a2c2d1bb0f\",\n \"variants\": [\n {\n \"name\": \"SurfPad Blue Variant\",\n \"description\": \"Blue variant of SurfPad\",\n \"costPrice\": 1000,\n \"sellingPrice\": 1200,\n \"currencyCode\": \"752\",\n \"productImages\": [\n \"https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg\"\n ],\n \"attributeValues\": [\n {\n \"attributeKey\": \"colour\",\n \"displayName\": \"blue\",\n \"value\": \"#0000FF\"\n },\n {\n \"attributeKey\": \"size\",\n \"displayName\": \"medium\",\n \"value\": \"M\"\n }\n ]\n }\n ]\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `variants` | `array` | Unique ID of the newly added variants. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"variants\": [\n \"81c319b6c7d2080807\"\n ]\n },\n \"message\": \"Variants added successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Product Catalog", "slug": "product-catalog-create-product-catalog", "description": "This API lets you to create a product catalog for your store to make an effortless product organization in the catalog.", "api": "Product Catalog API", "method": "POST", "path": "/catalog", "content": "# Create Product Catalog\n\n## Overview\nThis API lets you to create a product catalog for your store to make an effortless product organization in the catalog.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /catalog\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | Yes | Unique identifier of the store where the catalog will be created. |\n| `startDate` | `string` | No | Date the catalog becomes active, in ISO 8601 format. When omitted, the catalog has no start date. |\n| `endDate` | `string` | No | Date the catalog expires, in ISO 8601 format. When omitted, the catalog has no end date. |\n\n### Request Example\n```json\n{\n \"storeId\": \"8136a645a2c2d1bb0f\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data |\n|     `catalogId` | `string` | Unique ID of the newly created catalog. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"catalogId\": \"8219688f18ebb8020a\"\n },\n \"message\": \"Product catalog created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n\n---" }, { "title": "Create Product", "slug": "product-catalog-create-product", "description": "This API allows you to create a product in the product catalog.", "api": "Product Catalog API", "method": "POST", "path": "/catalog/:catalogId/products", "content": "# Create Product\n\n## Overview\nThis API allows you to create a product in the product catalog.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /catalog/:catalogId/products\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | Yes | Unique identifier of the store where the product will be created. |\n| `name` | `string` | Yes | Name of the product. |\n| `type` | `string` | Yes | A Product can exist in two ways as. Possible values: `PRODUCT`, `SERVICE`. |\n| `unitType` | `string` | Yes | This refers to the way a product is measured or quantified. Possible values: `FIXED_UNIT`, `VARIABLE_UNIT`, `FREE_UNIT`. |\n| `costPrice` | `number` | No | Cost price of the product, in the smallest unit of the currency (e.g. öre for SEK). |\n| `sellingPrice` | `number` | Yes | Selling price of the product, in the smallest unit of the currency (e.g. öre for SEK). |\n| `currencyCode` | `string` | No | It refers to the standardised code used to represent a specific currency. |\n| `tax` | `array` | No | Array of taxes. |\n|     `type` | `string` | No | Type of tax that applies to the product. Possible values: `VAT`, `CGST`, `SGST`, `GST`. |\n|     `percentage` | `string` | No | Percentage of the tax for the product. |\n|     `amount` | `number` | No | Fixed tax amount for the product, in the smallest unit of the currency. |\n| `description` | `string` | No | Description of the product. |\n| `unit` | `string` | Yes | This refers to the metric unit of the item. The possible values are 'm' , 'mm' , 'cm' , 'km' , 'in' , 'ft' , 'mi' , 'kg' , 'g' , 'mg' , 'lb' , 'oz' , 'l' , 'ml' , 'cu. m' , 'gal' , 'pt' , 'fl oz' , 'W' , 'kW' , 'kWh' , 'sq m' , 'sq km' , 'sq ft' , 'h' , 'min' , 's' , 'days' , 'wk' , 'mn' , 'yr' , 'nos'. |\n| `category` | `string` | No | Free-text category the product is grouped under. |\n| `categoryId` | `string` | No | Identifier of an existing category to file the product under. |\n| `discount` | `number` | No | Discount applied to the product, in the smallest unit of the currency. |\n| `productImages` | `array` | Yes | An array of URLs showcasing the product. |\n| `hsnCode` | `string` | No | A 6-digit uniform code that identifies the product. |\n| `barcode` | `string` | No | Encoded white and black lines on the product. |\n| `baseAttributes` | `array` | No | Variant attribute definitions for the product. |\n|     `attributeLabel` | `string` | No | Human-readable label for the attribute, for example Color. |\n|     `attributeKey` | `string` | No | Machine key for the attribute, for example color. |\n| `attributeValues` | `array` | No | Values assigned to the product for each attribute. |\n|     `attributeKey` | `string` | No | Attribute key the value belongs to. |\n|     `displayName` | `string` | No | Human-readable name of the value. |\n|     `value` | `string` | No | The attribute value itself. |\n| `productProperties` | `object` | No | Additional properties that help describe the product like size, origin, weight, manufacturer, etc. |\n| `metadata` | `object` | No | Free-form key/value metadata you can attach to the product for your own use. |\n| `monthlyPlans` | `object` | No | Refers to the charges of the product or service for a specific time period. |\n|     `description` | `string` | Yes | Description of the billing plan. |\n|     `amount` | `number` | No | Amount of the plan, in the smallest unit of the currency. |\n|     `currency` | `string` | No | It refers to the standardised code used to represent a specific currency. |\n|     `interval` | `string` | No | This refers to the time period of the billing plan. |\n|     `intervalCount` | `number` | No | Duration of the plan. |\n|     `recurring` | `boolean` | No | Denotes if the billing plan should repeat at regular intervals. |\n|     `bindingPeriod` | `number` | No | A binding period is a set timeframe for a billing plan to which the customer is expected to adhere. |\n|     `earlyTerminationPenalty` | `number` | No | It is the additional amount charged in case of early termination if applicable. |\n|     `earlyTermination` | `string` | No | Defines the intended action to be taken if the plan is terminated early. Possible values: `NO_PENALTY`, `BALANCE_AMOUNT`, `BALANCE_AMOUNT_PLUS_PENALTY`. |\n\n### Request Example\n```json\n{\n \"storeId\": \"8136a645a2c2d1bb0f\",\n \"name\": \"SurfPad Purple Logo\",\n \"type\": \"PRODUCT\",\n \"unitType\": \"FIXED_UNIT\",\n \"costPrice\": 2000,\n \"sellingPrice\": 4500,\n \"currencyCode\": \"752\",\n \"tax\": [\n {\n \"type\": \"VAT\",\n \"percentage\": \"25\"\n }\n ],\n \"description\": \"SurfPad Payment Terminal in Purple\",\n \"category\": \"electronics\",\n \"unit\": \"nos\",\n \"productImages\": [\n \"https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg\"\n ],\n \"hsnCode\": \"723453\",\n \"barcode\": \"7812123454323\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data |\n|     `productId` | `string` | Unique ID of the newly added product. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"productId\": \"81c30d16df28880301\"\n },\n \"message\": \"Product created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch all products", "slug": "product-catalog-fetch-all-products", "description": "This API allows you to retrieve all products associated with a product catalog.", "api": "Product Catalog API", "method": "GET", "path": "/catalog/:catalogId/products", "content": "# Fetch all products\n\n## Overview\nThis API allows you to retrieve all products associated with a product catalog.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /catalog/:catalogId/products\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Pagination\n\nPass the mandatory `storeId` query parameter as a string. Page through results with the `x-page-number` request header; the total number of matching products is returned in the `x-total-items` response header.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /catalog/:catalogId/products\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data |\n|     `products` | `array` | Details of the products. |\n|         `productId` | `string` | ID of the product. |\n|         `name` | `string` | Name of the product. |\n|         `currencyCode` | `string` | It refers to the standardised code used to represent a specific currency. |\n|         `description` | `string` | Description of the product. |\n|         `category` | `string` | Category the product is grouped under. |\n|         `unit` | `string` | This refers to the metric unit of the item. The possible values are 'm' , 'mm' , 'cm' , 'km' , 'in' , 'ft' , 'mi' , 'kg' , 'g' , 'mg' , 'lb' , 'oz' , 'l' , 'ml' , 'cu. m' , 'gal' , 'pt' , 'fl oz' , 'W' , 'kW' , 'kWh' , 'sq m' , 'sq km' , 'sq ft' , 'h' , 'min' , 's' , 'days' , 'wk' , 'mn' , 'yr' , 'nos'. |\n|         `productImages` | `array` | An array of URLs showcasing the product images. |\n|         `discount` | `number` | Discount applied to the product, in the smallest unit of the currency. |\n|         `hsnCode` | `string` | A 6-digit uniform code that identifies the product. |\n|         `barcode` | `string` | Encoded white and black lines on the products. |\n|         `variantCategory` | `array` | The variant categories defined for the product. |\n|         `productProperties` | `object` | Additional properties that describe the product details, which include type, size, origin, weight, manufacturer, etc. |\n|         `inventory` | `object` | Defines the information about the stock levels of the products listed in the catalog. |\n|         `unitType` | `string` | This specifies the general representation of quantity based on the product details and they have possible types. Possible values: `FIXED_UNIT`, `VARIABLE_UNIT`, `FREE_UNIT`. |\n|         `type` | `string` | Whether the item is a PRODUCT or a SERVICE. |\n|         `relatedProducts` | `array` | Identifiers of products tagged as related to this product. |\n|         `sellingPrice` | `number` | Selling price of the product, in the smallest unit of the currency. |\n|         `variants` | `array` | Variants of the product. |\n|         `billingPlans` | `array` | Recurring billing plans available for the product. |\n|         `tax` | `array` | Array of taxes. |\n|             `type` | `string` | Type of tax that applies to the product, for example VAT. |\n|             `percentage` | `string` | Percentage of the tax for the product. |\n|             `amount` | `number` | Fixed tax amount for the product, in the smallest unit of the currency. |\n|         `attributeValues` | `array` | Attribute values assigned to the product. |\n|             `attributeKey` | `string` | Key of the attribute. |\n|             `displayName` | `string` | Display name of the attribute. |\n|             `value` | `string` | Value of the attribute. |\n|         `campaignInfo` | `array` | Information of campaign. |\n|             `campaignName` | `string` | Name of the campaign. |\n|             `campaignId` | `string` | ID of the campaign. |\n|             `fixedAmount` | `number` | Reduced price during the campaign, in the smallest unit of the currency. |\n|             `percentage` | `string` | Percentage discount applied during the campaign. |\n|         `metadata` | `object` | Free-form key/value metadata attached to the product. |\n|     `bundles` | `array` | Refers to the products grouped together in a category. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"products\": [\n {\n \"productId\": \"823913d474de600e01\",\n \"name\": \"SurfPad Black Logo\",\n \"currencyCode\": \"752\",\n \"description\": \"SurfPad Payment Terminal in Black\",\n \"category\": \"electronics\",\n \"unit\": \"nos\",\n \"productImages\": [\n \"https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg\"\n ],\n \"hsnCode\": \"723453\",\n \"barcode\": \"7812123454323\",\n \"productProperties\": {\n \"size\": \"15x5 cm\",\n \"origin\": \"sweden\",\n \"weight\": \"250 g\",\n \"manufacturer\": \"datecs\"\n },\n \"inventory\": {},\n \"unitType\": \"FIXED_UNIT\",\n \"type\": \"PRODUCT\",\n \"relatedProducts\": [],\n \"sellingPrice\": 1500,\n \"variants\": [],\n \"billingPlans\": [],\n \"tax\": [\n {\n \"type\": \"VAT\",\n \"percentage\": \"25\",\n \"amount\": 0\n }\n ],\n \"campaignInfo\": [\n {\n \"campaignName\": \"First campaign\",\n \"campaignId\": \"8239b16f0a59580224\",\n \"fixedAmount\": 2000,\n \"percentage\": null\n }\n ]\n }\n ],\n \"bundles\": []\n },\n \"message\": \"Products fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Fetch Product Catalogs", "slug": "product-catalog-fetch-product-catalogs", "description": "Retrieves all product catalogs under the store.", "api": "Product Catalog API", "method": "GET", "path": "/catalog", "content": "# Fetch Product Catalogs\n\n## Overview\nRetrieves all product catalogs under the store.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nGET /catalog\n```\n\n### Query Parameters\nPass the mandatory `storeId` query parameter as a string to fetch the catalogs under a store.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /catalog\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data |\n|     `catalogIds` | `array` | List of product catalog IDs existing under the store. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"catalogIds\": [\n \"8187c051854a38000a\",\n \"818a5d4df1c258090a\",\n \"818bb06b93a5500b0a\",\n \"818f9f37bd0b58040a\"\n ]\n },\n \"message\": \"Product catalog fetched for storeId: 8136a645a2c2d1bb0f\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n\n---" }, { "title": "Fetch Product by Id", "slug": "product-catalog-fetch-product-by-id", "description": "This API allows you to retrieve a specific product by its ID.", "api": "Product Catalog API", "method": "GET", "path": "/catalog/:catalogId/products/:productId", "content": "# Fetch Product by Id\n\n## Overview\nThis API allows you to retrieve a specific product by its ID.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /catalog/:catalogId/products/:productId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\nPass the mandatory `storeId` query parameter as a string to fetch a specific product by its ID.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /catalog/:catalogId/products/:productId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data containing the product details. |\n|     `id` | `string` | Unique identifier of the product. |\n|     `name` | `string` | Name of the product. |\n|     `sellingPrice` | `number` | Selling price of the product. |\n|     `currencyCode` | `string` | Currency code for the product price. |\n|     `description` | `string` | Description of the product. |\n|     `category` | `string` | Category of the product. |\n|     `popularity` | `number` | Popularity score of the product. |\n|     `unit` | `string` | Unit of measurement for the product. |\n|     `hsnCode` | `string` | HSN code of the product. |\n|     `barcode` | `string` | Barcode of the product. |\n|     `type` | `string` | Type of the product. |\n|     `unitType` | `string` | Unit type of the product. |\n|     `attributeValues` | `array` | Array of attribute values for the product. |\n|         `attributeKey` | `string` | Key of the attribute. |\n|         `displayName` | `string` | Display name of the attribute. |\n|         `value` | `string` | Value of the attribute. |\n|     `tax` | `array` | Array of tax information for the product. |\n|         `type` | `string` | Type of tax. |\n|         `percentage` | `string` | Tax percentage. |\n|         `amount` | `number` | Tax amount, in the smallest unit of the currency. |\n|     `productImages` | `array` | Image URLs for the product. |\n|     `productProperties` | `object` | Free-form key/value properties describing the product. |\n|     `inventory` | `object` | Current stock information for the product. |\n|     `relatedProducts` | `array` | Identifiers of products tagged as related to this product. |\n|     `pricingPlans` | `array` | Recurring pricing plans available for the product. |\n|     `distributors` | `array` | Distributors that supply the product. |\n|     `campaignInfo` | `array` | Active campaigns on the product. |\n|     `variants` | `array` | Variants of the product. |\n|     `metadata` | `object` | Free-form key/value metadata attached to the product. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"id\": \"838bfc15a601800901\",\n \"name\": \"Test Product\",\n \"sellingPrice\": 14900,\n \"currencyCode\": \"752\",\n \"description\": \"Sitter som en smäck\",\n \"category\": \"TERMINAL\",\n \"popularity\": 0,\n \"unit\": \"nos\",\n \"hsnCode\": \"\",\n \"barcode\": \"\",\n \"type\": \"PRODUCT\",\n \"unitType\": \"FIXED_UNIT\",\n \"attributeValues\": [\n {\n \"attributeKey\": \"storlek\",\n \"displayName\": \"Storlek XL\",\n \"value\": \"XL\"\n }\n ],\n \"tax\": [\n {\n \"type\": \"VAT\",\n \"percentage\": \"25\",\n \"amount\": 0\n }\n ],\n \"productImages\": [],\n \"productProperties\": {},\n \"inventory\": {},\n \"relatedProducts\": [],\n \"campaignInfo\": [],\n \"variants\": []\n },\n \"message\": \"Products fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Generate Product Catalog from Images", "slug": "product-catalog-generate-product-catalog-from-images", "description": "Generate product catalog data with images and menu information from existing image data. Use this API to extract structured product information from menu images or catalog photos, automatically creating product listings with descriptions and pricing.", "api": "Product Catalog API", "method": "POST", "path": "/catalog/ai/scan", "content": "# Generate Product Catalog from Images\n\n## Overview\nGenerate product catalog data with images and menu information from existing image data. Use this API to extract structured product information from menu images or catalog photos, automatically creating product listings with descriptions and pricing.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /catalog/ai/scan\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `imgData` | `array` | Yes | Array of image URLs or base64 encoded image data to process. |\n| `imageType` | `array` | Yes | Array of image file types corresponding to the imgData array (e.g., 'png', 'jpg'). |\n\n### Request Example\n```json\n{\n \"imgData\": [\n \"https://storage.googleapis.com/sb-merchant-portal-ai-images/testMerchant/TestMenu/menu01.png\"\n ],\n \"imageType\": [\n \"png\"\n ]\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data containing extracted menu and product information. |\n|     `menuData` | `array` | Array of extracted product/menu items with their details. |\n|         `name` | `string` | Name of the product or menu item. |\n|         `description` | `string` | Description of the product or menu item. |\n|         `sellingPrice` | `string` | Price of the product or menu item. |\n|         `currencyCode` | `string` | Currency code for the price (e.g., '840' for USD). |\n|         `category` | `string` | Category classification of the product or menu item. |\n|         `image` | `string` | URL of the generated or associated product image. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"menuData\": [\n [\n {\n \"name\": \"The Junior\",\n \"description\": \"Two eggs any way, your choice of bacon, sausage, or ham, and coffee or tea.\",\n \"sellingPrice\": \"8.50\",\n \"currencyCode\": \"840\",\n \"category\": \"Breakfast Mains\",\n \"image\": \"https://storage.googleapis.com/sb-merchant-portal-ai-images/8113d3f8403b380409%2Fm_iWGri3XAyTmkbKYsYtV47%2Fthe_junior%2Fthe_junior_custom_prompt_09_08_2025_07_45_53_1.png\"\n },\n {\n \"name\": \"Buttermilk or Buckwheat Pancakes\",\n \"description\": \"Fluffy pancakes with a choice of bacon or maple sausage.\",\n \"sellingPrice\": \"8.00\",\n \"currencyCode\": \"840\",\n \"category\": \"Breakfast Mains\",\n \"image\": \"https://storage.googleapis.com/sb-merchant-portal-ai-images/8113d3f8403b380409%2Fm_iWGri3XAyTmkbKYsYtV47%2Fbuttermilk_or_buckwheat_pancakes%2Fbuttermilk_or_buckwheat_pancakes_custom_prompt_09_08_2025_07_45_52_1.png\"\n }\n ]\n ]\n },\n \"message\": \"Menu data extracted successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n\n---" }, { "title": "Generate Product Description", "slug": "product-catalog-generate-product-description", "description": "Generate AI-powered product descriptions based on product name, word length, and language preferences. Use this API to create compelling, professional product descriptions that enhance your product listings and improve customer engagement.", "api": "Product Catalog API", "method": "POST", "path": "/catalog/ai/description", "content": "# Generate Product Description\n\n## Overview\nGenerate AI-powered product descriptions based on product name, word length, and language preferences. Use this API to create compelling, professional product descriptions that enhance your product listings and improve customer engagement.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /catalog/ai/description\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `productName` | `string` | Yes | Name of the product for which to generate the description. |\n| `maxWordLength` | `number` | No | Maximum number of words for the generated description. |\n| `langCode` | `string` | No | Language code for the description generation (e.g., 'en' for English). |\n\n### Request Example\n```json\n{\n \"productName\": \"Addidas Running Shoes\",\n \"maxWordLength\": 150,\n \"langCode\": \"en\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data containing the generated description. |\n|     `description` | `string` | AI-generated product description. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"description\": \"Unleash your peak performance with Adidas running shoes, meticulously engineered for speed, comfort, and endurance. Experience the revolutionary boost midsole technology that returns energy with every stride, propelling you forward effortlessly. The lightweight, breathable upper ensures optimal ventilation, keeping your feet cool and dry even during intense workouts. Designed with a precision fit, these shoes offer exceptional support and stability, reducing the risk of injury and enhancing your natural gait. Whether you're a seasoned marathoner or a casual jogger, Adidas running shoes provide the perfect blend of innovation and style. Conquer your goals and shatter your personal bests with the ultimate running companion. Step into a world of unparalleled performance and elevate your running experience with Adidas.\"\n },\n \"message\": \"Description generated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n\n---" }, { "title": "Generate Product Images", "slug": "product-catalog-generate-product-images", "description": "Generate AI-powered product images based on product name, custom prompts, and specifications. Use this API to create professional product images that enhance your product catalog and marketing materials.", "api": "Product Catalog API", "method": "POST", "path": "/catalog/ai/image", "content": "# Generate Product Images\n\n## Overview\nGenerate AI-powered product images based on product name, custom prompts, and specifications. Use this API to create professional product images that enhance your product catalog and marketing materials.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /catalog/ai/image\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `productName` | `string` | Yes | Name of the product for which to generate images. |\n| `prompt` | `string` | No | Custom prompt describing the desired image characteristics and style. |\n| `noOfImages` | `number` | No | Number of images to generate for the product. |\n| `langCode` | `string` | Yes | Language code for image generation context (e.g., 'en' for English). |\n\n### Request Example\n```json\n{\n \"productName\": \"Gaming Laptop\",\n \"prompt\": \"sleek modern design with RGB lighting\",\n \"noOfImages\": 3,\n \"langCode\": \"en\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data containing the generated image paths. |\n|     `imagePath` | `array` | Array of URLs pointing to the generated product images. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"imagePath\": [\n \"https://storage.googleapis.com/sb-merchant-portal-ai-images/8113d3f8403b380409%2Fm_iWGri3XAyTmkbKYsYtV47%2Fadidas_t_shirt%2Fadidas_t_shirt_custom_prompt_09_08_2025_07_44_18_1.png\",\n \"https://storage.googleapis.com/sb-merchant-portal-ai-images/8113d3f8403b380409%2Fm_iWGri3XAyTmkbKYsYtV47%2Fadidas_t_shirt%2Fadidas_t_shirt_custom_prompt_09_08_2025_07_44_18_2.png\"\n ]\n },\n \"message\": \"Images generated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n\n---" }, { "title": "Get Product catalog Statistics", "slug": "product-catalog-get-product-catalog-statistics", "description": "Retrieve comprehensive statistics for an entire product catalog including summary metrics, VAT breakdown, and top-selling products within an optional date range.", "api": "Product Catalog API", "method": "GET", "path": "/catalog/:catalogId/statistics", "content": "# Get Product catalog Statistics\n\n## Overview\nRetrieve comprehensive statistics for an entire product catalog including summary metrics, VAT breakdown, and top-selling products within an optional date range.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /catalog/:catalogId/statistics\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\nOptionally pass the `startDate` and `endDate` query parameters in YYYY-MM-DD format to filter statistics by date range.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /catalog/:catalogId/statistics\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data containing catalog statistics. |\n|     `productCatalogId` | `string` | Unique identifier of the product catalog. |\n|     `productCatalogName` | `string` | Name of the product catalog. |\n|     `query` | `object` | The date range used for filtering statistics. |\n|         `startDate` | `string` | Start date of the statistics period in YYYY-MM-DD format. |\n|         `endDate` | `string` | End date of the statistics period in YYYY-MM-DD format. |\n|     `summary` | `object` | Summary statistics for the entire catalog. |\n|         `totalProducts` | `number` | Total number of products in the catalog. |\n|         `totalVariants` | `number` | Total number of variants across all products. |\n|         `byCurrency` | `array` | Summary statistics broken down by currency. |\n|             `currency` | `string` | Currency code. |\n|             `totalUnitsSold` | `number` | Total number of units sold. |\n|             `totalUnitsReturned` | `number` | Total number of units returned. |\n|             `totalRevenue` | `number` | Total revenue generated. |\n|             `totalVat` | `number` | Total VAT collected. |\n|             `totalCampaignDiscount` | `number` | Total campaign discount applied. |\n|             `orderCount` | `number` | Total number of orders. |\n|             `averageOrderValue` | `number` | Average order value. |\n|     `vatBreakdown` | `array` | VAT breakdown by percentage for the entire catalog. |\n|         `vatPercentage` | `string` | VAT percentage applied. |\n|         `vatAmount` | `number` | Total VAT amount collected at this percentage. |\n|         `taxableAmount` | `number` | Total taxable amount at this percentage. |\n|     `topSellingProducts` | `array` | List of top-selling products in the catalog. |\n|         `productId` | `string` | Unique identifier of the product. |\n|         `productName` | `string` | Name of the product. |\n|         `totalUnitsSold` | `number` | Total number of units sold for this product. |\n|         `totalRevenue` | `number` | Total revenue generated by this product. |\n|         `currencyBreakdown` | `array` | Sales breakdown by currency for this product. |\n|             `currency` | `string` | Currency code. |\n|             `totalUnitsSold` | `number` | Total units sold in this currency. |\n|             `totalRevenue` | `number` | Total revenue in this currency. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"productCatalogId\": \"8372ed4bc2c0000b0a\",\n \"productCatalogName\": \"Electronics & Accessories\",\n \"query\": {\n \"startDate\": \"2025-07-01\",\n \"endDate\": \"2025-12-01\"\n },\n \"summary\": {\n \"totalProducts\": 5,\n \"totalVariants\": 2,\n \"byCurrency\": [\n {\n \"currency\": \"666\",\n \"totalUnitsSold\": 17,\n \"totalUnitsReturned\": 0,\n \"totalRevenue\": 20000,\n \"totalVat\": 1130,\n \"totalCampaignDiscount\": 0,\n \"orderCount\": 5,\n \"averageOrderValue\": 4000\n },\n {\n \"currency\": \"752\",\n \"totalUnitsSold\": 120,\n \"totalUnitsReturned\": 0,\n \"totalRevenue\": 120000,\n \"totalVat\": 6780,\n \"totalCampaignDiscount\": 0,\n \"orderCount\": 30,\n \"averageOrderValue\": 4000\n }\n ]\n },\n \"vatBreakdown\": [\n {\n \"vatPercentage\": \"6\",\n \"vatAmount\": 7910,\n \"taxableAmount\": 140000\n }\n ],\n \"topSellingProducts\": [\n {\n \"productId\": \"8372ed51c2c0000701\",\n \"productName\": \"Wireless Bluetooth Headphones\",\n \"totalUnitsSold\": 92,\n \"totalRevenue\": 92000,\n \"currencyBreakdown\": [\n {\n \"currency\": \"752\",\n \"totalUnitsSold\": 92,\n \"totalRevenue\": 92000\n }\n ]\n },\n {\n \"productId\": \"8393dbb7e836b00a01\",\n \"productName\": \"USB-C Charging Cable\",\n \"totalUnitsSold\": 44,\n \"totalRevenue\": 44000,\n \"currencyBreakdown\": [\n {\n \"currency\": \"752\",\n \"totalUnitsSold\": 28,\n \"totalRevenue\": 28000\n },\n {\n \"currency\": \"666\",\n \"totalUnitsSold\": 16,\n \"totalRevenue\": 16000\n }\n ]\n },\n {\n \"productId\": \"83757823162fe00501\",\n \"productName\": \"Portable Power Bank 10000mAh\",\n \"totalUnitsSold\": 1,\n \"totalRevenue\": 4000,\n \"currencyBreakdown\": [\n {\n \"currency\": \"666\",\n \"totalUnitsSold\": 1,\n \"totalRevenue\": 4000\n }\n ]\n }\n ]\n },\n \"message\": \"Product catalog statistics fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Product Statistics", "slug": "product-catalog-get-product-statistics", "description": "Retrieve comprehensive statistics for a specific product including sales data, inventory status, VAT breakdown, and variant performance metrics within an optional date range.", "api": "Product Catalog API", "method": "GET", "path": "/catalog/:catalogId/products/:productId/statistics", "content": "# Get Product Statistics\n\n## Overview\nRetrieve comprehensive statistics for a specific product including sales data, inventory status, VAT breakdown, and variant performance metrics within an optional date range.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /catalog/:catalogId/products/:productId/statistics\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\nOptionally pass the `startDate` and `endDate` query parameters in YYYY-MM-DD format to filter statistics by date range.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /catalog/:catalogId/products/:productId/statistics\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data containing product statistics. |\n|     `productId` | `string` | Unique identifier of the product. |\n|     `productName` | `string` | Name of the product. |\n|     `unit` | `string` | Unit of measurement for the product. |\n|     `query` | `object` | The date range used for filtering statistics. |\n|         `startDate` | `string` | Start date of the statistics period in YYYY-MM-DD format. |\n|         `endDate` | `string` | End date of the statistics period in YYYY-MM-DD format. |\n|     `statistics` | `object` | Sales and performance statistics for the product. |\n|         `byCurrency` | `array` | Statistics broken down by currency. |\n|             `currency` | `string` | Currency code. |\n|             `totalUnitsSold` | `number` | Total number of units sold. |\n|             `totalUnitsReturned` | `number` | Total number of units returned. |\n|             `totalRevenue` | `number` | Total revenue generated. |\n|             `totalVat` | `number` | Total VAT collected. |\n|             `totalCampaignDiscount` | `number` | Total campaign discount applied. |\n|             `orderCount` | `number` | Total number of orders containing this product. |\n|             `averageOrderValue` | `number` | Average order value for orders containing this product. |\n|         `netUnitsSold` | `number` | Net units sold after accounting for returns. |\n|     `inventoryStatus` | `object` | Current inventory status of the product. |\n|         `currentStock` | `number` | Current stock quantity available. |\n|         `stockIn` | `number` | Total stock added during the period. |\n|         `stockOut` | `number` | Total stock removed during the period. |\n|     `vatBreakdown` | `array` | VAT breakdown by percentage. |\n|         `vatPercentage` | `string` | VAT percentage applied. |\n|         `vatAmount` | `number` | Total VAT amount collected at this percentage. |\n|         `taxableAmount` | `number` | Total taxable amount at this percentage. |\n|     `variants` | `array` | Statistics for each product variant. |\n|         `variantId` | `string` | Unique identifier of the variant. |\n|         `variantName` | `string` | Name of the variant. |\n|         `unit` | `string` | Unit of measurement for the variant. |\n|         `byCurrency` | `array` | Variant statistics broken down by currency. |\n|         `inventoryStatus` | `object` | Current inventory status of the variant. |\n|         `vatBreakdown` | `array` | VAT breakdown for the variant. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"productId\": \"838bfc15a601800901\",\n \"productName\": \"Test Product\",\n \"unit\": \"nos\",\n \"query\": {\n \"startDate\": \"2025-09-17\",\n \"endDate\": \"2025-12-17\"\n },\n \"statistics\": {\n \"byCurrency\": [],\n \"netUnitsSold\": 0\n },\n \"inventoryStatus\": {\n \"currentStock\": 0,\n \"stockIn\": 0,\n \"stockOut\": 0\n },\n \"vatBreakdown\": [],\n \"variants\": []\n },\n \"message\": \"Product statistics fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Product Inventory", "slug": "product-catalog-update-product-inventory", "description": "Update available stocks in the product inventory using this API.", "api": "Product Catalog API", "method": "PATCH", "path": "/catalog/:catalogId/products/:productId/inventory", "content": "# Update Product Inventory\n\n## Overview\nUpdate available stocks in the product inventory using this API.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /catalog/:catalogId/products/:productId/inventory\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | Yes | Unique identifier of the store where the product exists. |\n| `operation` | `string` | Yes | Defines the way in which the existing stock is modified. Possible values: `STOCK_UP`, `STOCK_DOWN`. |\n| `quantity` | `number` | Yes | Defines the number of units of a specific product that are available in stock. |\n| `unit` | `string` | Yes | This refers to the metric unit of the item. The possible values are 'm' , 'mm' , 'cm' , 'km' , 'in' , 'ft' , 'mi' , 'kg' , 'g' , 'mg' , 'lb' , 'oz' , 'l' , 'ml' , 'cu. m' , 'gal' , 'pt' , 'fl oz' , 'W' , 'kW' , 'kWh' , 'sq m' , 'sq km' , 'sq ft' , 'h' , 'min' , 's' , 'days' , 'wk' , 'mn' , 'yr' , 'nos'. |\n\n### Request Example\n```json\n{\n \"storeId\": \"8136a645a2c2d1bb0f\",\n \"operation\": \"STOCK_UP\",\n \"quantity\": 10,\n \"unit\": \"nos\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Inventory updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Product", "slug": "product-catalog-update-product", "description": "You can use this API to modify the products.", "api": "Product Catalog API", "method": "PATCH", "path": "/catalog/:catalogId/products/:productId", "content": "# Update Product\n\n## Overview\nYou can use this API to modify the products.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /catalog/:catalogId/products/:productId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | Yes | Unique identifier of the store where the product exists. |\n| `name` | `string` | No | Name of the product. |\n| `costPrice` | `number` | No | Cost price of the product. |\n| `sellingPrice` | `number` | No | Selling price of the product. |\n| `description` | `string` | No | Description of the product. |\n| `category` | `string` | No | This refers to a grouping of similar products that share a common characteristics. |\n| `unit` | `string` | No | This refers to the metric unit of the item. The possible values are 'm' , 'mm' , 'cm' , 'km' , 'in' , 'ft' , 'mi' , 'kg' , 'g' , 'mg' , 'lb' , 'oz' , 'l' , 'ml' , 'cu. m' , 'gal' , 'pt' , 'fl oz' , 'W' , 'kW' , 'kWh' , 'sq m' , 'sq km' , 'sq ft' , 'h' , 'min' , 's' , 'days' , 'wk' , 'mn' , 'yr' , 'nos'. |\n| `productImages` | `array` | No | An array of URLs showcasing the product images. |\n| `hsnCode` | `string` | No | A 6-digit uniform code that identifies the product. |\n| `barcode` | `string` | No | Encoded white and black lines on the products. |\n\n### Request Example\n```json\n{\n \"storeId\": \"8136a645a2c2d1bb0f\",\n \"name\": \"SurfPad Black Logo\",\n \"costPrice\": 0,\n \"sellingPrice\": 1500,\n \"description\": \"SurfPad Payment Terminal in Black\",\n \"category\": \"electronics\",\n \"unit\": \"nos\",\n \"productImages\": [\n \"https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg\"\n ],\n \"hsnCode\": \"723453\",\n \"barcode\": \"7812123454323\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Product updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Variant Inventory", "slug": "product-catalog-update-variant-inventory", "description": "Update available stocks in the variant inventory using this API.", "api": "Product Catalog API", "method": "PATCH", "path": "/catalog/:catalogId/products/:productId/variants/:variantId/inventory", "content": "# Update Variant Inventory\n\n## Overview\nUpdate available stocks in the variant inventory using this API.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n- The resource identified by `variantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /catalog/:catalogId/products/:productId/variants/:variantId/inventory\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n| `variantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | Yes | Unique identifier of the store where the variant exists. |\n| `operation` | `string` | Yes | Defines the way in which the existing variant stock is modified. Possible values: `STOCK_UP`, `STOCK_DOWN`. |\n| `quantity` | `number` | Yes | Defines the number of units of a specific variant that are available in stock. |\n| `unit` | `string` | Yes | This refers to the metric unit of the variant. The possible values are 'm' , 'mm' , 'cm' , 'km' , 'in' , 'ft' , 'mi' , 'kg' , 'g' , 'mg' , 'lb' , 'oz' , 'l' , 'ml' , 'cu. m' , 'gal' , 'pt' , 'fl oz' , 'W' , 'kW' , 'kWh' , 'sq m' , 'sq km' , 'sq ft' , 'h' , 'min' , 's' , 'days' , 'wk' , 'mn' , 'yr' , 'nos'. |\n\n### Request Example\n```json\n{\n \"storeId\": \"8136a645a2c2d1bb0f\",\n \"operation\": \"STOCK_UP\",\n \"quantity\": 15,\n \"unit\": \"nos\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Variant inventory updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n- The `variantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Variant", "slug": "product-catalog-update-variant", "description": "You can use this API to modify the product variants.", "api": "Product Catalog API", "method": "PATCH", "path": "/catalog/:catalogId/products/:productId/variants/:variantId", "content": "# Update Variant\n\n## Overview\nYou can use this API to modify the product variants.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n- The resource identified by `variantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /catalog/:catalogId/products/:productId/variants/:variantId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n| `variantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | Yes | Unique identifier of the store where the variant exists. |\n| `name` | `string` | No | Name of the variant. |\n| `costPrice` | `number` | No | Cost price of the variant. |\n| `sellingPrice` | `number` | No | Selling price of the variant. |\n| `description` | `string` | No | Description of the variant. |\n| `category` | `string` | No | This refers to a grouping of similar variants that share a common characteristics. |\n| `unit` | `string` | No | This refers to the metric unit of the variant. The possible values are 'm' , 'mm' , 'cm' , 'km' , 'in' , 'ft' , 'mi' , 'kg' , 'g' , 'mg' , 'lb' , 'oz' , 'l' , 'ml' , 'cu. m' , 'gal' , 'pt' , 'fl oz' , 'W' , 'kW' , 'kWh' , 'sq m' , 'sq km' , 'sq ft' , 'h' , 'min' , 's' , 'days' , 'wk' , 'mn' , 'yr' , 'nos'. |\n| `productImages` | `array` | No | Product images for the variant. |\n| `hsnCode` | `string` | No | A 6-digit uniform code that identifies the variant. |\n| `barcode` | `string` | No | Encoded white and black lines on the variants. |\n| `variantProperties` | `object` | No | Denotes the additional properties that describe the variant details which includes type, size, origin, weight, manufacturer, etc. |\n\n### Request Example\n```json\n{\n \"storeId\": \"8136a645a2c2d1bb0f\",\n \"name\": \"SurfPad Black Logo - Large\",\n \"costPrice\": 0,\n \"sellingPrice\": 1800,\n \"description\": \"SurfPad Payment Terminal in Black - Large Size\",\n \"category\": \"electronics\",\n \"unit\": \"nos\",\n \"productImages\": [\n \"https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg\"\n ],\n \"hsnCode\": \"723453\",\n \"barcode\": \"7812123454323\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Variant updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n- The `variantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Promotion", "slug": "promotions-create-promotion", "description": "Creates a new promotion for a merchant. Set `promoType` to choose the mechanism — a promo code that discounts a customer’s order, or a redirect link that sends customers to a destination — then define the schedule, the visual assets shown to customers, and any eligibility, redemption, and usage rules. A newly created promotion is not yet visible to customers: assign it to one or more stores and sync it to their terminals to make it live. The promotion type is fixed once the promotion is created.", "api": "Promotions API", "method": "POST", "path": "/merchants/:merchantId/promotions/v2", "content": "# Create Promotion\n\n## Overview\nCreates a new promotion for a merchant. Set `promoType` to choose the mechanism — a promo code that discounts a customer’s order, or a redirect link that sends customers to a destination — then define the schedule, the visual assets shown to customers, and any eligibility, redemption, and usage rules. A newly created promotion is not yet visible to customers: assign it to one or more stores and sync it to their terminals to make it live. The promotion type is fixed once the promotion is created.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /merchants/:merchantId/promotions/v2\n```\n\n### Headers\n| Header | Value | Required |\n|--------|-------|----------|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Request Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| merchantId | string | Yes | The unique identifier of the merchant the promotion belongs to. |\n| name | string | Yes | A name used to identify the promotion in the dashboard. |\n| promoType | string | Yes | The promotion mechanism. This is fixed at creation and cannot be changed later. Values: `PROMO_CODE`, `REDIRECT_LINK`. |\n| schedule | object | Yes | The window during which the promotion runs. |\n| schedule.startTime | string | Yes | ISO-8601 timestamp at which the promotion becomes active. |\n| schedule.endTime | string | Yes | ISO-8601 timestamp at which the promotion ends. |\n| visualAssets | array | Yes | The content shown to customers for the promotion. Each item’s `type` determines which of the fields below apply. |\n| visualAssets.type | string | Yes | The kind of asset. Values: `TEXT`, `IMAGE`, `VIDEO`, `BUTTON`. |\n| visualAssets.headline | string | No | The primary line of a TEXT asset. |\n| visualAssets.subheadline | string | No | The secondary line of a TEXT asset. |\n| visualAssets.body | string | No | The body copy of a TEXT asset. |\n| visualAssets.url | string | No | The public URL of an IMAGE or VIDEO asset. |\n| visualAssets.buttonText | string | No | The label shown on a BUTTON asset. |\n| visualAssets.buttonUrl | string | No | The URL a BUTTON asset opens when tapped. |\n| promoCode | object | No | The discount configuration for a promo-code promotion. |\n| promoCode.code | string | Yes | The code a customer enters at checkout to redeem the offer (for example, SAVE20). |\n| promoCode.offer | object | Yes | How much the code discounts. |\n| promoCode.offer.type | string | Yes | Whether the discount is a percentage or a fixed amount. Values: `PERCENTAGE_OFF`, `FIXED_AMOUNT_OFF`. |\n| promoCode.offer.percentage | number | No | The percentage discount to apply (0–100). |\n| promoCode.offer.amount | number | No | The fixed discount amount, in the smallest currency unit (for example, 10 SEK is 1000). |\n| promoCode.budget | object | Yes | The spend limit for the promo code. |\n| promoCode.budget.maxAmount | number | Yes | The maximum total discount the promotion may give away, in the smallest currency unit. When reached, the promotion stops automatically with status BUDGET_DEPLETED. |\n| redirectLink | object | No | The redirect destination for a redirect-link promotion. |\n| redirectLink.url | string | Yes | The destination the customer is taken to. |\n| assignmentRules | object | No | Conditions an order must satisfy for a customer to be eligible for the promotion. |\n| assignmentRules.minimumOrderAmount | number | No | The minimum order total required, in the smallest currency unit. |\n| assignmentRules.itemPresentInOrder | array | No | The order must contain at least one of these item IDs. |\n| assignmentRules.categoryPresentInOrder | array | No | The order must contain at least one item from these category IDs. |\n| redemptionRules | object | No | Conditions that must be met at checkout before the discount is applied. |\n| redemptionRules.minimumOrderAmount | number | No | The minimum order total required, in the smallest currency unit. |\n| redemptionRules.itemPresentInOrder | array | No | The order must contain at least one of these item IDs. |\n| redemptionRules.categoryPresentInOrder | array | No | The order must contain at least one item from these category IDs. |\n| usageLimits | object | No | Limits on how many times the promotion can be redeemed. |\n| usageLimits.maximumRedemptions | number | Yes | The total number of redemptions allowed across all customers. Once reached, the promotion stops with status ATTEMPTS_EXHAUSTED. |\n| usageLimits.maximumRedemptionsPerCustomer | number | No | The number of redemptions allowed per individual customer (for example, 1 for a one-time offer). |\n\n### Request Example\n```json\n{\n \"name\": \"Loyalty Boost\",\n \"promoType\": \"PROMO_CODE\",\n \"schedule\": {\n \"startTime\": \"2026-08-01T00:00:00Z\",\n \"endTime\": \"2026-08-31T23:59:59Z\"\n },\n \"visualAssets\": [\n {\n \"type\": \"TEXT\",\n \"headline\": \"Members save more\",\n \"subheadline\": \"This August\"\n },\n {\n \"type\": \"BUTTON\",\n \"buttonText\": \"Join now\",\n \"buttonUrl\": \"https://example.com/join\"\n }\n ],\n \"promoCode\": {\n \"code\": \"AUG10\",\n \"offer\": {\n \"type\": \"PERCENTAGE_OFF\",\n \"percentage\": 10\n },\n \"budget\": {\n \"maxAmount\": 5000\n }\n },\n \"assignmentRules\": {\n \"minimumOrderAmount\": 2500\n },\n \"usageLimits\": {\n \"maximumRedemptions\": 1000,\n \"maximumRedemptionsPerCustomer\": 2\n }\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Indicates whether the request succeeded — either 'SUCCESS' or 'ERROR'. |\n| data | object | Identifiers for the created promotion. |\n| data.promotionId | string | The identifier of the new promotion. Use it to fetch, update, assign, sync, or delete the promotion. |\n| message | string | For example, \"Promotion created successfully\". |\n\n### Success Response Example (201)\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"promotionId\": \"promo_8KzR4pQ7eZ2LvUjH\"\n },\n \"message\": \"Promotion created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required fields. Ensure all required parameters are present and valid.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized: Invalid API key or secret.\"\n}\n```\n**Description:** The API key or secret provided in the headers is incorrect. Verify your credentials.\n\n#### 403 - Forbidden\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Forbidden: Insufficient permissions.\"\n}\n```\n**Description:** The provided MERCHANT-ID does not have the necessary permissions to access this endpoint.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An internal server error occurred while processing the request. Retry later; if it persists, contact support.\n\n## Notes\n- Authentication is required via API Key and API Secret, along with a valid `MERCHANT-ID`.\n- All path parameters are required and must reference existing resources.\n\n---" }, { "title": "Fetch Promotion by ID", "slug": "promotions-fetch-promotion-by-id", "description": "Returns the full configuration of a single promotion — its schedule, visual assets, discount or redirect details, rules, and current status. The promotion is returned inside the `data` array.", "api": "Promotions API", "method": "GET", "path": "/merchants/:merchantId/promotions/:promotionId", "content": "# Fetch Promotion by ID\n\n## Overview\nReturns the full configuration of a single promotion — its schedule, visual assets, discount or redirect details, rules, and current status. The promotion is returned inside the `data` array.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/promotions/:promotionId\n```\n\n### Headers\n| Header | Value | Required |\n|--------|-------|----------|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Request Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| merchantId | string | Yes | The unique identifier of the merchant the promotion belongs to. |\n| promotionId | string | Yes | The promotion to retrieve. |\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Indicates whether the request succeeded — either 'SUCCESS' or 'ERROR'. |\n| data | array | The matching promotion. |\n| data.promotionId | string | The unique identifier of the promotion. |\n| data.name | string | The promotion’s name. |\n| data.status | string | The current lifecycle state of the promotion. Values: `ACTIVE`, `CREATED`, `DEACTIVATED`, `EXPIRED`, `BUDGET_DEPLETED`, `ATTEMPTS_EXHAUSTED`. |\n| data.promoType | string | The promotion mechanism. Values: `PROMO_CODE`, `REDIRECT_LINK`. |\n| data.appliedTo | string | The kind of entity the promotion applies to (for example, STORE or MERCHANT). |\n| data.appliedToId | string | The identifier of the entity the promotion applies to. |\n| data.schedule | object | The promotion’s active window. |\n| data.schedule.startTime | string | ISO-8601 start time. |\n| data.schedule.endTime | string | ISO-8601 end time. |\n| data.promoCode | object | Present when `promoType` is PROMO_CODE. |\n| data.promoCode.code | string | The redeemable code. |\n| data.promoCode.offer | object | The discount the code applies. |\n| data.promoCode.offer.type | string | Whether the discount is a percentage or a fixed amount. |\n| data.promoCode.offer.percentage | number | The percentage off, when the offer is PERCENTAGE_OFF. |\n| data.promoCode.offer.amount | number | The fixed amount off, when the offer is FIXED_AMOUNT_OFF. |\n| data.promoCode.budget | object | Budget and spend tracking. |\n| data.promoCode.budget.maxAmount | number | The spend limit. |\n| data.promoCode.budget.currency | string | The currency of the budget figures. |\n| data.promoCode.budget.spentAmount | number | How much of the budget has been used so far. |\n| data.redirectLink | object | Present when `promoType` is REDIRECT_LINK. |\n| data.redirectLink.url | string | The destination URL. |\n| data.redirectLink.sharableIdleLink | string | A generated short link for display on the idle screen. |\n| data.redirectLink.sharablePrinterLink | string | A generated short link for printed receipts. |\n| data.usageLimits | object | The redemption limits. |\n| data.usageLimits.maximumRedemptions | number | The total redemption limit. |\n| data.usageLimits.maximumRedemptionsPerCustomer | number | The per-customer redemption limit (may be null). |\n| data.visualAssets | array | The promotion’s display assets. |\n| data.createdAt | string | When the promotion was created. |\n| data.updatedAt | string | When the promotion was last updated. |\n| message | string | For example, \"Promotions fetched successfully\". |\n\n### Success Response Example (200)\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"promotionId\": \"promo_8KzR4pQ7eZ2LvUjH\",\n \"name\": \"Loyalty Boost\",\n \"status\": \"ACTIVE\",\n \"promoType\": \"PROMO_CODE\",\n \"appliedTo\": \"STORE\",\n \"appliedToId\": \"store_123\",\n \"schedule\": {\n \"startTime\": \"2026-08-01T00:00:00Z\",\n \"endTime\": \"2026-08-31T23:59:59Z\"\n },\n \"promoCode\": {\n \"code\": \"AUG10\",\n \"offer\": {\n \"type\": \"PERCENTAGE_OFF\",\n \"percentage\": 10\n },\n \"budget\": {\n \"maxAmount\": 5000,\n \"currency\": \"SEK\",\n \"spentAmount\": 1200\n }\n },\n \"usageLimits\": {\n \"maximumRedemptions\": 1000,\n \"maximumRedemptionsPerCustomer\": 2\n },\n \"visualAssets\": [],\n \"createdAt\": \"2026-07-20T08:00:00Z\",\n \"updatedAt\": \"2026-07-25T09:30:00Z\"\n }\n ],\n \"message\": \"Promotions fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required fields. Ensure all required parameters are present and valid.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized: Invalid API key or secret.\"\n}\n```\n**Description:** The API key or secret provided in the headers is incorrect. Verify your credentials.\n\n#### 403 - Forbidden\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Forbidden: Insufficient permissions.\"\n}\n```\n**Description:** The provided MERCHANT-ID does not have the necessary permissions to access this endpoint.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An internal server error occurred while processing the request. Retry later; if it persists, contact support.\n\n## Notes\n- Authentication is required via API Key and API Secret, along with a valid `MERCHANT-ID`.\n- All path parameters are required and must reference existing resources.\n\n---" }, { "title": "Delete Promotion", "slug": "promotions-delete-promotion", "description": "Permanently deletes a promotion. It is removed from every store it was assigned to and can no longer be displayed or redeemed. This action cannot be undone.", "api": "Promotions API", "method": "DELETE", "path": "/merchants/:merchantId/promotions/:promotionId", "content": "# Delete Promotion\n\n## Overview\nPermanently deletes a promotion. It is removed from every store it was assigned to and can no longer be displayed or redeemed. This action cannot be undone.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /merchants/:merchantId/promotions/:promotionId\n```\n\n### Headers\n| Header | Value | Required |\n|--------|-------|----------|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Request Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| merchantId | string | Yes | The unique identifier of the merchant the promotion belongs to. |\n| promotionId | string | Yes | The promotion to delete. |\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Indicates whether the request succeeded — either 'SUCCESS' or 'ERROR'. |\n| message | string | For example, \"Promotion deleted successfully\". |\n\n### Success Response Example (200)\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Promotion deleted successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required fields. Ensure all required parameters are present and valid.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized: Invalid API key or secret.\"\n}\n```\n**Description:** The API key or secret provided in the headers is incorrect. Verify your credentials.\n\n#### 403 - Forbidden\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Forbidden: Insufficient permissions.\"\n}\n```\n**Description:** The provided MERCHANT-ID does not have the necessary permissions to access this endpoint.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An internal server error occurred while processing the request. Retry later; if it persists, contact support.\n\n## Notes\n- Authentication is required via API Key and API Secret, along with a valid `MERCHANT-ID`.\n- All path parameters are required and must reference existing resources.\n\n---" }, { "title": "Fetch Promotions", "slug": "promotions-fetch-promotions", "description": "Returns a paginated list of the merchant’s promotions with their full configuration and current store/terminal assignments. Optionally filter by status, for example to show only ACTIVE promotions.", "api": "Promotions API", "method": "GET", "path": "/merchants/:merchantId/v2/promotions", "content": "# Fetch Promotions\n\n## Overview\nReturns a paginated list of the merchant’s promotions with their full configuration and current store/terminal assignments. Optionally filter by status, for example to show only ACTIVE promotions.\n\n> **Note:** Results are paginated. The total number of promotions and the current page are returned in the `x-total-items` and `x-page-number` response headers.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/v2/promotions\n```\n\n### Headers\n| Header | Value | Required |\n|--------|-------|----------|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Request Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| merchantId | string | Yes | The unique identifier of the merchant whose promotions are listed. |\n| status | string | No | Returns only promotions in this state. Omit to return promotions of any status. Values: `ACTIVE`, `CREATED`, `DEACTIVATED`, `EXPIRED`, `BUDGET_DEPLETED`, `ATTEMPTS_EXHAUSTED`. |\n| pageNumber | number | No | The page of results to return. Defaults to 1. |\n| pageSize | number | No | The number of promotions per page. Defaults to 100. |\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Indicates whether the request succeeded — either 'SUCCESS' or 'ERROR'. |\n| data | object | The paginated promotions payload. |\n| data.promotions | array | The promotions on the requested page. |\n| data.promotions.promotionId | string | The unique identifier of the promotion. |\n| data.promotions.name | string | The promotion’s name. |\n| data.promotions.status | string | The current lifecycle state of the promotion. Values: `ACTIVE`, `CREATED`, `DEACTIVATED`, `EXPIRED`, `BUDGET_DEPLETED`, `ATTEMPTS_EXHAUSTED`. |\n| data.promotions.promoType | string | The promotion mechanism. Values: `PROMO_CODE`, `REDIRECT_LINK`. |\n| data.promotions.appliedTo | string | The kind of entity the promotion applies to (for example, STORE or MERCHANT). |\n| data.promotions.appliedToId | string | The identifier of the entity the promotion applies to. |\n| data.promotions.schedule | object | The promotion’s active window. |\n| data.promotions.schedule.startTime | string | The ISO-8601 timestamp at which the promotion becomes active. |\n| data.promotions.schedule.endTime | string | The ISO-8601 timestamp at which the promotion ends. |\n| data.promotions.promoCode | object | Present when `promoType` is PROMO_CODE. |\n| data.promotions.promoCode.code | string | The redeemable code. |\n| data.promotions.promoCode.offer | object | The discount the code applies. |\n| data.promotions.promoCode.offer.type | string | Whether the discount is a percentage or a fixed amount. |\n| data.promotions.promoCode.offer.percentage | number | The percentage off, when the offer is PERCENTAGE_OFF. |\n| data.promotions.promoCode.offer.amount | number | The fixed amount off, when the offer is FIXED_AMOUNT_OFF. |\n| data.promotions.promoCode.budget | object | Budget and spend tracking. |\n| data.promotions.promoCode.budget.maxAmount | number | The spend limit. |\n| data.promotions.promoCode.budget.currency | string | The currency of the budget figures. |\n| data.promotions.promoCode.budget.spentAmount | number | How much of the budget has been used so far. |\n| data.promotions.redirectLink | object | Present when `promoType` is REDIRECT_LINK. |\n| data.promotions.redirectLink.url | string | The destination URL. |\n| data.promotions.redirectLink.sharableIdleLink | string | A generated short link for display on the idle screen. |\n| data.promotions.redirectLink.sharablePrinterLink | string | A generated short link for printed receipts. |\n| data.promotions.usageLimits | object | The redemption limits. |\n| data.promotions.usageLimits.maximumRedemptions | number | The total redemption limit. |\n| data.promotions.usageLimits.maximumRedemptionsPerCustomer | number | The per-customer redemption limit (may be null). |\n| data.promotions.visualAssets | array | The promotion’s display assets. |\n| data.promotions.assignments | array | Where the promotion is currently assigned. |\n| data.promotions.assignments.targetType | string | Whether the promotion is assigned to a store or a terminal. |\n| data.promotions.assignments.targetId | string | The identifier of the store or terminal the promotion is assigned to. |\n| data.promotions.assignments.assignedAt | string | When the assignment was made. |\n| data.promotions.createdAt | string | When the promotion was created. |\n| data.promotions.updatedAt | string | When the promotion was last updated. |\n| message | string | For example, \"Promotions fetched successfully\". |\n\n### Success Response Example (200)\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"promotions\": [\n {\n \"promotionId\": \"promo_8KzR4pQ7eZ2LvUjH\",\n \"name\": \"Loyalty Boost\",\n \"status\": \"ACTIVE\",\n \"promoType\": \"PROMO_CODE\",\n \"appliedTo\": \"STORE\",\n \"appliedToId\": \"store_123\",\n \"schedule\": {\n \"startTime\": \"2026-08-01T00:00:00Z\",\n \"endTime\": \"2026-08-31T23:59:59Z\"\n },\n \"promoCode\": {\n \"code\": \"AUG10\",\n \"offer\": {\n \"type\": \"PERCENTAGE_OFF\",\n \"percentage\": 10\n },\n \"budget\": {\n \"maxAmount\": 5000,\n \"currency\": \"SEK\",\n \"spentAmount\": 1200\n }\n },\n \"usageLimits\": {\n \"maximumRedemptions\": 1000,\n \"maximumRedemptionsPerCustomer\": 2\n },\n \"visualAssets\": [],\n \"assignments\": [\n {\n \"targetType\": \"STORE\",\n \"targetId\": \"store_123\",\n \"assignedAt\": \"2026-08-01T10:00:00Z\"\n }\n ],\n \"createdAt\": \"2026-07-20T08:00:00Z\",\n \"updatedAt\": \"2026-07-25T09:30:00Z\"\n }\n ]\n },\n \"message\": \"Promotions fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required fields. Ensure all required parameters are present and valid.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized: Invalid API key or secret.\"\n}\n```\n**Description:** The API key or secret provided in the headers is incorrect. Verify your credentials.\n\n#### 403 - Forbidden\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Forbidden: Insufficient permissions.\"\n}\n```\n**Description:** The provided MERCHANT-ID does not have the necessary permissions to access this endpoint.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An internal server error occurred while processing the request. Retry later; if it persists, contact support.\n\n## Notes\n- Authentication is required via API Key and API Secret, along with a valid `MERCHANT-ID`.\n- All path parameters are required and must reference existing resources.\n- This endpoint is paginated; see the parameter notes for page/size handling.\n\n---" }, { "title": "Update Promotion", "slug": "promotions-update-promotion", "description": "Updates an existing promotion. Only the fields included in the request are changed; any omitted field is left as it was. Updated content is then synced to the terminals where the promotion is displayed.", "api": "Promotions API", "method": "PUT", "path": "/merchants/:merchantId/promotions/:promotionId", "content": "# Update Promotion\n\n## Overview\nUpdates an existing promotion. Only the fields included in the request are changed; any omitted field is left as it was. Updated content is then synced to the terminals where the promotion is displayed.\n\n> **Note:** The promotion type (`promoType`) is fixed at creation and cannot be changed here — to change it, delete the promotion and create a new one.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /merchants/:merchantId/promotions/:promotionId\n```\n\n### Headers\n| Header | Value | Required |\n|--------|-------|----------|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Request Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| merchantId | string | Yes | The unique identifier of the merchant the promotion belongs to. |\n| promotionId | string | Yes | The promotion to update, as returned when it was created. |\n| name | string | No | A new name for the promotion. |\n| schedule | object | No | The window during which the promotion runs. |\n| schedule.startTime | string | Yes | ISO-8601 timestamp at which the promotion becomes active. |\n| schedule.endTime | string | Yes | ISO-8601 timestamp at which the promotion ends. |\n| visualAssets | array | No | Replaces the promotion’s display content with this set. Each item’s `type` determines which of the fields below apply. |\n| visualAssets.type | string | Yes | The kind of asset. Values: `TEXT`, `IMAGE`, `VIDEO`, `BUTTON`. |\n| visualAssets.headline | string | No | The primary line of a TEXT asset. |\n| visualAssets.subheadline | string | No | The secondary line of a TEXT asset. |\n| visualAssets.body | string | No | The body copy of a TEXT asset. |\n| visualAssets.url | string | No | The public URL of an IMAGE or VIDEO asset. |\n| visualAssets.buttonText | string | No | The label shown on a BUTTON asset. |\n| visualAssets.buttonUrl | string | No | The URL a BUTTON asset opens when tapped. |\n| promoCode | object | No | The discount configuration for a promo-code promotion. |\n| promoCode.code | string | Yes | The code a customer enters at checkout to redeem the offer (for example, SAVE20). |\n| promoCode.offer | object | Yes | How much the code discounts. |\n| promoCode.offer.type | string | Yes | Whether the discount is a percentage or a fixed amount. Values: `PERCENTAGE_OFF`, `FIXED_AMOUNT_OFF`. |\n| promoCode.offer.percentage | number | No | The percentage discount to apply (0–100). |\n| promoCode.offer.amount | number | No | The fixed discount amount, in the smallest currency unit (for example, 10 SEK is 1000). |\n| promoCode.budget | object | Yes | The spend limit for the promo code. |\n| promoCode.budget.maxAmount | number | Yes | The maximum total discount the promotion may give away, in the smallest currency unit. When reached, the promotion stops automatically with status BUDGET_DEPLETED. |\n| redirectLink | object | No | The redirect destination for a redirect-link promotion. |\n| redirectLink.url | string | Yes | The destination the customer is taken to. |\n| assignmentRules | object | No | Conditions an order must satisfy for a customer to be eligible for the promotion. |\n| assignmentRules.minimumOrderAmount | number | No | The minimum order total required, in the smallest currency unit. |\n| assignmentRules.itemPresentInOrder | array | No | The order must contain at least one of these item IDs. |\n| assignmentRules.categoryPresentInOrder | array | No | The order must contain at least one item from these category IDs. |\n| redemptionRules | object | No | Conditions that must be met at checkout before the discount is applied. |\n| redemptionRules.minimumOrderAmount | number | No | The minimum order total required, in the smallest currency unit. |\n| redemptionRules.itemPresentInOrder | array | No | The order must contain at least one of these item IDs. |\n| redemptionRules.categoryPresentInOrder | array | No | The order must contain at least one item from these category IDs. |\n| usageLimits | object | No | Limits on how many times the promotion can be redeemed. |\n| usageLimits.maximumRedemptions | number | Yes | The total number of redemptions allowed across all customers. Once reached, the promotion stops with status ATTEMPTS_EXHAUSTED. |\n| usageLimits.maximumRedemptionsPerCustomer | number | No | The number of redemptions allowed per individual customer (for example, 1 for a one-time offer). |\n\n### Request Example\n```json\n{\n \"name\": \"Loyalty Boost (extended)\",\n \"schedule\": {\n \"startTime\": \"2026-08-01T00:00:00Z\",\n \"endTime\": \"2026-09-15T23:59:59Z\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Indicates whether the request succeeded — either 'SUCCESS' or 'ERROR'. |\n| data | object | The updated promotion. |\n| message | string | For example, \"Promotion updated successfully\". |\n\n### Success Response Example (200)\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {},\n \"message\": \"Promotion updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required fields. Ensure all required parameters are present and valid.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized: Invalid API key or secret.\"\n}\n```\n**Description:** The API key or secret provided in the headers is incorrect. Verify your credentials.\n\n#### 403 - Forbidden\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Forbidden: Insufficient permissions.\"\n}\n```\n**Description:** The provided MERCHANT-ID does not have the necessary permissions to access this endpoint.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An internal server error occurred while processing the request. Retry later; if it persists, contact support.\n\n## Notes\n- Authentication is required via API Key and API Secret, along with a valid `MERCHANT-ID`.\n- All path parameters are required and must reference existing resources.\n\n---" }, { "title": "Email Receipt", "slug": "receipts-email-receipt", "description": "Send the receipt for a transaction as an email to the address provided in the body.", "api": "Receipts API", "method": "PUT", "path": "/receipts/:id/email", "content": "# Email Receipt\n\n## Overview\nSend the receipt for a transaction as an email to the address provided in the body.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required using API Key and API Secret.\n- The resource identified by `id` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /receipts/:id/email\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `email` | `string` | Yes | Email address to send the receipt to. |\n\n### Request Example\n```json\n{\n \"email\": \"customer@example.com\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | Human-facing status message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Email receipt processed successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `id` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Receipt Link", "slug": "receipts-fetch-receipt-link", "description": "Return a shareable link to the digital receipt for a transaction.", "api": "Receipts API", "method": "GET", "path": "/receipts/:id/link", "content": "# Fetch Receipt Link\n\n## Overview\nReturn a shareable link to the digital receipt for a transaction.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required using API Key and API Secret.\n- The resource identified by `id` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /receipts/:id/link\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /receipts/:id/link\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Contains the receipt link. |\n|     `receiptURL` | `string` | Shareable URL of the digital receipt. |\n| `message` | `string` | Human-facing status message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"receiptURL\": \"https://receipt.surfboardpayments.com/{{transactionId}}\"\n },\n \"message\": \"Receipt URL fetched successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `id` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Print ESC/POS Receipt", "slug": "receipts-print-escpos-receipt", "description": "Send raw ESC/POS commands (base64-encoded) to a terminal for printing. This endpoint takes a terminal ID in the path, not a receipt or transaction ID.", "api": "Receipts API", "method": "PUT", "path": "/receipts/:terminalId/escpos", "content": "# Print ESC/POS Receipt\n\n## Overview\nSend raw ESC/POS commands (base64-encoded) to a terminal for printing. This endpoint takes a terminal ID in the path, not a receipt or transaction ID.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required using API Key and API Secret.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /receipts/:terminalId/escpos\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `escposCommands` | `string` | Yes | Base64-encoded ESC/POS byte stream to send to the printer. The decoded payload must start with the ESC byte (0x1B). Maximum 100,000 base64 characters per call. |\n\n### Request Example\n```json\n{\n \"escposCommands\": \"G0A=\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | Human-facing status message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"ESC/POS commands sent to the terminal successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Print Receipt", "slug": "receipts-print-receipt", "description": "Print the receipt for a transaction. By default it prints on the terminal that processed the transaction; optionally target a different terminal or choose a template type.", "api": "Receipts API", "method": "POST", "path": "/receipts/:id/print", "content": "# Print Receipt\n\n## Overview\nPrint the receipt for a transaction. By default it prints on the terminal that processed the transaction; optionally target a different terminal or choose a template type.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required using API Key and API Secret.\n- The resource identified by `id` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /receipts/:id/print\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | No | Terminal to print on. Defaults to the terminal that processed the transaction. |\n| `templateType` | `string` | No | Which receipt template to print. Defaults to TRANSACTION_RECEIPT. Possible values: `TRANSACTION_RECEIPT`, `SALES_SUMMARY`. |\n\n### Request Example\n```json\n{\n \"terminalId\": \"{{terminalId}}\",\n \"templateType\": \"TRANSACTION_RECEIPT\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | Human-facing status message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Receipt sent to the printer successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `id` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Service Provider", "slug": "service-providers-create-service-provider", "description": "Start a company service provider application under a partner. Supply the company's country and corporate identifier, and Surfboard returns an application record together with a hosted KYB (Know Your Business) link that the service provider completes to finish onboarding.", "api": "Service Providers API", "method": "POST", "path": "/partners/:partnerId/service-providers", "content": "# Create Service Provider\n\n## Overview\nStart a company service provider application under a partner. Supply the company's country and corporate identifier, and Surfboard returns an application record together with a hosted KYB (Know Your Business) link that the service provider completes to finish onboarding.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/service-providers\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `country` | `string` | Yes | Two-letter ISO country code where the service provider is registered, for example 'SE'. |\n| `organisation` | `object` | Yes | Company details for the service provider. |\n|     `corporateId` | `string` | Yes | Corporate registration number of the company, validated against the supplied country. |\n\n### Request Example\n```json\n{\n \"country\": \"SE\",\n \"organisation\": {\n \"corporateId\": \"5560000000\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Details of the created service provider application. |\n|     `applicationId` | `string` | Unique identifier for the created service provider application. |\n|     `webKybUrl` | `string` | Hosted URL where the service provider completes the KYB (Know Your Business) verification. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"applicationId\": \"838ca3a7c530200810\",\n \"webKybUrl\": \"https://web-kyb-dev.web.app/838ca3a7c530200810?pi=QGv2Kgu9q0WAdg6FjkK0iEliyh8l61yxIXnaf0M70l4psKXW_6KihWL4wcY2aL0NfI5aM69J7bYUisZ8ecrFTNMrj4KU1ZjrN5Q3O9hcqlEgc6oQACb2eLM7SwwP0006\"\n },\n \"message\": \"Service provider company application created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Missing required parameter 'country' in create service provider company application\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Service Provider Application Status", "slug": "service-providers-fetch-service-provider-application-status", "description": "Retrieve the current status of a single service provider application by its ID. Use this to check where an application sits in the onboarding lifecycle and to obtain the resulting service provider ID once the application is approved.", "api": "Service Providers API", "method": "GET", "path": "/partners/:partnerId/service-providers/applications/:applicationId", "content": "# Fetch Service Provider Application Status\n\n## Overview\nRetrieve the current status of a single service provider application by its ID. Use this to check where an application sits in the onboarding lifecycle and to obtain the resulting service provider ID once the application is approved.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `applicationId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/service-providers/applications/:applicationId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `applicationId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/service-providers/applications/:applicationId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Current status details of the application. |\n|     `onboardingStatus` | `string` | Current onboarding status of the application, null if onboarding has not started. |\n|     `applicationStatus` | `string` | Current status of the application. Possible values: `APPLICATION_INITIATED`, `APPLICATION_STARTED`, `APPLICATION_EXPIRED`, `APPLICATION_SUBMITTED`, `APPLICATION_PENDING_INFORMATION`, `APPLICATION_SIGNED`, `APPLICATION_UNDER_REVIEW`, `APPLICATION_REJECTED`, `APPLICATION_COMPLETED`, `APPLICATION_APPROVED`, `MERCHANT_CREATED`, `SERVICE_PROVIDER_CREATED`. |\n|     `serviceProviderId` | `string` | Identifier of the created service provider once the application is approved, null while still pending. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"onboardingStatus\": null,\n \"applicationStatus\": \"APPLICATION_INITIATED\",\n \"serviceProviderId\": null\n },\n \"message\": \"Service provider application status fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to fetch service provider application status\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `applicationId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Settlement Reports", "slug": "reporting-fetch-settlement-reports", "description": "Retrieves the list of settlement reports for a merchant. Use this API to get a summary of the merchant’s settled transactions within a specific time frame, which can be daily or monthly depending on the report type opted for the merchant.", "api": "Reporting APIs", "method": "GET", "path": "/partners/:partnerId/merchants/:merchantId/reports", "content": "# Fetch Settlement Reports\n\n## Overview\nRetrieves the list of settlement reports for a merchant. Use this API to get a summary of the merchant’s settled transactions within a specific time frame, which can be daily or monthly depending on the report type opted for the merchant. This API supports pagination.\n\n## Prerequisites\n- A valid Partner ID and Merchant ID are required.\n- The Merchant must have existing settlement reports.\n- Authentication is required using API Key and API Secret.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants/:merchantId/reports\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Query Parameters\nN/A\n\n### Request Body Parameters\nN/A\n\n### Request Example\n```json\n{\n \"headers\": {\n \"Content-Type\": \"application/json\",\n \"API-KEY\": \"YOUR_API_KEY\",\n \"API-SECRET\": \"YOUR_API_SECRET\",\n \"MERCHANT-ID\": \"YOUR_MERCHANT_ID\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| data | array | Response data |\n| data[].payoutId | String | The payout ID used to identify a specific payout. |\n| data[].merchantId | String | The merchant ID of the merchant for which the settlement report is generated. |\n| data[].transactionStartDate | String | The date of the first transaction in the generated settlement report, in YYYY-MM-DD format. |\n| data[].transactionEndDate | String | The date of the last transaction in the generated settlement report, in YYYY-MM-DD format. |\n| data[].settlementDate | String | Date of the payout, in YYYY-MM-DD format. |\n| data[].reportType | String | Specifies the type of settlement report opted for the merchant. It can be either 'MONTHLY' or 'DAILY’. |\n| data[].url | String | URL from which the particular settlement report can be viewed. |\n| data[].totalSale | Number | The total amount of sales generated by the merchant during the report period. |\n| data[].totalRefund | Number | The total amount refunded by the merchant during the specified time period. |\n| data[].fee | Number | The total fee collected from transactions during the settlement. |\n| data[].payout | Number | The final amount paid out to the merchant after all deductions. |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"payoutId\": \"Q6z2e0goIOE4DXD0VYiT\",\n \"merchantId\": \"8149bdef0a2300090e\",\n \"transactionStartDate\": \"2023-08-07\",\n \"transactionEndDate\": \"2023-08-07\",\n \"settlementDate\": \"2023-08-08\",\n \"reportType\": \"DAILY\",\n \"url\": \"https://reports.surfboardpayments.com/settlementReport1.pdf\",\n \"totalSale\": 10000,\n \"totalRefund\": 100,\n \"fee\": 200,\n \"payout\": 9700\n },\n {\n \"payoutId\": \"Q6z2e0goIOE4DXD0VYiT\",\n \"merchantId\": \"8149bdef0a2300090e\",\n \"transactionStartDate\": \"2023-08-07\",\n \"transactionEndDate\": \"2023-08-07\",\n \"settlementDate\": \"2023-08-08\",\n \"reportType\": \"DAILY\",\n \"url\": \"https://reports.surfboardpayments.com/settlementReport2.pdf\",\n \"totalSale\": 10000,\n \"totalRefund\": 100,\n \"fee\": 200,\n \"payout\": 9700\n }\n ],\n \"message\": \"Settlement reports fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\nThere is no error JSON example given, so these are examples based on context:\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid Merchant ID\"\n}\n```\n**Description:** The provided Merchant ID is not valid. Check the Merchant ID and try again.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid API Key\"\n}\n```\n**Description:** The provided API Key is incorrect or missing. Verify your API Key and Secret.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Reports not found for specified merchant\"\n}\n```\n**Description:** No settlement reports exist for the given Merchant ID and Partner ID combination.\n\n## Notes\n- The `url` field in the response provides a direct link to download the settlement report in PDF format.\n- The report type can be either DAILY or MONTHLY depending on the merchant's configuration.\n- Ensure that the `transactionStartDate` and `transactionEndDate` are in the correct format (YYYY-MM-DD).\n- This endpoint supports pagination. Check for standard pagination parameters if needed (e.g., `page`, `pageSize`). The JSON did not give specific details of these.\n\n---" }, { "title": "Get All Service Provider Applications", "slug": "service-providers-get-all-service-provider-applications", "description": "Retrieve every service provider application under a partner, optionally filtered by application type. Use this to monitor onboarding and renewal progress across all of a partner's service providers.", "api": "Service Providers API", "method": "GET", "path": "/partners/:partnerId/service-providers/applications", "content": "# Get All Service Provider Applications\n\n## Overview\nRetrieve every service provider application under a partner, optionally filtered by application type. Use this to monitor onboarding and renewal progress across all of a partner's service providers.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/service-providers/applications\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\n\nTo filter results, pass the optional query param `applicationType`. Supported values are ONBOARDING and RENEWAL. Provide a single value or a comma-separated list such as ONBOARDING,RENEWAL. When omitted, ONBOARDING applications are returned.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `applicationType` | `string` | No | Filters applications by type. Provide a single value or a comma-separated list such as 'ONBOARDING,RENEWAL'. Defaults to 'ONBOARDING' when not supplied. Passed as a query parameter. Possible values: `ONBOARDING`, `RENEWAL`. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/service-providers/applications?applicationType=ONBOARDING\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | List of service provider applications under the partner. |\n|     `applicationId` | `string` | Unique identifier of the application. |\n|     `country` | `string` | Two-letter ISO country code where the service provider is registered. |\n|     `corporateId` | `string` | Corporate registration number of the service provider. |\n|     `applicationStatus` | `string` | Current status of the application. Possible values: `APPLICATION_INITIATED`, `APPLICATION_STARTED`, `APPLICATION_EXPIRED`, `APPLICATION_SUBMITTED`, `APPLICATION_PENDING_INFORMATION`, `APPLICATION_SIGNED`, `APPLICATION_UNDER_REVIEW`, `APPLICATION_REJECTED`, `APPLICATION_COMPLETED`, `APPLICATION_APPROVED`, `MERCHANT_CREATED`, `SERVICE_PROVIDER_CREATED`. |\n|     `createdAt` | `string` | ISO timestamp of when the application was created. |\n|     `lastUpdatedAt` | `string` | ISO timestamp of when the application was last updated. |\n|     `webKybUrl` | `string` | Hosted URL where the service provider completes KYB verification, when available. |\n|     `legalName` | `string` | Legal name of the service provider, when available. |\n|     `endDate` | `string` | ISO timestamp marking the end date of the application, when available. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"applicationId\": \"838ca3a7c530200810\",\n \"country\": \"SE\",\n \"corporateId\": \"3532007322\",\n \"applicationStatus\": \"APPLICATION_INITIATED\",\n \"createdAt\": \"2025-10-10T10:32:47.565Z\",\n \"lastUpdatedAt\": \"2025-10-10T10:32:47.565Z\",\n \"webKybUrl\": \"https://web-kyb-dev.web.app/838ca3a7c530200810?pi=QGv2Kgu9q0WAdg6FjkK0iEliyh8l61yxIXnaf0M70l4psKXW_6KihWL4wcY2aL0NfI5aM69J7bYUisZ8ecrFTNMrj4KU1ZjrN5Q3O9hcqlEgc6oQACb2eLM7SwwP0006\",\n \"legalName\": \"Turner, Runte and Kemmer\"\n },\n {\n \"applicationId\": \"838ca332c530200310\",\n \"country\": \"SE\",\n \"corporateId\": \"5834862013\",\n \"applicationStatus\": \"APPLICATION_STARTED\",\n \"createdAt\": \"2025-10-10T10:28:53.740Z\",\n \"lastUpdatedAt\": \"2025-10-10T10:39:34.614Z\",\n \"webKybUrl\": \"https://web-kyb-dev.web.app/838ca332c530200310?pi=rZzanQBc-0lZgNKHpPE0_ou4KDDcH1nXxKDuqS07IdTnTOQ-k62W--U2uyB21T2-ipMtS6E7iA6LLMb8T52FYHGd54jZX9nOdzM1YA9qNlZgT3n8_AZTcyC3ljNm0002\",\n \"legalName\": \"LOCO SP OBERBRUNNER LLC\"\n }\n ],\n \"message\": \"Applications under partner fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Bad request. Please check your request parameters\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Store", "slug": "stores-create-store", "description": "Creates a store under a merchant. Use this API to create a store to which you can register your terminals. You can create a single store or multiple stores under a merchant based on your requirements.", "api": "Stores API", "method": "POST", "path": "/partners/:partnerId/merchants/:merchantId/stores", "content": "# Create Store\n\n## Overview\nCreates a store under a merchant. Use this API to create a store to which you can register your terminals. You can create a single store or multiple stores under a merchant based on your requirements.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/merchants/:merchantId/stores\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeName` | `string` | Yes | Name of the store. |\n| `email` | `string` | No | Email address of the store. Email address in mandatory to support online payments. |\n| `phoneNumber` | `object` | Yes | Contact number of the store in code and number format. |\n|     `code` | `string` | Yes | International dialing code identifying the country or region. |\n|     `number` | `string` | Yes | A string of numbers ranging from 0-9 with a length of 5-15 characters. |\n| `address` | `object` | Yes | Address of the store. |\n|     `careOf` | `string` | No | Name of the person or entity receiving correspondence on behalf of the store (c/o). |\n|     `addressLine1` | `string` | Yes | First line of address. |\n|     `addressLine2` | `string` | No | Second line of address. |\n|     `addressLine3` | `string` | No | Third line of address. |\n|     `city` | `string` | Yes | Name of the city where the store is located. |\n|     `countryCode` | `string` | Yes | Two-letter ISO country code in uppercase, representing the location of the store. |\n|     `postalCode` | `string` | Yes | Postal code of the store. |\n| `acquirerMID` | `string` | No | Acquirer Merchant ID. Required for payment facilitator partners that want to support a store-based acquiring model. |\n| `onlineInfo` | `object` | No | In order to start accepting online payments you need to create an online store which requires some additional properties such as the following. |\n|     `merchantWebshopURL` | `string` | Yes | This is the web-shop URL of the merchant. |\n|     `paymentPageHostURL` | `string` | No | This is the URL of the payment page. This is required for integrating online payments using SDK mode. |\n|     `termsAndConditionsURL` | `string` | Yes | This is the URL of the T&C of the merchant’s web-shop, it has to contain the refund policy. |\n|     `privacyPolicyURL` | `string` | Yes | This is the URL of the privacy policy of the merchant. |\n|     `googlePayMerchantId` | `string` | No | Your Google Pay merchant identifier, used to enable Google Pay on the online store. |\n\n### Request Example\n```json\n{\n \"storeName\": \"Trial Store\",\n \"email\": \"TS@gmail.com\",\n \"phoneNumber\": {\n \"code\": \"91\",\n \"number\": \"3214576980\"\n },\n \"address\": {\n \"addressLine1\": \"Hagmarksgatan 3\",\n \"addressLine2\": \"Suite 724\",\n \"addressLine3\": \"North\",\n \"city\": \"Stockholm\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"103 16\"\n },\n \"onlineInfo\": {\n \"merchantWebshopURL\": \"https://testmerchantportal.com/home\",\n \"paymentPageHostURL\": \"https://testmerchantportal.com/payment\",\n \"termsAndConditionsURL\": \"https://testmerchantportal.com/terms\",\n \"privacyPolicyURL\": \"https://testmerchantportal.com/privacy\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `storeId` | `string` | Identifier of the newly created store. Use this when registering terminals or fetching the store's details. |\n|     `merchantUrlDomainVerificationKey` | `string` | Verification key to place on the merchant's webshop domain to prove ownership. Returned only when online store details were provided; null otherwise. |\n|     `paymentPageUrlDomainVerificationKey` | `string` | Verification key to place on the payment page host domain to prove ownership. Returned only when a payment page host URL was provided; null otherwise. |\n| `message` | `string` | A message that describes the status of the request |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"storeId\": \"81d64e7174dcb00b0f\",\n \"merchantUrlDomainVerificationKey\": \"499470649f03b53fa1175659d4389743974710260b7f410313487e6062b3d559\",\n \"paymentPageUrlDomainVerificationKey\": \"2179beab4f5e8c3960615205f042939a2ccc6c51a6e5923c9c068b3d9a645590\"\n },\n \"message\": \"Store created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Mandatory address parameters missing\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Deactivate a Store", "slug": "stores-deactivate-a-store", "description": "Deactivates a store. Use this API to deactivate any store under a merchant. You can delete a store instantly or schedule it to be deleted at a later date. Stores can be deleted only if there are no terminals registered to it. If a store has terminals registered to it, you will have to delink the terminal from the store or change the terminal to another store under the same merchant.", "api": "Stores API", "method": "DELETE", "path": "/partners/:partnerId/merchants/:merchantId/stores/:storeId", "content": "# Deactivate a Store\n\n## Overview\nDeactivates a store. Use this API to deactivate any store under a merchant. You can delete a store instantly or schedule it to be deleted at a later date. Stores can be deleted only if there are no terminals registered to it. If a store has terminals registered to it, you will have to delink the terminal from the store or change the terminal to another store under the same merchant.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /partners/:partnerId/merchants/:merchantId/stores/:storeId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `deactivationDate` | `string` | No | Date of deactivation of the store in yyyy-mm-dd format. |\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | Message describing the status of store deactivation. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Store deactivation initiated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch All Store Terminals", "slug": "stores-fetch-all-store-terminals", "description": "Retrieves a list of all terminals associated with a specific store. You can use this API to get information regarding all the terminals registered under a store.", "api": "Stores API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/terminals", "content": "# Fetch All Store Terminals\n\n## Overview\nRetrieves a list of all terminals associated with a specific store. You can use this API to get information regarding all the terminals registered under a store.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/terminals\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalType` | `string` | No | Optional query param to filter terminals by terminal type. Possible values: `surfpad`, `surftouch`, `surfprint`, `checkoutPro`, `checkoutX`, `PaymentPage`, `SelfHostedPage`, `MerchantInitiated`, `printer`, `surftester`. |\n\n### Pagination\n\nTo query terminals by terminal type, send in `terminalType` as query param.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/terminals?terminalType=surfpad\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. 'SUCCESS' \\| 'ERROR'. |\n| `data` | `array` | Response data. |\n|     `terminalId` | `String` | Store ID of the terminal. |\n|     `terminalType` | `string` | Describes the type of the terminal. Possible values: `surfpad`, `surftouch`, `surfprint`, `checkoutPro`, `checkoutX`, `PaymentPage`, `SelfHostedPage`, `MerchantInitiated`, `printer`, `surftester`. |\n|     `softwareVersion` | `String` | Software version of the terminal. |\n|     `osType` | `string` | Describes the type of operating system running on the terminals. Possible values: `android`, `ios`, `sb_firmware`. |\n|     `osVersion` | `String` | Operating System(OS) version of the terminal. |\n|     `deviceVendor` | `String` | Device vendor of the terminal. |\n|     `deviceModel` | `String` | Device model of the terminal. |\n|     `serialNo` | `String` | Serial number of the terminal. |\n|     `storeId` | `String` | The Store ID of the store under which the terminal is registered. |\n|     `linkedTerminalId` | `String` | The Terminal ID of another terminal to which the current terminal is linked. |\n|     `terminalStatus` | `String` | Status of the terminal. The terminal can be in any one of these states: 'REGISTERED' \\| 'ACTIVE' \\| 'IN_ACTIVE' \\| 'DE_REGISTERED’. |\n|     `terminalPaymentMethods` | `String` | Payment methods supported by the terminal. |\n|     `startDate` | `String` | Timestamp at which terminal was registered. |\n|     `terminalName` | `string` | Name of the terminal used as a reference for users. |\n| `message` | `string` | Message describing the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"terminalId\": \"81ff0cea07e4300105\",\n \"softwareVersion\": \"1.5.3\",\n \"osType\": \"android\",\n \"osVersion\": \"1.0.0.0\",\n \"deviceVendor\": \"Samsung\",\n \"deviceModel\": \"Galaxy N10\",\n \"serialNo\": null,\n \"storeId\": \"81fd3113680e60030f\",\n \"linkedTerminalId\": null,\n \"terminalStatus\": \"ACTIVE\",\n \"startDate\": \"2024-02-15T06:46:44.046Z\",\n \"terminalPaymentMethods\": [\n \"SWISH\",\n \"CASH\",\n \"SVEA_SWISH\"\n ],\n \"terminalName\": \"surf-touch\",\n \"terminalType\": \"unknown\",\n \"batteryPercentage\": null,\n \"powerSource\": null,\n \"deviceNetwork\": null,\n \"turnOnTime\": null,\n \"terminalCurrencyCode\": \"NA\"\n },\n {\n \"terminalId\": \"81ff0ff487e4300b04\",\n \"softwareVersion\": \"4.0.12.0\",\n \"osType\": \"pinpad\",\n \"osVersion\": \"2.0.0.0\",\n \"deviceVendor\": \"Datecs\",\n \"deviceModel\": \"Datecs Bluepad 55\",\n \"serialNo\": \"4299989999\",\n \"storeId\": \"81fd3113680e60030f\",\n \"linkedTerminalId\": null,\n \"terminalStatus\": \"REGISTERED\",\n \"startDate\": \"2024-02-15T07:12:41.658Z\",\n \"terminalPaymentMethods\": [\n \"CARD\"\n ],\n \"terminalName\": null,\n \"terminalType\": \"surfpad\",\n \"batteryPercentage\": null,\n \"powerSource\": null,\n \"deviceNetwork\": null,\n \"turnOnTime\": null,\n \"terminalCurrencyCode\": \"NA\"\n }\n ],\n \"message\": \"Terminal records fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Query Parameters for the supported paging parameters.\n\n---" }, { "title": "Fetch Store Domains", "slug": "stores-fetch-store-domains", "description": "This API retrieves the details of the store's domain.", "api": "Stores API", "method": "GET", "path": "/partners/:partnerId/merchants/:merchantId/stores/:storeId/online", "content": "# Fetch Store Domains\n\n## Overview\nThis API retrieves the details of the store's domain.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants/:merchantId/stores/:storeId/online\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/merchants/:merchantId/stores/:storeId/online\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `onlineStoreStatus` | `string` | Status of the online store. Possible values: `APPROVED`, `INITIATED`, `FAILED`. |\n|     `domains` | `array` | Contains the domain details. |\n|         `status` | `string` | The current status of the domain. Possible values: `ACTIVE`, `DEACTIVATED`. |\n|         `type` | `string` | Refers to the type of the domain. Possible values: `MERCHANT_WEBSHOP_URL`, `PAYMENT_PAGE_HOST_URL`. |\n|         `name` | `string` | Name of the domain. |\n|         `verificationKey` | `string` | This is the key set in your domain which is used for verification. |\n|         `isDomainVerified` | `boolean` | Indicates whether the domain has been verified. |\n| `message` | `string` | Message describing the status of domain verification of store. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"onlineStoreStatus\": \"APPROVED\",\n \"domains\": [\n {\n \"status\": \"ACTIVE\",\n \"type\": \"PAYMENT_PAGE_HOST_URL\",\n \"name\": \"www.surfpayapp.com\",\n \"verificationKey\": \"7fd242dd862a9f9f74ae11d62216f5729a5e5600e00b8d44300db41b4efcce68\",\n \"isDomainVerified\": true\n },\n {\n \"status\": \"ACTIVE\",\n \"type\": \"MERCHANT_WEBSHOP_URL\",\n \"name\": \"test.surfboard.se\",\n \"verificationKey\": \"7fd242dd862a9f9f74ae11d62216f5729a5e5600e00b8d44300db41b4efcce68\",\n \"isDomainVerified\": true\n }\n ]\n },\n \"message\": \"Online store domain details fetched successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Store Details", "slug": "stores-fetch-store-details", "description": "Retrieves information for a specific store. Use this API to get information regarding a particular store created under a merchant.", "api": "Stores API", "method": "GET", "path": "/partners/:partnerId/merchants/:merchantId/stores/:storeId", "content": "# Fetch Store Details\n\n## Overview\nRetrieves information for a specific store. Use this API to get information regarding a particular store created under a merchant.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants/:merchantId/stores/:storeId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/merchants/:merchantId/stores/:storeId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `storeId` | `string` | Store ID of the store. |\n|     `merchantId` | `string` | The Merchant ID of the merchant under which the store is created. |\n|     `name` | `string` | Name of the store. |\n|     `status` | `string` | Status of the store. Possible values: `ACTIVE`, `DEACTIVATED`, `BLOCKED`, `INACTIVE`. |\n|     `onlineOnboardingStatus` | `string` | Onboarding status of the online store. Possible values: `APPROVED`, `INITIATED`, `FAILED`. |\n|     `address` | `object` | Address of the store. |\n|         `careOf` | `string` | Name of the addressee that is accepting the correspondence for the intended recipient. |\n|         `addressLine1` | `string` | The first line of the store's address. |\n|         `addressLine2` | `string` | The second line of the store's address. |\n|         `addressLine3` | `string` | The third line of the store's address. |\n|         `city` | `string` | Name of the City where the store is located. |\n|         `countryCode` | `string` | Two-letter ISO country code in uppercase, representing the location of the store. |\n|         `postalCode` | `string` | Postal Code of the place where the store is located. |\n|     `onlineInfo` | `object` | In order to start accepting online payments you need to create an online store which requires some additional properties such as the following. |\n|         `merchantWebshopURL` | `string` | This is the web-shop URL of the merchant. |\n|         `paymentPageHostURL` | `string` | This is the URL of the payment page. |\n|         `termsAndConditionsURL` | `string` | This is the URL of the T&C of the merchant’s web-shop, it has to contain the refund policy. |\n|         `privacyPolicyURL` | `string` | This is the URL of the privacy policy of the merchant. |\n|         `googlePayMerchantId` | `string` | The Google Pay merchant identifier configured for the online store. |\n|     `phoneNumber` | `object` | Contact phone number of the store, present only when one is set. |\n|         `code` | `string` | International dialing code of the store's phone number. |\n|         `number` | `string` | Local phone number of the store. |\n|     `email` | `string` | Email address of the store. |\n| `message` | `string` | Message describing the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"storeId\": \"824bd4a739dc200b0f\",\n \"merchantId\": \"81a641f8b3cfd0070e\",\n \"name\": \"TEST\",\n \"status\": \"ACTIVE\",\n \"onlineOnboardingStatus\": \"APPROVED\",\n \"address\": {\n \"careOf\": null,\n \"addressLine1\": \"Main Street 123\",\n \"addressLine2\": \"6th lane\",\n \"addressLine3\": \"Building C\",\n \"city\": \"Stockholm\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"103 16\"\n },\n \"onlineInfo\": {\n \"merchantWebshopURL\": \"https://testmerchant.com\",\n \"paymentPageHostURL\": null,\n \"termsAndConditionsURL\": \"https://www.termsandconditions.com\",\n \"privacyPolicyURL\": \"https://www.privacypolicy.com\",\n \"googlePayMerchantId\": null\n },\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"701234567\"\n },\n \"email\": \"test@gmail.com\"\n },\n \"message\": \"Fetched store by ID\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Stores", "slug": "stores-fetch-stores", "description": "Retrieves a list of all stores associated with a specific merchant. You can use this API to get information regarding all the stores created under a particular merchant.", "api": "Stores API", "method": "GET", "path": "/partners/:partnerId/merchants/:merchantId/stores", "content": "# Fetch Stores\n\n## Overview\nRetrieves a list of all stores associated with a specific merchant. You can use this API to get information regarding all the stores created under a particular merchant.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants/:merchantId/stores\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/merchants/:merchantId/stores\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. 'SUCCESS' \\| 'ERROR'. |\n| `data` | `array` | Response data. |\n|     `storeId` | `string` | Store ID of the store. |\n|     `merchantId` | `string` | The Merchant ID of the merchant under which the store is created. |\n|     `name` | `string` | Name of the store. |\n|     `status` | `string` | Current lifecycle status of the store. Possible values: `ACTIVE`, `DEACTIVATED`, `BLOCKED`, `INACTIVE`. |\n|     `address` | `object` | Address of the store. |\n|         `careOf` | `string` | Name of the addressee that is accepting the correspondence for the intended recipient. |\n|         `addressLine1` | `string` | The first line of the store's address. |\n|         `addressLine2` | `string` | The second line of the store's address. |\n|         `addressLine3` | `string` | The third line of the store's address. |\n|         `city` | `string` | Name of the City where the store is located. |\n|         `countryCode` | `string` | Two-letter ISO country code in uppercase, representing the location of the store. |\n|         `postalCode` | `string` | Postal Code of the place where the store is located. |\n|     `onlineInfo` | `object` | In order to start accepting online payments you need to create an online store which requires some additional properties such as the following. |\n|         `merchantWebshopURL` | `string` | This is the web-shop URL of the merchant. |\n|         `paymentPageHostURL` | `string` | This is the URL of the payment page. |\n|         `termsAndConditionsURL` | `string` | This is the URL of the T&C of the merchant’s web-shop, it has to contain the refund policy. |\n|         `privacyPolicyURL` | `string` | This is the URL of the privacy policy of the merchant. |\n|         `googlePayMerchantId` | `string` | The Google Pay merchant identifier configured for the online store. |\n|     `phoneNumber` | `object` | Contact phone number of the store, present only when one is set. |\n|         `code` | `string` | International dialing code of the store's phone number. |\n|         `number` | `string` | Local phone number of the store. |\n|     `email` | `string` | Email address of the store. |\n| `message` | `string` | Message describing the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"storeId\": \"824bd4a739dc200b0f\",\n \"status\": \"ACTIVE\",\n \"merchantId\": \"81fa6b2d8d5dc8040e\",\n \"name\": \"Previous Store\",\n \"address\": {\n \"careOf\": null,\n \"addressLine1\": \"No:3, 10th street\",\n \"addressLine2\": null,\n \"addressLine3\": null,\n \"city\": \"Copenhagen\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"576462\"\n },\n \"onlineInfo\": {\n \"merchantWebshopURL\": \"https://testmerchantportal.com/home\",\n \"paymentPageHostURL\": \"https://testmerchantportal.com/payment\",\n \"termsAndConditionsURL\": \"https://testmerchantportal.com/terms\",\n \"privacyPolicyURL\": \"https://testmerchantportal.com/privacy\",\n \"googlePayMerchantId\": null\n },\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"12345678\"\n },\n \"email\": \"PS@gmail.com\"\n },\n {\n \"storeId\": \"st_p5Hprp71IKuPGOCqkZSt5\",\n \"status\": \"ACTIVE\",\n \"merchantId\": \"81fa6b2d8d5dc8040e\",\n \"name\": \"New Store\",\n \"address\": {\n \"careOf\": null,\n \"addressLine1\": \"No:3, 10th street\",\n \"addressLine2\": null,\n \"addressLine3\": null,\n \"city\": \"Copenhagen\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"576462\"\n },\n \"onlineInfo\": null,\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"4775866734\"\n },\n \"email\": \"NS@gmail.com\"\n }\n ],\n \"message\": \"Fetched stores successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Query Parameters for the supported paging parameters.\n\n---" }, { "title": "Update Store Details", "slug": "stores-update-store-details", "description": "Updates the store details. You can use this API to edit the name, address information, email address, and phone number of a store.", "api": "Stores API", "method": "PUT", "path": "/partners/:partnerId/merchants/:merchantId/stores/:storeId", "content": "# Update Store Details\n\n## Overview\nUpdates the store details. You can use this API to edit the name, address information, email address, and phone number of a store.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /partners/:partnerId/merchants/:merchantId/stores/:storeId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeName` | `string` | No | Name of the store. |\n| `email` | `string` | No | Email address of the store. |\n| `phoneNumber` | `object` | No | Contact number of the store in code and number format. |\n|     `code` | `string` | No | International dialing code identifying the country or region. |\n|     `number` | `string` | No | A string of numbers ranging from 0-9 with a length of 5-15 characters |\n| `address` | `object` | No | Address of the store. |\n|     `addressLine1` | `string` | No | First line of address. |\n|     `addressLine2` | `string` | No | Second line of address. |\n|     `addressLine3` | `string` | No | Third line of address. |\n|     `city` | `string` | No | City where the store is located. |\n|     `countryCode` | `string` | No | Two-letter ISO country code in uppercase, representing the location of the store. |\n|     `postalCode` | `string` | No | Postal code of the store. |\n|     `careOf` | `string` | No | Care-of (c/o) recipient line for the address. |\n| `acquirerMID` | `string` | No | Acquirer Merchant ID. Required for payment facilitator partners that want to support a store-based acquiring model. |\n| `onlineInfo` | `object` | No | In order to update a physical store into an online store, some additional properties are required. Online info can be updated only once. |\n|     `merchantWebshopURL` | `string` | Yes | This is the web-shop URL of the merchant. |\n|     `paymentPageHostURL` | `string` | No | This is the URL of the payment page. Required for integrating online payments using SDK mode. |\n|     `termsAndConditionsURL` | `string` | Yes | This is the URL of the T&C of the merchant’s web-shop, it has to contain the refund policy. |\n|     `privacyPolicyURL` | `string` | Yes | This is the URL of the privacy policy of the merchant. |\n|     `googlePayMerchantId` | `string` | No | Your Google Pay merchant identifier, used to enable Google Pay on the online store. |\n\n### Request Example\n```json\n{\n \"storeName\": \"Updated Store\",\n \"email\": \"US@gmail.com\",\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"7312345678\"\n },\n \"address\": {\n \"addressLine1\": \"Hagmarksgatan 3\",\n \"addressLine2\": \"Suite 724\",\n \"addressLine3\": \"North\",\n \"city\": \"Stockholm\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"103 16\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. 'SUCCESS' \\| 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `merchantUrlDomainVerificationKey` | `string` | Verification key to place on the merchant's webshop domain to prove ownership. Returned only when online store details were provided. |\n|     `paymentPageUrlDomainVerificationKey` | `string` | Verification key to place on the payment page host domain to prove ownership. Returned only when a payment page host URL was provided. |\n| `message` | `string` | Message describing the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"merchantUrlDomainVerificationKey\": \"499470649f03b53fa1175659d4389743974710260b7f410313487e6062b3d559\",\n \"paymentPageUrlDomainVerificationKey\": \"2179beab4f5e8c3960615205f042939a2ccc6c51a6e5923c9c068b3d9a645590\"\n },\n \"message\": \"Store data updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Verify Store Domain", "slug": "stores-verify-store-domain", "description": "Use this API to trigger a verify domain request with Surfboard.", "api": "Stores API", "method": "POST", "path": "/partners/:partnerId/merchants/:merchantId/stores/:storeId/verify", "content": "# Verify Store Domain\n\n## Overview\nUse this API to trigger a verify domain request with Surfboard.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/merchants/:merchantId/stores/:storeId/verify\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `domainType` | `String` | Yes | Specify the domain to be verified. Possible values: `MERCHANT_WEBSHOP_URL`, `PAYMENT_PAGE_HOST_URL`. |\n\n### Request Example\n```json\n{\n \"domainType\": \"MERCHANT_WEBSHOP_URL\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | Message describing the status of domain verification of store. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Domain verification done successfully for store: 8254c42dc430e00e0f.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Template", "slug": "templates-create-template", "description": "This API allows you to create a new POS template.", "api": "Templates API", "method": "POST", "path": "/merchants/:merchantId/stores/:storeId/templates", "content": "# Create Template\n\n## Overview\nThis API allows you to create a new POS template.\n\n## Prerequisites\n- A valid merchant ID and store ID are required in the URL path.\n- Authentication via API key and secret is required.\n- The merchant must have necessary permissions to create POS templates.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /merchants/:merchantId/stores/:storeId/templates\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Query Parameters\nN/A\n\n### Request Body Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| paymentMethodOrder | array | No | Array of preferred payment methods that will be displayed on the POS system in the order of preference. |\n| name | string | Yes | Name or label for the POS template. |\n| productsPerPage | number | No | Number of products to be displayed per page in the POS template. |\n| product | array | No | Product categories and their order. |\n|     category | string | Yes | Category of the product. |\n|     productOrder | array | Yes | Array of product IDs in the preferred order. |\n| autoSet | array | No | Array of time intervals during which certain automatic settings or actions should be applied. |\n|     start | string | Yes | Start time for the interval. |\n|     end | string | Yes | End time for the interval. |\n| terminal | object | No | Terminal information for the POS template. |\n|     primaryTerminal | string | No | ID of the primary terminal to be used. |\n|     secondaryTerminal | string | No | ID of the secondary terminal to be used. |\n|     terminalOrder | array | No | Array of terminal IDs in the preferred order. |\n| metaData | object | No | Additional metadata for the POS template as key-value pairs. |\n\n### Request Example\n```json\n{\n \"paymentMethodOrder\": [\"SWISH\"],\n \"name\": \"SurfboardString\",\n \"productsPerPage\": 10,\n \"autoSet\": [\n {\n \"start\": \"06:00\",\n \"end\": \"09:00\"\n },\n {\n \"start\": \"11:00\",\n \"end\": \"18:00\"\n }\n ],\n \"product\": [\n {\n \"category\": \"electronics\",\n \"productOrder\": [\"82674cfdf77f500001\", \"82674cfdf77f500001\"]\n }\n ],\n \"terminal\": {\n \"primaryTerminal\": \"82674beadf0f700405\",\n \"terminalOrder\": [\"82674beadf0f700405\"]\n },\n \"metaData\": {\n \"we\": \"do\",\n \"do\": \"we\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request. |\n| data | object | Response data. |\n|     templateId | string | The unique identifier of the newly created POS template. |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"templateId\": \"8271dfa5782e380148\"\n },\n \"message\": \"Pos-Template Created Successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body\"\n}\n```\n**Description:** The request body is malformed or missing required fields. Ensure that the request body is valid JSON and contains all required fields.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid API key\"\n}\n```\n**Description:** The provided API key is invalid or missing. Verify that you have supplied a valid API key in the request headers.\n\n#### 403 - Forbidden\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Insufficient permissions\"\n}\n```\n**Description:** The merchant does not have sufficient permissions to create templates. Ensure that the merchant account has the necessary privileges.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Merchant or store not found\"\n}\n```\n**Description:** The specified merchant or store ID does not exist. Verify that the merchant ID and store ID in the URL path are correct.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `templateId` is automatically generated and returned in the success response.\n- The order of elements within arrays like `paymentMethodOrder` and `productOrder` is significant and determines the display order.\n- Time values in `autoSet` should be in a valid 24-hour format (HH:MM).\n- The `metaData` field allows for flexible extension with custom key-value pairs.\n\n---" }, { "title": "Delete Template by ID", "slug": "templates-delete-template-by-id", "description": "Use this API to delete an existing template by Template ID.", "api": "Templates API", "method": "DELETE", "path": "/merchants/:merchantId/stores/:sId/templates/:templateId", "content": "# Delete Template by ID\n\n## Overview\nUse this API to delete an existing template by Template ID.\n\n## Prerequisites\n- A valid `merchantId` and `sId` (Store ID).\n- The `templateId` of the template you wish to delete.\n- Authentication is required using API Key and API Secret.\n- `MERCHANT-ID` header must be provided.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /merchants/:merchantId/stores/:sId/templates/:templateId\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Query Parameters\n*None*\n\n### Request Body Parameters\n*None*\n\n### Request Example\n```json\n// No request body is needed for DELETE requests\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request. Values: `SUCCESS`, `FAILURE`. |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n\t\"status\": \"SUCCESS\",\n\t\"message\": \"Template id [8271dfa5782e380148] deleted successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### *Error responses are not defined in the provided JSON.*\n\n## Notes\n- Ensure the `templateId` exists before attempting to delete it. Deleting a non-existent template might not result in an explicit error but may return a success message without actually deleting anything.\n\n---" }, { "title": "Fetch Template by ID", "slug": "templates-fetch-template-by-id", "description": "This API retrieves the details of a specific POS template using its ID.", "api": "Templates API", "method": "GET", "path": "/merchants/:merchantId/stores/:sId/templates/:templateId", "content": "# Fetch Template by ID\n\n## Overview\nThis API retrieves the details of a specific POS template using its ID.\n\n## Prerequisites\n- A valid merchant ID and store ID are required.\n- A valid template ID must be provided.\n- API Key and API Secret authentication are required.\n- Ensure the POS template exists.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:sId/templates/:templateId\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Query Parameters\n*No query parameters for this endpoint.*\n\n### Request Body Parameters\n*No request body parameters for this endpoint.*\n\n### Request Example\n```json\n{\n \"headers\": {\n \"Content-Type\": \"application/json\",\n \"API-KEY\": \"YOUR_API_KEY\",\n \"API-SECRET\": \"YOUR_API_SECRET\",\n \"MERCHANT-ID\": \"YOUR_MERCHANT_ID\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request. |\n| data | object | Response data. |\n| data.templateId | string | The unique identifier of the newly created POS template. |\n| data.userId | string | Unique identifier of the user who created the POS template. |\n| data.paymentMethodOrder | array | Array of preferred payment methods that will be displayed on the POS system in the order of preference. |\n| data.name | string | Name or label for the POS template. |\n| data.productsPerPage | number | Number of products to be displayed per page in the POS template. |\n| data.product | array | Product categories and their order. |\n| data.product.category | string | Category of the product. |\n| data.product.productOrder | array | Array of product IDs in the preferred order. |\n| data.autoSet | array | Array of time intervals during which certain automatic settings or actions should be applied. |\n| data.autoSet.start | string | Start time for the interval. |\n| data.autoSet.end | string | End time for the interval. |\n| data.terminal | object | Terminal information for the POS template. |\n| data.terminal.primaryTerminal | string | ID of the primary terminal to be used. |\n| data.terminal.secondaryTerminal | string | ID of the secondary terminal to be used. |\n| data.terminal.terminalOrder | array | Array of terminal IDs in the preferred order. |\n| data.metaData | object | Additional metadata for the POS template as key-value pairs. |\n| data.deleted | boolean | Denotes whether the template was deleted or not. |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n\t\"status\": \"SUCCESS\",\n\t\"data\": {\n\t\t\"templateId\": \"8267defa6150700b48\",\n\t\t\"userId\": \"u_EArLulLMogC6b-9e9Gci0\",\n\t\t\"name\": \"SurfboardString\",\n\t\t\"terminalOrder\": {\n\t\t\t\"terminalOrder\": [\n\t\t\t\t\"82674beadf0f700405\"\n\t\t\t],\n\t\t\t\"primaryTerminal\": \"82674beadf0f700405\",\n\t\t\t\"secondaryTerminal\": null\n\t\t},\n\t\t\"categoryOrder\": null,\n\t\t\"productOrder\": [\n\t\t\t{\n\t\t\t\t\"category\": \"electronics\",\n\t\t\t\t\"productOrder\": [\n\t\t\t\t\t\"82674cfdf77f500001\",\n\t\t\t\t\t\"82674cfdf77f500001\"\n\t\t\t\t]\n\t\t\t}\n\t\t],\n\t\t\"paymentMethodOrder\": [\n\t\t\t\"SWISH\"\n\t\t],\n\t\t\"autoSet\": [\n\t\t\t{\n\t\t\t\t\"start\": \"06:00\",\n\t\t\t\t\"end\": \"09:00\"\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"start\": \"11:00\",\n\t\t\t\t\"end\": \"18:00\"\n\t\t\t}\n\t\t],\n\t\t\"deleted\": false,\n\t\t\"metadata\": {\n\t\t\t\"we\": \"do\",\n\t\t\t\"do\": \"we\"\n\t\t}\n\t},\n\t\"message\": \"Template Data fetched successfully for the template id [8267defa6150700b48]\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** This error occurs if the request parameters are invalid, such as missing required fields or incorrect data types. Ensure all required parameters are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized: Invalid API key or secret.\"\n}\n```\n**Description:** This error indicates that the API key or secret is invalid or missing. Verify the API key and secret and include them in the request headers.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Template not found.\"\n}\n```\n**Description:** This error indicates that the template with the provided ID does not exist. Verify that the template ID is correct and that the template exists in the system.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred on the server.\"\n}\n```\n**Description:** This error indicates that an unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `terminalOrder`, `categoryOrder`, `productOrder`, `paymentMethodOrder`, and `autoSet` fields within the `data` object can be null. This indicates that no specific order or settings have been defined for the template.\n- The `metadata` field in `data` is an open key-value object, allowing for custom data to be stored alongside the template.\n- Ensure the `merchantId`, `sId` and `templateId` parameters in the endpoint URL are replaced with the actual corresponding values.\n\n---" }, { "title": "Fetch Templates", "slug": "templates-fetch-templates", "description": "This API retrieves all the POS templates created under the user.", "api": "Templates API", "method": "GET", "path": "/merchants/:merchantId/stores/:sId/templates", "content": "# Fetch Templates\n\n## Overview\nThis API retrieves all the POS templates created under the user.\n\n## Prerequisites\n- A valid merchant ID and store ID are required.\n- Authentication is required using API Key and API Secret.\n- The merchant must have created POS templates.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:sId/templates\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| Content-Type | application/json | Yes |\n| API-KEY | YOUR_API_KEY | Yes |\n| API-SECRET | YOUR_API_SECRET | Yes |\n| MERCHANT-ID | YOUR_MERCHANT_ID | Yes |\n\n### Query Parameters\nN/A\n\n### Request Body Parameters\nN/A\n\n### Request Example\n```json\n{\n \"headers\": {\n \"Content-Type\": \"application/json\",\n \"API-KEY\": \"YOUR_API_KEY\",\n \"API-SECRET\": \"YOUR_API_SECRET\",\n \"MERCHANT-ID\": \"YOUR_MERCHANT_ID\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| status | string | Status of the request. |\n| data | array | Response data containing an array of POS template objects. |\n| data[].templateId | string | The unique identifier of the POS template. |\n| data[].userId | string | Unique identifier of the user who created the POS template. |\n| data[].paymentMethodOrder | array | Array of preferred payment methods that will be displayed on the POS system in the order of preference. |\n| data[].name | string | Name or label for the POS template. |\n| data[].productsPerPage | number | Number of products to be displayed per page in the POS template. |\n| data[].product | array | Product categories and their order. |\n| data[].product[].category | string | Category of the product. |\n| data[].product[].productOrder | array | Array of product IDs in the preferred order. |\n| data[].autoSet | array | Array of time intervals during which certain automatic settings or actions should be applied. |\n| data[].autoSet[].start | string | Start time for the interval. |\n| data[].autoSet[].end | string | End time for the interval. |\n| data[].terminal | object | Terminal information for the POS template. |\n| data[].terminal.primaryTerminal | string | ID of the primary terminal to be used. |\n| data[].terminal.secondaryTerminal | string | ID of the secondary terminal to be used. |\n| data[].terminal.terminalOrder | array | Array of terminal IDs in the preferred order. |\n| data[].metaData | object | Additional metadata for the POS template as key-value pairs. |\n| data[].deleted | boolean | Denotes whether the template was deleted or not |\n| message | string | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"templateId\": \"826dcc0b62e0100248\",\n \"userId\": \"u_EArLulLMogC6b-9e9Gci0\",\n \"name\": \"SurfboardString\",\n \"terminalOrder\": {\n \"terminalOrder\": [\n \"82674beadf0f700405\"\n ],\n \"primaryTerminal\": \"82674beadf0f700405\",\n \"secondaryTerminal\": null\n },\n \"categoryOrder\": null,\n \"productOrder\": [\n {\n \"category\": \"electronics\",\n \"productOrder\": [\n \"82674cfdf77f500001\",\n \"82674cfdf77f500001\"\n ]\n }\n ],\n \"paymentMethodOrder\": [\n \"SWISH\"\n ],\n \"autoSet\": [\n {\n \"start\": \"06:00\",\n \"end\": \"09:00\"\n },\n {\n \"start\": \"11:00\",\n \"end\": \"18:00\"\n }\n ],\n \"deleted\": false\n }\n ],\n \"message\": \"Template Data fetched successfully for the user id [u_EArLulLMogC6b-9e9Gci0]\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** This error occurs when the request parameters are invalid. Ensure all required parameters are present and of the correct type. Check your API key and secret as well.\n\n---\n## Notes\n- `merchantId` and `sId` in the URL path should be replaced with the actual Merchant ID and Store ID.\n- The `API-KEY`, `API-SECRET` and `MERCHANT-ID` in the headers must be valid for authentication and authorization.\n- If there are no templates found, the data array will be empty." }, { "title": "Update Template", "slug": "templates-update-template", "description": "This API allows you to update an existing POS template.", "api": "Templates API", "method": "PUT", "path": "/merchants/:merchantId/stores/:sId/templates/:templateId", "content": "# Update Template\n\n## Overview\nThis API allows you to update an existing POS template.\n\n## Prerequisites\n- You need a valid `merchantId`, `sId` (store ID), and `templateId`.\n- You must have a valid API key and secret.\n- The template must already exist.\n- You need `PUT` access to the resource.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /merchants/:merchantId/stores/:sId/templates/:templateId\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentMethodOrder` | `array` | No | Array of preferred payment methods that will be displayed on the POS system in the order of preference. |\n| `name` | `string` | Yes | Name or label for the POS template. |\n| `productsPerPage` | `number` | No | Number of products to be displayed per page in the POS template. |\n| `product` | `array` | No | Product categories and their order. |\n|     `category` | `string` | Yes | Category of the product. |\n|     `productOrder` | `array` | Yes | Array of product IDs in the preferred order. |\n| `autoSet` | `array` | No | Array of time intervals during which certain automatic settings or actions should be applied. |\n|     `start` | `string` | Yes | Start time for the interval. |\n|     `end` | `string` | Yes | End time for the interval. |\n| `terminal` | `object` | No | Terminal information for the POS template. |\n|     `primaryTerminal` | `string` | No | ID of the primary terminal to be used. |\n|     `secondaryTerminal` | `string` | No | ID of the secondary terminal to be used. |\n|     `terminalOrder` | `array` | No | Array of terminal IDs in the preferred order. |\n| `metaData` | `object` | No | Additional metadata for the POS template as key-value pairs. |\n\n### Request Example\n```json\n{\n \"name\": \"Summer Sale Template\",\n \"productsPerPage\": 12,\n \"paymentMethodOrder\": [\"cash\", \"credit_card\", \"mobile_payment\"],\n \"product\": [\n {\n \"category\": \"Beverages\",\n \"productOrder\": [\"prod123\", \"prod456\", \"prod789\"]\n },\n {\n \"category\": \"Snacks\",\n \"productOrder\": [\"prod987\", \"prod654\", \"prod321\"]\n }\n ],\n \"autoSet\": [\n {\n \"start\": \"09:00\",\n \"end\": \"12:00\"\n },\n {\n \"start\": \"14:00\",\n \"end\": \"17:00\"\n }\n ],\n \"terminal\": {\n \"primaryTerminal\": \"terminal_alpha\",\n \"secondaryTerminal\": \"terminal_beta\",\n \"terminalOrder\": [\"terminal_alpha\", \"terminal_beta\", \"terminal_gamma\"]\n },\n \"metaData\": {\n \"theme\": \"light\",\n \"location\": \"front\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Pos-Template updated Successfully for template id 8269d8d131d1100848\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** This error occurs when the request body is malformed or contains invalid data. Check that all required fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access.\"\n}\n```\n**Description:** This error occurs when the API key or secret is invalid or missing. Ensure that the `API-KEY` and `API-SECRET` headers are correctly set. Also make sure `MERCHANT-ID` is set correctly.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Template not found.\"\n}\n```\n**Description:** This error occurs when the specified `templateId` does not exist. Verify that the template ID is correct.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** This error indicates a problem on the server side. Contact support if the error persists.\n\n## Notes\n- The `merchantId`, `sId`, and `templateId` are part of the URL path and should be replaced with the actual values for the merchant, store, and template being updated, respectively.\n- Make sure the time format for the `start` and `end` times in `autoSet` is consistent.\n- The order of items in the `productOrder` array within the `product` array dictates the display order.\n- The `metaData` object can contain any custom key-value pairs you need to associate with the template.\n\n---" }, { "title": "Change Store", "slug": "terminals-change-store", "description": "Changes the store to which the terminal is registered. You can use this API to utilize the terminal in another store created under the same merchant. However, the Terminal ID remains unchanged.", "api": "Terminals API", "method": "POST", "path": "/terminals/change", "content": "# Change Store\n\n## Overview\nChanges the store to which the terminal is registered. You can use this API to utilize the terminal in another store created under the same merchant. However, the Terminal ID remains unchanged.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /terminals/change\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminal$id` | `string` | Yes | Terminal ID of the terminal for which the store needs to be changed. |\n| `storeId` | `string` | No | Store ID of the store to which the terminal needs to be registered. |\n\n### Request Example\n```json\n{\n \"terminal$id\": \"c_Ou8mzoVQVn6dS4hvNtKH2\",\n \"storeId\": \"st_GZVDbwmS86_G9pwc669U2\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the store change. |\n| `message` | `string` | A message that describes the status of the store change. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Store successfully changed for the terminal\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n\n---" }, { "title": "Check Link Status", "slug": "terminals-check-link-status", "description": "Retrieves the linkage status between the terminal and CheckoutPro. Use this API to obtain the current link state between the terminal and CheckoutPro.", "api": "Terminals API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId/link", "content": "# Check Link Status\n\n## Overview\nRetrieves the linkage status between the terminal and CheckoutPro. Use this API to obtain the current link state between the terminal and CheckoutPro.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId/link\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId/link\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `linkageStatus` | `string` | Describes the linkage status of the terminal with CheckoutPro. i.e. ‘LINKED’ \\| ‘NOT_LINKED’. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"linkageStatus\": \"LINKED\"\n },\n \"message\": \"Fetched terminal status\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Delink Terminal from Store", "slug": "terminals-delink-terminal-from-store", "description": "Delinks the terminal from its registered store. Use this API to remove a terminal from its registered store. You cannot use this delinked terminal for another merchant. However, if you want to use this terminal in another store created under the same merchant, you can use the Change Store API.", "api": "Terminals API", "method": "POST", "path": "/terminals/deactivate", "content": "# Delink Terminal from Store\n\n## Overview\nDelinks the terminal from its registered store. Use this API to remove a terminal from its registered store. You cannot use this delinked terminal for another merchant. However, if you want to use this terminal in another store created under the same merchant, you can use the Change Store API.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /terminals/deactivate\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminal$id` | `string` | Yes | Terminal ID of the terminal that has to be delinked. |\n| `storeId` | `string` | No | Store ID of the store from which the terminal needs to be delinked. |\n\n### Request Example\n```json\n{\n \"terminal$id\": \"c_Ou8mzoVQVn6dS4hvNtKH2\",\n \"storeId\": \"st_GZVDbwmS86_G9pwc669U2\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | A message that describes the status of the terminal delinking. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Terminal removed from store\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n\n---" }, { "title": "Delink Terminal", "slug": "terminals-delink-terminal", "description": "Delinks the terminal from its linked CheckoutPro. Use this API to swap the terminal between different Checkouts.", "api": "Terminals API", "method": "DELETE", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId/link", "content": "# Delink Terminal\n\n## Overview\nDelinks the terminal from its linked CheckoutPro. Use this API to swap the terminal between different Checkouts.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /merchants/:merchantId/stores/:storeId/terminals/:terminalId/link\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminal$id` | `string` | Yes | Terminal ID of the terminal to delink from the CheckoutPro identified by the :terminalId path parameter. |\n\n### Request Example\n```json\n{\n \"terminal$id\": \"814aae4268e6700704\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | A message that describes the status of the delinking request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Terminal delinked successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Merchant Terminal Config", "slug": "terminals-fetch-merchant-terminal-config", "description": "Use this API to fetch all currently active terminal configurations for the merchant.", "api": "Terminals API", "method": "GET", "path": "/merchants/:merchantId/terminals/config", "content": "# Fetch Merchant Terminal Config\n\n## Overview\nUse this API to fetch all currently active terminal configurations for the merchant.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/terminals/config\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/terminals/config\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `wifiSsid` | `string` | Name of the WiFi network. |\n|     `wifiPassword` | `string` | Password for the WiFi network. |\n|     `autoSleep` | `number` | Auto sleep time for the terminal in seconds. Terminal will sleep if no transactions are received in this time period. Only applies if the terminal is running on battery. |\n|     `preferredRestartTime` | `string` | Scheduled restart time for the terminal in HH:MM format. The default is 02:00am according to the device's timezone. It has a 1 hour restart window. For example, if set to 02:00am, restart could occur anytime between 02:00am and 02:59am. It is essential for the device to restart at least once every 24 hours. This might be particularly important for businesses that operate beyond the default restart time. |\n|     `preferredNetwork` | `string` | Preferred network for the terminal. It can be either 'WIFI' or 'GSM'. Possible values: `WIFI`, `GSM`. |\n|     `alwaysShowMinorUnits` | `number` | Determines how the amount is displayed on the terminal. It can be either '0' or '1'. When set to '1', the terminal will always display the minor units, even for whole numbers (e.g., 29 will be displayed as 29.00). When set to 0, the terminal will not include minor units for whole numbers. |\n|     `language` | `string` | Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'. |\n|     `showStatusBar` | `boolean` | Determines whether the status bar is displayed on the terminal. If set 'TRUE', the terminal will display the status bar. This is applicable to SurfPad terminals. |\n|     `chipReadDelay` | `number` | Time delay in milliseconds before the card is read. |\n|     `showReceipt` | `boolean` | Set this to determine how receipts are showcased on the terminal. |\n|     `preferredGsmOperator` | `number` | The preferred GSM operator identified by a numeric code. |\n|     `openPosOnReboot` | `string` | Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'. |\n|     `enableRefundLock` | `boolean` | Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals. |\n|     `screenTimeout` | `number` | The duration (in milliseconds) before the screen times out due to inactivity. |\n|     `autoSleepInterval` | `number` | The interval (in milliseconds) before the device automatically goes to sleep. |\n|     `receiptScreenTimeout` | `number` | Timeout of the receipt screen on hardware terminals. |\n|     `offlineMode` | `string` | Current offline-payments toggle for the terminal. Possible values: `enabled`, `disabled`. |\n|     `displayContrast` | `number` | Display contrast level of the terminal screen. |\n|     `idleScreenImageUrl` | `string` | URL of the image shown on the terminal idle screen. |\n|     `lockScreenPin` | `string` | PIN required to unlock the terminal lock screen. |\n|     `refundScreenPin` | `string` | PIN required to authorize refunds on the terminal. |\n|     `enableLockScreen` | `boolean` | Whether the terminal auto-lock screen is enabled. |\n|     `printerConfig` | `string` | Printer configuration mode set for the terminal. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"preferredRestartTime\": \"02:00\",\n \"preferredNetwork\": \"WIFI\",\n \"wifiSsid\": \"surfboard\",\n \"wifiPassword\": \"surfboa\",\n \"language\": \"da\",\n \"autoSleep\": 400,\n \"alwaysShowMinorUnits\": 1,\n \"showStatusBar\": false,\n \"showReceipt\": true,\n \"chipReadDelay\": 500,\n \"openPosOnReboot\": \"enabled\",\n \"enableRefundLock\": true,\n \"screenTimeout\": 3000000,\n \"preferredGsmOperator\": 2,\n \"offlineMode\": \"enabled\"\n },\n \"message\": \"Merchant Terminal config queried successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Store Terminal Config", "slug": "terminals-fetch-store-terminal-config", "description": "Use this API to fetch all currently active configurations for the store.", "api": "Terminals API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/terminals/config", "content": "# Fetch Store Terminal Config\n\n## Overview\nUse this API to fetch all currently active configurations for the store.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/terminals/config\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/terminals/config\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `wifiSsid` | `string` | Name of the WiFi network. |\n|     `wifiPassword` | `string` | Password for the WiFi network. |\n|     `autoSleep` | `number` | Auto sleep time for the terminal in seconds. Terminal will sleep if no transactions are received in this time period. Only applies if the terminal is running on battery. |\n|     `preferredRestartTime` | `string` | Scheduled restart time for the terminal in HH:MM format. The default is 02:00am according to the device's timezone. It has a 1 hour restart window. For example, if set to 02:00am, restart could occur anytime between 02:00am and 02:59am. It is essential for the device to restart at least once every 24 hours. This might be particularly important for businesses that operate beyond the default restart time. |\n|     `preferredNetwork` | `string` | Preferred network for the terminal. It can be either 'WIFI' or 'GSM'. Possible values: `WIFI`, `GSM`. |\n|     `alwaysShowMinorUnits` | `number` | Determines how the amount is displayed on the terminal. It can be either '0' or '1'. When set to '1', the terminal will always display the minor units, even for whole numbers (e.g., 29 will be displayed as 29.00). When set to 0, the terminal will not include minor units for whole numbers. |\n|     `language` | `string` | Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'. |\n|     `showStatusBar` | `boolean` | Determines whether the status bar is displayed on the terminal. If set 'TRUE', the terminal will display the status bar. This is applicable to SurfPad terminals. |\n|     `chipReadDelay` | `number` | Time delay in milliseconds before the card is read. |\n|     `showReceipt` | `boolean` | Set this to determine how receipts are showcased on the terminal. |\n|     `preferredGsmOperator` | `number` | The preferred GSM operator identified by a numeric code. |\n|     `openPosOnReboot` | `string` | Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'. |\n|     `enableRefundLock` | `boolean` | Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals. |\n|     `screenTimeout` | `number` | The duration (in milliseconds) before the screen times out due to inactivity. |\n|     `autoSleepInterval` | `number` | The interval (in milliseconds) before the device automatically goes to sleep. |\n|     `receiptScreenTimeout` | `number` | Timeout of the receipt screen on hardware terminals. |\n|     `offlineMode` | `string` | Current offline-payments toggle for the terminal. Possible values: `enabled`, `disabled`. |\n|     `displayContrast` | `number` | Display contrast level of the terminal screen. |\n|     `idleScreenImageUrl` | `string` | URL of the image shown on the terminal idle screen. |\n|     `lockScreenPin` | `string` | PIN required to unlock the terminal lock screen. |\n|     `refundScreenPin` | `string` | PIN required to authorize refunds on the terminal. |\n|     `enableLockScreen` | `boolean` | Whether the terminal auto-lock screen is enabled. |\n|     `printerConfig` | `string` | Printer configuration mode set for the terminal. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"preferredRestartTime\": \"02:00\",\n \"preferredNetwork\": \"WIFI\",\n \"wifiSsid\": \"surfboard\",\n \"wifiPassword\": \"surfboa\",\n \"language\": \"da\",\n \"autoSleep\": 400,\n \"alwaysShowMinorUnits\": 1,\n \"showStatusBar\": false,\n \"showReceipt\": true,\n \"chipReadDelay\": 500,\n \"openPosOnReboot\": \"enabled\",\n \"enableRefundLock\": true,\n \"screenTimeout\": 3000000,\n \"preferredGsmOperator\": 2,\n \"offlineMode\": \"enabled\"\n },\n \"message\": \"Store Terminal config queried successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch APN List", "slug": "terminals-fetch-apn-list", "description": "Retrieves the list of APNs of the terminal. The terminal has to be active for a successful read, and the response will be received in exactly 10 seconds.", "api": "Terminals API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId/apns", "content": "# Fetch APN List\n\n## Overview\nRetrieves the list of APNs of the terminal. The terminal has to be active for a successful read, and the response will be received in exactly 10 seconds.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId/apns\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId/apns\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `apns` | `array` | An array of strings depicting all APNs of the terminal. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"apns\": [\n \"WIFI1\",\n \"WIFI2\"\n ]\n }\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Terminal by ID", "slug": "terminals-fetch-terminal-by-id", "description": "Retrieves information about a specific terminal. Use this API to get information regarding a particular terminal registered under a merchant.", "api": "Terminals API", "method": "GET", "path": "/terminals/:terminalId", "content": "# Fetch Terminal by ID\n\n## Overview\nRetrieves information about a specific terminal. Use this API to get information regarding a particular terminal registered under a merchant.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /terminals/:terminalId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /terminals/:terminalId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `terminalId` | `string` | Terminal ID of the terminal. |\n|     `terminalType` | `string` | Describes the type of the terminal. Possible values: `surfpad`, `surftouch`, `surfprint`, `checkoutPro`, `checkoutX`, `PaymentPage`, `SelfHostedPage`, `iFrame`, `MerchantInitiated`. |\n|     `softwareVersion` | `string` | Software version of the terminal. |\n|     `osType` | `string` | Describes the type of Operating System (OS) running on the terminal. Possible values: `android`, `ios`, `sb_firmware`. |\n|     `osVersion` | `string` | Operating System (OS) version of the terminal. |\n|     `deviceVendor` | `string` | Device vendor of the terminal. |\n|     `deviceModel` | `string` | Device model of the terminal. |\n|     `serialNo` | `string` | Serial number of the terminal. |\n|     `storeId` | `string` | The Store ID of the store under which the terminal is registered. |\n|     `linkedTerminalId` | `string` | The Terminal ID of another terminal to which the current terminal is linked. |\n|     `terminalStatus` | `string` | Status of the terminal, it can be in one of these states: REGISTERED \\| ACTIVE \\| IN_ACTIVE \\| DE_REGISTERED. |\n|     `terminalPaymentMethods` | `string` | Payment methods supported by the terminal. |\n|     `startDate` | `string` | Timestamp at which the terminal was created. |\n|     `terminalName` | `string` | Name of the terminal used as a reference for users. |\n|     `lastAliveAt` | `string` | Time at which the terminal was last seen online. |\n|     `isCharging` | `boolean` | A boolean value that denotes if the terminal is charging or not. |\n|     `batteryPercentage` | `number` | Battery percentage of the terminal. |\n|     `powerSource` | `string` | Current power source to the terminal. Possible values: `EXTERNAL_POWER`, `BATTERY`. |\n|     `deviceNetwork` | `string` | The current mode of communication. Possible values: `WIFI`, `GSM`. |\n|     `turnOnTime` | `string` | Last boot up time of terminal. |\n|     `terminalPublicKey` | `string` | Public key used while initializing the SelfHostedPage Online Terminal (Online SDK). |\n|     `metadata` | `object` | Arbitrary key-value metadata stored against the terminal. |\n|     `wifiStrength` | `number` | Wi-Fi signal strength reported by the terminal. |\n|     `gsmStrength` | `number` | GSM signal strength reported by the terminal. |\n|     `signalStrength` | `number` | Overall network signal strength reported by the terminal. |\n|     `softwareMode` | `string` | Software mode the terminal is running in. |\n|     `sdkUrl` | `string` | SDK URL associated with the terminal. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"terminalId\": \"81f878852b3a280904\",\n \"terminalType\": \"surfpad\",\n \"softwareVersion\": \"0.0.0\",\n \"osType\": \"sb_firmware\",\n \"osVersion\": \"0.0.0\",\n \"deviceVendor\": \"Datecs\",\n \"deviceModel\": \"Datecs PinPad\",\n \"serialNo\": \"2922000007\",\n \"storeId\": \"81497439a52270000f\",\n \"linkedTerminalId\": null,\n \"terminalStatus\": \"ACTIVE\",\n \"startDate\": \"2022-11-17T09:29:51.427Z\",\n \"terminalPaymentMethods\": [\n \"CARD\"\n ],\n \"terminalName\": \"My Terminal\",\n \"lastAliveAt\": \"2024-02-21T08:48:26.000Z\",\n \"isCharging\": false,\n \"batteryPercentage\": 100,\n \"powerSource\": \"BATTERY\",\n \"deviceNetwork\": \"WIFI\",\n \"turnOnTime\": \"2024-02-21T05:14:33.417Z\"\n },\n \"message\": \"Fetched terminal details successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Device Registration Code", "slug": "terminals-get-device-registration-code", "description": "This API generates a registration code and link that can be used to register devices to the store. The registration code can be entered manually on the device, or the registration link can be used for automatic registration via a QR code.", "api": "Terminals API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/device-registration", "content": "# Get Device Registration Code\n\n## Overview\nThis API generates a registration code and link that can be used to register devices to the store. The registration code can be entered manually on the device, or the registration link can be used for automatic registration via a QR code.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/device-registration\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/device-registration\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data containing registration information. |\n|     `registrationCode` | `string` | 6-digit registration code that can be entered on the device for registration. |\n|     `registrationLink` | `string` | Deep link URL that can be used for automatic device registration. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"registrationCode\": \"905788\",\n \"registrationLink\": \"checkoutx://com.surfboard.checkoutx/register?data=eyJyZWdpc3RyYXRpb25Db2RlIjoiOTA1Nzg4In0=\"\n },\n \"message\": \"Registration Code Generated Successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Terminal Config", "slug": "terminals-fetch-terminal-config", "description": "Use this API to fetch all currently active configurations for the terminal.", "api": "Terminals API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId/config", "content": "# Fetch Terminal Config\n\n## Overview\nUse this API to fetch all currently active configurations for the terminal.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId/config\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId/config\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `wifiSsid` | `string` | Name of the WiFi network. |\n|     `wifiPassword` | `string` | Password for the WiFi network. |\n|     `autoSleep` | `number` | Auto sleep time for the terminal in seconds. Terminal will sleep if no transactions are received in this time period. Only applies if the terminal is running on battery. |\n|     `preferredRestartTime` | `string` | Scheduled restart time for the terminal in HH:MM format. The default is 02:00am according to the device's timezone. It has a 1 hour restart window. For example, if set to 02:00am, restart could occur anytime between 02:00am and 02:59am. It is essential for the device to restart at least once every 24 hours. This might be particularly important for businesses that operate beyond the default restart time. |\n|     `preferredNetwork` | `string` | Preferred network for the terminal. It can be either 'WIFI' or 'GSM'. Possible values: `WIFI`, `GSM`. |\n|     `alwaysShowMinorUnits` | `number` | Determines how the amount is displayed on the terminal. It can be either '0' or '1'. When set to '1', the terminal will always display the minor units, even for whole numbers (e.g., 29 will be displayed as 29.00). When set to 0, the terminal will not include minor units for whole numbers. |\n|     `language` | `string` | Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'. |\n|     `showStatusBar` | `boolean` | Determines whether the status bar is displayed on the terminal. If set 'TRUE', the terminal will display the status bar. This is applicable to SurfPad terminals. |\n|     `chipReadDelay` | `number` | Time delay in milliseconds before the card is read. |\n|     `showReceipt` | `boolean` | Set this to determine how receipts are showcased on the terminal. |\n|     `preferredGsmOperator` | `number` | The preferred GSM operator identified by a numeric code. |\n|     `openPosOnReboot` | `string` | Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'. |\n|     `enableRefundLock` | `boolean` | Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals. |\n|     `screenTimeout` | `number` | The duration (in milliseconds) before the screen times out due to inactivity. |\n|     `autoSleepInterval` | `number` | The interval (in milliseconds) before the device automatically goes to sleep. |\n|     `receiptScreenTimeout` | `number` | Timeout of the receipt screen on hardware terminals. |\n|     `offlineMode` | `string` | Current offline-payments toggle for the terminal. Possible values: `enabled`, `disabled`. |\n|     `displayContrast` | `number` | Display contrast level of the terminal screen. |\n|     `idleScreenImageUrl` | `string` | URL of the image shown on the terminal idle screen. |\n|     `lockScreenPin` | `string` | PIN required to unlock the terminal lock screen. |\n|     `refundScreenPin` | `string` | PIN required to authorize refunds on the terminal. |\n|     `enableLockScreen` | `boolean` | Whether the terminal auto-lock screen is enabled. |\n|     `printerConfig` | `string` | Printer configuration mode set for the terminal. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"preferredRestartTime\": \"02:00\",\n \"preferredNetwork\": \"WIFI\",\n \"wifiSsid\": \"surfboard\",\n \"wifiPassword\": \"surfboa\",\n \"language\": \"da\",\n \"autoSleep\": 400,\n \"alwaysShowMinorUnits\": 1,\n \"showStatusBar\": false,\n \"showReceipt\": true,\n \"chipReadDelay\": 500,\n \"openPosOnReboot\": \"enabled\",\n \"enableRefundLock\": true,\n \"screenTimeout\": 3000000,\n \"preferredGsmOperator\": 2,\n \"offlineMode\": \"enabled\"\n },\n \"message\": \"Terminal config queried successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Interapp Code", "slug": "terminals-get-interapp-code", "description": "Use this API to generate the registration code used for interapp registration.", "api": "Terminals API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/terminals/interapp", "content": "# Get Interapp Code\n\n## Overview\nUse this API to generate the registration code used for interapp registration.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/terminals/interapp\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/terminals/interapp\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `registrationCode` | `string` | Returns the registration code for interapp. This code is valid for 120 seconds. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"registrationCode\": \"v_Z37lV0JatqBvou\"\n },\n \"message\": \"Inter app code generated Successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Link Terminal", "slug": "terminals-link-terminal", "description": "Links the terminal to the CheckoutPro. You can use this API to link the terminal to a CheckoutPro integration to accept payments.", "api": "Terminals API", "method": "PUT", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId/link", "content": "# Link Terminal\n\n## Overview\nLinks the terminal to the CheckoutPro. You can use this API to link the terminal to a CheckoutPro integration to accept payments.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /merchants/:merchantId/stores/:storeId/terminals/:terminalId/link\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminal$id` | `string` | Yes | Terminal ID of the terminal to link to the CheckoutPro identified by the :terminalId path parameter. |\n\n### Request Example\n```json\n{\n \"terminal$id\": \"814aae4268e6700704\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | A message that describes the status of the linking request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Terminal linked successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Interapp Details", "slug": "terminals-get-interapp-details", "description": "Fetches the current status of the interapp registration for a terminal.", "api": "Terminals API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/terminals/interapp/:registrationCode", "content": "# Get Interapp Details\n\n## Overview\nFetches the current status of the interapp registration for a terminal.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `registrationCode` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/terminals/interapp/:registrationCode\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `registrationCode` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/terminals/interapp/:registrationCode\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Interapp registration details returned for the terminal. |\n|     `registrationStatus` | `string` | Denotes the registration status of the terminal. Possible values: `REGISTERED`, `NOT_REGISTERED`. |\n|     `terminalId` | `string` | Terminal ID of the registered terminal. |\n|     `terminalName` | `string` | The name assigned to the registered terminal. |\n|     `softwareMode` | `string` | The software mode the terminal is running in. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"registrationStatus\": \"REGISTERED\",\n \"terminalId\": \"81f878852b3a280904\",\n \"terminalName\": \"Front Desk Terminal\",\n \"softwareMode\": \"online\"\n },\n \"message\": \"Terminal details fetched successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `registrationCode` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Move Terminal", "slug": "terminals-move-terminal", "description": "Use this API to reassign a hardware terminal to another merchant. This is limited to partners who handle their own storage and deal with terminals in bulk.", "api": "Terminals API", "method": "PUT", "path": "/partners/:partnerId/terminals/:serialNo/move", "content": "# Move Terminal\n\n## Overview\nUse this API to reassign a hardware terminal to another merchant. This is limited to partners who handle their own storage and deal with terminals in bulk.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `serialNo` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /partners/:partnerId/terminals/:serialNo/move\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `serialNo` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `targetMerchantId` | `string` | Yes | Target Merchant ID to which the terminal needs to be assigned. |\n\n### Request Example\n```json\n{\n \"targetMerchantId\": \"81fa6b2d8d5dc8040e\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | A message that describes the status of the move terminal request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Changed merchant for terminal successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `serialNo` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Reboot Terminal", "slug": "terminals-reboot-terminal", "description": "Publishes a reboot command to a terminal. Use this API to remotely restart a terminal. The command is delivered asynchronously, so a SUCCESS response confirms the command was published, not that the device has rebooted.", "api": "Terminals API", "method": "POST", "path": "/terminals/:terminalId/reboot", "content": "# Reboot Terminal\n\n## Overview\nPublishes a reboot command to a terminal. Use this API to remotely restart a terminal. The command is delivered asynchronously, so a SUCCESS response confirms the command was published, not that the device has rebooted.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /terminals/:terminalId/reboot\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | A message that describes the status of the reboot command. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Reboot command published successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Register Device", "slug": "terminals-register-device", "description": "Registers a new terminal to store. For SDK-based workflows, this API call is unnecessary as SDK methods cover terminal registration. After the terminal is registered to a store under the merchant, it cannot be repurposed to be used by another merchant. However, you can use the Change Store API to transfer the terminal to another store under the same merchant.", "api": "Terminals API", "method": "POST", "path": "/merchants/:merchantId/stores/:storeId/devices", "content": "# Register Device\n\n## Overview\nRegisters a new terminal to store. For SDK-based workflows, this API call is unnecessary as SDK methods cover terminal registration. After the terminal is registered to a store under the merchant, it cannot be repurposed to be used by another merchant. However, you can use the Change Store API to transfer the terminal to another store under the same merchant.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /merchants/:merchantId/stores/:storeId/devices\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `registrationIdentifier` | `string` | Yes | Usually, the registrationIdentifier is a 6-digit code found upon starting the terminal. For the SurfPad and Printer, you need to use the serial number from the back of the device. |\n| `terminalName` | `string` | No | Assign a name for your terminal. An optional param to identify a terminal for the user. |\n\n### Request Example\n```json\n{\n \"registrationIdentifier\": \"250901\",\n \"terminalName\": \"Kiosk One\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the terminal registration. |\n| `data` | `object` | Response data. |\n|     `terminalId` | `string` | Terminal ID of the registered terminal. |\n|     `publicKey` | `string` | The terminal public key. Populated for online/SDK terminals; typically null for hardware devices. |\n|     `registrationStatus` | `string` | Represents the current status of the terminal. Possible values: `REGISTERED`, `ALREADY_REGISTERED`. |\n|     `sdkUrl` | `string` | The SDK server URL, returned when a self-hosted SDK key is provisioned for the terminal. |\n| `message` | `string` | A message that describes the status of the terminal registration. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"terminalId\": \"813ca2cb12ce400405\",\n \"registrationStatus\": \"REGISTERED\"\n },\n \"message\": \"Terminal registered successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Register Online Terminal", "slug": "terminals-register-online-terminal", "description": "Registers a terminal with an online store so it can accept online payments.", "api": "Terminals API", "method": "POST", "path": "/merchants/:merchantId/stores/:storeId/online-terminals", "content": "# Register Online Terminal\n\n## Overview\nRegisters a terminal with an online store so it can accept online payments.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /merchants/:merchantId/stores/:storeId/online-terminals\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `onlineTerminalMode` | `string` | Yes | Online payments can be carried out using any of these following modes. Possible values: `PaymentPage`, `SelfHostedPage`, `iFrame`, `MerchantInitiated`. |\n\n### Request Example\n```json\n{\n \"onlineTerminalMode\": \"PaymentPage\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the terminal registration. |\n| `data` | `object` | Response data. |\n|     `terminalId` | `string` | Terminal ID of the registered terminal. |\n|     `publicKey` | `string` | For SelfHostedPage terminals use this key to initialize your Online SDK. |\n|     `registrationStatus` | `string` | Represents the current status of the terminal. Possible values: `REGISTERED`, `DEREGISTERED`, `FAILED`. |\n|     `sdkUrl` | `string` | The SDK server URL, returned when a self-hosted SDK key is provisioned for the terminal. |\n| `message` | `string` | A message that describes the status of the terminal registration. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"terminalId\": \"813ca2cb12ce400405\"\n },\n \"message\": \"Terminal registered successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Set Merchant Terminal Config", "slug": "terminals-set-merchant-terminal-config", "description": "Sets configurations for all the terminals registered to a specific merchant. Use this API to configure uniform settings and parameters across multiple terminals associated with a specific merchant.", "api": "Terminals API", "method": "PATCH", "path": "/merchants/:merchantId/terminals", "content": "# Set Merchant Terminal Config\n\n## Overview\nSets configurations for all the terminals registered to a specific merchant. Use this API to configure uniform settings and parameters across multiple terminals associated with a specific merchant.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /merchants/:merchantId/terminals\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `wifiSsid` | `string` | No | Name of the WiFi network. |\n| `wifiPassword` | `string` | No | Password for the WiFi network. |\n| `autoSleep` | `number` | No | Auto sleep time for the terminal in seconds. Terminal will sleep if no transactions are received in this time period. Only applies if the terminal is running on battery. |\n| `preferredRestartTime` | `string` | No | Scheduled restart time for the terminal in HH:MM format. The default is 02:00am according to the device's timezone. It has a 1 hour restart window. For example, if set to 02:00am, restart could occur anytime between 02:00am and 02:59am. It is essential for the device to restart at least once every 24 hours. This might be particularly important for businesses that operate beyond the default restart time. |\n| `preferredNetwork` | `string` | No | Preferred network for the terminal. It can be either 'WIFI' or 'GSM'. |\n| `alwaysShowMinorUnits` | `number` | No | Determines how the amount is displayed on the terminal. It can be either '0' or '1'. When set to '1', the terminal will always display the minor units, even for whole numbers (e.g., 29 will be displayed as 29.00). When set to 0, the terminal will not include minor units for whole numbers. |\n| `language` | `string` | No | Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'. |\n| `showStatusBar` | `boolean` | No | Determines whether the status bar is displayed on the terminal. If set 'TRUE', the terminal will display the status bar. This is applicable to SurfPad terminals. |\n| `chipReadDelay` | `number` | No | Time delay in milliseconds before the card is read. |\n| `showReceipt` | `boolean` | No | Set this to determine how receipts are showcased on the terminal. |\n| `preferredGsmOperator` | `number` | No | The preferred GSM operator identified by a numeric code. |\n| `openPosOnReboot` | `string` | No | Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'. |\n| `enableRefundLock` | `boolean` | No | Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals. |\n| `refundScreenPin` | `string` | No | The PIN code used to authorize refunds on the screen. This is only available for android terminals. |\n| `screenTimeout` | `number` | No | The duration (in milliseconds) before the screen times out due to inactivity. |\n| `autoSleepInterval` | `number` | No | The interval (in milliseconds) before the device automatically goes to sleep. |\n| `receiptScreenTimeout` | `number` | No | Timeout of the receipt screen on hardware terminals. |\n| `offlineMode` | `string` | No | Controls whether the terminal keeps accepting card payments while offline (stored and forwarded once connectivity returns). Applies to the sb_terminal_k checkout app. Possible values: `enabled`, `disabled`. |\n| `displayContrast` | `number` | No | Display contrast level of the terminal screen. |\n| `idleScreenImageUrl` | `string` | No | URL of the image displayed on the idle screen of the terminal. |\n| `lockScreenPin` | `string` | No | PIN code used to unlock the terminal lock screen. |\n| `enableLockScreen` | `boolean` | No | Determines whether the lock screen is enabled on the terminal. |\n| `printerConfig` | `string` | No | Printer configuration mode for the terminal. |\n\n### Request Example\n```json\n{\n \"wifiSsid\": \"wifiname\",\n \"wifiPassword\": \"wifipassword\",\n \"autoSleep\": 3000,\n \"preferredNetwork\": \"WIFI\",\n \"preferredRestartTime\": \"03:00\",\n \"alwaysShowMinorUnits\": 1,\n \"language\": \"en\",\n \"showStatusBar\": true,\n \"chipReadDelay\": 500,\n \"showReceipt\": true,\n \"offlineMode\": \"enabled\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"MERCHANT config updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Set Store Terminal Config", "slug": "terminals-set-store-terminal-config", "description": "Sets configurations for all the terminals registered to a specific store. Use this API to configure uniform settings and parameters across all the terminals associated with a specific store.", "api": "Terminals API", "method": "PATCH", "path": "/merchants/:merchantId/stores/:storeId/terminals", "content": "# Set Store Terminal Config\n\n## Overview\nSets configurations for all the terminals registered to a specific store. Use this API to configure uniform settings and parameters across all the terminals associated with a specific store.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /merchants/:merchantId/stores/:storeId/terminals\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `wifiSsid` | `string` | No | Name of the WiFi network. |\n| `wifiPassword` | `string` | No | Password for the WiFi network. |\n| `autoSleep` | `number` | No | Auto sleep time for the terminal in seconds. Terminal will sleep if no transactions are received in this time period. Only applies if the terminal is running on battery. |\n| `preferredRestartTime` | `string` | No | Scheduled restart time for the terminal in HH:MM format. The default is 02:00am according to the device's timezone. It has a 1 hour restart window. For example, if set to 02:00am, restart could occur anytime between 02:00am and 02:59am. It is essential for the device to restart at least once every 24 hours. This might be particularly important for businesses that operate beyond the default restart time. |\n| `preferredNetwork` | `string` | No | Preferred network for the terminal. It can be either 'WIFI' or 'GSM'. |\n| `alwaysShowMinorUnits` | `number` | No | Determines how the amount is displayed on the terminal. It can be either '0' or '1'. When set to '1', the terminal will always display the minor units, even for whole numbers (e.g., 29 will be displayed as 29.00). When set to 0, the terminal will not include minor units for whole numbers. |\n| `language` | `string` | No | Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'. |\n| `showStatusBar` | `boolean` | No | Determines whether the status bar is displayed on the terminal. If set 'TRUE', the terminal will display the status bar. This is applicable to SurfPad terminals. |\n| `chipReadDelay` | `number` | No | Time delay in milliseconds before the card is read. |\n| `showReceipt` | `boolean` | No | Set this to determine how receipts are showcased on the terminal. |\n| `preferredGsmOperator` | `number` | No | The preferred GSM operator identified by a numeric code. |\n| `openPosOnReboot` | `string` | No | Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'. |\n| `enableRefundLock` | `boolean` | No | Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals. |\n| `refundScreenPin` | `string` | No | The PIN code used to authorize refunds on the screen. This is only available for android terminals. |\n| `screenTimeout` | `number` | No | The duration (in milliseconds) before the screen times out due to inactivity. |\n| `autoSleepInterval` | `number` | No | The interval (in milliseconds) before the device automatically goes to sleep. |\n| `receiptScreenTimeout` | `number` | No | Timeout of the receipt screen on hardware terminals. |\n| `offlineMode` | `string` | No | Controls whether the terminal keeps accepting card payments while offline (stored and forwarded once connectivity returns). Applies to the sb_terminal_k checkout app. Possible values: `enabled`, `disabled`. |\n| `displayContrast` | `number` | No | Display contrast level of the terminal screen. |\n| `idleScreenImageUrl` | `string` | No | URL of the image displayed on the idle screen of the terminal. |\n| `lockScreenPin` | `string` | No | PIN code used to unlock the terminal lock screen. |\n| `enableLockScreen` | `boolean` | No | Determines whether the lock screen is enabled on the terminal. |\n| `printerConfig` | `string` | No | Printer configuration mode for the terminal. |\n\n### Request Example\n```json\n{\n \"wifiSsid\": \"wifiname\",\n \"wifiPassword\": \"wifipassword\",\n \"autoSleep\": 3000,\n \"preferredNetwork\": \"WIFI\",\n \"preferredRestartTime\": \"03:00\",\n \"alwaysShowMinorUnits\": 1,\n \"language\": \"en\",\n \"showStatusBar\": true,\n \"chipReadDelay\": 500,\n \"showReceipt\": true,\n \"offlineMode\": \"enabled\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"STORE config updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Set Terminal Config", "slug": "terminals-set-terminal-config", "description": "Sets specific configurations for an individual terminal. Use this API to configure settings and parameters for a particular terminal.", "api": "Terminals API", "method": "PATCH", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId", "content": "# Set Terminal Config\n\n## Overview\nSets specific configurations for an individual terminal. Use this API to configure settings and parameters for a particular terminal.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /merchants/:merchantId/stores/:storeId/terminals/:terminalId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `serialNo` | `string` | No | Serial number of the physical terminal. |\n| `wifiSsid` | `string` | No | Name of the WiFi network. |\n| `wifiPassword` | `string` | No | Password for the WiFi network. |\n| `autoSleep` | `number` | No | Auto sleep time for the terminal in seconds. Terminal will sleep if no transactions are received in this time period. Only applies if the terminal is running on battery. |\n| `preferredRestartTime` | `string` | No | Scheduled restart time for the terminal in HH:MM format. The default is 02:00am according to the device's timezone. It has a 1 hour restart window. For example, if set to 02:00am, restart could occur anytime between 02:00am and 02:59am. It is essential for the device to restart at least once every 24 hours. This might be particularly important for businesses that operate beyond the default restart time. |\n| `preferredNetwork` | `string` | No | Preferred network for the terminal. It can be either 'WIFI' or 'GSM'. |\n| `alwaysShowMinorUnits` | `number` | No | Determines how the amount is displayed on the terminal. It can be either '0' or '1'. When set to '1', the terminal will always display the minor units, even for whole numbers (e.g., 29 will be displayed as 29.00). When set to 0, the terminal will not include minor units for whole numbers. |\n| `language` | `string` | No | Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'. |\n| `showStatusBar` | `boolean` | No | Determines whether the status bar is displayed on the terminal. If set 'TRUE', the terminal will display the status bar. This is applicable to SurfPad terminals. |\n| `chipReadDelay` | `number` | No | Time delay in milliseconds before the card is read. |\n| `showReceipt` | `boolean` | No | Set this to determine how receipts are showcased on the terminal. |\n| `preferredGsmOperator` | `number` | No | The preferred GSM operator identified by a numeric code. |\n| `openPosOnReboot` | `string` | No | Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'. |\n| `enableRefundLock` | `boolean` | No | Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals. |\n| `refundScreenPin` | `string` | No | The PIN code used to authorize refunds on the screen. This is only available for android terminals. |\n| `screenTimeout` | `number` | No | The duration (in milliseconds) before the screen times out due to inactivity. |\n| `autoSleepInterval` | `number` | No | The interval (in milliseconds) before the device automatically goes to sleep. |\n| `receiptScreenTimeout` | `number` | No | Timeout of the receipt screen on hardware terminals. |\n| `offlineMode` | `string` | No | Controls whether the terminal keeps accepting card payments while offline (stored and forwarded once connectivity returns). Applies to the sb_terminal_k checkout app. Possible values: `enabled`, `disabled`. |\n| `displayContrast` | `number` | No | Display contrast level of the terminal screen. |\n| `idleScreenImageUrl` | `string` | No | URL of the image displayed on the idle screen of the terminal. |\n| `lockScreenPin` | `string` | No | PIN code used to unlock the terminal lock screen. |\n| `enableLockScreen` | `boolean` | No | Determines whether the lock screen is enabled on the terminal. |\n| `printerConfig` | `string` | No | Printer configuration mode for the terminal. |\n\n### Request Example\n```json\n{\n \"serialNo\": \"123456789\",\n \"wifiSsid\": \"wifiname\",\n \"wifiPassword\": \"wifipassword\",\n \"autoSleep\": 3000,\n \"preferredNetwork\": \"WIFI\",\n \"preferredRestartTime\": \"03:00\",\n \"alwaysShowMinorUnits\": 1,\n \"language\": \"en\",\n \"showStatusBar\": true,\n \"chipReadDelay\": 500,\n \"showReceipt\": true,\n \"offlineMode\": \"enabled\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"TERMINAL config updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Terminal Name", "slug": "terminals-update-terminal-name", "description": "Updates the display name of a registered terminal.", "api": "Terminals API", "method": "PUT", "path": "/terminals/:terminalId", "content": "# Update Terminal Name\n\n## Overview\nUpdates the display name of a registered terminal.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /terminals/:terminalId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalName` | `string` | No | Assign a name for your terminal. A param to identify a terminal for the user. |\n| `metadata` | `object` | No | Arbitrary key-value metadata to store against the terminal. At least one of terminalName or metadata must be provided. |\n\n### Request Example\n```json\n{\n \"terminalName\": \"New Terminal\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | A message that describes the status of the update request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Terminal updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Merchant Tips Config", "slug": "tips-fetch-merchant-tips-config", "description": "Retrieves the merchant-level tips configuration inherited by all terminals registered to the merchant. Use this API to get the tips configuration applied across the merchant.", "api": "Tips APIs", "method": "GET", "path": "/merchants/:merchantId/tips", "content": "# Fetch Merchant Tips Config\n\n## Overview\nRetrieves the merchant-level tips configuration inherited by all terminals registered to the merchant. Use this API to get the tips configuration applied across the merchant.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/tips\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/tips\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `tipConfig` | `string` | Specifies how tips are managed during payment. Always returned as ENABLED or DISABLED; a configuration stored as OTHER_AMOUNT is normalized to ENABLED here and surfaced separately through the freeAmountEnabled flag (which is true in that case). Possible values: `ENABLED`, `DISABLED`. |\n|     `tipLevel1` | `number` | The first preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n|     `tipLevel2` | `number` | The second preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n|     `tipLevel3` | `number` | The third preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n|     `defaultCustomAmount` | `number` | The value pre-filled on the screen for the custom tip amount. |\n|     `displayCalculatedAmount` | `string` | Specifies whether the calculated tip amount is shown on screen. Possible values: `ENABLED`, `DISABLED`. |\n|     `tipDisplayFormat` | `string` | The format in which the preset tip levels are displayed. Possible values: `PERCENTAGE`, `AMOUNT`. |\n|     `freeAmountEnabled` | `boolean` | True when the stored tips configuration is OTHER_AMOUNT (the customer can enter a custom tip amount); otherwise false. Derived directly from tipConfig, so it always accompanies a normalized tipConfig of ENABLED. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"tipConfig\": \"ENABLED\",\n \"tipLevel1\": 10,\n \"tipLevel2\": 20,\n \"tipLevel3\": 30,\n \"defaultCustomAmount\": 25,\n \"displayCalculatedAmount\": \"ENABLED\",\n \"tipDisplayFormat\": \"PERCENTAGE\",\n \"freeAmountEnabled\": true\n },\n \"message\": \"merchant config queried successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Store Tips Config", "slug": "tips-fetch-store-tips-config", "description": "Retrieves the store-level tips configuration applied to all terminals registered to the store. Use this API to get the tips configuration applied across the store.", "api": "Tips APIs", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/tips", "content": "# Fetch Store Tips Config\n\n## Overview\nRetrieves the store-level tips configuration applied to all terminals registered to the store. Use this API to get the tips configuration applied across the store.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/tips\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/tips\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `tipConfig` | `string` | Specifies how tips are managed during payment. Always returned as ENABLED or DISABLED; a configuration stored as OTHER_AMOUNT is normalized to ENABLED here and surfaced separately through the freeAmountEnabled flag (which is true in that case). Possible values: `ENABLED`, `DISABLED`. |\n|     `tipLevel1` | `number` | The first preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n|     `tipLevel2` | `number` | The second preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n|     `tipLevel3` | `number` | The third preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n|     `defaultCustomAmount` | `number` | The value pre-filled on the screen for the custom tip amount. |\n|     `displayCalculatedAmount` | `string` | Specifies whether the calculated tip amount is shown on screen. Possible values: `ENABLED`, `DISABLED`. |\n|     `tipDisplayFormat` | `string` | The format in which the preset tip levels are displayed. Possible values: `PERCENTAGE`, `AMOUNT`. |\n|     `freeAmountEnabled` | `boolean` | True when the stored tips configuration is OTHER_AMOUNT (the customer can enter a custom tip amount); otherwise false. Derived directly from tipConfig, so it always accompanies a normalized tipConfig of ENABLED. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"tipConfig\": \"ENABLED\",\n \"tipLevel1\": 10,\n \"tipLevel2\": 20,\n \"tipLevel3\": 30,\n \"defaultCustomAmount\": 25,\n \"displayCalculatedAmount\": \"ENABLED\",\n \"tipDisplayFormat\": \"PERCENTAGE\",\n \"freeAmountEnabled\": true\n },\n \"message\": \"store config queried successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Terminal Tips Config", "slug": "tips-fetch-terminal-tips-config", "description": "Retrieves the tips configuration for an individual terminal. Use this API to get the tips configuration applied to a particular terminal.", "api": "Tips APIs", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId/tips", "content": "# Fetch Terminal Tips Config\n\n## Overview\nRetrieves the tips configuration for an individual terminal. Use this API to get the tips configuration applied to a particular terminal.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId/tips\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId/tips\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `tipConfig` | `string` | Specifies how tips are managed during payment. Always returned as ENABLED or DISABLED; a configuration stored as OTHER_AMOUNT is normalized to ENABLED here and surfaced separately through the freeAmountEnabled flag (which is true in that case). Possible values: `ENABLED`, `DISABLED`. |\n|     `tipLevel1` | `number` | The first preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n|     `tipLevel2` | `number` | The second preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n|     `tipLevel3` | `number` | The third preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n|     `defaultCustomAmount` | `number` | The value pre-filled on the screen for the custom tip amount. |\n|     `displayCalculatedAmount` | `string` | Specifies whether the calculated tip amount is shown on screen. Possible values: `ENABLED`, `DISABLED`. |\n|     `tipDisplayFormat` | `string` | The format in which the preset tip levels are displayed. Possible values: `PERCENTAGE`, `AMOUNT`. |\n|     `freeAmountEnabled` | `boolean` | True when the stored tips configuration is OTHER_AMOUNT (the customer can enter a custom tip amount); otherwise false. Derived directly from tipConfig, so it always accompanies a normalized tipConfig of ENABLED. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"tipConfig\": \"ENABLED\",\n \"tipLevel1\": 10,\n \"tipLevel2\": 20,\n \"tipLevel3\": 30,\n \"defaultCustomAmount\": 25,\n \"displayCalculatedAmount\": \"ENABLED\",\n \"tipDisplayFormat\": \"PERCENTAGE\",\n \"freeAmountEnabled\": true\n },\n \"message\": \"terminal config queried successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Set Merchant Tips Config", "slug": "tips-set-merchant-tips-config", "description": "Sets the merchant-level tips configuration inherited by all stores and terminals registered to the merchant. Use this API to apply the same tips configuration across every terminal associated with a merchant.", "api": "Tips APIs", "method": "PATCH", "path": "/merchants/:merchantId/tips", "content": "# Set Merchant Tips Config\n\n## Overview\nSets the merchant-level tips configuration inherited by all stores and terminals registered to the merchant. Use this API to apply the same tips configuration across every terminal associated with a merchant.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /merchants/:merchantId/tips\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `tipConfig` | `string` | No | Specifies how tips are managed during the payment. Possible values: `ENABLED`, `DISABLED`, `OTHER_AMOUNT`. |\n| `tipLevel1` | `number` | No | The first preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n| `tipLevel2` | `number` | No | The second preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n| `tipLevel3` | `number` | No | The third preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n| `defaultCustomAmount` | `number` | No | The value pre-filled on the screen for the custom tip amount. |\n| `displayCalculatedAmount` | `string` | No | Specifies whether the calculated tip amount is shown on screen. Possible values: `ENABLED`, `DISABLED`. |\n| `tipDisplayFormat` | `string` | No | The format in which the preset tip levels are displayed. Possible values: `PERCENTAGE`, `AMOUNT`. |\n| `maxCustomTipAmount` | `number` | No | The maximum tip amount a customer can enter for a custom tip. |\n| `freeAmountEnabled` | `boolean` | No | Only meaningful when tipConfig is ENABLED: setting it to true switches the configuration to OTHER_AMOUNT, letting the customer enter a custom tip amount on the tips screen. It has no effect when tipConfig is DISABLED and is not stored as an independent field (equivalent to sending tipConfig: OTHER_AMOUNT). |\n\n### Request Example\n```json\n{\n \"tipConfig\": \"ENABLED\",\n \"tipLevel1\": 10,\n \"tipLevel2\": 20,\n \"tipLevel3\": 30,\n \"defaultCustomAmount\": 25,\n \"displayCalculatedAmount\": \"ENABLED\",\n \"tipDisplayFormat\": \"PERCENTAGE\",\n \"maxCustomTipAmount\": 100,\n \"freeAmountEnabled\": true\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"MERCHANT config updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Set Store Tips Config", "slug": "tips-set-store-tips-config", "description": "Sets the store-level tips configuration applied to every terminal registered to the store. Use this API to apply the same tips configuration across every terminal associated with a store.", "api": "Tips APIs", "method": "PATCH", "path": "/merchants/:merchantId/stores/:storeId/tips", "content": "# Set Store Tips Config\n\n## Overview\nSets the store-level tips configuration applied to every terminal registered to the store. Use this API to apply the same tips configuration across every terminal associated with a store.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /merchants/:merchantId/stores/:storeId/tips\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `tipConfig` | `string` | No | Specifies how tips are managed during the payment. Possible values: `ENABLED`, `DISABLED`, `OTHER_AMOUNT`. |\n| `tipLevel1` | `number` | No | The first preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n| `tipLevel2` | `number` | No | The second preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n| `tipLevel3` | `number` | No | The third preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n| `defaultCustomAmount` | `number` | No | The value pre-filled on the screen for the custom tip amount. |\n| `displayCalculatedAmount` | `string` | No | Specifies whether the calculated tip amount is shown on screen. Possible values: `ENABLED`, `DISABLED`. |\n| `tipDisplayFormat` | `string` | No | The format in which the preset tip levels are displayed. Possible values: `PERCENTAGE`, `AMOUNT`. |\n| `maxCustomTipAmount` | `number` | No | The maximum tip amount a customer can enter for a custom tip. |\n| `freeAmountEnabled` | `boolean` | No | Only meaningful when tipConfig is ENABLED: setting it to true switches the configuration to OTHER_AMOUNT, letting the customer enter a custom tip amount on the tips screen. It has no effect when tipConfig is DISABLED and is not stored as an independent field (equivalent to sending tipConfig: OTHER_AMOUNT). |\n\n### Request Example\n```json\n{\n \"tipConfig\": \"ENABLED\",\n \"tipLevel1\": 10,\n \"tipLevel2\": 20,\n \"tipLevel3\": 30,\n \"defaultCustomAmount\": 25,\n \"displayCalculatedAmount\": \"ENABLED\",\n \"tipDisplayFormat\": \"PERCENTAGE\",\n \"maxCustomTipAmount\": 100,\n \"freeAmountEnabled\": true\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"STORE config updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Set Terminal Tips Config", "slug": "tips-set-terminal-tips-config", "description": "Sets the tips configuration for an individual terminal. Use this API to configure tips for a particular terminal.", "api": "Tips APIs", "method": "PATCH", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId/tips", "content": "# Set Terminal Tips Config\n\n## Overview\nSets the tips configuration for an individual terminal. Use this API to configure tips for a particular terminal.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /merchants/:merchantId/stores/:storeId/terminals/:terminalId/tips\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `tipConfig` | `string` | No | Specifies how tips are managed during the payment. Possible values: `ENABLED`, `DISABLED`, `OTHER_AMOUNT`. |\n| `tipLevel1` | `number` | No | The first preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n| `tipLevel2` | `number` | No | The second preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n| `tipLevel3` | `number` | No | The third preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat. |\n| `defaultCustomAmount` | `number` | No | The value pre-filled on the screen for the custom tip amount. |\n| `displayCalculatedAmount` | `string` | No | Specifies whether the calculated tip amount is shown on screen. Possible values: `ENABLED`, `DISABLED`. |\n| `tipDisplayFormat` | `string` | No | The format in which the preset tip levels are displayed. Possible values: `PERCENTAGE`, `AMOUNT`. |\n| `maxCustomTipAmount` | `number` | No | The maximum tip amount a customer can enter for a custom tip. |\n| `freeAmountEnabled` | `boolean` | No | Only meaningful when tipConfig is ENABLED: setting it to true switches the configuration to OTHER_AMOUNT, letting the customer enter a custom tip amount on the tips screen. It has no effect when tipConfig is DISABLED and is not stored as an independent field (equivalent to sending tipConfig: OTHER_AMOUNT). |\n| `serialNo` | `string` | No | Hardware serial number of the target terminal. |\n\n### Request Example\n```json\n{\n \"tipConfig\": \"ENABLED\",\n \"tipLevel1\": 10,\n \"tipLevel2\": 20,\n \"tipLevel3\": 30,\n \"defaultCustomAmount\": 25,\n \"displayCalculatedAmount\": \"ENABLED\",\n \"tipDisplayFormat\": \"PERCENTAGE\",\n \"maxCustomTipAmount\": 100,\n \"freeAmountEnabled\": true,\n \"serialNo\": \"1850123456\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"TERMINAL config updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Bin Range", "slug": "bin-ranges-create-bin-range", "description": "Create a new bin range together with the card-number sub-ranges it covers.", "api": "Bin Ranges API", "method": "POST", "path": "/bin-ranges", "content": "# Create Bin Range\n\n## Overview\nCreate a new bin range together with the card-number sub-ranges it covers.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required using API Key and API Secret.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /bin-ranges\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `description` | `string` | Yes | A description of the bin range. |\n| `rangesIncluded` | `array` | Yes | The card-number sub-ranges covered by this bin range. |\n|     `start` | `string` | Yes | Inclusive start of the BIN sub-range. |\n|     `end` | `string` | Yes | Inclusive end of the BIN sub-range. |\n|     `description` | `string` | Yes | A description of this sub-range. |\n\n### Request Example\n```json\n{\n \"description\": \"Visa consumer ranges\",\n \"rangesIncluded\": [\n {\n \"start\": \"400000\",\n \"end\": \"499999\",\n \"description\": \"Visa primary range\"\n }\n ]\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The created bin range. |\n|     `binRangeId` | `string` | Unique identifier of the created bin range. |\n|     `partnerId` | `string` | Identifier of the partner that owns the bin range. |\n|     `description` | `string` | Description supplied when the bin range was created. |\n|     `rangesIncluded` | `array` | The card-number sub-ranges stored for this bin range. |\n|         `start` | `string` | Inclusive start of the BIN sub-range. |\n|         `end` | `string` | Inclusive end of the BIN sub-range. |\n|         `description` | `string` | A description of this sub-range. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"binRangeId\": \"br_81efdbe975ebc800\",\n \"partnerId\": \"p_5f2c1a9b3d\",\n \"description\": \"Visa consumer ranges\",\n \"rangesIncluded\": [\n {\n \"start\": \"400000\",\n \"end\": \"499999\",\n \"description\": \"Visa primary range\"\n }\n ]\n },\n \"message\": \"Bin range created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to create bin range\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Authentication failed\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n---" }, { "title": "List Bin Ranges", "slug": "bin-ranges-list-bin-ranges", "description": "Fetch a paginated list of the partner's bin ranges.", "api": "Bin Ranges API", "method": "GET", "path": "/bin-ranges", "content": "# List Bin Ranges\n\n## Overview\nFetch a paginated list of the partner's bin ranges.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required using API Key and API Secret.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /bin-ranges\n```\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `includeInactive` | `boolean` | No | Whether inactive bin ranges are included in the results. |\n\n### Pagination\n\nTo page through results send the requested page in the `x-page-number` header.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /bin-ranges?includeInactive=false\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The list of bin ranges for the current page. |\n|     `binRangeId` | `string` | Unique identifier of the bin range. |\n|     `partnerId` | `string` | Identifier of the partner that owns the bin range. |\n|     `description` | `string` | Description supplied when the bin range was created. |\n|     `rangesIncluded` | `array` | The card-number sub-ranges stored for this bin range. |\n|         `start` | `string` | Inclusive start of the BIN sub-range. |\n|         `end` | `string` | Inclusive end of the BIN sub-range. |\n|         `description` | `string` | A description of this sub-range. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"binRangeId\": \"br_81efdbe975ebc800\",\n \"partnerId\": \"p_5f2c1a9b3d\",\n \"description\": \"Visa consumer ranges\",\n \"rangesIncluded\": [\n {\n \"start\": \"400000\",\n \"end\": \"499999\",\n \"description\": \"Visa primary range\"\n }\n ]\n }\n ],\n \"message\": \"Bin ranges fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to fetch bin ranges\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Authentication failed\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Generate Branding with AI for Partner", "slug": "branding-generate-branding-with-ai-for-partner", "description": "Generate ready-to-use branding suggestions for a partner from a website. Supply the URL of a site and Surfboard analyzes it to propose one or more complete branding options — colors, button shape, font, logo and icon — that you can apply to a partner, merchant, store, or terminal.", "api": "Branding APIs", "method": "POST", "path": "/partners/:partnerId/ai/branding", "content": "# Generate Branding with AI for Partner\n\n## Overview\nGenerate ready-to-use branding suggestions for a partner from a website. Supply the URL of a site and Surfboard analyzes it to propose one or more complete branding options — colors, button shape, font, logo and icon — that you can apply to a partner, merchant, store, or terminal.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/ai/branding\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `url` | `string` | No | Website address to derive branding suggestions from, for example the partner's marketing site. When omitted, an empty URL is used and generic suggestions are returned. |\n\n### Request Example\n```json\n{\n \"url\": \"https://www.surfboard.se\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The generated branding suggestions. |\n|     `brandingOptions` | `array` | The suggested branding configurations. Each entry is a complete set of branding values you can apply. |\n|         `backgroundColor` | `string` | Suggested background color for the page, as a hex color code. |\n|         `brandColor` | `string` | Suggested primary brand color, as a hex color code. |\n|         `accentColor` | `string` | Suggested secondary color that complements the brand color, as a hex color code. |\n|         `rectShape` | `string` | Suggested shape for the page buttons. Possible values: `ROUNDED`, `PILL`, `EDGY`. |\n|         `fontType` | `string` | Suggested font family for the page. Possible values: `serif`, `sans-serif`, `mono`. |\n|         `logoUrl` | `string` | URL of the suggested logo to display on the page. |\n|         `iconUrl` | `string` | URL of the suggested icon to display on the page. |\n|         `footerColor` | `string` | Suggested footer background color, as a hex color code. |\n|     `metadata` | `object` | Details about the generation run. |\n|         `inputTokens` | `number` | Number of input tokens consumed to generate the suggestions. |\n|         `outputTokens` | `number` | Number of output tokens produced while generating the suggestions. |\n|         `outputType` | `string` | The kind of output that was generated. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"brandingOptions\": [\n {\n \"backgroundColor\": \"#F5F5F5\",\n \"brandColor\": \"#0E44E1\",\n \"accentColor\": \"#F08080\",\n \"rectShape\": \"ROUNDED\",\n \"fontType\": \"sans-serif\",\n \"logoUrl\": \"https://res.cloudinary.com/image/surfboard-logo.svg\",\n \"iconUrl\": \"https://res.cloudinary.com/image/surfboard-icon.svg\",\n \"footerColor\": \"#CD5C5B\"\n }\n ],\n \"metadata\": {\n \"inputTokens\": 1024,\n \"outputTokens\": 256,\n \"outputType\": \"json\"\n }\n },\n \"message\": \"Branding generated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to generate branding\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Close-Shift", "slug": "electronic-cash-register-close-shift", "description": "Close the active shift on the cash register identified by the :cashRegisterId path parameter.", "api": "Electronic Cash Register (ECR) V2 API", "method": "PUT", "path": "/merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/close-shift", "content": "# Close-Shift\n\n## Overview\nClose the active shift on the cash register identified by the :cashRegisterId path parameter.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `cashRegisterId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/close-shift\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```json\n{}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `cashRegisterId` | `string` | Cash register identifier. |\n|     `shiftNumber` | `number` | Number of the shift that was closed. |\n|     `pettyCash` | `number` | Petty-cash balance recorded at shift close. |\n| `message` | `string` | Response message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"cashRegisterId\": \"{{cashRegisterId}}\",\n \"shiftNumber\": 1,\n \"pettyCash\": 5000\n },\n \"message\": \"Shift closed successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `cashRegisterId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Cash Register", "slug": "electronic-cash-register-create-cash-register", "description": "Register a terminal as an Electronic Cash Register (ECR) for a specific store.", "api": "Electronic Cash Register (ECR) V2 API", "method": "POST", "path": "/merchants/:merchantId/stores/:storeId/cash-register", "content": "# Create Cash Register\n\n## Overview\nCreate a Cash Register for a specific store.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /merchants/:merchantId/stores/:storeId/cash-register\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `cashRegisterName` | `string` | Yes | Name of the cash register. |\n| `deviceId` | `string` | Yes | Terminal / device identifier. |\n| `emails` | `array` | No | List of email addresses for notifications. |\n\n### Request Example\n```json\n{\n \"cashRegisterName\": \"Main Register\",\n \"deviceId\": \"{{terminalId}}\",\n \"emails\": [\n \"store.manager@example.com\"\n ]\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `cashRegister` | `object` | Cash register details. |\n|         `cashRegisterId` | `string` | Unique identifier for the cash register. Save this ID as it is required for opening the register and shifts. |\n| `message` | `string` | Response message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"cashRegister\": {\n \"cashRegisterId\": \"{{cashRegisterId}}\"\n }\n },\n \"message\": \"Cash register subscribed successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Delete Cash Register", "slug": "electronic-cash-register-delete-cash-register", "description": "Deactivate a cash register. The register is identified by the :cashRegisterId path parameter.", "api": "Electronic Cash Register (ECR) V2 API", "method": "DELETE", "path": "/merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId", "content": "# Delete Cash Register\n\n## Overview\nDelete a Cash Register. The register is identified by the :cashRegisterId path parameter.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `cashRegisterId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | Response message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Cash register unsubscribed successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `cashRegisterId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Deposit Petty Cash", "slug": "electronic-cash-register-deposit-petty-cash", "description": "Deposit petty cash into the cash register during an active shift.", "api": "Electronic Cash Register (ECR) V2 API", "method": "POST", "path": "/merchants/:merchantId/stores/:storeId/cash-register/deposit-petty-cash", "content": "# Deposit Petty Cash\n\n## Overview\nDeposit petty cash into the cash register during an active shift.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /merchants/:merchantId/stores/:storeId/cash-register/deposit-petty-cash\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | Yes | Terminal / device identifier depositing the petty cash. |\n| `amount` | `number` | Yes | Amount of petty cash to deposit into the register. |\n\n### Request Example\n```json\n{\n \"terminalId\": \"{{terminalId}}\",\n \"amount\": 1000\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `cashRegisterId` | `string` | Cash register identifier. |\n|     `newPettyCash` | `number` | Petty-cash balance after the deposit. |\n| `message` | `string` | Response message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"cashRegisterId\": \"{{cashRegisterId}}\",\n \"newPettyCash\": 6000\n },\n \"message\": \"Petty cash inserted successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "End of Day", "slug": "electronic-cash-register-end-of-day", "description": "Perform the end-of-day close on the cash register identified by the :cashRegisterId path parameter.", "api": "Electronic Cash Register (ECR) V2 API", "method": "PUT", "path": "/merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/end-of-day", "content": "# End of Day\n\n## Overview\nPerform the end-of-day close on the cash register identified by the :cashRegisterId path parameter.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `cashRegisterId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/end-of-day\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```json\n{}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | Response message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Cash register closed successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `cashRegisterId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Cash Registers", "slug": "electronic-cash-register-fetch-cash-registers", "description": "Retrieve all cash registers associated with a merchant. This API is useful for verifying registered cash registers and fetching their details.", "api": "Electronic Cash Register (ECR) V2 API", "method": "GET", "path": "/merchants/:merchantId/cash-register", "content": "# Fetch Cash Registers\n\n## Overview\nRetrieve all cash registers associated with a merchant. This API is useful for verifying registered cash registers and fetching their details.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/cash-register\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/cash-register\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `array` | Array of cash register objects. |\n|     `cashRegisterId` | `string` | Unique identifier of the cash register. |\n|     `storeId` | `string` | Store identifier. |\n|     `terminalId` | `string` | Associated terminal (may be null if not yet assigned). |\n|     `merchantId` | `string` | Merchant identifier. |\n|     `cashRegisterName` | `string` | Name of the cash register. |\n| `message` | `string` | Response message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"cashRegisterId\": \"{{cashRegisterId}}\",\n \"storeId\": \"{{storeId}}\",\n \"terminalId\": \"{{terminalId}}\",\n \"merchantId\": \"{{merchantId}}\",\n \"cashRegisterName\": \"Main Register\"\n }\n ],\n \"message\": \"Cash registers fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Cash Register by ID", "slug": "electronic-cash-register-get-cash-register-by-id", "description": "Retrieve the full cash-register record, including its control-unit details, identified by the :cashRegisterId path parameter.", "api": "Electronic Cash Register (ECR) V2 API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId", "content": "# Get Cash Register by ID\n\n## Overview\nRetrieve the full cash-register record, including its control-unit details, identified by the :cashRegisterId path parameter.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `cashRegisterId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `cashRegisterId` | `string` | Cash register identifier. |\n|     `cashRegisterName` | `string` | Name of the cash register. |\n|     `activationDate` | `string` | Date the cash register was activated. |\n|     `closingTime` | `string` | Configured automatic closing time for the register. |\n|     `designation` | `string` | Designation of the cash register. |\n|     `modelOrProgram` | `string` | Model or program of the cash register. |\n|     `address` | `string` | Address associated with the cash register. |\n|     `email` | `array` | Email addresses configured to receive this register's reports. |\n|     `controlUnitAddress` | `string` | Address of the paired fiscal control unit. |\n|     `controlUnitManufacturer` | `string` | Manufacturer of the control unit. |\n|     `controlUnitType` | `string` | Type of the control unit. |\n|     `controlUnitModel` | `string` | Model of the control unit. |\n|     `controlUnitSerialNumber` | `string` | Serial number of the paired fiscal control unit. |\n|     `notifications` | `array` | Per-email notification subscriptions. |\n|         `email` | `string` | Email address subscribed to the notification. |\n|         `reports` | `array` | Report types this email receives. |\n| `message` | `string` | Response message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"cashRegisterId\": \"{{cashRegisterId}}\",\n \"cashRegisterName\": \"Main Register\",\n \"activationDate\": \"2026-04-15\",\n \"closingTime\": \"23:00\",\n \"designation\": \"Register 1\",\n \"modelOrProgram\": \"Surfboard ECR 1.0\",\n \"address\": \"Main Street 1, Stockholm\",\n \"email\": [\n \"store.manager@example.com\"\n ],\n \"controlUnitAddress\": \"Main Street 1, Stockholm\",\n \"controlUnitManufacturer\": \"Surfboard\",\n \"controlUnitType\": \"SOFTWARE\",\n \"controlUnitModel\": \"CU-100\",\n \"controlUnitSerialNumber\": \"{{controlUnitSerialNumber}}\",\n \"notifications\": [\n {\n \"email\": \"store.manager@example.com\",\n \"reports\": [\n \"Z_REPORT\"\n ]\n }\n ]\n },\n \"message\": \"Fetched cash register successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `cashRegisterId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Cash Register Files", "slug": "electronic-cash-register-get-cash-register-files", "description": "Retrieve the files generated for a cash register, identified by the :cashRegisterId path parameter.", "api": "Electronic Cash Register (ECR) V2 API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/files", "content": "# Get Cash Register Files\n\n## Overview\nRetrieve the files/reports generated for a cash register, identified by the :cashRegisterId path parameter.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `cashRegisterId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/files\n```\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `reportType` | `string` | No | Filters files to a specific report type; applied only when present. |\n| `startDate` | `string` | No | Start of the date range to filter files by; applied only when present. |\n| `endDate` | `string` | No | End of the date range to filter files by; applied only when present. |\n\n### Pagination\n\nUse `reportType` to filter by report type and `startDate`/`endDate` to filter by date range; each is applied only when present.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/files?reportType=value&startDate=value&endDate=value\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `array` | Array of cash register file objects. |\n|     `fileName` | `string` | Name of the file. |\n|     `fileType` | `string` | Type of the file. |\n|     `reportType` | `string` | Report type the file belongs to. |\n|     `sequence` | `number` | Ordinal sequence number of the file within its report type. |\n|     `fileUrl` | `string` | Download URL for the file. |\n| `message` | `string` | Response message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"fileName\": \"z-report-2026-04-15.pdf\",\n \"fileType\": \"application/pdf\",\n \"reportType\": \"Z_REPORT\",\n \"sequence\": 1,\n \"fileUrl\": \"https://files.example.com/z-report-2026-04-15.pdf\"\n }\n ],\n \"message\": \"Cash register files fetched successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `cashRegisterId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Query Parameters for the supported paging parameters.\n\n---" }, { "title": "Get Cash Register State", "slug": "electronic-cash-register-get-cash-register-state", "description": "Retrieve the current state of a cash register, including its active shift, identified by the :cashRegisterId path parameter.", "api": "Electronic Cash Register (ECR) V2 API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/state-info", "content": "# Get Cash Register State\n\n## Overview\nRetrieve the current state of a cash register, including its active shift, identified by the :cashRegisterId path parameter.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `cashRegisterId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/state-info\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/state-info\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `cashRegisterState` | `string` | Current lifecycle state of the cash register. |\n|     `cashRegisterId` | `string` | Cash register identifier. |\n|     `cashRegisterName` | `string` | Name of the cash register. |\n|     `currencyCode` | `string` | Currency in which the register operates. |\n|     `shiftInfo` | `object` | Current or most recent shift information. |\n|         `shiftNumber` | `number` | Shift number. |\n|         `shiftState` | `string` | Current state of the shift. |\n|         `cashierName` | `string` | Name of the cashier. |\n|         `shiftOpenedAt` | `string` | Timestamp when the shift started. |\n|         `shiftClosedAt` | `string` | Timestamp when the shift was closed. |\n|     `pettyCash` | `number` | Current petty-cash balance held in the register. |\n|     `openedAt` | `string` | Timestamp when the register was opened. |\n|     `closedAt` | `string` | Timestamp when the register was closed. |\n| `message` | `string` | Response message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"cashRegisterState\": \"CASH_REGISTER_OPEN\",\n \"cashRegisterId\": \"{{cashRegisterId}}\",\n \"cashRegisterName\": \"Main Register\",\n \"currencyCode\": \"SEK\",\n \"shiftInfo\": {\n \"shiftNumber\": 1,\n \"shiftState\": \"SHIFT_OPEN\",\n \"cashierName\": \"John Doe\",\n \"shiftOpenedAt\": \"2026-04-15T12:00:00Z\",\n \"shiftClosedAt\": null\n },\n \"pettyCash\": 5000,\n \"openedAt\": \"2026-04-15T08:00:00Z\",\n \"closedAt\": null\n },\n \"message\": \"Fetched cash register state successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `cashRegisterId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Open-Shift", "slug": "electronic-cash-register-open-shift", "description": "Open a cashier shift on the cash register identified by the :cashRegisterId path parameter.", "api": "Electronic Cash Register (ECR) V2 API", "method": "PUT", "path": "/merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/open-shift", "content": "# Open-Shift\n\n## Overview\nOpen a cashier shift on the cash register identified by the :cashRegisterId path parameter.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `cashRegisterId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/open-shift\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | Yes | Terminal / device identifier opening the shift. |\n| `pettyCash` | `number` | Yes | Opening petty-cash float for the shift. |\n| `cashierName` | `string` | No | Name of the cashier opening the shift. |\n\n### Request Example\n```json\n{\n \"terminalId\": \"{{terminalId}}\",\n \"pettyCash\": 5000,\n \"cashierName\": \"John Doe\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Opened shift details. |\n| `message` | `string` | Response message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {},\n \"message\": \"Shift opened successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `cashRegisterId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Scheduled Close Time", "slug": "electronic-cash-register-update-scheduled-close-time", "description": "Update the automatic closing time for a cash register. Sending a closing time sets the shift close type to CUSTOM. The register is identified by the :cashRegisterId path parameter.", "api": "Electronic Cash Register (ECR) V2 API", "method": "PATCH", "path": "/merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/closing-time", "content": "# Update Scheduled Close Time\n\n## Overview\nUpdate the scheduled close time for a cash-register. Sending a closing time sets the shift close type to CUSTOM, the default is 00:00 local time. The register is identified by the :cashRegisterId path parameter.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `cashRegisterId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /merchants/:merchantId/stores/:storeId/cash-register/:cashRegisterId/closing-time\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `closingTime` | `string` | Yes | New automatic closing time; sending it sets the shift close type to CUSTOM. |\n\n### Request Example\n```json\n{\n \"closingTime\": \"23:00\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | Response data. |\n|     `cashRegisterId` | `string` | Cash register identifier. |\n|     `newClosingTime` | `string` | Closing time now configured for the register. |\n|     `shiftCloseType` | `string` | Close type that was applied (CUSTOM). |\n|     `scheduledClosingTime` | `string` | Next scheduled automatic close, when applicable. |\n| `message` | `string` | Response message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"cashRegisterId\": \"{{cashRegisterId}}\",\n \"newClosingTime\": \"23:00\",\n \"shiftCloseType\": \"CUSTOM\",\n \"scheduledClosingTime\": \"2026-04-16T23:00:00Z\"\n },\n \"message\": \"Cash register closing time updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `cashRegisterId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Withdraw Cash", "slug": "electronic-cash-register-withdraw-cash", "description": "Record a cash withdrawal taken out of the cash register during an active shift.", "api": "Electronic Cash Register (ECR) V2 API", "method": "PUT", "path": "/merchants/:merchantId/stores/:storeId/cash-register/withdraw", "content": "# Withdraw Cash\n\n## Overview\nRecord a cash withdrawal taken out of the cash register during an active shift.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /merchants/:merchantId/stores/:storeId/cash-register/withdraw\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `amount` | `number` | Yes | Amount to withdraw. |\n| `terminalId` | `string` | Yes | Terminal / device identifier. |\n\n### Request Example\n```json\n{\n \"amount\": 500,\n \"terminalId\": \"{{terminalId}}\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | Response message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Cash withdrawn successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Change Merchant for Terminal", "slug": "logistics-change-merchant-for-terminal", "description": "Reassigns an already-shipped terminal to a different merchant. Use this when a device needs to be moved from one merchant to another, for example when hardware is redeployed across your merchant portfolio.", "api": "Logistics API", "method": "POST", "path": "/partners/:partnerId/change-merchant", "content": "# Change Merchant for Terminal\n\n## Overview\nReassigns an already-shipped terminal to a different merchant. Use this when a device needs to be moved from one merchant to another, for example when hardware is redeployed across your merchant portfolio.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/change-merchant\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `serialNo` | `string` | Yes | Serial number of the terminal to reassign. |\n| `targetMerchantId` | `string` | Yes | Identifier of the merchant the terminal should be reassigned to. |\n\n### Request Example\n```json\n{\n \"serialNo\": \"TERM001234567\",\n \"targetMerchantId\": \"m_iWGri3XAyTmkbKYsYtV47\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Merchant changed for terminal successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to change merchant for the terminal\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "List Manufactured Hardware", "slug": "logistics-list-manufactured-hardware", "description": "Retrieves the terminals and devices Surfboard has manufactured for a partner, together with their hardware, network, and software details. Narrow the results by serial number, terminal, device model or vendor, or the merchant a device is assigned to, and sort the list to build inventory reports or reconcile your device fleet.", "api": "Logistics API", "method": "GET", "path": "/partners/:partnerId/manufactured-hardware", "content": "# List Manufactured Hardware\n\n## Overview\nRetrieves the terminals and devices Surfboard has manufactured for a partner, together with their hardware, network, and software details. Narrow the results by serial number, terminal, device model or vendor, or the merchant a device is assigned to, and sort the list to build inventory reports or reconcile your device fleet.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/manufactured-hardware\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `serialNo` | `string` | No | Return only the device with this hardware serial number. |\n| `terminalId` | `string` | No | Return only the device provisioned as this terminal. |\n| `deviceModel` | `string` | No | Return only devices of this model, for example Surfpad. |\n| `deviceVendor` | `string` | No | Return only devices from this hardware vendor. |\n| `merchantId` | `string` | No | Return only devices currently assigned to this merchant. |\n| `sortBy` | `string` | No | The field to order the results by. Possible values: `createdAt`, `serialNo`, `status`. |\n| `sortOrder` | `string` | No | The direction to sort the results in. Possible values: `ASC`, `DESC`. |\n\n### Pagination\n\nPage through results with the `x-page-number` request header. The total number of matching devices is returned in the `x-total-items` response header.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/manufactured-hardware?serialNo=TERM001234567&terminalId=816a0ff6bc0fb00404&deviceModel=Surfpad&deviceVendor=Sunmi&merchantId=m_iWGri3XAyTmkbKYsYtV47&sortBy=createdAt&sortOrder=DESC\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The manufactured devices on the current page. |\n|     `serialNo` | `string` | Hardware serial number of the device. |\n|     `cpuSerialNumber` | `string` | Serial number of the device's CPU. |\n|     `deviceSerialNumber` | `string` | Manufacturer's device serial number. |\n|     `terminalId` | `string` | Identifier of the terminal this device was provisioned as, once activated. |\n|     `merchantId` | `string` | Identifier of the merchant the device is currently assigned to. |\n|     `deviceModel` | `string` | Model of the device, for example Surfpad. |\n|     `deviceVendor` | `string` | Hardware vendor that manufactured the device. |\n|     `osType` | `string` | Operating system running on the device. |\n|     `osVersion` | `string` | Operating system version installed on the device. |\n|     `adminVersion` | `string` | Version of the Surfboard admin application installed on the device. |\n|     `pinpadVersion` | `string` | Version of the PIN pad firmware installed on the device. |\n|     `softwareVersion` | `string` | Version of the payment software installed on the device. |\n|     `imeiNumber` | `string` | IMEI number of the device's cellular modem. |\n|     `imsiNumber` | `string` | IMSI number of the SIM provisioned in the device. |\n|     `uiccid` | `string` | ICCID of the SIM card provisioned in the device. |\n|     `status` | `string` | Current lifecycle status of the device, for example whether it has been manufactured, shipped, or activated. |\n|     `lastOperation` | `string` | The most recent operation performed on the device. |\n|     `manufacturedFor` | `string` | Identifier of the partner the device was manufactured for. |\n|     `shippedTo` | `string` | Identifier of the merchant or destination the device was shipped to. |\n|     `createdAt` | `string` | When the device record was created, in ISO 8601 format. |\n|     `startDate` | `string` | Start of the device's active service period. |\n|     `endDate` | `string` | End of the device's active service period. |\n|     `createdBy` | `string` | Identifier of the user or system that created the device record. |\n|     `createdFrom` | `string` | The source or channel the device record was created from. |\n|     `updatedAt` | `string` | When the device record was last updated, in ISO 8601 format. |\n|     `updatedBy` | `string` | Identifier of the user or system that last updated the device record. |\n|     `updatedFrom` | `string` | The source or channel the device record was last updated from. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"serialNo\": \"TERM001234567\",\n \"cpuSerialNumber\": \"CPU-8841207\",\n \"deviceSerialNumber\": \"DSN-55120983\",\n \"terminalId\": \"816a0ff6bc0fb00404\",\n \"merchantId\": \"m_iWGri3XAyTmkbKYsYtV47\",\n \"deviceModel\": \"Surfpad\",\n \"deviceVendor\": \"Sunmi\",\n \"osType\": \"Android\",\n \"osVersion\": \"11\",\n \"adminVersion\": \"3.4.1\",\n \"pinpadVersion\": \"1.2.0\",\n \"softwareVersion\": \"5.8.2\",\n \"imeiNumber\": \"356938035643809\",\n \"imsiNumber\": \"240080012345678\",\n \"uiccid\": \"8946071512345678901\",\n \"status\": \"SHIPPED\",\n \"manufacturedFor\": \"8113d3f8403b380409\",\n \"shippedTo\": \"m_iWGri3XAyTmkbKYsYtV47\",\n \"createdAt\": \"2026-06-01T09:24:11.000Z\",\n \"startDate\": \"2026-06-02\",\n \"endDate\": \"2027-06-02\"\n }\n ],\n \"message\": \"Manufactured hardware fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch manufactured hardware\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Ship Manufactured Hardware", "slug": "logistics-ship-manufactured-hardware", "description": "Activates and ships a manufactured device to a specific merchant. Provide the device's serial number and the target merchant is taken from the path to hand the terminal over to that merchant.", "api": "Logistics API", "method": "POST", "path": "/partners/:partnerId/merchants/:merchantId/ship-hardware", "content": "# Ship Manufactured Hardware\n\n## Overview\nActivates and ships a manufactured device to a specific merchant. Provide the device's serial number and the target merchant is taken from the path to hand the terminal over to that merchant.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/merchants/:merchantId/ship-hardware\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `serialNo` | `string` | Yes | Serial number of the manufactured device to ship and activate for the merchant. |\n\n### Request Example\n```json\n{\n \"serialNo\": \"TERM001234567\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Manufactured hardware shipped successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to ship the terminal\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Merchant Account", "slug": "merchants-create-merchant-account", "description": "Invite a new user to the merchant by initiating a sign-up. Surfboard sends the user an activation email; only the email address is required, with an optional role and name.", "api": "Merchants API", "method": "POST", "path": "/merchants/:merchantId/accounts", "content": "# Create Merchant Account\n\n## Overview\nInvite a new user to the merchant by initiating a sign-up. Surfboard sends the user an activation email; only the email address is required, with an optional role and name.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /merchants/:merchantId/accounts\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `email` | `string` | Yes | Email address of the user account being created. An activation invitation is sent to this address. |\n| `role` | `string` | No | Role to assign to the new user account. |\n| `firstName` | `string` | No | First name of the user. |\n| `lastName` | `string` | No | Last name of the user. |\n\n### Request Example\n```json\n{\n \"email\": \"newuser@surfboard.se\",\n \"role\": \"CASHIER\",\n \"firstName\": \"Amanda\",\n \"lastName\": \"Berg\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request 'SUCCESS' \\| 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Account creation initiated successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Account creation failed for merchant.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Application Signing Links", "slug": "merchants-fetch-application-signing-links", "description": "Retrieve the signing links generated for a merchant application, so the merchant signatories and ultimate beneficial owners (UBOs) can each sign the application. Each entry includes the signer and the link to complete their signature.", "api": "Merchants API", "method": "GET", "path": "/partners/:partnerId/applications/:applicationId/signing-links", "content": "# Fetch Application Signing Links\n\n## Overview\nRetrieve the signing links generated for a merchant application, so the merchant signatories and ultimate beneficial owners (UBOs) can each sign the application. Each entry includes the signer and the link to complete their signature.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `applicationId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/applications/:applicationId/signing-links\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `applicationId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/applications/:applicationId/signing-links\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The signing links for the application. Null when no signing sessions exist. |\n|     `type` | `string` | The kind of signing session, for example the signer category. |\n|     `linkId` | `string` | Unique identifier of the signing link. |\n|     `url` | `string` | The URL the signer opens to complete their signature. |\n|     `data` | `array` | The people associated with this signing link. Null when none are attached. |\n|         `name` | `string` | Name of the person who needs to sign. |\n|         `emailId` | `string` | Email address of the person who needs to sign. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"type\": \"SIGNATORY\",\n \"linkId\": \"lnk_81409507c1a5f00110\",\n \"url\": \"https://surfkyb.com/sign/lnk_81409507c1a5f00110\",\n \"data\": [\n {\n \"name\": \"Jane Doe\",\n \"emailId\": \"jane.doe@surfboard.se\"\n }\n ]\n }\n ],\n \"message\": \"Decoupled session fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to fetch decoupled session\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `applicationId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Merchant Users", "slug": "merchants-fetch-merchant-users", "description": "Retrieve the list of user accounts that have access to the authenticated merchant. Use this to review who can operate the merchant's terminals and back-office tools.", "api": "Merchants API", "method": "GET", "path": "/merchants/:merchantId/users", "content": "# Fetch Merchant Users\n\n## Overview\nRetrieve the list of user accounts that have access to the authenticated merchant. Use this to review who can operate the merchant's terminals and back-office tools.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/users\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/users\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The user accounts associated with the merchant. |\n|     `userId` | `string` | Unique identifier of the user account. |\n|     `email` | `string` | Email address of the user. |\n|     `firstName` | `string` | First name of the user. |\n|     `lastName` | `string` | Last name of the user. |\n|     `role` | `string` | Role assigned to the user within the merchant. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"userId\": \"81412e2e4102f80f0e\",\n \"email\": \"owner@surfboard.se\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"role\": \"ADMIN\"\n }\n ],\n \"message\": \"Fetched users for merchant successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch users for merchant\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Merchant Service Providers", "slug": "merchants-fetch-merchant-service-providers", "description": "Retrieve the service providers configured for the authenticated merchant, including their identifiers, contact details, and address. Service providers are third parties that receive a share of the merchant's transaction fees.", "api": "Merchants API", "method": "GET", "path": "/merchants/:merchantId/service-providers", "content": "# Fetch Merchant Service Providers\n\n## Overview\nRetrieve the service providers configured for the authenticated merchant, including their identifiers, contact details, and address. Service providers are third parties that receive a share of the merchant's transaction fees.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/service-providers\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/service-providers\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The service providers configured for the merchant. |\n|     `serviceProviders` | `array` | List of service providers. |\n|         `serviceProviderId` | `string` | Unique identifier of the service provider. |\n|         `personId` | `string` | Identifier of the person associated with the service provider. |\n|         `corporateId` | `string` | Corporate identifier of the service provider. |\n|         `nationalId` | `string` | National identifier of the service provider. |\n|         `name` | `string` | Name of the service provider. |\n|         `address` | `object` | Address of the service provider. Can be null. |\n|             `addressLine1` | `string` | First line of the service provider address. |\n|             `city` | `string` | City of the service provider. |\n|             `countryCode` | `string` | Two-letter ISO country code, in uppercase, of the service provider. |\n|             `postalCode` | `string` | Postal code of the service provider. |\n|         `phoneNumber` | `object` | Contact number of the service provider. Can be null. |\n|             `number` | `string` | Phone number of the service provider. |\n|             `code` | `string` | International dialing code of the phone number. |\n|             `role` | `string` | Role associated with the phone number. |\n|         `email` | `string` | Email address of the service provider. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"serviceProviders\": [\n {\n \"serviceProviderId\": \"sp_81412e3c3b1090060f\",\n \"personId\": \"pn_5f2c1a9b3d\",\n \"corporateId\": \"5591631360\",\n \"nationalId\": \"199001011234\",\n \"name\": \"Nordic Accounting AB\",\n \"address\": {\n \"addressLine1\": \"Main Street 123\",\n \"city\": \"Stockholm\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"12345\"\n },\n \"phoneNumber\": {\n \"number\": \"812345678\",\n \"code\": \"46\",\n \"role\": \"PRIMARY\"\n },\n \"email\": \"billing@nordicaccounting.se\"\n }\n ]\n },\n \"message\": \"Service providers fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch service providers\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Multi-merchant Group", "slug": "merchants-fetch-multi-merchant-group", "description": "Retrieve the merchants that belong to a single multi-merchant group. A multi-merchant group lets several merchants share the same terminals; this endpoint returns each member merchant of the given group.", "api": "Merchants API", "method": "GET", "path": "/partners/:partnerId/multi-merchants/:merchantId", "content": "# Fetch Multi-merchant Group\n\n## Overview\nRetrieve the merchants that belong to a single multi-merchant group. A multi-merchant group lets several merchants share the same terminals; this endpoint returns each member merchant of the given group.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/multi-merchants/:merchantId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Pagination\n\nPage through results with the `x-page-number` request header. The total number of member merchants is returned in the `x-total-items` response header.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/multi-merchants/:merchantId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The merchants that belong to the multi-merchant group. |\n|     `merchantId` | `string` | Unique identifier of the member merchant. |\n|     `merchantName` | `string` | Name of the member merchant. |\n|     `countryCode` | `string` | Two-letter ISO country code, in uppercase, of the member merchant. |\n|     `currencyCode` | `string` | Three-digit ISO currency code of the member merchant, returned when the merchant has a payment-facilitator account. |\n|     `acquirerMID` | `string` | Acquirer Merchant ID of the member merchant, returned when the merchant has a payment-facilitator account. |\n|     `partnerId` | `string` | Identifier of the partner that owns the merchant. |\n|     `merchantLanguage` | `string` | Default language configured for the merchant. |\n|     `merchantLogoUrl` | `string` | URL of the merchant's logo. |\n|     `email` | `string` | Contact email for the merchant. |\n|     `companyId` | `string` | Company registration (organization) number of the merchant. |\n|     `mccCode` | `string` | Merchant category code (MCC) for the merchant. |\n|     `createdAt` | `string` | When the merchant was created, in ISO 8601 format. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"merchantId\": \"817544960dd838040e\",\n \"merchantName\": \"Test Merchant one\",\n \"countryCode\": \"SE\",\n \"currencyCode\": \"752\",\n \"acquirerMID\": \"gfprLY1dyAQO\"\n },\n {\n \"merchantId\": \"8175449a8dd8380d0e\",\n \"merchantName\": \"Test Merchant two\",\n \"countryCode\": \"SE\"\n }\n ],\n \"message\": \"Successfully fetched merchants details\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"No merchants found under this multi merchant group\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Fetch Renewal Application", "slug": "merchants-fetch-renewal-application", "description": "Retrieve the merchant's most recent active renewal application, including its status and the KYB continuation link. Returns null when the merchant has no active renewal in progress.", "api": "Merchants API", "method": "GET", "path": "/merchants/:merchantId/renewal-application", "content": "# Fetch Renewal Application\n\n## Overview\nRetrieve the merchant's most recent active renewal application, including its status and the KYB continuation link. Returns null when the merchant has no active renewal in progress.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/renewal-application\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/renewal-application\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The latest active renewal application, or null when none exists. |\n|     `applicationId` | `string` | Identifier of the renewal application. |\n|     `applicationStatus` | `string` | Current status of the renewal application. |\n|     `endDate` | `string` | Date on which the renewal application period ends. |\n|     `createdAt` | `string` | Timestamp at which the renewal application was created. |\n|     `webKybUrl` | `string` | KYB continuation link for the renewal, when available. Can be null. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"applicationId\": \"81409507c1a5f00110\",\n \"applicationStatus\": \"APPLICATION_INITIATED\",\n \"endDate\": \"2026-12-31T00:00:00.000Z\",\n \"createdAt\": \"2026-06-01T09:24:11.000Z\",\n \"webKybUrl\": \"https://surfkyb.com/81409507c1a5f00110\"\n },\n \"message\": \"Fetched latest active renewal application successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch latest active renewal application\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Merchant Configuration", "slug": "merchants-update-merchant-configuration", "description": "Update the merchant's operational configuration, such as terminal display options, settlement behavior, and the default receipt template. Only the fields you send are updated.", "api": "Merchants API", "method": "PATCH", "path": "/merchants/:merchantId/configuration", "content": "# Update Merchant Configuration\n\n## Overview\nUpdate the merchant's operational configuration, such as terminal display options, settlement behavior, and the default receipt template. Only the fields you send are updated.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /merchants/:merchantId/configuration\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `showTodaySalesAggregate` | `boolean` | No | Show today's aggregated sales total on the merchant's terminals. |\n| `showProductCatalogue` | `boolean` | No | Show the product catalog on the terminal. |\n| `showExitButton` | `boolean` | No | Show the exit button on the terminal payment app. |\n| `showTransactions` | `boolean` | No | Show the transaction history on the terminal. |\n| `settlementFrequency` | `string` | No | How often the merchant is settled. Possible values: `DAILY`, `WEEKLY`, `MONTHLY`. |\n| `grossSettlement` | `boolean` | No | Settle gross amounts, with fees invoiced separately, instead of net settlement. |\n| `enableProductCreation` | `boolean` | No | Allow the merchant to create products from the terminal. |\n| `terminalReceiptTemplateId` | `string` | No | Identifier of the receipt template to use on the merchant terminals. |\n\n### Request Example\n```json\n{\n \"showTodaySalesAggregate\": true,\n \"showProductCatalogue\": false,\n \"settlementFrequency\": \"DAILY\",\n \"grossSettlement\": false\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request 'SUCCESS' \\| 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Configurations added successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to add configurations\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Merchant", "slug": "merchants-fetch-merchant", "description": "Retrieve the profile and lifetime transaction summary for the authenticated merchant, including contact details, address, and current/previous-month sales analytics. Use this to display merchant information in your own dashboards.", "api": "Merchants API", "method": "GET", "path": "/merchants/:merchantId", "content": "# Fetch Merchant\n\n## Overview\nRetrieve the profile and lifetime transaction summary for the authenticated merchant, including contact details, address, and current/previous-month sales analytics. Use this to display merchant information in your own dashboards.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The merchant profile and transaction summary. |\n|     `merchantId` | `string` | Unique identifier of the merchant. |\n|     `merchantType` | `string` | Classification of the merchant account within Surfboard. Possible values: `STANDARD`, `DYNAMIC_MERCHANT`, `MARKETPLACE_MERCHANT`, `PF_MERCHANT`, `PF_TEST_MERCHANT`, `PARTNER_MERCHANT`, `TEST_MERCHANT`, `DEACTIVATED_MERCHANT`, `ISV_MERCHANT`, `BLOCKED_MERCHANT`. |\n|     `partnerId` | `string` | Identifier of the partner the merchant is affiliated with. |\n|     `merchantName` | `string` | Name of the merchant. |\n|     `merchantLanguage` | `string` | Preferred language selected by the merchant. |\n|     `merchantLogoUrl` | `string` | URL of the merchant logo. |\n|     `email` | `string` | Email address of the merchant. |\n|     `companyId` | `string` | Company (corporate) identifier of the merchant. |\n|     `countryCode` | `string` | Two-letter ISO country code, in uppercase, of the merchant. |\n|     `mccCode` | `string` | Merchant Category Code (MCC) of the merchant. |\n|     `createdAt` | `string` | Timestamp at which the merchant was created. |\n|     `totalNumberOfTransaction` | `string` | Total number of transactions performed by the merchant. |\n|     `totalAmountOfTransaction` | `string` | Total monetary value of all transactions performed by the merchant, in the smallest currency unit. |\n|     `lastTransactionAt` | `string` | Timestamp of the merchant's most recent transaction, in ISO 8601 format. |\n|     `phoneNumber` | `string` | Contact phone number of the merchant. |\n|     `totalSales` | `string` | Total value of sales transactions for the merchant, in the smallest currency unit. |\n|     `totalRefunds` | `string` | Total value of refunded transactions for the merchant, in the smallest currency unit. |\n|     `currencyCode` | `string` | Three-digit ISO currency code of the merchant's settlement currency, e.g. '752' for SEK. |\n|     `acquirerMID` | `string` | Acquirer Merchant ID assigned when the merchant is onboarded through a payment facilitator or acquirer. |\n|     `address` | `object` | Physical address of the merchant. |\n|         `careOf` | `string` | Name of the addressee accepting correspondence on behalf of the merchant. |\n|         `addressLine1` | `string` | First line of the merchant address. |\n|         `addressLine2` | `string` | Second line of the merchant address. |\n|         `addressLine3` | `string` | Third line of the merchant address. |\n|         `city` | `string` | City where the merchant is located. |\n|         `countryCode` | `string` | Two-letter ISO country code, in uppercase, of the merchant address. |\n|         `postalCode` | `string` | Postal code of the merchant address. |\n|     `analytics` | `object` | Aggregated sales and refund counts for the current and previous month. |\n|         `countOfSales` | `number` | Total number of sales transactions recorded for the merchant. |\n|         `countOfRefunds` | `number` | Total number of refund transactions recorded for the merchant. |\n|         `currentMonthSale` | `number` | Value of sales in the current month, in the smallest currency unit. |\n|         `previousMonthSale` | `number` | Value of sales in the previous month, in the smallest currency unit. |\n|         `currentMonthCountOfSale` | `number` | Number of sales in the current month. |\n|         `previousMonthCountOfSale` | `number` | Number of sales in the previous month. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"merchantId\": \"81fa6b2d8d5dc8040e\",\n \"merchantType\": \"STANDARD\",\n \"partnerId\": \"8113d3f8403b380409\",\n \"merchantName\": \"Conroy Hane and Parker\",\n \"merchantLanguage\": \"sv\",\n \"merchantLogoUrl\": \"https://storage.googleapis.com/logo.png\",\n \"email\": \"contact@surfboard.se\",\n \"companyId\": \"5590520507\",\n \"countryCode\": \"SE\",\n \"mccCode\": \"5812\",\n \"createdAt\": \"2024-06-06T06:03:49.125Z\",\n \"totalNumberOfTransaction\": \"1877\",\n \"totalAmountOfTransaction\": \"774628102\",\n \"lastTransactionAt\": \"2024-07-15T09:23:09.816Z\",\n \"phoneNumber\": \"46812345678\",\n \"totalSales\": \"774628102\",\n \"totalRefunds\": \"12000\",\n \"currencyCode\": \"752\",\n \"acquirerMID\": \"gfprLY1dyAQO\",\n \"address\": {\n \"careOf\": \"John Doe\",\n \"addressLine1\": \"Main Street 123\",\n \"city\": \"Stockholm\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"12345\"\n },\n \"analytics\": {\n \"countOfSales\": 1850,\n \"countOfRefunds\": 27,\n \"currentMonthSale\": 45900,\n \"previousMonthSale\": 61200,\n \"currentMonthCountOfSale\": 120,\n \"previousMonthCountOfSale\": 158\n }\n },\n \"message\": \"Successfully fetched merchant details\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch merchant details\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Multi-merchant Group", "slug": "merchants-update-multi-merchant-group", "description": "Rename a multi-merchant group. Send the new name to update the group that the given multi-merchant ID refers to.", "api": "Merchants API", "method": "PUT", "path": "/partners/:partnerId/multi-merchants/:merchantId", "content": "# Update Multi-merchant Group\n\n## Overview\nRename a multi-merchant group. Send the new name to update the group that the given multi-merchant ID refers to.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /partners/:partnerId/multi-merchants/:merchantId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `multiMerchantName` | `string` | Yes | New name for the multi-merchant group. |\n\n### Request Example\n```json\n{\n \"multiMerchantName\": \"Nordic Retail Group\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request 'SUCCESS' \\| 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Update merchant details successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unhandled error occurred\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Customer Details", "slug": "orders-update-customer-details", "description": "Replaces the customer, billing and shipping contact details on an existing order. Use this API to set or correct who the order is for and where it is billed and shipped, identified by the Order ID in the URL.", "api": "Orders API", "method": "PUT", "path": "/orders/:orderId/customer", "content": "# Update Customer Details\n\n## Overview\nReplaces the customer, billing and shipping contact details on an existing order. Use this API to set or correct who the order is for and where it is billed and shipped, identified by the Order ID in the URL.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required using API Key, API Secret, and Merchant ID.\n- The resource identified by `orderId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /orders/:orderId/customer\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `customer` | `object` | No | Customer details for the order |\n|     `customerId` | `string` | No | Unique identifier for the customer |\n|     `person` | `object` | No | Personal information of the customer |\n|         `id` | `string` | No | Person identifier. |\n|         `name` | `object` | No | Full name of the customer |\n|             `firstName` | `string` | No | First name of the customer |\n|             `middleName` | `string` | No | Middle name of the customer |\n|             `lastName` | `string` | No | Last name of the customer |\n|         `email` | `string` | No | Email address of the customer |\n|         `phoneNumber` | `object` | No | Phone number of the customer |\n|             `code` | `string` | Yes | International dialing code (Eg., 46 for Sweden without '+') |\n|             `number` | `string` | Yes | National subscriber number (digits only) |\n|         `birthDate` | `string` | No | Date of birth in YYYY-MM-DD format |\n|         `personalNumber` | `string` | No | Personal identification number |\n|         `coordinationNumber` | `string` | No | Coordination number |\n|         `countryResidence` | `string` | No | Country of residence of the customer |\n|         `gdNumber` | `string` | No | Government-issued identification number of the customer |\n|     `company` | `object` | No | Company information for corporate purchases |\n|         `id` | `string` | No | Company identifier. |\n|         `vatId` | `string` | No | VAT ID of the company |\n|         `poDetails` | `string` | No | Purchase order details for the company |\n|         `companyName` | `string` | No | Company display name. |\n|         `registrationNumber` | `string` | No | Company registration number. |\n|         `gln` | `string` | No | GLN of the buyer's e-invoice department, used to route e-invoices. |\n| `billing` | `object` | No | Billing contact and address |\n|     `name` | `object` | No | Full name of the billing contact |\n|         `firstName` | `string` | No | First name of the billing contact |\n|         `middleName` | `string` | No | Middle name of the billing contact |\n|         `lastName` | `string` | No | Last name of the billing contact |\n|     `email` | `string` | No | Billing email |\n|     `phoneNumber` | `object` | No | Phone number for billing |\n|         `code` | `string` | Yes | International dialing code (Eg., 46 for Sweden without '+') |\n|         `number` | `string` | Yes | National subscriber number (digits only) |\n|     `address` | `object` | No | Billing address |\n|         `careOf` | `string` | No | Care of / attention |\n|         `addressLine1` | `string` | Yes | Primary address line |\n|         `addressLine2` | `string` | No | Address line 2 |\n|         `addressLine3` | `string` | No | Address line 3 |\n|         `city` | `string` | Yes | City name |\n|         `postalCode` | `string` | Yes | Postal/ZIP code |\n|         `countryCode` | `string` | Yes | Country code (ISO 3166-1 alpha-2) |\n| `shipping` | `object` | No | Shipping contact and address |\n|     `name` | `object` | No | Full name of the shipping contact |\n|         `firstName` | `string` | No | First name of the shipping contact |\n|         `middleName` | `string` | No | Middle name of the shipping contact |\n|         `lastName` | `string` | No | Last name of the shipping contact |\n|     `email` | `string` | No | Recipient email |\n|     `phoneNumber` | `object` | No | Phone number for shipping |\n|         `code` | `string` | Yes | International dialing code (Eg., 46 for Sweden without '+') |\n|         `number` | `string` | Yes | National subscriber number (digits only) |\n|     `address` | `object` | No | Shipping address |\n|         `careOf` | `string` | No | Care of / attention |\n|         `addressLine1` | `string` | Yes | Primary address line |\n|         `addressLine2` | `string` | No | Address line 2 |\n|         `addressLine3` | `string` | No | Address line 3 |\n|         `city` | `string` | Yes | City name |\n|         `postalCode` | `string` | Yes | Postal/ZIP code |\n|         `countryCode` | `string` | Yes | Country code (ISO 3166-1 alpha-2) |\n\n### Request Example\n```json\n{\n \"customer\": {\n \"customerId\": \"825a37d0aa1048120e\",\n \"person\": {\n \"name\": {\n \"firstName\": \"Tom\",\n \"middleName\": \"A\",\n \"lastName\": \"Andersson\"\n },\n \"email\": \"tom.andersson@example.com\",\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"701234567\"\n },\n \"birthDate\": \"1990-05-14\",\n \"personalNumber\": \"199005141234\",\n \"coordinationNumber\": \"199005741234\",\n \"countryResidence\": \"SE\",\n \"gdNumber\": \"GD123456\"\n },\n \"company\": {\n \"vatId\": \"SE556677889901\",\n \"poDetails\": \"PO-2024-0098\"\n }\n },\n \"billing\": {\n \"name\": {\n \"firstName\": \"Tom\",\n \"middleName\": \"A\",\n \"lastName\": \"Andersson\"\n },\n \"email\": \"tom.andersson@example.com\",\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"701234567\"\n },\n \"address\": {\n \"careOf\": \"c/o Reception\",\n \"addressLine1\": \"Storgatan 1\",\n \"addressLine2\": \"Floor 2\",\n \"addressLine3\": \"Door 4\",\n \"city\": \"Stockholm\",\n \"postalCode\": \"11122\",\n \"countryCode\": \"SE\"\n }\n },\n \"shipping\": {\n \"name\": {\n \"firstName\": \"Sam\",\n \"middleName\": \"A\",\n \"lastName\": \"Berg\"\n },\n \"email\": \"sam.berg@example.com\",\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"709876543\"\n },\n \"address\": {\n \"careOf\": \"c/o Reception\",\n \"addressLine1\": \"Kungsgatan 9\",\n \"addressLine2\": \"Floor 2\",\n \"addressLine3\": \"Door 4\",\n \"city\": \"Stockholm\",\n \"postalCode\": \"11122\",\n \"countryCode\": \"SE\"\n }\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Updated customer, billing and shipping details returned by the service. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {},\n \"message\": \"Customer details updated successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid order id\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Authentication failed\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY`, `API-SECRET`, and `MERCHANT-ID` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- The `orderId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Application Analytics", "slug": "partners-get-application-analytics", "description": "Retrieve aggregated merchant onboarding analytics for the partner, such as application counts by status, conversion and rejection rates, and merchants created. Filter by country, application type, or status group, choose a time frame, and group by dimensions like country or month for onboarding reporting.", "api": "Partners API", "method": "GET", "path": "/partners/:partnerId/partner-analytics", "content": "# Get Application Analytics\n\n## Overview\nRetrieve aggregated merchant onboarding analytics for the partner, such as application counts by status, conversion and rejection rates, and merchants created. Filter by country, application type, or status group, choose a time frame, and group by dimensions like country or month for onboarding reporting.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/partner-analytics\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier of the partner to fetch onboarding analytics for. Supplied in the URL path. |\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `timeFrame` | `string` | No | Preset time window to aggregate over. Use CUSTOM together with dateFrom and dateTo for an explicit range. Possible values: `LAST_24_HOURS`, `LAST_7_DAYS`, `LAST_30_DAYS`, `LAST_90_DAYS`, `LAST_6_MONTHS`, `LAST_12_MONTHS`, `MONTH_TO_DATE`, `QUARTER_TO_DATE`, `YEAR_TO_DATE`, `CUSTOM`. |\n| `dateFrom` | `string` | No | Start of a custom date range (ISO 8601). Used when timeFrame is CUSTOM. |\n| `dateTo` | `string` | No | End of a custom date range (ISO 8601). Used when timeFrame is CUSTOM. |\n| `groupBy` | `array` | No | One or more dimensions to group the results by. Possible values: `country`, `applicationType`, `statusGroup`, `day`, `week`, `month`, `quarter`, `year`. |\n| `filters[countries]` | `array` | No | Return only applications for these countries (ISO 3166-1 alpha-2 codes). |\n| `filters[applicationTypes]` | `array` | No | Return only applications of these types. Possible values: `ONBOARDING`, `RENEWAL`. |\n| `filters[statusGroup]` | `string` | No | Return only applications in this status group. Possible values: `IN_PROGRESS`, `COMPLETED`, `FAILED`, `UNDER_REVIEW`. |\n| `sortBy` | `string` | No | Field to sort the grouped rows by. Possible values: `totalApplications`, `totalCompleted`, `country`. |\n| `sortOrder` | `string` | No | Sort direction for the results. Possible values: `ASC`, `DESC`. |\n| `pageNumber` | `number` | No | Page of results to return. Overrides the x-page-number header when supplied. |\n| `itemsPerPage` | `number` | No | Number of rows to return per page. |\n\n### Pagination\n\nPage through results with the `x-page-number` request header. The total number of matching rows is returned in the `x-total-items` response header. List filters use bracket notation, for example `filters[countries]=SE&filters[countries]=NO`.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/partner-analytics?timeFrame=LAST_30_DAYS&groupBy=country&sortBy=totalApplications&sortOrder=DESC\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The aggregated onboarding analytics. |\n|     `applicationAnalyticsData` | `array` | The grouped analytics rows. |\n|         `country` | `string` | Country the row is grouped by. Present only when grouping by country. |\n|         `applicationType` | `string` | Application type the row is grouped by. Present only when grouping by application type. Possible values: `ONBOARDING`, `RENEWAL`. |\n|         `statusGroup` | `string` | Status group the row is grouped by. Present only when grouping by status group. Possible values: `IN_PROGRESS`, `COMPLETED`, `FAILED`, `UNDER_REVIEW`. |\n|         `timeSegment` | `string` | Time bucket the row is grouped by. Present only when grouping by a time dimension. |\n|         `totalApplications` | `number` | Total applications in this bucket. |\n|         `totalInitiated` | `number` | Applications initiated but not yet submitted in this bucket. |\n|         `totalExpired` | `number` | Applications that expired before completion in this bucket. |\n|         `totalSubmitted` | `number` | Applications submitted for review in this bucket. |\n|         `totalPending` | `number` | Applications awaiting further information in this bucket. |\n|         `totalSigned` | `number` | Applications signed in this bucket. |\n|         `totalRejected` | `number` | Applications rejected in this bucket. |\n|         `totalCompleted` | `number` | Applications that completed onboarding in this bucket. |\n|         `totalMerchantCreated` | `number` | Merchants created in this bucket. |\n|         `totalServiceProviderCreated` | `number` | Service providers created in this bucket. |\n|         `conversionRate` | `number` | Share of applications that completed onboarding, as a percentage. |\n|         `rejectionRate` | `number` | Share of applications that were rejected, as a percentage. |\n|         `expirationRate` | `number` | Share of applications that expired, as a percentage. |\n|     `totalCount` | `number` | Total number of grouped rows across all pages. |\n|     `pageNumber` | `number` | The page of results returned. |\n|     `itemsPerPage` | `number` | Number of rows returned per page. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"applicationAnalyticsData\": [\n {\n \"country\": \"SE\",\n \"totalApplications\": 84,\n \"totalInitiated\": 6,\n \"totalExpired\": 2,\n \"totalSubmitted\": 5,\n \"totalPending\": 3,\n \"totalSigned\": 9,\n \"totalRejected\": 1,\n \"totalCompleted\": 58,\n \"totalMerchantCreated\": 58,\n \"totalServiceProviderCreated\": 0,\n \"conversionRate\": 69.05,\n \"rejectionRate\": 1.19,\n \"expirationRate\": 2.38\n }\n ],\n \"totalCount\": 1,\n \"pageNumber\": 1,\n \"itemsPerPage\": 100\n },\n \"message\": \"Application analytics fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch application analytics.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Get Partner Config", "slug": "partners-get-partner-config", "description": "Retrieve the partner-level feature toggles that control how the partner portal and onboarding behave, such as whether terminals can be activated from the portal and whether the cash-register features are available.", "api": "Partners API", "method": "GET", "path": "/partners/:partnerId/config", "content": "# Get Partner Config\n\n## Overview\nRetrieve the partner-level feature toggles that control how the partner portal and onboarding behave, such as whether terminals can be activated from the portal and whether the cash-register features are available.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/config\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier of the partner to fetch configuration for. Supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/config\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The partner feature configuration. |\n|     `activateTerminalFromPortal` | `boolean` | Whether terminals can be activated directly from the partner portal. |\n|     `allowAdvancedOnboarding` | `boolean` | Whether the partner has access to the advanced onboarding flow. |\n|     `enableProductCatalogueInOnboarding` | `boolean` | Whether the product catalog step is shown during merchant onboarding. |\n|     `ecrEnabled` | `boolean` | Whether the partner has access to the cash-register (ECR) features in the portal. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"activateTerminalFromPortal\": true,\n \"allowAdvancedOnboarding\": false,\n \"enableProductCatalogueInOnboarding\": true,\n \"ecrEnabled\": false\n },\n \"message\": \"Partner config fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch partner config\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Partner Analytics", "slug": "partners-get-partner-analytics", "description": "Retrieve a high-level summary of the partner's onboarding and transaction activity, including application counts by status, merchants created, and transaction volumes and amounts across purchases and returns.", "api": "Partners API", "method": "GET", "path": "/partners/:partnerId/analytics", "content": "# Get Partner Analytics\n\n## Overview\nRetrieve a high-level summary of the partner's onboarding and transaction activity, including application counts by status, merchants created, and transaction volumes and amounts across purchases and returns.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/analytics\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier of the partner to fetch analytics for. Supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/analytics\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The partner activity summary. |\n|     `totalNumberOfApplication` | `number` | Total number of merchant applications created under the partner. |\n|     `totalNumberOfAppInitiated` | `number` | Number of applications that have been initiated but not yet submitted. |\n|     `totalNumberOfAppExpired` | `number` | Number of applications that expired before completion. |\n|     `totalNumberOfAppSubmitted` | `number` | Number of applications submitted for review. |\n|     `totalNumberOfAppPending` | `number` | Number of applications awaiting further information. |\n|     `totalNumberOfAppSigned` | `number` | Number of applications that have been signed. |\n|     `totalNumberOfAppRejected` | `number` | Number of applications that were rejected. |\n|     `totalNumberOfAppCompleted` | `number` | Number of applications that completed onboarding. |\n|     `totalNumberOfMerchantCreated` | `number` | Number of merchants created under the partner. |\n|     `totalNumberOfTransaction` | `number` | Total number of transactions across the partner's merchants. |\n|     `totalNumberOfPurchaseTransaction` | `number` | Number of purchase transactions across the partner's merchants. |\n|     `totalNumberReturnTransaction` | `number` | Number of return transactions across the partner's merchants. |\n|     `totalAmountOfTransaction` | `number` | Total value of all transactions, in the smallest unit of the currency (e.g. öre for SEK). |\n|     `totalAmountOfPurchaseTransaction` | `number` | Total value of purchase transactions, in the smallest currency unit. |\n|     `totalAmountOfReturnTransaction` | `number` | Total value of return transactions, in the smallest currency unit. |\n|     `recentActivityData` | `array` | Recent activity events for the partner, as an ordered list of key-value entries. |\n|         `event` | `string` | The type of activity that occurred. |\n|         `timestamp` | `string` | When the activity occurred, in ISO 8601 format. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"totalNumberOfApplication\": 128,\n \"totalNumberOfAppInitiated\": 12,\n \"totalNumberOfAppExpired\": 4,\n \"totalNumberOfAppSubmitted\": 9,\n \"totalNumberOfAppPending\": 6,\n \"totalNumberOfAppSigned\": 15,\n \"totalNumberOfAppRejected\": 3,\n \"totalNumberOfAppCompleted\": 79,\n \"totalNumberOfMerchantCreated\": 79,\n \"totalNumberOfTransaction\": 54210,\n \"totalNumberOfPurchaseTransaction\": 52890,\n \"totalNumberReturnTransaction\": 1320,\n \"totalAmountOfTransaction\": 812450000,\n \"totalAmountOfPurchaseTransaction\": 829100000,\n \"totalAmountOfReturnTransaction\": 16650000,\n \"recentActivityData\": [\n {\n \"event\": \"MERCHANT_CREATED\",\n \"timestamp\": \"2026-06-14T08:11:00.000Z\"\n }\n ]\n },\n \"message\": \"Partner details fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch partner details\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Partner Details", "slug": "partners-get-partner-details", "description": "Retrieve the core details of a partner account, including its onboarding URL, supported billing plans, enabled payment methods, and the acquirer configured for each country the partner operates in.", "api": "Partners API", "method": "GET", "path": "/partners/:partnerId", "content": "# Get Partner Details\n\n## Overview\nRetrieve the core details of a partner account, including its onboarding URL, supported billing plans, enabled payment methods, and the acquirer configured for each country the partner operates in.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier of the partner to fetch details for. Supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The partner account details. |\n|     `partnerId` | `string` | Unique identifier of the partner. |\n|     `webOnboardingUrl` | `string` | Hosted URL where the partner's merchants complete web-based onboarding. |\n|     `partnerName` | `string` | Display name of the partner. |\n|     `status` | `string` | Lifecycle status of the partner account, for example ACTIVE. |\n|     `supportedBillingPlans` | `array` | Billing plans the partner is allowed to assign to its merchants. |\n|     `partnerType` | `string` | Type of partner, which determines the onboarding and billing flow available to it. |\n|     `paymentMethods` | `array` | Payment methods enabled for the partner, for example CARD or SWISH. |\n|     `countryCode` | `string` | Primary country the partner is registered in (ISO 3166-1 alpha-2). |\n|     `acquirerConfig` | `array` | The acquirer used to process card payments, per operating country. |\n|         `country` | `string` | Country the acquirer applies to (ISO 3166-1 alpha-2). |\n|         `acquirer` | `string` | Name of the acquirer that settles card payments in this country. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"partnerId\": \"pt_9c31a0f4b2\",\n \"webOnboardingUrl\": \"https://onboarding.surfboard.se/pt_9c31a0f4b2\",\n \"partnerName\": \"Nordic Coffee Group\",\n \"status\": \"ACTIVE\",\n \"supportedBillingPlans\": [\n \"STANDARD\",\n \"PREMIUM\"\n ],\n \"partnerType\": \"RESELLER\",\n \"paymentMethods\": [\n \"CARD\",\n \"SWISH\"\n ],\n \"countryCode\": \"SE\",\n \"acquirerConfig\": [\n {\n \"country\": \"SE\",\n \"acquirer\": \"NEXI\"\n }\n ]\n },\n \"message\": \"Partner details fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch partner details\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Transaction Analytics", "slug": "partners-get-transaction-analytics", "description": "Retrieve aggregated transaction analytics across the partner's merchants. Narrow the results with filters such as store, terminal, payment method, card brand, or date range, and group the totals by one or more dimensions to build reporting dashboards.", "api": "Partners API", "method": "GET", "path": "/partners/:partnerId/transaction-analytics", "content": "# Get Transaction Analytics\n\n## Overview\nRetrieve aggregated transaction analytics across the partner's merchants. Narrow the results with filters such as store, terminal, payment method, card brand, or date range, and group the totals by one or more dimensions to build reporting dashboards.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/transaction-analytics\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier of the partner to fetch analytics for. Supplied in the URL path. |\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | No | Return only analytics for this merchant under the partner. |\n| `storeId` | `string` | No | Return only analytics for transactions at this store. |\n| `terminalId` | `string` | No | Return only analytics for transactions processed by this terminal. |\n| `startDate` | `string` | No | Start of the date range to aggregate over (ISO 8601, e.g. 2026-06-01). |\n| `endDate` | `string` | No | End of the date range to aggregate over (ISO 8601). |\n| `orderType` | `string` | No | Return only analytics for this order type. Possible values: `PURCHASE`, `RETURN`. |\n| `terminalType` | `string` | No | Return only analytics for this terminal type. |\n| `paymentMethod` | `string` | No | Return only analytics for this payment method, for example CARD or SWISH. |\n| `cardBrand` | `string` | No | Return only analytics for this card brand, for example VISA or MASTERCARD. |\n| `currency` | `string` | No | Return only analytics in this currency (ISO 4217 code). |\n| `includeRealtimeTransactions` | `boolean` | No | When true, includes transactions that have not yet settled in the aggregation. |\n\n### Pagination\n\nPage through results with the `x-page-number` request header. The total number of matching rows is returned in the `x-total-items` response header. Grouping is controlled with bracketed query keys, for example `groupBy[storeId]=true` or `groupBy[timeSegments]=DAILY`.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/transaction-analytics?startDate=2026-06-01&endDate=2026-06-30&storeId=st_2a91&paymentMethod=CARD&orderType=PURCHASE\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The aggregated analytics rows, one per grouping bucket. |\n|     `storeId` | `string` | Store the row is grouped by. Present only when grouping by store. |\n|     `terminalId` | `string` | Terminal the row is grouped by. Present only when grouping by terminal. |\n|     `orderType` | `string` | Order type the row is grouped by. Present only when grouping by order type. Possible values: `PURCHASE`, `RETURN`. |\n|     `terminalType` | `string` | Terminal type the row is grouped by. Present only when grouping by terminal type. |\n|     `orderTransactionCount` | `string` | Number of transactions in this grouping bucket. |\n|     `totalTransactionAmount` | `number` | Total transaction value for this bucket, in the smallest unit of the currency (e.g. öre for SEK). |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"storeId\": \"st_2a91\",\n \"orderType\": \"PURCHASE\",\n \"orderTransactionCount\": \"1204\",\n \"totalTransactionAmount\": 18942000\n }\n ],\n \"message\": \"Transaction analytics for partner fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch transaction analytics for partner.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Global Search", "slug": "partners-global-search", "description": "Run a free-text search across everything the partner owns — merchants, stores, terminals, applications, and companies — and get back the matching records grouped by type, along with the fields that matched. Narrow the search with filters such as merchant, store, or status.", "api": "Partners API", "method": "GET", "path": "/partners/:partnerId/global-search", "content": "# Global Search\n\n## Overview\nRun a free-text search across everything the partner owns — merchants, stores, terminals, applications, and companies — and get back the matching records grouped by type, along with the fields that matched. Narrow the search with filters such as merchant, store, or status.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/global-search\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier of the partner whose records are searched. Supplied in the URL path. |\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `query` | `string` | Yes | The text to search the partner's records for, such as a merchant name, store name, or company. |\n| `pageNumber` | `number` | No | Page of results to return. Overrides the x-page-number header when supplied. |\n| `merchantId` | `string` | No | Return only records belonging to this merchant. Accepts a single value or a comma-separated list. |\n| `merchantType` | `string` | No | Return only records for merchants of this type. Accepts a single value or a comma-separated list. |\n| `storeId` | `string` | No | Return only records belonging to this store. Accepts a single value or a comma-separated list. |\n| `storeStatus` | `string` | No | Return only stores in this status. Accepts a single value or a comma-separated list. |\n| `terminalStatus` | `string` | No | Return only terminals in this status. Accepts a single value or a comma-separated list. |\n| `applicationStatus` | `string` | No | Return only applications in this status. Accepts a single value or a comma-separated list. |\n| `applicationType` | `string` | No | Return only applications of this type. Accepts a single value or a comma-separated list. |\n| `type` | `string` | No | Return only records of this document type, for example MERCHANT or STORE. Accepts a single value or a comma-separated list. |\n\n### Pagination\n\nPage through results with the `x-page-number` request header, or supply `pageNumber` as a `query` parameter. The total number of matches is returned in the `x-total-items` response header.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/global-search?query=Kaffebaren&type=MERCHANT&storeStatus=ACTIVE\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The search results. |\n|     `hits` | `array` | The matching records. |\n|         `partnerId` | `string` | Identifier of the partner the matched record belongs to. |\n|         `merchantId` | `string` | Identifier of the merchant the matched record belongs to. |\n|         `storeId` | `string` | Identifier of the store the matched record belongs to. |\n|         `data` | `object` | The matched record's document fields. |\n|             `type` | `string` | The kind of record that matched, for example MERCHANT, STORE, or COMPANY. |\n|             `partnerId` | `string` | Identifier of the partner the record belongs to. |\n|             `merchantId` | `string` | Identifier of the merchant the record belongs to. |\n|             `storeId` | `string` | Identifier of the store the record belongs to. |\n|             `companyId` | `string` | Identifier of the company the record belongs to. |\n|             `pfAccountId` | `string` | Payment facilitator account identifier for the record. |\n|             `name` | `string` | Display name of the matched record. |\n|             `email` | `string` | Email associated with the matched record. |\n|             `status` | `string` | Status of the matched record, mirrored from its store status. |\n|             `storeStatus` | `string` | Status of the store the record belongs to. |\n|             `merchantType` | `string` | Type of the merchant the record belongs to. |\n|         `matches` | `array` | The individual field matches for this record. |\n|             `field` | `string` | The document field that matched the search. |\n|             `matched` | `array` | The matched value or values for the field. |\n|             `snippet` | `string` | A snippet of text surrounding the match. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"hits\": [\n {\n \"partnerId\": \"pt_9c31a0f4b2\",\n \"merchantId\": \"m_5f2c1a9b3d\",\n \"storeId\": \"st_2a91\",\n \"data\": {\n \"type\": \"MERCHANT\",\n \"partnerId\": \"pt_9c31a0f4b2\",\n \"merchantId\": \"m_5f2c1a9b3d\",\n \"storeId\": \"st_2a91\",\n \"companyId\": \"co_71ad\",\n \"pfAccountId\": \"pf_88c2\",\n \"name\": \"Kaffebaren AB\",\n \"email\": \"hello@kaffebaren.se\",\n \"status\": \"ACTIVE\",\n \"storeStatus\": \"ACTIVE\",\n \"merchantType\": \"STANDARD\"\n },\n \"matches\": [\n {\n \"field\": \"name\",\n \"matched\": [\n \"Kaffebaren AB\"\n ],\n \"snippet\": \"…Kaffebaren AB…\"\n }\n ]\n }\n ]\n },\n \"message\": \"Global search results fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch global search results\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "List Merchant Users", "slug": "partners-list-merchant-users", "description": "Retrieve all users that belong to a specific merchant under the partner, including their names, contact details, and role. Use this to manage the staff of one of your merchants.", "api": "Partners API", "method": "GET", "path": "/partners/:partnerId/merchants/:merchantId/users", "content": "# List Merchant Users\n\n## Overview\nRetrieve all users that belong to a specific merchant under the partner, including their names, contact details, and role. Use this to manage the staff of one of your merchants.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants/:merchantId/users\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier of the partner the merchant belongs to. Supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier of the merchant whose users are returned. Supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/merchants/:merchantId/users\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The users belonging to the merchant. |\n|     `userId` | `string` | Unique identifier of the user. |\n|     `firstName` | `string` | User's first name. |\n|     `lastName` | `string` | User's last name. |\n|     `imageUrl` | `string` | URL of the user's profile image. |\n|     `merchantId` | `string` | Identifier of the merchant the user belongs to. |\n|     `partnerId` | `string` | Identifier of the partner the user is associated with, if any. |\n|     `phoneNumber` | `string` | User's phone number. |\n|     `swishNumber` | `string` | User's Swish number, if set. |\n|     `address` | `string` | User's address. |\n|     `email` | `string` | User's email address. |\n|     `role` | `string` | The user's role, which determines their permissions. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"userId\": \"u_7b42c1\",\n \"firstName\": \"Erik\",\n \"lastName\": \"Lund\",\n \"imageUrl\": \"https://cdn.surfboard.se/u/7b42c1.png\",\n \"merchantId\": \"m_5f2c1a9b3d\",\n \"partnerId\": \"pt_9c31a0f4b2\",\n \"phoneNumber\": \"+46707654321\",\n \"swishNumber\": \"1231181189\",\n \"address\": \"Kungsgatan 5, Göteborg\",\n \"email\": \"erik@kaffebaren.se\",\n \"role\": \"CASHIER\"\n }\n ],\n \"message\": \"Fetched users for merchant successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch users for merchant\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "List Partner Users", "slug": "partners-list-partner-users", "description": "Retrieve all users that belong to the partner account, including their names, contact details, and role. Use this to manage the partner's team members.", "api": "Partners API", "method": "GET", "path": "/partners/:partnerId/users", "content": "# List Partner Users\n\n## Overview\nRetrieve all users that belong to the partner account, including their names, contact details, and role. Use this to manage the partner's team members.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/users\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier of the partner whose users are returned. Supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/users\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The users belonging to the partner. |\n|     `userId` | `string` | Unique identifier of the user. |\n|     `firstName` | `string` | User's first name. |\n|     `lastName` | `string` | User's last name. |\n|     `imageUrl` | `string` | URL of the user's profile image. |\n|     `merchantId` | `string` | Identifier of the merchant the user is associated with, if any. |\n|     `partnerId` | `string` | Identifier of the partner the user belongs to. |\n|     `phoneNumber` | `string` | User's phone number. |\n|     `swishNumber` | `string` | User's Swish number, if set. |\n|     `address` | `string` | User's address. |\n|     `email` | `string` | User's email address. |\n|     `role` | `string` | The user's role, which determines their permissions. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"userId\": \"u_3f81a0\",\n \"firstName\": \"Anna\",\n \"lastName\": \"Berg\",\n \"imageUrl\": \"https://cdn.surfboard.se/u/3f81a0.png\",\n \"merchantId\": \"\",\n \"partnerId\": \"pt_9c31a0f4b2\",\n \"phoneNumber\": \"+46701234567\",\n \"swishNumber\": \"\",\n \"address\": \"Storgatan 1, Stockholm\",\n \"email\": \"anna@nordiccoffee.se\",\n \"role\": \"ADMIN\"\n }\n ],\n \"message\": \"Fetched users for partner successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch users for partner\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Search Companies", "slug": "partners-search-companies", "description": "Search a company registry by name to find businesses during merchant onboarding, returning matching companies with their registry identifiers, legal form, and registered address. Optionally restrict the search to one or more countries.", "api": "Partners API", "method": "GET", "path": "/partners/:partnerId/companies/search", "content": "# Search Companies\n\n## Overview\nSearch a company registry by name to find businesses during merchant onboarding, returning matching companies with their registry identifiers, legal form, and registered address. Optionally restrict the search to one or more countries.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/companies/search\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier of the partner performing the search. Supplied in the URL path. |\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `companyName` | `string` | Yes | The company name to search the registry for. |\n| `countryCode` | `string` | No | Restrict the search to one or more countries (ISO 3166-1 alpha-2). Accepts a single value or a list. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/companies/search?companyName=Kaffebaren&countryCode=SE\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The matching companies. |\n|     `companyId` | `string` | Surfboard identifier for the company. |\n|     `creditsafeId` | `string` | Identifier of the company in the Creditsafe registry. |\n|     `companyName` | `string` | Registered name of the company. |\n|     `legalGroupCode` | `string` | Code identifying the company's legal form. |\n|     `legalGroupText` | `string` | Human-readable description of the company's legal form. |\n|     `address` | `object` | The company's registered address. |\n|         `simpleValue` | `string` | The full address as a single formatted string. |\n|         `street` | `string` | Street part of the address. |\n|         `city` | `string` | City part of the address. |\n|         `postCode` | `string` | Postal code part of the address. |\n|         `telephone` | `string` | Registered telephone number for the company. |\n|     `town` | `string` | Town the company is registered in. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"companyId\": \"co_71ad\",\n \"creditsafeId\": \"SE-0-5566778899\",\n \"companyName\": \"Kaffebaren AB\",\n \"legalGroupCode\": \"AB\",\n \"legalGroupText\": \"Aktiebolag\",\n \"address\": {\n \"simpleValue\": \"Storgatan 1, 111 22 Stockholm\",\n \"street\": \"Storgatan 1\",\n \"city\": \"Stockholm\",\n \"postCode\": \"111 22\",\n \"telephone\": \"+46 8 123 456\"\n },\n \"town\": \"Stockholm\"\n }\n ],\n \"message\": \"Company search completed successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to search companies\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Merchant User", "slug": "partners-update-merchant-user", "description": "Update the profile of a user belonging to one of the partner's merchants. Any combination of first name, last name, profile image, and address can be updated; omitted fields are left unchanged.", "api": "Partners API", "method": "PUT", "path": "/partners/:partnerId/merchants/:merchantId/users/:userId", "content": "# Update Merchant User\n\n## Overview\nUpdate the profile of a user belonging to one of the partner's merchants. Any combination of first name, last name, profile image, and address can be updated; omitted fields are left unchanged.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `userId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /partners/:partnerId/merchants/:merchantId/users/:userId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier of the partner the merchant belongs to. Supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier of the merchant the user belongs to. Supplied in the URL path. |\n| `userId` | `string` | Yes | Identifier of the user to update. Supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `firstName` | `string` | No | New first name for the user. |\n| `lastName` | `string` | No | New last name for the user. |\n| `imageUrl` | `string` | No | New profile image URL for the user. |\n| `address` | `string` | No | New address for the user. |\n\n### Request Example\n```json\n{\n \"firstName\": \"Erik\",\n \"lastName\": \"Lundqvist\",\n \"address\": \"Kungsgatan 5, Göteborg\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The updated user profile. |\n|     `userId` | `string` | Unique identifier of the user. |\n|     `firstName` | `string` | User's first name after the update. |\n|     `lastName` | `string` | User's last name after the update. |\n|     `imageUrl` | `string` | URL of the user's profile image after the update. |\n|     `address` | `string` | User's address after the update. |\n|     `email` | `string` | User's email address. |\n|     `merchantId` | `string` | Identifier of the merchant the user belongs to. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"userId\": \"u_7b42c1\",\n \"firstName\": \"Erik\",\n \"lastName\": \"Lundqvist\",\n \"imageUrl\": \"https://cdn.surfboard.se/u/7b42c1.png\",\n \"address\": \"Kungsgatan 5, Göteborg\",\n \"email\": \"erik@kaffebaren.se\",\n \"merchantId\": \"m_5f2c1a9b3d\"\n },\n \"message\": \"User profile updated successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"No fields provided to update.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `userId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Activate Payment Method for a Store", "slug": "payment-methods-activate-payment-method-for-a-store", "description": "Activates a single payment method for a specific store under a merchant. Only AMEX and SWISH can be activated at the store level; the store is taken from the URL path. Configuration values such as the AMEX merchant id or Swish number can be supplied alongside the payment method.", "api": "Payment Methods API", "method": "POST", "path": "/merchants/:merchantId/stores/:storeId/payment-methods", "content": "# Activate Payment Method for a Store\n\n## Overview\nActivates a single payment method for a specific store under a merchant. Only AMEX and SWISH can be activated at the store level; the store is taken from the URL path. Configuration values such as the AMEX merchant id or Swish number can be supplied alongside the payment method.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /merchants/:merchantId/stores/:storeId/payment-methods\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentMethod` | `string` | Yes | The payment method to activate for the store. Only AMEX and SWISH are accepted at the store level. Possible values: `AMEX`, `SWISH`. |\n| `amexMID` | `string` | No | American Express merchant id, required when activating the AMEX payment method. |\n| `swishNumber` | `string` | No | The Swish payee number to route Swish payments to, used when activating the SWISH payment method. |\n| `acquirerMID` | `string` | No | Acquirer merchant id to associate with the payment method. |\n| `username` | `string` | No | Provider username used when the payment method requires provider credentials. |\n| `password` | `string` | No | Provider password used when the payment method requires provider credentials. |\n| `klarnaMerchantId` | `string` | No | Klarna merchant id to associate with the payment method. |\n\n### Request Example\n```json\n{\n \"paymentMethod\": \"AMEX\",\n \"amexMID\": \"1234567890\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | Array of payment method registration results for the store. |\n|     `method` | `string` | The payment method name that was processed (e.g., 'amex', 'swish'). |\n|     `paymentMethodId` | `string` | Unique identifier assigned to the payment method (present on success). |\n|     `status` | `string` | Registration status for this payment method, either 'SUCCESS' or 'ERROR'. |\n|     `message` | `string` | Error message if registration failed (present on error). |\n| `message` | `string` | A message that describes the overall status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"method\": \"amex\",\n \"paymentMethodId\": \"8235c0943bd9800023\",\n \"status\": \"SUCCESS\"\n }\n ],\n \"message\": \"Processed payment method registrations\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid payment method type. Must be AMEX or SWISH.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Payment Methods with Status", "slug": "payment-methods-fetch-payment-methods-with-status", "description": "Retrieves every payment method configured for a merchant, including each method's activation status. Use this when you need to see both active and deactivated payment methods, for example to build a settings screen.", "api": "Payment Methods API", "method": "GET", "path": "/merchants/:merchantId/all-payment-methods", "content": "# Fetch Payment Methods with Status\n\n## Overview\nRetrieves every payment method configured for a merchant, including each method's activation status. Use this when you need to see both active and deactivated payment methods, for example to build a settings screen.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/all-payment-methods\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/all-payment-methods\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The payment methods configured for the merchant. |\n|     `paymentMethodId` | `string` | PaymentMethod ID of the payment method. |\n|     `paymentMethod` | `string` | Specifies the payment method, for example 'AMEX', 'SWISH', or 'CARD'. |\n|     `paymentStatus` | `string` | Activation status of the payment method, indicated as either 'ACTIVATED' or 'DEACTIVATED'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"paymentMethodId\": \"8235c0a33bd9800223\",\n \"paymentMethod\": \"SWISH\",\n \"paymentStatus\": \"ACTIVATED\"\n },\n {\n \"paymentMethodId\": \"8235c0943bd9800023\",\n \"paymentMethod\": \"AMEX\",\n \"paymentStatus\": \"DEACTIVATED\"\n }\n ],\n \"message\": \"Fetched all payment methods for merchant\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch payment methods for merchant\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "List Payment Methods", "slug": "payment-methods-list-payment-methods", "description": "Retrieves every payment method configured for a merchant along with its activation status. This is an alias of the Fetch Payment Methods with Status endpoint and returns the same response.", "api": "Payment Methods API", "method": "GET", "path": "/merchants/:merchantId/payment-methods/list", "content": "# List Payment Methods\n\n## Overview\nRetrieves every payment method configured for a merchant along with its activation status. This is an alias of the Fetch Payment Methods with Status endpoint and returns the same response.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/payment-methods/list\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/payment-methods/list\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The payment methods configured for the merchant. |\n|     `paymentMethodId` | `string` | PaymentMethod ID of the payment method. |\n|     `paymentMethod` | `string` | Specifies the payment method, for example 'AMEX', 'SWISH', or 'CARD'. |\n|     `paymentStatus` | `string` | Activation status of the payment method, indicated as either 'ACTIVATED' or 'DEACTIVATED'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"paymentMethodId\": \"8235c0a33bd9800223\",\n \"paymentMethod\": \"SWISH\",\n \"paymentStatus\": \"ACTIVATED\"\n },\n {\n \"paymentMethodId\": \"8235c0943bd9800023\",\n \"paymentMethod\": \"AMEX\",\n \"paymentStatus\": \"DEACTIVATED\"\n }\n ],\n \"message\": \"Fetched all payment methods for merchant\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch payment methods for merchant\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Check Payment Status", "slug": "payments-check-payment-status", "description": "Returns the current status of a payment. Use this API to poll the result of a payment after initiation. When the payment has completed, the response also includes the detailed transaction information.", "api": "Payments API", "method": "GET", "path": "/payments/:paymentId/status", "content": "# Check Payment Status\n\n## Overview\nReturns the current status of a payment. Use this API to poll the result of a payment after initiation. When the payment has completed, the response also includes the detailed transaction information.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `paymentId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /payments/:paymentId/status\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /payments/:paymentId/status\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `paymentStatus` | `string` | High-level lifecycle status of the payment, such as PAYMENT_COMPLETED, PAYMENT_FAILED, or PAYMENT_CANCELLED. |\n|     `failureReason` | `string` | Reason the payment failed, when applicable. |\n|     `transactionId` | `string` | Identifier of the transaction associated with the payment. |\n|     `transactionDetails` | `object` | Detailed transaction information, included when the payment has completed. |\n|         `transactionId` | `string` | Identifier of the completed transaction. |\n|         `terminalId` | `string` | Identifier of the terminal that processed the transaction. |\n|         `rrn` | `string` | Retrieval reference number for the transaction. |\n|         `amount` | `string` | Amount of the transaction. |\n|         `currency` | `string` | Currency of the transaction. |\n|         `method` | `string` | Payment method used for the transaction. |\n|         `truncatedPan` | `string` | Masked card number used for the transaction. |\n|         `cardLabel` | `string` | Label of the card used for the transaction. |\n|         `posEntryMode` | `string` | Point-of-sale entry mode of the transaction. |\n|         `aid` | `string` | Application identifier of the card application used. |\n|         `customerResponseCode` | `string` | Response code returned for the customer. |\n|         `cvmMethod` | `string` | Cardholder verification method applied. |\n|         `authMode` | `string` | Authorization mode of the transaction. |\n|         `cardBrand` | `string` | Brand of the card used for the transaction. |\n|         `terminalVerificationResult` | `string` | Terminal verification result of the transaction. |\n|         `cvmMethodDescription` | `string` | Human-readable description of the cardholder verification method. |\n|         `authCode` | `string` | Authorization code returned for the transaction. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"paymentStatus\": \"PAYMENT_COMPLETED\",\n \"transactionId\": \"82ff7c258148d80504\",\n \"transactionDetails\": {\n \"transactionId\": \"82ff7c258148d80504\",\n \"terminalId\": \"82ff7c258148d80504\",\n \"rrn\": \"000123456789\",\n \"amount\": \"1000\",\n \"currency\": \"752\",\n \"method\": \"CARD\",\n \"truncatedPan\": \"************1234\",\n \"cardLabel\": \"VISA\",\n \"posEntryMode\": \"07\",\n \"aid\": \"A0000000031010\",\n \"customerResponseCode\": \"00\",\n \"cvmMethod\": \"PIN\",\n \"authMode\": \"AUTH\",\n \"cardBrand\": \"VISA\",\n \"terminalVerificationResult\": \"0000008000\",\n \"cvmMethodDescription\": \"Online PIN\",\n \"authCode\": \"123456\"\n }\n },\n \"message\": \"Payment status fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `paymentId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Complete Payment", "slug": "payments-complete-payment", "description": "Finalizes a payment that requires an explicit completion step, such as after an external authorization or redirect returns. Use this API to move the payment to its final state.", "api": "Payments API", "method": "PUT", "path": "/payments/:paymentId/complete", "content": "# Complete Payment\n\n## Overview\nFinalizes a payment that requires an explicit completion step, such as after an external authorization or redirect returns. Use this API to move the payment to its final state.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `paymentId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /payments/:paymentId/complete\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `paymentStatus` | `string` | Lifecycle status of the payment after completion, such as PAYMENT_COMPLETED. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"paymentStatus\": \"PAYMENT_COMPLETED\"\n },\n \"message\": \"Payment completed successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `paymentId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Payment Details", "slug": "payments-get-payment-details", "description": "Fetches the full payment slip and detail record for a payment. Use this API to retrieve the data needed for receipts and reconciliation.", "api": "Payments API", "method": "GET", "path": "/payments/:paymentId", "content": "# Get Payment Details\n\n## Overview\nFetches the full payment slip and detail record for a payment. Use this API to retrieve the data needed for receipts and reconciliation.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `paymentId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /payments/:paymentId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\n\nTo localize receipt content, send in `lang` as a query param. It defaults to en when omitted.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `lang` | `string` | No | Language used for any localized receipt content. Defaults to en. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /payments/:paymentId?lang=value\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `paymentId` | `string` | Unique identifier of the payment. |\n|     `orderId` | `string` | Identifier of the order this payment belongs to. |\n|     `checkoutId` | `string` | Identifier of the checkout this payment belongs to. |\n|     `merchantId` | `string` | Identifier of the merchant. |\n|     `storeId` | `string` | Identifier of the store. |\n|     `transactionId` | `string` | Identifier of the underlying card transaction. |\n|     `purchasePaymentId` | `string` | Identifier of the original purchase payment this record relates to. |\n|     `requestId` | `string` | Identifier of the request that created the payment. |\n|     `externalRequestId` | `string` | External request identifier supplied by the caller. |\n|     `amount` | `string` | Payment amount, in minor units. |\n|     `currency` | `string` | ISO 4217 alpha currency code of the payment (e.g. SEK). |\n|     `paymentType` | `string` | Type of the payment (for example PURCHASE). |\n|     `paymentMethod` | `string` | Payment method used for the payment. |\n|     `paymentStatus` | `string` | Current status of the payment. |\n|     `cardBrand` | `string` | Card brand used for the payment (for example VISA). |\n|     `payeePhoneNumber` | `string` | Phone number of the payee, when applicable. |\n|     `terminalMessage` | `string` | Message shown on the terminal for the payment. |\n|     `terminalCode` | `array` | Terminal code(s) associated with the payment. |\n|     `userMessageId` | `string` | Identifier of the localized user message for the payment. |\n|     `voided` | `boolean` | Whether the payment has been voided. |\n|     `voidStatus` | `string` | Void status of the payment (for example NOT_INITIATED, VOID_INITIATED, VOIDED, CANNOT_VOID). |\n|     `voidRequestedAt` | `string` | Timestamp when a void was requested for the payment. |\n|     `createdAt` | `string` | Timestamp when the payment record was created. |\n|     `firstEntryTime` | `string` | Timestamp of the first entry for the payment. |\n|     `createdBy` | `string` | Identifier of the actor that created the payment record. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"paymentId\": \"811f9bd48c6eb80c06\",\n \"orderId\": \"838ca7fc6d7de9770b\",\n \"checkoutId\": \"83044b3703fed80106\",\n \"merchantId\": \"82ff7c258148d80504\",\n \"storeId\": \"83044b3703fed80106\",\n \"transactionId\": \"82ff7c258148d80504\",\n \"requestId\": \"84b1c2d3e4f5a60789\",\n \"amount\": \"1000\",\n \"currency\": \"SEK\",\n \"paymentType\": \"PURCHASE\",\n \"paymentMethod\": \"CARD\",\n \"paymentStatus\": \"PAYMENT_COMPLETED\",\n \"cardBrand\": \"VISA\",\n \"terminalMessage\": \"Approved\",\n \"terminalCode\": [\n \"000\"\n ],\n \"voided\": false,\n \"voidStatus\": \"NOT_INITIATED\",\n \"createdAt\": \"2026-06-17T10:15:00.000Z\"\n },\n \"message\": \"Payment details fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `paymentId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Place Klarna Order", "slug": "payments-place-klarna-order", "description": "Places and authorizes a Klarna order against an already-initiated Klarna payment. Use this API to exchange the Klarna SDK authorization token for a created Klarna order.", "api": "Payments API", "method": "POST", "path": "/payments/:paymentId/klarna/place-order", "content": "# Place Klarna Order\n\n## Overview\nPlaces and authorizes a Klarna order against an already-initiated Klarna payment. Use this API to exchange the Klarna SDK authorization token for a created Klarna order.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `paymentId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /payments/:paymentId/klarna/place-order\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentMethod` | `string` | Yes | Payment method that identifies the Klarna flow. Possible values: `KLARNA`. |\n| `authorizationToken` | `string` | Yes | Klarna authorization token returned by the Klarna SDK after the customer authorizes. |\n\n### Request Example\n```json\n{\n \"paymentMethod\": \"KLARNA\",\n \"authorizationToken\": \"b4bd3423-24e3-4e5d-bc08-2e1e9d1d6b6c\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `orderId` | `string` | Identifier of the Klarna order created from the authorization token. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"orderId\": \"838ca7fc6d7de9770b\"\n },\n \"message\": \"Klarna order placed successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `paymentId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Payment Method", "slug": "payments-update-payment-method", "description": "Switches the payment method on an in-flight payment, for example when a customer changes from card to Klarna at the payment page. Use this API to set a new payment method and re-apply initiation-style parameters.", "api": "Payments API", "method": "PUT", "path": "/payments/:paymentId/update/payment-method", "content": "# Update Payment Method\n\n## Overview\nSwitches the payment method on an in-flight payment, for example when a customer changes from card to Klarna at the payment page. Use this API to set a new payment method and re-apply initiation-style parameters.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `paymentId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /payments/:paymentId/update/payment-method\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `paymentMethod` | `string` | Yes | New payment method to set on the payment. Possible values: `CARD`, `CARD_NP`, `KLARNA`, `CTOKEN`, `GIFTCARD`, `SWISH`. |\n| `params` | `object` | No | Additional initiation-style parameters to apply with the new payment method. |\n|     `paymentMethod` | `string` | Yes | Payment method to apply within the re-initiation parameters; provided separately from the root paymentMethod field. Possible values: `CARD`, `CARD_NP`, `KLARNA`, `CTOKEN`, `GIFTCARD`, `SWISH`. |\n|     `orderId` | `string` | Yes | Identifier of the order the updated payment is for. |\n|     `terminalId` | `string` | No | Unique identifier of the terminal initiating the updated payment. |\n|     `amount` | `number` | No | Amount to charge with the new method in the smallest currency unit. |\n|     `initialOrderReference` | `string` | No | Reference to an original order. |\n|     `adjustments` | `array` | No | List of order-level monetary adjustments to apply to the payment. |\n|         `adjustmentAmount` | `number` | Yes | Mandatory monetary value of the adjustment in the smallest currency unit. |\n|         `amount` | `number` | No | Optional explicit monetary amount for the adjustment in the smallest currency unit, distinct from the mandatory adjustmentAmount. |\n|         `adjustmentType` | `string` | Yes | Type or category of the adjustment, such as tip or discount. |\n|         `metadata` | `object` | No | Arbitrary key/value metadata attached to the adjustment. |\n|         `createdBy` | `string` | No | Identifier of the actor who created the adjustment. |\n|     `refundProcessingParams` | `object` | No | Refund metadata used when processing refunds. |\n|         `purchasePaymentId` | `string` | No | Identifier of the original purchase payment being refunded. |\n|         `refundReason` | `string` | No | Reason for the refund request. Possible values: `CUSTOMER_INITIATED_RETURN`, `SUSPECTED_MALFUNCTION`, `SUSPECTED_FRAUD`, `DUPLICATE_TRANSACTION`, `OTHER`. |\n|         `otherReason` | `string` | No | Free-text reason for the return request when it does not fall into any of the predefined categories. |\n|     `serialSplitPaymentsMode` | `array` | No | An array of amounts in smallest currency unit to split the payment serially across multiple charges. |\n|     `paymentMethodParams` | `object` | No | Method-specific parameters for the chosen payment method. |\n|         `tokenId` | `string` | No | Saved-card or payment token identifier to charge for tokenised card payments. |\n|         `bic` | `string` | No | The BIC (Bank Identifier Code) is an ISO 9362 standard that uniquely identifies a bank, used for account-to-account and bank payments. |\n|         `ip` | `string` | No | Customer IP address used as risk and fraud context. |\n|         `swishMode` | `string` | No | Swish flow variant or mode selector (e.g., ECOM). |\n|         `payeePhoneNumber` | `object` | No | Payee phone number for Swish payments. |\n|             `code` | `string` | Yes | International dialing code (e.g., 46 for Sweden without '+'). |\n|             `number` | `string` | Yes | National subscriber number. |\n|         `giftCardId` | `string` | No | Identifier of the gift card to redeem. |\n|         `invoice` | `object` | No | Invoice payment configuration. |\n|             `invoiceDistribution` | `string` | No | Channel used to deliver the invoice (e.g., EMAIL). |\n|             `contractReference` | `string` | No | Reference to the underlying contract or agreement. |\n|             `debtCollectionEnabled` | `boolean` | No | Whether unpaid invoices are sent to debt collection. |\n|             `dueDate` | `string` | No | Relative due date for the invoice as a chrono expression (e.g., 30d). |\n|             `reminder` | `boolean` | No | Whether a payment reminder should be sent. |\n|             `invoicePaymentMethods` | `array` | No | Permitted payment methods for settling the invoice. Possible values: `BANK`, `DIRECT_BANK`, `CARD`. |\n|     `language` | `string` | No | Client or SDK short language code used to resolve the Klarna session locale. |\n|     `message` | `string` | No | Free-text message attached to the update. |\n|     `initialOrderId` | `string` | No | Identifier of the original order being updated. |\n\n### Request Example\n```json\n{\n \"paymentMethod\": \"KLARNA\",\n \"params\": {\n \"paymentMethod\": \"KLARNA\",\n \"orderId\": \"838ca7fc6d7de9770b\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `paymentId` | `string` | Identifier of the updated payment. |\n|     `paymentStatus` | `string` | Lifecycle status of the payment after the method update. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"paymentId\": \"811f9bd48c6eb80c06\",\n \"paymentStatus\": \"PAYMENT_INITIATED\"\n },\n \"message\": \"Payment method updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `paymentId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Add Product Campaign", "slug": "product-catalog-add-product-campaign", "description": "Attach a promotional campaign to a product, offering either a fixed reduced price or a percentage discount while the campaign is active.", "api": "Product Catalog API", "method": "POST", "path": "/catalog/:catalogId/products/:productId/campaign", "content": "# Add Product Campaign\n\n## Overview\nAttach a promotional campaign to a product, offering either a fixed reduced price or a percentage discount while the campaign is active.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /catalog/:catalogId/products/:productId/campaign\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `campaignName` | `string` | Yes | Name of the campaign shown to staff and customers. |\n| `storeId` | `string` | Yes | Identifier of the store the product belongs to. |\n| `price` | `object` | Yes | The discount the campaign applies. Provide either a fixed amount or a percentage. |\n|     `fixedAmount` | `number` | No | Reduced price during the campaign, in the smallest unit of the currency (e.g. öre for SEK). |\n|     `percentage` | `number` | No | Percentage discount applied during the campaign. |\n\n### Request Example\n```json\n{\n \"campaignName\": \"Summer Sale\",\n \"storeId\": \"8136a645a2c2d1bb0f\",\n \"price\": {\n \"fixedAmount\": 3500\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The created campaign. |\n|     `campaignId` | `string` | Unique identifier of the newly created campaign. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"campaignId\": \"8239b16f0a59580224\"\n },\n \"message\": \"Added product campaign for merchant successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Delete Product", "slug": "product-catalog-delete-product", "description": "Remove a product from a catalog. Pass the store the product belongs to as a query parameter.", "api": "Product Catalog API", "method": "DELETE", "path": "/catalog/:catalogId/products/:productId", "content": "# Delete Product\n\n## Overview\nRemove a product from a catalog. Pass the store the product belongs to as a query parameter.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /catalog/:catalogId/products/:productId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\nPass the mandatory `storeId` query parameter identifying the store the product belongs to.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | Yes | Identifier of the store the product belongs to. |\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Product for merchant removed successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Products for Partner", "slug": "product-catalog-fetch-products-for-partner", "description": "Retrieve a paginated list of the products and bundles available across a partner's merchants. Use this to build a partner-wide product catalog view.", "api": "Product Catalog API", "method": "GET", "path": "/partners/:partnerId/product-catalogue", "content": "# Fetch Products for Partner\n\n## Overview\nRetrieve a paginated list of the products and bundles available across a partner's merchants. Use this to build a partner-wide product catalog view.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/product-catalogue\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Pagination\n\nPage through results with the `x-page-number` request header. The total number of matching products is returned in the `x-total-items` response header.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/product-catalogue\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The products and bundles on the current page. |\n|     `products` | `array` | The partner's products. |\n|         `productId` | `string` | Unique identifier of the product. |\n|         `name` | `string` | Name of the product. |\n|         `currencyCode` | `string` | Currency the prices are expressed in. |\n|         `description` | `string` | Description of the product. |\n|         `category` | `string` | Category the product is grouped under. |\n|         `unit` | `string` | Unit of measurement for the product. |\n|         `productImages` | `array` | Image URLs for the product. |\n|         `discount` | `number` | Discount applied to the product, in the smallest unit of the currency. |\n|         `hsnCode` | `string` | Harmonized System (HSN) code classifying the product for tax. |\n|         `barcode` | `string` | Barcode value printed on the product. |\n|         `variantCategory` | `array` | The variant categories defined for the product. |\n|         `productProperties` | `object` | Free-form key/value properties describing the product. |\n|         `inventory` | `object` | Current stock information for the product. |\n|         `unitType` | `string` | How the product is priced and quantified (FIXED_UNIT, VARIABLE_UNIT or FREE_UNIT). |\n|         `type` | `string` | Whether the item is a PRODUCT or a SERVICE. |\n|         `relatedProducts` | `array` | Identifiers of products tagged as related. |\n|         `sellingPrice` | `number` | Selling price of the product, in the smallest unit of the currency. |\n|         `variants` | `array` | Variants of the product. |\n|         `billingPlans` | `array` | Recurring billing plans available for the product. |\n|         `tax` | `array` | Tax lines that apply to the product. |\n|             `type` | `string` | Type of tax, for example VAT. |\n|             `percentage` | `string` | Tax rate as a percentage. |\n|             `amount` | `number` | Fixed tax amount, in the smallest unit of the currency. |\n|         `attributeValues` | `array` | Attribute values assigned to the product. |\n|         `campaignInfo` | `array` | Active campaigns on the product. |\n|             `campaignName` | `string` | Name of the campaign. |\n|             `campaignId` | `string` | Identifier of the campaign. |\n|             `fixedAmount` | `number` | Reduced price during the campaign, in the smallest unit of the currency. |\n|             `percentage` | `string` | Percentage discount applied during the campaign. |\n|         `metadata` | `object` | Free-form key/value metadata attached to the product. |\n|     `bundles` | `array` | Bundles that group several products together. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"products\": [\n {\n \"productId\": \"823913d474de600e01\",\n \"name\": \"SurfPad Black Logo\",\n \"currencyCode\": \"752\",\n \"sellingPrice\": 1500,\n \"description\": \"SurfPad Payment Terminal in Black\",\n \"category\": \"electronics\",\n \"unit\": \"nos\",\n \"productImages\": [\n \"https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg\"\n ],\n \"unitType\": \"FIXED_UNIT\",\n \"type\": \"PRODUCT\",\n \"variants\": [],\n \"tax\": [\n {\n \"type\": \"VAT\",\n \"percentage\": \"25\",\n \"amount\": 0\n }\n ]\n }\n ],\n \"bundles\": []\n },\n \"message\": \"Products for partner fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Generate Description for Existing Product", "slug": "product-catalog-generate-description-for-existing-product", "description": "Generate an AI-written description for a product that already exists in a catalog. The product name and details are read from the catalog, so you only need to supply the desired length and language.", "api": "Product Catalog API", "method": "POST", "path": "/catalog/:catalogId/products/:productId/ai/description", "content": "# Generate Description for Existing Product\n\n## Overview\nGenerate an AI-written description for a product that already exists in a catalog. The product name and details are read from the catalog, so you only need to supply the desired length and language.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /catalog/:catalogId/products/:productId/ai/description\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `maxWordLength` | `number` | No | Maximum number of words in the generated description. |\n| `langCode` | `string` | No | Language to generate the description in (e.g. 'en' for English). |\n\n### Request Example\n```json\n{\n \"maxWordLength\": 150,\n \"langCode\": \"en\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The generated description. |\n|     `description` | `string` | AI-generated product description. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"description\": \"Experience effortless payments with the SurfPad terminal, engineered for speed, reliability, and a clean checkout every time.\"\n },\n \"message\": \"Description generated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Generate Images for Existing Product", "slug": "product-catalog-generate-images-for-existing-product", "description": "Generate AI-created images for a product that already exists in a catalog. The product name and details are read from the catalog; supply an optional prompt to steer the style and the number of images to produce.", "api": "Product Catalog API", "method": "POST", "path": "/catalog/:catalogId/products/:productId/ai/image", "content": "# Generate Images for Existing Product\n\n## Overview\nGenerate AI-created images for a product that already exists in a catalog. The product name and details are read from the catalog; supply an optional prompt to steer the style and the number of images to produce.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /catalog/:catalogId/products/:productId/ai/image\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `prompt` | `string` | No | Optional prompt describing the desired look and style of the images. |\n| `noOfImages` | `number` | No | Number of images to generate. |\n| `langCode` | `string` | No | Language context for image generation (e.g. 'en' for English). |\n\n### Request Example\n```json\n{\n \"prompt\": \"sleek modern product shot on a white background\",\n \"noOfImages\": 2,\n \"langCode\": \"en\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The generated images. |\n|     `imagePath` | `array` | URLs pointing to the generated product images. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"imagePath\": [\n \"https://storage.googleapis.com/sb-merchant-portal-ai-images/example_1.png\",\n \"https://storage.googleapis.com/sb-merchant-portal-ai-images/example_2.png\"\n ]\n },\n \"message\": \"Image generated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Remove Product Campaign", "slug": "product-catalog-remove-product-campaign", "description": "Remove a promotional campaign from a product, ending the discount it applied.", "api": "Product Catalog API", "method": "DELETE", "path": "/catalog/:catalogId/products/:productId/campaign/:campaignId", "content": "# Remove Product Campaign\n\n## Overview\nRemove a promotional campaign from a product, ending the discount it applied.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n- The resource identified by `campaignId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /catalog/:catalogId/products/:productId/campaign/:campaignId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n| `campaignId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\nPass the mandatory `storeId` query parameter identifying the store the product belongs to.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | Yes | Identifier of the store the product belongs to. |\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Removed product campaign for merchant successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n- The `campaignId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Remove Related Products", "slug": "product-catalog-remove-related-products", "description": "Remove one or more products from the set tagged as related to a given product.", "api": "Product Catalog API", "method": "DELETE", "path": "/catalog/:catalogId/products/:productId/related-products", "content": "# Remove Related Products\n\n## Overview\nRemove one or more products from the set tagged as related to a given product.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /catalog/:catalogId/products/:productId/related-products\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `relatedProducts` | `array` | No | The product identifiers to remove from the related products list. |\n\n### Request Example\n```json\n{\n \"relatedProducts\": [\n \"818f9fc43d0b580f02\"\n ]\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The result of the removal. |\n|     `productId` | `string` | Identifier of the product that was updated. |\n|     `removedCount` | `number` | Number of related products removed from the product. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"productId\": \"81c30d16df28880301\",\n \"removedCount\": 1\n },\n \"message\": \"Related products removed successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get Related Products", "slug": "product-catalog-get-related-products", "description": "Retrieve the products that have been tagged as related to a given product, for example accessories or recommended pairings shown alongside it.", "api": "Product Catalog API", "method": "GET", "path": "/catalog/:catalogId/products/:productId/related-products", "content": "# Get Related Products\n\n## Overview\nRetrieve the products that have been tagged as related to a given product, for example accessories or recommended pairings shown alongside it.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /catalog/:catalogId/products/:productId/related-products\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /catalog/:catalogId/products/:productId/related-products\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The product and its related products. |\n|     `productId` | `string` | Identifier of the product the related products belong to. |\n|     `relatedProducts` | `array` | The products tagged as related. |\n|         `id` | `string` | Unique identifier of the related product. |\n|         `name` | `string` | Name of the related product. |\n|         `description` | `string` | Description of the related product. |\n|         `sellingPrice` | `number` | Selling price of the related product, in the smallest unit of the currency. |\n|         `currencyCode` | `string` | Currency the price is expressed in. |\n|         `productImages` | `array` | Image URLs for the related product. |\n|         `type` | `string` | Whether the related item is a PRODUCT or a SERVICE. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"productId\": \"81c30d16df28880301\",\n \"relatedProducts\": [\n {\n \"id\": \"818f9fc43d0b580f01\",\n \"name\": \"SurfPad Charging Dock\",\n \"description\": \"Charging dock for the SurfPad terminal\",\n \"sellingPrice\": 1200,\n \"currencyCode\": \"752\",\n \"productImages\": [\n \"https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg\"\n ],\n \"type\": \"PRODUCT\"\n }\n ]\n },\n \"message\": \"Related products fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Related Products", "slug": "product-catalog-update-related-products", "description": "Replace the set of products tagged as related to a given product. The list you send becomes the new complete set of related products.", "api": "Product Catalog API", "method": "PATCH", "path": "/catalog/:catalogId/products/:productId/related-products", "content": "# Update Related Products\n\n## Overview\nReplace the set of products tagged as related to a given product. The list you send becomes the new complete set of related products.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `catalogId` in the URL path must exist.\n- The resource identified by `productId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /catalog/:catalogId/products/:productId/related-products\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `catalogId` | `string` | Yes | Identifier supplied in the URL path. |\n| `productId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `relatedProducts` | `array` | No | The product identifiers that should be tagged as related. Sending an empty array clears the related products. |\n\n### Request Example\n```json\n{\n \"relatedProducts\": [\n \"818f9fc43d0b580f01\",\n \"818f9fc43d0b580f02\"\n ]\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The result of the update. |\n|     `productId` | `string` | Identifier of the product that was updated. |\n|     `updatedCount` | `number` | Number of related products now tagged on the product. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"productId\": \"81c30d16df28880301\",\n \"updatedCount\": 2\n },\n \"message\": \"Related products updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to process request\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `catalogId` is part of the URL path and must be a valid identifier.\n- The `productId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Add Receipt Data", "slug": "receipts-add-receipt-data", "description": "Add receipt data that Surfboard does not hold — for example fiscal data from your own control unit — when you use Surfboard's digital-receipt or print APIs but keep some data on your side.", "api": "Receipts API", "method": "POST", "path": "/receipts/:id", "content": "# Add Receipt Data\n\n## Overview\nAdd receipt data that Surfboard does not hold — for example fiscal data from your own control unit — when you use Surfboard's digital-receipt or print APIs but keep some data on your side.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required using API Key and API Secret.\n- The resource identified by `id` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /receipts/:id\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `receiptNumber` | `number` | No | Receipt number from your own system. |\n| `cashRegisterName` | `string` | No | Name of the cash register that produced the receipt. |\n| `controlUnitSerial` | `string` | No | Serial number of the control unit used. |\n| `cashierName` | `string` | No | Name of the cashier who handled the transaction. |\n\n### Request Example\n```json\n{\n \"receiptNumber\": 1042,\n \"cashRegisterName\": \"Register 1\",\n \"controlUnitSerial\": \"CU-123456\",\n \"cashierName\": \"Alex\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | Human-facing status message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Receipt data added successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `id` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Receipt Data", "slug": "receipts-fetch-receipt-data", "description": "Fetch the raw receipt data for a completed transaction. Use this when you want to print the receipt yourself or render your own digital receipt.", "api": "Receipts API", "method": "GET", "path": "/receipts/:id", "content": "# Fetch Receipt Data\n\n## Overview\nFetch the raw receipt data for a completed transaction. Use this when you want to print the receipt yourself or render your own digital receipt.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required using API Key and API Secret.\n- The resource identified by `id` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /receipts/:id\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /receipts/:id\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `object` | The receipt payload for the transaction. Includes at least the fields below, plus line items, totals, and payment/fiscal details. |\n|     `id` | `string` | Transaction identifier the receipt belongs to. |\n|     `amount` | `number` | Transaction amount, in the smallest currency unit. |\n|     `currency` | `string` | ISO 4217 currency code of the transaction. |\n| `message` | `string` | Human-facing status message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"id\": \"{{transactionId}}\",\n \"amount\": 1000,\n \"currency\": \"SEK\"\n },\n \"message\": \"Receipt data fetched successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `id` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Print Receipt (Legacy)", "slug": "receipts-print-receipt-legacy", "description": "Legacy. Print the receipt using the older print API. Superseded by Print Receipt (POST /receipts/:id/print).", "api": "Receipts API", "method": "PUT", "path": "/receipts/:id/print", "content": "# Print Receipt (Legacy)\n\n## Overview\nLegacy. Print the receipt using the older print API. Superseded by Print Receipt.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required using API Key and API Secret.\n- The resource identified by `id` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /receipts/:id/print\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | No | Terminal to print on. Defaults to the terminal that processed the transaction. |\n| `language` | `string` | No | Language of the printed receipt. Possible values: `sv`, `da`, `fi`, `en`. |\n| `templateId` | `string` | No | Identifier of the receipt template to use. |\n\n### Request Example\n```json\n{\n \"terminalId\": \"{{terminalId}}\",\n \"language\": \"en\",\n \"templateId\": \"{{templateId}}\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | Human-facing status message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Print receipt processed successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `id` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Receipt Host Data", "slug": "receipts-update-receipt-host-data", "description": "Legacy. Update order data that Surfboard does not hold but that the receipt needs. Superseded by Add Receipt Data (POST /receipts/:id).", "api": "Receipts API", "method": "PUT", "path": "/receipts/:orderId", "content": "# Update Receipt Host Data\n\n## Overview\nLegacy. Update order data that Surfboard does not hold but that the receipt needs. Superseded by Add Receipt Data.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required using API Key and API Secret.\n- The resource identified by `orderId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /receipts/:orderId\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | No | Identifier of the merchant. |\n| `sequenceNumber` | `string` | No | Sequence number of the receipt from your system. |\n| `cashRegisterName` | `string` | No | Name of the cash register that produced the receipt. |\n| `controlUnitSerialNumber` | `string` | No | Serial number of the control unit used. |\n| `cashierName` | `string` | No | Name of the cashier who handled the transaction. |\n| `customerName` | `string` | No | Name of the customer. |\n\n### Request Example\n```json\n{\n \"merchantId\": \"{{merchantId}}\",\n \"sequenceNumber\": \"1042\",\n \"cashRegisterName\": \"Register 1\",\n \"controlUnitSerialNumber\": \"CU-123456\",\n \"cashierName\": \"Alex\",\n \"customerName\": \"Sam Smith\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | Human-facing status message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Receipt host data updated successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `orderId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Complete RFID Session", "slug": "rfid-complete-rfid-session", "description": "Completes an active RFID reading session. Optionally provide the final result of the session.", "api": "RFID API", "method": "POST", "path": "/terminals/:terminalId/sessions/:sessionId/complete", "content": "# Complete RFID Session\n\n## Overview\nCompletes an active RFID reading session. Optionally provide the final result of the session.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `terminalId` in the URL path must exist.\n- The resource identified by `sessionId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /terminals/:terminalId/sessions/:sessionId/complete\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n| `sessionId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `result` | `string` | No | The final result to set for the session. When omitted, the session is completed without an explicit result. Possible values: `COMPLETED`, `CANCELLED`, `TIMED_OUT`. |\n\n### Request Example\n```json\n{\n \"result\": \"COMPLETED\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Outcome of the request. |\n| `message` | `string` | Human-readable result message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"NFC reading session completed successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n- The `sessionId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch RFID Session Status", "slug": "rfid-fetch-rfid-session-status", "description": "Retrieves the current status of an RFID reading session, including the RFID tags read so far.", "api": "RFID API", "method": "GET", "path": "/terminals/:terminalId/sessions/:sessionId/status", "content": "# Fetch RFID Session Status\n\n## Overview\nRetrieves the current status of an RFID reading session, including the RFID tags read so far.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `terminalId` in the URL path must exist.\n- The resource identified by `sessionId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /terminals/:terminalId/sessions/:sessionId/status\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n| `sessionId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /terminals/:terminalId/sessions/:sessionId/status\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Outcome of the request. |\n| `data` | `object` | Current session status. |\n|     `sessionStatus` | `string` | Current status of the reading session. One of PENDING, COMPLETED, CANCELLED, TIMED_OUT, NOT_FOUND. Possible values: `PENDING`, `COMPLETED`, `CANCELLED`, `TIMED_OUT`, `NOT_FOUND`. |\n|     `nfcTags` | `array` | NFC/RFID tag identifiers read in the session so far. |\n| `message` | `string` | Human-readable result message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"sessionStatus\": \"PENDING\",\n \"nfcTags\": [\n \"E280117000000123456789AB\"\n ]\n },\n \"message\": \"Fetched NFC session status.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n- The `sessionId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch All RFID Sessions", "slug": "rfid-fetch-all-rfid-sessions", "description": "Retrieves all RFID reading sessions for the specified terminal.", "api": "RFID API", "method": "GET", "path": "/terminals/:terminalId/sessions", "content": "# Fetch All RFID Sessions\n\n## Overview\nRetrieves all RFID reading sessions for the specified terminal.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /terminals/:terminalId/sessions\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Pagination\n\nThis endpoint is paginated using request and response headers, not query parameters. Send the `x-page-number` request header to select the page (defaults to 1 when omitted). Each response returns the `x-total-items` header (total number of sessions) and the `x-page-number` header (the page that was served).\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n| `X-Page-Number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /terminals/:terminalId/sessions\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Outcome of the request. |\n| `data` | `array` | List of RFID reading sessions. |\n|     `sessionId` | `string` | Unique identifier of the RFID reading session. |\n|     `action` | `string` | The action the session performed. |\n|     `mode` | `string` | The read mode used for the session. |\n| `message` | `string` | Human-readable result message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"sessionId\": \"rfid_8267defa6150700b48\",\n \"action\": \"start\",\n \"mode\": \"single\"\n }\n ],\n \"message\": \"Fetched all NFC reading sessions under terminal.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Fetch RFID Tags", "slug": "rfid-fetch-rfid-tags", "description": "Retrieves all RFID tags read during the specified session.", "api": "RFID API", "method": "GET", "path": "/terminals/:terminalId/sessions/:sessionId/tags", "content": "# Fetch RFID Tags\n\n## Overview\nRetrieves all RFID tags read during the specified session.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `terminalId` in the URL path must exist.\n- The resource identified by `sessionId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /terminals/:terminalId/sessions/:sessionId/tags\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n| `sessionId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Pagination\n\nThis endpoint is paginated using request and response headers, not query parameters. Send the `x-page-number` request header to select the page (defaults to 1 when omitted). Each response returns the `x-total-items` header (total number of tags) and the `x-page-number` header (the page that was served).\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n| `X-Page-Number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /terminals/:terminalId/sessions/:sessionId/tags\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Outcome of the request. |\n| `data` | `array` | List of RFID tags read in the session. |\n|     `sessionId` | `string` | Identifier of the session the tag was read in. |\n|     `tagId` | `string` | The RFID tag identifier (EPC). |\n| `message` | `string` | Human-readable result message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"sessionId\": \"rfid_8267defa6150700b48\",\n \"tagId\": \"E280117000000123456789AB\"\n }\n ],\n \"message\": \"Fetched all tags under session.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n- The `sessionId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Start RFID Session", "slug": "rfid-start-rfid-session", "description": "Starts a new RFID reading session on the specified terminal. The terminal reads RFID tags in the selected mode until the session is completed.", "api": "RFID API", "method": "POST", "path": "/terminals/:terminalId/sessions", "content": "# Start RFID Session\n\n## Overview\nStarts a new RFID reading session on the specified terminal. The terminal reads RFID tags in the selected mode until the session is completed.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /terminals/:terminalId/sessions\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `mode` | `string` | Yes | The RFID tag read mode for the session. Possible values: `single`, `multiple`. |\n\n### Request Example\n```json\n{\n \"mode\": \"single\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Outcome of the request. |\n| `data` | `object` | The started session. |\n|     `sessionId` | `string` | Unique identifier of the RFID reading session. |\n| `message` | `string` | Human-readable result message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"sessionId\": \"rfid_8267defa6150700b48\"\n },\n \"message\": \"NFC reading session started successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Get RFID Session Details", "slug": "rfid-get-rfid-session-details", "description": "Retrieves the details of a specific RFID reading session.", "api": "RFID API", "method": "GET", "path": "/terminals/:terminalId/sessions/:sessionId", "content": "# Get RFID Session Details\n\n## Overview\nRetrieves the details of a specific RFID reading session.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `terminalId` in the URL path must exist.\n- The resource identified by `sessionId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /terminals/:terminalId/sessions/:sessionId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n| `sessionId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Pagination\n\nThis endpoint returns a single session object, so it is not paginated. For consistency with the session-list route it still emits the `x-total-items` and `x-page-number` response headers; both describe the underlying lookup and can be ignored for this single-record fetch.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /terminals/:terminalId/sessions/:sessionId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Outcome of the request. |\n| `data` | `object` | The RFID reading session. |\n|     `sessionId` | `string` | Unique identifier of the RFID reading session. |\n|     `action` | `string` | The action the session performed. |\n|     `mode` | `string` | The read mode used for the session. |\n| `message` | `string` | Human-readable result message. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"sessionId\": \"rfid_8267defa6150700b48\",\n \"action\": \"start\",\n \"mode\": \"single\"\n },\n \"message\": \"Fetched all NFC reading sessions under terminal.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n- The `sessionId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Service Providers for Partner", "slug": "service-providers-fetch-service-providers-for-partner", "description": "Retrieve all service providers registered under a partner, including their company details, contact information, and address. Use this to review the full roster of service providers a partner manages.", "api": "Service Providers API", "method": "GET", "path": "/partners/:partnerId/service-providers", "content": "# Fetch Service Providers for Partner\n\n## Overview\nRetrieve all service providers registered under a partner, including their company details, contact information, and address. Use this to review the full roster of service providers a partner manages.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/service-providers\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/service-providers\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Service providers registered under the partner. |\n|     `serviceProviders` | `array` | List of service providers under the partner. |\n|         `serviceProviderId` | `string` | Unique identifier of the service provider. |\n|         `personId` | `string` | Identifier of the associated person, null for company service providers. |\n|         `corporateId` | `string` | Corporate registration number of the service provider. |\n|         `nationalId` | `string` | National identification number, null when not applicable. |\n|         `name` | `string` | Name of the service provider, null when not specified. |\n|         `address` | `object` | Registered address of the service provider, null if unavailable. |\n|             `addressLine1` | `string` | First line of the address. |\n|             `city` | `string` | City of the address. |\n|             `countryCode` | `string` | Two-letter ISO country code of the address. |\n|             `postalCode` | `string` | Postal code of the address. |\n|         `phoneNumber` | `object` | Contact phone number of the service provider, null if unavailable. |\n|             `number` | `string` | Phone number of the service provider. |\n|             `code` | `string` | Country dialing code of the phone number. |\n|             `role` | `string` | Role associated with the phone number, null when not specified. |\n|         `email` | `string` | Email address of the service provider. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"serviceProviders\": [\n {\n \"serviceProviderId\": \"8385f437bc6d200b50\",\n \"personId\": null,\n \"corporateId\": \"5000008202\",\n \"nationalId\": null,\n \"name\": null,\n \"address\": {\n \"addressLine1\": \"Pacocha - Hand\",\n \"city\": \"Denesik Brook\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"61050\"\n },\n \"phoneNumber\": {\n \"number\": \"701208734\",\n \"code\": \"46\",\n \"role\": null\n },\n \"email\": \"harish@surfboard.se\"\n }\n ]\n },\n \"message\": \"Service providers fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to fetch service provider\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Service Providers for Merchant", "slug": "service-providers-fetch-service-providers-for-merchant", "description": "Retrieve the service providers currently active on a merchant account. Use this to see which service providers a merchant is linked to and whether each link is active.", "api": "Service Providers API", "method": "GET", "path": "/partners/:partnerId/merchants/:merchantId/service-providers", "content": "# Fetch Service Providers for Merchant\n\n## Overview\nRetrieve the service providers currently active on a merchant account. Use this to see which service providers a merchant is linked to and whether each link is active.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/merchants/:merchantId/service-providers\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/merchants/:merchantId/service-providers\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Active service providers linked to the merchant. |\n|     `activeServiceProviders` | `array` | List of service providers active on the merchant account. |\n|         `merchantId` | `string` | Identifier of the merchant the service provider is linked to. |\n|         `partnerId` | `string` | Identifier of the partner that owns the merchant. |\n|         `isActive` | `boolean` | Whether the link between the service provider and the merchant is currently active. |\n|         `serviceProvider` | `object` | Summary of the linked service provider, null if the details are unavailable. |\n|             `id` | `string` | Unique identifier of the service provider. |\n|             `name` | `string` | Name of the service provider. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"activeServiceProviders\": [\n {\n \"merchantId\": \"8385f437bc6d200b50\",\n \"partnerId\": \"8113d3f8403b380409\",\n \"isActive\": true,\n \"serviceProvider\": {\n \"id\": \"839ab2f1c47d300a20\",\n \"name\": \"Nordic Payments AB\"\n }\n }\n ]\n },\n \"message\": \"Active service providers fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to fetch service provider for merchant\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Initiate Individual Service Provider Onboarding", "slug": "service-providers-initiate-individual-service-provider-onboarding", "description": "Begin onboarding an individual service provider for a specific merchant. Surfboard sends the individual through a signing flow and returns the application and signing session so you can track the agreement to completion. Optionally attach fee configuration that applies to the service provider.", "api": "Service Providers API", "method": "POST", "path": "/partners/:partnerId/service-providers/individual", "content": "# Initiate Individual Service Provider Onboarding\n\n## Overview\nBegin onboarding an individual service provider for a specific merchant. Surfboard sends the individual through a signing flow and returns the application and signing session so you can track the agreement to completion. Optionally attach fee configuration that applies to the service provider.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/service-providers/individual\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `email` | `string` | Yes | Email address of the individual service provider being onboarded. |\n| `countryCode` | `string` | Yes | Two-letter ISO country code where the service provider is based, for example 'SE'. |\n| `merchantId` | `string` | Yes | Identifier of the merchant the individual service provider will be associated with. |\n| `spType` | `string` | No | Type of service provider being onboarded. Included only when provided. |\n| `config` | `object` | No | Optional fee configuration applied to the service provider. Included only when provided. |\n|     `feePercentage` | `number` | No | Percentage fee taken from each applicable transaction. |\n|     `feeFixedAmount` | `number` | No | Fixed fee amount in the smallest currency unit taken from each applicable transaction. |\n|     `deductApplicableTransactionFee` | `boolean` | No | Whether the applicable transaction fee is deducted from the service provider. |\n\n### Request Example\n```json\n{\n \"email\": \"harish@surfboard.se\",\n \"countryCode\": \"SE\",\n \"merchantId\": \"8385f437bc6d200b50\",\n \"spType\": \"INDIVIDUAL\",\n \"config\": {\n \"feePercentage\": 2.5,\n \"feeFixedAmount\": 100,\n \"deductApplicableTransactionFee\": true\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Details of the initiated individual onboarding. |\n|     `applicationId` | `string` | Unique identifier for the individual service provider application. |\n|     `signingLink` | `string` | Hosted URL where the individual signs the service provider agreement. |\n|     `signingSessionId` | `string` | Identifier of the signing session used to track the agreement. |\n|     `status` | `string` | Current status of the onboarding application. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"applicationId\": \"838ca3a7c530200810\",\n \"signingLink\": \"https://sign-dev.surfboardpayments.com/838ca3a7c530200810\",\n \"signingSessionId\": \"8391b7c2ad4e100722\",\n \"status\": \"APPLICATION_INITIATED\"\n },\n \"message\": \"Individual SP onboarding initiated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Missing required parameter 'merchantId' in initiate individual SP onboarding\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Link Service Provider to Merchant", "slug": "service-providers-link-service-provider-to-merchant", "description": "Associate an existing service provider with a merchant so the service provider becomes active on that merchant account. Use this once a service provider has been onboarded to start routing the merchant's applicable business through it.", "api": "Service Providers API", "method": "POST", "path": "/partners/:partnerId/merchants/:merchantId/service-providers/link", "content": "# Link Service Provider to Merchant\n\n## Overview\nAssociate an existing service provider with a merchant so the service provider becomes active on that merchant account. Use this once a service provider has been onboarded to start routing the merchant's applicable business through it.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /partners/:partnerId/merchants/:merchantId/service-providers/link\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `serviceProviderId` | `string` | Yes | Identifier of the service provider to link to the merchant. |\n\n### Request Example\n```json\n{\n \"serviceProviderId\": \"8385f437bc6d200b50\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Service provider linked to merchant successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Missing required parameter 'serviceProviderId' in link service provider for merchant\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Unlink Service Provider from Merchant", "slug": "service-providers-unlink-service-provider-from-merchant", "description": "Remove the association between a service provider and a merchant so the service provider is no longer active on that merchant account. Use this to stop routing the merchant's business through a service provider.", "api": "Service Providers API", "method": "DELETE", "path": "/partners/:partnerId/merchants/:merchantId/service-providers/unlink", "content": "# Unlink Service Provider from Merchant\n\n## Overview\nRemove the association between a service provider and a merchant so the service provider is no longer active on that merchant account. Use this to stop routing the merchant's business through a service provider.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /partners/:partnerId/merchants/:merchantId/service-providers/unlink\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `serviceProviderId` | `string` | Yes | Identifier of the service provider to unlink from the merchant. |\n\n### Request Example\n```json\n{\n \"serviceProviderId\": \"8385f437bc6d200b50\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Service provider unlinked from merchant successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Missing required parameter 'serviceProviderId' in unlink service provider for merchant\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Store (Merchant Scoped)", "slug": "stores-create-store-merchant-scoped", "description": "Creates a store directly under the authenticated merchant, without addressing the partner and merchant in the path. Use this when you are operating on behalf of a single merchant and want to spin up a new store to register terminals against. Supplying online store details also triggers domain verification so the store can accept online payments.", "api": "Stores API", "method": "POST", "path": "/stores", "content": "# Create Store (Merchant Scoped)\n\n## Overview\nCreates a store directly under the authenticated merchant, without addressing the partner and merchant in the path. Use this when you are operating on behalf of a single merchant and want to spin up a new store to register terminals against. Supplying online store details also triggers domain verification so the store can accept online payments.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /stores\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeName` | `string` | Yes | Name of the store as it should appear to staff and on reporting. |\n| `email` | `string` | No | Contact email address for the store. Required if you plan to enable online payments for the store. |\n| `phoneNumber` | `object` | No | Contact phone number of the store, split into dialing code and number. |\n|     `code` | `string` | Yes | International dialing code identifying the country or region. |\n|     `number` | `string` | Yes | The local phone number, 5 to 15 digits with no separators. |\n| `address` | `object` | Yes | Physical address of the store. City, postal code, and country code are required. |\n|     `careOf` | `string` | No | Name of the person or entity receiving correspondence on behalf of the store (c/o). |\n|     `addressLine1` | `string` | Yes | First line of the store's street address. |\n|     `addressLine2` | `string` | No | Second line of the store's street address. |\n|     `addressLine3` | `string` | No | Third line of the store's street address. |\n|     `city` | `string` | Yes | City where the store is located. |\n|     `countryCode` | `string` | Yes | Two-letter ISO 3166-1 alpha-2 country code in uppercase, representing where the store is located. |\n|     `postalCode` | `string` | Yes | Postal or ZIP code of the store's address. |\n| `acquirerMID` | `string` | No | Acquirer Merchant ID, required for payment facilitator partners that operate a store-based acquiring model. |\n| `onlineInfo` | `object` | No | Online store details. Provide these to turn the store into an online store that can accept web payments; doing so initiates domain verification. |\n|     `merchantWebshopURL` | `string` | Yes | The URL of the merchant's webshop. |\n|     `paymentPageHostURL` | `string` | No | The URL that hosts the payment page. Required when integrating online payments in SDK mode. |\n|     `termsAndConditionsURL` | `string` | Yes | URL of the webshop's terms and conditions, which must include the refund policy. |\n|     `privacyPolicyURL` | `string` | Yes | URL of the webshop's privacy policy. |\n|     `googlePayMerchantId` | `string` | No | Your Google Pay merchant identifier, used to enable Google Pay on the online store. |\n\n### Request Example\n```json\n{\n \"storeName\": \"Trial Store\",\n \"email\": \"integrations@surfboard.se\",\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"701234567\"\n },\n \"address\": {\n \"addressLine1\": \"Hagmarksgatan 3\",\n \"city\": \"Stockholm\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"103 16\"\n }\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Details of the created store. |\n|     `storeId` | `string` | Identifier of the newly created store. Use this when registering terminals or fetching the store's details. |\n|     `merchantUrlDomainVerificationKey` | `string` | Verification key to place on the merchant's webshop domain to prove ownership. Returned only when online store details were provided; null otherwise. |\n|     `paymentPageUrlDomainVerificationKey` | `string` | Verification key to place on the payment page host domain to prove ownership. Returned only when a payment page host URL was provided; null otherwise. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"storeId\": \"81d64e7174dcb00b0f\",\n \"merchantUrlDomainVerificationKey\": null,\n \"paymentPageUrlDomainVerificationKey\": null\n },\n \"message\": \"Store created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Mandatory address parameters missing\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n\n---" }, { "title": "Deactivate Store (Merchant Scoped)", "slug": "stores-deactivate-store-merchant-scoped", "description": "Deactivates a store belonging to the authenticated merchant. You can deactivate immediately or schedule deactivation for a future date. A store can only be deactivated once it has no terminals registered to it, so first delink or move any terminals to another store under the same merchant.", "api": "Stores API", "method": "POST", "path": "/stores/deactivate", "content": "# Deactivate Store (Merchant Scoped)\n\n## Overview\nDeactivates a store belonging to the authenticated merchant. You can deactivate immediately or schedule deactivation for a future date. A store can only be deactivated once it has no terminals registered to it, so first delink or move any terminals to another store under the same merchant.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /stores/deactivate\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | Yes | Identifier of the store to deactivate. |\n| `deactivationDate` | `string` | No | Future date on which the store should be deactivated, in yyyy-mm-dd format. When omitted, the store is deactivated immediately. |\n\n### Request Example\n```json\n{\n \"storeId\": \"824bd4a739dc200b0f\",\n \"deactivationDate\": \"2026-12-31\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the store deactivation. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Store deactivation initiated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Please provide a future date\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n\n---" }, { "title": "Fetch One Store (Merchant Scoped)", "slug": "stores-fetch-one-store-merchant-scoped", "description": "Retrieves the full details of a single store belonging to the authenticated merchant, including its address, contact details, lifecycle status, and any online store configuration.", "api": "Stores API", "method": "GET", "path": "/stores/:storeId", "content": "# Fetch One Store (Merchant Scoped)\n\n## Overview\nRetrieves the full details of a single store belonging to the authenticated merchant, including its address, contact details, lifecycle status, and any online store configuration.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `storeId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /stores/:storeId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /stores/:storeId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Details of the requested store. |\n|     `storeId` | `string` | Identifier of the store. |\n|     `merchantId` | `string` | Identifier of the merchant the store belongs to. |\n|     `name` | `string` | Name of the store. |\n|     `status` | `string` | Current lifecycle status of the store. Possible values: `ACTIVE`, `DEACTIVATED`, `BLOCKED`, `INACTIVE`. |\n|     `onlineOnboardingStatus` | `string` | Onboarding status of the store for online payments. Possible values: `APPROVED`, `INITIATED`, `FAILED`. |\n|     `address` | `object` | Physical address of the store. |\n|         `careOf` | `string` | Name of the person or entity receiving correspondence on behalf of the store (c/o). |\n|         `addressLine1` | `string` | First line of the store's street address. |\n|         `addressLine2` | `string` | Second line of the store's street address. |\n|         `addressLine3` | `string` | Third line of the store's street address. |\n|         `city` | `string` | City where the store is located. |\n|         `countryCode` | `string` | Two-letter ISO 3166-1 alpha-2 country code in uppercase. |\n|         `postalCode` | `string` | Postal or ZIP code of the store's address. |\n|     `onlineInfo` | `object` | Online store details, present only when the store is set up to accept online payments. |\n|         `merchantWebshopURL` | `string` | The URL of the merchant's webshop. |\n|         `paymentPageHostURL` | `string` | The URL that hosts the payment page. |\n|         `termsAndConditionsURL` | `string` | URL of the webshop's terms and conditions. |\n|         `privacyPolicyURL` | `string` | URL of the webshop's privacy policy. |\n|         `googlePayMerchantId` | `string` | The Google Pay merchant identifier configured for the online store. |\n|     `phoneNumber` | `object` | Contact phone number of the store, present only when one is set. |\n|         `code` | `string` | International dialing code of the store's phone number. |\n|         `number` | `string` | Local phone number of the store. |\n|     `email` | `string` | Contact email address of the store. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"storeId\": \"824bd4a739dc200b0f\",\n \"merchantId\": \"81a641f8b3cfd0070e\",\n \"name\": \"Trial Store\",\n \"status\": \"ACTIVE\",\n \"onlineOnboardingStatus\": \"APPROVED\",\n \"address\": {\n \"careOf\": null,\n \"addressLine1\": \"Hagmarksgatan 3\",\n \"addressLine2\": null,\n \"addressLine3\": null,\n \"city\": \"Stockholm\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"103 16\"\n },\n \"onlineInfo\": {\n \"merchantWebshopURL\": \"https://testmerchant.com\",\n \"paymentPageHostURL\": null,\n \"termsAndConditionsURL\": \"https://testmerchant.com/terms\",\n \"privacyPolicyURL\": \"https://testmerchant.com/privacy\",\n \"googlePayMerchantId\": null\n },\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"701234567\"\n },\n \"email\": \"integrations@surfboard.se\"\n },\n \"message\": \"Fetched store by ID\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to fetch store details.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `storeId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "List Stores (Merchant Scoped)", "slug": "stores-list-stores-merchant-scoped", "description": "Retrieves a paginated list of all stores that belong to the authenticated merchant. Use this to see every store you can register terminals against without addressing the partner and merchant in the path.", "api": "Stores API", "method": "GET", "path": "/stores", "content": "# List Stores (Merchant Scoped)\n\n## Overview\nRetrieves a paginated list of all stores that belong to the authenticated merchant. Use this to see every store you can register terminals against without addressing the partner and merchant in the path.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nGET /stores\n```\n\n### Pagination\n\nPage through results with the `x-page-number` request header. The total number of stores is returned in the `x-total-items` response header.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /stores?x-page-number=1\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The stores on the current page. |\n|     `storeId` | `string` | Identifier of the store. |\n|     `status` | `string` | Current lifecycle status of the store. Possible values: `ACTIVE`, `DEACTIVATED`, `BLOCKED`, `INACTIVE`. |\n|     `merchantId` | `string` | Identifier of the merchant the store belongs to. |\n|     `name` | `string` | Name of the store. |\n|     `address` | `object` | Physical address of the store. |\n|         `careOf` | `string` | Name of the person or entity receiving correspondence on behalf of the store (c/o). |\n|         `addressLine1` | `string` | First line of the store's street address. |\n|         `addressLine2` | `string` | Second line of the store's street address. |\n|         `addressLine3` | `string` | Third line of the store's street address. |\n|         `city` | `string` | City where the store is located. |\n|         `countryCode` | `string` | Two-letter ISO 3166-1 alpha-2 country code in uppercase. |\n|         `postalCode` | `string` | Postal or ZIP code of the store's address. |\n|     `onlineInfo` | `object` | Online store details, present only when the store is set up to accept online payments. |\n|         `merchantWebshopURL` | `string` | The URL of the merchant's webshop. |\n|         `paymentPageHostURL` | `string` | The URL that hosts the payment page. |\n|         `termsAndConditionsURL` | `string` | URL of the webshop's terms and conditions. |\n|         `privacyPolicyURL` | `string` | URL of the webshop's privacy policy. |\n|         `googlePayMerchantId` | `string` | The Google Pay merchant identifier configured for the online store. |\n|     `phoneNumber` | `object` | Contact phone number of the store, present only when one is set. |\n|         `code` | `string` | International dialing code of the store's phone number. |\n|         `number` | `string` | Local phone number of the store. |\n|     `email` | `string` | Contact email address of the store. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"storeId\": \"824bd4a739dc200b0f\",\n \"status\": \"ACTIVE\",\n \"merchantId\": \"81fa6b2d8d5dc8040e\",\n \"name\": \"Trial Store\",\n \"address\": {\n \"careOf\": null,\n \"addressLine1\": \"Hagmarksgatan 3\",\n \"addressLine2\": null,\n \"addressLine3\": null,\n \"city\": \"Stockholm\",\n \"countryCode\": \"SE\",\n \"postalCode\": \"103 16\"\n },\n \"onlineInfo\": null,\n \"phoneNumber\": {\n \"code\": \"46\",\n \"number\": \"701234567\"\n },\n \"email\": \"integrations@surfboard.se\"\n }\n ],\n \"message\": \"Fetched stores successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"No stores found under this merchant\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Change Terminal Store", "slug": "terminals-change-terminal-store", "description": "Changes the store to which a terminal is registered under a merchant. Use this API to move a terminal to another store created under the same merchant. The Terminal ID remains unchanged.", "api": "Terminals API", "method": "POST", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId/change", "content": "# Change Terminal Store\n\n## Overview\nChanges the store to which a terminal is registered under a merchant. Use this API to move a terminal to another store created under the same merchant. The Terminal ID remains unchanged.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /merchants/:merchantId/stores/:storeId/terminals/:terminalId/change\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `storeId` | `string` | No | Store ID of the destination store the terminal is moved to. |\n\n### Request Example\n```json\n{\n \"storeId\": \"st_GZVDbwmS86_G9pwc669U2\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the store change. |\n| `message` | `string` | A message that describes the status of the store change. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Store successfully changed for the terminal\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Deactivate Terminal under Store", "slug": "terminals-deactivate-terminal-under-store", "description": "Removes a terminal from a merchant's store. Use this API to deregister a terminal scoped to a specific store. You cannot reuse this terminal for another merchant, but you can use the Change Terminal Store API to move it to another store under the same merchant.", "api": "Terminals API", "method": "DELETE", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId", "content": "# Deactivate Terminal under Store\n\n## Overview\nRemoves a terminal from a merchant's store. Use this API to deregister a terminal scoped to a specific store. You cannot reuse this terminal for another merchant, but you can use the Change Terminal Store API to move it to another store under the same merchant.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /merchants/:merchantId/stores/:storeId/terminals/:terminalId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `message` | `string` | A message that describes the status of the terminal removal. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Terminal removed from store\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Partner Terminal Config", "slug": "terminals-fetch-partner-terminal-config", "description": "Use this API to fetch all currently active terminal configurations for the partner.", "api": "Terminals API", "method": "GET", "path": "/partners/:partnerId/terminals/config", "content": "# Fetch Partner Terminal Config\n\n## Overview\nUse this API to fetch all currently active terminal configurations for the partner.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/terminals/config\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/terminals/config\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `preferredRestartTime` | `string` | Scheduled restart time for the terminal in HH:MM format. The default is 02:00am according to the device's timezone. It has a 1 hour restart window. For example, if set to 02:00am, restart could occur anytime between 02:00am and 02:59am. It is essential for the device to restart at least once every 24 hours. This might be particularly important for businesses that operate beyond the default restart time. |\n|     `idleScreenImageUrl` | `string` | URL of the image displayed on the idle screen of the terminal. |\n|     `preferredNetwork` | `string` | Preferred network for the terminal. It can be either 'WIFI' or 'GSM'. |\n|     `wifiSsid` | `string` | Name of the WiFi network. |\n|     `wifiPassword` | `string` | Password for the WiFi network. |\n|     `language` | `string` | Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'. |\n|     `autoSleep` | `number` | Auto sleep time for the terminal in seconds. Terminal will sleep if no transactions are received in this time period. Only applies if the terminal is running on battery. |\n|     `alwaysShowMinorUnits` | `number` | Determines how the amount is displayed on the terminal. It can be either '0' or '1'. When set to '1', the terminal will always display the minor units, even for whole numbers (e.g., 29 will be displayed as 29.00). When set to 0, the terminal will not include minor units for whole numbers. |\n|     `showStatusBar` | `boolean` | Determines whether the status bar is displayed on the terminal. If set 'TRUE', the terminal will display the status bar. This is applicable to SurfPad terminals. |\n|     `showReceipt` | `boolean` | Set this to determine how receipts are showcased on the terminal. |\n|     `chipReadDelay` | `number` | Time delay in milliseconds before the card is read. |\n|     `openPosOnReboot` | `string` | Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'. |\n|     `lockScreenPin` | `string` | PIN code used to unlock the terminal's lock screen. |\n|     `refundScreenPin` | `string` | PIN code used to authorize refunds on the terminal. |\n|     `screenTimeout` | `number` | The duration (in milliseconds) before the screen times out due to inactivity. |\n|     `autoSleepInterval` | `number` | The interval (in milliseconds) before the device automatically goes to sleep. |\n|     `preferredGsmOperator` | `number` | The preferred GSM operator identified by a numeric code. |\n|     `enableRefundLock` | `boolean` | Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals. |\n|     `enableLockScreen` | `boolean` | Determines whether the lock screen is enabled on the terminal. |\n|     `printerConfig` | `string` | Printer configuration mode set for the terminal. |\n|     `receiptScreenTimeout` | `number` | Timeout of the receipt screen on hardware terminals. |\n|     `offlineMode` | `string` | Current offline-payments toggle for the terminal. Possible values: `enabled`, `disabled`. |\n|     `displayContrast` | `number` | Display contrast level of the terminal screen. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"preferredRestartTime\": \"02:00\",\n \"preferredNetwork\": \"WIFI\",\n \"wifiSsid\": \"surfboard\",\n \"wifiPassword\": \"surfboa\",\n \"language\": \"da\",\n \"autoSleep\": 400,\n \"alwaysShowMinorUnits\": 1,\n \"showStatusBar\": false,\n \"showReceipt\": true,\n \"chipReadDelay\": 500,\n \"openPosOnReboot\": \"enabled\",\n \"screenTimeout\": 3000000,\n \"preferredGsmOperator\": 2,\n \"enableRefundLock\": true\n },\n \"message\": \"Partner Terminal config queried successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Terminal by ID under Store", "slug": "terminals-fetch-terminal-by-id-under-store", "description": "Retrieves information about a specific terminal registered under a merchant's store. Use this API to get the details of a particular terminal scoped to a store.", "api": "Terminals API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId", "content": "# Fetch Terminal by ID under Store\n\n## Overview\nRetrieves information about a specific terminal registered under a merchant's store. Use this API to get the details of a particular terminal scoped to a store.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `terminalId` | `string` | Terminal ID of the terminal. |\n|     `terminalType` | `string` | Describes the type of the terminal. Possible values: `surfpad`, `surftouch`, `surfprint`, `checkoutPro`, `checkoutX`, `PaymentPage`, `SelfHostedPage`, `iFrame`, `MerchantInitiated`. |\n|     `softwareVersion` | `string` | Software version of the terminal. |\n|     `osType` | `string` | Describes the type of Operating System (OS) running on the terminal. Possible values: `android`, `ios`, `sb_firmware`. |\n|     `osVersion` | `string` | Operating System (OS) version of the terminal. |\n|     `deviceVendor` | `string` | Device vendor of the terminal. |\n|     `deviceModel` | `string` | Device model of the terminal. |\n|     `serialNo` | `string` | Serial number of the terminal. |\n|     `storeId` | `string` | The Store ID of the store under which the terminal is registered. |\n|     `linkedTerminalId` | `string` | The Terminal ID of another terminal to which the current terminal is linked. |\n|     `terminalStatus` | `string` | Status of the terminal, it can be in one of these states: REGISTERED \\| ACTIVE \\| IN_ACTIVE \\| DE_REGISTERED. |\n|     `terminalPaymentMethods` | `string` | Payment methods supported by the terminal. |\n|     `startDate` | `string` | Timestamp at which the terminal was created. |\n|     `terminalName` | `string` | Name of the terminal used as a reference for users. |\n|     `lastAliveAt` | `string` | Time at which the terminal was last seen online. |\n|     `isCharging` | `boolean` | A boolean value that denotes if the terminal is charging or not. |\n|     `batteryPercentage` | `number` | Battery percentage of the terminal. |\n|     `powerSource` | `string` | Current power source to the terminal. Possible values: `EXTERNAL_POWER`, `BATTERY`. |\n|     `deviceNetwork` | `string` | The current mode of communication. Possible values: `WIFI`, `GSM`. |\n|     `turnOnTime` | `string` | Last boot up time of terminal. |\n|     `terminalPublicKey` | `string` | Public key used while initializing the SelfHostedPage Online Terminal (Online SDK). |\n|     `metadata` | `object` | Arbitrary key-value metadata stored against the terminal. |\n|     `wifiStrength` | `number` | Wi-Fi signal strength reported by the terminal. |\n|     `gsmStrength` | `number` | GSM signal strength reported by the terminal. |\n|     `signalStrength` | `number` | Overall network signal strength reported by the terminal. |\n|     `softwareMode` | `string` | Software mode the terminal is running in. |\n|     `sdkUrl` | `string` | SDK URL associated with the terminal. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"terminalId\": \"81f878852b3a280904\",\n \"terminalType\": \"surfpad\",\n \"softwareVersion\": \"0.0.0\",\n \"osType\": \"sb_firmware\",\n \"osVersion\": \"0.0.0\",\n \"deviceVendor\": \"Datecs\",\n \"deviceModel\": \"Datecs PinPad\",\n \"serialNo\": \"2922000007\",\n \"storeId\": \"81497439a52270000f\",\n \"linkedTerminalId\": null,\n \"terminalStatus\": \"ACTIVE\",\n \"startDate\": \"2022-11-17T09:29:51.427Z\",\n \"terminalPaymentMethods\": [\n \"CARD\"\n ],\n \"terminalName\": \"My Terminal\",\n \"lastAliveAt\": \"2024-02-21T08:48:26.000Z\",\n \"isCharging\": false,\n \"batteryPercentage\": 100,\n \"powerSource\": \"BATTERY\",\n \"deviceNetwork\": \"WIFI\",\n \"turnOnTime\": \"2024-02-21T05:14:33.417Z\"\n },\n \"message\": \"Fetched terminal details successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Fetch Terminal Metrics", "slug": "terminals-fetch-terminal-metrics", "description": "Retrieves metric time-series data for a terminal, such as battery status and network strength. Use this API to monitor the health and connectivity of a terminal over time. You can optionally filter the metrics by event type and date range.", "api": "Terminals API", "method": "GET", "path": "/terminals/:terminalId/metrics", "content": "# Fetch Terminal Metrics\n\n## Overview\nRetrieves metric time-series data for a terminal, such as battery status and network strength. Use this API to monitor the health and connectivity of a terminal over time. You can optionally filter the metrics by event type and date range.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /terminals/:terminalId/metrics\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `event` | `string` | No | Metric event type to filter by. Must be one of the accepted values: BATTERY_STATUS, NETWORK_STRENGTH, AGGREGATED_BATTERY_PERCENTAGE, AGGREGATED_CHARGING_STATE, AGGREGATED_POWER_SOURCE, AGGREGATED_GSM_CONNECTION_TYPE, AGGREGATED_GSM_SIGNAL_STRENGTH, AGGREGATED_WIFI_SIGNAL_STRENGTH or AGGREGATED_NETWORK_TYPE. |\n| `queryDates` | `string` | No | One or more dates to scope the metrics query. A single value is accepted and wrapped into an array. |\n\n### Pagination\n\nTo filter the metrics, send in `event` and `queryDates` as query params. This endpoint is paginated. Send the `x-page-number` request header to page through the results (default 1). Each response returns the `x-total-items` header (total number of matching records) and the `x-page-number` header (the page that was served).\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /terminals/:terminalId/metrics?event=value&queryDates=value\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request. |\n| `data` | `array` | List of terminal metric series, one per requested event. |\n|     `terminalId` | `string` | Terminal ID of the terminal the metric belongs to. |\n|     `event` | `string` | Metric event type of the series. |\n|     `data` | `object` | Metric data of the series. |\n|         `value` | `array` | Time-ordered list of metric samples. |\n|             `time` | `string` | Timestamp of the sample. |\n|             `value` | `string` | Value of the sample, which can be a string or a boolean. |\n| `message` | `string` | Status message of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"terminalId\": \"81f878852b3a280904\",\n \"event\": \"BATTERY_STATUS\",\n \"data\": {\n \"value\": [\n {\n \"time\": \"2024-02-21T08:48:26.000Z\",\n \"value\": \"100\"\n }\n ]\n }\n }\n ],\n \"message\": \"Fetched terminal metrics successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Get Entry Code", "slug": "terminals-get-entry-code", "description": "Generates an entry code for a terminal under a merchant's store. Use this API to obtain the entry code, its registration code identifier, and the validity window for the terminal.", "api": "Terminals API", "method": "GET", "path": "/merchants/:merchantId/stores/:storeId/terminals/:terminalId/entry-code", "content": "# Get Entry Code\n\n## Overview\nGenerates an entry code for a terminal under a merchant's store. Use this API to obtain the entry code, its registration code identifier, and the validity window for the terminal.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId/entry-code\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/stores/:storeId/terminals/:terminalId/entry-code\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `registrationCodeId` | `string` | Identifier of the registration code associated with the entry code. |\n|     `validUntil` | `string` | Lifetime of the entry code in seconds, returned as a string. |\n|     `entryCode` | `string` | The generated entry code for the terminal. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"registrationCodeId\": \"81f878852b3a280904\",\n \"validUntil\": \"120\",\n \"entryCode\": \"905788\"\n },\n \"message\": \"Fetched entry code\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Port Partner Terminals", "slug": "terminals-port-partner-terminals", "description": "Ports a batch of terminals to a target merchant under a partner. Use this API to bulk reassign terminals, specifying the destination store for each terminal. This is limited to partners who handle their own storage and deal with terminals in bulk.", "api": "Terminals API", "method": "PUT", "path": "/partners/:partnerId/terminals/port", "content": "# Port Partner Terminals\n\n## Overview\nPorts a batch of terminals to a target merchant under a partner. Use this API to bulk reassign terminals, specifying the destination store for each terminal. This is limited to partners who handle their own storage and deal with terminals in bulk.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /partners/:partnerId/terminals/port\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalDetails` | `array` | Yes | List of terminals to port to the target merchant. |\n|     `serialNo` | `string` | Yes | Serial number of the terminal to port. |\n|     `storeId` | `string` | Yes | Store ID the terminal should be assigned to under the target merchant. |\n| `targetMerchantId` | `string` | Yes | Merchant ID of the merchant the terminals are ported to. |\n\n### Request Example\n```json\n{\n \"targetMerchantId\": \"81fa6b2d8d5dc8040e\",\n \"terminalDetails\": [\n {\n \"serialNo\": \"2922000007\",\n \"storeId\": \"st_GZVDbwmS86_G9pwc669U2\"\n }\n ]\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | Response data. Each entry reports the per-terminal port outcome. |\n|     `status` | `string` | Port status of the terminal. |\n|     `serialNo` | `string` | Serial number of the ported terminal. |\n|     `terminalId` | `string` | Terminal ID of the resulting terminal. |\n|     `registrationInfo` | `object` | Registration information of the ported terminal. |\n|     `errorMessage` | `string` | Error message describing why the terminal failed to port, when applicable. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"status\": \"SUCCESS\",\n \"serialNo\": \"2922000007\",\n \"terminalId\": \"81f878852b3a280904\",\n \"registrationInfo\": {},\n \"errorMessage\": \"\"\n }\n ],\n \"message\": \"Terminals of partner ported successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Publish Terminal Image and Config", "slug": "terminals-publish-terminal-image-and-config", "description": "Publishes the configuration and idle screen image to a terminal under a partner's merchant and store. Use this API to push the currently configured terminal settings and image to a specific terminal.", "api": "Terminals API", "method": "PUT", "path": "/partners/:partnerId/merchants/:merchantId/stores/:storeId/terminals/:terminalId/config", "content": "# Publish Terminal Image and Config\n\n## Overview\nPublishes the configuration and idle screen image to a terminal under a partner's merchant and store. Use this API to push the currently configured terminal settings and image to a specific terminal.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `merchantId` in the URL path must exist.\n- The resource identified by `storeId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /partners/:partnerId/merchants/:merchantId/stores/:storeId/terminals/:terminalId/config\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n| `storeId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `offlineMode` | `string` | No | Controls whether the terminal keeps accepting card payments while offline (stored and forwarded once connectivity returns). Applies to the sb_terminal_k checkout app. Possible values: `enabled`, `disabled`. |\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `preferredRestartTime` | `string` | Scheduled restart time for the terminal in HH:MM format. The default is 02:00am according to the device's timezone. It has a 1 hour restart window. For example, if set to 02:00am, restart could occur anytime between 02:00am and 02:59am. It is essential for the device to restart at least once every 24 hours. This might be particularly important for businesses that operate beyond the default restart time. |\n|     `idleScreenImageUrl` | `string` | URL of the image displayed on the idle screen of the terminal. |\n|     `preferredNetwork` | `string` | Preferred network for the terminal. It can be either 'WIFI' or 'GSM'. |\n|     `wifiSsid` | `string` | Name of the WiFi network. |\n|     `wifiPassword` | `string` | Password for the WiFi network. |\n|     `language` | `string` | Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'. |\n|     `autoSleep` | `number` | Auto sleep time for the terminal in seconds. Terminal will sleep if no transactions are received in this time period. Only applies if the terminal is running on battery. |\n|     `alwaysShowMinorUnits` | `number` | Determines how the amount is displayed on the terminal. It can be either '0' or '1'. When set to '1', the terminal will always display the minor units, even for whole numbers (e.g., 29 will be displayed as 29.00). When set to 0, the terminal will not include minor units for whole numbers. |\n|     `showStatusBar` | `boolean` | Determines whether the status bar is displayed on the terminal. If set 'TRUE', the terminal will display the status bar. This is applicable to SurfPad terminals. |\n|     `showReceipt` | `boolean` | Set this to determine how receipts are showcased on the terminal. |\n|     `chipReadDelay` | `number` | Time delay in milliseconds before the card is read. |\n|     `openPosOnReboot` | `string` | Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'. |\n|     `lockScreenPin` | `string` | PIN code used to unlock the terminal's lock screen. |\n|     `refundScreenPin` | `string` | PIN code used to authorize refunds on the terminal. |\n|     `screenTimeout` | `number` | The duration (in milliseconds) before the screen times out due to inactivity. |\n|     `autoSleepInterval` | `number` | The interval (in milliseconds) before the device automatically goes to sleep. |\n|     `preferredGsmOperator` | `number` | The preferred GSM operator identified by a numeric code. |\n|     `enableRefundLock` | `boolean` | Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals. |\n|     `enableLockScreen` | `boolean` | Determines whether the lock screen is enabled on the terminal. |\n|     `printerConfig` | `string` | Printer configuration mode set for the terminal. |\n|     `receiptScreenTimeout` | `number` | Timeout of the receipt screen on hardware terminals. |\n|     `offlineMode` | `string` | Current offline-payments toggle for the terminal. Possible values: `enabled`, `disabled`. |\n|     `displayContrast` | `number` | Display contrast level of the terminal screen. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"preferredRestartTime\": \"02:00\",\n \"preferredNetwork\": \"WIFI\",\n \"wifiSsid\": \"surfboard\",\n \"wifiPassword\": \"surfboa\",\n \"language\": \"da\",\n \"autoSleep\": 400,\n \"alwaysShowMinorUnits\": 1,\n \"showStatusBar\": false,\n \"showReceipt\": true,\n \"chipReadDelay\": 500,\n \"openPosOnReboot\": \"enabled\",\n \"screenTimeout\": 3000000,\n \"preferredGsmOperator\": 2,\n \"enableRefundLock\": true\n },\n \"message\": \"Terminal config published successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- The `storeId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Query Terminals Under Merchant", "slug": "terminals-query-terminals-under-merchant", "description": "Retrieves all the terminals registered under a merchant. Use this API to list every terminal associated with the merchant. You can optionally filter the results by terminal type.", "api": "Terminals API", "method": "GET", "path": "/merchants/:merchantId/terminals", "content": "# Query Terminals Under Merchant\n\n## Overview\nRetrieves all the terminals registered under a merchant. Use this API to list every terminal associated with the merchant. You can optionally filter the results by terminal type.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `merchantId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /merchants/:merchantId/terminals\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `merchantId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalType` | `string` | No | Filters the terminals by type. For example 'surfpad', 'surftouch', 'surfprint', 'checkoutPro', 'checkoutX' or 'iFrame'. |\n\n### Pagination\n\nTo filter the terminals by type send in `terminalType` as a query param. This endpoint is paginated. Send the `x-page-number` request header to page through the results (default 1). Each response returns the `x-total-items` header (total number of matching records) and the `x-page-number` header (the page that was served).\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /merchants/:merchantId/terminals?terminalType=value\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | Response data. |\n|     `terminalId` | `string` | Terminal ID of the terminal. |\n|     `terminalType` | `string` | Describes the type of the terminal, for example 'surfpad', 'surftouch', 'surfprint', 'checkoutPro', 'checkoutX' or 'iFrame'. |\n|     `softwareVersion` | `string` | Software version of the terminal. |\n|     `osType` | `string` | Describes the type of Operating System (OS) running on the terminal. |\n|     `osVersion` | `string` | Operating System (OS) version of the terminal. |\n|     `deviceVendor` | `string` | Device vendor of the terminal. |\n|     `deviceModel` | `string` | Device model of the terminal. |\n|     `serialNo` | `string` | Serial number of the terminal. |\n|     `lastAliveAt` | `string` | Timestamp of the last time the terminal was seen alive. |\n|     `isCharging` | `boolean` | Whether the terminal is currently charging. |\n|     `batteryPercentage` | `number` | Current battery charge level of the terminal, as a percentage. |\n|     `wifiStrength` | `number` | Wi-Fi signal strength of the terminal. |\n|     `gsmStrength` | `number` | GSM signal strength of the terminal. |\n|     `powerSource` | `string` | Power source the terminal is currently using. |\n|     `deviceNetwork` | `string` | Network the terminal device is connected to. |\n|     `turnOnTime` | `string` | Timestamp of when the terminal was last turned on. |\n|     `softwareMode` | `string` | The software mode the terminal is running in. |\n|     `terminalPublicKey` | `string` | The public key of the terminal. |\n|     `signalStrength` | `number` | Overall signal strength reported by the terminal. |\n|     `sdkUrl` | `string` | The SDK server URL, present for self-hosted SDK terminals. |\n|     `storeId` | `string` | The Store ID of the store under which the terminal is registered. |\n|     `linkedTerminalId` | `string` | The Terminal ID of another terminal to which the current terminal is linked. |\n|     `terminalStatus` | `string` | Status of the terminal, it can be in one of these states: REGISTERED \\| ACTIVE \\| IN_ACTIVE \\| DE_REGISTERED. |\n|     `startDate` | `string` | Timestamp at which the terminal was created. |\n|     `terminalPaymentMethods` | `string` | Payment methods supported by the terminal. |\n|     `terminalName` | `string` | Name of the terminal used as a reference for users. |\n|     `terminalCurrencyCode` | `string` | Currency code associated with the terminal. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"terminalId\": \"81f878852b3a280904\",\n \"terminalType\": \"surfpad\",\n \"serialNo\": \"2922000007\",\n \"storeId\": \"81497439a52270000f\",\n \"terminalStatus\": \"ACTIVE\",\n \"terminalName\": \"My Terminal\",\n \"terminalCurrencyCode\": \"NA\"\n }\n ],\n \"message\": \"Fetched terminals successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `merchantId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Query Terminals Under Partner", "slug": "terminals-query-terminals-under-partner", "description": "Retrieves the terminals registered under a partner. Use this API to look up a terminal by its Terminal ID or serial number. When the path value is longer than 13 characters it is treated as a Terminal ID, otherwise it is treated as a serial number.", "api": "Terminals API", "method": "GET", "path": "/partners/:partnerId/terminals/:terminalId", "content": "# Query Terminals Under Partner\n\n## Overview\nRetrieves the terminals registered under a partner. Use this API to look up a terminal by its Terminal ID or serial number. When the path value is longer than 13 characters it is treated as a Terminal ID, otherwise it is treated as a serial number.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n- The resource identified by `terminalId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/terminals/:terminalId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n| `terminalId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Pagination\n\nThis endpoint is paginated. Send the `x-page-number` request header to page through the results (default 1). Each response returns the `x-total-items` header (total number of matching records) and the `x-page-number` header (the page that was served).\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/terminals/:terminalId\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | Response data. |\n|     `terminalId` | `string` | Terminal ID of the terminal. |\n|     `terminalType` | `string` | Describes the type of the terminal, for example 'surfpad', 'surftouch', 'surfprint', 'checkoutPro', 'checkoutX' or 'iFrame'. |\n|     `softwareVersion` | `string` | Software version of the terminal. |\n|     `osType` | `string` | Describes the type of Operating System (OS) running on the terminal. |\n|     `osVersion` | `string` | Operating System (OS) version of the terminal. |\n|     `deviceVendor` | `string` | Device vendor of the terminal. |\n|     `deviceModel` | `string` | Device model of the terminal. |\n|     `serialNo` | `string` | Serial number of the terminal. |\n|     `lastAliveAt` | `string` | Timestamp of the last time the terminal was seen alive. |\n|     `isCharging` | `boolean` | Whether the terminal is currently charging. |\n|     `batteryPercentage` | `number` | Current battery charge level of the terminal, as a percentage. |\n|     `wifiStrength` | `number` | Wi-Fi signal strength of the terminal. |\n|     `gsmStrength` | `number` | GSM signal strength of the terminal. |\n|     `powerSource` | `string` | Power source the terminal is currently using. |\n|     `deviceNetwork` | `string` | Network the terminal device is connected to. |\n|     `turnOnTime` | `string` | Timestamp of when the terminal was last turned on. |\n|     `softwareMode` | `string` | The software mode the terminal is running in. |\n|     `terminalPublicKey` | `string` | The public key of the terminal. |\n|     `signalStrength` | `number` | Overall signal strength reported by the terminal. |\n|     `sdkUrl` | `string` | The SDK server URL, present for self-hosted SDK terminals. |\n|     `storeId` | `string` | The Store ID of the store under which the terminal is registered. |\n|     `linkedTerminalId` | `string` | The Terminal ID of another terminal to which the current terminal is linked. |\n|     `terminalStatus` | `string` | Status of the terminal, it can be in one of these states: REGISTERED \\| ACTIVE \\| IN_ACTIVE \\| DE_REGISTERED. |\n|     `startDate` | `string` | Timestamp at which the terminal was created. |\n|     `terminalPaymentMethods` | `string` | Payment methods supported by the terminal. |\n|     `terminalName` | `string` | Name of the terminal used as a reference for users. |\n|     `merchantId` | `string` | The Merchant ID of the merchant under which the terminal is registered. |\n|     `terminalCurrencyCode` | `string` | Currency code associated with the terminal. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"terminalId\": \"81f878852b3a280904\",\n \"terminalType\": \"surfpad\",\n \"serialNo\": \"2922000007\",\n \"storeId\": \"81497439a52270000f\",\n \"terminalStatus\": \"ACTIVE\",\n \"terminalName\": \"My Terminal\",\n \"merchantId\": \"81fa6b2d8d5dc8040e\",\n \"terminalCurrencyCode\": \"NA\"\n }\n ],\n \"message\": \"Fetched terminals successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n- The `terminalId` is part of the URL path and must be a valid identifier.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Query Partner Terminal Configs", "slug": "terminals-query-partner-terminal-configs", "description": "Retrieves the allowed external software versions for a partner. Use this API to fetch the configurations applicable at the partner, merchant, store, or terminal scope. The scope is selected based on the query param provided, in priority order: terminalId, then storeId, then merchantId, otherwise the partner scope.", "api": "Terminals API", "method": "GET", "path": "/partners/:partnerId/terminal-configs", "content": "# Query Partner Terminal Configs\n\n## Overview\nRetrieves the allowed external software versions for a partner. Use this API to fetch the configurations applicable at the partner, merchant, store, or terminal scope. The scope is selected based on the query param provided, in priority order: terminalId, then storeId, then merchantId, otherwise the partner scope.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nGET /partners/:partnerId/terminal-configs\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Query Parameters\n\nTo select the config scope, send in `terminalId`, `storeId` or `merchantId` as a query param.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `terminalId` | `string` | No | Selects the TERMINAL config scope. This has the highest priority. |\n| `storeId` | `string` | No | Selects the STORE config scope when terminalId is absent. |\n| `merchantId` | `string` | No | Selects the MERCHANT config scope when terminalId and storeId are absent. When none of these are provided, the scope defaults to PARTNER. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /partners/:partnerId/terminal-configs?terminalId=value&storeId=value&merchantId=value\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Response data. |\n|     `allowedExternalSoftwareVersions` | `array` | List of allowed external software versions. Defaults to an empty array when none are configured. |\n|         `type` | `string` | Type of the external software. |\n|         `version` | `string` | Version of the external software. |\n|         `softwareId` | `string` | Identifier of the external software. |\n|         `minVersion` | `string` | Minimum supported version of the external software. |\n|         `isPos` | `boolean` | Indicates whether the software is a POS application. |\n|         `terminalType` | `string` | Terminal type the software applies to. |\n|         `deviceType` | `string` | Device type the software applies to. |\n|         `overrideLevel` | `string` | Scope at which the configuration is overridden. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"allowedExternalSoftwareVersions\": [\n {\n \"type\": \"pos\",\n \"version\": \"1.2.0\",\n \"softwareId\": \"81fa6b2d8d5dc8040e\",\n \"minVersion\": \"1.0.0\",\n \"isPos\": true,\n \"terminalType\": \"surftouch\",\n \"deviceType\": \"android\",\n \"overrideLevel\": \"PARTNER\"\n }\n ]\n },\n \"message\": \"Terminal configs fetched successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request parameters.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Update Partner Terminal Config", "slug": "terminals-update-partner-terminal-config", "description": "Sets terminal configuration for the terminals under a partner. All config fields are optional and only the provided ones are applied.", "api": "Terminals API", "method": "PATCH", "path": "/partners/:partnerId/terminals", "content": "# Update Partner Terminal Config\n\n## Overview\nSets terminal configuration for the terminals under a partner. All config fields are optional and only the provided ones are applied.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `partnerId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPATCH /partners/:partnerId/terminals\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `partnerId` | `string` | Yes | Identifier supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `preferredRestartTime` | `string` | No | Scheduled restart time for the terminal in HH:MM format. The default is 02:00am according to the device's timezone. It has a 1 hour restart window. For example, if set to 02:00am, restart could occur anytime between 02:00am and 02:59am. It is essential for the device to restart at least once every 24 hours. |\n| `idleScreenImageUrl` | `string` | No | URL of the image displayed on the idle screen of the terminal. |\n| `autoSleep` | `number` | No | Auto sleep time for the terminal in seconds. Terminal will sleep if no transactions are received in this time period. Only applies if the terminal is running on battery. |\n| `showStatusBar` | `boolean` | No | Determines whether the status bar is displayed on the terminal. If set 'TRUE', the terminal will display the status bar. This is applicable to SurfPad terminals. |\n| `screenTimeout` | `number` | No | The duration (in milliseconds) before the screen times out due to inactivity. |\n| `autoSleepInterval` | `number` | No | The interval (in milliseconds) before the device automatically goes to sleep. |\n| `printerConfig` | `string` | No | Printer configuration mode for the terminal. |\n| `receiptScreenTimeout` | `number` | No | Timeout of the receipt screen on hardware terminals. |\n| `showReceipt` | `boolean` | No | Set this to determine how receipts are showcased on the terminal. |\n| `language` | `string` | No | Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'. |\n| `alwaysShowMinorUnits` | `number` | No | Determines how the amount is displayed on the terminal. It can be either '0' or '1'. When set to '1', the terminal will always display the minor units, even for whole numbers (e.g., 29 will be displayed as 29.00). When set to 0, the terminal will not include minor units for whole numbers. |\n| `openPosOnReboot` | `string` | No | Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'. |\n| `chipReadDelay` | `number` | No | Time delay in milliseconds before the card is read. |\n| `lockScreenPin` | `string` | No | PIN code used to unlock the terminal's lock screen. |\n| `refundScreenPin` | `string` | No | PIN code used to authorize refunds on the terminal. |\n| `enableRefundLock` | `boolean` | No | Determines whether refunds require the refund PIN. |\n| `enableLockScreen` | `boolean` | No | Determines whether the lock screen is enabled on the terminal. |\n| `wifiSsid` | `string` | No | Name of the WiFi network. |\n| `wifiPassword` | `string` | No | Password for the WiFi network. |\n| `preferredGsmOperator` | `number` | No | The preferred GSM operator identified by a numeric code. |\n| `preferredNetwork` | `string` | No | Preferred network for the terminal. It can be either 'WIFI' or 'GSM'. |\n| `offlineMode` | `string` | No | Controls whether the terminal keeps accepting card payments while offline (stored and forwarded once connectivity returns). Applies to the sb_terminal_k checkout app. Possible values: `enabled`, `disabled`. |\n\n### Request Example\n```json\n{\n \"wifiSsid\": \"wifiname\",\n \"wifiPassword\": \"wifipassword\",\n \"autoSleep\": 3000,\n \"preferredNetwork\": \"WIFI\",\n \"preferredRestartTime\": \"03:00\",\n \"alwaysShowMinorUnits\": 1,\n \"language\": \"en\",\n \"showStatusBar\": true,\n \"chipReadDelay\": 500,\n \"showReceipt\": true\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, indicated as either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"PARTNER config updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Invalid request body.\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- The `partnerId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "List Transactions by Date Range", "slug": "transactions-list-transactions-by-date-range", "description": "The same paginated transaction list as List Transactions, but the date range is supplied as `start` and `end` query parameters. The response is identical; use whichever parameter names fit your integration.", "api": "Transactions API", "method": "GET", "path": "/transactions/range", "content": "# List Transactions by Date Range\n\n## Overview\nThe same paginated transaction list as List Transactions, but the date range is supplied as `start` and `end` query parameters. The response is identical; use whichever parameter names fit your integration.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nGET /transactions/range\n```\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `start` | `string` | No | Start of the date range to fetch transactions for (ISO 8601, e.g. 2026-06-01). |\n| `end` | `string` | No | End of the date range. If start is supplied without end, a 24-hour window from start is used. |\n| `storeId` | `string` | No | Return only transactions that took place at this store. |\n| `terminalId` | `string` | No | Return only transactions processed by this terminal (checkout). |\n\n### Pagination\n\nPage through results with the `x-page-number` request header. The total number of matching transactions is returned in the `x-total-items` response header.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /transactions/range?start=2026-06-01&end=2026-06-30&storeId=st_2a91&terminalId=t_7c33\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The transactions on the current page. |\n|     `transactionId` | `string` | Unique identifier of the transaction. |\n|     `merchantId` | `string` | Identifier of the merchant the transaction belongs to. |\n|     `storeId` | `string` | Identifier of the store where the transaction took place. |\n|     `terminalId` | `string` | Identifier of the terminal (checkout) that processed the transaction. |\n|     `orderId` | `string` | Identifier of the order the transaction settled. |\n|     `paymentId` | `string` | Identifier of the payment that produced the transaction. |\n|     `referenceId` | `string` | Your own reference, supplied when the payment was created. |\n|     `rrn` | `string` | Retrieval reference number assigned by the acquirer. |\n|     `amount` | `number` | Transaction amount, in the smallest unit of the currency (e.g. öre for SEK). |\n|     `currency` | `string` | ISO 4217 currency code of the transaction. |\n|     `method` | `string` | Payment method used, for example CARD, SWISH or GIFT_CARD. |\n|     `type` | `string` | Transaction type, for example PURCHASE or RETURN. |\n|     `orderSummary` | `string` | Short, human-readable summary of the order. |\n|     `timestamp` | `string` | When the transaction was created, in ISO 8601 format. |\n|     `voided` | `boolean` | Whether the transaction was voided. |\n|     `issuerCountry` | `string` | Country of the card issuer, reported at settlement. |\n|     `interchangeDomain` | `string` | Interchange domain the card falls under, for example domestic or intra-regional. |\n|     `cardCategory` | `string` | Card category reported at settlement, for example consumer or commercial. |\n|     `cardUsage` | `string` | Card funding type reported at settlement, for example debit or credit. |\n|     `fee` | `number` | Surfboard fee charged on the transaction, in the smallest currency unit. |\n|     `feeVat` | `number` | VAT charged on the Surfboard fee, in the smallest currency unit. |\n|     `settlementStatus` | `string` | Settlement state of the transaction; NOT_SETTLED until it is paid out. |\n|     `payout` | `number` | Amount paid out to the merchant for this transaction, in the smallest currency unit. |\n|     `settlementRef` | `string` | Reference of the settlement batch the transaction was paid out in. |\n|     `settlementDate` | `string` | Date the transaction was paid out to the merchant. |\n|     `truncatedPan` | `string` | Last four digits of the card number (PAN), zero-padded to four characters. |\n|     `cardLabel` | `string` | Application label of the card scheme used (the AID name). |\n|     `posEntryMode` | `string` | How the card was presented at the point of sale (entry mode). |\n|     `issuerApplication` | `string` | Issuer application data returned by the card. |\n|     `terminalVerificationResult` | `string` | Terminal verification results (TVR) from the card interaction. |\n|     `aid` | `string` | Application identifier (AID) of the card scheme used. |\n|     `customerResponseCode` | `string` | Response code returned by the card issuer. |\n|     `cvmMethod` | `string` | Cardholder verification method code used during the transaction. |\n|     `cvmMethodDescription` | `string` | Human-readable description of the cardholder verification method (e.g. 'Online PIN', 'No CVM'). |\n|     `authMode` | `string` | Authorization mode; ISSUER when the issuer authorized the transaction. |\n|     `cardBrand` | `string` | Card brand, for example VISA or MASTERCARD. |\n|     `authCode` | `string` | Authorization code returned by the issuer. |\n|     `adjustments` | `array` | Tip or amount adjustments applied to the transaction. Present only when adjustments exist. |\n|         `type` | `string` | The kind of adjustment, for example TIP. |\n|         `amount` | `number` | Adjustment amount, in the smallest currency unit. |\n|         `adjustmentId` | `string` | Unique identifier of the adjustment. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"transactionId\": \"txn_8f21c0a9b7\",\n \"merchantId\": \"m_5f2c1a9b3d\",\n \"storeId\": \"st_2a91\",\n \"terminalId\": \"t_7c33\",\n \"orderId\": \"ord_4b19d2\",\n \"paymentId\": \"pay_a71f\",\n \"referenceId\": \"order-2026-0012\",\n \"rrn\": \"618234501122\",\n \"amount\": 14900,\n \"currency\": \"SEK\",\n \"method\": \"CARD\",\n \"type\": \"PURCHASE\",\n \"orderSummary\": \"2x Flat White\",\n \"timestamp\": \"2026-06-01T09:24:11.000Z\",\n \"voided\": false,\n \"settlementStatus\": \"SETTLED\",\n \"fee\": 268,\n \"feeVat\": 67,\n \"payout\": 14632,\n \"cardBrand\": \"VISA\",\n \"truncatedPan\": \"0341\",\n \"cardLabel\": \"VISA CREDIT\",\n \"authMode\": \"ISSUER\"\n }\n ],\n \"message\": \"Fetched all transactions under merchant\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to fetch transactions\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "List Transactions", "slug": "transactions-list-transactions", "description": "Retrieve a paginated list of the authenticated merchant's transactions. Narrow the results to a date range, a single store, or a single terminal. When a start date is given without an end date, a 24-hour window from the start date is used.", "api": "Transactions API", "method": "GET", "path": "/transactions", "content": "# List Transactions\n\n## Overview\nRetrieve a paginated list of the authenticated merchant's transactions. Narrow the results to a date range, a single store, or a single terminal. When a start date is given without an end date, a 24-hour window from the start date is used.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nGET /transactions\n```\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `startDate` | `string` | No | Start of the date range to fetch transactions for (ISO 8601, e.g. 2026-06-01). When omitted, results are not date-filtered. |\n| `endDate` | `string` | No | End of the date range. If a startDate is supplied without an endDate, a 24-hour window from startDate is used. |\n| `storeId` | `string` | No | Return only transactions that took place at this store. |\n| `terminalId` | `string` | No | Return only transactions processed by this terminal (checkout). |\n\n### Pagination\n\nPage through results with the `x-page-number` request header. The total number of matching transactions is returned in the `x-total-items` response header.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `x-page-number` | `1` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /transactions?startDate=2026-06-01&endDate=2026-06-30&storeId=st_2a91&terminalId=t_7c33\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The transactions on the current page. |\n|     `transactionId` | `string` | Unique identifier of the transaction. |\n|     `merchantId` | `string` | Identifier of the merchant the transaction belongs to. |\n|     `storeId` | `string` | Identifier of the store where the transaction took place. |\n|     `terminalId` | `string` | Identifier of the terminal (checkout) that processed the transaction. |\n|     `orderId` | `string` | Identifier of the order the transaction settled. |\n|     `paymentId` | `string` | Identifier of the payment that produced the transaction. |\n|     `referenceId` | `string` | Your own reference, supplied when the payment was created. |\n|     `rrn` | `string` | Retrieval reference number assigned by the acquirer. |\n|     `amount` | `number` | Transaction amount, in the smallest unit of the currency (e.g. öre for SEK). |\n|     `currency` | `string` | ISO 4217 currency code of the transaction. |\n|     `method` | `string` | Payment method used, for example CARD, SWISH or GIFT_CARD. |\n|     `type` | `string` | Transaction type, for example PURCHASE or RETURN. |\n|     `orderSummary` | `string` | Short, human-readable summary of the order. |\n|     `timestamp` | `string` | When the transaction was created, in ISO 8601 format. |\n|     `voided` | `boolean` | Whether the transaction was voided. |\n|     `issuerCountry` | `string` | Country of the card issuer, reported at settlement. |\n|     `interchangeDomain` | `string` | Interchange domain the card falls under, for example domestic or intra-regional. |\n|     `cardCategory` | `string` | Card category reported at settlement, for example consumer or commercial. |\n|     `cardUsage` | `string` | Card funding type reported at settlement, for example debit or credit. |\n|     `fee` | `number` | Surfboard fee charged on the transaction, in the smallest currency unit. |\n|     `feeVat` | `number` | VAT charged on the Surfboard fee, in the smallest currency unit. |\n|     `settlementStatus` | `string` | Settlement state of the transaction; NOT_SETTLED until it is paid out. |\n|     `payout` | `number` | Amount paid out to the merchant for this transaction, in the smallest currency unit. |\n|     `settlementRef` | `string` | Reference of the settlement batch the transaction was paid out in. |\n|     `settlementDate` | `string` | Date the transaction was paid out to the merchant. |\n|     `truncatedPan` | `string` | Last four digits of the card number (PAN), zero-padded to four characters. |\n|     `cardLabel` | `string` | Application label of the card scheme used (the AID name). |\n|     `posEntryMode` | `string` | How the card was presented at the point of sale (entry mode). |\n|     `issuerApplication` | `string` | Issuer application data returned by the card. |\n|     `terminalVerificationResult` | `string` | Terminal verification results (TVR) from the card interaction. |\n|     `aid` | `string` | Application identifier (AID) of the card scheme used. |\n|     `customerResponseCode` | `string` | Response code returned by the card issuer. |\n|     `cvmMethod` | `string` | Cardholder verification method code used during the transaction. |\n|     `cvmMethodDescription` | `string` | Human-readable description of the cardholder verification method (e.g. 'Online PIN', 'No CVM'). |\n|     `authMode` | `string` | Authorization mode; ISSUER when the issuer authorized the transaction. |\n|     `cardBrand` | `string` | Card brand, for example VISA or MASTERCARD. |\n|     `authCode` | `string` | Authorization code returned by the issuer. |\n|     `adjustments` | `array` | Tip or amount adjustments applied to the transaction. Present only when adjustments exist. |\n|         `type` | `string` | The kind of adjustment, for example TIP. |\n|         `amount` | `number` | Adjustment amount, in the smallest currency unit. |\n|         `adjustmentId` | `string` | Unique identifier of the adjustment. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"transactionId\": \"txn_8f21c0a9b7\",\n \"merchantId\": \"m_5f2c1a9b3d\",\n \"storeId\": \"st_2a91\",\n \"terminalId\": \"t_7c33\",\n \"orderId\": \"ord_4b19d2\",\n \"paymentId\": \"pay_a71f\",\n \"referenceId\": \"order-2026-0012\",\n \"rrn\": \"618234501122\",\n \"amount\": 14900,\n \"currency\": \"SEK\",\n \"method\": \"CARD\",\n \"type\": \"PURCHASE\",\n \"orderSummary\": \"2x Flat White\",\n \"timestamp\": \"2026-06-01T09:24:11.000Z\",\n \"voided\": false,\n \"settlementStatus\": \"SETTLED\",\n \"fee\": 268,\n \"feeVat\": 67,\n \"payout\": 14632,\n \"cardBrand\": \"VISA\",\n \"truncatedPan\": \"0341\",\n \"cardLabel\": \"VISA CREDIT\",\n \"authMode\": \"ISSUER\"\n }\n ],\n \"message\": \"Fetched all transactions under merchant\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Failed to fetch transactions\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Search Transactions", "slug": "transactions-search-transactions", "description": "Run a free-text search across the merchant's transactions — for example by order reference, RRN, or card label — and get back the matching transactions along with the fields that matched and a short snippet for each.", "api": "Transactions API", "method": "GET", "path": "/transactions/search", "content": "# Search Transactions\n\n## Overview\nRun a free-text search across the merchant's transactions — for example by order reference, RRN, or card label — and get back the matching transactions along with the fields that matched and a short snippet for each.\n\n## Prerequisites\n- An active partner account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nGET /transactions/search\n```\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `query` | `string` | Yes | The text to search the merchant's transactions for, such as an order reference, RRN, or card label. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /transactions/search?query=order-2026-0012\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | The search results. |\n|     `transactionDetails` | `object` | The matches found for the search. |\n|         `entries` | `number` | Total number of matching transactions. |\n|         `hits` | `array` | The matching transactions. |\n|             `transactionId` | `string` | Identifier of the matching transaction. |\n|             `path` | `string` | Location within the transaction where the match was found. |\n|             `matches` | `array` | The individual field matches for this transaction. |\n|                 `field` | `string` | The transaction field that matched the search. |\n|                 `matched` | `string` | The matched value. |\n|                 `snippet` | `string` | A snippet of text surrounding the match. |\n|             `transaction` | `object` | A normalized view of the matched transaction. |\n|                 `transactionId` | `string` | Unique identifier of the transaction. |\n|                 `merchantId` | `string` | Identifier of the merchant the transaction belongs to. |\n|                 `storeId` | `string` | Identifier of the store where the transaction took place. |\n|                 `terminalId` | `string` | Identifier of the terminal (checkout) that processed the transaction. |\n|                 `orderId` | `string` | Identifier of the order the transaction settled. |\n|                 `paymentId` | `string` | Identifier of the payment that produced the transaction. |\n|                 `referenceId` | `string` | Your own reference, supplied when the payment was created. |\n|                 `rrn` | `string` | Retrieval reference number assigned by the acquirer. |\n|                 `amount` | `number` | Transaction amount, in the smallest unit of the currency (e.g. öre for SEK). |\n|                 `currency` | `string` | ISO 4217 currency code of the transaction. |\n|                 `method` | `string` | Payment method used, for example CARD, SWISH or GIFT_CARD. |\n|                 `type` | `string` | Transaction type, for example PURCHASE or RETURN. |\n|                 `orderSummary` | `string` | Short, human-readable summary of the order. |\n|                 `timestamp` | `string` | When the transaction was created, in ISO 8601 format. |\n|                 `voided` | `boolean` | Whether the transaction was voided. |\n|                 `issuerCountry` | `string` | Country of the card issuer, reported at settlement. |\n|                 `interchangeDomain` | `string` | Interchange domain the card falls under, for example domestic or intra-regional. |\n|                 `cardCategory` | `string` | Card category reported at settlement, for example consumer or commercial. |\n|                 `cardUsage` | `string` | Card funding type reported at settlement, for example debit or credit. |\n|                 `fee` | `number` | Surfboard fee charged on the transaction, in the smallest currency unit. |\n|                 `feeVat` | `number` | VAT charged on the Surfboard fee, in the smallest currency unit. |\n|                 `settlementStatus` | `string` | Settlement state of the transaction; NOT_SETTLED until it is paid out. |\n|                 `payout` | `number` | Amount paid out to the merchant for this transaction, in the smallest currency unit. |\n|                 `settlementRef` | `string` | Reference of the settlement batch the transaction was paid out in. |\n|                 `settlementDate` | `string` | Date the transaction was paid out to the merchant. |\n|                 `truncatedPan` | `string` | Last four digits of the card number (PAN), zero-padded to four characters. |\n|                 `cardLabel` | `string` | Application label of the card scheme used (the AID name). |\n|                 `posEntryMode` | `string` | How the card was presented at the point of sale (entry mode). |\n|                 `issuerApplication` | `string` | Issuer application data returned by the card. |\n|                 `terminalVerificationResult` | `string` | Terminal verification results (TVR) from the card interaction. |\n|                 `aid` | `string` | Application identifier (AID) of the card scheme used. |\n|                 `customerResponseCode` | `string` | Response code returned by the card issuer. |\n|                 `cvmMethod` | `string` | Cardholder verification method code used during the transaction. |\n|                 `cvmMethodDescription` | `string` | Human-readable description of the cardholder verification method (e.g. 'Online PIN', 'No CVM'). |\n|                 `authMode` | `string` | Authorization mode; ISSUER when the issuer authorized the transaction. |\n|                 `cardBrand` | `string` | Card brand, for example VISA or MASTERCARD. |\n|                 `authCode` | `string` | Authorization code returned by the issuer. |\n|                 `adjustments` | `array` | Tip or amount adjustments applied to the transaction. Present only when adjustments exist. |\n|                     `type` | `string` | The kind of adjustment, for example TIP. |\n|                     `amount` | `number` | Adjustment amount, in the smallest currency unit. |\n|                     `adjustmentId` | `string` | Unique identifier of the adjustment. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"transactionDetails\": {\n \"entries\": 1,\n \"hits\": [\n {\n \"transactionId\": \"txn_8f21c0a9b7\",\n \"path\": \"transaction.referenceId\",\n \"matches\": [\n {\n \"field\": \"referenceId\",\n \"matched\": \"order-2026-0012\",\n \"snippet\": \"…order-2026-0012…\"\n }\n ],\n \"transaction\": {\n \"transactionId\": \"txn_8f21c0a9b7\",\n \"merchantId\": \"m_5f2c1a9b3d\",\n \"storeId\": \"st_2a91\",\n \"terminalId\": \"t_7c33\",\n \"orderId\": \"ord_4b19d2\",\n \"paymentId\": \"pay_a71f\",\n \"referenceId\": \"order-2026-0012\",\n \"rrn\": \"618234501122\",\n \"amount\": 14900,\n \"currency\": \"SEK\",\n \"method\": \"CARD\",\n \"type\": \"PURCHASE\",\n \"orderSummary\": \"2x Flat White\",\n \"timestamp\": \"2026-06-01T09:24:11.000Z\",\n \"voided\": false,\n \"settlementStatus\": \"SETTLED\",\n \"fee\": 268,\n \"feeVat\": 67,\n \"payout\": 14632,\n \"cardBrand\": \"VISA\",\n \"truncatedPan\": \"0341\",\n \"cardLabel\": \"VISA CREDIT\",\n \"authMode\": \"ISSUER\"\n }\n }\n ]\n }\n },\n \"message\": \"Transaction details search done successfully.\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Please pass in the search value as a query.\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n\n---" }, { "title": "Activate Webhook", "slug": "webhooks-activate-webhook", "description": "Activate a webhook against a specific environment so it begins receiving events. Supply the webhook identifier in the path and the target environment in the body. Use this once your endpoint is ready to accept live deliveries. Send the `MERCHANT-ID` header to manage a specific merchant's webhooks; omit it to manage the partner's own webhooks.", "api": "Webhooks API", "method": "POST", "path": "/webhooks/:webhookId/activate", "content": "# Activate Webhook\n\n## Overview\nActivate a webhook against a specific environment so it begins receiving events. Supply the webhook identifier in the path and the target environment in the body. Use this once your endpoint is ready to accept live deliveries. Send the `MERCHANT-ID` header to manage a specific merchant's webhooks; omit it to manage the partner's own webhooks.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `webhookId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /webhooks/:webhookId/activate\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `webhookId` | `string` | Yes | Identifier of the webhook to activate, supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `type` | `string` | Yes | Environment to activate the webhook in. Possible values: `DEMO`, `LIVE`. |\n\n### Request Example\n```json\n{\n \"type\": \"LIVE\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Details of the activated webhook. |\n|     `webhookId` | `string` | Identifier of the activated webhook. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"webhookId\": \"wh_9c1f2a7b40\"\n },\n \"message\": \"Webhook activated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to activate webhook. Please try again later\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `webhookId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "Create Webhook", "slug": "webhooks-create-webhook", "description": "Register a new webhook so Surfboard can deliver events to your endpoint. Supply the HTTPS URL to deliver to, a display name, the event types to subscribe to, and an email to alert on repeated delivery failures. The response returns the new webhook's identifier and the signing certificate you use to verify that incoming deliveries came from Surfboard. Send the `MERCHANT-ID` header to manage a specific merchant's webhooks; omit it to manage the partner's own webhooks.", "api": "Webhooks API", "method": "POST", "path": "/webhooks", "content": "# Create Webhook\n\n## Overview\nRegister a new webhook so Surfboard can deliver events to your endpoint. Supply the HTTPS URL to deliver to, a display name, the event types to subscribe to, and an email to alert on repeated delivery failures. The response returns the new webhook's identifier and the signing certificate you use to verify that incoming deliveries came from Surfboard. Send the `MERCHANT-ID` header to manage a specific merchant's webhooks; omit it to manage the partner's own webhooks.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nPOST /webhooks\n```\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `webhookUrl` | `string` | Yes | The HTTPS endpoint Surfboard should deliver events to. |\n| `webhookName` | `string` | Yes | A display name for the webhook, used to identify it in listings. |\n| `events` | `array` | Yes | The event types to subscribe this webhook to. |\n| `alertEmail` | `string` | Yes | Email address to notify when webhook delivery repeatedly fails. |\n\n### Request Example\n```json\n{\n \"webhookUrl\": \"https://example.com/surfboard/webhook\",\n \"webhookName\": \"Order events\",\n \"events\": [\n \"PAYMENT_SUCCEEDED\",\n \"PAYMENT_FAILED\"\n ],\n \"alertEmail\": \"integrations@surfboard.se\"\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `object` | Details of the created webhook. |\n|     `webhookId` | `string` | Unique identifier of the newly created webhook. |\n|     `webhookCertificate` | `string` | Signing certificate used to verify that deliveries to your endpoint originated from Surfboard. |\n|     `tested` | `boolean` | Whether the webhook has passed a delivery test against its endpoint. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": {\n \"webhookId\": \"wh_9c1f2a7b40\",\n \"webhookCertificate\": \"-----BEGIN CERTIFICATE-----\\nMIIB...snip...IDAQAB\\n-----END CERTIFICATE-----\",\n \"tested\": false\n },\n \"message\": \"Webhook created successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to create webhook. Please try again later\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n\n---" }, { "title": "Disable Webhook", "slug": "webhooks-disable-webhook", "description": "Disable a webhook so Surfboard stops delivering events to it. Supply the webhook identifier in the URL path. The webhook remains on the account and can be reactivated later. Send the `MERCHANT-ID` header to manage a specific merchant's webhooks; omit it to manage the partner's own webhooks.", "api": "Webhooks API", "method": "DELETE", "path": "/webhooks/:webhookId", "content": "# Disable Webhook\n\n## Overview\nDisable a webhook so Surfboard stops delivering events to it. Supply the webhook identifier in the URL path. The webhook remains on the account and can be reactivated later. Send the `MERCHANT-ID` header to manage a specific merchant's webhooks; omit it to manage the partner's own webhooks.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `webhookId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nDELETE /webhooks/:webhookId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `webhookId` | `string` | Yes | Identifier of the webhook to disable, supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Webhook disabled successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to disable webhook. Please try again later\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `webhookId` is part of the URL path and must be a valid identifier.\n\n---" }, { "title": "List Webhooks", "slug": "webhooks-list-webhooks", "description": "Retrieve a paginated list of the webhooks configured on the authenticated account, including each webhook's URL, subscribed events, alert email, and whether it is active and has passed its delivery test. Send the `MERCHANT-ID` header to manage a specific merchant's webhooks; omit it to manage the partner's own webhooks.", "api": "Webhooks API", "method": "GET", "path": "/webhooks", "content": "# List Webhooks\n\n## Overview\nRetrieve a paginated list of the webhooks configured on the authenticated account, including each webhook's URL, subscribed events, alert email, and whether it is active and has passed its delivery test. Send the `MERCHANT-ID` header to manage a specific merchant's webhooks; omit it to manage the partner's own webhooks.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n\n## Request\n\n### HTTP Method and URL\n```\nGET /webhooks\n```\n\n### Query Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `page` | `string` | No | Page of results to return. Defaults to the first page when omitted or not a number. |\n\n### Pagination\n\nPage through results with the `page` query parameter, for example `?page=2`. When omitted, the first `page` is returned.\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\nThis endpoint does not take a request body.\n\n### Request Example\n```text\nGET /webhooks?page=1\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `data` | `array` | The webhooks configured on the account for the current page. |\n|     `webhookId` | `string` | Unique identifier of the webhook. |\n|     `webhookName` | `string` | The display name you gave the webhook. |\n|     `webhookUrl` | `string` | The HTTPS endpoint Surfboard delivers events to. |\n|     `active` | `boolean` | Whether the webhook is currently active and receiving events. |\n|     `alertEmail` | `string` | Email address notified when webhook delivery repeatedly fails. |\n|     `tested` | `boolean` | Whether the webhook has passed a delivery test against its endpoint. |\n|     `events` | `array` | The event types this webhook is subscribed to. |\n|     `createdAt` | `string` | When the webhook was created, in ISO 8601 format. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"data\": [\n {\n \"webhookId\": \"wh_9c1f2a7b40\",\n \"webhookName\": \"Order events\",\n \"webhookUrl\": \"https://example.com/surfboard/webhook\",\n \"active\": true,\n \"alertEmail\": \"integrations@surfboard.se\",\n \"tested\": true,\n \"events\": [\n \"PAYMENT_SUCCEEDED\",\n \"PAYMENT_FAILED\"\n ],\n \"createdAt\": \"2026-06-01T09:24:11.000Z\"\n }\n ],\n \"message\": \"Fetched all webhooks under merchant\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to get all webhooks. Please try again later\"\n}\n```\n**Description:** The request parameters are malformed. Check the URL path and query parameters against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- This endpoint is paginated; see the Pagination section for how to page through the results.\n\n---" }, { "title": "Update Webhook", "slug": "webhooks-update-webhook", "description": "Update a webhook's configuration. Supply the webhook identifier in the path and include only the fields you want to change; any field you omit is left untouched. Use this to point a webhook at a new URL, rename it, change the alert email, or adjust which events it is subscribed to. Send the `MERCHANT-ID` header to manage a specific merchant's webhooks; omit it to manage the partner's own webhooks.", "api": "Webhooks API", "method": "PUT", "path": "/webhooks/:webhookId", "content": "# Update Webhook\n\n## Overview\nUpdate a webhook's configuration. Supply the webhook identifier in the path and include only the fields you want to change; any field you omit is left untouched. Use this to point a webhook at a new URL, rename it, change the alert email, or adjust which events it is subscribed to. Send the `MERCHANT-ID` header to manage a specific merchant's webhooks; omit it to manage the partner's own webhooks.\n\n## Prerequisites\n- An active merchant account is required.\n- Authentication is required — send an API Key and API Secret pair (as shown), or another supported scheme (see Notes).\n- The resource identified by `webhookId` in the URL path must exist.\n\n## Request\n\n### HTTP Method and URL\n```\nPUT /webhooks/:webhookId\n```\n\n### Path Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `webhookId` | `string` | Yes | Identifier of the webhook to update, supplied in the URL path. |\n\n### Headers\n| Header | Value | Required |\n|---|---|---|\n| `Content-Type` | `application/json` | Yes |\n| `API-KEY` | `YOUR_API_KEY` | Yes |\n| `API-SECRET` | `YOUR_API_SECRET` | Yes |\n| `MERCHANT-ID` | `YOUR_MERCHANT_ID` | No |\n\n### Request Body Parameters\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `webhookUrl` | `string` | No | New HTTPS endpoint to deliver events to. Omit to leave unchanged. |\n| `webhookName` | `string` | No | New display name for the webhook. Omit to leave unchanged. |\n| `alertEmail` | `string` | No | New email address to notify on repeated delivery failures. Omit to leave unchanged. |\n| `events` | `array` | No | New set of event types to subscribe the webhook to. Omit to leave unchanged. |\n\n### Request Example\n```json\n{\n \"webhookName\": \"Order and refund events\",\n \"events\": [\n \"PAYMENT_SUCCEEDED\",\n \"PAYMENT_FAILED\",\n \"REFUND_SUCCEEDED\"\n ]\n}\n```\n\n## Response\n\n### Response Parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `status` | `string` | Status of the request, either 'SUCCESS' or 'ERROR'. |\n| `message` | `string` | A message that describes the status of the request. |\n\n### Success Response Example\n```json\n{\n \"status\": \"SUCCESS\",\n \"message\": \"Webhook updated successfully\"\n}\n```\n\n## Error Responses\n\n### Possible Errors\n\n#### 400 - Bad Request\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unable to update webhook. Please try again later\"\n}\n```\n**Description:** The request body is malformed or missing required parameters. Check the request body against the documented schema and ensure all mandatory fields are present and of the correct type.\n\n#### 401 - Unauthorized\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Unauthorized access. Please provide valid credentials to access this endpoint.\"\n}\n```\n**Description:** Authentication failed. Ensure the `API-KEY` and `API-SECRET` headers are correctly set and valid for your account.\n\n#### 404 - Not Found\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"Resource not found.\"\n}\n```\n**Description:** The requested resource does not exist. Verify the identifiers in the request path and try again.\n\n#### 500 - Internal Server Error\n```json\n{\n \"status\": \"ERROR\",\n \"message\": \"An unexpected error occurred.\"\n}\n```\n**Description:** An unexpected error occurred on the server. Try the request again later. If the problem persists, contact support.\n\n## Notes\n- Authenticate with **one** of: an `API-KEY` + `API-SECRET` pair (shown above), a bearer JWT (`Authorization`), an API token (`X-Surfboard-Api-Token`), or a nonce (`X-Surfboard-Nonce`).\n- `MERCHANT-ID` is optional; when sent it must match the `:merchantId` in the path.\n- The `webhookId` is part of the URL path and must be a valid identifier.\n\n---" } ] }