{ "openapi": "3.1.0", "info": { "title": "Surfboard Payments, Carbon API", "version": "1.0.0", "summary": "The credentialed payments API: orders, payments, terminals, merchants, reporting and the rest.", "description": "The Carbon API is what actually moves money: create an order, initiate a payment on a terminal or a hosted page, capture, refund, void, then read it back out of reporting.\n\n**The base URL is not published.** It is issued with your credentials in the Developer Portal console and differs between accounts and between the Demo and Live environments. Read it from configuration as `SURFBOARD_API_URL`. If you are an agent, ask the user to copy it from the console; never guess a host or reuse one from an example.\n\n**Authentication** is three headers: `API-KEY`, `API-SECRET`, and, for merchant-scoped calls, `MERCHANT-ID`. Partner-scoped calls carry the partner in the path instead. Client-side code should use a client auth token rather than the key and secret.\n\n**Conventions that catch integrations out:** amounts are integer minor units and prices are gross, currencies are ISO 4217 numeric codes as strings (`\"752\"`, not `\"SEK\"`), countries are ISO 3166-1 alpha-2 uppercase, identifiers are opaque hex strings to be stored and returned unchanged, and list endpoints page through the `X-PAGE-NUMBER` header at a fixed 100 rows.\n\nThis document is generated from the published reference, which stays the source of truth: https://developers.surfboardpayments.com/", "contact": { "name": "Surfboard Payments developer support", "url": "https://developers.surfboardpayments.com/" }, "license": { "name": "Terms of use", "url": "https://www.surfboardpayments.com/terms-and-conditions" }, "termsOfService": "https://www.surfboardpayments.com/terms-and-conditions" }, "servers": [ { "url": "{apiBaseUrl}", "description": "Your account base URL, from the Developer Portal console at https://developers.surfboardpayments.com/console/api-keys. Demo and Live are different hosts.", "variables": { "apiBaseUrl": { "default": "https://YOUR_API_URL", "description": "The value of SURFBOARD_API_URL for the environment you are calling." } } } ], "externalDocs": { "description": "Developer portal and API reference", "url": "https://developers.surfboardpayments.com/" }, "tags": [ { "name": "Adjustments API", "description": "Adjustments API takes care of handling additional amounts to orders like tips, surcharges, insurance payments etc included while performing a transaction." }, { "name": "Admin Functions API", "description": "The Admin Functions API provides comprehensive administrative capabilities for managing user accounts, roles, permissions, and system configurations. These APIs enable partners and merchants to perform administrative operations programmatically, including user account management, role assignments, and system-level configurations with flexible permission controls." }, { "name": "AI API", "description": "The AI API provides powerful artificial intelligence capabilities for merchants to enhance their product management and branding. Generate compelling product descriptions, create professional product images, extract catalog data from images, and develop branding options using advanced AI technology." }, { "name": "Bin Ranges API", "description": "The Bin Ranges API manages the BIN (Bank Identification Number) ranges owned by a partner, including the card-number sub-ranges that each range covers." }, { "name": "Branding APIs", "description": "Branding APIs enable you to customize all customer facing pages provided by Surfboard. The branding can be configured at various levels similar to the terminal config." }, { "name": "Client Auth Tokens API", "description": "These APIs are used when you would like to make requests from the client directly to Surfboard without using the API-Key and API-Secret. The generated token is restricted to perform calls limited to orders, payments and transactions." }, { "name": "Customers API", "description": "The Customers API enables merchants to manage customer information including personal details, addresses, contact information, and associated payment cards. This API provides functionality to create customer profiles and retrieve detailed customer information for enhanced customer relationship management." }, { "name": "Electronic Cash Register (ECR) V2 API", "description": "The ECR V2 API enables merchants to manage electronic cash registers for daily operations. This includes subscribing cash registers, opening/closing registers and shifts, managing cash deposits and withdrawals, and tracking register state. The API follows a sequential flow matching natural business day operations." }, { "name": "Gift Cards API", "description": "The Gift Cards API enables merchants to create, manage, and track gift cards. Gift cards can be of two types: FUND (monetary value) or ENTITLEMENT (usage-based). The API supports creating gift cards, retrieving gift card information, and tracking transactions." }, { "name": "Logistics API", "description": "Partners can place orders for products (terminals and other accessories) from Surfboard. As a partner, you can provide a product catalog containing a range of product options for merchants to choose from." }, { "name": "Merchant Charge & Billing Plans", "description": "This section covers the APIs used to create, update, and retrieve charges associated with a merchant, as well as manage billing plans for partners. Charges can be one-time or subscription-based, while billing plans define pricing structures for different payment methods and card brands." }, { "name": "Merchants API", "description": "A merchant is created in Surfboard with the completion of an onboarding process. Merchant creation can be initiated through ISVs who have partnered with Surfboard to offer payment solutions to their merchants in addition to their existing products." }, { "name": "Notifications API", "description": "The Notifications API enables merchants and partners to subscribe to event notifications via SFTP or email. It allows you to configure automated notifications for various events and manage your notification subscriptions." }, { "name": "Orders API", "description": "The Orders API enables merchants to create and manage orders. Orders must be created to initiate payments because each payment is assigned to a specific order. In this way, each payment is coupled with the total payable amount and detailed line items like products purchased, the quantity of products, the individual price per item etc. This streamlines the payment operations (tracking, receipts, refunds etc.)." }, { "name": "Partners API", "description": "The Partners API lets a Surfboard partner manage the merchants, users, and analytics that sit under their partner account. Look up partner details and configuration, pull partner, transaction and application analytics, search across everything a partner owns, look up companies during onboarding, and list and update users." }, { "name": "Payment Methods API", "description": "The Payment Methods API enables you to add, manage, and remove additional payments methods offered by Surfboard. While the CARD is the default payment method, these APIs allows for the addition and removal of other payment methods such as AMEX and SWISH. These payment methods can be added to specific merchants and/or stores, offering versatility in payment strategies." }, { "name": "Payments API", "description": "The Payments API enables merchants to initiate, check the status of, cancel, and void payments. The payment operations are performed for the orders created by the merchants. This ensures that each payment is associated with a specific order and has rich data associated with it." }, { "name": "Product Catalog API", "description": "The product catalog API allows the merchants to create a catalog and organize the products with detailed specifications under their store." }, { "name": "Promotions API", "description": "The Promotions API lets merchants run marketing campaigns that are shown to customers across their stores and terminals — for example on a terminal’s idle screen or printed on a receipt. A promotion defines what is displayed (its visual assets), when it runs (its schedule), and how it rewards customers: either a promo code that applies a discount at checkout or a redirect link that sends customers to a destination. After it is created, a promotion is assigned to one or more stores and synced to their terminals to go live, and it keeps running within its schedule until it expires or its budget or redemption limits are reached." }, { "name": "Receipts API", "description": "The Receipts API lets you fetch receipt data, add data Surfboard does not hold, print receipts (including raw ESC/POS), email receipts, and get a shareable receipt link." }, { "name": "Reporting APIs", "description": "Reporting APIs enable merchants to generate actionable reports about various aspects of their business. Through these APIs you gain access to precise data, enabling you to track revenue, monitor transaction volume, identify fraud, reconcile financial records, and make informed decisions for your business." }, { "name": "RFID API", "description": "APIs for managing RFID reading sessions on a terminal. Start a reading session, query its status, list sessions, read the captured tags, and complete a session." }, { "name": "Service Providers API", "description": "The Service Providers API lets partners onboard service providers, track their application progress, and link them to the merchants they serve. Use it to submit company or individual service provider applications, follow each application through KYB and signing, and manage which service providers are active on a merchant account." }, { "name": "Stores API", "description": "Stores represent the physical or virtual location of sales. Stores have to be created for each merchant before they can register terminals to accept payments. Onboarded merchants can have one or more stores created under them based on their business requirements." }, { "name": "Templates API", "description": "The POS Template API allows you to customize and manage the content displayed on your POS screen." }, { "name": "Terminals API", "description": "Surfboard offers a diverse range of hardware terminals along with the SoftPOS terminal that can be integrated with your existing ECRs and checkout systems. The Terminals API allows you to register and manage these terminals. For CheckoutPro integration, you can use the Terminals APIs to link the terminal to your CheckoutPro, check the linkage status, and delink the terminal from your CheckoutPro." }, { "name": "Tips APIs", "description": "Tips APIs enable merchants to integrate tipping functionality directly into the payment terminals. These APIs provide options for adding either preset or custom tip amounts to the overall payment amount on the terminal screen. When customers make payments, they can choose from these displayed preset tip values or decide to enter a custom amount based on their preference. Tips can be configured at the merchant, store, or terminal levels, allowing for flexibility to match your unique operational requirements." }, { "name": "Transactions API", "description": "The Transactions API lets you retrieve a merchant's card and payment transactions. Fetch a paginated transaction list — optionally narrowed to a date range, store, or terminal — or run a free-text search across a merchant's transactions to reconcile payments, build reporting, or look up an individual sale." }, { "name": "Webhooks API", "description": "The Webhooks API lets you register and manage HTTPS endpoints that Surfboard calls when events happen on a merchant account. Create a webhook to subscribe to the events you care about, list your configured webhooks, update a webhook's URL, name, alert email or event subscriptions, activate a webhook against your demo or live environment, and disable one you no longer need. Webhooks are managed at partner level by default, or scoped to a merchant by sending the `MERCHANT-ID` header." } ], "security": [ { "apiKey": [], "apiSecret": [] } ], "paths": { "/adjustments/{id}": { "get": { "operationId": "fetchAdjustments", "summary": "Fetch Adjustments", "description": "Fetch all adjustments created under a merchant or store.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Adjustments API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier for the id this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": true, "description": "Start date of the range in yyyy-mm-dd format.", "schema": { "description": "Start date of the range in yyyy-mm-dd format.", "type": "string" } }, { "name": "endDate", "in": "query", "required": true, "description": "End date of the range in yyyy-mm-dd format.", "schema": { "description": "End date of the range in yyyy-mm-dd format.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "array", "items": { "type": "object", "properties": { "adjustmentId": { "description": "Adjustment ID of the adjustment.", "type": "string" }, "adjustmentType": { "description": "Type of the adjustment.", "type": "string" }, "amount": { "description": "Amount of the adjustment.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "adjustmentId": "81efdbe975ebc800ff", "adjustmentType": "tips", "amount": "100" } ], "message": "Adjustments fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Invalid date format" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } }, "404": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "No adjustments found" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/accounts": { "post": { "operationId": "merchantsCreateMerchantAccount", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "Email address of the user account being created. An activation invitation is sent to this address.", "type": "string" }, "role": { "description": "Role to assign to the new user account.", "type": "string" }, "firstName": { "description": "First name of the user.", "type": "string" }, "lastName": { "description": "Last name of the user.", "type": "string" } }, "required": [ "email" ] }, "example": { "email": "newuser@surfboard.se", "role": "CASHIER", "firstName": "Amanda", "lastName": "Berg" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request 'SUCCESS' | 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Account creation initiated successfully." } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Account creation failed for merchant." } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/partners/{partnerId}/accounts": { "post": { "operationId": "createPartnerAccount", "summary": "Create Partner Account", "description": "Create a new account for a partner with specified email and role permissions.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Admin Functions API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "Email address for the new partner account", "type": "string" }, "role": { "description": "Role assigned to the account (e.g., ADMIN, SUPER_ADMIN, USER).", "type": "string" } }, "required": [ "email" ] }, "example": { "email": "admin@partner.com", "role": "ADMIN" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "message": { "description": "A message that describes the status of the request", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Initiate Signup sucessfull" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/ai/branding": { "post": { "operationId": "generateBrandingOptions", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "AI API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "Website URL to analyze for branding inspiration and color scheme generation.", "type": "string" } }, "required": [ "url" ] }, "example": { "url": "https://example-company.com" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing generated branding options.", "type": "object", "properties": { "options": { "description": "Array of branding option sets with metadata.", "type": "array", "items": { "type": "object", "properties": { "brandingOptions": { "description": "Array of branding configuration options.", "type": "array", "items": { "type": "object", "properties": { "backgroundColor": { "description": "Hex color code for the background color.", "type": "string" }, "brandColor": { "description": "Hex color code for the primary brand color.", "type": "string" }, "accentColor": { "description": "Hex color code for accent elements.", "type": "string" }, "rectShape": { "description": "Shape style for rectangular elements (e.g., 'rounded', 'square').", "type": "string" }, "fontType": { "description": "Font family type for text elements (e.g., 'mono', 'serif', 'sans-serif').", "type": "string" }, "logoUrl": { "description": "URL of the generated or suggested logo image.", "type": "string" }, "iconUrl": { "description": "URL of the generated or suggested icon image.", "type": "string" }, "footerColor": { "description": "Hex color code for footer elements.", "type": "string" } }, "required": [ "backgroundColor", "brandColor", "accentColor", "rectShape", "fontType", "logoUrl", "iconUrl", "footerColor" ], "additionalProperties": true } }, "metadata": { "description": "Metadata about the AI generation process.", "type": "object", "properties": { "inputTokens": { "description": "Number of input tokens used in the AI generation.", "type": "number" }, "outputTokens": { "description": "Number of output tokens generated by the AI.", "type": "number" }, "outputType": { "description": "Type of output generated (e.g., 'text', 'image').", "type": "string" } }, "required": [ "inputTokens", "outputTokens", "outputType" ], "additionalProperties": true } }, "required": [ "brandingOptions", "metadata" ], "additionalProperties": true } } }, "required": [ "options" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "options": [ { "brandingOptions": [ { "backgroundColor": "#FDFDFF", "brandColor": "#38488F", "accentColor": "#38488F", "rectShape": "rounded", "fontType": "mono", "logoUrl": "", "iconUrl": "", "footerColor": "#F0F0F2" } ], "metadata": { "inputTokens": 1043, "outputTokens": 85, "outputType": "text" } } ] }, "message": "Branding generated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/ai/enhance-image": { "post": { "operationId": "enhanceImage", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "AI API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productName": { "description": "Name of the product to provide context for image enhancement.", "type": "string" }, "url": { "description": "URL of the product image to be enhanced.", "type": "string" }, "mode": { "description": "Enhancement mode to apply to the image.\n\nValues:\n- `STANDARD`: Apply standard image enhancements including lighting, color correction, and quality improvements.\n- `SCENE`: Generate contextual scene backgrounds and lifestyle imagery for the product.", "type": "string", "enum": [ "STANDARD", "SCENE" ] } }, "required": [ "productName", "url", "mode" ] }, "example": { "productName": "Wireless Bluetooth Headphones", "url": "https://example.com/images/product-12345.jpg", "mode": "STANDARD" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing enhanced image URLs.", "type": "object", "properties": { "imageUrls": { "description": "Array of URLs pointing to the enhanced product images.", "type": "array", "items": {} } }, "required": [ "imageUrls" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "imageUrls": [ "https://cdn.example.com/enhanced/image-abc123-v1.jpg", "https://cdn.example.com/enhanced/image-abc123-v2.jpg", "https://cdn.example.com/enhanced/image-abc123-v3.jpg" ] }, "message": "Image enhanced successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/bin-ranges": { "post": { "operationId": "createBinRange", "summary": "Create Bin Range", "description": "Create a new bin range together with the card-number sub-ranges it covers.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Bin Ranges API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "description": "A description of the bin range.", "type": "string" }, "rangesIncluded": { "description": "The card-number sub-ranges covered by this bin range.", "type": "array", "items": { "type": "object", "properties": { "start": { "description": "Inclusive start of the BIN sub-range.", "type": "string" }, "end": { "description": "Inclusive end of the BIN sub-range.", "type": "string" }, "description": { "description": "A description of this sub-range.", "type": "string" } }, "required": [ "start", "end", "description" ] } } }, "required": [ "description", "rangesIncluded" ] }, "example": { "description": "Visa consumer ranges", "rangesIncluded": [ { "start": "400000", "end": "499999", "description": "Visa primary range" } ] } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The created bin range.", "type": "object", "properties": { "binRangeId": { "description": "Unique identifier of the created bin range.", "type": "string" }, "partnerId": { "description": "Identifier of the partner that owns the bin range.", "type": "string" }, "description": { "description": "Description supplied when the bin range was created.", "type": "string" }, "rangesIncluded": { "description": "The card-number sub-ranges stored for this bin range.", "type": "array", "items": { "type": "object", "properties": { "start": { "description": "Inclusive start of the BIN sub-range.", "type": "string" }, "end": { "description": "Inclusive end of the BIN sub-range.", "type": "string" }, "description": { "description": "A description of this sub-range.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "binRangeId": "br_81efdbe975ebc800", "partnerId": "p_5f2c1a9b3d", "description": "Visa consumer ranges", "rangesIncluded": [ { "start": "400000", "end": "499999", "description": "Visa primary range" } ] }, "message": "Bin range created successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to create bin range" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] }, "get": { "operationId": "listBinRanges", "summary": "List Bin Ranges", "description": "Fetch a paginated list of the partner's bin ranges.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Bin Ranges API" ], "parameters": [ { "name": "includeInactive", "in": "query", "required": false, "description": "Whether inactive bin ranges are included in the results.", "schema": { "description": "Whether inactive bin ranges are included in the results.", "type": "boolean" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The list of bin ranges for the current page.", "type": "array", "items": { "type": "object", "properties": { "binRangeId": { "description": "Unique identifier of the bin range.", "type": "string" }, "partnerId": { "description": "Identifier of the partner that owns the bin range.", "type": "string" }, "description": { "description": "Description supplied when the bin range was created.", "type": "string" }, "rangesIncluded": { "description": "The card-number sub-ranges stored for this bin range.", "type": "array", "items": { "type": "object", "properties": { "start": { "description": "Inclusive start of the BIN sub-range.", "type": "string" }, "end": { "description": "Inclusive end of the BIN sub-range.", "type": "string" }, "description": { "description": "A description of this sub-range.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "binRangeId": "br_81efdbe975ebc800", "partnerId": "p_5f2c1a9b3d", "description": "Visa consumer ranges", "rangesIncluded": [ { "start": "400000", "end": "499999", "description": "Visa primary range" } ] } ], "message": "Bin ranges fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to fetch bin ranges" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/merchants/{merchantId}/branding": { "patch": { "operationId": "createBrandingForMerchant", "summary": "Create Branding for Merchant", "description": "Create a branding configuration for customizable pages at merchant level\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "backgroundColor": { "description": "Background color for the page.", "type": "string" }, "brandColor": { "description": "Primary brand color for your page.", "type": "string" }, "footerColor": { "description": "Footer's background color on the page.", "type": "string" }, "accentColor": { "description": "This is a secondary color that complements your brand color.", "type": "string" }, "rectShape": { "description": "Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'.", "type": "string", "enum": [ null, null, null ] }, "fontType": { "description": "Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'.", "type": "string", "enum": [ null, null, null ] }, "logoUrl": { "description": "Logo that will be displayed on the page.", "type": "string" }, "iconUrl": { "description": "Icon that will be displayed on the page.", "type": "string" }, "primaryCoverImage": { "description": "Primary cover image that will be displayed on the page.", "type": "string" }, "secondaryCoverImage": { "description": "Secondary cover image that will be displayed on the page. Not live yet.", "type": "string" } } }, "example": { "backgroundColor": "#667085", "brandColor": "#697085", "accentColor": "#787085", "rectShape": "ROUNDED", "fontType": "sans-serif", "logoUrl": "https://res.cloudinary.com/image/surfboard-icon.svg", "iconUrl": "https://res.cloudinary.com/image/surfboard-icon.svg", "footerColor": "#CD5C5B", "primaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "secondaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Branding configuration set successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchBrandingForMerchant", "summary": "Fetch Branding for Merchant", "description": "Fetch existing branding configuration at merchant level.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "backgroundColor": { "description": "Background color for the page.", "type": "string" }, "brandColor": { "description": "Primary brand color for your page.", "type": "string" }, "footerColor": { "description": "Footer's background color on the page.", "type": "string" }, "accentColor": { "description": "This is a secondary color that complements your brand color.", "type": "string" }, "rectShape": { "description": "Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'.", "type": "string" }, "fontType": { "description": "Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'.", "type": "string" }, "logoUrl": { "description": "Logo that will be displayed on the page.", "type": "string" }, "iconUrl": { "description": "Icon that will be displayed on the page.", "type": "string" }, "primaryCoverImage": { "description": "Primary cover image that will be displayed on the page.", "type": "string" }, "secondaryCoverImage": { "description": "Secondary cover image that will be displayed on the page.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "backgroundColor": "#F08080", "brandColor": "#0E44E1", "rectShape": "ROUNDED", "fontType": "serif", "accentColor": "#F08080", "logoUrl": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "iconUrl": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "footerColor": "#CD5C5B", "primaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "secondaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6" }, "message": "Fetched Branding successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "delete": { "operationId": "removeBrandingForMerchant", "summary": "Remove Branding for Merchant", "description": "Removes the existing branding configuration at the merchant level.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message describing the outcome of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Configuration deleted successfully for id [8113d3f8403b380409] and type MERCHANT" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/branding": { "patch": { "operationId": "createBrandingForStore", "summary": "Create Branding for Store", "description": "Create a branding configuration for customizable pages at store level\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "backgroundColor": { "description": "Background color for the page.", "type": "string" }, "brandColor": { "description": "Primary brand color for your page.", "type": "string" }, "footerColor": { "description": "Footer's background color on the page.", "type": "string" }, "accentColor": { "description": "This is a secondary color that complements your brand color.", "type": "string" }, "rectShape": { "description": "Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'.", "type": "string", "enum": [ null, null, null ] }, "fontType": { "description": "Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'.", "type": "string", "enum": [ null, null, null ] }, "logoUrl": { "description": "Logo that will be displayed on the page.", "type": "string" }, "iconUrl": { "description": "Icon that will be displayed on the page.", "type": "string" }, "primaryCoverImage": { "description": "Primary cover image that will be displayed on the page.", "type": "string" }, "secondaryCoverImage": { "description": "Secondary cover image that will be displayed on the page.", "type": "string" } } }, "example": { "backgroundColor": "#667085", "brandColor": "#697085", "accentColor": "#787085", "rectShape": "ROUNDED", "fontType": "sans-serif", "logoUrl": "https://res.cloudinary.com/image/surfboard-icon.svg", "iconUrl": "https://res.cloudinary.com/image/surfboard-icon.svg", "footerColor": "#CD5C5B", "primaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "secondaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Branding configuration set successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchBrandingForStore", "summary": "Fetch Branding for Store", "description": "Fetch existing branding configuration at store level.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "backgroundColor": { "description": "Background color for the page.", "type": "string" }, "brandColor": { "description": "Primary brand color for your page.", "type": "string" }, "footerColor": { "description": "Footer's background color on the page.", "type": "string" }, "accentColor": { "description": "This is a secondary color that complements your brand color.", "type": "string" }, "rectShape": { "description": "Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'.", "type": "string" }, "fontType": { "description": "Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'.", "type": "string" }, "logoUrl": { "description": "Logo that will be displayed on the page.", "type": "string" }, "iconUrl": { "description": "Icon that will be displayed on the page.", "type": "string" }, "primaryCoverImage": { "description": "Primary cover image that will be displayed on the page.", "type": "string" }, "secondaryCoverImage": { "description": "Secondary cover image that will be displayed on the page.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "backgroundColor": "#F08080", "brandColor": "#0E44E1", "rectShape": "ROUNDED", "fontType": "serif", "accentColor": "#F08080", "logoUrl": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "iconUrl": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "footerColor": "#CD5C5B", "primaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "secondaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6" }, "message": "Fetched Branding successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "delete": { "operationId": "removeBrandingForStore", "summary": "Remove Branding for Store", "description": "Removes the existing branding configuration at the store level.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message describing the outcome of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Configuration deleted successfully for id [8113d3f8403b380409] and type STORE" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/terminals/{terminalId}/branding": { "patch": { "operationId": "createBrandingForTerminal", "summary": "Create Branding for Terminal", "description": "Create a branding configuration for customizable pages at terminal level\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "backgroundColor": { "description": "Background color for the page.", "type": "string" }, "brandColor": { "description": "Primary brand color for your page.", "type": "string" }, "footerColor": { "description": "Footer's background color on the page.", "type": "string" }, "accentColor": { "description": "This is a secondary color that complements your brand color.", "type": "string" }, "rectShape": { "description": "Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'.", "type": "string", "enum": [ null, null, null ] }, "fontType": { "description": "Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'.", "type": "string", "enum": [ null, null, null ] }, "logoUrl": { "description": "Logo that will be displayed on the page.", "type": "string" }, "iconUrl": { "description": "Icon that will be displayed on the page.", "type": "string" }, "primaryCoverImage": { "description": "Primary cover image that will be displayed on the page.", "type": "string" }, "secondaryCoverImage": { "description": "Secondary cover image that will be displayed on the page.", "type": "string" } } }, "example": { "backgroundColor": "#667085", "brandColor": "#697085", "accentColor": "#787085", "rectShape": "ROUNDED", "fontType": "sans-serif", "logoUrl": "https://res.cloudinary.com/image/surfboard-icon.svg", "iconUrl": "https://res.cloudinary.com/image/surfboard-icon.svg", "footerColor": "#CD5C5B", "primaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "secondaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Branding configuration set successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchBrandingForTerminal", "summary": "Fetch Branding for Terminal", "description": "Fetch existing branding configuration at terminal level.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "backgroundColor": { "description": "Background color for the page.", "type": "string" }, "brandColor": { "description": "Primary brand color for your page.", "type": "string" }, "footerColor": { "description": "Footer's background color on the page.", "type": "string" }, "accentColor": { "description": "This is a secondary color that complements your brand color.", "type": "string" }, "rectShape": { "description": "Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'.", "type": "string" }, "fontType": { "description": "Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'.", "type": "string" }, "logoUrl": { "description": "Logo that will be displayed on the page.", "type": "string" }, "iconUrl": { "description": "Icon that will be displayed on the page.", "type": "string" }, "primaryCoverImage": { "description": "Primary cover image that will be displayed on the page.", "type": "string" }, "secondaryCoverImage": { "description": "Secondary cover image that will be displayed on the page.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "backgroundColor": "#F08080", "brandColor": "#0E44E1", "rectShape": "ROUNDED", "fontType": "serif", "accentColor": "#F08080", "logoUrl": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "iconUrl": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "footerColor": "#CD5C5B", "primaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "secondaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6" }, "message": "Fetched Branding successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "delete": { "operationId": "removeBrandingForTerminal", "summary": "Remove Branding for Terminal", "description": "Removes the existing branding configuration at the terminal level.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message describing the outcome of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Configuration deleted successfully for id [833b9e1cf983580704] and type TERMINAL" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/partners/{partnerId}/branding": { "patch": { "operationId": "createBrandingForPartner", "summary": "Create Branding for Partner", "description": "Create a branding configuration for customizable pages at partner level\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "backgroundColor": { "description": "Background color for the page.", "type": "string" }, "brandColor": { "description": "Primary brand color for your page.", "type": "string" }, "footerColor": { "description": "Footer's background color on the page.", "type": "string" }, "accentColor": { "description": "This is a secondary color that complements your brand color.", "type": "string" }, "rectShape": { "description": "Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'.", "type": "string", "enum": [ null, null, null ] }, "fontType": { "description": "Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'.", "type": "string", "enum": [ null, null, null ] }, "logoUrl": { "description": "Logo that will be displayed on the page.", "type": "string" }, "iconUrl": { "description": "Icon that will be displayed on the page.", "type": "string" }, "primaryCoverImage": { "description": "Primary cover image that will be displayed on the page.", "type": "string" }, "secondaryCoverImage": { "description": "Secondary cover image that will be displayed on the page.", "type": "string" } } }, "example": { "backgroundColor": "#667085", "brandColor": "#697085", "accentColor": "#787085", "rectShape": "ROUNDED", "fontType": "sans-serif", "logoUrl": "https://res.cloudinary.com/image/surfboard-icon.svg", "iconUrl": "https://res.cloudinary.com/image/surfboard-icon.svg", "footerColor": "#CD5C5B", "primaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "secondaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Branding configuration set successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] }, "get": { "operationId": "fetchBrandingForPartner", "summary": "Fetch Branding for Partner", "description": "Fetch existing branding configuration at partner level.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "backgroundColor": { "description": "Background color for the page.", "type": "string" }, "brandColor": { "description": "Primary brand color for your page.", "type": "string" }, "footerColor": { "description": "Footer's background color on the page.", "type": "string" }, "accentColor": { "description": "This is a secondary color that complements your brand color.", "type": "string" }, "rectShape": { "description": "Decides the shape of the page buttons. The available shapes are 'ROUNDED', 'PILL' and 'EDGY'.", "type": "string" }, "fontType": { "description": "Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'.", "type": "string" }, "logoUrl": { "description": "Logo that will be displayed on the page.", "type": "string" }, "iconUrl": { "description": "Icon that will be displayed on the page.", "type": "string" }, "primaryCoverImage": { "description": "Primary cover image that will be displayed on the page.", "type": "string" }, "secondaryCoverImage": { "description": "Secondary cover image that will be displayed on the page.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "backgroundColor": "#F08080", "brandColor": "#0E44E1", "rectShape": "ROUNDED", "fontType": "serif", "accentColor": "#F08080", "logoUrl": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "iconUrl": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "footerColor": "#CD5C5B", "primaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6", "secondaryCoverImage": "https://images.app.goo.gl/PxBcTVm4Q1xJFhCn6" }, "message": "Fetched Branding successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] }, "delete": { "operationId": "removeBrandingForPartner", "summary": "Remove Branding for Partner", "description": "Removes the existing branding configuration at the partner level.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message describing the outcome of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Configuration deleted successfully for id [8113d3f8403b380409] and type PARTNER" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/ai/branding": { "post": { "operationId": "generateBrandingWithAiForPartner", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Branding APIs" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "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.", "type": "string" } } }, "example": { "url": "https://www.surfboard.se" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The generated branding suggestions.", "type": "object", "properties": { "brandingOptions": { "description": "The suggested branding configurations. Each entry is a complete set of branding values you can apply.", "type": "array", "items": { "type": "object", "properties": { "backgroundColor": { "description": "Suggested background color for the page, as a hex color code.", "type": "string" }, "brandColor": { "description": "Suggested primary brand color, as a hex color code.", "type": "string" }, "accentColor": { "description": "Suggested secondary color that complements the brand color, as a hex color code.", "type": "string" }, "rectShape": { "description": "Suggested shape for the page buttons.", "type": "string", "enum": [ null, null, null ] }, "fontType": { "description": "Suggested font family for the page.", "type": "string", "enum": [ null, null, null ] }, "logoUrl": { "description": "URL of the suggested logo to display on the page.", "type": "string" }, "iconUrl": { "description": "URL of the suggested icon to display on the page.", "type": "string" }, "footerColor": { "description": "Suggested footer background color, as a hex color code.", "type": "string" } }, "additionalProperties": true } }, "metadata": { "description": "Details about the generation run.", "type": "object", "properties": { "inputTokens": { "description": "Number of input tokens consumed to generate the suggestions.", "type": "number" }, "outputTokens": { "description": "Number of output tokens produced while generating the suggestions.", "type": "number" }, "outputType": { "description": "The kind of output that was generated.", "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "brandingOptions": [ { "backgroundColor": "#F5F5F5", "brandColor": "#0E44E1", "accentColor": "#F08080", "rectShape": "ROUNDED", "fontType": "sans-serif", "logoUrl": "https://res.cloudinary.com/image/surfboard-logo.svg", "iconUrl": "https://res.cloudinary.com/image/surfboard-icon.svg", "footerColor": "#CD5C5B" } ], "metadata": { "inputTokens": 1024, "outputTokens": 256, "outputType": "json" } }, "message": "Branding generated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to generate branding" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/token": { "post": { "operationId": "createToken", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Client Auth Tokens API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "providerId": { "description": "Provider ID of the auth provider", "type": "string" }, "providerCertificate": { "description": "Certificate of the auth provider", "type": "string" }, "externalUserId": { "description": "ExternalUserId ID to be assigned to the user who requires auth token", "type": "string" }, "email": { "description": "Email address of the user", "type": "string" } }, "required": [ "providerId", "providerCertificate", "externalUserId" ] }, "example": { "providerId": "BB72CE2C-B160-4BFE-ACB9-3FC270260C33", "providerCertificate": "2c95c565604048d7998a034ccbd2fbb5", "externalUserId": "A8895CBBCC503F" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'..", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "token": { "description": "Auth Token that is valid for a given interval specified in validUntil", "type": "string" }, "validUntil": { "description": "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.", "type": "string" } }, "required": [ "token", "validUntil" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/customers": { "post": { "operationId": "addCustomerDetails", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Customers API" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "description": "Customer's first name.", "type": "string" }, "middleName": { "description": "Customer's middle name.", "type": "string" }, "lastName": { "description": "Customer's surname or last name.", "type": "string" }, "birthDate": { "description": "Customer's date of birth in YYYY/MM/DD format.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code representing the customer's country, in uppercase.", "type": "string" }, "gender": { "description": "Customer's gender.", "type": "string" }, "address": { "description": "Array of customer addresses for different purposes (shipping, billing, etc.).", "type": "array", "items": { "type": "object", "properties": { "careOf": { "description": "Care of information for the address.", "type": "string" }, "addressLine1": { "description": "First line of the customer's address.", "type": "string" }, "addressLine2": { "description": "Second line of the customer's address.", "type": "string" }, "addressLine3": { "description": "Third line of the customer's address.", "type": "string" }, "city": { "description": "City of the customer's address.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code for the address, in uppercase.", "type": "string" }, "postalCode": { "description": "Postal code of the customer's address.", "type": "string" }, "role": { "description": "Purpose of the address (e.g., 'shipping', 'billing').", "type": "string" } }, "required": [ "addressLine1", "city", "countryCode", "postalCode" ] } }, "emails": { "description": "Array of customer email addresses with their respective roles.", "type": "array", "items": { "type": "object", "properties": { "email": { "description": "Customer's email address.", "type": "string" }, "role": { "description": "Role or purpose of the email address.", "type": "string" } }, "required": [ "email", "role" ] } }, "phoneNumbers": { "description": "Array of customer phone numbers with their respective roles.", "type": "array", "items": { "type": "object", "properties": { "phoneNumber": { "description": "Customer's phone number details.", "type": "object", "properties": { "code": { "description": "International dialing code for the phone number.", "type": "string" }, "number": { "description": "Phone number without the country code.", "type": "string" } }, "required": [ "code", "number" ] }, "role": { "description": "Role or purpose of the phone number (e.g., 'own', 'work', 'home').", "type": "string" } }, "required": [ "phoneNumber" ] } }, "cardIds": { "description": "Array of payment card identifiers associated with the customer.", "type": "array", "items": {} } } }, "example": { "firstName": "John", "middleName": "Doe", "birthDate": "1940/03/04", "countryCode": "SE", "address": [ { "careOf": "second address at 3:40", "addressLine1": "second address at 3:40", "addressLine2": "3rd west street", "addressLine3": "B-Block", "city": "Ølstykke Stenløse", "countryCode": "SE", "postalCode": "99 999", "role": "shipping" } ], "phoneNumbers": [ { "phoneNumber": { "code": "91", "number": "9876543210" }, "role": "own" } ], "cardIds": [ "824c514bfe001805f0", "827a63468b993801f0", "827a63460b99380df0" ] } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing the created customer information.", "type": "object", "properties": { "customerId": { "description": "Unique identifier assigned to the newly created customer.", "type": "string" } }, "required": [ "customerId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "customerId": "83018337960e2802f7" }, "message": "Added customer successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/customers/{customerId}": { "get": { "operationId": "fetchCustomerDetailsById", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Customers API" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Identifier for the customer this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing comprehensive customer information.", "type": "object", "properties": { "firstName": { "description": "Customer's first name.", "type": "string" }, "middleName": { "description": "Customer's middle name.", "type": "string" }, "lastName": { "description": "Customer's surname or last name.", "type": "string" }, "birthDate": { "description": "Customer's date of birth.", "type": "string" }, "gender": { "description": "Customer's gender.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code representing the customer's country.", "type": "string" }, "address": { "description": "Array of customer addresses.", "type": "array", "items": { "type": "object", "properties": { "careOf": { "description": "Care of information for the address.", "type": "string" }, "addressLine1": { "description": "First line of the customer's address.", "type": "string" }, "addressLine2": { "description": "Second line of the customer's address.", "type": "string" }, "addressLine3": { "description": "Third line of the customer's address.", "type": "string" }, "city": { "description": "City of the customer's address.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code for the address.", "type": "string" }, "postalCode": { "description": "Postal code of the customer's address.", "type": "string" }, "role": { "description": "Purpose of the address (e.g., 'shipping', 'billing').", "type": "string" } }, "required": [ "addressLine1", "city", "countryCode", "postalCode" ], "additionalProperties": true } }, "emails": { "description": "Array of customer email addresses.", "type": "array", "items": { "type": "object", "properties": { "email": { "description": "Customer's email address.", "type": "string" }, "role": { "description": "Role or purpose of the email address.", "type": "string" } }, "required": [ "email", "role" ], "additionalProperties": true } }, "phoneNumbers": { "description": "Array of customer phone numbers.", "type": "array", "items": { "type": "object", "properties": { "phoneNumber": { "description": "Customer's phone number details.", "type": "object", "properties": { "code": { "description": "International dialing code for the phone number.", "type": "string" }, "number": { "description": "Phone number without the country code.", "type": "string" } }, "required": [ "code", "number" ], "additionalProperties": true }, "role": { "description": "Role or purpose of the phone number.", "type": "string" } }, "required": [ "phoneNumber", "role" ], "additionalProperties": true } }, "cardIds": { "description": "Array of payment card identifiers associated with the customer.", "type": "array", "items": {} } }, "required": [ "countryCode", "address", "emails", "phoneNumbers", "cardIds" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "countryCode": "SE", "address": [ { "careOf": "second address at 3:40", "addressLine1": "second address at 3:40", "addressLine2": "3rd west street", "addressLine3": "B-Block", "city": "Ølstykke Stenløse", "countryCode": "SE", "postalCode": "99 999", "role": "shipping" } ], "emails": [], "phoneNumbers": [ { "phoneNumber": { "code": "91", "number": "9876543210" }, "role": "own" } ], "cardIds": [ "824c514bfe001805f0", "827a63468b993801f0", "827a63460b99380df0" ] }, "message": "Fetched customer details successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/stores/{storeId}/cash-register": { "post": { "operationId": "createCashRegister", "summary": "Create Cash Register", "description": "Create a Cash Register for a specific store.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Electronic Cash Register (ECR) V2 API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cashRegisterName": { "description": "Name of the cash register.", "type": "string" }, "deviceId": { "description": "Terminal / device identifier.", "type": "string" }, "emails": { "description": "List of email addresses for notifications.", "type": "array", "items": {} } }, "required": [ "cashRegisterName", "deviceId" ] }, "example": { "cashRegisterName": "Main Register", "deviceId": "{{terminalId}}", "emails": [ "store.manager@example.com" ] } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "cashRegister": { "description": "Cash register details.", "type": "object", "properties": { "cashRegisterId": { "description": "Unique identifier for the cash register. Save this ID as it is required for opening the register and shifts.", "type": "string" } }, "required": [ "cashRegisterId" ], "additionalProperties": true } }, "required": [ "cashRegister" ], "additionalProperties": true }, "message": { "description": "Response message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "cashRegister": { "cashRegisterId": "{{cashRegisterId}}" } }, "message": "Cash register subscribed successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/cash-register/withdraw": { "put": { "operationId": "withdrawCash", "summary": "Withdraw Cash", "description": "Record a cash withdrawal taken out of the cash register during an active shift.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Electronic Cash Register (ECR) V2 API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "description": "Amount to withdraw.", "type": "number" }, "terminalId": { "description": "Terminal / device identifier.", "type": "string" } }, "required": [ "amount", "terminalId" ] }, "example": { "amount": 500, "terminalId": "{{terminalId}}" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "Response message.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Cash withdrawn successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/cash-register": { "get": { "operationId": "fetchCashRegisters", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Electronic Cash Register (ECR) V2 API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Array of cash register objects.", "type": "array", "items": { "type": "object", "properties": { "cashRegisterId": { "description": "Unique identifier of the cash register.", "type": "string" }, "storeId": { "description": "Store identifier.", "type": "string" }, "terminalId": { "description": "Associated terminal (may be null if not yet assigned).", "type": "string" }, "merchantId": { "description": "Merchant identifier.", "type": "string" }, "cashRegisterName": { "description": "Name of the cash register.", "type": "string" } }, "required": [ "cashRegisterId", "storeId", "merchantId", "cashRegisterName" ], "additionalProperties": true } }, "message": { "description": "Response message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "cashRegisterId": "{{cashRegisterId}}", "storeId": "{{storeId}}", "terminalId": "{{terminalId}}", "merchantId": "{{merchantId}}", "cashRegisterName": "Main Register" } ], "message": "Cash registers fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/cash-register/{cashRegisterId}": { "delete": { "operationId": "deleteCashRegister", "summary": "Delete Cash Register", "description": "Delete a Cash Register. The register is identified by the :cashRegisterId path parameter.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Electronic Cash Register (ECR) V2 API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "cashRegisterId", "in": "path", "required": true, "description": "Identifier for the cash register this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "Response message.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Cash register unsubscribed successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "get": { "operationId": "getCashRegisterById", "summary": "Get Cash Register by ID", "description": "Retrieve the full cash-register record, including its control-unit details, identified by the :cashRegisterId path parameter.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Electronic Cash Register (ECR) V2 API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "cashRegisterId", "in": "path", "required": true, "description": "Identifier for the cash register this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "cashRegisterId": { "description": "Cash register identifier.", "type": "string" }, "cashRegisterName": { "description": "Name of the cash register.", "type": "string" }, "activationDate": { "description": "Date the cash register was activated.", "type": "string" }, "closingTime": { "description": "Configured automatic closing time for the register.", "type": "string" }, "designation": { "description": "Designation of the cash register.", "type": "string" }, "modelOrProgram": { "description": "Model or program of the cash register.", "type": "string" }, "address": { "description": "Address associated with the cash register.", "type": "string" }, "email": { "description": "Email addresses configured to receive this register's reports.", "type": "array", "items": {} }, "controlUnitAddress": { "description": "Address of the paired fiscal control unit.", "type": "string" }, "controlUnitManufacturer": { "description": "Manufacturer of the control unit.", "type": "string" }, "controlUnitType": { "description": "Type of the control unit.", "type": "string" }, "controlUnitModel": { "description": "Model of the control unit.", "type": "string" }, "controlUnitSerialNumber": { "description": "Serial number of the paired fiscal control unit.", "type": "string" }, "notifications": { "description": "Per-email notification subscriptions.", "type": "array", "items": { "type": "object", "properties": { "email": { "description": "Email address subscribed to the notification.", "type": "string" }, "reports": { "description": "Report types this email receives.", "type": "array", "items": {} } }, "required": [ "email", "reports" ], "additionalProperties": true } } }, "required": [ "cashRegisterId", "cashRegisterName", "activationDate", "closingTime", "designation", "modelOrProgram", "address", "email", "controlUnitAddress", "controlUnitManufacturer", "controlUnitType", "controlUnitModel", "controlUnitSerialNumber", "notifications" ], "additionalProperties": true }, "message": { "description": "Response message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "cashRegisterId": "{{cashRegisterId}}", "cashRegisterName": "Main Register", "activationDate": "2026-04-15", "closingTime": "23:00", "designation": "Register 1", "modelOrProgram": "Surfboard ECR 1.0", "address": "Main Street 1, Stockholm", "email": [ "store.manager@example.com" ], "controlUnitAddress": "Main Street 1, Stockholm", "controlUnitManufacturer": "Surfboard", "controlUnitType": "SOFTWARE", "controlUnitModel": "CU-100", "controlUnitSerialNumber": "{{controlUnitSerialNumber}}", "notifications": [ { "email": "store.manager@example.com", "reports": [ "Z_REPORT" ] } ] }, "message": "Fetched cash register successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/stores/{storeId}/cash-register/{cashRegisterId}/state-info": { "get": { "operationId": "getCashRegisterState", "summary": "Get Cash Register State", "description": "Retrieve the current state of a cash register, including its active shift, identified by the :cashRegisterId path parameter.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Electronic Cash Register (ECR) V2 API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "cashRegisterId", "in": "path", "required": true, "description": "Identifier for the cash register this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "cashRegisterState": { "description": "Current lifecycle state of the cash register.", "type": "string" }, "cashRegisterId": { "description": "Cash register identifier.", "type": "string" }, "cashRegisterName": { "description": "Name of the cash register.", "type": "string" }, "currencyCode": { "description": "Currency in which the register operates.", "type": "string" }, "shiftInfo": { "description": "Current or most recent shift information.", "type": "object", "properties": { "shiftNumber": { "description": "Shift number.", "type": "number" }, "shiftState": { "description": "Current state of the shift.", "type": "string" }, "cashierName": { "description": "Name of the cashier.", "type": "string" }, "shiftOpenedAt": { "description": "Timestamp when the shift started.", "type": "string" }, "shiftClosedAt": { "description": "Timestamp when the shift was closed.", "type": "string" } }, "required": [ "shiftNumber", "shiftState" ], "additionalProperties": true }, "pettyCash": { "description": "Current petty-cash balance held in the register.", "type": "number" }, "openedAt": { "description": "Timestamp when the register was opened.", "type": "string" }, "closedAt": { "description": "Timestamp when the register was closed.", "type": "string" } }, "required": [ "cashRegisterState", "cashRegisterId", "cashRegisterName", "currencyCode", "shiftInfo", "pettyCash" ], "additionalProperties": true }, "message": { "description": "Response message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "cashRegisterState": "CASH_REGISTER_OPEN", "cashRegisterId": "{{cashRegisterId}}", "cashRegisterName": "Main Register", "currencyCode": "SEK", "shiftInfo": { "shiftNumber": 1, "shiftState": "SHIFT_OPEN", "cashierName": "John Doe", "shiftOpenedAt": "2026-04-15T12:00:00Z", "shiftClosedAt": null }, "pettyCash": 5000, "openedAt": "2026-04-15T08:00:00Z", "closedAt": null }, "message": "Fetched cash register state successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/stores/{storeId}/cash-register/{cashRegisterId}/open-shift": { "put": { "operationId": "openShift", "summary": "Open-Shift", "description": "Open a cashier shift on the cash register identified by the :cashRegisterId path parameter.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Electronic Cash Register (ECR) V2 API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "cashRegisterId", "in": "path", "required": true, "description": "Identifier for the cash register this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terminalId": { "description": "Terminal / device identifier opening the shift.", "type": "string" }, "pettyCash": { "description": "Opening petty-cash float for the shift.", "type": "number" }, "cashierName": { "description": "Name of the cashier opening the shift.", "type": "string" } }, "required": [ "terminalId", "pettyCash" ] }, "example": { "terminalId": "{{terminalId}}", "pettyCash": 5000, "cashierName": "John Doe" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Opened shift details.", "type": "object", "additionalProperties": true }, "message": { "description": "Response message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": {}, "message": "Shift opened successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/stores/{storeId}/cash-register/{cashRegisterId}/close-shift": { "put": { "operationId": "closeShift", "summary": "Close-Shift", "description": "Close the active shift on the cash register identified by the :cashRegisterId path parameter.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Electronic Cash Register (ECR) V2 API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "cashRegisterId", "in": "path", "required": true, "description": "Identifier for the cash register this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "cashRegisterId": { "description": "Cash register identifier.", "type": "string" }, "shiftNumber": { "description": "Number of the shift that was closed.", "type": "number" }, "pettyCash": { "description": "Petty-cash balance recorded at shift close.", "type": "number" } }, "required": [ "cashRegisterId", "shiftNumber", "pettyCash" ], "additionalProperties": true }, "message": { "description": "Response message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "cashRegisterId": "{{cashRegisterId}}", "shiftNumber": 1, "pettyCash": 5000 }, "message": "Shift closed successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/stores/{storeId}/cash-register/{cashRegisterId}/end-of-day": { "put": { "operationId": "endOfDay", "summary": "End of Day", "description": "Perform the end-of-day close on the cash register identified by the :cashRegisterId path parameter.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Electronic Cash Register (ECR) V2 API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "cashRegisterId", "in": "path", "required": true, "description": "Identifier for the cash register this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "Response message.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Cash register closed successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/stores/{storeId}/cash-register/{cashRegisterId}/closing-time": { "patch": { "operationId": "updateScheduledCloseTime", "summary": "Update Scheduled Close Time", "description": "Update 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\nReference: https://developers.surfboardpayments.com/", "tags": [ "Electronic Cash Register (ECR) V2 API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "cashRegisterId", "in": "path", "required": true, "description": "Identifier for the cash register this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "closingTime": { "description": "New automatic closing time; sending it sets the shift close type to CUSTOM.", "type": "string" } }, "required": [ "closingTime" ] }, "example": { "closingTime": "23:00" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "cashRegisterId": { "description": "Cash register identifier.", "type": "string" }, "newClosingTime": { "description": "Closing time now configured for the register.", "type": "string" }, "shiftCloseType": { "description": "Close type that was applied (CUSTOM).", "type": "string" }, "scheduledClosingTime": { "description": "Next scheduled automatic close, when applicable.", "type": "string" } }, "required": [ "cashRegisterId", "newClosingTime", "shiftCloseType" ], "additionalProperties": true }, "message": { "description": "Response message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "cashRegisterId": "{{cashRegisterId}}", "newClosingTime": "23:00", "shiftCloseType": "CUSTOM", "scheduledClosingTime": "2026-04-16T23:00:00Z" }, "message": "Cash register closing time updated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/stores/{storeId}/cash-register/deposit-petty-cash": { "post": { "operationId": "depositPettyCash", "summary": "Deposit Petty Cash", "description": "Deposit petty cash into the cash register during an active shift.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Electronic Cash Register (ECR) V2 API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terminalId": { "description": "Terminal / device identifier depositing the petty cash.", "type": "string" }, "amount": { "description": "Amount of petty cash to deposit into the register.", "type": "number" } }, "required": [ "terminalId", "amount" ] }, "example": { "terminalId": "{{terminalId}}", "amount": 1000 } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "cashRegisterId": { "description": "Cash register identifier.", "type": "string" }, "newPettyCash": { "description": "Petty-cash balance after the deposit.", "type": "number" } }, "required": [ "cashRegisterId", "newPettyCash" ], "additionalProperties": true }, "message": { "description": "Response message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "cashRegisterId": "{{cashRegisterId}}", "newPettyCash": 6000 }, "message": "Petty cash inserted successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/stores/{storeId}/cash-register/{cashRegisterId}/files": { "get": { "operationId": "getCashRegisterFiles", "summary": "Get Cash Register Files", "description": "Retrieve the files/reports generated for a cash register, identified by the :cashRegisterId path parameter.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Electronic Cash Register (ECR) V2 API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "cashRegisterId", "in": "path", "required": true, "description": "Identifier for the cash register this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "reportType", "in": "query", "required": false, "description": "Filters files to a specific report type; applied only when present.", "schema": { "description": "Filters files to a specific report type; applied only when present.", "type": "string" } }, { "name": "startDate", "in": "query", "required": false, "description": "Start of the date range to filter files by; applied only when present.", "schema": { "description": "Start of the date range to filter files by; applied only when present.", "type": "string" } }, { "name": "endDate", "in": "query", "required": false, "description": "End of the date range to filter files by; applied only when present.", "schema": { "description": "End of the date range to filter files by; applied only when present.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Array of cash register file objects.", "type": "array", "items": { "type": "object", "properties": { "fileName": { "description": "Name of the file.", "type": "string" }, "fileType": { "description": "Type of the file.", "type": "string" }, "reportType": { "description": "Report type the file belongs to.", "type": "string" }, "sequence": { "description": "Ordinal sequence number of the file within its report type.", "type": "number" }, "fileUrl": { "description": "Download URL for the file.", "type": "string" } }, "required": [ "fileName", "fileType", "reportType", "sequence", "fileUrl" ], "additionalProperties": true } }, "message": { "description": "Response message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "fileName": "z-report-2026-04-15.pdf", "fileType": "application/pdf", "reportType": "Z_REPORT", "sequence": 1, "fileUrl": "https://files.example.com/z-report-2026-04-15.pdf" } ], "message": "Cash register files fetched successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/giftcards": { "post": { "operationId": "createGiftCard", "summary": "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).\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Gift Cards API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cardType": { "description": "Type of gift card to create.\n\nValues:\n- `FUND`: Gift card with monetary value\n- `ENTITLEMENT`: Gift card with usage-based limits", "type": "string", "enum": [ "FUND", "ENTITLEMENT" ] }, "amount": { "description": "Monetary amount for FUND type gift cards. Required when cardType is FUND.", "type": "number" }, "redemptionLimit": { "description": "Number of times the gift card can be used. Required when cardType is ENTITLEMENT.", "type": "number" }, "currency": { "description": "Currency code for the gift card amount.", "type": "string" }, "name": { "description": "Optional name for the gift card.", "type": "string" }, "accessControl": { "description": "Access control level for the gift card.\n\nValues:\n- `OPEN`: Gift card can be used by anyone\n- `RESTRICTED`: Gift card has restricted access", "type": "string", "enum": [ "OPEN", "RESTRICTED" ] }, "expiryDate": { "description": "Expiry date for the gift card in mm/dd/yyyy or mm-dd-yyyy format.", "type": "string" }, "note": { "description": "Optional note or description for the gift card.", "type": "string" } }, "required": [ "cardType" ] }, "example": { "cardType": "FUND", "amount": 100, "currency": "SEK", "name": "Holiday Gift Card", "accessControl": "OPEN", "expiryDate": "12/31/2024", "note": "Happy Holidays!" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing gift card details.", "type": "object", "properties": { "giftCardId": { "description": "Unique identifier for the created gift card.", "type": "string" }, "pan": { "description": "Primary Account Number for the gift card.", "type": "string" }, "name": { "description": "Name of the gift card.", "type": "string" }, "formats": { "description": "Different format representations of the gift card.", "type": "object", "properties": { "qrCode": { "description": "QR code representation of the gift card.", "type": "string" }, "nfcData": { "description": "NFC data for the gift card.", "type": "string" }, "barcode": { "description": "Barcode representation of the gift card.", "type": "string" } }, "additionalProperties": true }, "cardType": { "description": "Type of the gift card (FUND or ENTITLEMENT).", "type": "string" }, "amount": { "description": "Monetary amount for FUND type gift cards.", "type": "number" }, "redemptionLimit": { "description": "Usage limit for ENTITLEMENT type gift cards.", "type": "number" }, "currency": { "description": "Currency code for the gift card.", "type": "string" }, "accessControl": { "description": "Access control level of the gift card.", "type": "string" }, "externalId": { "description": "External identifier for the gift card.", "type": "string" }, "externalIdType": { "description": "Type of external identifier.", "type": "string" }, "status": { "description": "Current status of the gift card.", "type": "string" }, "shareableLink": { "description": "Shareable link for the gift card.", "type": "string" }, "expiryDate": { "description": "Expiry date of the gift card.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "giftCardId": "83a5aea0381600045c", "pan": "1504703347938280", "name": "Birthday Gift Card", "formats": { "qrCode": "undefinedVWwIYiYXCANr202512310200", "nfcData": "undefinedVWwIYiYXCANr202512310200", "barcode": "2877866156" }, "cardType": "FUND", "amount": 100, "redemptionLimit": 0, "currency": "SEK", "accessControl": "OPEN", "externalId": "m_iWGri3XAyTmkbKYsYtV47", "externalIdType": "MERCHANT", "status": "CREATED", "shareableLink": "https://slr.test.surfboard.se/afaa6fb5" }, "message": "Gift card created successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "get": { "operationId": "getAllGiftCards", "summary": "Get All Gift Cards", "description": "Retrieves a paginated list of all gift cards for a merchant. Supports filtering by type and status.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Gift Cards API" ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Filter gift cards by type.\n\nValues:\n- `FUND`: Gift cards with monetary value\n- `ENTITLEMENT`: Gift cards with usage-based limits", "schema": { "description": "Filter gift cards by type.\n\nValues:\n- `FUND`: Gift cards with monetary value\n- `ENTITLEMENT`: Gift cards with usage-based limits", "type": "string", "enum": [ "FUND", "ENTITLEMENT" ] } }, { "name": "status", "in": "query", "required": false, "description": "Filter gift cards by status.", "schema": { "description": "Filter gift cards by status.", "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Array of gift card objects.", "type": "array", "items": { "type": "object", "properties": { "giftCardId": { "description": "Unique identifier for the gift card.", "type": "string" }, "pan": { "description": "Primary Account Number for the gift card.", "type": "string" }, "name": { "description": "Name of the gift card.", "type": "string" }, "cardType": { "description": "Type of the gift card (FUND or ENTITLEMENT).", "type": "string" }, "amount": { "description": "Original monetary amount for FUND type gift cards.", "type": "number" }, "currentAmount": { "description": "Current remaining amount for FUND type gift cards.", "type": "number" }, "usageCount": { "description": "Number of times the gift card has been used.", "type": "number" }, "redemptionLimit": { "description": "Usage limit for ENTITLEMENT type gift cards.", "type": "number" }, "currency": { "description": "Currency code for the gift card.", "type": "string" }, "accessControl": { "description": "Access control level of the gift card.", "type": "string" }, "status": { "description": "Current status of the gift card.", "type": "string" }, "expiryDate": { "description": "Expiry date of the gift card.", "type": "string" }, "lastTransactionAt": { "description": "Timestamp of the last transaction.", "type": "string" }, "transactionCount": { "description": "Total number of transactions.", "type": "number" }, "totalRedeemed": { "description": "Total amount redeemed from the gift card.", "type": "number" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "giftCardId": "83a2adb2fd9d58095c", "pan": "1802723955691673", "name": "Birthday Gift Card", "cardType": "FUND", "amount": 100, "currentAmount": 100, "usageCount": 0, "redemptionLimit": 0, "currency": "SEK", "accessControl": "OPEN", "status": "CREATED", "expiryDate": "2025-12-31T00:00:00.000Z", "transactionCount": 0, "totalRedeemed": 0 }, { "giftCardId": "83a2ac747d9d580b5c", "pan": "1167728279630112", "name": "Birthday Gift Card", "cardType": "FUND", "amount": 100, "currentAmount": 100, "usageCount": 0, "redemptionLimit": 0, "currency": "SEK", "accessControl": "OPEN", "status": "CREATED", "expiryDate": "2025-12-31T00:00:00.000Z", "transactionCount": 0, "totalRedeemed": 0 }, { "giftCardId": "83a256695d9d28025c", "pan": "1657679889602692", "name": "Birthday Gift Card", "cardType": "FUND", "amount": 100, "currentAmount": 100, "usageCount": 0, "redemptionLimit": 0, "currency": "SEK", "accessControl": "OPEN", "status": "CREATED", "expiryDate": "2025-12-31T00:00:00.000Z", "transactionCount": 0, "totalRedeemed": 0 } ], "message": "Gift cards fetched" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/giftcards/{id}": { "get": { "operationId": "getGiftCardDetails", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Gift Cards API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier for the id this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Detailed gift card information.", "type": "object", "properties": { "giftCardId": { "description": "Unique identifier for the gift card.", "type": "string" }, "pan": { "description": "Primary Account Number for the gift card.", "type": "string" }, "name": { "description": "Name of the gift card.", "type": "string" }, "cardType": { "description": "Type of the gift card (FUND or ENTITLEMENT).", "type": "string" }, "amount": { "description": "Original monetary amount for FUND type gift cards.", "type": "number" }, "currentAmount": { "description": "Current remaining amount for FUND type gift cards.", "type": "number" }, "usageCount": { "description": "Number of times the gift card has been used.", "type": "number" }, "redemptionLimit": { "description": "Usage limit for ENTITLEMENT type gift cards.", "type": "number" }, "currency": { "description": "Currency code for the gift card.", "type": "string" }, "accessControl": { "description": "Access control level of the gift card.", "type": "string" }, "status": { "description": "Current status of the gift card.", "type": "string" }, "expiryDate": { "description": "Expiry date of the gift card.", "type": "string" }, "lastTransactionAt": { "description": "Timestamp of the last transaction.", "type": "string" }, "transactionCount": { "description": "Total number of transactions.", "type": "number" }, "totalRedeemed": { "description": "Total amount redeemed from the gift card.", "type": "number" }, "customerDetails": { "description": "Customer information associated with the gift card.", "type": "object", "properties": { "customerId": { "description": "Unique identifier for the customer.", "type": "string" }, "firstName": { "description": "Customer's first name.", "type": "string" }, "middleName": { "description": "Customer's middle name.", "type": "string" }, "surname": { "description": "Customer's surname.", "type": "string" }, "countryCode": { "description": "Customer's country code.", "type": "string" }, "emails": { "description": "Array of customer email addresses.", "type": "array", "items": { "type": "object", "properties": { "email": { "description": "Customer email address.", "type": "string" } }, "additionalProperties": true } }, "phoneNumbers": { "description": "Array of customer phone numbers.", "type": "array", "items": { "type": "object", "properties": { "phoneNumber": { "description": "Customer phone number details.", "type": "object", "properties": { "countryCode": { "description": "Phone number country code.", "type": "string" }, "number": { "description": "Phone number.", "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true }, "shareableLink": { "description": "Shareable link for the gift card.", "type": "string" }, "formats": { "description": "Different format representations of the gift card.", "type": "object", "properties": { "qrCode": { "description": "QR code representation of the gift card.", "type": "string" }, "nfcData": { "description": "NFC data for the gift card.", "type": "string" }, "barcode": { "description": "Barcode representation of the gift card.", "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "giftCardId": "83a2adb2fd9d58095c", "pan": "1802723955691673", "name": "Birthday Gift Card", "cardType": "FUND", "amount": 100, "currentAmount": 75, "usageCount": 2, "redemptionLimit": 0, "currency": "SEK", "accessControl": "OPEN", "externalId": "m_iWGri3XAyTmkbKYsYtV47", "externalIdType": "MERCHANT", "status": "ACTIVE", "expiryDate": "2025-12-31T00:00:00.000Z", "lastTransactionAt": "2024-11-15T10:30:00Z", "transactionCount": 2, "totalRedeemed": 25, "customerDetails": { "customerId": "83a2adb2fd9d58001c", "firstName": "John", "surname": "Doe", "countryCode": "SE", "emails": [ { "email": "john.doe@example.com" } ], "phoneNumbers": [ { "phoneNumber": { "countryCode": "+46", "number": "701234567" } } ] }, "shareableLink": "https://slr.test.surfboard.se/afaa6fb5", "formats": { "qrCode": "undefinedVWwIYiYXCANr202512310200", "nfcData": "undefinedVWwIYiYXCANr202512310200", "barcode": "2877866156" } }, "message": "Gift card details retrieved successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/giftcards/{giftCardId}/transactions": { "get": { "operationId": "getGiftCardTransactions", "summary": "Get Gift Card Transactions", "description": "Retrieves a paginated list of transactions for a specific gift card. Supports filtering by transaction type.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Gift Cards API" ], "parameters": [ { "name": "giftCardId", "in": "path", "required": true, "description": "Identifier for the gift card this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "transactionType", "in": "query", "required": false, "description": "Filter transactions by type.\n\nValues:\n- `ISSUED`: Gift card issuance transactions\n- `CREDIT`: Credit transactions (adding value)\n- `DEBIT`: Debit transactions (using value)", "schema": { "description": "Filter transactions by type.\n\nValues:\n- `ISSUED`: Gift card issuance transactions\n- `CREDIT`: Credit transactions (adding value)\n- `DEBIT`: Debit transactions (using value)", "type": "string", "enum": [ "ISSUED", "CREDIT", "DEBIT" ] } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Array of transaction objects.", "type": "array", "items": { "type": "object", "properties": { "paymentId": { "description": "Unique identifier for the payment/transaction.", "type": "string" }, "transactionType": { "description": "Type of transaction (ISSUED, CREDIT, DEBIT).", "type": "string" }, "transactionAmount": { "description": "Amount involved in the transaction.", "type": "number" }, "currency": { "description": "Currency code for the transaction amount.", "type": "string" }, "valueBefore": { "description": "Gift card value before the transaction.", "type": "number" }, "valueAfter": { "description": "Gift card value after the transaction.", "type": "number" }, "orderId": { "description": "Associated order ID if applicable.", "type": "string" }, "merchantId": { "description": "Merchant ID associated with the transaction.", "type": "string" }, "storeId": { "description": "Store ID associated with the transaction.", "type": "string" }, "metadata": { "description": "Additional metadata for the transaction.", "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "paymentId": "83a2adb2fd9d58095d", "transactionType": "ISSUED", "transactionAmount": 100, "currency": "SEK", "valueBefore": 0, "valueAfter": 100, "merchantId": "83a2adb2fd9d58001a", "storeId": "83a2adb2fd9d58002b" }, { "paymentId": "83a2adb2fd9d58095e", "transactionType": "DEBIT", "transactionAmount": 25, "currency": "SEK", "valueBefore": 100, "valueAfter": 75, "orderId": "83a2adb2fd9d58003c", "merchantId": "83a2adb2fd9d58001a", "storeId": "83a2adb2fd9d58002b", "metadata": { "terminalId": "83a2adb2fd9d58004d", "transactionDate": "2024-11-15T10:30:00Z" } } ], "message": "Gift card transactions retrieved successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/merchants/{merchantId}/shipment": { "post": { "operationId": "createShipment", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Logistics API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shippingAddress": { "description": "Input the shipping address for the products. If no address is specified, the merchant's address will be used as the default shipping address.", "type": "object", "properties": { "name": { "description": "Full name of the receiver for the shipment.", "type": "string" }, "addressLine1": { "description": "The first line of the receiver's address.", "type": "string" }, "addressLine2": { "description": "The second line of the receiver's address.", "type": "string" }, "addressLine3": { "description": "The third line of the receiver's address.", "type": "string" }, "city": { "description": "City of the receiver", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code of the receiver, in uppercase.", "type": "string" }, "postalCode": { "description": "Postal code of the receiver.", "type": "string" }, "phoneNumber": { "description": "Contact number of the receiver in code and number format.", "type": "object", "properties": { "code": { "description": "International dialing code identifying the country or region.", "type": "string" }, "number": { "description": "Phone number.", "type": "string" } }, "required": [ "code", "number" ] }, "email": { "description": "Email address of the receiver.", "type": "string" }, "deliveryInstruction": { "description": "Delivery instructions for the carrier.", "type": "string" } }, "required": [ "name", "addressLine1", "city", "countryCode", "postalCode" ] }, "lineItems": { "description": "An array of products to be shipped.", "type": "array", "items": { "type": "object", "properties": { "productId": { "description": "The SurfboardProductId of the product or group of products. This is unique to the partner.", "type": "string" }, "quantity": { "description": "Number of products or group of products to be shipped.", "type": "number" }, "billingPlanId": { "description": "Optional billing plan for the product or group of products chosen. If omitted, default plan will be chosen.", "type": "string" }, "replacementFor": { "description": "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.", "type": "string" } }, "required": [ "productId", "quantity" ] } } }, "required": [ "lineItems" ] }, "example": { "shippingAddress": { "name": "John Doe", "addressLine1": "Main Street 123", "addressLine2": "Building C", "addressLine3": "Building C", "city": "Stockholm", "countryCode": "SE", "postalCode": "123 45", "phoneNumber": { "code": "46", "number": "771890089" }, "email": "developer@test.se", "deliveryInstruction": "XXX" }, "lineItems": [ { "productId": "12345", "quantity": 1 } ] } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'..", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "orderId": { "description": "Order ID for the order.", "type": "string" } }, "required": [ "orderId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "orderId": "81376ad8ebedf80310" }, "message": "Order for shipping terminal successfully created" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/partners/{partnerId}/merchants/{merchantId}/shipment/{orderId}": { "get": { "operationId": "getShipmentStatus", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Logistics API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "orderId", "in": "path", "required": true, "description": "Identifier for the order this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'..", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "orderStatus": { "description": "Describes the status of the shipment order for terminals and accessories. The possible values are:\n\nValues:\n- `ORDER_PLACED`: The order has been successfully placed.\n- `ORDER_SHIPPED`: The order has been shipped and is in transit.\n- `ORDER_COMPLETED`: The order has been successfully fulfilled and completed.\n- `ORDER_PENDING_FOR_STOCK`: The order is pending processing due to stock availability.", "type": "string", "enum": [ "ORDER_PLACED", "ORDER_SHIPPED", "ORDER_COMPLETED", "ORDER_PENDING_FOR_STOCK" ] }, "trackingUrl": { "description": "The tracking url of the shipment.", "type": "string" }, "trackingCode": { "description": "The carrier's tracking code for the shipment.", "type": "string" }, "deliveryPartner": { "description": "The partner or carrier responsible for delivering the shipment.", "type": "string" }, "packages": { "description": "Specifies information about the products included in the shipment.", "type": "array", "items": { "type": "object", "properties": { "productId": { "description": "The SurfboardProductId of the product or group of products. This is unique to the partner", "type": "string" }, "serialNumber": { "description": "Serial number of the device.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "orderStatus": "ORDER_PENDING_FOR_STOCK", "trackingUrl": "", "trackingCode": "", "deliveryPartner": "DHL", "packages": [ { "productId": "817361bb0a23400701", "serialNumber": "" } ] }, "message": "Order status fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/partners/{partnerId}/manufactured-hardware": { "get": { "operationId": "listManufacturedHardware", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Logistics API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "serialNo", "in": "query", "required": false, "description": "Return only the device with this hardware serial number.", "schema": { "description": "Return only the device with this hardware serial number.", "type": "string" } }, { "name": "terminalId", "in": "query", "required": false, "description": "Return only the device provisioned as this terminal.", "schema": { "description": "Return only the device provisioned as this terminal.", "type": "string" } }, { "name": "deviceModel", "in": "query", "required": false, "description": "Return only devices of this model, for example Surfpad.", "schema": { "description": "Return only devices of this model, for example Surfpad.", "type": "string" } }, { "name": "deviceVendor", "in": "query", "required": false, "description": "Return only devices from this hardware vendor.", "schema": { "description": "Return only devices from this hardware vendor.", "type": "string" } }, { "name": "merchantId", "in": "query", "required": false, "description": "Return only devices currently assigned to this merchant.", "schema": { "description": "Return only devices currently assigned to this merchant.", "type": "string" } }, { "name": "sortBy", "in": "query", "required": false, "description": "The field to order the results by.\n\nValues:\n- `createdAt`: Sort by the date the device record was created.\n- `serialNo`: Sort by hardware serial number.\n- `status`: Sort by the device's current lifecycle status.", "schema": { "description": "The field to order the results by.\n\nValues:\n- `createdAt`: Sort by the date the device record was created.\n- `serialNo`: Sort by hardware serial number.\n- `status`: Sort by the device's current lifecycle status.", "type": "string", "enum": [ "createdAt", "serialNo", "status" ] } }, { "name": "sortOrder", "in": "query", "required": false, "description": "The direction to sort the results in.\n\nValues:\n- `ASC`: Sort in ascending order.\n- `DESC`: Sort in descending order.", "schema": { "description": "The direction to sort the results in.\n\nValues:\n- `ASC`: Sort in ascending order.\n- `DESC`: Sort in descending order.", "type": "string", "enum": [ "ASC", "DESC" ] } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The manufactured devices on the current page.", "type": "array", "items": { "type": "object", "properties": { "serialNo": { "description": "Hardware serial number of the device.", "type": "string" }, "cpuSerialNumber": { "description": "Serial number of the device's CPU.", "type": "string" }, "deviceSerialNumber": { "description": "Manufacturer's device serial number.", "type": "string" }, "terminalId": { "description": "Identifier of the terminal this device was provisioned as, once activated.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant the device is currently assigned to.", "type": "string" }, "deviceModel": { "description": "Model of the device, for example Surfpad.", "type": "string" }, "deviceVendor": { "description": "Hardware vendor that manufactured the device.", "type": "string" }, "osType": { "description": "Operating system running on the device.", "type": "string" }, "osVersion": { "description": "Operating system version installed on the device.", "type": "string" }, "adminVersion": { "description": "Version of the Surfboard admin application installed on the device.", "type": "string" }, "pinpadVersion": { "description": "Version of the PIN pad firmware installed on the device.", "type": "string" }, "softwareVersion": { "description": "Version of the payment software installed on the device.", "type": "string" }, "imeiNumber": { "description": "IMEI number of the device's cellular modem.", "type": "string" }, "imsiNumber": { "description": "IMSI number of the SIM provisioned in the device.", "type": "string" }, "uiccid": { "description": "ICCID of the SIM card provisioned in the device.", "type": "string" }, "status": { "description": "Current lifecycle status of the device, for example whether it has been manufactured, shipped, or activated.", "type": "string" }, "lastOperation": { "description": "The most recent operation performed on the device.", "type": "string" }, "manufacturedFor": { "description": "Identifier of the partner the device was manufactured for.", "type": "string" }, "shippedTo": { "description": "Identifier of the merchant or destination the device was shipped to.", "type": "string" }, "createdAt": { "description": "When the device record was created, in ISO 8601 format.", "type": "string" }, "startDate": { "description": "Start of the device's active service period.", "type": "string" }, "endDate": { "description": "End of the device's active service period.", "type": "string" }, "createdBy": { "description": "Identifier of the user or system that created the device record.", "type": "string" }, "createdFrom": { "description": "The source or channel the device record was created from.", "type": "string" }, "updatedAt": { "description": "When the device record was last updated, in ISO 8601 format.", "type": "string" }, "updatedBy": { "description": "Identifier of the user or system that last updated the device record.", "type": "string" }, "updatedFrom": { "description": "The source or channel the device record was last updated from.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "serialNo": "TERM001234567", "cpuSerialNumber": "CPU-8841207", "deviceSerialNumber": "DSN-55120983", "terminalId": "816a0ff6bc0fb00404", "merchantId": "m_iWGri3XAyTmkbKYsYtV47", "deviceModel": "Surfpad", "deviceVendor": "Sunmi", "osType": "Android", "osVersion": "11", "adminVersion": "3.4.1", "pinpadVersion": "1.2.0", "softwareVersion": "5.8.2", "imeiNumber": "356938035643809", "imsiNumber": "240080012345678", "uiccid": "8946071512345678901", "status": "SHIPPED", "manufacturedFor": "8113d3f8403b380409", "shippedTo": "m_iWGri3XAyTmkbKYsYtV47", "createdAt": "2026-06-01T09:24:11.000Z", "startDate": "2026-06-02", "endDate": "2027-06-02" } ], "message": "Manufactured hardware fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch manufactured hardware" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/change-merchant": { "post": { "operationId": "changeMerchantForTerminal", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Logistics API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serialNo": { "description": "Serial number of the terminal to reassign.", "type": "string" }, "targetMerchantId": { "description": "Identifier of the merchant the terminal should be reassigned to.", "type": "string" } }, "required": [ "serialNo", "targetMerchantId" ] }, "example": { "serialNo": "TERM001234567", "targetMerchantId": "m_iWGri3XAyTmkbKYsYtV47" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Merchant changed for terminal successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to change merchant for the terminal" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/merchants/{merchantId}/ship-hardware": { "post": { "operationId": "shipManufacturedHardware", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Logistics API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serialNo": { "description": "Serial number of the manufactured device to ship and activate for the merchant.", "type": "string" } }, "required": [ "serialNo" ] }, "example": { "serialNo": "TERM001234567" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Manufactured hardware shipped successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to ship the terminal" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/logistics/orders": { "post": { "operationId": "shipTerminalsInBulk", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Logistics API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shippingAddress": { "description": "Shipping address for the bulk order.", "type": "object", "properties": { "name": { "description": "Full name of the receiver for the shipment.", "type": "string" }, "addressLine1": { "description": "The first line of the receiver's address.", "type": "string" }, "addressLine2": { "description": "The second line of the receiver's address.", "type": "string" }, "addressLine3": { "description": "The third line of the receiver's address.", "type": "string" }, "city": { "description": "City of the receiver.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code of the receiver, in uppercase.", "type": "string" }, "postalCode": { "description": "Postal code of the receiver.", "type": "string" }, "phoneNumber": { "description": "Contact number of the receiver in code and number format.", "type": "object", "properties": { "code": { "description": "International dialing code identifying the country or region.", "type": "string" }, "number": { "description": "Phone number.", "type": "string" } }, "required": [ "code", "number" ] }, "email": { "description": "Email address of the receiver.", "type": "string" }, "deliveryInstruction": { "description": "Delivery instructions for the carrier.", "type": "string" } }, "required": [ "name", "addressLine1", "city", "countryCode", "postalCode" ] }, "lineItems": { "description": "An array of products to be shipped in bulk.", "type": "array", "items": { "type": "object", "properties": { "productId": { "description": "The SurfboardProductId of the product or group of products.", "type": "string" }, "quantity": { "description": "Number of products or group of products to be shipped.", "type": "number" }, "billingPlanId": { "description": "Optional billing plan for the product or group of products chosen.", "type": "string" }, "replacementFor": { "description": "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.", "type": "string" } }, "required": [ "productId", "quantity" ] } } }, "required": [ "lineItems" ] }, "example": { "shippingAddress": { "name": "Jane Smith", "addressLine1": "456 Business Ave", "addressLine2": "Floor 2", "city": "Stockholm", "countryCode": "SE", "postalCode": "12345" }, "lineItems": [ { "productId": "81bddf38fa28380101", "quantity": 5, "billingPlanId": "BP_001", "replacementFor": "82674cfdf77f500001" } ] } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "orderId": { "description": "Order ID for the bulk order.", "type": "string" } }, "required": [ "orderId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "orderId": "83992e47b219100f28" }, "message": "Bulk logistic order created successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true }, "get": { "operationId": "fetchPartnerOrders", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Logistics API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Array of order objects.", "type": "array", "items": { "type": "object", "properties": { "orderId": { "description": "Unique identifier for the order.", "type": "string" }, "trackingUrl": { "description": "The tracking URL of the shipment.", "type": "string" }, "trackingCode": { "description": "The carrier's tracking code for the shipment.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant the order was placed for.", "type": "string" }, "deliveryPartner": { "description": "The partner or carrier responsible for delivering the shipment.", "type": "string" }, "status": { "description": "Current status of the order.", "type": "string" }, "packages": { "description": "Array of package details in the order.", "type": "array", "items": { "type": "object", "properties": { "productId": { "description": "The SurfboardProductId of the product.", "type": "string" }, "serialNumber": { "description": "Serial number of the device.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "orderId": "8190422d77e1400428", "trackingUrl": "", "trackingCode": "", "merchantId": "m_iWGri3XAyTmkbKYsYtV47", "status": "ORDER_CANCELLED", "deliveryPartner": "DHL", "packages": [ { "productId": "817361bb0a23400701", "serialNumber": "" } ] }, { "orderId": "819118d10a3d900f28", "trackingUrl": "", "trackingCode": "", "merchantId": "m_iWGri3XAyTmkbKYsYtV47", "status": "ORDER_CANCELLED", "deliveryPartner": "DHL", "packages": [ { "productId": "817361bb0a23400701", "serialNumber": "" } ] } ], "message": "Orders fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/logistics/returns": { "post": { "operationId": "createReturn", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Logistics API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantInfo": { "description": "Detailed merchant information for the return request.", "type": "object", "properties": { "name": { "description": "Name of the merchant.", "type": "string" }, "email": { "description": "Email address of the merchant.", "type": "string" }, "phoneNumber": { "description": "Contact number of the merchant in code and number format.", "type": "object", "properties": { "code": { "description": "International dialing code identifying the country or region.", "type": "string" }, "number": { "description": "Phone number.", "type": "string" } }, "required": [ "code", "number" ] }, "addressLine1": { "description": "First line of the merchant's address.", "type": "string" }, "addressLine2": { "description": "Second line of the merchant's address.", "type": "string" }, "addressLine3": { "description": "Third line of the merchant's address.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code in uppercase.", "type": "string" }, "postalNumber": { "description": "Postal code of the merchant's address.", "type": "string" }, "city": { "description": "City of the merchant's address.", "type": "string" } }, "required": [ "name", "email", "phoneNumber", "addressLine1", "countryCode", "postalNumber", "city" ] }, "returnOrderLines": { "description": "Array of return order line items.", "type": "array", "items": { "type": "object", "properties": { "serial": { "description": "Serial number of the terminal to be returned.", "type": "string" }, "merchantId": { "description": "Unique identifier of the merchant. Provide both merchantId and terminalId for a registered terminal, or omit both to return an unregistered terminal.", "type": "string" }, "terminalId": { "description": "Unique identifier of the terminal. Provide both terminalId and merchantId for a registered terminal, or omit both to return an unregistered terminal.", "type": "string" }, "reasonForReturn": { "description": "Reason for the return.\n\nValues:\n- `WARRANTY`: The warranty covers issues potentially related to factory defects.\n- `NOT_USING_SERVICE`: Not using service applies when the merchant voluntarily leaves or their partner ends the partnership.\n- `NON_WARRANTY_BROKEN`: Non-warranty broken applies when the terminal is damaged due to misuse or accident.\n- `TECHNICAL_ISSUES`: Technical issues apply when the terminal's software malfunctions.\n- `COMPATIBILITY_ISSUES`: Compatibility issues occur when the terminal doesn't pair with the merchant's POS system.", "type": "string", "enum": [ "WARRANTY", "NOT_USING_SERVICE", "NON_WARRANTY_BROKEN", "TECHNICAL_ISSUES", "COMPATIBILITY_ISSUES" ] }, "stopBilling": { "description": "Whether to stop billing for this terminal.", "type": "boolean" }, "comment": { "description": "Additional comments regarding the return.", "type": "string" } }, "required": [ "serial", "reasonForReturn" ] } }, "deliveryInstruction": { "description": "Delivery instructions for the carrier.", "type": "string" } }, "required": [ "merchantInfo", "returnOrderLines" ] }, "example": { "merchantInfo": { "name": "Demo Store", "email": "demo@example.com", "phoneNumber": { "code": "46", "number": "123456789" }, "addressLine1": "Demo Street 123", "addressLine2": "Building A", "addressLine3": null, "city": "Stockholm", "countryCode": "SE", "postalNumber": "12345" }, "returnOrderLines": [ { "serial": "TERM001234567", "terminalId": "816a0ff6bc0fb00404", "reasonForReturn": "NOT_USING_SERVICE", "stopBilling": true, "comment": "Device not working properly" } ], "deliveryInstruction": "Please call before delivery" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "returnId": { "description": "ID of the return request.", "type": "number" } }, "required": [ "returnId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "returnId": 80 }, "message": "Return request created successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true }, "get": { "operationId": "getReturns", "summary": "Get Returns", "description": "Retrieves return requests for a specific merchant using the API. Supports filtering by status and provides detailed return information.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Logistics API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "required": false, "description": "Filter returns by status.\n\nValues:\n- `APPROVED`: Returns that have been approved for processing.\n- `CREATED`: Returns that have been created but not yet processed.", "schema": { "description": "Filter returns by status.\n\nValues:\n- `APPROVED`: Returns that have been approved for processing.\n- `CREATED`: Returns that have been created but not yet processed.", "type": "string", "enum": [ "APPROVED", "CREATED" ] } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Array of return request objects.", "type": "array", "items": { "type": "object", "properties": { "returnId": { "description": "Unique identifier for the return request.", "type": "number" }, "partnerId": { "description": "Unique identifier of the partner.", "type": "string" }, "merchantName": { "description": "Name of the merchant.", "type": "string" }, "merchantEmail": { "description": "Email address of the merchant.", "type": "string" }, "merchantPhone": { "description": "Phone number of the merchant.", "type": "string" }, "merchantAddressLine1": { "description": "First line of the merchant's address.", "type": "string" }, "merchantAddressLine2": { "description": "Second line of the merchant's address.", "type": "string" }, "merchantAddressLine3": { "description": "Third line of the merchant's address.", "type": "string" }, "merchantCity": { "description": "City of the merchant's address.", "type": "string" }, "merchantPostalNumber": { "description": "Postal code of the merchant's address.", "type": "string" }, "merchantCountryCode": { "description": "Country code of the merchant's address.", "type": "string" }, "deliveryInstruction": { "description": "Delivery instructions for the return.", "type": "string" }, "status": { "description": "Current status of the return request.\n\nValues:\n- `APPROVED`: The return request has been approved for processing.\n- `CREATED`: The return request has been created but not yet processed.", "type": "string", "enum": [ "APPROVED", "CREATED" ] }, "returnOrderLines": { "description": "Array of return order line items.", "type": "array", "items": { "type": "object", "properties": { "returnOrderlineId": { "description": "Unique identifier for the return order line.", "type": "number" }, "returnId": { "description": "ID of the parent return request.", "type": "number" }, "serial": { "description": "Serial number of the terminal.", "type": "string" }, "terminalId": { "description": "Unique identifier of the terminal.", "type": "string" }, "merchantId": { "description": "Unique identifier of the merchant.", "type": "string" }, "deviceModel": { "description": "Model of the device being returned.", "type": "string" }, "reasonForReturn": { "description": "Reason for the return.", "type": "string" }, "stopBilling": { "description": "Whether billing has been stopped for this terminal.", "type": "boolean" }, "comment": { "description": "Additional comments regarding the return.", "type": "string" }, "isUnregistered": { "description": "Whether this line was created for an unregistered terminal, one with no associated terminal or merchant.", "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" }, "totalCount": { "description": "Total count of return requests matching the criteria.", "type": "number" } }, "required": [ "status", "data", "message", "totalCount" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "returnId": 80, "partnerId": "8113d3f8403b380409", "merchantName": "Demo Store", "merchantEmail": "demo@example.com", "merchantPhone": "+46123456789", "merchantAddressLine1": "Demo Street 123", "merchantAddressLine2": "Building A", "merchantAddressLine3": "", "merchantCity": "Stockholm", "merchantPostalNumber": "12345", "merchantCountryCode": "SE", "deliveryInstruction": "Please call before delivery", "status": "CREATED", "returnOrderLines": [ { "returnOrderlineId": 78, "returnId": 80, "serial": "TERM001234567", "terminalId": "816a0ff6bc0fb00404", "merchantId": "m_iWGri3XAyTmkbKYsYtV47", "deviceModel": "Surfpad", "reasonForReturn": "NOT_USING_SERVICE", "stopBilling": true, "comment": "Device not working properly", "isUnregistered": false } ] } ], "message": "Return requests gotten successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/logistics/orders": { "get": { "operationId": "fetchMerchantOrders", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Logistics API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Array of order objects for the merchant.", "type": "array", "items": { "type": "object", "properties": { "orderId": { "description": "Unique identifier for the order.", "type": "string" }, "trackingUrl": { "description": "The tracking URL of the shipment.", "type": "string" }, "trackingCode": { "description": "The carrier's tracking code for the shipment.", "type": "string" }, "status": { "description": "Current status of the order.", "type": "string" }, "deliveryPartner": { "description": "The partner or carrier responsible for delivering the shipment.", "type": "string" }, "packages": { "description": "Array of package details in the order.", "type": "array", "items": { "type": "object", "properties": { "productId": { "description": "The SurfboardProductId of the product.", "type": "string" }, "serialNumber": { "description": "Serial number of the device.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "orderId": "8190422d77e1400428", "trackingUrl": "", "trackingCode": "", "status": "ORDER_CANCELLED", "deliveryPartner": "DHL", "packages": [ { "productId": "817361bb0a23400701", "serialNumber": "" } ] }, { "orderId": "819118d10a3d900f28", "trackingUrl": "", "trackingCode": "", "status": "ORDER_CANCELLED", "deliveryPartner": "DHL", "packages": [ { "productId": "817361bb0a23400701", "serialNumber": "" } ] } ], "message": "Orders fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/merchants/{merchantId}/charges": { "post": { "operationId": "createMerchantCharge", "summary": "Create Merchant Charge", "description": "Creates a new charge for a merchant. Partners can specify the charge details.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchant Charge & Billing Plans" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "description": "A brief description of the charge.", "type": "string" }, "currency": { "description": "Three-digit currency code", "type": "string" }, "amount": { "description": "Charge amount in smallest currency units", "type": "number" }, "vat": { "description": "Optional VAT amount.", "type": "number" }, "billingDate": { "description": "Date on which the charge is effective, in yyyy-mm-dd format.", "type": "string" }, "recurring": { "description": "If set, defines a recurring charge schedule including frequency and optional end date.", "type": "object", "properties": { "frequency": { "description": "Specifies how frequently the charge will be billed. The possible values are:\n\nValues:\n- `daily`: Recurring charge occurs every day.\n- `twiceWeekly`: Recurring charge occurs twice a week.\n- `weekly`: Recurring charge occurs once per week.\n- `tenDays`: Recurring charge occurs once every 10 days.\n- `fortNightly`: Recurring charge occurs once every two weeks.\n- `monthly`: Recurring charge occurs once per month.\n- `everyTwoMonths`: Recurring charge occurs once every two months.\n- `trimester`: Recurring charge occurs every three months.\n- `quarterly`: Recurring charge occurs once every quarter (three months).\n- `twiceYearly`: Recurring charge occurs twice a year.\n- `annually`: Recurring charge occurs once a year.", "type": "string", "enum": [ "daily", "twiceWeekly", "weekly", "tenDays", "fortNightly", "monthly", "everyTwoMonths", "trimester", "quarterly", "twiceYearly", "annually" ] }, "billingEndDate": { "description": "Date in yyyy-mm-dd format specifying when to stop recurring charges.", "type": "string" } }, "required": [ "frequency" ] } }, "required": [ "description", "currency", "amount" ] }, "example": { "description": "Fee", "currency": "752", "amount": 5000000, "vat": 35, "billingDate": "2025-02-11", "recurring": { "billingEndDate": "2025-02-12", "frequency": "daily" } } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Indicates if the request was 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing information about the created charge.", "type": "object", "properties": { "chargeId": { "description": "Unique identifier for the newly created charge.", "type": "string" } }, "required": [ "chargeId" ], "additionalProperties": true }, "message": { "description": "A message describing the outcome of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "chargeId": "82eb21dbb4bcf80c46" }, "message": "Merchant charge created successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to create merchant charge for partner" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchAllMerchantCharges", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchant Charge & Billing Plans" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "An array of merchant charges.", "type": "array", "items": { "type": "object", "properties": { "chargeId": { "description": "Unique identifier for the charge.", "type": "string" }, "subChargeId": { "description": "Identifier specifically tied to the sub-charge, usually the same as 'id' for single charges.", "type": "string" }, "merchantId": { "description": "The merchant ID to whom this charge applies.", "type": "string" }, "isSubscriptionCharge": { "description": "Indicates whether this charge is part of a subscription (recurring).", "type": "boolean" }, "description": { "description": "A brief text describing the charge.", "type": "string" }, "amount": { "description": "Charge amount in smallest currency units.", "type": "number" }, "vat": { "description": "VAT amount applied to this charge.", "type": "number" }, "status": { "description": "Current status of the charge, for example 'PENDING'.", "type": "string" }, "billingDate": { "description": "Date the charge is billed, in ISO 8601 format.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message describing the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "chargeId": "82ed1af7b38e080146", "subChargeId": "82ed1af7b38e080146", "merchantId": "m_iWGri3XAyTmkbKYsYtV47", "isSubscriptionCharge": true, "description": "Fee", "amount": 650000, "vat": 15, "status": "PENDING", "billingDate": "2025-02-11T00:00:00.000Z" }, { "chargeId": "82eb21dbb4bcf80c46", "subChargeId": "82ec36fee443f80f46", "merchantId": "m_iWGri3XAyTmkbKYsYtV47", "isSubscriptionCharge": true, "description": "Fee", "amount": 5000000, "vat": 35, "status": "PENDING", "billingDate": "2025-02-09T00:00:00.000Z" }, { "chargeId": "82eb21dbb4bcf80c46", "subChargeId": "82eb21dbb4bcf80c46", "merchantId": "m_iWGri3XAyTmkbKYsYtV47", "isSubscriptionCharge": true, "description": "Fee", "amount": 5000000, "vat": 35, "status": "PENDING", "billingDate": "2025-02-08T00:00:00.000Z" } ], "message": "Merchant charges fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch merchant charges for partner." } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/merchants/{merchantId}/charges/{chargeId}": { "put": { "operationId": "updateMerchantCharge", "summary": "Update Merchant Charge", "description": "Updates an existing charge for a merchant. Partners can modify the amount, VAT, and optionally adjust the recurring settings.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchant Charge & Billing Plans" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "chargeId", "in": "path", "required": true, "description": "Identifier for the charge this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "description": "Updated amount in minor currency units.", "type": "number" }, "vat": { "description": "Optional updated VAT amount.", "type": "number" }, "recurring": { "description": "Updated recurring schedule. Billing end date and updateType can be specified here.", "type": "object", "properties": { "updateType": { "description": "Indicates the type of the update.The possible values are\n\nValues:\n- `onlyNext`: Applies the update to the next billing cycle only.\n- `lifeTime`: Applies the update for the remaining lifetime of the subscription.\n- `current`: Applies the update immediately to the current billing cycle.", "type": "string", "enum": [ "onlyNext", "lifeTime", "current" ] }, "billingEndDate": { "description": "Date in yyyy-mm-dd format specifying the new end date for the recurring charge.", "type": "string" } }, "required": [ "updateType" ] } }, "required": [ "amount" ] }, "example": { "amount": 650000, "vat": 15, "recurring": { "updateType": "onlyNext", "billingEndDate": "2025-10-23" } } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Indicates if the request was 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message describing the outcome of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Updated merchant charge for partner successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to update merchant charge for partner" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchMerchantChargeById", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchant Charge & Billing Plans" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "chargeId", "in": "path", "required": true, "description": "Identifier for the charge this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "data": { "description": "Response data containing details of the requested merchant charge", "type": "object", "properties": { "chargeId": { "description": "Unique identifier of the charge.", "type": "string" }, "isSubscriptionCharge": { "description": "Specifies if this charge is subscription-based (recurring).", "type": "boolean" }, "description": { "description": "A short description of the charge.", "type": "string" }, "amount": { "description": "Charge amount in smallest currency units.", "type": "number" }, "vat": { "description": "The VAT amount applied to this charge.", "type": "number" }, "frequency": { "description": "Specifies how frequently the charge will be billed. The possible values are:\n\nValues:\n- `daily`: Recurring charge occurs every day.\n- `twiceWeekly`: Recurring charge occurs twice a week.\n- `weekly`: Recurring charge occurs once per week.\n- `tenDays`: Recurring charge occurs once every 10 days.\n- `fortNightly`: Recurring charge occurs once every two weeks.\n- `monthly`: Recurring charge occurs once per month.\n- `everyTwoMonths`: Recurring charge occurs once every two months.\n- `trimester`: Recurring charge occurs every three months.\n- `quarterly`: Recurring charge occurs once every quarter (three months).\n- `twiceYearly`: Recurring charge occurs twice a year.\n- `annually`: Recurring charge occurs once a year.\n- `unscheduled`: Recurring charge does not follow a fixed schedule.", "type": "string", "enum": [ "daily", "twiceWeekly", "weekly", "tenDays", "fortNightly", "monthly", "everyTwoMonths", "trimester", "quarterly", "twiceYearly", "annually", "unscheduled" ] }, "billingDate": { "description": "Date the charge is billed, in ISO 8601 format.", "type": "string" }, "billingStartDate": { "description": "Start date of the recurring charge in ISO 8601 format.", "type": "string" }, "billingEndDate": { "description": "End date of the recurring charge in ISO 8601 format.", "type": "string" }, "subCharges": { "description": "Array of sub-charges associated with this main charge.", "type": "array", "items": { "type": "object", "properties": { "subChargeId": { "description": "Unique identifier for this sub-charge.", "type": "string" }, "description": { "description": "A short text describing the sub-charge.", "type": "string" }, "amount": { "description": "Charge amount in smallest currency units", "type": "number" }, "vat": { "description": "VAT amount for this sub-charge.", "type": "number" }, "status": { "description": "Current status of the sub-charge.", "type": "string" }, "billingDate": { "description": "Date when this sub-charge was billed, in ISO 8601 format.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "chargeId": "82eb21dbb4bcf80c46", "isSubscriptionCharge": true, "description": "Fee", "amount": 5000000, "vat": 35, "frequency": "daily", "billingStartDate": "2025-02-18T00:00:00.000Z", "billingEndDate": "2025-02-20T00:00:00.000Z", "subCharges": [ { "subChargeId": "82f1a47a1f97000446", "description": "Fee", "amount": 650000, "vat": 15, "status": "PENDING", "billingDate": "2025-02-18T00:00:00.000Z" } ] }, "message": "Merchant charge fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch details of the merchant charge for partner." } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/billing-plans": { "post": { "operationId": "createBillingPlans", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchant Charge & Billing Plans" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "description": "Array of billing plan objects to create.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique identifier for the billing plan.", "type": "string" }, "cardBrand": { "description": "Card brand this plan's rates apply to. Leave unset to apply the plan across all supported brands.\n\nValues:\n- `AMEX`: American Express cards.\n- `DISCOVER`: Discover cards.\n- `MASTERCARD`: Mastercard-branded cards.\n- `VISA`: Visa-branded cards.\n- `VISA_MC`: Visa and Mastercard combined, billed at the same rate.", "type": "string", "enum": [ "AMEX", "DISCOVER", "MASTERCARD", "VISA", "VISA_MC" ] }, "terminalType": { "description": "The kind of terminal this plan prices.\n\nValues:\n- `STANDARD`: A standalone physical card terminal.\n- `SOFTPOS`: A soft point-of-sale terminal running on a phone or tablet.\n- `ONLINE`: An online or e-commerce checkout.", "type": "string", "enum": [ "STANDARD", "SOFTPOS", "ONLINE" ] }, "paymentMethod": { "description": "The payment method this plan prices.\n\nValues:\n- `ACCTOACC`: Account-to-account bank transfer.\n- `B2BINV`: Business-to-business invoicing.\n- `CARD`: Card payments.\n- `DCC_INSTORE`: In-store dynamic currency conversion.\n- `EPASSI`: ePassi benefit payments.\n- `KLARNA`: Klarna pay-later payments.\n- `MOBILEPAY`: MobilePay wallet payments.\n- `SWISH`: Swish instant payments.\n- `VIPPS`: Vipps wallet payments.", "type": "string", "enum": [ "ACCTOACC", "B2BINV", "CARD", "DCC_INSTORE", "EPASSI", "KLARNA", "MOBILEPAY", "SWISH", "VIPPS" ] }, "planType": { "description": "How this plan prices transactions.\n\nValues:\n- `FIXED`: A single flat rate applies to every transaction.\n- `VARIABLE`: The rate varies by the card's interchange domain and card type.\n- `IC++`: Interchange-plus-plus pricing, passing through the scheme's interchange and scheme fees on top of the Surfboard margin.", "type": "string", "enum": [ "FIXED", "VARIABLE", "IC++" ] }, "description": { "description": "Description of the billing plan.", "type": "string" }, "domesticDebitNonCommercial": { "description": "Percentage rate for domestic debit non-commercial transactions.", "type": "number" }, "domesticCreditNonCommercial": { "description": "Percentage rate for domestic credit non-commercial transactions.", "type": "number" }, "domesticDebitCommercial": { "description": "Percentage rate for domestic debit commercial transactions.", "type": "number" }, "domesticCreditCommercial": { "description": "Percentage rate for domestic credit commercial transactions.", "type": "number" }, "eeaDebitNonCommercial": { "description": "Percentage rate for EEA debit non-commercial transactions.", "type": "number" }, "eeaCreditNonCommercial": { "description": "Percentage rate for EEA credit non-commercial transactions.", "type": "number" }, "eeaDebitCommercial": { "description": "Percentage rate for EEA debit commercial transactions.", "type": "number" }, "eeaCreditCommercial": { "description": "Percentage rate for EEA credit commercial transactions.", "type": "number" }, "internationalDebitNonCommercial": { "description": "Percentage rate for international debit non-commercial transactions.", "type": "number" }, "internationalCreditNonCommercial": { "description": "Percentage rate for international credit non-commercial transactions.", "type": "number" }, "internationalDebitCommercial": { "description": "Percentage rate for international debit commercial transactions.", "type": "number" }, "internationalCreditCommercial": { "description": "Percentage rate for international credit commercial transactions.", "type": "number" }, "minimumCeiling": { "description": "Minimum ceiling amount for transactions.", "type": "number" }, "fixedCost": { "description": "Fixed cost amount per transaction.", "type": "number" }, "fixedPercentage": { "description": "Fixed percentage rate applied to transactions.", "type": "number" }, "vatPercentage": { "description": "VAT percentage applied to the billing plan.", "type": "number" }, "cardTypeFees": { "description": "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.", "type": "object", "additionalProperties": true }, "binRangeFees": { "description": "Rate overrides that apply only to card BIN ranges, letting you price specific issuing ranges differently from the plan's default rates.", "type": "array", "items": {} } }, "required": [ "id", "terminalType", "paymentMethod", "planType", "description" ] } } }, "required": [ "plans" ] }, "example": { "plans": [ { "id": "SP_NOK7", "paymentMethod": "CARD", "cardBrand": "DISCOVER", "terminalType": "STANDARD", "planType": "FIXED", "description": "Testing 2024", "fixedPercentage": 13.4 } ] } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Indicates if the request was 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message describing the outcome of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Billing plans created successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to create billing plans" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] }, "get": { "operationId": "fetchBillingPlans", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchant Charge & Billing Plans" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Array of billing plan objects.", "type": "array", "items": { "type": "object", "properties": { "billingPlanId": { "description": "Unique identifier for the billing plan.", "type": "string" }, "cardBrand": { "description": "Card brand for which this plan applies.", "type": "string" }, "terminalType": { "description": "Type of terminal for which this plan applies.", "type": "string" }, "paymentMethod": { "description": "Payment method for which this plan applies.", "type": "string" }, "planType": { "description": "Type of billing plan (FIXED or VARIABLE).", "type": "string" }, "description": { "description": "Description of the billing plan.", "type": "string" }, "domesticDebitNonCommercial": { "description": "Percentage rate for domestic debit non-commercial transactions.", "type": "number" }, "domesticCreditNonCommercial": { "description": "Percentage rate for domestic credit non-commercial transactions.", "type": "number" }, "domesticDebitCommercial": { "description": "Percentage rate for domestic debit commercial transactions.", "type": "number" }, "domesticCreditCommercial": { "description": "Percentage rate for domestic credit commercial transactions.", "type": "number" }, "eeaDebitNonCommercial": { "description": "Percentage rate for EEA debit non-commercial transactions.", "type": "number" }, "eeaCreditNonCommercial": { "description": "Percentage rate for EEA credit non-commercial transactions.", "type": "number" }, "eeaDebitCommercial": { "description": "Percentage rate for EEA debit commercial transactions.", "type": "number" }, "eeaCreditCommercial": { "description": "Percentage rate for EEA credit commercial transactions.", "type": "number" }, "internationalDebitNonCommercial": { "description": "Percentage rate for international debit non-commercial transactions.", "type": "number" }, "internationalCreditNonCommercial": { "description": "Percentage rate for international credit non-commercial transactions.", "type": "number" }, "internationalDebitCommercial": { "description": "Percentage rate for international debit commercial transactions.", "type": "number" }, "internationalCreditCommercial": { "description": "Percentage rate for international credit commercial transactions.", "type": "number" }, "minimumCeiling": { "description": "Minimum ceiling amount for transactions.", "type": "number" }, "fixedCost": { "description": "Fixed cost amount per transaction.", "type": "number" }, "fixedPercentage": { "description": "Fixed percentage rate applied to transactions.", "type": "number" }, "vatPercentage": { "description": "VAT percentage applied to the billing plan.", "type": "number" }, "cardTypeFees": { "description": "Per-card-type rate overrides for the plan, keyed by card type. Empty when the plan has no per-card-type overrides.", "type": "object", "additionalProperties": true }, "binRangeFees": { "description": "Rate overrides that apply to specific card BIN ranges. Empty when the plan has no BIN-range overrides.", "type": "array", "items": {} } }, "additionalProperties": true } }, "message": { "description": "A message describing the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "billingPlanId": "ANCN_POS_PREMIUM_PLUS", "cardBrand": "VISA_MC", "terminalType": "STANDARD", "paymentMethod": "CARD", "planType": "VARIABLE", "description": "Billing Plan Description", "domesticDebitNonCommercial": 0.49, "domesticCreditNonCommercial": 0.59, "domesticDebitCommercial": 1.95, "domesticCreditCommercial": 1.95, "eeaDebitNonCommercial": 0.49, "eeaCreditNonCommercial": 0.59, "eeaDebitCommercial": 1.95, "eeaCreditCommercial": 1.95, "internationalDebitNonCommercial": 1.95, "internationalCreditNonCommercial": 1.95, "internationalDebitCommercial": 1.95, "internationalCreditCommercial": 1.95, "minimumCeiling": 0, "fixedCost": 0.12, "fixedPercentage": 0, "vatPercentage": 0 }, { "billingPlanId": "P_DKKVK_V149M000F000", "cardBrand": "VISA_MC", "terminalType": "STANDARD", "paymentMethod": "CARD", "planType": "FIXED", "description": "Billing Plan Description", "domesticDebitNonCommercial": 1.49, "domesticCreditNonCommercial": 1.49, "domesticDebitCommercial": 1.49, "domesticCreditCommercial": 1.49, "eeaDebitNonCommercial": 1.49, "eeaCreditNonCommercial": 1.49, "eeaDebitCommercial": 1.49, "eeaCreditCommercial": 1.49, "internationalDebitNonCommercial": 1.49, "internationalCreditNonCommercial": 1.49, "internationalDebitCommercial": 1.49, "internationalCreditCommercial": 1.49, "minimumCeiling": 0, "fixedCost": 0, "fixedPercentage": 0, "vatPercentage": 0 } ], "message": "Partner billing plans fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to fetch billing plans for partner" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/merchants/{merchantId}/plans": { "get": { "operationId": "fetchBillingPlansForMerchant", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchant Charge & Billing Plans" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Array of billing plan objects assigned to the merchant.", "type": "array", "items": { "type": "object", "properties": { "billingPlanId": { "description": "Unique identifier for the billing plan.", "type": "string" }, "cardBrand": { "description": "Card brand for which this plan applies.", "type": "string" }, "terminalType": { "description": "Type of terminal for which this plan applies.", "type": "string" }, "paymentMethod": { "description": "Payment method for which this plan applies.", "type": "string" }, "planType": { "description": "Type of billing plan (FIXED or VARIABLE).", "type": "string" }, "description": { "description": "Description of the billing plan.", "type": "string" }, "domesticDebitNonCommercial": { "description": "Percentage rate for domestic debit non-commercial transactions.", "type": "number" }, "domesticCreditNonCommercial": { "description": "Percentage rate for domestic credit non-commercial transactions.", "type": "number" }, "domesticDebitCommercial": { "description": "Percentage rate for domestic debit commercial transactions.", "type": "number" }, "domesticCreditCommercial": { "description": "Percentage rate for domestic credit commercial transactions.", "type": "number" }, "eeaDebitNonCommercial": { "description": "Percentage rate for EEA debit non-commercial transactions.", "type": "number" }, "eeaCreditNonCommercial": { "description": "Percentage rate for EEA credit non-commercial transactions.", "type": "number" }, "eeaDebitCommercial": { "description": "Percentage rate for EEA debit commercial transactions.", "type": "number" }, "eeaCreditCommercial": { "description": "Percentage rate for EEA credit commercial transactions.", "type": "number" }, "internationalDebitNonCommercial": { "description": "Percentage rate for international debit non-commercial transactions.", "type": "number" }, "internationalCreditNonCommercial": { "description": "Percentage rate for international credit non-commercial transactions.", "type": "number" }, "internationalDebitCommercial": { "description": "Percentage rate for international debit commercial transactions.", "type": "number" }, "internationalCreditCommercial": { "description": "Percentage rate for international credit commercial transactions.", "type": "number" }, "minimumCeiling": { "description": "Minimum ceiling amount for transactions.", "type": "number" }, "fixedCost": { "description": "Fixed cost amount per transaction.", "type": "number" }, "fixedPercentage": { "description": "Fixed percentage rate applied to transactions.", "type": "number" }, "vatPercentage": { "description": "VAT percentage applied to the billing plan.", "type": "number" }, "cardTypeFees": { "description": "Per-card-type rate overrides for the plan, keyed by card type. Empty when the plan has no per-card-type overrides.", "type": "object", "additionalProperties": true }, "binRangeFees": { "description": "Rate overrides that apply to specific card BIN ranges. Empty when the plan has no BIN-range overrides.", "type": "array", "items": {} } }, "additionalProperties": true } }, "message": { "description": "A message describing the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "billingPlanId": "SP_SE_Fix119", "cardBrand": "VISA_MC", "terminalType": "STANDARD", "paymentMethod": "CARD", "planType": "FIXED", "description": "Billing Plan Description", "domesticDebitNonCommercial": 1.19, "domesticCreditNonCommercial": 1.19, "domesticDebitCommercial": 1.19, "domesticCreditCommercial": 1.19, "eeaDebitNonCommercial": 1.19, "eeaCreditNonCommercial": 1.19, "eeaDebitCommercial": 1.19, "eeaCreditCommercial": 1.19, "internationalDebitNonCommercial": 1.19, "internationalCreditNonCommercial": 1.19, "internationalDebitCommercial": 1.19, "internationalCreditCommercial": 1.19, "minimumCeiling": 0.99, "fixedCost": 0, "fixedPercentage": 0, "vatPercentage": 0 } ], "message": "Billing plans for the merchant fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to fetch billing plans for merchant" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/billing-plans/{id}": { "get": { "operationId": "fetchBillingPlanById", "summary": "Fetch Billing Plan by ID", "description": "Fetches detailed information for a specific billing plan using its ID.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchant Charge & Billing Plans" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier for the id this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Array containing the filtered billing plan details.", "type": "array", "items": { "type": "object", "properties": { "billingPlanId": { "description": "Unique identifier for the billing plan.", "type": "string" }, "paymentMethod": { "description": "Payment method for which this plan applies.", "type": "string" }, "cardBrand": { "description": "Card brand for which this plan applies.", "type": "string" }, "terminalType": { "description": "Type of terminal for which this plan applies.", "type": "string" }, "planType": { "description": "Type of billing plan (FIXED, VARIABLE, or IC++).", "type": "string" }, "description": { "description": "Description of the billing plan.", "type": "string" }, "domesticDebitNonCommercial": { "description": "Percentage rate for domestic debit non-commercial transactions.", "type": "number" }, "domesticCreditNonCommercial": { "description": "Percentage rate for domestic credit non-commercial transactions.", "type": "number" }, "domesticDebitCommercial": { "description": "Percentage rate for domestic debit commercial transactions.", "type": "number" }, "domesticCreditCommercial": { "description": "Percentage rate for domestic credit commercial transactions.", "type": "number" }, "eeaDebitNonCommercial": { "description": "Percentage rate for EEA debit non-commercial transactions.", "type": "number" }, "eeaCreditNonCommercial": { "description": "Percentage rate for EEA credit non-commercial transactions.", "type": "number" }, "eeaDebitCommercial": { "description": "Percentage rate for EEA debit commercial transactions.", "type": "number" }, "eeaCreditCommercial": { "description": "Percentage rate for EEA credit commercial transactions.", "type": "number" }, "internationalDebitNonCommercial": { "description": "Percentage rate for international debit non-commercial transactions.", "type": "number" }, "internationalCreditNonCommercial": { "description": "Percentage rate for international credit non-commercial transactions.", "type": "number" }, "internationalDebitCommercial": { "description": "Percentage rate for international debit commercial transactions.", "type": "number" }, "internationalCreditCommercial": { "description": "Percentage rate for international credit commercial transactions.", "type": "number" }, "fixedPercentage": { "description": "Fixed percentage rate applied to transactions.", "type": "number" }, "fixedCost": { "description": "Fixed cost per transaction, in the smallest currency unit.", "type": "number" }, "minimumCeiling": { "description": "Minimum ceiling amount for transactions, in the smallest currency unit.", "type": "number" }, "vatPercentage": { "description": "VAT percentage applied to the billing plan.", "type": "number" }, "cardTypeFees": { "description": "Per-card-type rate overrides for the plan, keyed by card type. Empty when the plan has no per-card-type overrides.", "type": "object", "additionalProperties": true }, "binRangeFees": { "description": "Rate overrides that apply to specific card BIN ranges. Empty when the plan has no BIN-range overrides.", "type": "array", "items": {} } }, "additionalProperties": true } }, "message": { "description": "A message describing the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "billingPlanId": "PLAN_001", "paymentMethod": "CARD", "cardBrand": "VISA", "terminalType": "STANDARD", "planType": "FIXED", "description": "Standard billing plan", "domesticDebitNonCommercial": 1.49, "domesticCreditNonCommercial": 1.59 } ], "message": "Billing plan retrieved successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to fetch billing plans for partner" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true }, "delete": { "operationId": "removeBillingPlanById", "summary": "Remove Billing Plan by ID", "description": "Removes one or more billing plans by their IDs for a specific partner.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchant Charge & Billing Plans" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "Identifier for the id this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message describing the outcome of the removal operation.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Billing plans removed from the partner successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to remove billing plans" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/merchants": { "post": { "operationId": "createMerchant", "summary": "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. When you pre-enter the merchant's details, Surfboard resolves the company's registry data (legal name, address, directors and beneficial owners where available) from the national business registry and classifies the free-text businessDescription into a merchant category (MCC), which determines the documents the merchant must supply. The returned link is already populated: the merchant only adds their bank account, any category-specific documents, and the signing of signatories and beneficial owners. If any part of the prefill cannot be resolved the call still succeeds and returns a working link. You can also create the merchant's first store, display or pre-select products, and set pricing plans in the same call.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "description": "Merchant's country of registration as a two-letter ISO code in uppercase. One of 'SE', 'NO', 'DK', 'FI', 'IE'.", "type": "string" }, "localeSelected": { "description": "UI language for the web KYB link, e.g. 'sv', 'da', 'fi', 'en'. Defaults to the country's language.", "type": "string" }, "organisation": { "description": "The legal entity.", "type": "object", "properties": { "corporateId": { "description": "National company or organisation number. Format is validated per country.", "type": "string" }, "legalName": { "description": "Registered legal name. Resolved from the registry if omitted. Mandatory for a PF partner. Conditionally required: see the endpoint notes.", "type": "string" }, "mccCode": { "description": "A specific merchant category code, if you already know it. Otherwise it is derived from preEnteredInformation.businessDescription. Mandatory for a PF partner. Conditionally required: see the endpoint notes.", "type": "string" }, "address": { "description": "Registered address. Resolved from the registry if omitted. Mandatory for a PF partner. Conditionally required: see the endpoint notes.", "type": "object", "properties": { "careOf": { "description": "Name of the addressee that is accepting the correspondence for the intended recipient.", "type": "string" }, "addressLine1": { "description": "Address of the organisation.", "type": "string" }, "addressLine2": { "description": "Address of the organisation.", "type": "string" }, "addressLine3": { "description": "Address of the organisation.", "type": "string" }, "city": { "description": "City where the organisation is located.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code in uppercase, representing the country where the organization is located.", "type": "string" }, "postalCode": { "description": "Postal code of the organisation.", "type": "string" } }, "required": [ "addressLine1", "city", "countryCode", "postalCode" ] }, "phoneNumber": { "description": "Contact number of the organisation in code and number format, e.g. { \"code\": \"46\", \"number\": \"701234567\" }.", "type": "object", "properties": { "code": { "description": "International dialing code identifying the country or region.", "type": "string" }, "number": { "description": "Phone number.", "type": "string" } }, "required": [ "code", "number" ] }, "email": { "description": "Company contact email. Mandatory for a PF partner. Conditionally required: see the endpoint notes.", "type": "string" } }, "required": [ "corporateId" ] }, "multiMerchantId": { "description": "Attach this merchant to an existing multi-merchant group.", "type": "string" }, "controlFields": { "description": "Onboarding configuration: the store, acquirer settings, product options, flags, and the information you prefill on the merchant's behalf.", "type": "object", "properties": { "displayProducts": { "description": "Hardware/product IDs to show in the catalogue step.", "type": "array", "items": { "type": "object", "properties": { "productId": { "description": "Represents the product ID of a product selected for delivery to the merchant.", "type": "string" }, "pricingPlans": { "description": "A list of strings specifying the billing plan for a merchant. This allows you to set up a plan based on the monthly price for a terminal and the duration in months. The specific plan details are provided by Surfboard.", "type": "array", "items": {} } }, "required": [ "productId" ] } }, "acquirerConfig": { "description": "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. Conditionally required: see the endpoint notes.", "type": "object", "properties": { "currency": { "description": "Currency code for the acquirer configuration (e.g., 'SEK', 'EUR', 'USD').", "type": "string" }, "acquirer": { "description": "Name of the acquirer (e.g., 'nets', 'swedbank').", "type": "string" }, "acquirerMID": { "description": "Acquirer Merchant ID for transaction processing in structured format.", "type": "string" }, "acquirerIID": { "description": "Acquirer institution ID.", "type": "string" } } }, "showProductCatalogue": { "description": "Whether the merchant sees the hardware/product step during the web KYB. Requires the product catalogue to be enabled for your programme; defaults to your programme setting.", "type": "boolean" }, "directMerchantCreation": { "description": "Create the merchant directly rather than as an onboarding application. Only applicable if your programme has a direct acquirer agreement; leave unset otherwise.", "type": "boolean" }, "disableFields": { "description": "Lock sections of the web KYB against merchant edits.", "type": "object", "properties": { "onlineInfo": { "description": "When true, locks the website/e-commerce URLs and requires store.onlineInfo (with merchantWebshopURL, termsAndConditionsURL, privacyPolicyURL) in the same request.", "type": "boolean" } } }, "merchantConfig": { "description": "Configuration settings for the merchant.", "type": "object", "properties": { "settlementFrequency": { "description": "Payout cadence for the merchant. Further values on request.\n\nValues:\n- `daily`: Every business day\n- `twiceWeekly`: Twice a week\n- `weekly`: Once a week\n- `tenDays`: Every ten days\n- `fortNightly`: Every two weeks\n- `monthly`: Once a month\n- `everyTwoMonths`: Every two months\n- `trimester`: Every four months\n- `quarterly`: Every three months\n- `twiceYearly`: Twice a year", "type": "string", "enum": [ "daily", "twiceWeekly", "weekly", "tenDays", "fortNightly", "monthly", "everyTwoMonths", "trimester", "quarterly", "twiceYearly" ] }, "serviceProvider": { "description": "Service provider fee split for the merchant. Links an onboarded service provider and sets its standing share. See the Service Providers API.", "type": "array", "items": { "type": "object", "properties": { "serviceProviderId": { "description": "Unique identifier of the service provider.", "type": "string" }, "deductApplicableTransactionFee": { "description": "Whether to deduct applicable transaction fees.", "type": "boolean" }, "amount": { "description": "Fee structure for the service provider.", "type": "object", "properties": { "percentage": { "description": "Percentage-based fee.", "type": "string" }, "fixed": { "description": "Fixed fee amount.", "type": "number" }, "adjustmentTypes": { "description": "Adjustment types the share is taken from, e.g. [\"TIPS\"].", "type": "array", "items": {} } } } }, "required": [ "serviceProviderId" ] } } } }, "transactionPricingPlan": { "description": "Billing/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.", "type": "string" }, "paymentMethods": { "description": "Configuration for payment methods to be enabled for the merchant.", "type": "object", "properties": { "card": { "description": "Card payment method configuration. Can be a boolean to enable/disable or an object with specific settings.", "type": "object", "properties": { "billingPlan": { "description": "Billing plan for card payments.", "type": "string" }, "mId": { "description": "Merchant ID for card payments.", "type": "string" }, "scheme": { "description": "Array of supported card schemes.\n\nValues:\n- `visa`: Visa card scheme\n- `mastercard`: Mastercard scheme", "type": "array", "items": {} } }, "required": [ "scheme" ] }, "amex": { "description": "American Express payment method configuration. Can be a boolean to enable/disable or an object with specific settings.", "type": "object", "properties": { "mId": { "description": "American Express Merchant ID. Required when configuring AMEX payment method.", "type": "string" } }, "required": [ "mId" ] }, "swish": { "description": "Swedish mobile payment method configuration. Can be a boolean to enable/disable or an object with specific settings.", "type": "object", "properties": { "billingPlan": { "description": "Billing plan for Swish payments.", "type": "string" }, "swishNumber": { "description": "Optional Swish number for the payment method configuration.", "type": "string" } } }, "klarna": { "description": "Buy now, pay later payment method configuration. Can be a boolean to enable/disable or an object with specific settings.", "type": "object", "properties": { "billingPlan": { "description": "Billing plan for Klarna payments.", "type": "string" }, "mId": { "description": "Klarna Merchant ID for the payment method configuration.", "type": "string" }, "klarnaPricingPlan": { "description": "Klarna pricing plan configuration.", "type": "string" }, "username": { "description": "Klarna account username. Required when configuring KLARNA payment method.", "type": "string" }, "password": { "description": "Klarna account password. Required when configuring KLARNA payment method.", "type": "string" } }, "required": [ "username", "password" ] }, "b2binv": { "description": "B2B invoice payment method configuration. Can be a boolean to enable/disable or an object with specific settings.", "type": "object", "properties": { "billingPlan": { "description": "Billing plan for B2B invoice payments.", "type": "string" }, "clientId": { "description": "Client ID for B2B invoice payment method.", "type": "string" }, "clientSecretKey": { "description": "Client secret key for B2B invoice payment method.", "type": "string" } } }, "acc2acc": { "description": "Account to account transfer payment method configuration. Can be a boolean to enable/disable or an object with specific settings.", "type": "object", "properties": { "billingPlan": { "description": "Billing plan for account-to-account payments.", "type": "string" }, "mId": { "description": "Merchant ID for account to account transfers.", "type": "string" } } }, "vipps": { "description": "Norwegian mobile payment method. Set to true to enable Vipps payment method.", "type": "boolean" }, "mobilepay": { "description": "Danish mobile payment method. Set to true to enable MobilePay payment method.", "type": "boolean" } } }, "preSelectProducts": { "description": "Products pre-added to the merchant's basket. These are shipped as part of the onboarding process without further input from the merchant.", "type": "array", "items": { "type": "object", "properties": { "productId": { "description": "Represents the product ID of a product selected for delivery to the merchant.", "type": "string" }, "quantity": { "description": "Quantity of the product", "type": "string" }, "pricingPlanId": { "description": "Specifies the billing plan for a merchant. This allows you to set up a plan based on the monthly price for a terminal and the duration in months. The specific plan details are provided by Surfboard.", "type": "string" } }, "required": [ "productId" ] } }, "linkUsers": { "description": "Existing user IDs to link to the new merchant.", "type": "array", "items": {} }, "redirectUrl": { "description": "Where to send the merchant after they finish the web KYB.", "type": "string" }, "generateShortLink": { "description": "Also return a shortened onboarding link (shortLinkUrl). Default false.", "type": "boolean" }, "store": { "description": "Create the merchant's first store in the same call. Conditionally required: see the endpoint notes.", "type": "object", "properties": { "name": { "description": "Store / trading name.", "type": "string" }, "email": { "description": "Store contact email.", "type": "string" }, "phoneNumber": { "description": "Contact number of the store in code and number format.", "type": "object", "properties": { "code": { "description": "International dialing code identifying the country or region.", "type": "string" }, "number": { "description": "A string of numbers ranging from 0-9 with a length of 5-15 characters.", "type": "string" } }, "required": [ "code", "number" ] }, "address": { "description": "The address of the store.", "type": "object", "properties": { "careOf": { "description": "Name of the addressee that is accepting the correspondence for the intended recipient.", "type": "string" }, "addressLine1": { "description": "Address of the store.", "type": "string" }, "addressLine2": { "description": "Address of the store.", "type": "string" }, "addressLine3": { "description": "Address of the store.", "type": "string" }, "city": { "description": "City where the store is located.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code in uppercase, representing the country where the store is located.", "type": "string" }, "postalCode": { "description": "Postal code of the store.", "type": "string" } }, "required": [ "addressLine1", "city", "countryCode", "postalCode" ] }, "onlineInfo": { "description": "E-commerce details. Required to start accepting online payments.", "type": "object", "properties": { "merchantWebshopURL": { "description": "This is the web-shop URL of the merchant.", "type": "string" }, "paymentPageHostURL": { "description": "This is the URL of the payment page. This is required for integrating online payments using SDK mode.", "type": "string" }, "termsAndConditionsURL": { "description": "This is the URL of the T&C of the merchant’s web-shop, it has to contain the refund policy.", "type": "string" }, "privacyPolicyURL": { "description": "This is the URL of the privacy policy of the merchant.", "type": "string" }, "googlePayMerchantId": { "description": "This is the Google Pay merchant ID of the merchant.", "type": "string" } }, "required": [ "merchantWebshopURL", "termsAndConditionsURL", "privacyPolicyURL" ] }, "paymentChannels": { "description": "Where the merchant takes payments. At least one channel must be true.", "type": "object", "properties": { "physical": { "description": "The merchant takes payments in person.", "type": "boolean" }, "online": { "description": "The merchant takes payments online.", "type": "boolean" }, "physicalSharePercent": { "description": "Share of turnover taken in person (1-99). Only meaningful when both channels are used.", "type": "number" } }, "required": [ "physical", "online" ] } }, "required": [ "name", "address" ] }, "preEnteredInformation": { "description": "The data you prefill on the merchant's behalf: purpose, people and trading details. Everything here is optional; supply what you know. Supplying businessDescription is what triggers automatic category (MCC) classification.", "type": "object", "properties": { "businessDescription": { "description": "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.", "type": "string" }, "applicant": { "description": "The main contact. Give at least name and email. Receives a signing invitation only if also a signatory or beneficial owner.", "type": "object", "properties": { "email": { "description": "Applicant's email.", "type": "string" }, "name": { "description": "Applicant's full name. Recommended.", "type": "string" }, "isSignatory": { "description": "Is an authorised signatory.", "type": "boolean" }, "isUbo": { "description": "Is a beneficial owner (UBO).", "type": "boolean" }, "isChairman": { "description": "Is the chairperson.", "type": "boolean" }, "ownershipPercent": { "description": "Ownership percentage (0-100). Only relevant when isUbo is true.", "type": "number" }, "ownershipType": { "description": "Direct, or owned via another company. Only relevant when isUbo is true.\n\nValues:\n- `direct`: Owns the shares directly\n- `indirect`: Owns via another company", "type": "string", "enum": [ "direct", "indirect" ] }, "entityName": { "description": "The intermediary company through which ownership is held. Required if ownershipType is 'indirect'. Only relevant when isUbo is true. Conditionally required: see the endpoint notes.", "type": "string" } }, "required": [ "email" ] }, "signatories": { "description": "Additional authorised signatories. Each receives a signing invitation.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Signatory's full name.", "type": "string" }, "email": { "description": "Signatory's email.", "type": "string" } }, "required": [ "name", "email" ] } }, "ubos": { "description": "Additional beneficial owners (UBOs). Each receives a signing invitation.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Owner's full name.", "type": "string" }, "email": { "description": "Owner's email.", "type": "string" }, "ownershipPercent": { "description": "Ownership percentage (0-100).", "type": "number" }, "ownershipType": { "description": "Direct, or owned via another company.\n\nValues:\n- `direct`: Owns the shares directly\n- `indirect`: Owns via another company", "type": "string", "enum": [ "direct", "indirect" ] }, "entityName": { "description": "The intermediary company through which ownership is held. Required if ownershipType is 'indirect'. Conditionally required: see the endpoint notes.", "type": "string" } }, "required": [ "name", "email" ] } }, "chairpersons": { "description": "Chairpersons. No signing link unless they are also a signatory or UBO.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Chairperson's full name.", "type": "string" }, "email": { "description": "Chairperson's email.", "type": "string" } }, "required": [ "name", "email" ] } }, "openingInfo": { "description": "Opening pattern. isOpenAllYear and isSeasonalOpen must be opposite (exactly one true); if not open all year, monthsOpen is required; if isStoreOpenAtNight is true, reasonForOpeningAtNight is required.", "type": "object", "properties": { "isSeasonalOpen": { "description": "If they are a seasonal merchant, open only on select seasons.", "type": "boolean" }, "monthsOpen": { "description": "Months open (1-12). Required when not open all year. Conditionally required: see the endpoint notes.", "type": "array", "items": {} }, "isOpenAllYear": { "description": "If merchant will be accepting payments all year round.", "type": "boolean" }, "isStoreOpenAtNight": { "description": "Mention if merchant stores are open all night.", "type": "boolean" }, "reasonForOpeningAtNight": { "description": "Provide a reason as to why they are open all night. Mandatory when 'isStoreOpenAtNight' is set to true. Conditionally required: see the endpoint notes.", "type": "string" } }, "required": [ "isSeasonalOpen", "isOpenAllYear", "isStoreOpenAtNight" ] }, "giftcards": { "description": "Only if the merchant sells gift cards.", "type": "object", "properties": { "revenueSharePercent": { "description": "Percentage share of the merchant's yearly revenue that comes from gift-card sales (0-100).", "type": "number" }, "averageValidDays": { "description": "Average validity period of a gift card, in days.", "type": "number" } }, "required": [ "revenueSharePercent", "averageValidDays" ] }, "prePayments": { "description": "Only if the merchant takes prepayments.", "type": "object", "properties": { "averageDeliveryTimeInDays": { "description": "Average time between payment and delivery of goods/services, in days.", "type": "number" }, "salesPercentPerYear": { "description": "Percentage of yearly sales taken as prepayment (0-100).", "type": "number" } }, "required": [ "averageDeliveryTimeInDays", "salesPercentPerYear" ] }, "fundsInfo": { "description": "Expected turnover profile.", "type": "object", "properties": { "estimatedAmountPerYear": { "description": "Estimated annual card turnover.", "type": "number" }, "priceOfMostExpensiveItemSold": { "description": "Price of most expensive item.", "type": "number" }, "averageTransactionValuePerDay": { "description": "Estimated amount of sales per day.", "type": "number" }, "estimatedAmountPerTransaction": { "description": "Average amount per transaction.", "type": "number" }, "estimatedFrequencyOfTransactions": { "description": "Transaction frequency.\n\nValues:\n- `DAILY`: Multiple times per day\n- `WEEKLY`: A few times per week\n- `MONTHLY`: A few times per month\n- `YEARLY`: A few times per year", "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "YEARLY" ] }, "estimatedNoOfDailyTransactions": { "description": "Average number of sales per day. Mandatory when 'estimatedFrequencyOfTransactions' is set to 'DAILY' Conditionally required: see the endpoint notes.", "type": "number" } }, "required": [ "estimatedAmountPerYear", "priceOfMostExpensiveItemSold", "averageTransactionValuePerDay", "estimatedAmountPerTransaction", "estimatedFrequencyOfTransactions" ] } } } } } }, "required": [ "country", "organisation" ] }, "example": { "country": "DK", "localeSelected": "da", "organisation": { "corporateId": "12345678" }, "controlFields": { "generateShortLink": true, "store": { "name": "Havnens Café", "email": "hello@havnenscafe.dk", "phoneNumber": { "code": "45", "number": "31234567" }, "address": { "addressLine1": "Havnegade 12", "city": "København", "countryCode": "DK", "postalCode": "1058" }, "paymentChannels": { "physical": true, "online": true, "physicalSharePercent": 80 } }, "preEnteredInformation": { "businessDescription": "Selling coffee, pastries and light lunches at our harbourside café.", "applicant": { "email": "owner@havnenscafe.dk", "name": "Mette Jensen", "isSignatory": true, "isUbo": true, "ownershipPercent": 100, "ownershipType": "direct" }, "ubos": [ { "name": "Lars Holm", "email": "lars@example.dk", "ownershipPercent": 0, "ownershipType": "indirect", "entityName": "Holm Holding ApS" } ], "openingInfo": { "isOpenAllYear": true, "isSeasonalOpen": false, "monthsOpen": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ], "isStoreOpenAtNight": false, "reasonForOpeningAtNight": "" }, "giftcards": { "revenueSharePercent": 15, "averageValidDays": 365 }, "fundsInfo": { "averageTransactionValuePerDay": 4000, "estimatedAmountPerYear": 1200000, "priceOfMostExpensiveItemSold": 250, "estimatedAmountPerTransaction": 95, "estimatedFrequencyOfTransactions": "DAILY" } } } } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request 'SUCCESS' | 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "applicationId": { "description": "ID of the onboarding application. Use it to check status.", "type": "string" }, "webKybUrl": { "description": "The link to hand to the merchant to complete onboarding. Treat it as sensitive: it grants access to the application.", "type": "string" }, "merchantId": { "description": "ID of the merchant record.", "type": "string" }, "storeId": { "description": "ID of the created store, when store was supplied.", "type": "string" }, "shortLinkUrl": { "description": "Shortened link, present when generateShortLink was true.", "type": "string" }, "validUntil": { "description": "Link expiry timestamp (ISO 8601).", "type": "string" } }, "required": [ "applicationId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Merchant application created successfully.", "data": { "applicationId": "845adba035abb00310", "webKybUrl": "https://onboarding.surfboard.se/845adba035abb00310?pi=M703SPUzM0Rhz0f91l209KundIhf", "shortLinkUrl": "https://sb.fyi/abcd12", "validUntil": "2026-12-01T00:00:00.000Z", "merchantId": "83af75d53169b0070e", "storeId": "845adbc0a3f2b00711" } } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] }, "get": { "operationId": "fetchAllMerchants", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "data": { "description": "Response data", "type": "array", "items": { "type": "object", "properties": { "merchantId": { "description": "Merchant ID of the merchant.", "type": "string" }, "partnerId": { "description": "The Partner ID of the partner with whom the merchant is affiliated.", "type": "string" }, "merchantName": { "description": "Name of the merchant.", "type": "string" }, "merchantLanguage": { "description": "Preferred language selected by the merchant.", "type": "string" }, "merchantLogoUrl": { "description": "Merchant logo URL.", "type": "string" }, "email": { "description": "Email address of the merchant.", "type": "string" }, "companyId": { "description": "Company ID of the merchant.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code in uppercase, representing the primary location of the merchant.", "type": "string" }, "mccCode": { "description": "Merchant Category Code (MCC) of the merchant.", "type": "string" }, "createdAt": { "description": "Timestamp at which the merchant was created.", "type": "string" }, "totalNumberOfTransaction": { "description": "The total number of transactions performed.", "type": "string" }, "totalAmountOfTransaction": { "description": "The total amount of money involved in all transactions, in the smallest currency unit.", "type": "string" }, "lastTransactionAt": { "description": "The timestamp of the last transaction in ISO format.", "type": "string" }, "phoneNumber": { "description": "The contact phone number related to the merchant.", "type": "string" }, "totalSales": { "description": "Total value of sales transactions for the merchant, in the smallest currency unit.", "type": "string" }, "totalRefunds": { "description": "Total value of refunded transactions for the merchant, in the smallest currency unit.", "type": "string" }, "currencyCode": { "description": "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’.", "type": "string" }, "acquirerMID": { "description": "Denotes the Acquirer MID for onboarding merchants through payment institution partners (PF or Acquirer). Returned only when the merchant has a payment-facilitator account.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "merchantId": "8248db4c5c8dd0130e", "partnerId": "8113d3f8403b380409", "merchantName": "Raynor LLC", "merchantLanguage": "sv", "merchantLogoUrl": "https://storage.googleapis.com/logo-raynor.png", "email": "sathish@surfboard.se", "companyId": "5590890439", "countryCode": "SE", "mccCode": 8021, "createdAt": "2024-06-06 06:03:49.125", "totalNumberOfTransaction": "11", "totalAmountOfTransaction": "2200", "lastTransactionAt": "2024-08-22 07:58:35.310568", "phoneNumber": "4623423423", "totalSales": "2200", "totalRefunds": "0", "currencyCode": "752", "acquirerMID": "gkjb4ug3KAUP" }, { "merchantId": "81a25a0b304ed0070e", "partnerId": "8113d3f8403b380409", "merchantName": "Conroy, Hane", "merchantLanguage": "en", "merchantLogoUrl": "https://storage.googleapis.com/logo-conroy.png", "email": "conroy@gmail.com", "countryCode": "SE", "mccCode": 5812, "createdAt": "2022-11-04 13:41:46.81", "totalNumberOfTransaction": "1877", "totalAmountOfTransaction": "774628102", "lastTransactionAt": "2024-07-15 09:23:09.816546", "phoneNumber": "+468787870484", "totalSales": "774628102", "totalRefunds": "12000", "currencyCode": "752", "acquirerMID": "kpIy8YO3ycKyhKR" } ], "message": "Successfully fetched merchants details" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/merchants/{applicationId}/status": { "get": { "operationId": "checkApplicationStatus", "summary": "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 while the application is open, and read the merchant ID and store ID once the merchant is live. The same IDs are also delivered through the webhook.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "applicationId", "in": "path", "required": true, "description": "Identifier for the application this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "applicationId": { "description": "The Application ID of the respective merchant returned by the Create Merchant API.", "type": "string" }, "webKybUrl": { "description": "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.", "type": "string" }, "applicationStatus": { "description": "Describes the status of the application. The possible values are:\n\nValues:\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`: Both the merchant signatories and 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.", "type": "string", "enum": [ "APPLICATION_INITIATED", "APPLICATION_STARTED", "APPLICATION_SUBMITTED", "APPLICATION_PENDING_INFORMATION", "APPLICATION_SIGNED", "APPLICATION_REJECTED", "APPLICATION_COMPLETED", "APPLICATION_EXPIRED", "MERCHANT_CREATED" ] }, "merchantId": { "description": "Merchant ID of the created merchant is returned when application status is 'MERCHANT_CREATED'", "type": "string" }, "storeId": { "description": "Store ID of the store created under the merchant is returned when application status is 'MERCHANT_CREATED'", "type": "string" }, "billingPlans": { "description": "Array of billing plans associated with the merchant application.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique identifier of the billing plan.", "type": "string" }, "cardBrand": { "description": "Card brand the billing plan applies to.", "type": "string" }, "terminalType": { "description": "Terminal type the billing plan applies to.", "type": "string" }, "paymentMethod": { "description": "Payment method the billing plan applies to.", "type": "string" }, "planType": { "description": "Type of the billing plan.", "type": "string" }, "description": { "description": "Human-readable description of the billing plan.", "type": "string" } }, "additionalProperties": true } }, "onlineOnboardingStatus": { "description": "Status of the online onboarding process for the merchant. Can be null if not applicable.", "type": "string" }, "paymentMethods": { "description": "Array of payment methods configured for the merchant.", "type": "array", "items": { "type": "object", "properties": { "paymentMethod": { "description": "Name of the payment method.", "type": "string" }, "status": { "description": "Status of the payment method for the merchant.", "type": "string" } }, "additionalProperties": true } }, "domainVerification": { "description": "Domain verification details for the merchant's online store. Empty when domain verification is not applicable.", "type": "array", "items": { "type": "object", "properties": { "domainName": { "description": "Domain name being verified for the merchant's online store.", "type": "string" }, "domainStatus": { "description": "Verification status of the domain.", "type": "string" }, "domainVerificationKey": { "description": "Key the merchant uses to verify ownership of the domain.", "type": "string" }, "verifyDomainType": { "description": "Type of domain verification being performed.", "type": "string" }, "isDomainVerified": { "description": "Indicates whether the domain has been verified.", "type": "boolean" }, "verificationMethod": { "description": "Method used to verify the domain.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "applicationId": "81409507c1a5f00110", "webKybUrl": "http://partner.surfboardpayments.com/81409507c1a5f00110", "applicationStatus": "MERCHANT_CREATED", "merchantId": "81412e2e4102f80f0e", "storeId": "81412e3c3b1090060f", "onlineOnboardingStatus": "PENDING_VERIFICATION", "billingPlans": [ { "id": "81412e3c3b1090060f", "cardBrand": "VISA", "terminalType": "sb_terminal_c", "paymentMethod": "CARD", "planType": "TRANSACTION", "description": "Standard Transaction Plan" } ], "paymentMethods": [ { "paymentMethod": "CARD", "status": "ACTIVE" }, { "paymentMethod": "SWISH", "status": "ACTIVE" } ], "domainVerification": [ { "domainName": "shop.example.se", "domainStatus": "VERIFIED", "domainVerificationKey": "sb-verify-81412e3c3b", "verifyDomainType": "DNS", "isDomainVerified": true, "verificationMethod": "TXT_RECORD" } ] }, "message": "Application status fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/multi-merchant": { "post": { "operationId": "createMultiMerchantGroup", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "description": "Two-letter ISO country code, in uppercase e.g 'SE', 'DK', 'NO'.", "type": "string" }, "postalCode": { "description": "Postal code of the multi-merchant group's address.", "type": "string" }, "name": { "description": "Name of the Multi-merchant group.", "type": "string" }, "email": { "description": "Email address of the Multi-merchant group.", "type": "string" } }, "required": [ "country", "postalCode" ] }, "example": { "country": "SE", "postalCode": "123456" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request 'SUCCESS' | 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "applicationId": { "description": "This is the applicationId that you will use to track the status of the create multi-merchant group request.", "type": "string" }, "merchantId": { "description": "Multi-merchant ID.", "type": "string" }, "storeId": { "description": "Multi-merchant store ID.", "type": "string" } }, "required": [ "applicationId", "storeId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "applicationId": "81376ad8ebedf80310", "merchantId": "81660b596c7fd0000e", "storeId": "81660b59434440030f" }, "message": "Multi Merchant created successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/applications": { "get": { "operationId": "fetchAllMerchantApplications", "summary": "Fetch All Merchant Applications", "description": "Retrieves a list of all merchants applications with a specific partner.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "data": { "description": "Response data", "type": "array", "items": { "type": "object", "properties": { "applicationId": { "description": "The Application ID used to uniquely identify a merchant's application.", "type": "string" }, "applicationStatus": { "description": "Describes the status of the application. The possible values are:\n\nValues:\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_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`: Both the merchant signatories and 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- `MERCHANT_CREATED`: The merchant account has been created. At this stage, the Merchant ID and Store ID will be returned in the status call.", "type": "string", "enum": [ "APPLICATION_INITIATED", "APPLICATION_SUBMITTED", "APPLICATION_PENDING_INFORMATION", "APPLICATION_SIGNED", "APPLICATION_REJECTED", "APPLICATION_COMPLETED", "MERCHANT_CREATED" ] }, "corporateId": { "description": "Corporate ID of the respective merchant.", "type": "string" }, "country": { "description": "Two-letter ISO country code in uppercase, representing the primary location of the merchant.", "type": "string" }, "createdAt": { "description": "Date of application creation in ISO string format", "type": "string" }, "lastUpdatedAt": { "description": "Date of last updation recorded with the merchant application in ISO string format", "type": "string" }, "webKybUrl": { "description": "The Web KYB URL generated for the application.", "type": "string" }, "legalName": { "description": "Legal name of the organization associated with the application.", "type": "string" }, "endDate": { "description": "Date on which the application period ends, in ISO string format.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "applicationId": "816e0b8aabe6580310", "country": "SE", "corporateId": "1234567898", "applicationStatus": "MERCHANT_CREATED", "createdAt": "2023-07-10T07:17:41.489Z", "lastUpdatedAt": "2023-07-10T07:17:41.519Z", "webKybUrl": "https://surfkyb.com/816e0b8aabe6580310", "legalName": "Year Zero Press AB", "endDate": "2024-07-10T07:17:41.519Z" }, { "applicationId": "816e0983abe6580a10", "country": "DK", "applicationStatus": "APPLICATION_INITIATED", "createdAt": "2023-07-10T07:00:23.106Z", "lastUpdatedAt": "2023-07-10T07:00:23.106Z", "webKybUrl": "https://surfkyb.com/816e0983abe6580a10" } ], "message": "Applications of partner fetched successfully with partnerId: 8113d3f8403b380409." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/merchants/{merchantId}": { "get": { "operationId": "fetchMerchantDetails", "summary": "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\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "merchantId": { "description": "Merchant ID of the merchant.", "type": "string" }, "merchantType": { "description": "Classification of the merchant account within Surfboard.\n\nValues:\n- `STANDARD`: A regular merchant account.\n- `DYNAMIC_MERCHANT`: A multi-merchant (dynamic) account that shares terminals across several merchants.\n- `MARKETPLACE_MERCHANT`: A merchant operating within a marketplace setup.\n- `PF_MERCHANT`: A merchant onboarded through a payment facilitator.\n- `PF_TEST_MERCHANT`: A payment facilitator merchant used for testing.\n- `PARTNER_MERCHANT`: A merchant onboarded directly by a partner.\n- `TEST_MERCHANT`: A merchant used for testing and integration.\n- `DEACTIVATED_MERCHANT`: A merchant account that has been deactivated.\n- `ISV_MERCHANT`: A merchant onboarded through an ISV partner.\n- `BLOCKED_MERCHANT`: A merchant account that has been blocked.", "type": "string", "enum": [ "STANDARD", "DYNAMIC_MERCHANT", "MARKETPLACE_MERCHANT", "PF_MERCHANT", "PF_TEST_MERCHANT", "PARTNER_MERCHANT", "TEST_MERCHANT", "DEACTIVATED_MERCHANT", "ISV_MERCHANT", "BLOCKED_MERCHANT" ] }, "partnerId": { "description": "The Partner ID of the partner with whom the merchant is affiliated.", "type": "string" }, "currencyCode": { "description": "Three-digit ISO currency code, representing the supported currency for the merchant. Can be any one of the following: ‘208’ | ‘978’ | ‘752’.", "type": "number" }, "merchantName": { "description": "Name of the merchant.", "type": "string" }, "merchantLanguage": { "description": "Preferred language selected by the merchant.", "type": "string" }, "merchantLogoUrl": { "description": "Merchant logo URL.", "type": "string" }, "email": { "description": "Email address of the merchant.", "type": "string" }, "companyId": { "description": "Company ID of the merchant.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code in uppercase, representing the primary location of the merchant.", "type": "string" }, "mccCode": { "description": "Merchant Category Code (MCC) of the merchant.", "type": "string" }, "address": { "description": "Physical address of the merchant.", "type": "object", "properties": { "careOf": { "description": "Name of the addressee that is accepting the correspondence for the intended recipient.", "type": "string" }, "addressLine1": { "description": "Address of the merchant.", "type": "string" }, "addressLine2": { "description": "Address of the merchant.", "type": "string" }, "addressLine3": { "description": "Address of the merchant.", "type": "string" }, "city": { "description": "City where the merchant is located.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code in uppercase, representing the location of the merchant.", "type": "string" }, "postalCode": { "description": "Postal code of the merchant.", "type": "string" } }, "required": [ "addressLine1", "city", "countryCode", "postalCode" ], "additionalProperties": true }, "createdAt": { "description": "Timestamp at which the merchant was created.", "type": "string" }, "totalNumberOfTransaction": { "description": "Total number of transactions performed by the merchant.", "type": "string" }, "totalAmountOfTransaction": { "description": "Denotes the total monetary value of all transactions performed by the merchant.", "type": "string" }, "lastTransactionAt": { "description": "Timestamp of the last transaction in ISO 8601 format represented as 'YYYY-MM-DDTHH:mm:ss.sssZ'.", "type": "string" }, "phoneNumber": { "description": "Phone number of the merchant.", "type": "string" }, "acquirerMID": { "description": "Denotes the Acquirer MID for onboarding merchants through payment institution partners(PF or Acquirer).", "type": "string" }, "totalSales": { "description": "Total value of sales transactions for the merchant, in the smallest currency unit.", "type": "string" }, "totalRefunds": { "description": "Total value of refunded transactions for the merchant, in the smallest currency unit.", "type": "string" }, "analytics": { "description": "Aggregated sales and refund counts for the current and previous month.", "type": "object", "properties": { "countOfSales": { "description": "Total number of sales transactions recorded for the merchant.", "type": "number" }, "countOfRefunds": { "description": "Total number of refund transactions recorded for the merchant.", "type": "number" }, "currentMonthSale": { "description": "Value of sales in the current month, in the smallest currency unit.", "type": "number" }, "previousMonthSale": { "description": "Value of sales in the previous month, in the smallest currency unit.", "type": "number" }, "currentMonthCountOfSale": { "description": "Number of sales in the current month.", "type": "number" }, "previousMonthCountOfSale": { "description": "Number of sales in the previous month.", "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "merchantId": "81fa6b2d8d5dc8040e", "partnerId": "8113d3f8403b380409", "merchantName": "Conroy Hane and Parker", "merchantLanguage": "se", "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", "email": "ashinisb@surfboard.se", "companyId": "5590520507", "countryCode": "SE", "mccCode": 1520, "phoneNumber": "917676576569", "merchantType": "STANDARD", "currencyCode": "752", "acquirerMID": "gfprLY1dyAQO", "address": { "careOf": "chennai", "addressLine1": "Stockholm", "addressLine2": "Diya ssssssTowers", "addressLine3": "process", "city": "Sweden", "countryCode": "SE", "postalCode": "22331" } }, "message": "Successfully fetched merchant details " } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "put": { "operationId": "updateMerchantDetails", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantName": { "description": "Name of the merchant.", "type": "string" }, "merchantLanguage": { "description": "Preferred language for the merchant, as a two-letter language code, for example 'sv' or 'en'.", "type": "string" }, "email": { "description": "Email address of the merchant.", "type": "string" }, "merchantLogoUrl": { "description": "Merchant logo URL.", "type": "string" }, "phoneNumber": { "description": "Contact number of the merchant in code and number format", "type": "object", "properties": { "code": { "description": "International dialing code identifying the country or region.", "type": "number" }, "number": { "description": "A string of numbers ranging from 0-9 with a length of 5-15 characters.", "type": "string" } } } } }, "example": { "merchantName": "Conroy Hane and Parker", "merchantLanguage": "sv", "email": "test@gmail.com", "phoneNumber": { "code": 46, "number": "771890089" }, "merchantLogoUrl": "https://storage.googleapis.com/merchant-logo.png" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request 'SUCCESS' | 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Successfully updated the merchant details." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/partners/{partnerId}/multi-merchants": { "get": { "operationId": "fetchAllMultiMerchantGroups", "summary": "Fetch All Multi-Merchant Groups", "description": "Fetch all existing multi-merchant groups under a partner.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "data": { "description": "Response data", "type": "array", "items": { "type": "object", "properties": { "multiMerchantId": { "description": "Multimerchant ID of the multi-merchant group.", "type": "string" }, "multiMerchantName": { "description": "Name of the multi-merchant group.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code in uppercase, representing the primary location of the multi-merchant group.", "type": "string" }, "postalCode": { "description": "Postal code of the multi-merchant.", "type": "string" }, "merchants": { "description": "List of merchants present under a multi-merchant group.", "type": "array", "items": { "type": "object", "properties": { "merchantId": { "description": "Merchant ID of the merchant.", "type": "string" }, "merchantName": { "description": "Name of the merchant.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code in uppercase, representing the primary location of the merchant.", "type": "string" } }, "additionalProperties": true } } }, "required": [ "postalCode", "merchants" ], "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "multiMerchantId": "817544218dd838050e", "multiMerchantName": "Multi Merchant one", "countryCode": "SE", "postalCode": "12345", "merchants": [ { "merchantId": "817544960dd838040e", "merchantName": "Test Merchant one", "countryCode": "SE" }, { "merchantId": "8175449a8dd8380d0e", "merchantName": "Test Merchant two", "countryCode": "SE" } ] }, { "multiMerchantId": "81701e32ff5690020e", "multiMerchantName": "Multi Merchant two", "countryCode": "SE", "postalCode": "12346" } ], "message": "Multi merchant groups fetched successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/merchants/{merchantId}/contracts": { "get": { "operationId": "fetchAllMerchantContracts", "summary": "Fetch All Merchant Contracts", "description": "Retrieves the list of all contracts under the specific merchant.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "data": { "description": "Response data", "type": "array", "items": { "type": "object", "properties": { "contractId": { "description": "The contract ID used to identify a contract.", "type": "string" }, "type": { "description": "Denotes type of the merchant contract.\n\nValues:\n- `MERCHANT_AGREEMENT`: A contract that establishes relationship and services agreed between two parties.", "type": "string", "enum": [ "MERCHANT_AGREEMENT" ] }, "status": { "description": "Denotes the status of the merchant contract. It can be either 'ACTIVE' or 'INACTIVE'", "type": "string" }, "contractLink": { "description": "Link for the merchant contract.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "contractId": "81d9b757ea31c0013d", "type": "MERCHANT_AGREEMENT", "status": "ACTIVE", "contractLink": "https://storage.googleapis.com/test" } ], "message": "Fetched merchant agreement contracts successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/analytics": { "get": { "operationId": "fetchTransactionAnalytics", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "query", "required": false, "description": "Provide store ID to filter analytics for a specific store.", "schema": { "description": "Provide store ID to filter analytics for a specific store.", "type": "string" } }, { "name": "terminalId", "in": "query", "required": false, "description": "Provide terminal ID to filter analytics for a specific terminal.", "schema": { "description": "Provide terminal ID to filter analytics for a specific terminal.", "type": "string" } }, { "name": "startDate", "in": "query", "required": false, "description": "Start of the date range in yyyy-mm-dd format.", "schema": { "description": "Start of the date range in yyyy-mm-dd format.", "type": "string" } }, { "name": "endDate", "in": "query", "required": false, "description": "End of the date range in yyyy-mm-dd format.", "schema": { "description": "End of the date range in yyyy-mm-dd format.", "type": "string" } }, { "name": "orderType", "in": "query", "required": false, "description": "Type of order to filter by. Possible values are 'purchase' and 'return'.", "schema": { "description": "Type of order to filter by. Possible values are 'purchase' and 'return'.", "type": "string" } }, { "name": "terminalType", "in": "query", "required": false, "description": "Type of terminal to filter results.\n\nValues:\n- `surfpad`: Hardware terminal with a physical keypad.\n- `surftouch`: Android terminal with custom payment apps, digital receipts etc.\n- `surfprint`: Android terminal with a built-in printer.\n- `checkoutPro`: Complete checkout solution with a customer facing screen.\n- `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.\n- `softpos`: SoftPOS solution on COTS devices.\n- `PaymentPage`: In this mode, the payment page and all associated configuration is managed by Surfboard.\n- `SelfHostedPage`: With SelfHostedPage, Surfboard renders the fields in your page.\n- `MerchantInitiated`: Set this type if you want to accept Merchant Initiated Transactions (MIT).", "schema": { "description": "Type of terminal to filter results.\n\nValues:\n- `surfpad`: Hardware terminal with a physical keypad.\n- `surftouch`: Android terminal with custom payment apps, digital receipts etc.\n- `surfprint`: Android terminal with a built-in printer.\n- `checkoutPro`: Complete checkout solution with a customer facing screen.\n- `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.\n- `softpos`: SoftPOS solution on COTS devices.\n- `PaymentPage`: In this mode, the payment page and all associated configuration is managed by Surfboard.\n- `SelfHostedPage`: With SelfHostedPage, Surfboard renders the fields in your page.\n- `MerchantInitiated`: Set this type if you want to accept Merchant Initiated Transactions (MIT).", "type": "string", "enum": [ "surfpad", "surftouch", "surfprint", "checkoutPro", "checkoutX", "softpos", "PaymentPage", "SelfHostedPage", "MerchantInitiated" ] } }, { "name": "paymentMethod", "in": "query", "required": false, "description": "Payment method to filter analytics.", "schema": { "description": "Payment method to filter analytics.", "type": "string" } }, { "name": "posEntryMode", "in": "query", "required": false, "description": "POS entry mode to filter by.", "schema": { "description": "POS entry mode to filter by.", "type": "string" } }, { "name": "cardBrand", "in": "query", "required": false, "description": "Card brand to filter by.", "schema": { "description": "Card brand to filter by.", "type": "string" } }, { "name": "currency", "in": "query", "required": false, "description": "Three digit numeric or ISO code representing currency.", "schema": { "description": "Three digit numeric or ISO code representing currency.", "type": "string" } }, { "name": "groupBy", "in": "query", "required": false, "description": "Use this object to group analytics by store, terminal, etc. For example, groupBy[storeId]=true.", "schema": { "description": "Use this object to group analytics by store, terminal, etc. For example, groupBy[storeId]=true.", "type": "object", "properties": { "storeId": { "description": "Set to true to group results by store.", "type": "boolean" }, "terminalId": { "description": "Set to true to group results by terminalId.", "type": "boolean" }, "orderType": { "description": "Set to true to group results by orderType.", "type": "boolean" }, "terminalType": { "description": "Set to true to group results by terminalType.", "type": "boolean" }, "paymentMethod": { "description": "Set to true to group results by paymentMethod.", "type": "boolean" }, "cardBrand": { "description": "Set to true to group results by cardBrand.", "type": "boolean" }, "posEntryMode": { "description": "Set to true to group results by posEntryMode.", "type": "boolean" }, "timeSegments": { "description": "Segments the analytics by time. Possible values are 'DAILY', 'WEEKLY', 'MONTHLY', 'QUARTERLY', 'YEARLY'.for example groupBy[timeSegments]=DAILY.", "type": "string" } } } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "An array of analytics objects, each containing aggregated transaction information.", "type": "array", "items": { "type": "object", "properties": { "currency": { "description": "The currency code for the transactions, typically a three-digit numeric code.", "type": "string" }, "storeId": { "description": "The store ID the transactions belong to. Present when results are grouped by this dimension.", "type": "string" }, "terminalId": { "description": "The terminal ID from which the transactions were made.", "type": "string" }, "terminalType": { "description": "Specifies the type of terminal.", "type": "string" }, "orderType": { "description": "The type of order.", "type": "string" }, "paymentMethod": { "description": "The payment method used.", "type": "string" }, "cardBrand": { "description": "The brand of the card, if paymentMethod is 'CARD'. This may be empty if no card brand applies.", "type": "string" }, "posEntryMode": { "description": "The POS entry mode used for the transactions. Present when results are grouped by this dimension.", "type": "string" }, "timeSegments": { "description": "The date/time segment in which these transactions occurred.", "type": "string" }, "orderTransactionCount": { "description": "Number of transactions that match this grouping or filter.", "type": "string" }, "totalTransactionAmount": { "description": "Aggregate sum of transaction amounts (in minor currency units) for this group.", "type": "number" } }, "additionalProperties": true } }, "message": { "description": "A message describing the status or outcome of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "currency": "752", "storeId": "82dd3f7c6a2ab00e03", "terminalId": "82dd3f9aad1ec80f04", "terminalType": "sb_terminal_c", "orderType": "PURCHASE", "paymentMethod": "CARD", "cardBrand": "VISA", "posEntryMode": "CONTACTLESS", "timeSegments": "2025-01-21 00:00:00", "orderTransactionCount": "1", "totalTransactionAmount": 150 }, { "currency": "752", "storeId": "82dd3f7c6a2ab00e03", "terminalId": "82dd3f9aad1ec80f04", "terminalType": "sb_terminal_c", "orderType": "PURCHASE", "paymentMethod": "CARD", "cardBrand": "MASTERCARD", "posEntryMode": "CONTACTLESS", "timeSegments": "2025-01-21 00:00:00", "orderTransactionCount": "3", "totalTransactionAmount": 450 } ], "message": "Transaction Analytics Data queried successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}": { "get": { "operationId": "fetchMerchant", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The merchant profile and transaction summary.", "type": "object", "properties": { "merchantId": { "description": "Unique identifier of the merchant.", "type": "string" }, "merchantType": { "description": "Classification of the merchant account within Surfboard.\n\nValues:\n- `STANDARD`: A regular merchant account.\n- `DYNAMIC_MERCHANT`: A multi-merchant (dynamic) account that shares terminals across several merchants.\n- `MARKETPLACE_MERCHANT`: A merchant operating within a marketplace setup.\n- `PF_MERCHANT`: A merchant onboarded through a payment facilitator.\n- `PF_TEST_MERCHANT`: A payment facilitator merchant used for testing.\n- `PARTNER_MERCHANT`: A merchant onboarded directly by a partner.\n- `TEST_MERCHANT`: A merchant used for testing and integration.\n- `DEACTIVATED_MERCHANT`: A merchant account that has been deactivated.\n- `ISV_MERCHANT`: A merchant onboarded through an ISV partner.\n- `BLOCKED_MERCHANT`: A merchant account that has been blocked.", "type": "string", "enum": [ "STANDARD", "DYNAMIC_MERCHANT", "MARKETPLACE_MERCHANT", "PF_MERCHANT", "PF_TEST_MERCHANT", "PARTNER_MERCHANT", "TEST_MERCHANT", "DEACTIVATED_MERCHANT", "ISV_MERCHANT", "BLOCKED_MERCHANT" ] }, "partnerId": { "description": "Identifier of the partner the merchant is affiliated with.", "type": "string" }, "merchantName": { "description": "Name of the merchant.", "type": "string" }, "merchantLanguage": { "description": "Preferred language selected by the merchant.", "type": "string" }, "merchantLogoUrl": { "description": "URL of the merchant logo.", "type": "string" }, "email": { "description": "Email address of the merchant.", "type": "string" }, "companyId": { "description": "Company (corporate) identifier of the merchant.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code, in uppercase, of the merchant.", "type": "string" }, "mccCode": { "description": "Merchant Category Code (MCC) of the merchant.", "type": "string" }, "createdAt": { "description": "Timestamp at which the merchant was created.", "type": "string" }, "totalNumberOfTransaction": { "description": "Total number of transactions performed by the merchant.", "type": "string" }, "totalAmountOfTransaction": { "description": "Total monetary value of all transactions performed by the merchant, in the smallest currency unit.", "type": "string" }, "lastTransactionAt": { "description": "Timestamp of the merchant's most recent transaction, in ISO 8601 format.", "type": "string" }, "phoneNumber": { "description": "Contact phone number of the merchant.", "type": "string" }, "totalSales": { "description": "Total value of sales transactions for the merchant, in the smallest currency unit.", "type": "string" }, "totalRefunds": { "description": "Total value of refunded transactions for the merchant, in the smallest currency unit.", "type": "string" }, "currencyCode": { "description": "Three-digit ISO currency code of the merchant's settlement currency, e.g. '752' for SEK.", "type": "string" }, "acquirerMID": { "description": "Acquirer Merchant ID assigned when the merchant is onboarded through a payment facilitator or acquirer.", "type": "string" }, "address": { "description": "Physical address of the merchant.", "type": "object", "properties": { "careOf": { "description": "Name of the addressee accepting correspondence on behalf of the merchant.", "type": "string" }, "addressLine1": { "description": "First line of the merchant address.", "type": "string" }, "addressLine2": { "description": "Second line of the merchant address.", "type": "string" }, "addressLine3": { "description": "Third line of the merchant address.", "type": "string" }, "city": { "description": "City where the merchant is located.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code, in uppercase, of the merchant address.", "type": "string" }, "postalCode": { "description": "Postal code of the merchant address.", "type": "string" } }, "additionalProperties": true }, "analytics": { "description": "Aggregated sales and refund counts for the current and previous month.", "type": "object", "properties": { "countOfSales": { "description": "Total number of sales transactions recorded for the merchant.", "type": "number" }, "countOfRefunds": { "description": "Total number of refund transactions recorded for the merchant.", "type": "number" }, "currentMonthSale": { "description": "Value of sales in the current month, in the smallest currency unit.", "type": "number" }, "previousMonthSale": { "description": "Value of sales in the previous month, in the smallest currency unit.", "type": "number" }, "currentMonthCountOfSale": { "description": "Number of sales in the current month.", "type": "number" }, "previousMonthCountOfSale": { "description": "Number of sales in the previous month.", "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "merchantId": "81fa6b2d8d5dc8040e", "merchantType": "STANDARD", "partnerId": "8113d3f8403b380409", "merchantName": "Conroy Hane and Parker", "merchantLanguage": "sv", "merchantLogoUrl": "https://storage.googleapis.com/logo.png", "email": "contact@surfboard.se", "companyId": "5590520507", "countryCode": "SE", "mccCode": "5812", "createdAt": "2024-06-06T06:03:49.125Z", "totalNumberOfTransaction": "1877", "totalAmountOfTransaction": "774628102", "lastTransactionAt": "2024-07-15T09:23:09.816Z", "phoneNumber": "46812345678", "totalSales": "774628102", "totalRefunds": "12000", "currencyCode": "752", "acquirerMID": "gfprLY1dyAQO", "address": { "careOf": "John Doe", "addressLine1": "Main Street 123", "city": "Stockholm", "countryCode": "SE", "postalCode": "12345" }, "analytics": { "countOfSales": 1850, "countOfRefunds": 27, "currentMonthSale": 45900, "previousMonthSale": 61200, "currentMonthCountOfSale": 120, "previousMonthCountOfSale": 158 } }, "message": "Successfully fetched merchant details" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch merchant details" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/users": { "get": { "operationId": "fetchMerchantUsers", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The user accounts associated with the merchant.", "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "Unique identifier of the user account.", "type": "string" }, "email": { "description": "Email address of the user.", "type": "string" }, "firstName": { "description": "First name of the user.", "type": "string" }, "lastName": { "description": "Last name of the user.", "type": "string" }, "role": { "description": "Role assigned to the user within the merchant.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "userId": "81412e2e4102f80f0e", "email": "owner@surfboard.se", "firstName": "Jane", "lastName": "Doe", "role": "ADMIN" } ], "message": "Fetched users for merchant successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch users for merchant" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/renewal-application": { "get": { "operationId": "fetchRenewalApplication", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The latest active renewal application, or null when none exists.", "type": "object", "properties": { "applicationId": { "description": "Identifier of the renewal application.", "type": "string" }, "applicationStatus": { "description": "Current status of the renewal application.", "type": "string" }, "endDate": { "description": "Date on which the renewal application period ends.", "type": "string" }, "createdAt": { "description": "Timestamp at which the renewal application was created.", "type": "string" }, "webKybUrl": { "description": "KYB continuation link for the renewal, when available. Can be null.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "applicationId": "81409507c1a5f00110", "applicationStatus": "APPLICATION_INITIATED", "endDate": "2026-12-31T00:00:00.000Z", "createdAt": "2026-06-01T09:24:11.000Z", "webKybUrl": "https://surfkyb.com/81409507c1a5f00110" }, "message": "Fetched latest active renewal application successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch latest active renewal application" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/configuration": { "patch": { "operationId": "updateMerchantConfiguration", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "showTodaySalesAggregate": { "description": "Show today's aggregated sales total on the merchant's terminals.", "type": "boolean" }, "showProductCatalogue": { "description": "Show the product catalog on the terminal.", "type": "boolean" }, "showExitButton": { "description": "Show the exit button on the terminal payment app.", "type": "boolean" }, "showTransactions": { "description": "Show the transaction history on the terminal.", "type": "boolean" }, "settlementFrequency": { "description": "How often the merchant is settled.\n\nValues:\n- `DAILY`: Daily settlement.\n- `WEEKLY`: Weekly settlement.\n- `MONTHLY`: Monthly settlement.", "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ] }, "grossSettlement": { "description": "Settle gross amounts, with fees invoiced separately, instead of net settlement.", "type": "boolean" }, "enableProductCreation": { "description": "Allow the merchant to create products from the terminal.", "type": "boolean" }, "terminalReceiptTemplateId": { "description": "Identifier of the receipt template to use on the merchant terminals.", "type": "string" } } }, "example": { "showTodaySalesAggregate": true, "showProductCatalogue": false, "settlementFrequency": "DAILY", "grossSettlement": false } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request 'SUCCESS' | 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Configurations added successfully." } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to add configurations" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/service-providers": { "get": { "operationId": "fetchMerchantServiceProviders", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The service providers configured for the merchant.", "type": "object", "properties": { "serviceProviders": { "description": "List of service providers.", "type": "array", "items": { "type": "object", "properties": { "serviceProviderId": { "description": "Unique identifier of the service provider.", "type": "string" }, "personId": { "description": "Identifier of the person associated with the service provider.", "type": "string" }, "corporateId": { "description": "Corporate identifier of the service provider.", "type": "string" }, "nationalId": { "description": "National identifier of the service provider.", "type": "string" }, "name": { "description": "Name of the service provider.", "type": "string" }, "address": { "description": "Address of the service provider. Can be null.", "type": "object", "properties": { "addressLine1": { "description": "First line of the service provider address.", "type": "string" }, "city": { "description": "City of the service provider.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code, in uppercase, of the service provider.", "type": "string" }, "postalCode": { "description": "Postal code of the service provider.", "type": "string" } }, "additionalProperties": true }, "phoneNumber": { "description": "Contact number of the service provider. Can be null.", "type": "object", "properties": { "number": { "description": "Phone number of the service provider.", "type": "string" }, "code": { "description": "International dialing code of the phone number.", "type": "string" }, "role": { "description": "Role associated with the phone number.", "type": "string" } }, "additionalProperties": true }, "email": { "description": "Email address of the service provider.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "serviceProviders": [ { "serviceProviderId": "sp_81412e3c3b1090060f", "personId": "pn_5f2c1a9b3d", "corporateId": "5591631360", "nationalId": "199001011234", "name": "Nordic Accounting AB", "address": { "addressLine1": "Main Street 123", "city": "Stockholm", "countryCode": "SE", "postalCode": "12345" }, "phoneNumber": { "number": "812345678", "code": "46", "role": "PRIMARY" }, "email": "billing@nordicaccounting.se" } ] }, "message": "Service providers fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch service providers" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/partners/{partnerId}/multi-merchants/{merchantId}": { "get": { "operationId": "fetchMultiMerchantGroup", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The merchants that belong to the multi-merchant group.", "type": "array", "items": { "type": "object", "properties": { "merchantId": { "description": "Unique identifier of the member merchant.", "type": "string" }, "merchantName": { "description": "Name of the member merchant.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code, in uppercase, of the member merchant.", "type": "string" }, "currencyCode": { "description": "Three-digit ISO currency code of the member merchant, returned when the merchant has a payment-facilitator account.", "type": "string" }, "acquirerMID": { "description": "Acquirer Merchant ID of the member merchant, returned when the merchant has a payment-facilitator account.", "type": "string" }, "partnerId": { "description": "Identifier of the partner that owns the merchant.", "type": "string" }, "merchantLanguage": { "description": "Default language configured for the merchant.", "type": "string" }, "merchantLogoUrl": { "description": "URL of the merchant's logo.", "type": "string" }, "email": { "description": "Contact email for the merchant.", "type": "string" }, "companyId": { "description": "Company registration (organization) number of the merchant.", "type": "string" }, "mccCode": { "description": "Merchant category code (MCC) for the merchant.", "type": "string" }, "createdAt": { "description": "When the merchant was created, in ISO 8601 format.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "merchantId": "817544960dd838040e", "merchantName": "Test Merchant one", "countryCode": "SE", "currencyCode": "752", "acquirerMID": "gfprLY1dyAQO" }, { "merchantId": "8175449a8dd8380d0e", "merchantName": "Test Merchant two", "countryCode": "SE" } ], "message": "Successfully fetched merchants details" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "No merchants found under this multi merchant group" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] }, "put": { "operationId": "updateMultiMerchantGroup", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "multiMerchantName": { "description": "New name for the multi-merchant group.", "type": "string" } }, "required": [ "multiMerchantName" ] }, "example": { "multiMerchantName": "Nordic Retail Group" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request 'SUCCESS' | 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Update merchant details successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unhandled error occurred" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/applications/{applicationId}/signing-links": { "get": { "operationId": "fetchApplicationSigningLinks", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Merchants API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "applicationId", "in": "path", "required": true, "description": "Identifier for the application this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The signing links for the application. Null when no signing sessions exist.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "The kind of signing session, for example the signer category.", "type": "string" }, "linkId": { "description": "Unique identifier of the signing link.", "type": "string" }, "url": { "description": "The URL the signer opens to complete their signature.", "type": "string" }, "data": { "description": "The people associated with this signing link. Null when none are attached.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Name of the person who needs to sign.", "type": "string" }, "emailId": { "description": "Email address of the person who needs to sign.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "type": "SIGNATORY", "linkId": "lnk_81409507c1a5f00110", "url": "https://surfkyb.com/sign/lnk_81409507c1a5f00110", "data": [ { "name": "Jane Doe", "emailId": "jane.doe@surfboard.se" } ] } ], "message": "Decoupled session fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to fetch decoupled session" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/merchants/{merchantId}/notifications/reports": { "post": { "operationId": "subscribeToMerchantReports", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Notifications API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "description": "The event type to subscribe to for notifications\n\nValues:\n- `DAILY_REPORTS`: Daily merchant reports\n- `MONTHLY_REPORTS`: Monthly merchant reports\n- `PAYMENT_COMPLETED`: Payment completion notifications\n- `DAILY_FILE_TRANSFER`: Daily SFTP file transfers\n- `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers\n- `MONTHLY_FILE_TRANSFER`: Monthly SFTP file transfers", "type": "string", "enum": [ "DAILY_REPORTS", "MONTHLY_REPORTS", "PAYMENT_COMPLETED", "DAILY_FILE_TRANSFER", "WEEKLY_FILE_TRANSFER", "MONTHLY_FILE_TRANSFER" ] }, "email": { "description": "Email address for notification delivery (optional) Conditionally required: see the endpoint notes.", "type": "string" }, "slackUrl": { "description": "Slack webhook URL for notification delivery (optional) Conditionally required: see the endpoint notes.", "type": "string" }, "sftpInfo": { "description": "SFTP configuration for receiving notification reports Conditionally required: see the endpoint notes.", "type": "object", "properties": { "host": { "description": "SFTP server hostname or IP address", "type": "string" }, "user": { "description": "Username for SFTP authentication", "type": "string" }, "port": { "description": "SFTP server port (default: 22)", "type": "number" }, "hostKey": { "description": "SFTP server host key for secure connection", "type": "string" }, "remoteDirectory": { "description": "Remote directory path for file delivery", "type": "string" }, "separator": { "description": "Field separator for CSV reports\n\nValues:\n- `COMMA`: Comma separator (,)\n- `SEMICOLON`: Semicolon separator (;)\n- `PIPE`: Pipe separator (|)\n- `TAB`: Tab separator", "type": "string", "enum": [ "COMMA", "SEMICOLON", "PIPE", "TAB" ] }, "paymentStatuses": { "description": "Restrict the report to payments with these statuses. Accepts a subset of PAYMENT_COMPLETED and PAYMENT_FAILED.", "type": "array", "items": {} }, "paymentTypes": { "description": "Restrict the report to these payment types, letting you control whether refunds are included. Accepts PURCHASE and RETURN.", "type": "array", "items": {} }, "includeColumns": { "description": "Choose which columns appear in the CSV report. Accepts individual column names or group tokens such as ADJUSTMENTS.", "type": "array", "items": {} } }, "required": [ "host", "user" ] } }, "required": [ "event" ] }, "example": { "event": "DAILY_FILE_TRANSFER", "slackUrl": "https://surfboardworkspace.slack.com/archives/C039RL0LS8M", "email": "john@gmail.com", "sftpInfo": { "host": "192.168.0.211", "user": "surfboard-test", "port": 8080, "hostKey": "AAAAB3NzaC1yc2EAAAADAQABAAABgQDVjVZBKMAFE3z4m1M6xVpudb+Wcal1kAfzdpOsi64cXjBdK2VS0cuI38htYHGXhpqQ2z/XbYZ2ZfPUkzL/P0IV7Kec22ohLNSN3+r9r3jjB/EU9S46ApuHzloEFnSlPVT5xQA2d09Rs40iMjRp3hfov4pwNPwlav0ikLafSvPWZ2bUfsWq/vNdhnNGBd0au59qIAHrphkF5oyRQUjC5kssSuwZXo2GWC0zHuT06h3/t21BJMoQT4cJ2AEw5Cfvq/cUtSAUKsWaz++0wgyYBOYnYGHpxype+6c7x8gRkuAeuSyj/CdDG39CMSKLsf35CSr7bH8Tsmm6VuIPFwTr8FloGdVwthQiSOPDn15kQXeEiksmzeIMKilgpEWIxp1pgYgtrOefAXp+aoKSqNw+ccvUhiVwIpo2BXxM+l3douJMy2B7A29R+VvwOGDV1zbiYrxjbpDHqMpLjOo5vckj/YYyvHn32nnmb92Hl+A1+b9om1c/y/RN2aRgz6tgmPxhhVU=", "paymentStatuses": [ "PAYMENT_COMPLETED" ], "paymentTypes": [ "PURCHASE", "RETURN" ], "includeColumns": [ "ADJUSTMENTS" ] } } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "data": { "description": "Array of notification subscription data", "type": "array", "items": { "type": "object", "properties": { "notificationId": { "description": "Unique identifier for the notification subscription", "type": "string" }, "NotificationChannel": { "description": "Type of notification channel (e.g., SLACK, SFTP, EMAIL)", "type": "string" }, "publicKey": { "description": "Public key for SFTP authentication (only present for SFTP channels)", "type": "string" } }, "required": [ "notificationId", "NotificationChannel" ], "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "notificationId": "839dd1b8113ff809f3", "NotificationChannel": "EMAIL" }, { "notificationId": "839dd1b8113ff819f3", "NotificationChannel": "SLACK" }, { "notificationId": "839dd1b8113ff82af3", "NotificationChannel": "SFTP", "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCfGfO3kOLdYji5R6GNI8lvfyI5MgpQY43OF+HwAqgF96L6hg1jG/Nu58bToPZoaf+lkqp+/MDNGTIeRfMkR+3g1Q2sgZ3jGvN3lErvfbbnYGx7qDzfyMCg7i9VneVOJb4fxoSRzbja2ZG7XxbSzBPvzGky38AKqBq5EysO8/FnA6I9SNCMPcyaEq3Rs33kGjcBthOxc3X+3dRvKt0GU77xtt0tWl7vP/DHXj9m32kcjNN2647i/oRoAiM58fhtsU3UM5TQGYn6WJ0/su7X5JnBy2+WktotJvfzF7ri2Q+R5Ac7kem5g17wdMPgICaz1sDY6haxI3TuDOe8ZVybfV6T surfboard-test@34.88.179.4" } ], "message": "External notification for MERCHANT_ID: m_iWGri3XAyTmkbKYsYtV47 registered successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Invalid SFTP event: \"PAYMENT_COMPLETED\". Accepted: DAILY_FILE_TRANSFER, WEEKLY_FILE_TRANSFER, MONTHLY_FILE_TRANSFER" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/notifications": { "get": { "operationId": "fetchExternalNotificationsForMerchant", "summary": "Fetch External Notifications for Merchant", "description": "Retrieves all external notifications configured for a merchant. Supports filtering by event type, notification channel, and notification ID\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Notifications API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "event", "in": "query", "required": false, "description": "Filter by event type\n\nValues:\n- `DAILY_REPORTS`: Daily merchant reports\n- `MONTHLY_REPORTS`: Monthly merchant reports\n- `PAYMENT_COMPLETED`: Payment completion notifications\n- `DAILY_FILE_TRANSFER`: Daily SFTP file transfers\n- `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers\n- `MONTHLY_FILE_TRANSFER`: Monthly SFTP file transfers", "schema": { "description": "Filter by event type\n\nValues:\n- `DAILY_REPORTS`: Daily merchant reports\n- `MONTHLY_REPORTS`: Monthly merchant reports\n- `PAYMENT_COMPLETED`: Payment completion notifications\n- `DAILY_FILE_TRANSFER`: Daily SFTP file transfers\n- `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers\n- `MONTHLY_FILE_TRANSFER`: Monthly SFTP file transfers", "type": "string", "enum": [ "DAILY_REPORTS", "MONTHLY_REPORTS", "PAYMENT_COMPLETED", "DAILY_FILE_TRANSFER", "WEEKLY_FILE_TRANSFER", "MONTHLY_FILE_TRANSFER" ] } }, { "name": "notificationChannel", "in": "query", "required": false, "description": "Filter by notification channel\n\nValues:\n- `EMAIL`: Email notifications\n- `SLACK`: Slack notifications\n- `SFTP`: SFTP file transfer notifications", "schema": { "description": "Filter by notification channel\n\nValues:\n- `EMAIL`: Email notifications\n- `SLACK`: Slack notifications\n- `SFTP`: SFTP file transfer notifications", "type": "string", "enum": [ "EMAIL", "SLACK", "SFTP" ] } }, { "name": "notificationId", "in": "query", "required": false, "description": "Filter by notification ID", "schema": { "description": "Filter by notification ID", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "data": { "description": "Array of notification objects", "type": "array", "items": { "type": "object", "properties": { "notificationId": { "description": "Unique identifier for the notification", "type": "string" }, "event": { "description": "Event type for the notification\n\nValues:\n- `DAILY_REPORTS`: Daily merchant reports\n- `MONTHLY_REPORTS`: Monthly merchant reports\n- `PAYMENT_COMPLETED`: Payment completion notifications\n- `DAILY_FILE_TRANSFER`: Daily SFTP file transfers\n- `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers\n- `MONTHLY_FILE_TRANSFER`: Monthly SFTP file transfers", "type": "string", "enum": [ "DAILY_REPORTS", "MONTHLY_REPORTS", "PAYMENT_COMPLETED", "DAILY_FILE_TRANSFER", "WEEKLY_FILE_TRANSFER", "MONTHLY_FILE_TRANSFER" ] }, "notificationChannel": { "description": "Channel used for notification delivery", "type": "string" }, "address": { "description": "Address configuration for the notification", "type": "object", "properties": { "url": { "description": "URL for webhook notifications", "type": "string" }, "email": { "description": "Email address for email notifications", "type": "string" }, "host": { "description": "SFTP host address", "type": "string" }, "remoteDirectory": { "description": "SFTP remote directory", "type": "string" }, "user": { "description": "SFTP username", "type": "string" }, "port": { "description": "SFTP port number", "type": "number" }, "publicKey": { "description": "SFTP public key", "type": "string" }, "separator": { "description": "CSV field separator", "type": "string" }, "paymentStatuses": { "description": "Payment statuses the SFTP report is filtered to, when configured", "type": "array", "items": {} }, "paymentTypes": { "description": "Payment types the SFTP report is filtered to, when configured", "type": "array", "items": {} }, "includeColumns": { "description": "Columns included in the SFTP report, when configured", "type": "array", "items": {} } }, "additionalProperties": true }, "status": { "description": "Status of the notification subscription", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "notificationId": "839cfe66fe08b00bf3", "event": "WEEKLY_FILE_TRANSFER", "notificationChannel": "SFTP", "address": { "host": "192.168.0.211", "user": "surfboard-test", "port": 8080, "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDPrhFN05QsXZPVGn3uHpRih3bJrRARfvqvyZ5RuRG78YXiVjfHszckpzcay7uF6fsMQes8ky4RGywHs7UfhWbXhu5EDE/swZzTtu8TRVmRhIL6K1o8VKFEEJat3+UgwgrkdKHpUyld3r2doNcViHDiBTiVW4O4JR98/XHrhR7Ge9EPxE/iVwyur+YREtt3RKdZV3d+NG+4WFRqaq70lM13z0u1lACP8PRl4dyRbjrpGoMGq2zDSvyerzS6fKg7jm1UBOt4wznu8pjIE+A+9xiNvzpnxG1q4GxwpRq8e8AY5WIvpngOpaiifEObAGWnauvWnenPwV/yvudTwK4bFQBV surfboard-test@192.168.0.211", "separator": ",", "paymentStatuses": [ "PAYMENT_COMPLETED" ], "paymentTypes": [ "PURCHASE", "RETURN" ], "includeColumns": [ "ADJUSTMENTS" ] }, "status": "REGISTERED" }, { "notificationId": "839d223b9df16805f3", "event": "PAYMENT_COMPLETED", "notificationChannel": "EMAIL", "address": { "email": "merchant@example.com" }, "status": "SUBSCRIBED" } ], "message": "External notification for MERCHANT_ID: m_iWGri3XAyTmkbKYsYtV47 fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Invalid notificationChannel. Must be one of: EMAIL, SLACK, SFTP" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/notifications/{notificationId}": { "delete": { "operationId": "unsubscribeNotificationForMerchant", "summary": "Unsubscribe Notification for Merchant", "description": "Unsubscribe from a specific notification for a merchant. This endpoint removes the notification subscription identified by the notification ID\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Notifications API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "notificationId", "in": "path", "required": true, "description": "Identifier for the notification this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "message": { "description": "A message that describes the status of the request", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "External notification unsubscribed successfully for the given ID [m_iWGri3XAyTmkbKYsYtV47] and external alert ID [839d12501df1680cf3]" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to cancel external notification subscription." } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/notifications/reports": { "post": { "operationId": "subscribeToPartnerNotifications", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Notifications API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "description": "The event type to subscribe to for notifications\n\nValues:\n- `MERCHANT_ONBOARDED`: Merchant onboarding notifications\n- `ONLINE_STORE_ONBOARDED`: Online store onboarding notifications\n- `TERMINAL_REGISTERED`: Terminal registration notifications\n- `LOGISTICS_TERMINAL_SHIPPED`: Logistics terminal shipping notifications\n- `DAILY_FILE_TRANSFER`: Daily SFTP file transfers\n- `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers\n- `MONTHLY_FILE_TRANSFER`: Monthly SFTP file transfers", "type": "string", "enum": [ "MERCHANT_ONBOARDED", "ONLINE_STORE_ONBOARDED", "TERMINAL_REGISTERED", "LOGISTICS_TERMINAL_SHIPPED", "DAILY_FILE_TRANSFER", "WEEKLY_FILE_TRANSFER", "MONTHLY_FILE_TRANSFER" ] }, "email": { "description": "Email address for notification delivery (optional) Conditionally required: see the endpoint notes.", "type": "string" }, "slackUrl": { "description": "Slack webhook URL for notification delivery (optional) Conditionally required: see the endpoint notes.", "type": "string" }, "sftpInfo": { "description": "SFTP configuration for receiving notification reports Conditionally required: see the endpoint notes.", "type": "object", "properties": { "host": { "description": "SFTP server hostname or IP address", "type": "string" }, "user": { "description": "Username for SFTP authentication", "type": "string" }, "port": { "description": "SFTP server port (default: 22)", "type": "number" }, "hostKey": { "description": "SFTP server host key for secure connection", "type": "string" }, "remoteDirectory": { "description": "Remote directory path for file delivery", "type": "string" }, "separator": { "description": "Field separator for CSV reports\n\nValues:\n- `COMMA`: Comma separator (,)\n- `SEMICOLON`: Semicolon separator (;)\n- `PIPE`: Pipe separator (|)\n- `TAB`: Tab separator", "type": "string", "enum": [ "COMMA", "SEMICOLON", "PIPE", "TAB" ] }, "paymentStatuses": { "description": "Restrict the report to payments with these statuses. Accepts a subset of PAYMENT_COMPLETED and PAYMENT_FAILED.", "type": "array", "items": {} }, "paymentTypes": { "description": "Restrict the report to these payment types, letting you control whether refunds are included. Accepts PURCHASE and RETURN.", "type": "array", "items": {} }, "includeColumns": { "description": "Choose which columns appear in the CSV report. Accepts individual column names or group tokens such as ADJUSTMENTS.", "type": "array", "items": {} } }, "required": [ "host", "user" ] } }, "required": [ "event" ] }, "example": { "event": "DAILY_FILE_TRANSFER", "slackUrl": "https://surfboardworkspace.slack.com/archives/C039RL0LS8M", "email": "john@gmail.com", "sftpInfo": { "host": "192.168.0.211", "user": "surfboard-test", "port": 8080, "hostKey": "AAAAB3NzaC1yc2EAAAADAQABAAABgQDVjVZBKMAFE3z4m1M6xVpudb+Wcal1kAfzdpOsi64cXjBdK2VS0cuI38htYHGXhpqQ2z/XbYZ2ZfPUkzL/P0IV7Kec22ohLNSN3+r9r3jjB/EU9S46ApuHzloEFnSlPVT5xQA2d09Rs40iMjRp3hfov4pwNPwlav0ikLafSvPWZ2bUfsWq/vNdhnNGBd0au59qIAHrphkF5oyRQUjC5kssSuwZXo2GWC0zHuT06h3/t21BJMoQT4cJ2AEw5Cfvq/cUtSAUKsWaz++0wgyYBOYnYGHpxype+6c7x8gRkuAeuSyj/CdDG39CMSKLsf35CSr7bH8Tsmm6VuIPFwTr8FloGdVwthQiSOPDn15kQXeEiksmzeIMKilgpEWIxp1pgYgtrOefAXp+aoKSqNw+ccvUhiVwIpo2BXxM+l3douJMy2B7A29R+VvwOGDV1zbiYrxjbpDHqMpLjOo5vckj/YYyvHn32nnmb92Hl+A1+b9om1c/y/RN2aRgz6tgmPxhhVU=", "paymentStatuses": [ "PAYMENT_COMPLETED" ], "paymentTypes": [ "PURCHASE", "RETURN" ], "includeColumns": [ "ADJUSTMENTS" ] } } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "data": { "description": "Array of notification subscription data", "type": "array", "items": { "type": "object", "properties": { "notificationId": { "description": "Unique identifier for the notification subscription", "type": "string" }, "NotificationChannel": { "description": "Type of notification channel (e.g., SLACK, SFTP, EMAIL)", "type": "string" }, "publicKey": { "description": "Public key for SFTP authentication (only present for SFTP channels)", "type": "string" } }, "required": [ "notificationId", "NotificationChannel" ], "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "notificationId": "839dd1b8113ff809f3", "NotificationChannel": "EMAIL" }, { "notificationId": "839dd1b8113ff819f3", "NotificationChannel": "SLACK" }, { "notificationId": "839dd1b8113ff82af3", "NotificationChannel": "SFTP", "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCfGfO3kOLdYji5R6GNI8lvfyI5MgpQY43OF+HwAqgF96L6hg1jG/Nu58bToPZoaf+lkqp+/MDNGTIeRfMkR+3g1Q2sgZ3jGvN3lErvfbbnYGx7qDzfyMCg7i9VneVOJb4fxoSRzbja2ZG7XxbSzBPvzGky38AKqBq5EysO8/FnA6I9SNCMPcyaEq3Rs33kGjcBthOxc3X+3dRvKt0GU77xtt0tWl7vP/DHXj9m32kcjNN2647i/oRoAiM58fhtsU3UM5TQGYn6WJ0/su7X5JnBy2+WktotJvfzF7ri2Q+R5Ac7kem5g17wdMPgICaz1sDY6haxI3TuDOe8ZVybfV6T surfboard-test@34.88.179.4" } ], "message": "External notification for PARTNER_ID: 8113d3f8403b380409 registered successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Invalid event: \"DAILY_REPORTS\". Accepted: MERCHANT_ONBOARDED, ONLINE_STORE_ONBOARDED, TERMINAL_REGISTERED, LOGISTICS_TERMINAL_SHIPPED" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/notifications": { "get": { "operationId": "fetchExternalNotificationsForPartner", "summary": "Fetch External Notifications for Partner", "description": "Retrieves all external notifications configured for a partner. Supports filtering by event type, notification channel, and notification ID\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Notifications API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "event", "in": "query", "required": false, "description": "Filter by event type\n\nValues:\n- `MERCHANT_ONBOARDED`: Merchant onboarding notifications\n- `ONLINE_STORE_ONBOARDED`: Online store onboarding notifications\n- `TERMINAL_REGISTERED`: Terminal registration notifications\n- `LOGISTICS_TERMINAL_SHIPPED`: Logistics terminal shipping notifications\n- `DAILY_FILE_TRANSFER`: Daily SFTP file transfers\n- `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers\n- `MONTHLY_FILE_TRANSFER`: Monthly SFTP file transfers", "schema": { "description": "Filter by event type\n\nValues:\n- `MERCHANT_ONBOARDED`: Merchant onboarding notifications\n- `ONLINE_STORE_ONBOARDED`: Online store onboarding notifications\n- `TERMINAL_REGISTERED`: Terminal registration notifications\n- `LOGISTICS_TERMINAL_SHIPPED`: Logistics terminal shipping notifications\n- `DAILY_FILE_TRANSFER`: Daily SFTP file transfers\n- `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers\n- `MONTHLY_FILE_TRANSFER`: Monthly SFTP file transfers", "type": "string", "enum": [ "MERCHANT_ONBOARDED", "ONLINE_STORE_ONBOARDED", "TERMINAL_REGISTERED", "LOGISTICS_TERMINAL_SHIPPED", "DAILY_FILE_TRANSFER", "WEEKLY_FILE_TRANSFER", "MONTHLY_FILE_TRANSFER" ] } }, { "name": "notificationChannel", "in": "query", "required": false, "description": "Filter by notification channel\n\nValues:\n- `EMAIL`: Email notifications\n- `SLACK`: Slack notifications\n- `SFTP`: SFTP file transfer notifications", "schema": { "description": "Filter by notification channel\n\nValues:\n- `EMAIL`: Email notifications\n- `SLACK`: Slack notifications\n- `SFTP`: SFTP file transfer notifications", "type": "string", "enum": [ "EMAIL", "SLACK", "SFTP" ] } }, { "name": "notificationId", "in": "query", "required": false, "description": "Filter by notification ID", "schema": { "description": "Filter by notification ID", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "data": { "description": "Array of notification objects", "type": "array", "items": { "type": "object", "properties": { "notificationId": { "description": "Unique identifier for the notification", "type": "string" }, "event": { "description": "Event type for the notification\n\nValues:\n- `MERCHANT_ONBOARDED`: Merchant onboarding notifications\n- `ONLINE_STORE_ONBOARDED`: Online store onboarding notifications\n- `TERMINAL_REGISTERED`: Terminal registration notifications\n- `LOGISTICS_TERMINAL_SHIPPED`: Logistics terminal shipping notifications\n- `DAILY_FILE_TRANSFER`: Daily SFTP file transfers\n- `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers\n- `MONTHLY_FILE_TRANSFER`: Monthly SFTP file transfers", "type": "string", "enum": [ "MERCHANT_ONBOARDED", "ONLINE_STORE_ONBOARDED", "TERMINAL_REGISTERED", "LOGISTICS_TERMINAL_SHIPPED", "DAILY_FILE_TRANSFER", "WEEKLY_FILE_TRANSFER", "MONTHLY_FILE_TRANSFER" ] }, "notificationChannel": { "description": "Channel used for notification delivery", "type": "string" }, "address": { "description": "Address configuration for the notification", "type": "object", "properties": { "url": { "description": "URL for webhook notifications", "type": "string" }, "email": { "description": "Email address for email notifications", "type": "string" }, "host": { "description": "SFTP host address", "type": "string" }, "remoteDirectory": { "description": "SFTP remote directory", "type": "string" }, "user": { "description": "SFTP username", "type": "string" }, "port": { "description": "SFTP port number", "type": "number" }, "publicKey": { "description": "SFTP public key", "type": "string" }, "separator": { "description": "CSV field separator", "type": "string" }, "paymentStatuses": { "description": "Payment statuses the SFTP report is filtered to, when configured", "type": "array", "items": {} }, "paymentTypes": { "description": "Payment types the SFTP report is filtered to, when configured", "type": "array", "items": {} }, "includeColumns": { "description": "Columns included in the SFTP report, when configured", "type": "array", "items": {} } }, "additionalProperties": true }, "status": { "description": "Status of the notification subscription", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "notificationId": "839cfe66fe08b00bf3", "event": "WEEKLY_FILE_TRANSFER", "notificationChannel": "SFTP", "address": { "host": "192.168.0.211", "user": "surfboard-test", "port": 8080, "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDPrhFN05QsXZPVGn3uHpRih3bJrRARfvqvyZ5RuRG78YXiVjfHszckpzcay7uF6fsMQes8ky4RGywHs7UfhWbXhu5EDE/swZzTtu8TRVmRhIL6K1o8VKFEEJat3+UgwgrkdKHpUyld3r2doNcViHDiBTiVW4O4JR98/XHrhR7Ge9EPxE/iVwyur+YREtt3RKdZV3d+NG+4WFRqaq70lM13z0u1lACP8PRl4dyRbjrpGoMGq2zDSvyerzS6fKg7jm1UBOt4wznu8pjIE+A+9xiNvzpnxG1q4GxwpRq8e8AY5WIvpngOpaiifEObAGWnauvWnenPwV/yvudTwK4bFQBV surfboard-test@192.168.0.211", "separator": ",", "paymentStatuses": [ "PAYMENT_COMPLETED" ], "paymentTypes": [ "PURCHASE", "RETURN" ], "includeColumns": [ "ADJUSTMENTS" ] }, "status": "REGISTERED" }, { "notificationId": "839d223b9df16805f3", "event": "ONLINE_STORE_ONBOARDED", "notificationChannel": "EMAIL", "address": { "email": "partner@example.com" }, "status": "SUBSCRIBED" } ], "message": "External notification for PARTNER_ID: 8113d3f8403b380409 fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Invalid notificationChannel. Must be one of: EMAIL, SLACK, SFTP" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/notifications/{notificationId}": { "delete": { "operationId": "unsubscribeNotificationsForPartner", "summary": "Unsubscribe Notifications for Partner", "description": "Unsubscribe from a specific notification for a partner. This endpoint removes the notification subscription identified by the notification ID\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Notifications API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "notificationId", "in": "path", "required": true, "description": "Identifier for the notification this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'", "type": "string" }, "message": { "description": "A message that describes the status of the request", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "External notification unsubscribed successfully for the given ID [8113d3f8403b380409] and external alert ID [839d12501df1680cf3]" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to cancel external notification subscription." } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/orders": { "post": { "operationId": "createOrder", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Orders API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terminal$id": { "description": "ID of the checkout or payment terminal", "type": "string" }, "referenceId": { "description": "External reference ID for the order", "type": "string" }, "comments": { "description": "Additional comments or notes for the order", "type": "string" }, "customer": { "description": "Customer details for the order", "type": "object", "properties": { "customerId": { "description": "Unique identifier for the customer", "type": "string" }, "person": { "description": "Personal information of the customer", "type": "object", "properties": { "id": { "description": "Person identifier.", "type": "string" }, "name": { "description": "Full name of the customer", "type": "object", "properties": { "firstName": { "description": "First name of the customer", "type": "string" }, "middleName": { "description": "Middle name of the customer", "type": "string" }, "lastName": { "description": "Last name of the customer", "type": "string" } } }, "email": { "description": "Email address of the customer", "type": "string" }, "phoneNumber": { "description": "Phone number of the customer", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ] }, "birthDate": { "description": "Date of birth in YYYY-MM-DD format", "type": "string" }, "personalNumber": { "description": "Personal identification number", "type": "string" }, "coordinationNumber": { "description": "Coordination number", "type": "string" }, "countryResidence": { "description": "Country of residence of the customer", "type": "string" }, "gdNumber": { "description": "Government-issued identification number of the customer", "type": "string" } } }, "company": { "description": "Company information for corporate purchases", "type": "object", "properties": { "id": { "description": "Company identifier.", "type": "string" }, "vatId": { "description": "VAT ID of the company", "type": "string" }, "poDetails": { "description": "Purchase order details for the company", "type": "string" }, "companyName": { "description": "Company display name.", "type": "string" }, "registrationNumber": { "description": "Company registration number.", "type": "string" }, "gln": { "description": "GLN of the buyer's e-invoice department, used to route e-invoices.", "type": "string" } } } } }, "billing": { "description": "Billing contact and address", "type": "object", "properties": { "name": { "description": "Full name of the billing contact", "type": "object", "properties": { "firstName": { "description": "First name of the billing contact", "type": "string" }, "middleName": { "description": "Middle name of the billing contact", "type": "string" }, "lastName": { "description": "Last name of the billing contact", "type": "string" } } }, "email": { "description": "Billing email", "type": "string" }, "phoneNumber": { "description": "Phone number for billing", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ] }, "address": { "description": "Billing address", "type": "object", "properties": { "careOf": { "description": "Care of / attention", "type": "string" }, "addressLine1": { "description": "Primary address line", "type": "string" }, "addressLine2": { "description": "Address line 2", "type": "string" }, "addressLine3": { "description": "Address line 3", "type": "string" }, "city": { "description": "City name", "type": "string" }, "postalCode": { "description": "Postal/ZIP code", "type": "string" }, "countryCode": { "description": "Country code (ISO 3166-1 alpha-2)", "type": "string" } }, "required": [ "addressLine1", "city", "postalCode", "countryCode" ] } } }, "shipping": { "description": "Shipping contact and address", "type": "object", "properties": { "name": { "description": "Full name of the shipping contact", "type": "object", "properties": { "firstName": { "description": "First name of the shipping contact", "type": "string" }, "middleName": { "description": "Middle name of the shipping contact", "type": "string" }, "lastName": { "description": "Last name of the shipping contact", "type": "string" } } }, "email": { "description": "Recipient email", "type": "string" }, "phoneNumber": { "description": "Phone number for shipping", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ] }, "address": { "description": "Shipping address", "type": "object", "properties": { "careOf": { "description": "Care of / attention", "type": "string" }, "addressLine1": { "description": "Primary address line", "type": "string" }, "addressLine2": { "description": "Address line 2", "type": "string" }, "addressLine3": { "description": "Address line 3", "type": "string" }, "city": { "description": "City name", "type": "string" }, "postalCode": { "description": "Postal/ZIP code", "type": "string" }, "countryCode": { "description": "Country code (ISO 3166-1 alpha-2)", "type": "string" } }, "required": [ "addressLine1", "city", "postalCode", "countryCode" ] } } }, "orderLines": { "description": "List of items in the order", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Order line identifier", "type": "string" }, "externalItemId": { "description": "External order line identifier", "type": "string" }, "name": { "description": "Product name", "type": "string" }, "categoryId": { "description": "Product category identifier", "type": "string" }, "description": { "description": "Line item description", "type": "string" }, "quantity": { "description": "Quantity ordered. A negative value indicates a refund.", "type": "number" }, "amount": { "description": "Pricing details for the line item", "type": "object", "properties": { "regular": { "description": "Regular price amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "campaign": { "description": "Campaign/discount amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "shipping": { "description": "Shipping amount for this item in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "total": { "description": "Total line amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "currency": { "description": "Currency (numeric ISO 4217 as string)", "type": "string" }, "tax": { "description": "Tax breakdown", "type": "array", "items": { "type": "object", "properties": { "amount": { "description": "Tax amount", "type": "number" }, "percentage": { "description": "Tax rate percentage", "type": "number" }, "type": { "description": "Tax type (e.g., VAT)", "type": "string" } }, "required": [ "amount", "percentage", "type" ] } } }, "required": [ "regular", "total", "currency" ] }, "unit": { "description": "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'.", "type": "string" }, "gtin": { "description": "Global Trade Item Number", "type": "string" }, "imageUrl": { "description": "Image URL for the product", "type": "string" }, "brand": { "description": "Brand name", "type": "string" }, "purchaseOrderId": { "description": "Mandatory purchase order identifier if it's a return item. Conditionally required: see the endpoint notes.", "type": "string" }, "promotionApplied": { "description": "Product promotional campaign identifier.", "type": "string" }, "metadata": { "description": "Arbitrary metadata for the line", "type": "object", "additionalProperties": true }, "storeId": { "description": "Store identifier", "type": "string" }, "purchasePaymentId": { "description": "Purchase payment identifier associated with the order line", "type": "string" } }, "required": [ "id", "name", "quantity", "amount" ] } }, "totalOrderAmount": { "description": "Total amount details of the order.", "type": "object", "properties": { "regular": { "description": "Total regular order amount in the smallest currency unit (e.g., 10 SEK is represented as 1000)", "type": "number" }, "campaign": { "description": "Total campaign or discount amount applied to the order in the smallest currency unit", "type": "number" }, "total": { "description": "Overall payable order amount in the smallest currency unit (regular - campaign + shipping + tax)", "type": "number" }, "currency": { "description": "Order currency represented as a numeric ISO 4217 code (e.g., '752' for SEK)", "type": "string" }, "tax": { "description": "Order-level tax breakdown across applied tax categories", "type": "array", "items": { "type": "object", "properties": { "amount": { "description": "Total tax amount for the order in the smallest currency unit", "type": "number" }, "percentage": { "description": "Applied tax rate percentage", "type": "number" }, "type": { "description": "Type of tax applied (e.g., VAT, GST)", "type": "string" } }, "required": [ "amount", "percentage", "type" ] } } }, "required": [ "regular", "total", "currency" ] }, "date": { "description": "Order date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00). If not specified, the current date is used.", "type": "string" }, "metadata": { "description": "Arbitrary key-value style metadata items", "type": "object", "additionalProperties": true }, "adjustments": { "description": "Order-level adjustments", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Adjustment type", "type": "string" }, "value": { "description": "Adjustment value", "type": "number" }, "metadata": { "description": "Arbitrary key-value style metadata items.", "type": "object", "additionalProperties": true } }, "required": [ "type", "value" ] } }, "controlFunctions": { "description": "Advanced order/payment control configuration", "type": "object", "properties": { "cancelPreviousPendingOrder": { "description": "Set as true when you want to cancel all previous pending orders", "type": "boolean" }, "orderLineLevelCalculation": { "description": "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.", "type": "boolean" }, "serviceProviders": { "description": "External service providers participating in the transaction", "type": "array", "items": { "type": "object", "properties": { "serviceProviderId": { "description": "Service provider identifier", "type": "string" }, "amount": { "description": "Share/fee configuration", "type": "object", "properties": { "percentage": { "description": "Percentage share", "type": "number" }, "fixed": { "description": "Fixed share amount", "type": "number" }, "adjustmentTypes": { "description": "Allowed adjustment types for this provider as an array of string.", "type": "array", "items": {} } } } }, "required": [ "serviceProviderId" ] } }, "initiatePaymentsOptions": { "description": "Parameters for initiating payment", "type": "object", "properties": { "paymentMethod": { "description": "Payment method to use Conditionally required: see the endpoint notes.", "type": "string" }, "amount": { "description": "Amount to charge in smallest currency units.", "type": "number" }, "paymentMethodParams": { "description": "Method-specific parameters", "type": "object", "properties": { "tokenId": { "description": "Saved payment token ID Conditionally required: see the endpoint notes.", "type": "string" }, "bic": { "description": "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. Conditionally required: see the endpoint notes.", "type": "string" }, "swishMode": { "description": "Swish mode (e.g., ECOM) Conditionally required: see the endpoint notes.", "type": "string" }, "payeePhoneNumber": { "description": "Mandatory phone number for SWISH payments. Conditionally required: see the endpoint notes.", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ] }, "giftCard": { "description": "Gift card payment details Conditionally required: see the endpoint notes. Not live yet.", "type": "object", "properties": { "giftCardId": { "description": "Gift card identifier", "type": "string" }, "giftCardRedemptionMode": { "description": "Redemption mode (e.g., WALLET)", "type": "string" } } }, "invoice": { "description": "Invoice payment configuration", "type": "object", "properties": { "invoiceDistribution": { "description": "Distribution channel (e.g., EMAIL) Conditionally required: see the endpoint notes.", "type": "string" }, "contractReference": { "description": "Contract reference identifier", "type": "string" }, "debtCollectionEnabled": { "description": "Enable debt collection", "type": "boolean" }, "dueDate": { "description": "Due date or relative duration (e.g., 30d) Conditionally required: see the endpoint notes.", "type": "string" }, "invoicePaymentMethods": { "description": "Allowed payment methods for invoice Conditionally required: see the endpoint notes.", "type": "array", "items": {} }, "reminder": { "description": "Enable reminders Conditionally required: see the endpoint notes.", "type": "boolean" } } } } }, "serialSplitPaymentsMode": { "description": "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.", "type": "array", "items": {} }, "refundProcessingParams": { "description": "Parameters for processing refunds", "type": "object", "properties": { "purchasePaymentId": { "description": "Original purchase payment ID", "type": "string" }, "refundReason": { "description": "Reason for refund (as provided)", "type": "string" }, "otherReason": { "description": "Other reason details", "type": "string" } } } } }, "tipsMode": { "description": "Tips configuration (STANDARD | ROUNDUP | NONE)", "type": "string" }, "cardStatementDescriptor": { "description": "Statement descriptor text", "type": "string" }, "includeAdjustmentsForRefund": { "description": "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.", "type": "boolean" }, "lockToPaymentMethods": { "description": "An array of payment methods locked in. All available payment methods are supported. For example, ['CARD', 'KLARNA']", "type": "array", "items": {} }, "tapBeforeAmount": { "description": "If true, requires the customer to tap the card before the amount is entered, ensuring amount confirmation prior to payment.", "type": "boolean" }, "delayCapture": { "description": "Allows capture at a later time.", "type": "boolean" }, "delayPayout": { "description": "Delays the final amount paid out to the merchant after all deductions, in the format numbers + 'm' | 'h' | 'd' .", "type": "string" }, "fulfillmentDate": { "description": "Planned fulfillment date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00)", "type": "string" }, "callBackUrl": { "description": "This is a dynamic callback URL that is used to perform webhook calls in relation to the order and payment.", "type": "string" }, "throwErrorIfTerminalInactiveFor": { "description": "Threshold in ms if the respective terminal has been inactive for the given time frame.", "type": "number" }, "clearingCutOff": { "description": "Clearing cutoff configuration in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00)", "type": "string" }, "currency": { "description": "Order currency override", "type": "string" }, "authMode": { "description": "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.", "type": "string" }, "receipt": { "description": "Receipt handling options", "type": "object", "properties": { "autoPrintReceipt": { "description": "Auto-print setting", "type": "boolean" }, "autoSendReceiptIfEmailAvailable": { "description": "Auto-send if email present", "type": "boolean" }, "sequenceNumber": { "description": "Receipt sequence number", "type": "string" }, "cashRegisterName": { "description": "Cash register name", "type": "string" }, "controlUnitSerialNumber": { "description": "Control unit serial number", "type": "string" }, "receiptRedirectURL": { "description": "Receipt redirect URL", "type": "string" }, "cashierName": { "description": "Cashier name", "type": "string" }, "promotionsToDisplay": { "description": "Promotions to display on receipt", "type": "array", "items": {} } } }, "surcharges": { "description": "A record of additional fees or charges applied to the transaction, keyed by unique identifiers. Not live yet.", "type": "object", "properties": { "domestic": { "description": "Surcharges for domestic transactions (same country).", "type": "object", "properties": { "consumer": { "description": "Surcharges for consumer cards in domestic transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for consumer debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units (e.g., 100 = 1.00).", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge (e.g., 1.5 = 1.5%).", "type": "number" } } }, "credit": { "description": "Surcharge definitions for consumer credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } } } }, "corporate": { "description": "Surcharges for corporate cards in domestic transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for corporate debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } }, "credit": { "description": "Surcharge definitions for corporate credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } } } } } }, "international": { "description": "Surcharges for international transactions (outside the merchant’s country).", "type": "object", "properties": { "consumer": { "description": "Surcharges for consumer cards in international transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for consumer debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } }, "credit": { "description": "Surcharge definitions for consumer credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } } } }, "corporate": { "description": "Surcharges for corporate cards in international transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for corporate debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } }, "credit": { "description": "Surcharge definitions for corporate credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } } } } } }, "eea": { "description": "Surcharges for EEA (European Economic Area) transactions.", "type": "object", "properties": { "consumer": { "description": "Surcharges for consumer cards in EEA transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for consumer debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } }, "credit": { "description": "Surcharge definitions for consumer credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } } } }, "corporate": { "description": "Surcharges for corporate cards in EEA transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for corporate debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } }, "credit": { "description": "Surcharge definitions for corporate credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } } } } } } } }, "readTags": { "description": "This field denotes the type of NFC reading allowed on the terminal for the order. The possible values are,\n\nValues:\n- `NONE`: This value indicates that no tags are allowed for reading.\n- `SINGLE`: Single read allowed for the order.\n- `MULTIPLE_EDITABLE`: Multiple tags can be read and edited.\n- `MULTIPLE_NONEDITABLE`: Multiple tags can be read, but cannot be modified.", "type": "string", "enum": [ "NONE", "SINGLE", "MULTIPLE_EDITABLE", "MULTIPLE_NONEDITABLE" ] }, "ecrEnabled": { "description": "Whether ECR (electronic cash register) mode is enabled.", "type": "boolean" }, "online": { "description": "Online payment/link settings", "type": "object", "properties": { "enforceTokenization": { "description": "Denotes whether the card is tokenised for a future transaction or not.", "type": "boolean" }, "paymentPageValidFor": { "description": "Default validity of the payment page in format , where unit is 'm' | 'h' | 'd' (e.g., '15m', '2h', '3d').", "type": "string" }, "enforce3DSecure": { "description": "Force 3-D Secure authentication when available.", "type": "boolean" }, "relaxed3ds": { "description": "Allow relaxed 3-D Secure handling.", "type": "boolean" }, "addressRequirements": { "description": "Require an address on the payment page.", "type": "boolean" }, "redirectUrl": { "description": "Redirect URL after the online transaction completes successfully. The orderId will be appended as a query parameter.", "type": "string" }, "accountNameVerification": { "description": "Account-name verification mode applied during the payment.", "type": "string" }, "errorIfTokenizationFails": { "description": "If true, fail the flow when card tokenization cannot be completed.", "type": "boolean" }, "failureRedirectUrl": { "description": "Redirect URL when the transaction fails. The orderId will be appended as a query parameter.", "type": "string" }, "tokenisationIfPossible": { "description": "Attempts tokenization when supported, without failing the flow if tokenization is unavailable.", "type": "boolean" }, "subscription": { "description": "Marks this as a subscription/recurring-capable order.", "type": "boolean" }, "payButtonType": { "description": "UI pay button label/type used on the payment page.\n\nValues:\n- `ADD_MONEY`: Add money to balance\n- `BOOK`: Book a service\n- `CHECKOUT`: Standard checkout\n- `CONTINUE`: Continue flow\n- `CONTRIBUTE`: Contribute to a cause\n- `DONATE`: Donate money\n- `ORDER`: Place an order\n- `PAY`: Pay now\n- `RENT`: Rent item/service\n- `SUPPORT`: Support a creator/cause\n- `TIP`: Leave a tip\n- `TOP_UP`: Top up balance", "type": "string", "enum": [ "ADD_MONEY", "BOOK", "CHECKOUT", "CONTINUE", "CONTRIBUTE", "DONATE", "ORDER", "PAY", "RENT", "SUPPORT", "TIP", "TOP_UP" ] }, "generateShortLink": { "description": "If true, generates a short URL for the payment page. Default is false.", "type": "boolean" }, "generateOnlineLinkWith": { "description": "The terminal identifier used to generate the online payment link.", "type": "string" }, "recurring": { "description": "Encompasses all controls related to recurring payments.", "type": "object", "properties": { "subscriptionAmountType": { "description": "Determines the type of the subscription amount for order.\n\nValues:\n- `fixed`: A fixed amount is collected.\n- `variable`: A variable amount is collected.", "type": "string", "enum": [ "fixed", "variable" ] }, "maxAmount": { "description": "Maximum amount for the order in the lowest currency unit (only valid for variable subscription amounts).", "type": "number" }, "frequency": { "description": "Frequency of the recurring collection. 'daily' | 'twiceWeekly' | 'weekly' | 'tenDays' | 'fortNightly' | 'monthly' | 'everyTwoMonths' | 'trimester' | 'quarterly' | 'twiceYearly' | 'annually' | 'unscheduled'. Conditionally required: see the endpoint notes.", "type": "string" }, "numberOfPayments": { "description": "Total number of payments expected for this order.", "type": "number" }, "uniqueReference": { "description": "A unique reference for the recurring order.", "type": "string" }, "validation": { "description": "The validation type for the recurring order, possible values are 'validated' | 'notValidated'. Conditionally required: see the endpoint notes.", "type": "string" } }, "required": [ "frequency" ] }, "currency": { "description": "Currency as a numeric ISO 4217 code (string), e.g., '752' for SEK.", "type": "string" }, "selfCardCharging": { "description": "Allow the customer to self-charge their card.", "type": "boolean" } } }, "taxHandlingStrategy": { "description": "Tax calculation strategy", "type": "object", "properties": { "treatAmountAsTaxExclusive": { "description": "Prices exclude tax", "type": "boolean" }, "taxTreatmentStrategy": { "description": "Rounding strategy configuration", "type": "string" } } } } } }, "required": [ "terminal$id", "orderLines" ] }, "example": { "terminal$id": "8386af3b0f71b80b04", "orderLines": [ { "id": "TERM123", "name": "Nike Shoes", "quantity": 1, "amount": { "regular": 500, "campaign": 0, "shipping": 0, "total": 500, "currency": "752", "tax": [ { "amount": 20, "percentage": 20, "type": "VAT" } ] } } ], "controlFunctions": { "initiatePaymentsOptions": { "paymentMethod": "CARD" } } } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "orderId": { "description": "Order ID of the order created.", "type": "string" }, "paymentId": { "description": "A payment ID assigned to each payment instance. Ensure that this ID is stored securely and tied to an identifiable entity until payment completion.", "type": "string" }, "interAppJWT": { "description": "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.", "type": "string" }, "nonce": { "description": "The authorization key required to process online payments through a SelfHostedPage terminal.", "type": "string" }, "paymentPageLink": { "description": "This is the payment page link where payments can be made, applicable to both PaymentPage and iFrame terminals.", "type": "string" }, "shortLinkUrl": { "description": "Short link to the payment page URL when generateShortLink is set to true.", "type": "string" }, "invoiceDetails": { "description": "Invoice details for the payment when applicable.", "type": "object", "properties": { "invoiceId": { "description": "Unique identifier for the invoice.", "type": "number" }, "invoicePdfUrl": { "description": "URL to download the invoice PDF.", "type": "string" }, "iban": { "description": "International Bank Account Number for the invoice.", "type": "string" }, "accountHolderName": { "description": "Name of the account holder for the invoice.", "type": "string" }, "bic": { "description": "Bank Identifier Code for the invoice.", "type": "string" }, "bankgiro": { "description": "Bankgiro number for the invoice.", "type": "string" }, "ocr": { "description": "OCR reference number for the invoice payment.", "type": "string" } }, "additionalProperties": true }, "paymentUrl": { "description": "Direct URL for payment processing.", "type": "string" }, "qr": { "description": "QR code data for payment.", "type": "string" }, "qrData": { "description": "Raw QR code data for payment processing.", "type": "string" }, "qrVisibleFor": { "description": "Duration for which the QR code remains visible.", "type": "string" }, "qrLink": { "description": "Link to the QR code for payment.", "type": "string" }, "klarnaClientToken": { "description": "Client token for Klarna payment processing.", "type": "string" }, "paymentToken": { "description": "Token for payment processing.", "type": "string" }, "sveaInitiationParams": { "description": "Initiation parameters for Svea payment processing.", "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "orderId": "8381a26eae26f0900b", "paymentId": "8381a26eae26f2af06", "interAppJWT": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvaWQiOiI4MzgxYTI2ZWFlMjZmMDkwMGIiLCJ0aWQiOiI4MzNjZWI4MjQwNGU3MDBiMDQiLCJwaWQiOiI4MzgxYTI2ZWFlMjZmMmFmMDYiLCJwbSI6IkNBU0giLCJhIjoxMDAwMCwiYyI6Ijc1MiIsImNvbnRyb2xGdW5jdGlvbnNFbmNvZGVyIjoiMCIsImlzc3VlZEJ5Ijoic2IucHMiLCJpYXQiOjE3NTg2NDk5NDk3MzN9.3pp94sCLJ_AnfkTmgcEhqv2HnGkxwXD3-ckP-TQGA94" }, "message": "Order created successfully" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/orders/{orderId}": { "put": { "operationId": "updateOrder", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Orders API" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Identifier for the order this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terminal$id": { "description": "ID of the checkout or payment terminal", "type": "string" }, "referenceId": { "description": "External reference ID for the order", "type": "string" }, "comments": { "description": "Additional comments or notes for the order", "type": "string" }, "customer": { "description": "Customer details for the order", "type": "object", "properties": { "customerId": { "description": "Unique identifier for the customer", "type": "string" }, "person": { "description": "Personal information of the customer", "type": "object", "properties": { "id": { "description": "Person identifier.", "type": "string" }, "name": { "description": "Full name of the customer", "type": "object", "properties": { "firstName": { "description": "First name of the customer", "type": "string" }, "middleName": { "description": "Middle name of the customer", "type": "string" }, "lastName": { "description": "Last name of the customer", "type": "string" } } }, "email": { "description": "Email address of the customer", "type": "string" }, "phoneNumber": { "description": "Phone number of the customer", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ] }, "birthDate": { "description": "Date of birth in YYYY-MM-DD format", "type": "string" }, "personalNumber": { "description": "Personal identification number", "type": "string" }, "coordinationNumber": { "description": "Coordination number", "type": "string" }, "countryResidence": { "description": "Country of residence of the customer", "type": "string" }, "gdNumber": { "description": "Government-issued identification number of the customer", "type": "string" } } }, "company": { "description": "Company information for corporate purchases", "type": "object", "properties": { "id": { "description": "Company identifier.", "type": "string" }, "vatId": { "description": "VAT ID of the company", "type": "string" }, "poDetails": { "description": "Purchase order details for the company", "type": "string" }, "companyName": { "description": "Company display name.", "type": "string" }, "registrationNumber": { "description": "Company registration number.", "type": "string" }, "gln": { "description": "GLN of the buyer's e-invoice department, used to route e-invoices.", "type": "string" } } } } }, "billing": { "description": "Billing contact and address", "type": "object", "properties": { "name": { "description": "Full name of the billing contact", "type": "object", "properties": { "firstName": { "description": "First name of the billing contact", "type": "string" }, "middleName": { "description": "Middle name of the billing contact", "type": "string" }, "lastName": { "description": "Last name of the billing contact", "type": "string" } } }, "email": { "description": "Billing email", "type": "string" }, "phoneNumber": { "description": "Phone number for billing", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ] }, "address": { "description": "Billing address", "type": "object", "properties": { "careOf": { "description": "Care of / attention", "type": "string" }, "addressLine1": { "description": "Primary address line", "type": "string" }, "addressLine2": { "description": "Address line 2", "type": "string" }, "addressLine3": { "description": "Address line 3", "type": "string" }, "city": { "description": "City name", "type": "string" }, "postalCode": { "description": "Postal/ZIP code", "type": "string" }, "countryCode": { "description": "Country code (ISO 3166-1 alpha-2)", "type": "string" } }, "required": [ "addressLine1", "city", "postalCode", "countryCode" ] } } }, "shipping": { "description": "Shipping contact and address", "type": "object", "properties": { "name": { "description": "Full name of the shipping contact", "type": "object", "properties": { "firstName": { "description": "First name of the shipping contact", "type": "string" }, "middleName": { "description": "Middle name of the shipping contact", "type": "string" }, "lastName": { "description": "Last name of the shipping contact", "type": "string" } } }, "email": { "description": "Recipient email", "type": "string" }, "phoneNumber": { "description": "Phone number for shipping", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ] }, "address": { "description": "Shipping address", "type": "object", "properties": { "careOf": { "description": "Care of / attention", "type": "string" }, "addressLine1": { "description": "Primary address line", "type": "string" }, "addressLine2": { "description": "Address line 2", "type": "string" }, "addressLine3": { "description": "Address line 3", "type": "string" }, "city": { "description": "City name", "type": "string" }, "postalCode": { "description": "Postal/ZIP code", "type": "string" }, "countryCode": { "description": "Country code (ISO 3166-1 alpha-2)", "type": "string" } }, "required": [ "addressLine1", "city", "postalCode", "countryCode" ] } } }, "orderLines": { "description": "List of items in the order", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Order line identifier", "type": "string" }, "externalItemId": { "description": "External order line identifier", "type": "string" }, "name": { "description": "Product name", "type": "string" }, "categoryId": { "description": "Product category identifier", "type": "string" }, "description": { "description": "Line item description", "type": "string" }, "quantity": { "description": "Quantity ordered. A negative value indicates a refund.", "type": "number" }, "amount": { "description": "Pricing details for the line item", "type": "object", "properties": { "regular": { "description": "Regular price amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "campaign": { "description": "Campaign/discount amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "shipping": { "description": "Shipping amount for this item in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "total": { "description": "Total line amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "currency": { "description": "Currency (numeric ISO 4217 as string)", "type": "string" }, "tax": { "description": "Tax breakdown", "type": "array", "items": { "type": "object", "properties": { "amount": { "description": "Tax amount", "type": "number" }, "percentage": { "description": "Tax rate percentage", "type": "number" }, "type": { "description": "Tax type (e.g., VAT)", "type": "string" } }, "required": [ "amount", "percentage", "type" ] } } }, "required": [ "regular", "total", "currency" ] }, "unit": { "description": "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'.", "type": "string" }, "gtin": { "description": "Global Trade Item Number", "type": "string" }, "imageUrl": { "description": "Image URL for the product", "type": "string" }, "brand": { "description": "Brand name", "type": "string" }, "purchaseOrderId": { "description": "Mandatory purchase order identifier if it's a return item, i.e. a negative quantity. Conditionally required: see the endpoint notes.", "type": "string" }, "promotionApplied": { "description": "Product promotional campaign identifier.", "type": "string" }, "metadata": { "description": "Arbitrary metadata for the line", "type": "object", "additionalProperties": true }, "storeId": { "description": "Store identifier", "type": "string" }, "purchasePaymentId": { "description": "Purchase payment identifier associated with the order line", "type": "string" } }, "required": [ "id", "name", "quantity", "amount" ] } }, "totalOrderAmount": { "description": "Total amount details of the order.", "type": "object", "properties": { "regular": { "description": "Total regular order amount in the smallest currency unit (e.g., 10 SEK is represented as 1000)", "type": "number" }, "campaign": { "description": "Total campaign or discount amount applied to the order in the smallest currency unit", "type": "number" }, "total": { "description": "Overall payable order amount in the smallest currency unit (regular - campaign + shipping + tax)", "type": "number" }, "currency": { "description": "Order currency represented as a numeric ISO 4217 code (e.g., '752' for SEK)", "type": "string" }, "tax": { "description": "Order-level tax breakdown across applied tax categories", "type": "array", "items": { "type": "object", "properties": { "amount": { "description": "Total tax amount for the order in the smallest currency unit", "type": "number" }, "percentage": { "description": "Applied tax rate percentage", "type": "number" }, "type": { "description": "Type of tax applied (e.g., VAT, GST)", "type": "string" } }, "required": [ "amount", "percentage", "type" ] } } }, "required": [ "regular", "total", "currency" ] }, "date": { "description": "Order date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00). If not specified, the current date is used.", "type": "string" }, "metadata": { "description": "Arbitrary key-value style metadata items", "type": "object", "additionalProperties": true }, "adjustments": { "description": "Order-level adjustments", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Adjustment type", "type": "string" }, "value": { "description": "Adjustment value", "type": "number" }, "metadata": { "description": "Arbitrary key-value style metadata items.", "type": "object", "additionalProperties": true } }, "required": [ "type", "value" ] } }, "controlFunctions": { "description": "Advanced order/payment control configuration", "type": "object", "properties": { "cancelPreviousPendingOrder": { "description": "Set as true when you want to cancel all previous pending orders", "type": "boolean" }, "orderLineLevelCalculation": { "description": "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.", "type": "boolean" }, "serviceProviders": { "description": "External service providers participating in the transaction", "type": "array", "items": { "type": "object", "properties": { "serviceProviderId": { "description": "Service provider identifier", "type": "string" }, "amount": { "description": "Share/fee configuration", "type": "object", "properties": { "percentage": { "description": "Percentage share", "type": "number" }, "fixed": { "description": "Fixed share amount", "type": "number" }, "adjustmentTypes": { "description": "Allowed adjustment types for this provider as an array of string.", "type": "array", "items": {} } } } }, "required": [ "serviceProviderId" ] } }, "initiatePaymentsOptions": { "description": "Parameters for initiating payment", "type": "object", "properties": { "paymentMethod": { "description": "Payment method to use", "type": "string" }, "amount": { "description": "Amount to charge in smallest currency units.", "type": "number" }, "paymentMethodParams": { "description": "Method-specific parameters", "type": "object", "properties": { "tokenId": { "description": "Saved payment token ID", "type": "string" }, "swishMode": { "description": "Swish mode (e.g., ECOM)", "type": "string" }, "payeePhoneNumber": { "description": "Mandatory phone number for SWISH payments. Conditionally required: see the endpoint notes.", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ] }, "giftCard": { "description": "Gift card payment details Not live yet.", "type": "object", "properties": { "giftCardId": { "description": "Gift card identifier", "type": "string" }, "giftCardRedemptionMode": { "description": "Redemption mode (e.g., WALLET)", "type": "string" } } }, "invoice": { "description": "Invoice payment configuration", "type": "object", "properties": { "invoiceDistribution": { "description": "Distribution channel (e.g., EMAIL)", "type": "string" }, "contractReference": { "description": "Contract reference identifier", "type": "string" }, "debtCollectionEnabled": { "description": "Enable debt collection", "type": "boolean" }, "dueDate": { "description": "Due date or relative duration (e.g., 30d)", "type": "string" }, "invoicePaymentMethods": { "description": "Allowed payment methods for invoice", "type": "array", "items": {} }, "reminder": { "description": "Enable reminders", "type": "boolean" } } } } }, "serialSplitPaymentsMode": { "description": "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.", "type": "array", "items": {} }, "refundProcessingParams": { "description": "Parameters for processing refunds", "type": "object", "properties": { "purchasePaymentId": { "description": "Original purchase payment ID", "type": "string" }, "refundReason": { "description": "Reason for refund (as provided)", "type": "string" }, "otherReason": { "description": "Other reason details", "type": "string" } } } } }, "tipsMode": { "description": "Tips configuration (STANDARD | ROUNDUP | NONE)", "type": "string" }, "cardStatementDescriptor": { "description": "Statement descriptor text", "type": "string" }, "includeAdjustmentsForRefund": { "description": "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.", "type": "boolean" }, "lockToPaymentMethods": { "description": "An array of payment methods locked in. All available payment methods are supported. For example, ['CARD', 'KLARNA']", "type": "array", "items": {} }, "tapBeforeAmount": { "description": "If true, requires the customer to tap the card before the amount is entered, ensuring amount confirmation prior to payment.", "type": "boolean" }, "delayCapture": { "description": "Allows capture at a later time.", "type": "boolean" }, "delayPayout": { "description": "Delays the final amount paid out to the merchant after all deductions, in the format numbers + 'm' | 'h' | 'd' .", "type": "string" }, "fulfillmentDate": { "description": "Planned fulfillment date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00)", "type": "string" }, "callBackUrl": { "description": "This is a dynamic callback URL that is used to perform webhook calls in relation to the order and payment.", "type": "string" }, "throwErrorIfTerminalInactiveFor": { "description": "Threshold in ms if the respective terminal has been inactive for the given time frame.", "type": "number" }, "clearingCutOff": { "description": "Clearing cutoff configuration in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00)", "type": "string" }, "currency": { "description": "Order currency override", "type": "string" }, "authMode": { "description": "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.", "type": "string" }, "receipt": { "description": "Receipt handling options", "type": "object", "properties": { "autoPrintReceipt": { "description": "Auto-print setting", "type": "boolean" }, "autoSendReceiptIfEmailAvailable": { "description": "Auto-send if email present", "type": "boolean" }, "sequenceNumber": { "description": "Receipt sequence number", "type": "string" }, "cashRegisterName": { "description": "Cash register name", "type": "string" }, "controlUnitSerialNumber": { "description": "Control unit serial number", "type": "string" }, "receiptRedirectURL": { "description": "Receipt redirect URL", "type": "string" }, "cashierName": { "description": "Cashier name", "type": "string" }, "promotionsToDisplay": { "description": "Promotions to display on receipt", "type": "array", "items": {} } } }, "surcharges": { "description": "A record of additional fees or charges applied to the transaction, keyed by unique identifiers. Not live yet.", "type": "object", "properties": { "domestic": { "description": "Surcharges for domestic transactions (same country).", "type": "object", "properties": { "consumer": { "description": "Surcharges for consumer cards in domestic transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for consumer debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units (e.g., 100 = 1.00).", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge (e.g., 1.5 = 1.5%).", "type": "number" } } }, "credit": { "description": "Surcharge definitions for consumer credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } } } }, "corporate": { "description": "Surcharges for corporate cards in domestic transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for corporate debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } }, "credit": { "description": "Surcharge definitions for corporate credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } } } } } }, "international": { "description": "Surcharges for international transactions (outside the merchant’s country).", "type": "object", "properties": { "consumer": { "description": "Surcharges for consumer cards in international transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for consumer debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } }, "credit": { "description": "Surcharge definitions for consumer credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } } } }, "corporate": { "description": "Surcharges for corporate cards in international transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for corporate debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } }, "credit": { "description": "Surcharge definitions for corporate credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } } } } } }, "eea": { "description": "Surcharges for EEA (European Economic Area) transactions.", "type": "object", "properties": { "consumer": { "description": "Surcharges for consumer cards in EEA transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for consumer debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } }, "credit": { "description": "Surcharge definitions for consumer credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } } } }, "corporate": { "description": "Surcharges for corporate cards in EEA transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for corporate debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } }, "credit": { "description": "Surcharge definitions for corporate credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } } } } } } } } }, "readTags": { "description": "This field denotes the type of NFC reading allowed on the terminal for the order. The possible values are,\n\nValues:\n- `NONE`: This value indicates that no tags are allowed for reading.\n- `SINGLE`: Single read allowed for the order.\n- `MULTIPLE_EDITABLE`: Multiple tags can be read and edited.\n- `MULTIPLE_NONEDITABLE`: Multiple tags can be read, but cannot be modified.", "type": "string", "enum": [ "NONE", "SINGLE", "MULTIPLE_EDITABLE", "MULTIPLE_NONEDITABLE" ] }, "ecrEnabled": { "description": "Whether ECR (electronic cash register) mode is enabled.", "type": "boolean" }, "online": { "description": "Online payment/link settings", "type": "object", "properties": { "enforceTokenization": { "description": "Denotes whether the card is tokenised for a future transaction or not.", "type": "boolean" }, "paymentPageValidFor": { "description": "Default validity of the payment page in format , where unit is 'm' | 'h' | 'd' (e.g., '15m', '2h', '3d').", "type": "string" }, "enforce3DSecure": { "description": "Force 3-D Secure authentication when available.", "type": "boolean" }, "relaxed3ds": { "description": "Allow relaxed 3-D Secure handling.", "type": "boolean" }, "addressRequirements": { "description": "Require an address on the payment page.", "type": "boolean" }, "redirectUrl": { "description": "Redirect URL after the online transaction completes successfully. The orderId will be appended as a query parameter.", "type": "string" }, "accountNameVerification": { "description": "Account-name verification mode applied during the payment.", "type": "string" }, "errorIfTokenizationFails": { "description": "If true, fail the flow when card tokenization cannot be completed.", "type": "boolean" }, "failureRedirectUrl": { "description": "Redirect URL when the transaction fails. The orderId will be appended as a query parameter.", "type": "string" }, "tokenisationIfPossible": { "description": "Attempts tokenization when supported, without failing the flow if tokenization is unavailable.", "type": "boolean" }, "subscription": { "description": "Marks this as a subscription/recurring-capable order.", "type": "boolean" }, "payButtonType": { "description": "UI pay button label/type used on the payment page.\n\nValues:\n- `ADD_MONEY`: Add money to balance\n- `BOOK`: Book a service\n- `CHECKOUT`: Standard checkout\n- `CONTINUE`: Continue flow\n- `CONTRIBUTE`: Contribute to a cause\n- `DONATE`: Donate money\n- `ORDER`: Place an order\n- `PAY`: Pay now\n- `RENT`: Rent item/service\n- `SUPPORT`: Support a creator/cause\n- `TIP`: Leave a tip\n- `TOP_UP`: Top up balance", "type": "string", "enum": [ "ADD_MONEY", "BOOK", "CHECKOUT", "CONTINUE", "CONTRIBUTE", "DONATE", "ORDER", "PAY", "RENT", "SUPPORT", "TIP", "TOP_UP" ] }, "generateShortLink": { "description": "If true, generates a short URL for the payment page. Default is false.", "type": "boolean" }, "generateOnlineLinkWith": { "description": "The terminal identifier used to generate the online payment link.", "type": "string" }, "recurring": { "description": "Encompasses all controls related to recurring payments.", "type": "object", "properties": { "subscriptionAmountType": { "description": "Determines the type of the subscription amount for order.\n\nValues:\n- `fixed`: A fixed amount is collected.\n- `variable`: A variable amount is collected.", "type": "string", "enum": [ "fixed", "variable" ] }, "maxAmount": { "description": "Maximum amount for the order in the lowest currency unit (only valid for variable subscription amounts).", "type": "number" }, "frequency": { "description": "Frequency of the recurring collection. 'daily' | 'twiceWeekly' | 'weekly' | 'tenDays' | 'fortNightly' | 'monthly' | 'everyTwoMonths' | 'trimester' | 'quarterly' | 'twiceYearly' | 'annually' | 'unscheduled'. Conditionally required: see the endpoint notes.", "type": "string" }, "numberOfPayments": { "description": "Total number of payments expected for this order.", "type": "number" }, "uniqueReference": { "description": "A unique reference for the recurring order.", "type": "string" }, "validation": { "description": "The validation type for the recurring order, possible values are 'validated' | 'notValidated'. Conditionally required: see the endpoint notes.", "type": "string" } }, "required": [ "frequency" ] }, "currency": { "description": "Currency as a numeric ISO 4217 code (string), e.g., '752' for SEK.", "type": "string" }, "selfCardCharging": { "description": "Allow the customer to self-charge their card.", "type": "boolean" } } }, "taxHandlingStrategy": { "description": "Tax calculation strategy", "type": "object", "properties": { "treatAmountAsTaxExclusive": { "description": "Prices exclude tax", "type": "boolean" }, "taxTreatmentStrategy": { "description": "Rounding strategy configuration", "type": "string" } } } } } }, "required": [ "terminal$id", "orderLines" ] }, "example": { "terminal$id": "8386af3b0f71b80b04", "orderLines": [ { "id": "TERM123", "name": "Nike Shoes", "quantity": 1, "amount": { "regular": 500, "campaign": 0, "shipping": 0, "total": 500, "currency": "752", "tax": [ { "amount": 20, "percentage": 20, "type": "VAT" } ] } } ], "controlFunctions": { "initiatePaymentsOptions": { "paymentMethod": "CARD" } } } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Order updated successfully" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "get": { "operationId": "fetchOrderById", "summary": "Fetch Order By Id", "description": "Retrieves the details of an existing order using its Order Id.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Orders API" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Identifier for the order this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Contains the respective order details.", "type": "object", "properties": { "terminal$id": { "description": "ID of the checkout or payment terminal", "type": "string" }, "referenceId": { "description": "External reference ID for the order", "type": "string" }, "comments": { "description": "Additional comments or notes for the order", "type": "string" }, "customer": { "description": "Customer details for the order", "type": "object", "properties": { "customerId": { "description": "Unique identifier for the customer", "type": "string" }, "person": { "description": "Personal information of the customer", "type": "object", "properties": { "id": { "description": "Person identifier.", "type": "string" }, "name": { "description": "Full name of the customer", "type": "object", "properties": { "firstName": { "description": "First name of the customer", "type": "string" }, "middleName": { "description": "Middle name of the customer", "type": "string" }, "lastName": { "description": "Last name of the customer", "type": "string" } }, "additionalProperties": true }, "email": { "description": "Email address of the customer", "type": "string" }, "phoneNumber": { "description": "Phone number of the customer", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ], "additionalProperties": true }, "birthDate": { "description": "Date of birth in YYYY-MM-DD format", "type": "string" }, "personalNumber": { "description": "Personal identification number", "type": "string" }, "coordinationNumber": { "description": "Coordination number", "type": "string" }, "countryResidence": { "description": "Country of residence of the customer", "type": "string" }, "gdNumber": { "description": "Government-issued identification number of the customer", "type": "string" } }, "additionalProperties": true }, "company": { "description": "Company information for corporate purchases", "type": "object", "properties": { "id": { "description": "Company identifier.", "type": "string" }, "vatId": { "description": "VAT ID of the company", "type": "string" }, "poDetails": { "description": "Purchase order details for the company", "type": "string" }, "companyName": { "description": "Company display name.", "type": "string" }, "registrationNumber": { "description": "Company registration number.", "type": "string" }, "gln": { "description": "GLN of the buyer's e-invoice department, used to route e-invoices.", "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "billing": { "description": "Billing contact and address", "type": "object", "properties": { "name": { "description": "Full name of the billing contact", "type": "object", "properties": { "firstName": { "description": "First name of the billing contact", "type": "string" }, "middleName": { "description": "Middle name of the billing contact", "type": "string" }, "lastName": { "description": "Last name of the billing contact", "type": "string" } }, "additionalProperties": true }, "email": { "description": "Billing email", "type": "string" }, "phoneNumber": { "description": "Phone number for billing", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ], "additionalProperties": true }, "address": { "description": "Billing address", "type": "object", "properties": { "careOf": { "description": "Care of / attention", "type": "string" }, "addressLine1": { "description": "Primary address line", "type": "string" }, "addressLine2": { "description": "Address line 2", "type": "string" }, "addressLine3": { "description": "Address line 3", "type": "string" }, "city": { "description": "City name", "type": "string" }, "postalCode": { "description": "Postal/ZIP code", "type": "string" }, "countryCode": { "description": "Country code (ISO 3166-1 alpha-2)", "type": "string" } }, "required": [ "addressLine1", "city", "postalCode", "countryCode" ], "additionalProperties": true } }, "additionalProperties": true }, "shipping": { "description": "Shipping contact and address", "type": "object", "properties": { "name": { "description": "Full name of the shipping contact", "type": "object", "properties": { "firstName": { "description": "First name of the shipping contact", "type": "string" }, "middleName": { "description": "Middle name of the shipping contact", "type": "string" }, "lastName": { "description": "Last name of the shipping contact", "type": "string" } }, "additionalProperties": true }, "email": { "description": "Recipient email", "type": "string" }, "phoneNumber": { "description": "Phone number for shipping", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ], "additionalProperties": true }, "address": { "description": "Shipping address", "type": "object", "properties": { "careOf": { "description": "Care of / attention", "type": "string" }, "addressLine1": { "description": "Primary address line", "type": "string" }, "addressLine2": { "description": "Address line 2", "type": "string" }, "addressLine3": { "description": "Address line 3", "type": "string" }, "city": { "description": "City name", "type": "string" }, "postalCode": { "description": "Postal/ZIP code", "type": "string" }, "countryCode": { "description": "Country code (ISO 3166-1 alpha-2)", "type": "string" } }, "required": [ "addressLine1", "city", "postalCode", "countryCode" ], "additionalProperties": true } }, "additionalProperties": true }, "orderLines": { "description": "List of items in the order", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Order line identifier", "type": "string" }, "externalItemId": { "description": "External order line identifier", "type": "string" }, "name": { "description": "Product name", "type": "string" }, "categoryId": { "description": "Product category identifier", "type": "string" }, "description": { "description": "Line item description", "type": "string" }, "quantity": { "description": "Quantity ordered. A negative value indicates a refund.", "type": "number" }, "amount": { "description": "Pricing details for the line item", "type": "object", "properties": { "regular": { "description": "Regular price amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "campaign": { "description": "Campaign/discount amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "shipping": { "description": "Shipping amount for this item in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "total": { "description": "Total line amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "currency": { "description": "Currency (numeric ISO 4217 as string)", "type": "string" }, "tax": { "description": "Tax breakdown", "type": "array", "items": { "type": "object", "properties": { "amount": { "description": "Tax amount", "type": "number" }, "percentage": { "description": "Tax rate percentage", "type": "number" }, "type": { "description": "Tax type (e.g., VAT)", "type": "string" } }, "required": [ "amount", "percentage", "type" ], "additionalProperties": true } } }, "required": [ "regular", "total", "currency" ], "additionalProperties": true }, "unit": { "description": "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'.", "type": "string" }, "gtin": { "description": "Global Trade Item Number", "type": "string" }, "imageUrl": { "description": "Image URL for the product", "type": "string" }, "brand": { "description": "Brand name", "type": "string" }, "purchaseOrderId": { "description": "Mandatory purchase order identifier if it's a return item. Conditionally required: see the endpoint notes.", "type": "string" }, "purchasePaymentId": { "description": "Purchase payment identifier associated with the order line.", "type": "string" }, "promotionApplied": { "description": "Product promotional campaign identifier.", "type": "string" }, "metadata": { "description": "Arbitrary metadata for the line", "type": "object", "additionalProperties": true }, "storeId": { "description": "Store identifier", "type": "string" } }, "required": [ "id", "name", "quantity" ], "additionalProperties": true } }, "totalOrderAmount": { "description": "Total amount details of the order.", "type": "object", "properties": { "regular": { "description": "Total regular order amount in the smallest currency unit (e.g., 10 SEK is represented as 1000)", "type": "number" }, "campaign": { "description": "Total campaign or discount amount applied to the order in the smallest currency unit", "type": "number" }, "total": { "description": "Overall payable order amount in the smallest currency unit (regular - campaign + shipping + tax)", "type": "number" }, "currency": { "description": "Order currency represented as a numeric ISO 4217 code (e.g., '752' for SEK)", "type": "string" }, "tax": { "description": "Order-level tax breakdown across applied tax categories", "type": "array", "items": { "type": "object", "properties": { "amount": { "description": "Total tax amount for the order in the smallest currency unit", "type": "number" }, "percentage": { "description": "Applied tax rate percentage", "type": "number" }, "type": { "description": "Type of tax applied (e.g., VAT, GST)", "type": "string" } }, "required": [ "amount", "percentage", "type" ], "additionalProperties": true } } }, "required": [ "regular", "total", "currency" ], "additionalProperties": true }, "date": { "description": "Order date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00). If not specified, the current date is used.", "type": "string" }, "metadata": { "description": "Arbitrary key-value style metadata items", "type": "object", "additionalProperties": true }, "adjustments": { "description": "Order-level adjustments", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Adjustment type", "type": "string" }, "value": { "description": "Adjustment value", "type": "number" }, "metadata": { "description": "Arbitrary key-value style metadata items.", "type": "object", "additionalProperties": true }, "adjustmentId": { "description": "Unique identifier of the adjustment.", "type": "string" } }, "required": [ "type", "value" ], "additionalProperties": true } }, "controlFunctions": { "description": "Advanced order/payment control configuration", "type": "object", "properties": { "cancelPreviousPendingOrder": { "description": "Set as true when you want to cancel all previous pending orders", "type": "boolean" }, "orderLineLevelCalculation": { "description": "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.", "type": "boolean" }, "serviceProviders": { "description": "External service providers participating in the transaction", "type": "array", "items": { "type": "object", "properties": { "serviceProviderId": { "description": "Service provider identifier", "type": "string" }, "amount": { "description": "Share/fee configuration", "type": "object", "properties": { "percentage": { "description": "Percentage share", "type": "number" }, "fixed": { "description": "Fixed share amount", "type": "number" }, "adjustmentTypes": { "description": "Allowed adjustment types for this provider as an array of string.", "type": "array", "items": {} } }, "additionalProperties": true } }, "required": [ "serviceProviderId" ], "additionalProperties": true } }, "initiatePaymentsOptions": { "description": "Parameters for initiating payment", "type": "object", "properties": { "paymentMethod": { "description": "Payment method to use", "type": "string" }, "amount": { "description": "Amount to charge in smallest currency units.", "type": "number" }, "paymentMethodParams": { "description": "Method-specific parameters", "type": "object", "properties": { "tokenId": { "description": "Saved payment token ID", "type": "string" }, "swishMode": { "description": "Swish mode (e.g., ECOM)", "type": "string" }, "giftCard": { "description": "Gift card payment details Not live yet.", "type": "object", "properties": { "giftCardId": { "description": "Gift card identifier", "type": "string" }, "giftCardRedemptionMode": { "description": "Redemption mode (e.g., WALLET)", "type": "string" } }, "additionalProperties": true }, "invoice": { "description": "Invoice payment configuration", "type": "object", "properties": { "invoiceDistribution": { "description": "Distribution channel (e.g., EMAIL)", "type": "string" }, "contractReference": { "description": "Contract reference identifier", "type": "string" }, "debtCollectionEnabled": { "description": "Enable debt collection", "type": "boolean" }, "dueDate": { "description": "Due date or relative duration (e.g., 30d)", "type": "string" }, "invoicePaymentMethods": { "description": "Allowed payment methods for invoice", "type": "array", "items": {} }, "reminder": { "description": "Enable reminders", "type": "boolean" } }, "additionalProperties": true } }, "additionalProperties": true }, "serialSplitPaymentsMode": { "description": "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.", "type": "array", "items": {} }, "refundProcessingParams": { "description": "Parameters for processing refunds", "type": "object", "properties": { "purchasePaymentId": { "description": "Original purchase payment ID", "type": "string" }, "refundReason": { "description": "Reason for refund (as provided)", "type": "string" }, "otherReason": { "description": "Other reason details", "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "tipsMode": { "description": "Tips configuration (STANDARD | ROUNDUP | NONE)", "type": "string" }, "cardStatementDescriptor": { "description": "Statement descriptor text", "type": "string" }, "includeAdjustmentsForRefund": { "description": "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.", "type": "boolean" }, "lockToPaymentMethods": { "description": "An array of payment methods locked in. All available payment methods are supported. For example, ['CARD', 'KLARNA']", "type": "array", "items": {} }, "tapBeforeAmount": { "description": "If true, requires the customer to tap the card before the amount is entered, ensuring amount confirmation prior to payment.", "type": "boolean" }, "delayCapture": { "description": "Allows capture at a later time.", "type": "boolean" }, "delayPayout": { "description": "Delays the final amount paid out to the merchant after all deductions, in the format numbers + 'm' | 'h' | 'd' .", "type": "string" }, "fulfillmentDate": { "description": "Planned fulfillment date in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00)", "type": "string" }, "callBackUrl": { "description": "This is a dynamic callback URL that is used to perform webhook calls in relation to the order and payment.", "type": "string" }, "throwErrorIfTerminalInactiveFor": { "description": "Threshold in ms if the respective terminal has been inactive for the given time frame.", "type": "number" }, "clearingCutOff": { "description": "Clearing cutoff configuration in ISO 8601 format (e.g., 2018-04-04T10:20:30+02:00)", "type": "string" }, "currency": { "description": "Order currency override", "type": "string" }, "authMode": { "description": "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.", "type": "string" }, "receipt": { "description": "Receipt handling options", "type": "object", "properties": { "autoPrintReceipt": { "description": "Auto-print setting", "type": "boolean" }, "autoSendReceiptIfEmailAvailable": { "description": "Auto-send if email present", "type": "boolean" }, "sequenceNumber": { "description": "Receipt sequence number", "type": "string" }, "cashRegisterName": { "description": "Cash register name", "type": "string" }, "controlUnitSerialNumber": { "description": "Control unit serial number", "type": "string" }, "receiptRedirectURL": { "description": "Receipt redirect URL", "type": "string" }, "cashierName": { "description": "Cashier name", "type": "string" }, "promotionsToDisplay": { "description": "Promotions to display on receipt", "type": "array", "items": {} } }, "additionalProperties": true }, "surcharges": { "description": "A record of additional fees or charges applied to the transaction, keyed by unique identifiers. Not live yet.", "type": "object", "properties": { "domestic": { "description": "Surcharges for domestic transactions (same country).", "type": "object", "properties": { "consumer": { "description": "Surcharges for consumer cards in domestic transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for consumer debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units (e.g., 100 = 1.00).", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge (e.g., 1.5 = 1.5%).", "type": "number" } }, "additionalProperties": true }, "credit": { "description": "Surcharge definitions for consumer credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true }, "corporate": { "description": "Surcharges for corporate cards in domestic transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for corporate debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } }, "additionalProperties": true }, "credit": { "description": "Surcharge definitions for corporate credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "international": { "description": "Surcharges for international transactions (outside the merchant’s country).", "type": "object", "properties": { "consumer": { "description": "Surcharges for consumer cards in international transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for consumer debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } }, "additionalProperties": true }, "credit": { "description": "Surcharge definitions for consumer credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true }, "corporate": { "description": "Surcharges for corporate cards in international transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for corporate debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } }, "additionalProperties": true }, "credit": { "description": "Surcharge definitions for corporate credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "eea": { "description": "Surcharges for EEA (European Economic Area) transactions.", "type": "object", "properties": { "consumer": { "description": "Surcharges for consumer cards in EEA transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for consumer debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } }, "additionalProperties": true }, "credit": { "description": "Surcharge definitions for consumer credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true }, "corporate": { "description": "Surcharges for corporate cards in EEA transactions.", "type": "object", "properties": { "debit": { "description": "Surcharge definitions for corporate debit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } }, "additionalProperties": true }, "credit": { "description": "Surcharge definitions for corporate credit cards.", "type": "object", "properties": { "fixedAmount": { "description": "A flat surcharge amount in minor currency units.", "type": "number" }, "fixedPercentage": { "description": "A percentage-based surcharge.", "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "readTags": { "description": "This field denotes the type of NFC reading allowed on the terminal for the order. The possible values are,\n\nValues:\n- `NONE`: This value indicates that no tags are allowed for reading.\n- `SINGLE`: Single read allowed for the order.\n- `MULTIPLE_EDITABLE`: Multiple tags can be read and edited.\n- `MULTIPLE_NONEDITABLE`: Multiple tags can be read, but cannot be modified.", "type": "string", "enum": [ "NONE", "SINGLE", "MULTIPLE_EDITABLE", "MULTIPLE_NONEDITABLE" ] }, "ecrEnabled": { "description": "Whether ECR (electronic cash register) mode is enabled.", "type": "boolean" }, "online": { "description": "Online payment/link settings", "type": "object", "properties": { "enforceTokenization": { "description": "Denotes whether the card is tokenised for a future transaction or not.", "type": "boolean" }, "paymentPageValidFor": { "description": "Default validity of the payment page in format , where unit is 'm' | 'h' | 'd' (e.g., '15m', '2h', '3d').", "type": "string" }, "enforce3DSecure": { "description": "Force 3-D Secure authentication when available.", "type": "boolean" }, "relaxed3ds": { "description": "Allow relaxed 3-D Secure handling.", "type": "boolean" }, "addressRequirements": { "description": "Require an address on the payment page.", "type": "boolean" }, "redirectUrl": { "description": "Redirect URL after the online transaction completes successfully. The orderId will be appended as a query parameter.", "type": "string" }, "accountNameVerification": { "description": "Account-name verification mode applied during the payment.", "type": "string" }, "errorIfTokenizationFails": { "description": "If true, fail the flow when card tokenization cannot be completed.", "type": "boolean" }, "failureRedirectUrl": { "description": "Redirect URL when the transaction fails. The orderId will be appended as a query parameter.", "type": "string" }, "tokenisationIfPossible": { "description": "Attempts tokenization when supported, without failing the flow if tokenization is unavailable.", "type": "boolean" }, "subscription": { "description": "Marks this as a subscription/recurring-capable order.", "type": "boolean" }, "payButtonType": { "description": "UI pay button label/type used on the payment page.\n\nValues:\n- `ADD_MONEY`: Add money to balance\n- `BOOK`: Book a service\n- `CHECKOUT`: Standard checkout\n- `CONTINUE`: Continue flow\n- `CONTRIBUTE`: Contribute to a cause\n- `DONATE`: Donate money\n- `ORDER`: Place an order\n- `PAY`: Pay now\n- `RENT`: Rent item/service\n- `SUPPORT`: Support a creator/cause\n- `TIP`: Leave a tip\n- `TOP_UP`: Top up balance", "type": "string", "enum": [ "ADD_MONEY", "BOOK", "CHECKOUT", "CONTINUE", "CONTRIBUTE", "DONATE", "ORDER", "PAY", "RENT", "SUPPORT", "TIP", "TOP_UP" ] }, "generateShortLink": { "description": "If true, generates a short URL for the payment page. Default is false.", "type": "boolean" }, "generateOnlineLinkWith": { "description": "The terminal identifier used to generate the online payment link.", "type": "string" }, "recurring": { "description": "Encompasses all controls related to recurring payments.", "type": "object", "properties": { "subscriptionAmountType": { "description": "Determines the type of the subscription amount for order.\n\nValues:\n- `fixed`: A fixed amount is collected.\n- `variable`: A variable amount is collected.", "type": "string", "enum": [ "fixed", "variable" ] }, "maxAmount": { "description": "Maximum amount for the order in the lowest currency unit (only valid for variable subscription amounts).", "type": "number" }, "frequency": { "description": "Frequency of the recurring collection. 'daily' | 'twiceWeekly' | 'weekly' | 'tenDays' | 'fortNightly' | 'monthly' | 'everyTwoMonths' | 'trimester' | 'quarterly' | 'twiceYearly' | 'annually' | 'unscheduled'. Conditionally required: see the endpoint notes.", "type": "string" }, "numberOfPayments": { "description": "Total number of payments expected for this order.", "type": "number" }, "uniqueReference": { "description": "A unique reference for the recurring order.", "type": "string" }, "validation": { "description": "The validation type for the recurring order, possible values are 'validated' | 'notValidated'. Conditionally required: see the endpoint notes.", "type": "string" } }, "required": [ "frequency" ], "additionalProperties": true }, "currency": { "description": "Currency as a numeric ISO 4217 code (string), e.g., '752' for SEK.", "type": "string" }, "selfCardCharging": { "description": "Allow the customer to self-charge their card.", "type": "boolean" } }, "additionalProperties": true }, "taxHandlingStrategy": { "description": "Tax calculation strategy", "type": "object", "properties": { "treatAmountAsTaxExclusive": { "description": "Prices exclude tax", "type": "boolean" }, "taxTreatmentStrategy": { "description": "Rounding strategy configuration", "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true } }, "required": [ "terminal$id", "orderLines" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "terminal$id": "8386af3b0f71b80b04", "referenceId": "838f324b016d7009", "date": "2025-10-14T07:39:02.812Z", "adjustments": [ { "adjustmentId": "838f324b016d703e36", "type": "TIPS", "value": 100 } ], "orderLines": [ { "id": "TERM123NAL", "name": "Nike Shoes", "quantity": 1, "amount": { "regular": 500, "total": 500, "currency": "752", "tax": [ { "amount": 20, "percentage": 20, "type": "VAT" } ] } } ], "totalOrderAmount": { "regular": 500, "total": 600, "currency": "752" }, "controlFunctions": { "cancelPreviousPendingOrder": false, "orderLineLevelCalculation": false } }, "message": "Order fetched successfully" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "delete": { "operationId": "cancelAnOrder", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Orders API" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Identifier for the order this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Order cancelled successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/orders/{orderId}/status": { "get": { "operationId": "fetchOrderStatus", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Orders API" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Identifier for the order this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "orderStatus": { "description": "Describes the status of the order. The possible values are:\n\nValues:\n- `PENDING`: An order has been created and is waiting for payment processing.\n- `PAYMENT_COMPLETED`: The payment has been completed for the order.\n- `PAYMENT_CANCELLED`: The payment attempt has been cancelled for the order.\n- `PARTIAL_PAYMENT_COMPLETED`: A partial payment was completed for the order\n- `PAYMENT_PROCESSED`: The payment has been authorized.", "type": "string", "enum": [ "PENDING", "PAYMENT_COMPLETED", "PAYMENT_CANCELLED", "PARTIAL_PAYMENT_COMPLETED", "PAYMENT_PROCESSED" ] }, "payments": { "description": "Retrieves the status of all payments related to the order.", "type": "array", "items": { "type": "object", "properties": { "paymentId": { "description": "Unique identifier of the payment", "type": "string" }, "paymentStatus": { "description": "Describes the status of the payment. The possible values are:\n\nValues:\n- `PAYMENT_INITIATED`: A payment attempt has been initiated.\n- `PAYMENT_PROCESSING`: The payment is being authorized.\n- `PAYMENT_PROCESSED`: The payment has been authorized.\n- `PAYMENT_COMPLETED`: The payment has been completed.\n- `PAYMENT_FAILED`: The payment attempt has failed.\n- `PAYMENT_CANCELLED`: The payment attempt has been cancelled.", "type": "string", "enum": [ "PAYMENT_INITIATED", "PAYMENT_PROCESSING", "PAYMENT_PROCESSED", "PAYMENT_COMPLETED", "PAYMENT_FAILED", "PAYMENT_CANCELLED" ] }, "failureReason": { "description": "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.", "type": "string" }, "paymentMethod": { "description": "Denotes the payment method used.", "type": "string" }, "amount": { "description": "Amount involved with the payment attempt.", "type": "number" } }, "required": [ "paymentStatus" ], "additionalProperties": true } }, "paymentIds": { "description": "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.", "type": "array", "items": {} }, "transactions": { "description": "Retrieves all transaction details for the order. This information is only available when orderStatus is 'PAYMENT_COMPLETED' or 'PARTIAL_PAYMENT_COMPLETED'", "type": "array", "items": { "type": "object", "properties": { "transactionId": { "description": "Transaction ID of the transaction.", "type": "string" }, "merchantId": { "description": "Merchant ID of the merchant who performed the transaction.", "type": "string" }, "storeId": { "description": "Store ID of the store in which the transaction was performed", "type": "string" }, "terminalId": { "description": "Terminal ID of the checkout or payment terminal from which the transaction was performed.", "type": "string" }, "orderId": { "description": "Order ID of the order for which the transaction was performed.", "type": "string" }, "paymentId": { "description": "Payment ID of the transaction.", "type": "string" }, "referenceId": { "description": "Reference ID of the transaction.", "type": "string" }, "rrn": { "description": "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.", "type": "string" }, "amount": { "description": "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.", "type": "string" }, "currency": { "description": "Three digit numeric code representing the currency of the transaction.", "type": "string" }, "method": { "description": "The method in which the transaction was carried out. The payment method currently supported is 'CARD'.", "type": "string" }, "type": { "description": "Type of the transaction. It can be either 'purchase' or 'return.", "type": "string" }, "orderSummary": { "description": "Specifies a short summary of the order. Usually contains the initial line items included in the order.", "type": "string" }, "timestamp": { "description": "Timestamp of the transaction in ISO 8601 format represented as 'YYYY-MM-DDTHH:mm:ss.sssZ'.", "type": "string" }, "voided": { "description": "A boolean value that denotes if the transaction has been voided or not.", "type": "boolean" }, "issuerCountry": { "description": "Country of the card issuer.", "type": "string" }, "interchangeDomain": { "description": "Interchange domain of the transaction. It can be Domestic | Intraregional-EEA | Interregional-Non-EEA.", "type": "string" }, "cardCategory": { "description": "Denotes the card category, which can be Consumer | Commercial.", "type": "string" }, "cardUsage": { "description": "Denotes the card type, whether it is Debit, Credit or Prepaid.", "type": "string" }, "fee": { "description": "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.", "type": "string" }, "settlementStatus": { "description": "Denotes the status of the settlement.\n\nValues:\n- `PROCESSED`: Settlement processed. Waiting on amount to be credited to merchant's bank account.\n- `SETTLED`: The transaction was settled.\n- `NOT_SETTLED`: The transaction is not settled.\n- `ERROR`: Error occurred during the settlement process.", "type": "string", "enum": [ "PROCESSED", "SETTLED", "NOT_SETTLED", "ERROR" ] }, "payout": { "description": "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.", "type": "string" }, "settlementRef": { "description": "Reference Id for the payout which includes this transaction.", "type": "string" }, "settlementDate": { "description": "Date of the settlement for the transaction. Date in ISO string format.", "type": "string" }, "truncatedPan": { "description": "The last four digits of the PAN (Primary Account Number) from the card used for the transaction.", "type": "string" }, "cardLabel": { "description": "The designated label of the card brand for the transaction, often referred to as the AID (Application Identifier) Label.", "type": "string" }, "posEntryMode": { "description": "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.", "type": "string" }, "issuerApplication": { "description": "Specifies the payment application used in the transaction. Usually present when cards with both Debit and Credit facility are used.", "type": "string" }, "terminalVerificationResult": { "description": "Specifies the additional results if the transaction underwent EMV terminal verification.", "type": "string" }, "aid": { "description": "Specifies the Application Identifier (AID) associated with the card used for the transaction.", "type": "string" }, "customerResponseCode": { "description": "A two-character response code of the transaction. For all approved transactions, this code is '00'.", "type": "string" }, "cvmMethod": { "description": "Indicates the Card Holder Verification Method (CVM) used in the transaction.", "type": "string" }, "cvmMethodDescription": { "description": "Specifies the cvmMethod applied for the provided CARD transaction.", "type": "string" }, "authMode": { "description": "Indicates the authentication mode of the payment. This can be either 'ISSUER' or 'CARD'.", "type": "string" }, "cardBrand": { "description": "Denotes the brand of card used for the transaction. This is an optional normalized field available only for CARD payments. Eg., VISA, MASTERCARD, AMEX.", "type": "string" } }, "additionalProperties": true } }, "orderLines": { "description": "List of items in the order", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique identifier of the order line.", "type": "string" }, "name": { "description": "Display name of the actor, or null.", "type": "string" }, "quantity": { "description": "Quantity ordered. A negative value indicates a refund.", "type": "number" }, "amount": { "description": "Pricing details for the order line.", "type": "object", "properties": { "regular": { "description": "Regular price amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "total": { "description": "Total line amount in the smallest currency unit (eg.,10 SEK is 1000 in amount)", "type": "number" }, "currency": { "description": "ISO currency code of the amount.", "type": "string" } }, "additionalProperties": true }, "purchasePaymentId": { "description": "Original purchase payment ID", "type": "string" } }, "additionalProperties": true } } }, "required": [ "orderStatus", "payments" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "orderStatus": "PAYMENT_COMPLETED", "payments": [ { "paymentId": "838a071326f1330706", "paymentStatus": "PAYMENT_COMPLETED", "paymentMethod": "CARD", "amount": 200 } ], "transactions": [ { "transactionId": "838a071326f1333319", "merchantId": "8280577d677b18050e", "terminalId": "828057b63d8e480804", "orderId": "838a071326f130950b", "paymentId": "838a071326f1330706", "rrn": "526506000001", "amount": "200", "currency": "752", "method": "CARD", "type": "PURCHASE", "timestamp": "2025-10-08T07:25:11.144Z", "voided": false, "settlementStatus": "NOT_SETTLED", "truncatedPan": "0010", "posEntryMode": "07", "customerResponseCode": "00", "cvmMethodDescription": "No CVM", "authMode": "ISSUER", "cardBrand": "VISA" } ], "orderLines": [ { "id": "838a071326f1330707", "name": "Sample Product", "quantity": 2, "amount": { "regular": 10000, "total": 20000, "currency": "752" }, "purchasePaymentId": "838a071326f1330706" } ], "paymentIds": [ "838a071326f1330706" ] }, "message": "Fetched order status successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/orders/{orderId}/customer": { "put": { "operationId": "updateCustomerDetails", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Orders API" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Identifier for the order this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "description": "Customer details for the order", "type": "object", "properties": { "customerId": { "description": "Unique identifier for the customer", "type": "string" }, "person": { "description": "Personal information of the customer", "type": "object", "properties": { "id": { "description": "Person identifier.", "type": "string" }, "name": { "description": "Full name of the customer", "type": "object", "properties": { "firstName": { "description": "First name of the customer", "type": "string" }, "middleName": { "description": "Middle name of the customer", "type": "string" }, "lastName": { "description": "Last name of the customer", "type": "string" } } }, "email": { "description": "Email address of the customer", "type": "string" }, "phoneNumber": { "description": "Phone number of the customer", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ] }, "birthDate": { "description": "Date of birth in YYYY-MM-DD format", "type": "string" }, "personalNumber": { "description": "Personal identification number", "type": "string" }, "coordinationNumber": { "description": "Coordination number", "type": "string" }, "countryResidence": { "description": "Country of residence of the customer", "type": "string" }, "gdNumber": { "description": "Government-issued identification number of the customer", "type": "string" } } }, "company": { "description": "Company information for corporate purchases", "type": "object", "properties": { "id": { "description": "Company identifier.", "type": "string" }, "vatId": { "description": "VAT ID of the company", "type": "string" }, "poDetails": { "description": "Purchase order details for the company", "type": "string" }, "companyName": { "description": "Company display name.", "type": "string" }, "registrationNumber": { "description": "Company registration number.", "type": "string" }, "gln": { "description": "GLN of the buyer's e-invoice department, used to route e-invoices.", "type": "string" } } } } }, "billing": { "description": "Billing contact and address", "type": "object", "properties": { "name": { "description": "Full name of the billing contact", "type": "object", "properties": { "firstName": { "description": "First name of the billing contact", "type": "string" }, "middleName": { "description": "Middle name of the billing contact", "type": "string" }, "lastName": { "description": "Last name of the billing contact", "type": "string" } } }, "email": { "description": "Billing email", "type": "string" }, "phoneNumber": { "description": "Phone number for billing", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ] }, "address": { "description": "Billing address", "type": "object", "properties": { "careOf": { "description": "Care of / attention", "type": "string" }, "addressLine1": { "description": "Primary address line", "type": "string" }, "addressLine2": { "description": "Address line 2", "type": "string" }, "addressLine3": { "description": "Address line 3", "type": "string" }, "city": { "description": "City name", "type": "string" }, "postalCode": { "description": "Postal/ZIP code", "type": "string" }, "countryCode": { "description": "Country code (ISO 3166-1 alpha-2)", "type": "string" } }, "required": [ "addressLine1", "city", "postalCode", "countryCode" ] } } }, "shipping": { "description": "Shipping contact and address", "type": "object", "properties": { "name": { "description": "Full name of the shipping contact", "type": "object", "properties": { "firstName": { "description": "First name of the shipping contact", "type": "string" }, "middleName": { "description": "Middle name of the shipping contact", "type": "string" }, "lastName": { "description": "Last name of the shipping contact", "type": "string" } } }, "email": { "description": "Recipient email", "type": "string" }, "phoneNumber": { "description": "Phone number for shipping", "type": "object", "properties": { "code": { "description": "International dialing code (Eg., 46 for Sweden without '+')", "type": "string" }, "number": { "description": "National subscriber number (digits only)", "type": "string" } }, "required": [ "code", "number" ] }, "address": { "description": "Shipping address", "type": "object", "properties": { "careOf": { "description": "Care of / attention", "type": "string" }, "addressLine1": { "description": "Primary address line", "type": "string" }, "addressLine2": { "description": "Address line 2", "type": "string" }, "addressLine3": { "description": "Address line 3", "type": "string" }, "city": { "description": "City name", "type": "string" }, "postalCode": { "description": "Postal/ZIP code", "type": "string" }, "countryCode": { "description": "Country code (ISO 3166-1 alpha-2)", "type": "string" } }, "required": [ "addressLine1", "city", "postalCode", "countryCode" ] } } } } }, "example": { "customer": { "customerId": "825a37d0aa1048120e", "person": { "name": { "firstName": "Tom", "middleName": "A", "lastName": "Andersson" }, "email": "tom.andersson@example.com", "phoneNumber": { "code": "46", "number": "701234567" }, "birthDate": "1990-05-14", "personalNumber": "199005141234", "coordinationNumber": "199005741234", "countryResidence": "SE", "gdNumber": "GD123456" }, "company": { "vatId": "SE556677889901", "poDetails": "PO-2024-0098" } }, "billing": { "name": { "firstName": "Tom", "middleName": "A", "lastName": "Andersson" }, "email": "tom.andersson@example.com", "phoneNumber": { "code": "46", "number": "701234567" }, "address": { "careOf": "c/o Reception", "addressLine1": "Storgatan 1", "addressLine2": "Floor 2", "addressLine3": "Door 4", "city": "Stockholm", "postalCode": "11122", "countryCode": "SE" } }, "shipping": { "name": { "firstName": "Sam", "middleName": "A", "lastName": "Berg" }, "email": "sam.berg@example.com", "phoneNumber": { "code": "46", "number": "709876543" }, "address": { "careOf": "c/o Reception", "addressLine1": "Kungsgatan 9", "addressLine2": "Floor 2", "addressLine3": "Door 4", "city": "Stockholm", "postalCode": "11122", "countryCode": "SE" } } } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Updated customer, billing and shipping details returned by the service.", "type": "object", "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": {}, "message": "Customer details updated successfully." } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Invalid order id" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/orders/{orderId}/receipt": { "put": { "operationId": "addReceiptInformation", "summary": "Add Receipt Information", "description": "This API allows you to store cash register details for receipts.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Orders API" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Identifier for the order this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "description": "Merchant the receipt belongs to.", "type": "string" }, "sequenceNumber": { "description": "Receipt sequence number.", "type": "string" }, "cashRegisterName": { "description": "Name of the cash register.", "type": "string" }, "controlUnitSerialNumber": { "description": "Serial number of the fiscal control unit.", "type": "string" }, "cashierName": { "description": "Name of the cashier.", "type": "string" }, "customerName": { "description": "Name of the customer on the receipt.", "type": "string" } } }, "example": { "merchantId": "825a376eeed1200600", "sequenceNumber": "1234567", "cashRegisterName": "Test", "controlUnitSerialNumber": "1234567", "cashierName": "Amanda", "customerName": "Tom" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request 'SUCCESS' | 'ERROR'.", "type": "string" }, "message": { "description": "Status message of the request is displayed.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Receipt data updated successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/orders/{orderId}/adjustments": { "get": { "operationId": "fetchOrderAdjustments", "summary": "Fetch Order Adjustments", "description": "Fetch all adjustments created under an order.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Orders API" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Identifier for the order this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": false, "description": "Start of the date range to filter adjustments by, in yyyy-mm-dd format. Applied only when endDate is also sent.", "schema": { "description": "Start of the date range to filter adjustments by, in yyyy-mm-dd format. Applied only when endDate is also sent.", "type": "string" } }, { "name": "endDate", "in": "query", "required": false, "description": "End of the date range to filter adjustments by, in yyyy-mm-dd format. Applied only when startDate is also sent.", "schema": { "description": "End of the date range to filter adjustments by, in yyyy-mm-dd format. Applied only when startDate is also sent.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "array", "items": { "type": "object", "properties": { "adjustmentId": { "description": "Adjustment ID of the adjustment.", "type": "string" }, "transactionId": { "description": "Transaction the adjustment is associated with.", "type": "string" }, "orderId": { "description": "Order the adjustment belongs to.", "type": "string" }, "adjustmentType": { "description": "Type of the adjustment", "type": "string" }, "amount": { "description": "Amount of the adjustment.", "type": "number" }, "currency": { "description": "Currency of the adjustment amount.", "type": "string" }, "metadata": { "description": "Free-form metadata for the adjustment.", "type": "object", "additionalProperties": true }, "createdAt": { "description": "Timestamp when the adjustment was created.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "adjustmentId": "81efdbe975ebc800ff", "transactionId": "8267defa6150700b48", "orderId": "82674cfdf77f500001", "adjustmentType": "tips", "amount": 100, "currency": "SEK", "metadata": {}, "createdAt": "2026-06-22T07:39:02.812Z" } ], "message": "Adjustments fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/orders/{orderId}/tokens": { "get": { "operationId": "fetchTokensFromOrder", "summary": "Fetch Tokens from Order", "description": "Fetch all tokenized card information collected for online orders.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Orders API" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Identifier for the order this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "array", "items": { "type": "object", "properties": { "cardBrand": { "description": "Denotes the brand of the card. E.g. VISA, MASTERCARD, AMEX.", "type": "string" }, "cardholderName": { "description": "Name of the card holder.", "type": "string" }, "tokenId": { "description": "Tokenized card information.", "type": "string" }, "createdAt": { "description": "Date of tokenization in ISO string format.", "type": "string" }, "expiryMonth": { "description": "Expiration month of the card.", "type": "number" }, "expiryYear": { "description": "Expiration year of the card.", "type": "number" }, "truncatedPan": { "description": "The last four digits of the PAN (Primary Account Number) from the card.", "type": "string" }, "cardArt": { "description": "Denotes the visual images of the card. Eg., VISA, MASTERCARD, AMEX.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "cardBrand": "VISA", "cardholderName": "Tom", "tokenId": "822d544dc48c200308", "createdAt": "2024-04-25T11:22:24.845Z", "expiryMonth": 7, "expiryYear": 2026, "truncatedPan": "8907", "cardArt": "iVBORw0KGgoAAAANSUhEUgAAAUQAAA......" }, { "cardBrand": "VISA", "cardholderName": "Sam", "tokenId": "822d544dc48c200308", "createdAt": "2024-04-25T11:22:24.845Z", "expiryMonth": 5, "expiryYear": 2025, "truncatedPan": "0987", "cardArt": "YAAAAAXNSR0IArs4c6QAAAARnQU1BA......" } ], "message": "Fetched the card information." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/orders/{terminalId}/online": { "get": { "operationId": "fetchOnlineOrders", "summary": "Fetch Online Orders", "description": "This API retrieves a list of all online orders created under a terminal.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Orders API" ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "array", "items": { "type": "object", "properties": { "orderId": { "description": "Id of the order.", "type": "string" }, "status": { "description": "Status of the order.", "type": "string" }, "terminalId": { "description": "Id of the payment terminal.", "type": "string" }, "totalOrderAmount": { "description": "Total order value.", "type": "string" }, "currency": { "description": "Type of currency.", "type": "string" }, "paymentPageUrl": { "description": "This is the URL of the payment page.", "type": "string" }, "nonceId": { "description": "Single-use identifier issued for the order's online payment session.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "orderId": "825a37cb9e2048070b", "status": "PENDING", "terminalId": "825a376eeed1200604", "totalOrderAmount": "450", "currency": "SEK", "paymentPageUrl": "https://pay.beta.surfboard.se/825a37cb9e2048070b?pi=w60wGmUUE-k5XN1iT1RyYo-TzaiUl8wsIyO9IEZf4KE-wmDDnl-cxJ4IWkhnCqRvuk6P1WRPDaZP23_LevN0G5JqG_hDgZI9dEn4ooF3ELZMUHiE-ocL_LGc4nT1Cbuv&add=IzNDMkEyMSB8Q0FSRA==", "nonceId": "825a37cd2f1048090c" }, { "orderId": "825a37ca1e20480e0b", "status": "PENDING", "terminalId": "825a376eeed1200604", "totalOrderAmount": "450", "currency": "SEK", "paymentPageUrl": "https://pay.beta.surfboard.se/825a37ca1e20480e0b?pi=gav_crJ4iqayHI05XyMgNdVbTW78QmRMJGm5QFaN0vCvydZfzw8_KQ9j5dd90Yf-OLEq72cpN905QNRXGVki4jxdmvDTPoW8RTNFIC_TPqiCcV80rdpXIuR1Tw6El8PI&add=IzNDMkEyMSB8Q0FSRA==", "nonceId": "825a37cb6e10480f0d" } ], "message": "Fetched online orders successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/partners/{partnerId}": { "get": { "operationId": "getPartnerDetails", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Partners API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier of the partner to fetch details for. Supplied in the URL path.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The partner account details.", "type": "object", "properties": { "partnerId": { "description": "Unique identifier of the partner.", "type": "string" }, "webOnboardingUrl": { "description": "Hosted URL where the partner's merchants complete web-based onboarding.", "type": "string" }, "partnerName": { "description": "Display name of the partner.", "type": "string" }, "status": { "description": "Lifecycle status of the partner account, for example ACTIVE.", "type": "string" }, "supportedBillingPlans": { "description": "Billing plans the partner is allowed to assign to its merchants.", "type": "array", "items": {} }, "partnerType": { "description": "Type of partner, which determines the onboarding and billing flow available to it.", "type": "string" }, "paymentMethods": { "description": "Payment methods enabled for the partner, for example CARD or SWISH.", "type": "array", "items": {} }, "countryCode": { "description": "Primary country the partner is registered in (ISO 3166-1 alpha-2).", "type": "string" }, "acquirerConfig": { "description": "The acquirer used to process card payments, per operating country.", "type": "array", "items": { "type": "object", "properties": { "country": { "description": "Country the acquirer applies to (ISO 3166-1 alpha-2).", "type": "string" }, "acquirer": { "description": "Name of the acquirer that settles card payments in this country.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "partnerId": "pt_9c31a0f4b2", "webOnboardingUrl": "https://onboarding.surfboard.se/pt_9c31a0f4b2", "partnerName": "Nordic Coffee Group", "status": "ACTIVE", "supportedBillingPlans": [ "STANDARD", "PREMIUM" ], "partnerType": "RESELLER", "paymentMethods": [ "CARD", "SWISH" ], "countryCode": "SE", "acquirerConfig": [ { "country": "SE", "acquirer": "NEXI" } ] }, "message": "Partner details fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch partner details" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/config": { "get": { "operationId": "getPartnerConfig", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Partners API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier of the partner to fetch configuration for. Supplied in the URL path.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The partner feature configuration.", "type": "object", "properties": { "activateTerminalFromPortal": { "description": "Whether terminals can be activated directly from the partner portal.", "type": "boolean" }, "allowAdvancedOnboarding": { "description": "Whether the partner has access to the advanced onboarding flow.", "type": "boolean" }, "enableProductCatalogueInOnboarding": { "description": "Whether the product catalog step is shown during merchant onboarding.", "type": "boolean" }, "ecrEnabled": { "description": "Whether the partner has access to the cash-register (ECR) features in the portal.", "type": "boolean" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "activateTerminalFromPortal": true, "allowAdvancedOnboarding": false, "enableProductCatalogueInOnboarding": true, "ecrEnabled": false }, "message": "Partner config fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch partner config" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/analytics": { "get": { "operationId": "getPartnerAnalytics", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Partners API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier of the partner to fetch analytics for. Supplied in the URL path.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The partner activity summary.", "type": "object", "properties": { "totalNumberOfApplication": { "description": "Total number of merchant applications created under the partner.", "type": "number" }, "totalNumberOfAppInitiated": { "description": "Number of applications that have been initiated but not yet submitted.", "type": "number" }, "totalNumberOfAppExpired": { "description": "Number of applications that expired before completion.", "type": "number" }, "totalNumberOfAppSubmitted": { "description": "Number of applications submitted for review.", "type": "number" }, "totalNumberOfAppPending": { "description": "Number of applications awaiting further information.", "type": "number" }, "totalNumberOfAppSigned": { "description": "Number of applications that have been signed.", "type": "number" }, "totalNumberOfAppRejected": { "description": "Number of applications that were rejected.", "type": "number" }, "totalNumberOfAppCompleted": { "description": "Number of applications that completed onboarding.", "type": "number" }, "totalNumberOfMerchantCreated": { "description": "Number of merchants created under the partner.", "type": "number" }, "totalNumberOfTransaction": { "description": "Total number of transactions across the partner's merchants.", "type": "number" }, "totalNumberOfPurchaseTransaction": { "description": "Number of purchase transactions across the partner's merchants.", "type": "number" }, "totalNumberReturnTransaction": { "description": "Number of return transactions across the partner's merchants.", "type": "number" }, "totalAmountOfTransaction": { "description": "Total value of all transactions, in the smallest unit of the currency (e.g. öre for SEK).", "type": "number" }, "totalAmountOfPurchaseTransaction": { "description": "Total value of purchase transactions, in the smallest currency unit.", "type": "number" }, "totalAmountOfReturnTransaction": { "description": "Total value of return transactions, in the smallest currency unit.", "type": "number" }, "recentActivityData": { "description": "Recent activity events for the partner, as an ordered list of key-value entries.", "type": "array", "items": { "type": "object", "properties": { "event": { "description": "The type of activity that occurred.", "type": "string" }, "timestamp": { "description": "When the activity occurred, in ISO 8601 format.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "totalNumberOfApplication": 128, "totalNumberOfAppInitiated": 12, "totalNumberOfAppExpired": 4, "totalNumberOfAppSubmitted": 9, "totalNumberOfAppPending": 6, "totalNumberOfAppSigned": 15, "totalNumberOfAppRejected": 3, "totalNumberOfAppCompleted": 79, "totalNumberOfMerchantCreated": 79, "totalNumberOfTransaction": 54210, "totalNumberOfPurchaseTransaction": 52890, "totalNumberReturnTransaction": 1320, "totalAmountOfTransaction": 812450000, "totalAmountOfPurchaseTransaction": 829100000, "totalAmountOfReturnTransaction": 16650000, "recentActivityData": [ { "event": "MERCHANT_CREATED", "timestamp": "2026-06-14T08:11:00.000Z" } ] }, "message": "Partner details fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch partner details" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/transaction-analytics": { "get": { "operationId": "getTransactionAnalytics", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Partners API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier of the partner to fetch analytics for. Supplied in the URL path.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "query", "required": false, "description": "Return only analytics for this merchant under the partner.", "schema": { "description": "Return only analytics for this merchant under the partner.", "type": "string" } }, { "name": "storeId", "in": "query", "required": false, "description": "Return only analytics for transactions at this store.", "schema": { "description": "Return only analytics for transactions at this store.", "type": "string" } }, { "name": "terminalId", "in": "query", "required": false, "description": "Return only analytics for transactions processed by this terminal.", "schema": { "description": "Return only analytics for transactions processed by this terminal.", "type": "string" } }, { "name": "startDate", "in": "query", "required": false, "description": "Start of the date range to aggregate over (ISO 8601, e.g. 2026-06-01).", "schema": { "description": "Start of the date range to aggregate over (ISO 8601, e.g. 2026-06-01).", "type": "string" } }, { "name": "endDate", "in": "query", "required": false, "description": "End of the date range to aggregate over (ISO 8601).", "schema": { "description": "End of the date range to aggregate over (ISO 8601).", "type": "string" } }, { "name": "orderType", "in": "query", "required": false, "description": "Return only analytics for this order type.", "schema": { "description": "Return only analytics for this order type.", "type": "string", "enum": [ null, null ] } }, { "name": "terminalType", "in": "query", "required": false, "description": "Return only analytics for this terminal type.", "schema": { "description": "Return only analytics for this terminal type.", "type": "string" } }, { "name": "paymentMethod", "in": "query", "required": false, "description": "Return only analytics for this payment method, for example CARD or SWISH.", "schema": { "description": "Return only analytics for this payment method, for example CARD or SWISH.", "type": "string" } }, { "name": "cardBrand", "in": "query", "required": false, "description": "Return only analytics for this card brand, for example VISA or MASTERCARD.", "schema": { "description": "Return only analytics for this card brand, for example VISA or MASTERCARD.", "type": "string" } }, { "name": "currency", "in": "query", "required": false, "description": "Return only analytics in this currency (ISO 4217 code).", "schema": { "description": "Return only analytics in this currency (ISO 4217 code).", "type": "string" } }, { "name": "includeRealtimeTransactions", "in": "query", "required": false, "description": "When true, includes transactions that have not yet settled in the aggregation.", "schema": { "description": "When true, includes transactions that have not yet settled in the aggregation.", "type": "boolean" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The aggregated analytics rows, one per grouping bucket.", "type": "array", "items": { "type": "object", "properties": { "storeId": { "description": "Store the row is grouped by. Present only when grouping by store.", "type": "string" }, "terminalId": { "description": "Terminal the row is grouped by. Present only when grouping by terminal.", "type": "string" }, "orderType": { "description": "Order type the row is grouped by. Present only when grouping by order type.", "type": "string", "enum": [ null, null ] }, "terminalType": { "description": "Terminal type the row is grouped by. Present only when grouping by terminal type.", "type": "string" }, "orderTransactionCount": { "description": "Number of transactions in this grouping bucket.", "type": "string" }, "totalTransactionAmount": { "description": "Total transaction value for this bucket, in the smallest unit of the currency (e.g. öre for SEK).", "type": "number" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "storeId": "st_2a91", "orderType": "PURCHASE", "orderTransactionCount": "1204", "totalTransactionAmount": 18942000 } ], "message": "Transaction analytics for partner fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch transaction analytics for partner." } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/partner-analytics": { "get": { "operationId": "getApplicationAnalytics", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Partners API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier of the partner to fetch onboarding analytics for. Supplied in the URL path.", "schema": { "type": "string" } }, { "name": "timeFrame", "in": "query", "required": false, "description": "Preset time window to aggregate over. Use CUSTOM together with dateFrom and dateTo for an explicit range.", "schema": { "description": "Preset time window to aggregate over. Use CUSTOM together with dateFrom and dateTo for an explicit range.", "type": "string", "enum": [ null, null, null, null, null, null, null, null, null, null ] } }, { "name": "dateFrom", "in": "query", "required": false, "description": "Start of a custom date range (ISO 8601). Used when timeFrame is CUSTOM.", "schema": { "description": "Start of a custom date range (ISO 8601). Used when timeFrame is CUSTOM.", "type": "string" } }, { "name": "dateTo", "in": "query", "required": false, "description": "End of a custom date range (ISO 8601). Used when timeFrame is CUSTOM.", "schema": { "description": "End of a custom date range (ISO 8601). Used when timeFrame is CUSTOM.", "type": "string" } }, { "name": "groupBy", "in": "query", "required": false, "description": "One or more dimensions to group the results by.", "schema": { "description": "One or more dimensions to group the results by.", "type": "array", "items": {} } }, { "name": "filters[countries]", "in": "query", "required": false, "description": "Return only applications for these countries (ISO 3166-1 alpha-2 codes).", "schema": { "description": "Return only applications for these countries (ISO 3166-1 alpha-2 codes).", "type": "array", "items": {} } }, { "name": "filters[applicationTypes]", "in": "query", "required": false, "description": "Return only applications of these types.", "schema": { "description": "Return only applications of these types.", "type": "array", "items": {} } }, { "name": "filters[statusGroup]", "in": "query", "required": false, "description": "Return only applications in this status group.", "schema": { "description": "Return only applications in this status group.", "type": "string", "enum": [ null, null, null, null ] } }, { "name": "sortBy", "in": "query", "required": false, "description": "Field to sort the grouped rows by.", "schema": { "description": "Field to sort the grouped rows by.", "type": "string", "enum": [ null, null, null ] } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Sort direction for the results.", "schema": { "description": "Sort direction for the results.", "type": "string", "enum": [ null, null ] } }, { "name": "pageNumber", "in": "query", "required": false, "description": "Page of results to return. Overrides the x-page-number header when supplied.", "schema": { "description": "Page of results to return. Overrides the x-page-number header when supplied.", "type": "number" } }, { "name": "itemsPerPage", "in": "query", "required": false, "description": "Number of rows to return per page.", "schema": { "description": "Number of rows to return per page.", "type": "number" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The aggregated onboarding analytics.", "type": "object", "properties": { "applicationAnalyticsData": { "description": "The grouped analytics rows.", "type": "array", "items": { "type": "object", "properties": { "country": { "description": "Country the row is grouped by. Present only when grouping by country.", "type": "string" }, "applicationType": { "description": "Application type the row is grouped by. Present only when grouping by application type.", "type": "string", "enum": [ null, null ] }, "statusGroup": { "description": "Status group the row is grouped by. Present only when grouping by status group.", "type": "string", "enum": [ null, null, null, null ] }, "timeSegment": { "description": "Time bucket the row is grouped by. Present only when grouping by a time dimension.", "type": "string" }, "totalApplications": { "description": "Total applications in this bucket.", "type": "number" }, "totalInitiated": { "description": "Applications initiated but not yet submitted in this bucket.", "type": "number" }, "totalExpired": { "description": "Applications that expired before completion in this bucket.", "type": "number" }, "totalSubmitted": { "description": "Applications submitted for review in this bucket.", "type": "number" }, "totalPending": { "description": "Applications awaiting further information in this bucket.", "type": "number" }, "totalSigned": { "description": "Applications signed in this bucket.", "type": "number" }, "totalRejected": { "description": "Applications rejected in this bucket.", "type": "number" }, "totalCompleted": { "description": "Applications that completed onboarding in this bucket.", "type": "number" }, "totalMerchantCreated": { "description": "Merchants created in this bucket.", "type": "number" }, "totalServiceProviderCreated": { "description": "Service providers created in this bucket.", "type": "number" }, "conversionRate": { "description": "Share of applications that completed onboarding, as a percentage.", "type": "number" }, "rejectionRate": { "description": "Share of applications that were rejected, as a percentage.", "type": "number" }, "expirationRate": { "description": "Share of applications that expired, as a percentage.", "type": "number" } }, "additionalProperties": true } }, "totalCount": { "description": "Total number of grouped rows across all pages.", "type": "number" }, "pageNumber": { "description": "The page of results returned.", "type": "number" }, "itemsPerPage": { "description": "Number of rows returned per page.", "type": "number" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "applicationAnalyticsData": [ { "country": "SE", "totalApplications": 84, "totalInitiated": 6, "totalExpired": 2, "totalSubmitted": 5, "totalPending": 3, "totalSigned": 9, "totalRejected": 1, "totalCompleted": 58, "totalMerchantCreated": 58, "totalServiceProviderCreated": 0, "conversionRate": 69.05, "rejectionRate": 1.19, "expirationRate": 2.38 } ], "totalCount": 1, "pageNumber": 1, "itemsPerPage": 100 }, "message": "Application analytics fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch application analytics." } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/global-search": { "get": { "operationId": "globalSearch", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Partners API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier of the partner whose records are searched. Supplied in the URL path.", "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": true, "description": "The text to search the partner's records for, such as a merchant name, store name, or company.", "schema": { "description": "The text to search the partner's records for, such as a merchant name, store name, or company.", "type": "string" } }, { "name": "pageNumber", "in": "query", "required": false, "description": "Page of results to return. Overrides the x-page-number header when supplied.", "schema": { "description": "Page of results to return. Overrides the x-page-number header when supplied.", "type": "number" } }, { "name": "merchantId", "in": "query", "required": false, "description": "Return only records belonging to this merchant. Accepts a single value or a comma-separated list.", "schema": { "description": "Return only records belonging to this merchant. Accepts a single value or a comma-separated list.", "type": "string" } }, { "name": "merchantType", "in": "query", "required": false, "description": "Return only records for merchants of this type. Accepts a single value or a comma-separated list.", "schema": { "description": "Return only records for merchants of this type. Accepts a single value or a comma-separated list.", "type": "string" } }, { "name": "storeId", "in": "query", "required": false, "description": "Return only records belonging to this store. Accepts a single value or a comma-separated list.", "schema": { "description": "Return only records belonging to this store. Accepts a single value or a comma-separated list.", "type": "string" } }, { "name": "storeStatus", "in": "query", "required": false, "description": "Return only stores in this status. Accepts a single value or a comma-separated list.", "schema": { "description": "Return only stores in this status. Accepts a single value or a comma-separated list.", "type": "string" } }, { "name": "terminalStatus", "in": "query", "required": false, "description": "Return only terminals in this status. Accepts a single value or a comma-separated list.", "schema": { "description": "Return only terminals in this status. Accepts a single value or a comma-separated list.", "type": "string" } }, { "name": "applicationStatus", "in": "query", "required": false, "description": "Return only applications in this status. Accepts a single value or a comma-separated list.", "schema": { "description": "Return only applications in this status. Accepts a single value or a comma-separated list.", "type": "string" } }, { "name": "applicationType", "in": "query", "required": false, "description": "Return only applications of this type. Accepts a single value or a comma-separated list.", "schema": { "description": "Return only applications of this type. Accepts a single value or a comma-separated list.", "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Return only records of this document type, for example MERCHANT or STORE. Accepts a single value or a comma-separated list.", "schema": { "description": "Return only records of this document type, for example MERCHANT or STORE. Accepts a single value or a comma-separated list.", "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The search results.", "type": "object", "properties": { "hits": { "description": "The matching records.", "type": "array", "items": { "type": "object", "properties": { "partnerId": { "description": "Identifier of the partner the matched record belongs to.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant the matched record belongs to.", "type": "string" }, "storeId": { "description": "Identifier of the store the matched record belongs to.", "type": "string" }, "data": { "description": "The matched record's document fields.", "type": "object", "properties": { "type": { "description": "The kind of record that matched, for example MERCHANT, STORE, or COMPANY.", "type": "string" }, "partnerId": { "description": "Identifier of the partner the record belongs to.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant the record belongs to.", "type": "string" }, "storeId": { "description": "Identifier of the store the record belongs to.", "type": "string" }, "companyId": { "description": "Identifier of the company the record belongs to.", "type": "string" }, "pfAccountId": { "description": "Payment facilitator account identifier for the record.", "type": "string" }, "name": { "description": "Display name of the matched record.", "type": "string" }, "email": { "description": "Email associated with the matched record.", "type": "string" }, "status": { "description": "Status of the matched record, mirrored from its store status.", "type": "string" }, "storeStatus": { "description": "Status of the store the record belongs to.", "type": "string" }, "merchantType": { "description": "Type of the merchant the record belongs to.", "type": "string" } }, "additionalProperties": true }, "matches": { "description": "The individual field matches for this record.", "type": "array", "items": { "type": "object", "properties": { "field": { "description": "The document field that matched the search.", "type": "string" }, "matched": { "description": "The matched value or values for the field.", "type": "array", "items": {} }, "snippet": { "description": "A snippet of text surrounding the match.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "hits": [ { "partnerId": "pt_9c31a0f4b2", "merchantId": "m_5f2c1a9b3d", "storeId": "st_2a91", "data": { "type": "MERCHANT", "partnerId": "pt_9c31a0f4b2", "merchantId": "m_5f2c1a9b3d", "storeId": "st_2a91", "companyId": "co_71ad", "pfAccountId": "pf_88c2", "name": "Kaffebaren AB", "email": "hello@kaffebaren.se", "status": "ACTIVE", "storeStatus": "ACTIVE", "merchantType": "STANDARD" }, "matches": [ { "field": "name", "matched": [ "Kaffebaren AB" ], "snippet": "…Kaffebaren AB…" } ] } ] }, "message": "Global search results fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch global search results" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/companies/search": { "get": { "operationId": "searchCompanies", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Partners API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier of the partner performing the search. Supplied in the URL path.", "schema": { "type": "string" } }, { "name": "companyName", "in": "query", "required": true, "description": "The company name to search the registry for.", "schema": { "description": "The company name to search the registry for.", "type": "string" } }, { "name": "countryCode", "in": "query", "required": false, "description": "Restrict the search to one or more countries (ISO 3166-1 alpha-2). Accepts a single value or a list.", "schema": { "description": "Restrict the search to one or more countries (ISO 3166-1 alpha-2). Accepts a single value or a list.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The matching companies.", "type": "array", "items": { "type": "object", "properties": { "companyId": { "description": "Surfboard identifier for the company.", "type": "string" }, "creditsafeId": { "description": "Identifier of the company in the Creditsafe registry.", "type": "string" }, "companyName": { "description": "Registered name of the company.", "type": "string" }, "legalGroupCode": { "description": "Code identifying the company's legal form.", "type": "string" }, "legalGroupText": { "description": "Human-readable description of the company's legal form.", "type": "string" }, "address": { "description": "The company's registered address.", "type": "object", "properties": { "simpleValue": { "description": "The full address as a single formatted string.", "type": "string" }, "street": { "description": "Street part of the address.", "type": "string" }, "city": { "description": "City part of the address.", "type": "string" }, "postCode": { "description": "Postal code part of the address.", "type": "string" }, "telephone": { "description": "Registered telephone number for the company.", "type": "string" } }, "additionalProperties": true }, "town": { "description": "Town the company is registered in.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "companyId": "co_71ad", "creditsafeId": "SE-0-5566778899", "companyName": "Kaffebaren AB", "legalGroupCode": "AB", "legalGroupText": "Aktiebolag", "address": { "simpleValue": "Storgatan 1, 111 22 Stockholm", "street": "Storgatan 1", "city": "Stockholm", "postCode": "111 22", "telephone": "+46 8 123 456" }, "town": "Stockholm" } ], "message": "Company search completed successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to search companies" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/users": { "get": { "operationId": "listPartnerUsers", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Partners API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier of the partner whose users are returned. Supplied in the URL path.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The users belonging to the partner.", "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "Unique identifier of the user.", "type": "string" }, "firstName": { "description": "User's first name.", "type": "string" }, "lastName": { "description": "User's last name.", "type": "string" }, "imageUrl": { "description": "URL of the user's profile image.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant the user is associated with, if any.", "type": "string" }, "partnerId": { "description": "Identifier of the partner the user belongs to.", "type": "string" }, "phoneNumber": { "description": "User's phone number.", "type": "string" }, "swishNumber": { "description": "User's Swish number, if set.", "type": "string" }, "address": { "description": "User's address.", "type": "string" }, "email": { "description": "User's email address.", "type": "string" }, "role": { "description": "The user's role, which determines their permissions.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "userId": "u_3f81a0", "firstName": "Anna", "lastName": "Berg", "imageUrl": "https://cdn.surfboard.se/u/3f81a0.png", "merchantId": "", "partnerId": "pt_9c31a0f4b2", "phoneNumber": "+46701234567", "swishNumber": "", "address": "Storgatan 1, Stockholm", "email": "anna@nordiccoffee.se", "role": "ADMIN" } ], "message": "Fetched users for partner successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch users for partner" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/merchants/{merchantId}/users": { "get": { "operationId": "listMerchantUsers", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Partners API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier of the partner the merchant belongs to. Supplied in the URL path.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier of the merchant whose users are returned. Supplied in the URL path.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The users belonging to the merchant.", "type": "array", "items": { "type": "object", "properties": { "userId": { "description": "Unique identifier of the user.", "type": "string" }, "firstName": { "description": "User's first name.", "type": "string" }, "lastName": { "description": "User's last name.", "type": "string" }, "imageUrl": { "description": "URL of the user's profile image.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant the user belongs to.", "type": "string" }, "partnerId": { "description": "Identifier of the partner the user is associated with, if any.", "type": "string" }, "phoneNumber": { "description": "User's phone number.", "type": "string" }, "swishNumber": { "description": "User's Swish number, if set.", "type": "string" }, "address": { "description": "User's address.", "type": "string" }, "email": { "description": "User's email address.", "type": "string" }, "role": { "description": "The user's role, which determines their permissions.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "userId": "u_7b42c1", "firstName": "Erik", "lastName": "Lund", "imageUrl": "https://cdn.surfboard.se/u/7b42c1.png", "merchantId": "m_5f2c1a9b3d", "partnerId": "pt_9c31a0f4b2", "phoneNumber": "+46707654321", "swishNumber": "1231181189", "address": "Kungsgatan 5, Göteborg", "email": "erik@kaffebaren.se", "role": "CASHIER" } ], "message": "Fetched users for merchant successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch users for merchant" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/merchants/{merchantId}/users/{userId}": { "put": { "operationId": "updateMerchantUser", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Partners API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier of the partner the merchant belongs to. Supplied in the URL path.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier of the merchant the user belongs to. Supplied in the URL path.", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "Identifier of the user to update. Supplied in the URL path.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "description": "New first name for the user.", "type": "string" }, "lastName": { "description": "New last name for the user.", "type": "string" }, "imageUrl": { "description": "New profile image URL for the user.", "type": "string" }, "address": { "description": "New address for the user.", "type": "string" } } }, "example": { "firstName": "Erik", "lastName": "Lundqvist", "address": "Kungsgatan 5, Göteborg" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The updated user profile.", "type": "object", "properties": { "userId": { "description": "Unique identifier of the user.", "type": "string" }, "firstName": { "description": "User's first name after the update.", "type": "string" }, "lastName": { "description": "User's last name after the update.", "type": "string" }, "imageUrl": { "description": "URL of the user's profile image after the update.", "type": "string" }, "address": { "description": "User's address after the update.", "type": "string" }, "email": { "description": "User's email address.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant the user belongs to.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "userId": "u_7b42c1", "firstName": "Erik", "lastName": "Lundqvist", "imageUrl": "https://cdn.surfboard.se/u/7b42c1.png", "address": "Kungsgatan 5, Göteborg", "email": "erik@kaffebaren.se", "merchantId": "m_5f2c1a9b3d" }, "message": "User profile updated successfully." } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "No fields provided to update." } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/merchants/{merchantId}/payment-methods": { "post": { "operationId": "activatePaymentMethod", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payment Methods API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Optional merchant identifier for the payment method configuration.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "description": "Optional store identifier to associate payment methods with a specific store.", "type": "string" }, "terminalId": { "description": "Optional terminal (checkout) identifier to associate the payment methods with a specific terminal.", "type": "string" }, "card": { "description": "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.", "type": "boolean" }, "amex": { "description": "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.", "type": "boolean" }, "swish": { "description": "Swedish mobile payment method configuration. Set to true to enable Swish payments.", "type": "boolean" }, "klarna": { "description": "Buy now, pay later payment method configuration. Set to true to enable Klarna payments.", "type": "boolean" }, "b2binv": { "description": "B2B invoice payment method configuration. Set to true to enable B2B invoice payments.", "type": "boolean" }, "acc2acc": { "description": "Account to account transfer payment method configuration. Set to true to enable account to account transfers.", "type": "boolean" }, "vipps": { "description": "Norwegian mobile payment method. Set to true to enable Vipps payment method.", "type": "boolean" }, "mobilepay": { "description": "Danish mobile payment method. Set to true to enable MobilePay payment method.", "type": "boolean" } } }, "example": { "card": true, "amex": true, "swish": true, "klarna": true, "b2binv": true, "acc2acc": true, "vipps": true, "mobilepay": true } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Array of payment method registration results.", "type": "array", "items": { "type": "object", "properties": { "method": { "description": "The payment method name (e.g., 'amex', 'swish', 'card').", "type": "string" }, "paymentMethodId": { "description": "Unique identifier assigned to the payment method (present on success).", "type": "string" }, "status": { "description": "Registration status for this payment method, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "Error message if registration failed (present on error).", "type": "string" } }, "required": [ "method", "status" ], "additionalProperties": true } }, "message": { "description": "A message that describes the overall status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "method": "b2binv", "paymentMethodId": "838f499c1f7bf00c23", "status": "SUCCESS" }, { "method": "card", "paymentMethodId": "82523116c63be80123", "status": "SUCCESS" }, { "method": "swish", "status": "ERROR", "message": "PM_0010 - Register payment method failed: SWISH registration already exists." }, { "method": "acc2acc", "paymentMethodId": "838f499c1f7bf01c23", "status": "SUCCESS" } ], "message": "Processed payment method registrations" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchAllPaymentMethods", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payment Methods API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "array", "items": { "type": "object", "properties": { "paymentMethodId": { "description": "PaymentMethod ID of the payment method.", "type": "string" }, "paymentMethod": { "description": "Specifies the payment method. It can be one of the following: 'AMEX', 'SWISH', or 'CARD’.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "paymentMethodId": "8235c0a33bd9800223", "paymentMethod": "SWISH" }, { "paymentMethodId": "8235c0943bd9800023", "paymentMethod": "AMEX" } ], "message": "Fetched activated payment methods" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/payment-methods": { "post": { "operationId": "activatePaymentMethodForAStore", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payment Methods API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethod": { "description": "The payment method to activate for the store. Only AMEX and SWISH are accepted at the store level.", "type": "string", "enum": [ null, null ] }, "amexMID": { "description": "American Express merchant id, required when activating the AMEX payment method.", "type": "string" }, "swishNumber": { "description": "The Swish payee number to route Swish payments to, used when activating the SWISH payment method.", "type": "string" }, "acquirerMID": { "description": "Acquirer merchant id to associate with the payment method.", "type": "string" }, "username": { "description": "Provider username used when the payment method requires provider credentials.", "type": "string" }, "password": { "description": "Provider password used when the payment method requires provider credentials.", "type": "string" }, "klarnaMerchantId": { "description": "Klarna merchant id to associate with the payment method.", "type": "string" } }, "required": [ "paymentMethod" ] }, "example": { "paymentMethod": "AMEX", "amexMID": "1234567890" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Array of payment method registration results for the store.", "type": "array", "items": { "type": "object", "properties": { "method": { "description": "The payment method name that was processed (e.g., 'amex', 'swish').", "type": "string" }, "paymentMethodId": { "description": "Unique identifier assigned to the payment method (present on success).", "type": "string" }, "status": { "description": "Registration status for this payment method, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "Error message if registration failed (present on error).", "type": "string" } }, "required": [ "method", "status" ], "additionalProperties": true } }, "message": { "description": "A message that describes the overall status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "method": "amex", "paymentMethodId": "8235c0943bd9800023", "status": "SUCCESS" } ], "message": "Processed payment method registrations" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Invalid payment method type. Must be AMEX or SWISH." } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/payment-methods/{paymentMethodId}": { "delete": { "operationId": "deactivatePaymentMethod", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payment Methods API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "paymentMethodId", "in": "path", "required": true, "description": "Identifier for the payment method this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Deactivated payment method successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to deactivate payment method" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchPaymentMethodDetails", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payment Methods API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "paymentMethodId", "in": "path", "required": true, "description": "Identifier for the payment method this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "paymentMethodId": { "description": "PaymentMethod ID of the payment method.", "type": "string" }, "paymentMethod": { "description": "Specifies the payment method. It can be one of the following: 'AMEX', 'SWISH', or 'CARD’.", "type": "string" }, "status": { "description": "Status of the payment method, indicated as either ACTIVATED' or 'DEACTIVATED’.", "type": "string" }, "amexMID": { "description": "Returns AMEX MID for AMEX payment method.", "type": "string" }, "acquirerMID": { "description": "Returns the respective Acquirer MID for CARD payment method.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "paymentMethodId": "8235c0943bd9800023", "paymentMethod": "AMEX", "status": "ACTIVATED", "amexMID": "abcedefg" }, "message": "Fetched payment method successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/all-payment-methods": { "get": { "operationId": "fetchPaymentMethodsWithStatus", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payment Methods API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The payment methods configured for the merchant.", "type": "array", "items": { "type": "object", "properties": { "paymentMethodId": { "description": "PaymentMethod ID of the payment method.", "type": "string" }, "paymentMethod": { "description": "Specifies the payment method, for example 'AMEX', 'SWISH', or 'CARD'.", "type": "string" }, "paymentStatus": { "description": "Activation status of the payment method, indicated as either 'ACTIVATED' or 'DEACTIVATED'.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "paymentMethodId": "8235c0a33bd9800223", "paymentMethod": "SWISH", "paymentStatus": "ACTIVATED" }, { "paymentMethodId": "8235c0943bd9800023", "paymentMethod": "AMEX", "paymentStatus": "DEACTIVATED" } ], "message": "Fetched all payment methods for merchant" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch payment methods for merchant" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/payment-methods/list": { "get": { "operationId": "listPaymentMethods", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payment Methods API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The payment methods configured for the merchant.", "type": "array", "items": { "type": "object", "properties": { "paymentMethodId": { "description": "PaymentMethod ID of the payment method.", "type": "string" }, "paymentMethod": { "description": "Specifies the payment method, for example 'AMEX', 'SWISH', or 'CARD'.", "type": "string" }, "paymentStatus": { "description": "Activation status of the payment method, indicated as either 'ACTIVATED' or 'DEACTIVATED'.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "paymentMethodId": "8235c0a33bd9800223", "paymentMethod": "SWISH", "paymentStatus": "ACTIVATED" }, { "paymentMethodId": "8235c0943bd9800023", "paymentMethod": "AMEX", "paymentStatus": "DEACTIVATED" } ], "message": "Fetched all payment methods for merchant" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch payment methods for merchant" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/payments": { "post": { "operationId": "initiateAPayment", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payments API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethod": { "description": "Specifies the method in which the payment is to be processed.\n\nValues:\n- `CARD`: Use this payment method to make card transactions for the order.\n- `CARD_NP`: Use this payment method to process card-not-present (CNP) refunds for the order.\n- `KLARNA`: Make payments using Klarna.\n- `CTOKEN`: Use this payment method to make payments using tokenised card if available. Used during online payments.\n- `GIFTCARD`: Use this to make payments with gift cards/vouchers.\n- `SWISH`: Take the payment via Swish. Requires paymentMethodParams.payeePhoneNumber.", "type": "string", "enum": [ "CARD", "CARD_NP", "KLARNA", "CTOKEN", "GIFTCARD", "SWISH" ] }, "orderId": { "description": "Unique identifier of the order to initiate payment for.", "type": "string" }, "terminalId": { "description": "Unique identifier of the terminal that initiates the payment, used for in-store and card-present flows.", "type": "string" }, "amount": { "description": "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.", "type": "number" }, "initialOrderReference": { "description": "Reference to an original order, used for follow-up or linked payments.", "type": "string" }, "adjustments": { "description": "List of order-level monetary adjustments to apply to the payment.", "type": "array", "items": { "type": "object", "properties": { "adjustmentAmount": { "description": "Mandatory monetary value of the adjustment in the smallest currency unit.", "type": "number" }, "amount": { "description": "Optional explicit monetary amount for the adjustment in the smallest currency unit, distinct from the mandatory adjustmentAmount.", "type": "number" }, "adjustmentType": { "description": "Type or category of the adjustment, such as tip or discount.", "type": "string" }, "metadata": { "description": "Arbitrary key/value metadata attached to the adjustment.", "type": "object", "additionalProperties": true }, "createdBy": { "description": "Identifier of the actor who created the adjustment.", "type": "string" } }, "required": [ "adjustmentAmount", "adjustmentType" ] } }, "paymentMethodParams": { "description": "Method-specific parameters for the chosen payment method.", "type": "object", "properties": { "tokenId": { "description": "Saved-card or payment token identifier to charge for tokenised card payments.", "type": "string" }, "bic": { "description": "The BIC (Bank Identifier Code) is an ISO 9362 standard that uniquely identifies a bank, used for account-to-account and bank payments.", "type": "string" }, "ip": { "description": "Customer IP address used as risk and fraud context.", "type": "string" }, "swishMode": { "description": "Swish flow variant or mode selector (e.g., ECOM).", "type": "string" }, "payeePhoneNumber": { "description": "Payee phone number for Swish payments.", "type": "object", "properties": { "code": { "description": "International dialing code (e.g., 46 for Sweden without '+').", "type": "string" }, "number": { "description": "National subscriber number.", "type": "string" } }, "required": [ "code", "number" ] }, "giftCardId": { "description": "Identifier of the gift card to redeem.", "type": "string" }, "invoice": { "description": "Invoice payment configuration.", "type": "object", "properties": { "invoiceDistribution": { "description": "Channel used to deliver the invoice (e.g., EMAIL).", "type": "string" }, "contractReference": { "description": "Reference to the underlying contract or agreement.", "type": "string" }, "debtCollectionEnabled": { "description": "Whether unpaid invoices are sent to debt collection.", "type": "boolean" }, "dueDate": { "description": "Relative due date for the invoice as a chrono expression (e.g., 30d).", "type": "string" }, "invoicePaymentMethods": { "description": "Permitted payment methods for settling the invoice.\n\nValues:\n- `BANK`: Standard bank transfer initiated manually by the payer.\n- `DIRECT_BANK`: Automated account-to-account (A2A) transfer using open banking or similar mechanisms.\n- `CARD`: Payment made via credit or debit cards through a supported card network.", "type": "array", "items": {} }, "reminder": { "description": "Whether a payment reminder should be sent.", "type": "boolean" } } } } }, "serialSplitPaymentsMode": { "description": "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. Not live yet.", "type": "array", "items": {} }, "refundProcessingParams": { "description": "Refund metadata used when processing refunds. Conditionally required: see the endpoint notes.", "type": "object", "properties": { "purchasePaymentId": { "description": "Identifier of the original purchase payment being refunded.", "type": "string" }, "refundReason": { "description": "Reason for the refund request.\n\nValues:\n- `CUSTOMER_INITIATED_RETURN`: This type of refund refers to when a customer initiates a return of a product or service they purchased.\n- `SUSPECTED_MALFUNCTION`: When there is a suspected system malfunction which demands a return request, this type is used.\n- `SUSPECTED_FRAUD`: When there is a suspected irregularity/fraud requiring a return request, this type is used.\n- `DUPLICATE_TRANSACTION`: This type of refund request is submitted when there are duplicate transactions noticed in the system.\n- `OTHER`: The \"OTHER\" refund request type encompasses any refund request that does not fit into the specific categories mentioned above.", "type": "string", "enum": [ "CUSTOMER_INITIATED_RETURN", "SUSPECTED_MALFUNCTION", "SUSPECTED_FRAUD", "DUPLICATE_TRANSACTION", "OTHER" ] }, "otherReason": { "description": "Free-text reason for the return request when it does not fall into any of the predefined categories.", "type": "string" } } }, "language": { "description": "Client or SDK short language code (e.g., fi, no) used to resolve the Klarna session locale.", "type": "string" } }, "required": [ "paymentMethod", "orderId" ] }, "example": { "orderId": "838ca7fc6d7de9770b", "paymentMethod": "CARD" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "paymentId": { "description": "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.", "type": "string" }, "interAppJWT": { "description": "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.", "type": "string" }, "paymentUrl": { "description": "Direct URL for payment processing.", "type": "string" }, "qr": { "description": "QR code data for payment.", "type": "string" }, "qrData": { "description": "Raw QR code data for payment processing.", "type": "string" }, "qrVisibleFor": { "description": "Duration for which the QR code remains visible.", "type": "string" }, "qrLink": { "description": "Link to the QR code for payment.", "type": "string" }, "klarnaClientToken": { "description": "Client token for Klarna payment processing.", "type": "string" }, "paymentToken": { "description": "Token for payment processing.", "type": "string" }, "sveaInitiationParams": { "description": "Initiation parameters for Svea payment processing.", "type": "string" }, "epassiInitiationParams": { "description": "Initiation parameters for Epassi payment processing.", "type": "string" }, "invoiceDetails": { "description": "Invoice details for the payment when applicable.", "type": "object", "properties": { "invoiceId": { "description": "Unique identifier for the invoice.", "type": "number" }, "invoicePdfUrl": { "description": "URL to download the invoice PDF.", "type": "string" }, "iban": { "description": "International Bank Account Number for the invoice.", "type": "string" }, "accountHolderName": { "description": "Name of the account holder for the invoice.", "type": "string" }, "bic": { "description": "Bank Identifier Code for the invoice.", "type": "string" }, "bankgiro": { "description": "Bankgiro number to pay the invoice to.", "type": "string" }, "ocr": { "description": "OCR reference number to quote when paying the invoice.", "type": "string" } }, "additionalProperties": true }, "adjustmentsSummary": { "description": "Summary of the adjustments applied to the payment.", "type": "object", "properties": { "totalAmount": { "description": "Total amount of all applied adjustments in the smallest currency unit.", "type": "number" }, "count": { "description": "Number of adjustments applied to the payment.", "type": "number" }, "adjustments": { "description": "Individual adjustments applied to the payment.", "type": "array", "items": { "type": "object", "properties": { "amount": { "description": "Amount of the adjustment in the smallest currency unit.", "type": "number" }, "type": { "description": "Type or category of the adjustment, such as tip or discount.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "required": [ "paymentId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "paymentId": "811f9bd48c6eb80c06", "interAppJWT": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvaWQiOiI4MzA0NDdkM2U3NGQwMDBiMGIiLCJ0aWQiOiI4MmZmN2MyNTgxNDhkODA1MDQiLCJwaWQiOiI4MzA0NGIzNzAzZmVkODAxMDYiLCJwbSI6IkNBUkQiLCJhIjoxMDAwLCJjIjoiNzUyIiwiY29udHJvbEZ1bmN0aW9uc0VuY29kZXIiOiIxIiwiaXNzdWVkQnkiOiJzYi5wcyIsImlhdCI6MTc0MjIyMTI5NDE1NH0.ftXsXUKmNl-ck47jXKPIa1WXbmH0gbiM8nUAOjBbb0U", "invoiceDetails": { "invoiceId": 1024, "invoicePdfUrl": "https://invoices.example.com/811f9bd48c6eb80c06.pdf", "iban": "SE3550000000054910000003", "accountHolderName": "Surfboard AB", "bic": "ESSESESS", "bankgiro": "5050-1055", "ocr": "1234567890123" }, "adjustmentsSummary": { "totalAmount": 100, "count": 1, "adjustments": [ { "amount": 100, "type": "tip" } ] } }, "message": "Payment initiated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/payments/{paymentId}/status": { "get": { "operationId": "checkPaymentStatus", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payments API" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "description": "Identifier for the payment this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "paymentStatus": { "description": "High-level lifecycle status of the payment, such as PAYMENT_COMPLETED, PAYMENT_FAILED, or PAYMENT_CANCELLED.", "type": "string" }, "failureReason": { "description": "Reason the payment failed, when applicable.", "type": "string" }, "transactionId": { "description": "Identifier of the transaction associated with the payment.", "type": "string" }, "transactionDetails": { "description": "Detailed transaction information, included when the payment has completed.", "type": "object", "properties": { "transactionId": { "description": "Identifier of the completed transaction.", "type": "string" }, "terminalId": { "description": "Identifier of the terminal that processed the transaction.", "type": "string" }, "rrn": { "description": "Retrieval reference number for the transaction.", "type": "string" }, "amount": { "description": "Amount of the transaction.", "type": "string" }, "currency": { "description": "Currency of the transaction.", "type": "string" }, "method": { "description": "Payment method used for the transaction.", "type": "string" }, "truncatedPan": { "description": "Masked card number used for the transaction.", "type": "string" }, "cardLabel": { "description": "Label of the card used for the transaction.", "type": "string" }, "posEntryMode": { "description": "Point-of-sale entry mode of the transaction.", "type": "string" }, "aid": { "description": "Application identifier of the card application used.", "type": "string" }, "customerResponseCode": { "description": "Response code returned for the customer.", "type": "string" }, "cvmMethod": { "description": "Cardholder verification method applied.", "type": "string" }, "authMode": { "description": "Authorization mode of the transaction.", "type": "string" }, "cardBrand": { "description": "Brand of the card used for the transaction.", "type": "string" }, "terminalVerificationResult": { "description": "Terminal verification result of the transaction.", "type": "string" }, "cvmMethodDescription": { "description": "Human-readable description of the cardholder verification method.", "type": "string" }, "authCode": { "description": "Authorization code returned for the transaction.", "type": "string" } }, "additionalProperties": true } }, "required": [ "paymentStatus" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "paymentStatus": "PAYMENT_COMPLETED", "transactionId": "82ff7c258148d80504", "transactionDetails": { "transactionId": "82ff7c258148d80504", "terminalId": "82ff7c258148d80504", "rrn": "000123456789", "amount": "1000", "currency": "752", "method": "CARD", "truncatedPan": "************1234", "cardLabel": "VISA", "posEntryMode": "07", "aid": "A0000000031010", "customerResponseCode": "00", "cvmMethod": "PIN", "authMode": "AUTH", "cardBrand": "VISA", "terminalVerificationResult": "0000008000", "cvmMethodDescription": "Online PIN", "authCode": "123456" } }, "message": "Payment status fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/payments/{paymentId}": { "get": { "operationId": "getPaymentDetails", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payments API" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "description": "Identifier for the payment this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "description": "Language used for any localized receipt content. Defaults to en.", "schema": { "description": "Language used for any localized receipt content. Defaults to en.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "paymentId": { "description": "Unique identifier of the payment.", "type": "string" }, "orderId": { "description": "Identifier of the order this payment belongs to.", "type": "string" }, "checkoutId": { "description": "Identifier of the checkout this payment belongs to.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant.", "type": "string" }, "storeId": { "description": "Identifier of the store.", "type": "string" }, "transactionId": { "description": "Identifier of the underlying card transaction.", "type": "string" }, "purchasePaymentId": { "description": "Identifier of the original purchase payment this record relates to.", "type": "string" }, "requestId": { "description": "Identifier of the request that created the payment.", "type": "string" }, "externalRequestId": { "description": "External request identifier supplied by the caller.", "type": "string" }, "amount": { "description": "Payment amount, in minor units.", "type": "string" }, "currency": { "description": "ISO 4217 alpha currency code of the payment (e.g. SEK).", "type": "string" }, "paymentType": { "description": "Type of the payment (for example PURCHASE).", "type": "string" }, "paymentMethod": { "description": "Payment method used for the payment.", "type": "string" }, "paymentStatus": { "description": "Current status of the payment.", "type": "string" }, "cardBrand": { "description": "Card brand used for the payment (for example VISA).", "type": "string" }, "payeePhoneNumber": { "description": "Phone number of the payee, when applicable.", "type": "string" }, "terminalMessage": { "description": "Message shown on the terminal for the payment.", "type": "string" }, "terminalCode": { "description": "Terminal code(s) associated with the payment.", "type": "array", "items": {} }, "userMessageId": { "description": "Identifier of the localized user message for the payment.", "type": "string" }, "voided": { "description": "Whether the payment has been voided.", "type": "boolean" }, "voidStatus": { "description": "Void status of the payment (for example NOT_INITIATED, VOID_INITIATED, VOIDED, CANNOT_VOID).", "type": "string" }, "voidRequestedAt": { "description": "Timestamp when a void was requested for the payment.", "type": "string" }, "createdAt": { "description": "Timestamp when the payment record was created.", "type": "string" }, "firstEntryTime": { "description": "Timestamp of the first entry for the payment.", "type": "string" }, "createdBy": { "description": "Identifier of the actor that created the payment record.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "paymentId": "811f9bd48c6eb80c06", "orderId": "838ca7fc6d7de9770b", "checkoutId": "83044b3703fed80106", "merchantId": "82ff7c258148d80504", "storeId": "83044b3703fed80106", "transactionId": "82ff7c258148d80504", "requestId": "84b1c2d3e4f5a60789", "amount": "1000", "currency": "SEK", "paymentType": "PURCHASE", "paymentMethod": "CARD", "paymentStatus": "PAYMENT_COMPLETED", "cardBrand": "VISA", "terminalMessage": "Approved", "terminalCode": [ "000" ], "voided": false, "voidStatus": "NOT_INITIATED", "createdAt": "2026-06-17T10:15:00.000Z" }, "message": "Payment details fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "delete": { "operationId": "cancelAPayment", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payments API" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "description": "Identifier for the payment this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "paymentStatus": { "description": "Describes the status of the payment. The possible values are:\n\nValues:\n- `PAYMENT_COMPLETED`: The payment was completed and cannot be cancelled.\n- `PAYMENT_FAILED`: Cannot cancel a failed payment.\n- `PAYMENT_CANCELLED`: The payment attempt has been cancelled.", "type": "string", "enum": [ "PAYMENT_COMPLETED", "PAYMENT_FAILED", "PAYMENT_CANCELLED" ] } }, "required": [ "paymentStatus" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "paymentStatus": "PAYMENT_CANCELLED" }, "message": "Payment cancelled successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/payments/{paymentId}/void": { "put": { "operationId": "voidAPayment", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payments API" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "description": "Identifier for the payment this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "voidStatus": { "description": "Depicts the status of the void command.\n\nValues:\n- `NOT_INITIATED`: Void has not been initiated for the payment.\n- `VOID_INITIATED`: Void is initiated.\n- `CANNOT_VOID`: The payment cannot be voided either because the transaction is not completed or the void period has exceeded. Voids need to be initiated before 23:50 CET on the same date as the transaction.\n- `VOIDED`: Void is completed.", "type": "string", "enum": [ "NOT_INITIATED", "VOID_INITIATED", "CANNOT_VOID", "VOIDED" ] }, "message": { "description": "Message describing the outcome of the void request.", "type": "string" } }, "required": [ "voidStatus" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "voidStatus": "VOID_INITIATED", "message": "Void initiated successfully" }, "message": "payment void status successfully retrieved from external API" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/payments/{paymentId}/capture": { "post": { "operationId": "capturePayment", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payments API" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "description": "Identifier for the payment this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Payment captured successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "checkCaptureStatus", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payments API" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "description": "Identifier for the payment this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "captureStatus": { "description": "Denotes the status of the capture request for payment.\n\nValues:\n- `PENDING`: Payment yet to be captured.\n- `SUCCESS`: Payment captured successfully.\n- `ERROR`: Error encountered while processing capture request.", "type": "string", "enum": [ "PENDING", "SUCCESS", "ERROR" ] } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "captureStatus": "SUCCESS" }, "message": "Capture status fetched successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/payments/{paymentId}/complete": { "put": { "operationId": "completePayment", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payments API" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "description": "Identifier for the payment this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "paymentStatus": { "description": "Lifecycle status of the payment after completion, such as PAYMENT_COMPLETED.", "type": "string" } }, "required": [ "paymentStatus" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "paymentStatus": "PAYMENT_COMPLETED" }, "message": "Payment completed successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/payments/{paymentId}/klarna/place-order": { "post": { "operationId": "placeKlarnaOrder", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payments API" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "description": "Identifier for the payment this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethod": { "description": "Payment method that identifies the Klarna flow.\n\nValues:\n- `KLARNA`: Identifies the Klarna payment flow.", "type": "string", "enum": [ "KLARNA" ] }, "authorizationToken": { "description": "Klarna authorization token returned by the Klarna SDK after the customer authorizes.", "type": "string" } }, "required": [ "paymentMethod", "authorizationToken" ] }, "example": { "paymentMethod": "KLARNA", "authorizationToken": "b4bd3423-24e3-4e5d-bc08-2e1e9d1d6b6c" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "orderId": { "description": "Identifier of the Klarna order created from the authorization token.", "type": "string" } }, "required": [ "orderId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "orderId": "838ca7fc6d7de9770b" }, "message": "Klarna order placed successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/payments/{paymentId}/update/payment-method": { "put": { "operationId": "updatePaymentMethod", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Payments API" ], "parameters": [ { "name": "paymentId", "in": "path", "required": true, "description": "Identifier for the payment this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethod": { "description": "New payment method to set on the payment.\n\nValues:\n- `CARD`: Use this payment method to make card transactions for the order.\n- `CARD_NP`: Use this payment method to process card-not-present (CNP) refunds for the order.\n- `KLARNA`: Make payments using Klarna.\n- `CTOKEN`: Use this payment method to make payments using tokenised card if available. Used during online payments.\n- `GIFTCARD`: Use this to make payments with gift cards/vouchers.\n- `SWISH`: Take the payment via Swish.", "type": "string", "enum": [ "CARD", "CARD_NP", "KLARNA", "CTOKEN", "GIFTCARD", "SWISH" ] }, "params": { "description": "Additional initiation-style parameters to apply with the new payment method.", "type": "object", "properties": { "paymentMethod": { "description": "Payment method to apply within the re-initiation parameters; provided separately from the root paymentMethod field.\n\nValues:\n- `CARD`: Use this payment method to make card transactions for the order.\n- `CARD_NP`: Use this payment method to process card-not-present (CNP) refunds for the order.\n- `KLARNA`: Make payments using Klarna.\n- `CTOKEN`: Use this payment method to make payments using tokenised card if available. Used during online payments.\n- `GIFTCARD`: Use this to make payments with gift cards/vouchers.\n- `SWISH`: Take the payment via Swish.", "type": "string", "enum": [ "CARD", "CARD_NP", "KLARNA", "CTOKEN", "GIFTCARD", "SWISH" ] }, "orderId": { "description": "Identifier of the order the updated payment is for.", "type": "string" }, "terminalId": { "description": "Unique identifier of the terminal initiating the updated payment.", "type": "string" }, "amount": { "description": "Amount to charge with the new method in the smallest currency unit.", "type": "number" }, "initialOrderReference": { "description": "Reference to an original order.", "type": "string" }, "adjustments": { "description": "List of order-level monetary adjustments to apply to the payment.", "type": "array", "items": { "type": "object", "properties": { "adjustmentAmount": { "description": "Mandatory monetary value of the adjustment in the smallest currency unit.", "type": "number" }, "amount": { "description": "Optional explicit monetary amount for the adjustment in the smallest currency unit, distinct from the mandatory adjustmentAmount.", "type": "number" }, "adjustmentType": { "description": "Type or category of the adjustment, such as tip or discount.", "type": "string" }, "metadata": { "description": "Arbitrary key/value metadata attached to the adjustment.", "type": "object", "additionalProperties": true }, "createdBy": { "description": "Identifier of the actor who created the adjustment.", "type": "string" } }, "required": [ "adjustmentAmount", "adjustmentType" ] } }, "refundProcessingParams": { "description": "Refund metadata used when processing refunds.", "type": "object", "properties": { "purchasePaymentId": { "description": "Identifier of the original purchase payment being refunded.", "type": "string" }, "refundReason": { "description": "Reason for the refund request.\n\nValues:\n- `CUSTOMER_INITIATED_RETURN`: This type of refund refers to when a customer initiates a return of a product or service they purchased.\n- `SUSPECTED_MALFUNCTION`: When there is a suspected system malfunction which demands a return request, this type is used.\n- `SUSPECTED_FRAUD`: When there is a suspected irregularity/fraud requiring a return request, this type is used.\n- `DUPLICATE_TRANSACTION`: This type of refund request is submitted when there are duplicate transactions noticed in the system.\n- `OTHER`: The \"OTHER\" refund request type encompasses any refund request that does not fit into the specific categories mentioned above.", "type": "string", "enum": [ "CUSTOMER_INITIATED_RETURN", "SUSPECTED_MALFUNCTION", "SUSPECTED_FRAUD", "DUPLICATE_TRANSACTION", "OTHER" ] }, "otherReason": { "description": "Free-text reason for the return request when it does not fall into any of the predefined categories.", "type": "string" } } }, "serialSplitPaymentsMode": { "description": "An array of amounts in smallest currency unit to split the payment serially across multiple charges.", "type": "array", "items": {} }, "paymentMethodParams": { "description": "Method-specific parameters for the chosen payment method.", "type": "object", "properties": { "tokenId": { "description": "Saved-card or payment token identifier to charge for tokenised card payments.", "type": "string" }, "bic": { "description": "The BIC (Bank Identifier Code) is an ISO 9362 standard that uniquely identifies a bank, used for account-to-account and bank payments.", "type": "string" }, "ip": { "description": "Customer IP address used as risk and fraud context.", "type": "string" }, "swishMode": { "description": "Swish flow variant or mode selector (e.g., ECOM).", "type": "string" }, "payeePhoneNumber": { "description": "Payee phone number for Swish payments.", "type": "object", "properties": { "code": { "description": "International dialing code (e.g., 46 for Sweden without '+').", "type": "string" }, "number": { "description": "National subscriber number.", "type": "string" } }, "required": [ "code", "number" ] }, "giftCardId": { "description": "Identifier of the gift card to redeem.", "type": "string" }, "invoice": { "description": "Invoice payment configuration.", "type": "object", "properties": { "invoiceDistribution": { "description": "Channel used to deliver the invoice (e.g., EMAIL).", "type": "string" }, "contractReference": { "description": "Reference to the underlying contract or agreement.", "type": "string" }, "debtCollectionEnabled": { "description": "Whether unpaid invoices are sent to debt collection.", "type": "boolean" }, "dueDate": { "description": "Relative due date for the invoice as a chrono expression (e.g., 30d).", "type": "string" }, "reminder": { "description": "Whether a payment reminder should be sent.", "type": "boolean" }, "invoicePaymentMethods": { "description": "Permitted payment methods for settling the invoice.\n\nValues:\n- `BANK`: Standard bank transfer initiated manually by the payer.\n- `DIRECT_BANK`: Automated account-to-account (A2A) transfer using open banking or similar mechanisms.\n- `CARD`: Payment made via credit or debit cards through a supported card network.", "type": "array", "items": {} } } } } }, "language": { "description": "Client or SDK short language code used to resolve the Klarna session locale.", "type": "string" }, "message": { "description": "Free-text message attached to the update.", "type": "string" }, "initialOrderId": { "description": "Identifier of the original order being updated.", "type": "string" } }, "required": [ "paymentMethod", "orderId" ] } }, "required": [ "paymentMethod" ] }, "example": { "paymentMethod": "KLARNA", "params": { "paymentMethod": "KLARNA", "orderId": "838ca7fc6d7de9770b" } } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "paymentId": { "description": "Identifier of the updated payment.", "type": "string" }, "paymentStatus": { "description": "Lifecycle status of the payment after the method update.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "paymentId": "811f9bd48c6eb80c06", "paymentStatus": "PAYMENT_INITIATED" }, "message": "Payment method updated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/catalog": { "post": { "operationId": "createProductCatalog", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "description": "Unique identifier of the store where the catalog will be created.", "type": "string" }, "startDate": { "description": "Date the catalog becomes active, in ISO 8601 format. When omitted, the catalog has no start date.", "type": "string" }, "endDate": { "description": "Date the catalog expires, in ISO 8601 format. When omitted, the catalog has no end date.", "type": "string" } }, "required": [ "storeId" ] }, "example": { "storeId": "8136a645a2c2d1bb0f" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "catalogId": { "description": "Unique ID of the newly created catalog.", "type": "string" } }, "required": [ "catalogId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "catalogId": "8219688f18ebb8020a" }, "message": "Product catalog created successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "get": { "operationId": "fetchProductCatalogs", "summary": "Fetch Product Catalogs", "description": "Retrieves all product catalogs under the store.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "catalogIds": { "description": "List of product catalog IDs existing under the store.", "type": "array", "items": {} } }, "required": [ "catalogIds" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "catalogIds": [ "8187c051854a38000a", "818a5d4df1c258090a", "818bb06b93a5500b0a", "818f9f37bd0b58040a" ] }, "message": "Product catalog fetched for storeId: 8136a645a2c2d1bb0f" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/catalog/{catalogId}/products": { "post": { "operationId": "createProduct", "summary": "Create Product", "description": "This API allows you to create a product in the product catalog.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "description": "Unique identifier of the store where the product will be created.", "type": "string" }, "name": { "description": "Name of the product.", "type": "string" }, "type": { "description": "A Product can exist in two ways as the following,\n\nValues:\n- `PRODUCT`: Its refers to tangible things sold for the exchange of a fee.\n- `SERVICE`: Refers to action provided in exchange for a fee.", "type": "string", "enum": [ "PRODUCT", "SERVICE" ] }, "unitType": { "description": "This refers to the way a product is measured or quantified.\n\nValues:\n- `FIXED_UNIT`: Pre-packaged products sold in fixed units.\n- `VARIABLE_UNIT`: Product sold by weight or volume.\n- `FREE_UNIT`: Products priced at checkout.", "type": "string", "enum": [ "FIXED_UNIT", "VARIABLE_UNIT", "FREE_UNIT" ] }, "costPrice": { "description": "Cost price of the product, in the smallest unit of the currency (e.g. öre for SEK).", "type": "number" }, "sellingPrice": { "description": "Selling price of the product, in the smallest unit of the currency (e.g. öre for SEK).", "type": "number" }, "currencyCode": { "description": "It refers to the standardised code used to represent a specific currency.", "type": "string" }, "tax": { "description": "Array of taxes.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Type of tax that applies to the product.\n\nValues:\n- `VAT`: Value-added tax.\n- `CGST`: Central goods and services tax.\n- `SGST`: State goods and services tax.\n- `GST`: Goods and services tax.", "type": "string", "enum": [ "VAT", "CGST", "SGST", "GST" ] }, "percentage": { "description": "Percentage of the tax for the product.", "type": "string" }, "amount": { "description": "Fixed tax amount for the product, in the smallest unit of the currency.", "type": "number" } } } }, "description": { "description": "Description of the product.", "type": "string" }, "unit": { "description": "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'.", "type": "string" }, "category": { "description": "Free-text category the product is grouped under.", "type": "string" }, "categoryId": { "description": "Identifier of an existing category to file the product under.", "type": "string" }, "discount": { "description": "Discount applied to the product, in the smallest unit of the currency.", "type": "number" }, "productImages": { "description": "An array of URLs showcasing the product.", "type": "array", "items": {} }, "hsnCode": { "description": "A 6-digit uniform code that identifies the product.", "type": "string" }, "barcode": { "description": "Encoded white and black lines on the product.", "type": "string" }, "baseAttributes": { "description": "Variant attribute definitions for the product.", "type": "array", "items": { "type": "object", "properties": { "attributeLabel": { "description": "Human-readable label for the attribute, for example Color.", "type": "string" }, "attributeKey": { "description": "Machine key for the attribute, for example color.", "type": "string" } } } }, "attributeValues": { "description": "Values assigned to the product for each attribute.", "type": "array", "items": { "type": "object", "properties": { "attributeKey": { "description": "Attribute key the value belongs to.", "type": "string" }, "displayName": { "description": "Human-readable name of the value.", "type": "string" }, "value": { "description": "The attribute value itself.", "type": "string" } } } }, "productProperties": { "description": "Additional properties that help describe the product like size, origin, weight, manufacturer, etc.", "type": "object", "additionalProperties": true }, "metadata": { "description": "Free-form key/value metadata you can attach to the product for your own use.", "type": "object", "additionalProperties": true }, "monthlyPlans": { "description": "Refers to the charges of the product or service for a specific time period.", "type": "object", "properties": { "description": { "description": "Description of the billing plan.", "type": "string" }, "amount": { "description": "Amount of the plan, in the smallest unit of the currency.", "type": "number" }, "currency": { "description": "It refers to the standardised code used to represent a specific currency.", "type": "string" }, "interval": { "description": "This refers to the time period of the billing plan.", "type": "string" }, "intervalCount": { "description": "Duration of the plan.", "type": "number" }, "recurring": { "description": "Denotes if the billing plan should repeat at regular intervals.", "type": "boolean" }, "bindingPeriod": { "description": "A binding period is a set timeframe for a billing plan to which the customer is expected to adhere.", "type": "number" }, "earlyTerminationPenalty": { "description": "It is the additional amount charged in case of early termination if applicable.", "type": "number" }, "earlyTermination": { "description": "Defines the intended action to be taken if the plan is terminated early.\n\nValues:\n- `NO_PENALTY`: No penalty charged for early termination.\n- `BALANCE_AMOUNT`: Customer has to pay the balance amount if terminated early.\n- `BALANCE_AMOUNT_PLUS_PENALTY`: Customer has to pay the remaining amount plus a penalty amount.", "type": "string", "enum": [ "NO_PENALTY", "BALANCE_AMOUNT", "BALANCE_AMOUNT_PLUS_PENALTY" ] } }, "required": [ "description" ] } }, "required": [ "storeId", "name", "type", "unitType", "sellingPrice", "unit", "productImages" ] }, "example": { "storeId": "8136a645a2c2d1bb0f", "name": "SurfPad Purple Logo", "type": "PRODUCT", "unitType": "FIXED_UNIT", "costPrice": 2000, "sellingPrice": 4500, "currencyCode": "752", "tax": [ { "type": "VAT", "percentage": "25" } ], "description": "SurfPad Payment Terminal in Purple", "category": "electronics", "unit": "nos", "productImages": [ "https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg" ], "hsnCode": "723453", "barcode": "7812123454323" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "productId": { "description": "Unique ID of the newly added product.", "type": "string" } }, "required": [ "productId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "productId": "81c30d16df28880301" }, "message": "Product created successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "get": { "operationId": "fetchAllProducts", "summary": "Fetch all products", "description": "This API allows you to retrieve all products associated with a product catalog.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "object", "properties": { "products": { "description": "Details of the products.", "type": "array", "items": { "type": "object", "properties": { "productId": { "description": "ID of the product.", "type": "string" }, "name": { "description": "Name of the product.", "type": "string" }, "currencyCode": { "description": "It refers to the standardised code used to represent a specific currency.", "type": "string" }, "description": { "description": "Description of the product.", "type": "string" }, "category": { "description": "Category the product is grouped under.", "type": "string" }, "unit": { "description": "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'.", "type": "string" }, "productImages": { "description": "An array of URLs showcasing the product images.", "type": "array", "items": {} }, "discount": { "description": "Discount applied to the product, in the smallest unit of the currency.", "type": "number" }, "hsnCode": { "description": "A 6-digit uniform code that identifies the product.", "type": "string" }, "barcode": { "description": "Encoded white and black lines on the products.", "type": "string" }, "variantCategory": { "description": "The variant categories defined for the product.", "type": "array", "items": {} }, "productProperties": { "description": "Additional properties that describe the product details, which include type, size, origin, weight, manufacturer, etc.", "type": "object", "additionalProperties": true }, "inventory": { "description": "Defines the information about the stock levels of the products listed in the catalog.", "type": "object", "additionalProperties": true }, "unitType": { "description": "This specifies the general representation of quantity based on the product details and they have possible types.\n\nValues:\n- `FIXED_UNIT`: Pre-packaged products sold in fixed units.\n- `VARIABLE_UNIT`: Products sold by weight or volume.\n- `FREE_UNIT`: Products priced at checkout.", "type": "string", "enum": [ "FIXED_UNIT", "VARIABLE_UNIT", "FREE_UNIT" ] }, "type": { "description": "Whether the item is a PRODUCT or a SERVICE.", "type": "string" }, "relatedProducts": { "description": "Identifiers of products tagged as related to this product.", "type": "array", "items": {} }, "sellingPrice": { "description": "Selling price of the product, in the smallest unit of the currency.", "type": "number" }, "variants": { "description": "Variants of the product.", "type": "array", "items": {} }, "billingPlans": { "description": "Recurring billing plans available for the product.", "type": "array", "items": {} }, "tax": { "description": "Array of taxes.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Type of tax that applies to the product, for example VAT.", "type": "string" }, "percentage": { "description": "Percentage of the tax for the product.", "type": "string" }, "amount": { "description": "Fixed tax amount for the product, in the smallest unit of the currency.", "type": "number" } }, "required": [ "type", "percentage", "amount" ], "additionalProperties": true } }, "attributeValues": { "description": "Attribute values assigned to the product.", "type": "array", "items": { "type": "object", "properties": { "attributeKey": { "description": "Key of the attribute.", "type": "string" }, "displayName": { "description": "Display name of the attribute.", "type": "string" }, "value": { "description": "Value of the attribute.", "type": "string" } }, "required": [ "attributeKey", "displayName", "value" ], "additionalProperties": true } }, "campaignInfo": { "description": "Information of campaign.", "type": "array", "items": { "type": "object", "properties": { "campaignName": { "description": "Name of the campaign.", "type": "string" }, "campaignId": { "description": "ID of the campaign.", "type": "string" }, "fixedAmount": { "description": "Reduced price during the campaign, in the smallest unit of the currency.", "type": "number" }, "percentage": { "description": "Percentage discount applied during the campaign.", "type": "string" } }, "required": [ "campaignName", "campaignId", "fixedAmount", "percentage" ], "additionalProperties": true } }, "metadata": { "description": "Free-form key/value metadata attached to the product.", "type": "object", "additionalProperties": true } }, "required": [ "productId", "name", "currencyCode", "description", "category", "unit", "productImages", "discount", "hsnCode", "barcode", "variantCategory", "productProperties", "inventory", "unitType", "type", "relatedProducts", "sellingPrice", "variants", "billingPlans", "tax", "attributeValues", "campaignInfo", "metadata" ], "additionalProperties": true } }, "bundles": { "description": "Refers to the products grouped together in a category.", "type": "array", "items": {} } }, "required": [ "products", "bundles" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "products": [ { "productId": "823913d474de600e01", "name": "SurfPad Black Logo", "currencyCode": "752", "description": "SurfPad Payment Terminal in Black", "category": "electronics", "unit": "nos", "productImages": [ "https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg" ], "hsnCode": "723453", "barcode": "7812123454323", "productProperties": { "size": "15x5 cm", "origin": "sweden", "weight": "250 g", "manufacturer": "datecs" }, "inventory": {}, "unitType": "FIXED_UNIT", "type": "PRODUCT", "relatedProducts": [], "sellingPrice": 1500, "variants": [], "billingPlans": [], "tax": [ { "type": "VAT", "percentage": "25", "amount": 0 } ], "campaignInfo": [ { "campaignName": "First campaign", "campaignId": "8239b16f0a59580224", "fixedAmount": 2000, "percentage": null } ] } ], "bundles": [] }, "message": "Products fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/catalog/{catalogId}/products/{productId}": { "patch": { "operationId": "updateProduct", "summary": "Update Product", "description": "You can use this API to modify the products.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "description": "Unique identifier of the store where the product exists.", "type": "string" }, "name": { "description": "Name of the product.", "type": "string" }, "costPrice": { "description": "Cost price of the product.", "type": "number" }, "sellingPrice": { "description": "Selling price of the product.", "type": "number" }, "description": { "description": "Description of the product.", "type": "string" }, "category": { "description": "This refers to a grouping of similar products that share a common characteristics.", "type": "string" }, "unit": { "description": "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'.", "type": "string" }, "productImages": { "description": "An array of URLs showcasing the product images.", "type": "array", "items": {} }, "hsnCode": { "description": "A 6-digit uniform code that identifies the product.", "type": "string" }, "barcode": { "description": "Encoded white and black lines on the products.", "type": "string" } }, "required": [ "storeId" ] }, "example": { "storeId": "8136a645a2c2d1bb0f", "name": "SurfPad Black Logo", "costPrice": 0, "sellingPrice": 1500, "description": "SurfPad Payment Terminal in Black", "category": "electronics", "unit": "nos", "productImages": [ "https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg" ], "hsnCode": "723453", "barcode": "7812123454323" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Product updated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "get": { "operationId": "fetchProductById", "summary": "Fetch Product by Id", "description": "This API allows you to retrieve a specific product by its ID.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing the product details.", "type": "object", "properties": { "id": { "description": "Unique identifier of the product.", "type": "string" }, "name": { "description": "Name of the product.", "type": "string" }, "sellingPrice": { "description": "Selling price of the product.", "type": "number" }, "currencyCode": { "description": "Currency code for the product price.", "type": "string" }, "description": { "description": "Description of the product.", "type": "string" }, "category": { "description": "Category of the product.", "type": "string" }, "popularity": { "description": "Popularity score of the product.", "type": "number" }, "unit": { "description": "Unit of measurement for the product.", "type": "string" }, "hsnCode": { "description": "HSN code of the product.", "type": "string" }, "barcode": { "description": "Barcode of the product.", "type": "string" }, "type": { "description": "Type of the product.", "type": "string" }, "unitType": { "description": "Unit type of the product.", "type": "string" }, "attributeValues": { "description": "Array of attribute values for the product.", "type": "array", "items": { "type": "object", "properties": { "attributeKey": { "description": "Key of the attribute.", "type": "string" }, "displayName": { "description": "Display name of the attribute.", "type": "string" }, "value": { "description": "Value of the attribute.", "type": "string" } }, "required": [ "attributeKey", "displayName", "value" ], "additionalProperties": true } }, "tax": { "description": "Array of tax information for the product.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Type of tax.", "type": "string" }, "percentage": { "description": "Tax percentage.", "type": "string" }, "amount": { "description": "Tax amount, in the smallest unit of the currency.", "type": "number" } }, "required": [ "type", "percentage", "amount" ], "additionalProperties": true } }, "productImages": { "description": "Image URLs for the product.", "type": "array", "items": {} }, "productProperties": { "description": "Free-form key/value properties describing the product.", "type": "object", "additionalProperties": true }, "inventory": { "description": "Current stock information for the product.", "type": "object", "additionalProperties": true }, "relatedProducts": { "description": "Identifiers of products tagged as related to this product.", "type": "array", "items": {} }, "pricingPlans": { "description": "Recurring pricing plans available for the product.", "type": "array", "items": {} }, "distributors": { "description": "Distributors that supply the product.", "type": "array", "items": {} }, "campaignInfo": { "description": "Active campaigns on the product.", "type": "array", "items": {} }, "variants": { "description": "Variants of the product.", "type": "array", "items": {} }, "metadata": { "description": "Free-form key/value metadata attached to the product.", "type": "object", "additionalProperties": true } }, "required": [ "id", "name", "sellingPrice", "currencyCode", "description", "category", "popularity", "unit", "hsnCode", "barcode", "type", "unitType", "attributeValues", "tax", "productImages", "productProperties", "inventory", "relatedProducts", "pricingPlans", "distributors", "campaignInfo", "variants", "metadata" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "id": "838bfc15a601800901", "name": "Test Product", "sellingPrice": 14900, "currencyCode": "752", "description": "Sitter som en smäck", "category": "TERMINAL", "popularity": 0, "unit": "nos", "hsnCode": "", "barcode": "", "type": "PRODUCT", "unitType": "FIXED_UNIT", "attributeValues": [ { "attributeKey": "storlek", "displayName": "Storlek XL", "value": "XL" } ], "tax": [ { "type": "VAT", "percentage": "25", "amount": 0 } ], "productImages": [], "productProperties": {}, "inventory": {}, "relatedProducts": [], "campaignInfo": [], "variants": [] }, "message": "Products fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "delete": { "operationId": "deleteProduct", "summary": "Delete Product", "description": "Remove a product from a catalog. Pass the store the product belongs to as a query parameter.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "query", "required": true, "description": "Identifier of the store the product belongs to.", "schema": { "description": "Identifier of the store the product belongs to.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Product for merchant removed successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/catalog/{catalogId}/products/{productId}/variants": { "post": { "operationId": "addVariantForProduct", "summary": "Add Variant For Product", "description": "This API allows you to add a variant to an existing product in the product catalog.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "description": "Unique identifier of the store where the product exists.", "type": "string" }, "variants": { "description": "Specifications of the product.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Name of the variant.", "type": "string" }, "description": { "description": "Description of the variant.", "type": "string" }, "popularity": { "description": "Popularity score of the variant.", "type": "number" }, "costPrice": { "description": "Cost price of the variant, in the smallest unit of the currency.", "type": "number" }, "sellingPrice": { "description": "Selling price of the variant, in the smallest unit of the currency.", "type": "number" }, "currencyCode": { "description": "It refers to the standardised code used to represent a specific currency.", "type": "string" }, "productImages": { "description": "An array of URLs showcasing the variant images.", "type": "array", "items": {} }, "baseAttributes": { "description": "Variant attribute definitions for the variant.", "type": "array", "items": { "type": "object", "properties": { "attributeLabel": { "description": "Human-readable label for the attribute, for example Color.", "type": "string" }, "attributeKey": { "description": "Machine key for the attribute, for example color.", "type": "string" } }, "required": [ "attributeLabel", "attributeKey" ] } }, "attributeValues": { "description": "Use to show the available variants of the products.", "type": "array", "items": { "type": "object", "properties": { "attributeKey": { "description": "This refers to the category of the variant.", "type": "string" }, "displayName": { "description": "Name of the variant.", "type": "string" }, "value": { "description": "Value of the variant.", "type": "string" } }, "required": [ "attributeKey", "displayName", "value" ] } }, "variantProperties": { "description": "Free-form key/value properties describing the variant, such as size, weight or origin.", "type": "object", "additionalProperties": true }, "metadata": { "description": "Free-form key/value metadata you can attach to the variant for your own use.", "type": "object", "additionalProperties": true } }, "required": [ "name", "attributeValues" ] } } }, "required": [ "storeId", "variants" ] }, "example": { "storeId": "8136a645a2c2d1bb0f", "variants": [ { "name": "SurfPad Blue Variant", "description": "Blue variant of SurfPad", "costPrice": 1000, "sellingPrice": 1200, "currencyCode": "752", "productImages": [ "https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg" ], "attributeValues": [ { "attributeKey": "colour", "displayName": "blue", "value": "#0000FF" }, { "attributeKey": "size", "displayName": "medium", "value": "M" } ] } ] } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "variants": { "description": "Unique ID of the newly added variants.", "type": "array", "items": {} } }, "required": [ "variants" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "variants": [ "81c319b6c7d2080807" ] }, "message": "Variants added successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/catalog/{catalogId}/products/{productId}/related-products": { "post": { "operationId": "addRelatedProducts", "summary": "Add Related Products", "description": "This API helps you to tag the product with other relatable products in the catalog.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "description": "Unique identifier of the store where the product exists.", "type": "string" }, "relatedProducts": { "description": "An array of product Id's.", "type": "array", "items": {} } }, "required": [ "storeId", "relatedProducts" ] }, "example": { "storeId": "8136a645a2c2d1bb0f", "relatedProducts": [ "818f9fc43d0b580f01" ] } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Related Products for merchant added successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "get": { "operationId": "getRelatedProducts", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The product and its related products.", "type": "object", "properties": { "productId": { "description": "Identifier of the product the related products belong to.", "type": "string" }, "relatedProducts": { "description": "The products tagged as related.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique identifier of the related product.", "type": "string" }, "name": { "description": "Name of the related product.", "type": "string" }, "description": { "description": "Description of the related product.", "type": "string" }, "sellingPrice": { "description": "Selling price of the related product, in the smallest unit of the currency.", "type": "number" }, "currencyCode": { "description": "Currency the price is expressed in.", "type": "string" }, "productImages": { "description": "Image URLs for the related product.", "type": "array", "items": {} }, "type": { "description": "Whether the related item is a PRODUCT or a SERVICE.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "productId": "81c30d16df28880301", "relatedProducts": [ { "id": "818f9fc43d0b580f01", "name": "SurfPad Charging Dock", "description": "Charging dock for the SurfPad terminal", "sellingPrice": 1200, "currencyCode": "752", "productImages": [ "https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg" ], "type": "PRODUCT" } ] }, "message": "Related products fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "patch": { "operationId": "updateRelatedProducts", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "relatedProducts": { "description": "The product identifiers that should be tagged as related. Sending an empty array clears the related products.", "type": "array", "items": {} } } }, "example": { "relatedProducts": [ "818f9fc43d0b580f01", "818f9fc43d0b580f02" ] } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The result of the update.", "type": "object", "properties": { "productId": { "description": "Identifier of the product that was updated.", "type": "string" }, "updatedCount": { "description": "Number of related products now tagged on the product.", "type": "number" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "productId": "81c30d16df28880301", "updatedCount": 2 }, "message": "Related products updated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "delete": { "operationId": "removeRelatedProducts", "summary": "Remove Related Products", "description": "Remove one or more products from the set tagged as related to a given product.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "relatedProducts", "in": "query", "required": false, "description": "The product identifiers to remove from the related products list.", "schema": { "description": "The product identifiers to remove from the related products list.", "type": "array", "items": {} } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The result of the removal.", "type": "object", "properties": { "productId": { "description": "Identifier of the product that was updated.", "type": "string" }, "removedCount": { "description": "Number of related products removed from the product.", "type": "number" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "productId": "81c30d16df28880301", "removedCount": 1 }, "message": "Related products removed successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/catalog/{catalogId}/products/{productId}/inventory": { "patch": { "operationId": "updateProductInventory", "summary": "Update Product Inventory", "description": "Update available stocks in the product inventory using this API.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "description": "Unique identifier of the store where the product exists.", "type": "string" }, "operation": { "description": "Defines the way in which the existing stock is modified.\n\nValues:\n- `STOCK_UP`: Indicates an addition to the currently available stock.\n- `STOCK_DOWN`: Decrease the quantity in available stock.", "type": "string", "enum": [ "STOCK_UP", "STOCK_DOWN" ] }, "quantity": { "description": "Defines the number of units of a specific product that are available in stock.", "type": "number" }, "unit": { "description": "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'.", "type": "string" } }, "required": [ "storeId", "operation", "quantity", "unit" ] }, "example": { "storeId": "8136a645a2c2d1bb0f", "operation": "STOCK_UP", "quantity": 10, "unit": "nos" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Inventory updated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/catalog/{catalogId}/products/{productId}/variants/{variantId}": { "patch": { "operationId": "updateVariant", "summary": "Update Variant", "description": "You can use this API to modify the product variants.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "variantId", "in": "path", "required": true, "description": "Identifier for the variant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "description": "Unique identifier of the store where the variant exists.", "type": "string" }, "name": { "description": "Name of the variant.", "type": "string" }, "costPrice": { "description": "Cost price of the variant.", "type": "number" }, "sellingPrice": { "description": "Selling price of the variant.", "type": "number" }, "description": { "description": "Description of the variant.", "type": "string" }, "category": { "description": "This refers to a grouping of similar variants that share a common characteristics.", "type": "string" }, "unit": { "description": "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'.", "type": "string" }, "productImages": { "description": "Product images for the variant.", "type": "array", "items": {} }, "hsnCode": { "description": "A 6-digit uniform code that identifies the variant.", "type": "string" }, "barcode": { "description": "Encoded white and black lines on the variants.", "type": "string" }, "variantProperties": { "description": "Denotes the additional properties that describe the variant details which includes type, size, origin, weight, manufacturer, etc.", "type": "object", "additionalProperties": true } }, "required": [ "storeId" ] }, "example": { "storeId": "8136a645a2c2d1bb0f", "name": "SurfPad Black Logo - Large", "costPrice": 0, "sellingPrice": 1800, "description": "SurfPad Payment Terminal in Black - Large Size", "category": "electronics", "unit": "nos", "productImages": [ "https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg" ], "hsnCode": "723453", "barcode": "7812123454323" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Variant updated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/catalog/{catalogId}/products/{productId}/variants/{variantId}/inventory": { "patch": { "operationId": "updateVariantInventory", "summary": "Update Variant Inventory", "description": "Update available stocks in the variant inventory using this API.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "variantId", "in": "path", "required": true, "description": "Identifier for the variant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "description": "Unique identifier of the store where the variant exists.", "type": "string" }, "operation": { "description": "Defines the way in which the existing variant stock is modified.\n\nValues:\n- `STOCK_UP`: Indicates an addition to the currently available variant stock.\n- `STOCK_DOWN`: Decrease the quantity in available variant stock.", "type": "string", "enum": [ "STOCK_UP", "STOCK_DOWN" ] }, "quantity": { "description": "Defines the number of units of a specific variant that are available in stock.", "type": "number" }, "unit": { "description": "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'.", "type": "string" } }, "required": [ "storeId", "operation", "quantity", "unit" ] }, "example": { "storeId": "8136a645a2c2d1bb0f", "operation": "STOCK_UP", "quantity": 15, "unit": "nos" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Variant inventory updated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/catalog/ai/description": { "post": { "operationId": "generateProductDescription", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productName": { "description": "Name of the product for which to generate the description.", "type": "string" }, "maxWordLength": { "description": "Maximum number of words for the generated description.", "type": "number" }, "langCode": { "description": "Language code for the description generation (e.g., 'en' for English).", "type": "string" } }, "required": [ "productName" ] }, "example": { "productName": "Addidas Running Shoes", "maxWordLength": 150, "langCode": "en" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing the generated description.", "type": "object", "properties": { "description": { "description": "AI-generated product description.", "type": "string" } }, "required": [ "description" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "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." }, "message": "Description generated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/catalog/ai/image": { "post": { "operationId": "generateProductImages", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productName": { "description": "Name of the product for which to generate images.", "type": "string" }, "prompt": { "description": "Custom prompt describing the desired image characteristics and style.", "type": "string" }, "noOfImages": { "description": "Number of images to generate for the product.", "type": "number" }, "langCode": { "description": "Language code for image generation context (e.g., 'en' for English).", "type": "string" } }, "required": [ "productName", "langCode" ] }, "example": { "productName": "Gaming Laptop", "prompt": "sleek modern design with RGB lighting", "noOfImages": 3, "langCode": "en" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing the generated image paths.", "type": "object", "properties": { "imagePath": { "description": "Array of URLs pointing to the generated product images.", "type": "array", "items": {} } }, "required": [ "imagePath" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "imagePath": [ "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", "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" ] }, "message": "Images generated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/catalog/ai/scan": { "post": { "operationId": "generateProductCatalogFromImages", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "imgData": { "description": "Array of image URLs or base64 encoded image data to process.", "type": "array", "items": {} }, "imageType": { "description": "Array of image file types corresponding to the imgData array (e.g., 'png', 'jpg').", "type": "array", "items": {} } }, "required": [ "imgData", "imageType" ] }, "example": { "imgData": [ "https://storage.googleapis.com/sb-merchant-portal-ai-images/testMerchant/TestMenu/menu01.png" ], "imageType": [ "png" ] } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing extracted menu and product information.", "type": "object", "properties": { "menuData": { "description": "Array of extracted product/menu items with their details.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Name of the product or menu item.", "type": "string" }, "description": { "description": "Description of the product or menu item.", "type": "string" }, "sellingPrice": { "description": "Price of the product or menu item.", "type": "string" }, "currencyCode": { "description": "Currency code for the price (e.g., '840' for USD).", "type": "string" }, "category": { "description": "Category classification of the product or menu item.", "type": "string" }, "image": { "description": "URL of the generated or associated product image.", "type": "string" } }, "required": [ "name", "description", "sellingPrice", "currencyCode", "category", "image" ], "additionalProperties": true } } }, "required": [ "menuData" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "menuData": [ [ { "name": "The Junior", "description": "Two eggs any way, your choice of bacon, sausage, or ham, and coffee or tea.", "sellingPrice": "8.50", "currencyCode": "840", "category": "Breakfast Mains", "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" }, { "name": "Buttermilk or Buckwheat Pancakes", "description": "Fluffy pancakes with a choice of bacon or maple sausage.", "sellingPrice": "8.00", "currencyCode": "840", "category": "Breakfast Mains", "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" } ] ] }, "message": "Menu data extracted successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/catalog/{catalogId}/products/{productId}/statistics": { "get": { "operationId": "getProductStatistics", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing product statistics.", "type": "object", "properties": { "productId": { "description": "Unique identifier of the product.", "type": "string" }, "productName": { "description": "Name of the product.", "type": "string" }, "unit": { "description": "Unit of measurement for the product.", "type": "string" }, "query": { "description": "The date range used for filtering statistics.", "type": "object", "properties": { "startDate": { "description": "Start date of the statistics period in YYYY-MM-DD format.", "type": "string" }, "endDate": { "description": "End date of the statistics period in YYYY-MM-DD format.", "type": "string" } }, "required": [ "startDate", "endDate" ], "additionalProperties": true }, "statistics": { "description": "Sales and performance statistics for the product.", "type": "object", "properties": { "byCurrency": { "description": "Statistics broken down by currency.", "type": "array", "items": { "type": "object", "properties": { "currency": { "description": "Currency code.", "type": "string" }, "totalUnitsSold": { "description": "Total number of units sold.", "type": "number" }, "totalUnitsReturned": { "description": "Total number of units returned.", "type": "number" }, "totalRevenue": { "description": "Total revenue generated.", "type": "number" }, "totalVat": { "description": "Total VAT collected.", "type": "number" }, "totalCampaignDiscount": { "description": "Total campaign discount applied.", "type": "number" }, "orderCount": { "description": "Total number of orders containing this product.", "type": "number" }, "averageOrderValue": { "description": "Average order value for orders containing this product.", "type": "number" } }, "required": [ "currency", "totalUnitsSold", "totalUnitsReturned", "totalRevenue", "totalVat", "totalCampaignDiscount", "orderCount", "averageOrderValue" ], "additionalProperties": true } }, "netUnitsSold": { "description": "Net units sold after accounting for returns.", "type": "number" } }, "required": [ "byCurrency", "netUnitsSold" ], "additionalProperties": true }, "inventoryStatus": { "description": "Current inventory status of the product.", "type": "object", "properties": { "currentStock": { "description": "Current stock quantity available.", "type": "number" }, "stockIn": { "description": "Total stock added during the period.", "type": "number" }, "stockOut": { "description": "Total stock removed during the period.", "type": "number" } }, "required": [ "currentStock", "stockIn", "stockOut" ], "additionalProperties": true }, "vatBreakdown": { "description": "VAT breakdown by percentage.", "type": "array", "items": { "type": "object", "properties": { "vatPercentage": { "description": "VAT percentage applied.", "type": "string" }, "vatAmount": { "description": "Total VAT amount collected at this percentage.", "type": "number" }, "taxableAmount": { "description": "Total taxable amount at this percentage.", "type": "number" } }, "required": [ "vatPercentage", "vatAmount", "taxableAmount" ], "additionalProperties": true } }, "variants": { "description": "Statistics for each product variant.", "type": "array", "items": { "type": "object", "properties": { "variantId": { "description": "Unique identifier of the variant.", "type": "string" }, "variantName": { "description": "Name of the variant.", "type": "string" }, "unit": { "description": "Unit of measurement for the variant.", "type": "string" }, "byCurrency": { "description": "Variant statistics broken down by currency.", "type": "array", "items": {} }, "inventoryStatus": { "description": "Current inventory status of the variant.", "type": "object", "additionalProperties": true }, "vatBreakdown": { "description": "VAT breakdown for the variant.", "type": "array", "items": {} } }, "required": [ "variantId", "variantName", "unit", "byCurrency", "inventoryStatus", "vatBreakdown" ], "additionalProperties": true } } }, "required": [ "productId", "productName", "unit", "query", "statistics", "inventoryStatus", "vatBreakdown", "variants" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "productId": "838bfc15a601800901", "productName": "Test Product", "unit": "nos", "query": { "startDate": "2025-09-17", "endDate": "2025-12-17" }, "statistics": { "byCurrency": [], "netUnitsSold": 0 }, "inventoryStatus": { "currentStock": 0, "stockIn": 0, "stockOut": 0 }, "vatBreakdown": [], "variants": [] }, "message": "Product statistics fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/catalog/{catalogId}/statistics": { "get": { "operationId": "getProductCatalogStatistics", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing catalog statistics.", "type": "object", "properties": { "productCatalogId": { "description": "Unique identifier of the product catalog.", "type": "string" }, "productCatalogName": { "description": "Name of the product catalog.", "type": "string" }, "query": { "description": "The date range used for filtering statistics.", "type": "object", "properties": { "startDate": { "description": "Start date of the statistics period in YYYY-MM-DD format.", "type": "string" }, "endDate": { "description": "End date of the statistics period in YYYY-MM-DD format.", "type": "string" } }, "required": [ "startDate", "endDate" ], "additionalProperties": true }, "summary": { "description": "Summary statistics for the entire catalog.", "type": "object", "properties": { "totalProducts": { "description": "Total number of products in the catalog.", "type": "number" }, "totalVariants": { "description": "Total number of variants across all products.", "type": "number" }, "byCurrency": { "description": "Summary statistics broken down by currency.", "type": "array", "items": { "type": "object", "properties": { "currency": { "description": "Currency code.", "type": "string" }, "totalUnitsSold": { "description": "Total number of units sold.", "type": "number" }, "totalUnitsReturned": { "description": "Total number of units returned.", "type": "number" }, "totalRevenue": { "description": "Total revenue generated.", "type": "number" }, "totalVat": { "description": "Total VAT collected.", "type": "number" }, "totalCampaignDiscount": { "description": "Total campaign discount applied.", "type": "number" }, "orderCount": { "description": "Total number of orders.", "type": "number" }, "averageOrderValue": { "description": "Average order value.", "type": "number" } }, "required": [ "currency", "totalUnitsSold", "totalUnitsReturned", "totalRevenue", "totalVat", "totalCampaignDiscount", "orderCount", "averageOrderValue" ], "additionalProperties": true } } }, "required": [ "totalProducts", "totalVariants", "byCurrency" ], "additionalProperties": true }, "vatBreakdown": { "description": "VAT breakdown by percentage for the entire catalog.", "type": "array", "items": { "type": "object", "properties": { "vatPercentage": { "description": "VAT percentage applied.", "type": "string" }, "vatAmount": { "description": "Total VAT amount collected at this percentage.", "type": "number" }, "taxableAmount": { "description": "Total taxable amount at this percentage.", "type": "number" } }, "required": [ "vatPercentage", "vatAmount", "taxableAmount" ], "additionalProperties": true } }, "topSellingProducts": { "description": "List of top-selling products in the catalog.", "type": "array", "items": { "type": "object", "properties": { "productId": { "description": "Unique identifier of the product.", "type": "string" }, "productName": { "description": "Name of the product.", "type": "string" }, "totalUnitsSold": { "description": "Total number of units sold for this product.", "type": "number" }, "totalRevenue": { "description": "Total revenue generated by this product.", "type": "number" }, "currencyBreakdown": { "description": "Sales breakdown by currency for this product.", "type": "array", "items": { "type": "object", "properties": { "currency": { "description": "Currency code.", "type": "string" }, "totalUnitsSold": { "description": "Total units sold in this currency.", "type": "number" }, "totalRevenue": { "description": "Total revenue in this currency.", "type": "number" } }, "required": [ "currency", "totalUnitsSold", "totalRevenue" ], "additionalProperties": true } } }, "required": [ "productId", "productName", "totalUnitsSold", "totalRevenue", "currencyBreakdown" ], "additionalProperties": true } } }, "required": [ "productCatalogId", "query", "summary", "vatBreakdown", "topSellingProducts" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "productCatalogId": "8372ed4bc2c0000b0a", "productCatalogName": "Electronics & Accessories", "query": { "startDate": "2025-07-01", "endDate": "2025-12-01" }, "summary": { "totalProducts": 5, "totalVariants": 2, "byCurrency": [ { "currency": "666", "totalUnitsSold": 17, "totalUnitsReturned": 0, "totalRevenue": 20000, "totalVat": 1130, "totalCampaignDiscount": 0, "orderCount": 5, "averageOrderValue": 4000 }, { "currency": "752", "totalUnitsSold": 120, "totalUnitsReturned": 0, "totalRevenue": 120000, "totalVat": 6780, "totalCampaignDiscount": 0, "orderCount": 30, "averageOrderValue": 4000 } ] }, "vatBreakdown": [ { "vatPercentage": "6", "vatAmount": 7910, "taxableAmount": 140000 } ], "topSellingProducts": [ { "productId": "8372ed51c2c0000701", "productName": "Wireless Bluetooth Headphones", "totalUnitsSold": 92, "totalRevenue": 92000, "currencyBreakdown": [ { "currency": "752", "totalUnitsSold": 92, "totalRevenue": 92000 } ] }, { "productId": "8393dbb7e836b00a01", "productName": "USB-C Charging Cable", "totalUnitsSold": 44, "totalRevenue": 44000, "currencyBreakdown": [ { "currency": "752", "totalUnitsSold": 28, "totalRevenue": 28000 }, { "currency": "666", "totalUnitsSold": 16, "totalRevenue": 16000 } ] }, { "productId": "83757823162fe00501", "productName": "Portable Power Bank 10000mAh", "totalUnitsSold": 1, "totalRevenue": 4000, "currencyBreakdown": [ { "currency": "666", "totalUnitsSold": 1, "totalRevenue": 4000 } ] } ] }, "message": "Product catalog statistics fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/catalog/{catalogId}/products/{productId}/campaign": { "post": { "operationId": "addProductCampaign", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaignName": { "description": "Name of the campaign shown to staff and customers.", "type": "string" }, "storeId": { "description": "Identifier of the store the product belongs to.", "type": "string" }, "price": { "description": "The discount the campaign applies. Provide either a fixed amount or a percentage.", "type": "object", "properties": { "fixedAmount": { "description": "Reduced price during the campaign, in the smallest unit of the currency (e.g. öre for SEK).", "type": "number" }, "percentage": { "description": "Percentage discount applied during the campaign.", "type": "number" } } } }, "required": [ "campaignName", "storeId", "price" ] }, "example": { "campaignName": "Summer Sale", "storeId": "8136a645a2c2d1bb0f", "price": { "fixedAmount": 3500 } } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The created campaign.", "type": "object", "properties": { "campaignId": { "description": "Unique identifier of the newly created campaign.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "campaignId": "8239b16f0a59580224" }, "message": "Added product campaign for merchant successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/catalog/{catalogId}/products/{productId}/campaign/{campaignId}": { "delete": { "operationId": "removeProductCampaign", "summary": "Remove Product Campaign", "description": "Remove a promotional campaign from a product, ending the discount it applied.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "campaignId", "in": "path", "required": true, "description": "Identifier for the campaign this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "query", "required": true, "description": "Identifier of the store the product belongs to.", "schema": { "description": "Identifier of the store the product belongs to.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Removed product campaign for merchant successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/catalog/{catalogId}/products/{productId}/ai/description": { "post": { "operationId": "generateDescriptionForExistingProduct", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxWordLength": { "description": "Maximum number of words in the generated description.", "type": "number" }, "langCode": { "description": "Language to generate the description in (e.g. 'en' for English).", "type": "string" } } }, "example": { "maxWordLength": 150, "langCode": "en" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The generated description.", "type": "object", "properties": { "description": { "description": "AI-generated product description.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "description": "Experience effortless payments with the SurfPad terminal, engineered for speed, reliability, and a clean checkout every time." }, "message": "Description generated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/catalog/{catalogId}/products/{productId}/ai/image": { "post": { "operationId": "generateImagesForExistingProduct", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "catalogId", "in": "path", "required": true, "description": "Identifier for the catalog this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Identifier for the product this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "description": "Optional prompt describing the desired look and style of the images.", "type": "string" }, "noOfImages": { "description": "Number of images to generate.", "type": "number" }, "langCode": { "description": "Language context for image generation (e.g. 'en' for English).", "type": "string" } } }, "example": { "prompt": "sleek modern product shot on a white background", "noOfImages": 2, "langCode": "en" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The generated images.", "type": "object", "properties": { "imagePath": { "description": "URLs pointing to the generated product images.", "type": "array", "items": {} } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "imagePath": [ "https://storage.googleapis.com/sb-merchant-portal-ai-images/example_1.png", "https://storage.googleapis.com/sb-merchant-portal-ai-images/example_2.png" ] }, "message": "Image generated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/partners/{partnerId}/product-catalogue": { "get": { "operationId": "fetchProductsForPartner", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Product Catalog API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The products and bundles on the current page.", "type": "object", "properties": { "products": { "description": "The partner's products.", "type": "array", "items": { "type": "object", "properties": { "productId": { "description": "Unique identifier of the product.", "type": "string" }, "name": { "description": "Name of the product.", "type": "string" }, "currencyCode": { "description": "Currency the prices are expressed in.", "type": "string" }, "description": { "description": "Description of the product.", "type": "string" }, "category": { "description": "Category the product is grouped under.", "type": "string" }, "unit": { "description": "Unit of measurement for the product.", "type": "string" }, "productImages": { "description": "Image URLs for the product.", "type": "array", "items": {} }, "discount": { "description": "Discount applied to the product, in the smallest unit of the currency.", "type": "number" }, "hsnCode": { "description": "Harmonized System (HSN) code classifying the product for tax.", "type": "string" }, "barcode": { "description": "Barcode value printed on the product.", "type": "string" }, "variantCategory": { "description": "The variant categories defined for the product.", "type": "array", "items": {} }, "productProperties": { "description": "Free-form key/value properties describing the product.", "type": "object", "additionalProperties": true }, "inventory": { "description": "Current stock information for the product.", "type": "object", "additionalProperties": true }, "unitType": { "description": "How the product is priced and quantified (FIXED_UNIT, VARIABLE_UNIT or FREE_UNIT).", "type": "string" }, "type": { "description": "Whether the item is a PRODUCT or a SERVICE.", "type": "string" }, "relatedProducts": { "description": "Identifiers of products tagged as related.", "type": "array", "items": {} }, "sellingPrice": { "description": "Selling price of the product, in the smallest unit of the currency.", "type": "number" }, "variants": { "description": "Variants of the product.", "type": "array", "items": {} }, "billingPlans": { "description": "Recurring billing plans available for the product.", "type": "array", "items": {} }, "tax": { "description": "Tax lines that apply to the product.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Type of tax, for example VAT.", "type": "string" }, "percentage": { "description": "Tax rate as a percentage.", "type": "string" }, "amount": { "description": "Fixed tax amount, in the smallest unit of the currency.", "type": "number" } }, "additionalProperties": true } }, "attributeValues": { "description": "Attribute values assigned to the product.", "type": "array", "items": {} }, "campaignInfo": { "description": "Active campaigns on the product.", "type": "array", "items": { "type": "object", "properties": { "campaignName": { "description": "Name of the campaign.", "type": "string" }, "campaignId": { "description": "Identifier of the campaign.", "type": "string" }, "fixedAmount": { "description": "Reduced price during the campaign, in the smallest unit of the currency.", "type": "number" }, "percentage": { "description": "Percentage discount applied during the campaign.", "type": "string" } }, "additionalProperties": true } }, "metadata": { "description": "Free-form key/value metadata attached to the product.", "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "bundles": { "description": "Bundles that group several products together.", "type": "array", "items": {} } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "products": [ { "productId": "823913d474de600e01", "name": "SurfPad Black Logo", "currencyCode": "752", "sellingPrice": 1500, "description": "SurfPad Payment Terminal in Black", "category": "electronics", "unit": "nos", "productImages": [ "https://res.cloudinary.com/martinsurf/image/upload/v1619101937/surfboardpayments/surfboard-icon.svg" ], "unitType": "FIXED_UNIT", "type": "PRODUCT", "variants": [], "tax": [ { "type": "VAT", "percentage": "25", "amount": 0 } ] } ], "bundles": [] }, "message": "Products for partner fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to process request" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/merchants/{merchantId}/promotions/v2": { "post": { "operationId": "createPromotion", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Promotions API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "The unique identifier of the merchant the promotion belongs to.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "A name used to identify the promotion in the dashboard.", "type": "string" }, "promoType": { "description": "The promotion mechanism. This is fixed at creation and cannot be changed later.\n\nValues:\n- `PROMO_CODE`: A discount the customer redeems with a code, configured in `promoCode`.\n- `REDIRECT_LINK`: Sends the customer to a destination URL, configured in `redirectLink`.", "type": "string", "enum": [ "PROMO_CODE", "REDIRECT_LINK" ] }, "schedule": { "description": "The window during which the promotion runs.", "type": "object", "properties": { "startTime": { "description": "ISO-8601 timestamp at which the promotion becomes active.", "type": "string" }, "endTime": { "description": "ISO-8601 timestamp at which the promotion ends.", "type": "string" } }, "required": [ "startTime", "endTime" ] }, "visualAssets": { "description": "The content shown to customers for the promotion. Each item’s `type` determines which of the fields below apply.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "The kind of asset.\n\nValues:\n- `TEXT`: Text content, shown using `headline`, `subheadline`, and `body`.\n- `IMAGE`: An image, shown using `url`.\n- `VIDEO`: A video, shown using `url`.\n- `BUTTON`: A button, shown using `buttonText` and `buttonUrl`.", "type": "string", "enum": [ "TEXT", "IMAGE", "VIDEO", "BUTTON" ] }, "headline": { "description": "The primary line of a TEXT asset.", "type": "string" }, "subheadline": { "description": "The secondary line of a TEXT asset.", "type": "string" }, "body": { "description": "The body copy of a TEXT asset.", "type": "string" }, "url": { "description": "The public URL of an IMAGE or VIDEO asset.", "type": "string" }, "buttonText": { "description": "The label shown on a BUTTON asset.", "type": "string" }, "buttonUrl": { "description": "The URL a BUTTON asset opens when tapped.", "type": "string" } }, "required": [ "type" ] } }, "promoCode": { "description": "The discount configuration for a promo-code promotion.", "type": "object", "properties": { "code": { "description": "The code a customer enters at checkout to redeem the offer (for example, SAVE20).", "type": "string" }, "offer": { "description": "How much the code discounts.", "type": "object", "properties": { "type": { "description": "Whether the discount is a percentage or a fixed amount.\n\nValues:\n- `PERCENTAGE_OFF`: A percentage discount, set by `percentage`.\n- `FIXED_AMOUNT_OFF`: A fixed-value discount, set by `amount`.", "type": "string", "enum": [ "PERCENTAGE_OFF", "FIXED_AMOUNT_OFF" ] }, "percentage": { "description": "The percentage discount to apply (0–100).", "type": "number" }, "amount": { "description": "The fixed discount amount, in the smallest currency unit (for example, 10 SEK is 1000).", "type": "number" } }, "required": [ "type" ] }, "budget": { "description": "The spend limit for the promo code.", "type": "object", "properties": { "maxAmount": { "description": "The maximum total discount the promotion may give away, in the smallest currency unit. When reached, the promotion stops automatically with status BUDGET_DEPLETED.", "type": "number" } }, "required": [ "maxAmount" ] } }, "required": [ "code", "offer", "budget" ] }, "redirectLink": { "description": "The redirect destination for a redirect-link promotion.", "type": "object", "properties": { "url": { "description": "The destination the customer is taken to.", "type": "string" } }, "required": [ "url" ] }, "assignmentRules": { "description": "Conditions an order must satisfy for a customer to be eligible for the promotion.", "type": "object", "properties": { "minimumOrderAmount": { "description": "The minimum order total required, in the smallest currency unit.", "type": "number" }, "itemPresentInOrder": { "description": "The order must contain at least one of these item IDs.", "type": "array", "items": {} }, "categoryPresentInOrder": { "description": "The order must contain at least one item from these category IDs.", "type": "array", "items": {} } } }, "redemptionRules": { "description": "Conditions that must be met at checkout before the discount is applied.", "type": "object", "properties": { "minimumOrderAmount": { "description": "The minimum order total required, in the smallest currency unit.", "type": "number" }, "itemPresentInOrder": { "description": "The order must contain at least one of these item IDs.", "type": "array", "items": {} }, "categoryPresentInOrder": { "description": "The order must contain at least one item from these category IDs.", "type": "array", "items": {} } } }, "usageLimits": { "description": "Limits on how many times the promotion can be redeemed.", "type": "object", "properties": { "maximumRedemptions": { "description": "The total number of redemptions allowed across all customers. Once reached, the promotion stops with status ATTEMPTS_EXHAUSTED.", "type": "number" }, "maximumRedemptionsPerCustomer": { "description": "The number of redemptions allowed per individual customer (for example, 1 for a one-time offer).", "type": "number" } }, "required": [ "maximumRedemptions" ] } }, "required": [ "name", "promoType", "schedule", "visualAssets" ] }, "example": { "name": "Loyalty Boost", "promoType": "PROMO_CODE", "schedule": { "startTime": "2026-08-01T00:00:00Z", "endTime": "2026-08-31T23:59:59Z" }, "visualAssets": [ { "type": "TEXT", "headline": "Members save more", "subheadline": "This August" }, { "type": "BUTTON", "buttonText": "Join now", "buttonUrl": "https://example.com/join" } ], "promoCode": { "code": "AUG10", "offer": { "type": "PERCENTAGE_OFF", "percentage": 10 }, "budget": { "maxAmount": 5000 } }, "assignmentRules": { "minimumOrderAmount": 2500 }, "usageLimits": { "maximumRedemptions": 1000, "maximumRedemptionsPerCustomer": 2 } } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Indicates whether the request succeeded — either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Identifiers for the created promotion.", "type": "object", "properties": { "promotionId": { "description": "The identifier of the new promotion. Use it to fetch, update, assign, sync, or delete the promotion.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "For example, \"Promotion created successfully\".", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "promotionId": "promo_8KzR4pQ7eZ2LvUjH" }, "message": "Promotion created successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/promotions/{promotionId}": { "put": { "operationId": "updatePromotion", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Promotions API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "The unique identifier of the merchant the promotion belongs to.", "schema": { "type": "string" } }, { "name": "promotionId", "in": "path", "required": true, "description": "The promotion to update, as returned when it was created.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "A new name for the promotion.", "type": "string" }, "schedule": { "description": "The window during which the promotion runs.", "type": "object", "properties": { "startTime": { "description": "ISO-8601 timestamp at which the promotion becomes active.", "type": "string" }, "endTime": { "description": "ISO-8601 timestamp at which the promotion ends.", "type": "string" } }, "required": [ "startTime", "endTime" ] }, "visualAssets": { "description": "Replaces the promotion’s display content with this set. Each item’s `type` determines which of the fields below apply.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "The kind of asset.\n\nValues:\n- `TEXT`: Text content, shown using `headline`, `subheadline`, and `body`.\n- `IMAGE`: An image, shown using `url`.\n- `VIDEO`: A video, shown using `url`.\n- `BUTTON`: A button, shown using `buttonText` and `buttonUrl`.", "type": "string", "enum": [ "TEXT", "IMAGE", "VIDEO", "BUTTON" ] }, "headline": { "description": "The primary line of a TEXT asset.", "type": "string" }, "subheadline": { "description": "The secondary line of a TEXT asset.", "type": "string" }, "body": { "description": "The body copy of a TEXT asset.", "type": "string" }, "url": { "description": "The public URL of an IMAGE or VIDEO asset.", "type": "string" }, "buttonText": { "description": "The label shown on a BUTTON asset.", "type": "string" }, "buttonUrl": { "description": "The URL a BUTTON asset opens when tapped.", "type": "string" } }, "required": [ "type" ] } }, "promoCode": { "description": "The discount configuration for a promo-code promotion.", "type": "object", "properties": { "code": { "description": "The code a customer enters at checkout to redeem the offer (for example, SAVE20).", "type": "string" }, "offer": { "description": "How much the code discounts.", "type": "object", "properties": { "type": { "description": "Whether the discount is a percentage or a fixed amount.\n\nValues:\n- `PERCENTAGE_OFF`: A percentage discount, set by `percentage`.\n- `FIXED_AMOUNT_OFF`: A fixed-value discount, set by `amount`.", "type": "string", "enum": [ "PERCENTAGE_OFF", "FIXED_AMOUNT_OFF" ] }, "percentage": { "description": "The percentage discount to apply (0–100).", "type": "number" }, "amount": { "description": "The fixed discount amount, in the smallest currency unit (for example, 10 SEK is 1000).", "type": "number" } }, "required": [ "type" ] }, "budget": { "description": "The spend limit for the promo code.", "type": "object", "properties": { "maxAmount": { "description": "The maximum total discount the promotion may give away, in the smallest currency unit. When reached, the promotion stops automatically with status BUDGET_DEPLETED.", "type": "number" } }, "required": [ "maxAmount" ] } }, "required": [ "code", "offer", "budget" ] }, "redirectLink": { "description": "The redirect destination for a redirect-link promotion.", "type": "object", "properties": { "url": { "description": "The destination the customer is taken to.", "type": "string" } }, "required": [ "url" ] }, "assignmentRules": { "description": "Conditions an order must satisfy for a customer to be eligible for the promotion.", "type": "object", "properties": { "minimumOrderAmount": { "description": "The minimum order total required, in the smallest currency unit.", "type": "number" }, "itemPresentInOrder": { "description": "The order must contain at least one of these item IDs.", "type": "array", "items": {} }, "categoryPresentInOrder": { "description": "The order must contain at least one item from these category IDs.", "type": "array", "items": {} } } }, "redemptionRules": { "description": "Conditions that must be met at checkout before the discount is applied.", "type": "object", "properties": { "minimumOrderAmount": { "description": "The minimum order total required, in the smallest currency unit.", "type": "number" }, "itemPresentInOrder": { "description": "The order must contain at least one of these item IDs.", "type": "array", "items": {} }, "categoryPresentInOrder": { "description": "The order must contain at least one item from these category IDs.", "type": "array", "items": {} } } }, "usageLimits": { "description": "Limits on how many times the promotion can be redeemed.", "type": "object", "properties": { "maximumRedemptions": { "description": "The total number of redemptions allowed across all customers. Once reached, the promotion stops with status ATTEMPTS_EXHAUSTED.", "type": "number" }, "maximumRedemptionsPerCustomer": { "description": "The number of redemptions allowed per individual customer (for example, 1 for a one-time offer).", "type": "number" } }, "required": [ "maximumRedemptions" ] } } }, "example": { "name": "Loyalty Boost (extended)", "schedule": { "startTime": "2026-08-01T00:00:00Z", "endTime": "2026-09-15T23:59:59Z" } } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Indicates whether the request succeeded — either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The updated promotion.", "type": "object", "additionalProperties": true }, "message": { "description": "For example, \"Promotion updated successfully\".", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": {}, "message": "Promotion updated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "delete": { "operationId": "deletePromotion", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Promotions API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "The unique identifier of the merchant the promotion belongs to.", "schema": { "type": "string" } }, { "name": "promotionId", "in": "path", "required": true, "description": "The promotion to delete.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Indicates whether the request succeeded — either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "For example, \"Promotion deleted successfully\".", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Promotion deleted successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "get": { "operationId": "fetchPromotionById", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Promotions API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "The unique identifier of the merchant the promotion belongs to.", "schema": { "type": "string" } }, { "name": "promotionId", "in": "path", "required": true, "description": "The promotion to retrieve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Indicates whether the request succeeded — either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The matching promotion.", "type": "array", "items": { "type": "object", "properties": { "promotionId": { "description": "The unique identifier of the promotion.", "type": "string" }, "name": { "description": "The promotion’s name.", "type": "string" }, "status": { "description": "The current lifecycle state of the promotion.\n\nValues:\n- `ACTIVE`: Currently running — within its schedule, with budget and redemption limits remaining.\n- `CREATED`: Created but not yet started (its start time is in the future).\n- `DEACTIVATED`: Manually switched off by the merchant.\n- `EXPIRED`: Past its end time.\n- `BUDGET_DEPLETED`: Stopped because spend reached the promo code budget.\n- `ATTEMPTS_EXHAUSTED`: Stopped because the redemption limit was reached.", "type": "string", "enum": [ "ACTIVE", "CREATED", "DEACTIVATED", "EXPIRED", "BUDGET_DEPLETED", "ATTEMPTS_EXHAUSTED" ] }, "promoType": { "description": "The promotion mechanism.\n\nValues:\n- `PROMO_CODE`: A discount the customer redeems with a code, configured in `promoCode`.\n- `REDIRECT_LINK`: Sends the customer to a destination URL, configured in `redirectLink`.", "type": "string", "enum": [ "PROMO_CODE", "REDIRECT_LINK" ] }, "appliedTo": { "description": "The kind of entity the promotion applies to (for example, STORE or MERCHANT).", "type": "string" }, "appliedToId": { "description": "The identifier of the entity the promotion applies to.", "type": "string" }, "schedule": { "description": "The promotion’s active window.", "type": "object", "properties": { "startTime": { "description": "ISO-8601 start time.", "type": "string" }, "endTime": { "description": "ISO-8601 end time.", "type": "string" } }, "additionalProperties": true }, "promoCode": { "description": "Present when `promoType` is PROMO_CODE.", "type": "object", "properties": { "code": { "description": "The redeemable code.", "type": "string" }, "offer": { "description": "The discount the code applies.", "type": "object", "properties": { "type": { "description": "Whether the discount is a percentage or a fixed amount.", "type": "string" }, "percentage": { "description": "The percentage off, when the offer is PERCENTAGE_OFF.", "type": "number" }, "amount": { "description": "The fixed amount off, when the offer is FIXED_AMOUNT_OFF.", "type": "number" } }, "additionalProperties": true }, "budget": { "description": "Budget and spend tracking.", "type": "object", "properties": { "maxAmount": { "description": "The spend limit.", "type": "number" }, "currency": { "description": "The currency of the budget figures.", "type": "string" }, "spentAmount": { "description": "How much of the budget has been used so far.", "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true }, "redirectLink": { "description": "Present when `promoType` is REDIRECT_LINK.", "type": "object", "properties": { "url": { "description": "The destination URL.", "type": "string" }, "sharableIdleLink": { "description": "A generated short link for display on the idle screen.", "type": "string" }, "sharablePrinterLink": { "description": "A generated short link for printed receipts.", "type": "string" } }, "additionalProperties": true }, "usageLimits": { "description": "The redemption limits.", "type": "object", "properties": { "maximumRedemptions": { "description": "The total redemption limit.", "type": "number" }, "maximumRedemptionsPerCustomer": { "description": "The per-customer redemption limit (may be null).", "type": "number" } }, "additionalProperties": true }, "visualAssets": { "description": "The promotion’s display assets.", "type": "array", "items": {} }, "createdAt": { "description": "When the promotion was created.", "type": "string" }, "updatedAt": { "description": "When the promotion was last updated.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "For example, \"Promotions fetched successfully\".", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "promotionId": "promo_8KzR4pQ7eZ2LvUjH", "name": "Loyalty Boost", "status": "ACTIVE", "promoType": "PROMO_CODE", "appliedTo": "STORE", "appliedToId": "store_123", "schedule": { "startTime": "2026-08-01T00:00:00Z", "endTime": "2026-08-31T23:59:59Z" }, "promoCode": { "code": "AUG10", "offer": { "type": "PERCENTAGE_OFF", "percentage": 10 }, "budget": { "maxAmount": 5000, "currency": "SEK", "spentAmount": 1200 } }, "usageLimits": { "maximumRedemptions": 1000, "maximumRedemptionsPerCustomer": 2 }, "visualAssets": [], "createdAt": "2026-07-20T08:00:00Z", "updatedAt": "2026-07-25T09:30:00Z" } ], "message": "Promotions fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/v2/promotions": { "get": { "operationId": "fetchPromotions", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Promotions API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "The unique identifier of the merchant whose promotions are listed.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Returns only promotions in this state. Omit to return promotions of any status.\n\nValues:\n- `ACTIVE`: Currently running — within its schedule, with budget and redemption limits remaining.\n- `CREATED`: Created but not yet started (its start time is in the future).\n- `DEACTIVATED`: Manually switched off by the merchant.\n- `EXPIRED`: Past its end time.\n- `BUDGET_DEPLETED`: Stopped because spend reached the promo code budget.\n- `ATTEMPTS_EXHAUSTED`: Stopped because the redemption limit was reached.", "schema": { "description": "Returns only promotions in this state. Omit to return promotions of any status.\n\nValues:\n- `ACTIVE`: Currently running — within its schedule, with budget and redemption limits remaining.\n- `CREATED`: Created but not yet started (its start time is in the future).\n- `DEACTIVATED`: Manually switched off by the merchant.\n- `EXPIRED`: Past its end time.\n- `BUDGET_DEPLETED`: Stopped because spend reached the promo code budget.\n- `ATTEMPTS_EXHAUSTED`: Stopped because the redemption limit was reached.", "type": "string", "enum": [ "ACTIVE", "CREATED", "DEACTIVATED", "EXPIRED", "BUDGET_DEPLETED", "ATTEMPTS_EXHAUSTED" ] } }, { "name": "pageNumber", "in": "query", "required": false, "description": "The page of results to return. Defaults to 1.", "schema": { "description": "The page of results to return. Defaults to 1.", "type": "number" } }, { "name": "pageSize", "in": "query", "required": false, "description": "The number of promotions per page. Defaults to 100.", "schema": { "description": "The number of promotions per page. Defaults to 100.", "type": "number" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Indicates whether the request succeeded — either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The paginated promotions payload.", "type": "object", "properties": { "promotions": { "description": "The promotions on the requested page.", "type": "array", "items": { "type": "object", "properties": { "promotionId": { "description": "The unique identifier of the promotion.", "type": "string" }, "name": { "description": "The promotion’s name.", "type": "string" }, "status": { "description": "The current lifecycle state of the promotion.\n\nValues:\n- `ACTIVE`: Currently running — within its schedule, with budget and redemption limits remaining.\n- `CREATED`: Created but not yet started (its start time is in the future).\n- `DEACTIVATED`: Manually switched off by the merchant.\n- `EXPIRED`: Past its end time.\n- `BUDGET_DEPLETED`: Stopped because spend reached the promo code budget.\n- `ATTEMPTS_EXHAUSTED`: Stopped because the redemption limit was reached.", "type": "string", "enum": [ "ACTIVE", "CREATED", "DEACTIVATED", "EXPIRED", "BUDGET_DEPLETED", "ATTEMPTS_EXHAUSTED" ] }, "promoType": { "description": "The promotion mechanism.\n\nValues:\n- `PROMO_CODE`: A discount the customer redeems with a code, configured in `promoCode`.\n- `REDIRECT_LINK`: Sends the customer to a destination URL, configured in `redirectLink`.", "type": "string", "enum": [ "PROMO_CODE", "REDIRECT_LINK" ] }, "appliedTo": { "description": "The kind of entity the promotion applies to (for example, STORE or MERCHANT).", "type": "string" }, "appliedToId": { "description": "The identifier of the entity the promotion applies to.", "type": "string" }, "schedule": { "description": "The promotion’s active window.", "type": "object", "properties": { "startTime": { "description": "The ISO-8601 timestamp at which the promotion becomes active.", "type": "string" }, "endTime": { "description": "The ISO-8601 timestamp at which the promotion ends.", "type": "string" } }, "additionalProperties": true }, "promoCode": { "description": "Present when `promoType` is PROMO_CODE.", "type": "object", "properties": { "code": { "description": "The redeemable code.", "type": "string" }, "offer": { "description": "The discount the code applies.", "type": "object", "properties": { "type": { "description": "Whether the discount is a percentage or a fixed amount.", "type": "string" }, "percentage": { "description": "The percentage off, when the offer is PERCENTAGE_OFF.", "type": "number" }, "amount": { "description": "The fixed amount off, when the offer is FIXED_AMOUNT_OFF.", "type": "number" } }, "additionalProperties": true }, "budget": { "description": "Budget and spend tracking.", "type": "object", "properties": { "maxAmount": { "description": "The spend limit.", "type": "number" }, "currency": { "description": "The currency of the budget figures.", "type": "string" }, "spentAmount": { "description": "How much of the budget has been used so far.", "type": "number" } }, "additionalProperties": true } }, "additionalProperties": true }, "redirectLink": { "description": "Present when `promoType` is REDIRECT_LINK.", "type": "object", "properties": { "url": { "description": "The destination URL.", "type": "string" }, "sharableIdleLink": { "description": "A generated short link for display on the idle screen.", "type": "string" }, "sharablePrinterLink": { "description": "A generated short link for printed receipts.", "type": "string" } }, "additionalProperties": true }, "usageLimits": { "description": "The redemption limits.", "type": "object", "properties": { "maximumRedemptions": { "description": "The total redemption limit.", "type": "number" }, "maximumRedemptionsPerCustomer": { "description": "The per-customer redemption limit (may be null).", "type": "number" } }, "additionalProperties": true }, "visualAssets": { "description": "The promotion’s display assets.", "type": "array", "items": {} }, "assignments": { "description": "Where the promotion is currently assigned.", "type": "array", "items": { "type": "object", "properties": { "targetType": { "description": "Whether the promotion is assigned to a store or a terminal.", "type": "string" }, "targetId": { "description": "The identifier of the store or terminal the promotion is assigned to.", "type": "string" }, "assignedAt": { "description": "When the assignment was made.", "type": "string" } }, "additionalProperties": true } }, "createdAt": { "description": "When the promotion was created.", "type": "string" }, "updatedAt": { "description": "When the promotion was last updated.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "message": { "description": "For example, \"Promotions fetched successfully\".", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "promotions": [ { "promotionId": "promo_8KzR4pQ7eZ2LvUjH", "name": "Loyalty Boost", "status": "ACTIVE", "promoType": "PROMO_CODE", "appliedTo": "STORE", "appliedToId": "store_123", "schedule": { "startTime": "2026-08-01T00:00:00Z", "endTime": "2026-08-31T23:59:59Z" }, "promoCode": { "code": "AUG10", "offer": { "type": "PERCENTAGE_OFF", "percentage": 10 }, "budget": { "maxAmount": 5000, "currency": "SEK", "spentAmount": 1200 } }, "usageLimits": { "maximumRedemptions": 1000, "maximumRedemptionsPerCustomer": 2 }, "visualAssets": [], "assignments": [ { "targetType": "STORE", "targetId": "store_123", "assignedAt": "2026-08-01T10:00:00Z" } ], "createdAt": "2026-07-20T08:00:00Z", "updatedAt": "2026-07-25T09:30:00Z" } ] }, "message": "Promotions fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/receipts/{id}": { "get": { "operationId": "fetchReceiptData", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Receipts API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier for the id this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "The receipt payload for the transaction. Includes at least the fields below, plus line items, totals, and payment/fiscal details.", "type": "object", "properties": { "id": { "description": "Transaction identifier the receipt belongs to.", "type": "string" }, "amount": { "description": "Transaction amount, in the smallest currency unit.", "type": "number" }, "currency": { "description": "ISO 4217 currency code of the transaction.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "Human-facing status message.", "type": "string" } }, "required": [ "status" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "id": "{{transactionId}}", "amount": 1000, "currency": "SEK" }, "message": "Receipt data fetched successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] }, "post": { "operationId": "addReceiptData", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Receipts API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier for the id this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "receiptNumber": { "description": "Receipt number from your own system.", "type": "number" }, "cashRegisterName": { "description": "Name of the cash register that produced the receipt.", "type": "string" }, "controlUnitSerial": { "description": "Serial number of the control unit used.", "type": "string" }, "cashierName": { "description": "Name of the cashier who handled the transaction.", "type": "string" } } }, "example": { "receiptNumber": 1042, "cashRegisterName": "Register 1", "controlUnitSerial": "CU-123456", "cashierName": "Alex" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "Human-facing status message.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Receipt data added successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/receipts/{id}/print": { "post": { "operationId": "printReceipt", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Receipts API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier for the id this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "terminalId": { "description": "Terminal to print on. Defaults to the terminal that processed the transaction.", "type": "string" }, "templateType": { "description": "Which receipt template to print. Defaults to TRANSACTION_RECEIPT.\n\nValues:\n- `TRANSACTION_RECEIPT`: The standard per-transaction receipt.\n- `SALES_SUMMARY`: A sales-summary receipt.", "type": "string", "enum": [ "TRANSACTION_RECEIPT", "SALES_SUMMARY" ] } } }, "example": { "terminalId": "{{terminalId}}", "templateType": "TRANSACTION_RECEIPT" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "Human-facing status message.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Receipt sent to the printer successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] }, "put": { "operationId": "printReceiptLegacy", "summary": "Print Receipt (Legacy)", "description": "Legacy. Print the receipt using the older print API. Superseded by Print Receipt.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Receipts API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier for the id this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "terminalId": { "description": "Terminal to print on. Defaults to the terminal that processed the transaction.", "type": "string" }, "language": { "description": "Language of the printed receipt.\n\nValues:\n- `sv`: Swedish.\n- `da`: Danish.\n- `fi`: Finnish.\n- `en`: English.", "type": "string", "enum": [ "sv", "da", "fi", "en" ] }, "templateId": { "description": "Identifier of the receipt template to use.", "type": "string" } } }, "example": { "terminalId": "{{terminalId}}", "language": "en", "templateId": "{{templateId}}" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "Human-facing status message.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Print receipt processed successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/receipts/{id}/email": { "put": { "operationId": "emailReceipt", "summary": "Email Receipt", "description": "Send the receipt for a transaction as an email to the address provided in the body.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Receipts API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier for the id this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "Email address to send the receipt to.", "type": "string" } }, "required": [ "email" ] }, "example": { "email": "customer@example.com" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "Human-facing status message.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Email receipt processed successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/receipts/{id}/link": { "get": { "operationId": "fetchReceiptLink", "summary": "Fetch Receipt Link", "description": "Return a shareable link to the digital receipt for a transaction.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Receipts API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier for the id this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Contains the receipt link.", "type": "object", "properties": { "receiptURL": { "description": "Shareable URL of the digital receipt.", "type": "string" } }, "required": [ "receiptURL" ], "additionalProperties": true }, "message": { "description": "Human-facing status message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "receiptURL": "https://receipt.surfboardpayments.com/{{transactionId}}" }, "message": "Receipt URL fetched successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/receipts/{terminalId}/escpos": { "put": { "operationId": "printEscPosReceipt", "summary": "Print ESC/POS 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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Receipts API" ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "escposCommands": { "description": "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.", "type": "string" } }, "required": [ "escposCommands" ] }, "example": { "escposCommands": "G0A=" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "Human-facing status message.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "ESC/POS commands sent to the terminal successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/receipts/{orderId}": { "put": { "operationId": "updateReceiptHostData", "summary": "Update Receipt Host Data", "description": "Legacy. Update order data that Surfboard does not hold but that the receipt needs. Superseded by Add Receipt Data.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Receipts API" ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Identifier for the order this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantId": { "description": "Identifier of the merchant.", "type": "string" }, "sequenceNumber": { "description": "Sequence number of the receipt from your system.", "type": "string" }, "cashRegisterName": { "description": "Name of the cash register that produced the receipt.", "type": "string" }, "controlUnitSerialNumber": { "description": "Serial number of the control unit used.", "type": "string" }, "cashierName": { "description": "Name of the cashier who handled the transaction.", "type": "string" }, "customerName": { "description": "Name of the customer.", "type": "string" } } }, "example": { "merchantId": "{{merchantId}}", "sequenceNumber": "1042", "cashRegisterName": "Register 1", "controlUnitSerialNumber": "CU-123456", "cashierName": "Alex", "customerName": "Sam Smith" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "Human-facing status message.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Receipt host data updated successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/partners/{partnerId}/merchants/{merchantId}/reports": { "get": { "operationId": "fetchSettlementReports", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Reporting APIs" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data", "type": "array", "items": { "type": "object", "properties": { "payoutId": { "description": "The payout ID used to identify a specific payout.", "type": "string" }, "merchantId": { "description": "The merchant ID of the merchant for which the settlement report is generated.", "type": "string" }, "transactionStartDate": { "description": "The date of the first transaction in the generated settlement report, in YYYY-MM-DD format.", "type": "string" }, "transactionEndDate": { "description": "The date of the last transaction in the generated settlement report, in YYYY-MM-DD format.", "type": "string" }, "settlementDate": { "description": "Date of the payout, in YYYY-MM-DD format.", "type": "string" }, "reportType": { "description": "Specifies the type of settlement report opted for the merchant. It can be either 'MONTHLY' or 'DAILY’.", "type": "string" }, "url": { "description": "URL from which the particular settlement report can be viewed.", "type": "string" }, "totalSale": { "description": "The total amount of sales generated by the merchant during the report period.", "type": "number" }, "totalRefund": { "description": "The total amount refunded by the merchant during the specified time period.", "type": "number" }, "fee": { "description": "The total fee collected from transactions during the settlement.", "type": "number" }, "payout": { "description": "The final amount paid out to the merchant after all deductions.", "type": "number" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "payoutId": "Q6z2e0goIOE4DXD0VYiT", "merchantId": "8149bdef0a2300090e", "transactionStartDate": "2023-08-07", "transactionEndDate": "2023-08-07", "settlementDate": "2023-08-08", "reportType": "DAILY", "url": "https://reports.surfboardpayments.com/settlementReport1.pdf", "totalSale": 10000, "totalRefund": 100, "fee": 200, "payout": 9700 }, { "payoutId": "Q6z2e0goIOE4DXD0VYiT", "merchantId": "8149bdef0a2300090e", "transactionStartDate": "2023-08-07", "transactionEndDate": "2023-08-07", "settlementDate": "2023-08-08", "reportType": "DAILY", "url": "https://reports.surfboardpayments.com/settlementReport2.pdf", "totalSale": 10000, "totalRefund": 100, "fee": 200, "payout": 9700 } ], "message": "Settlement reports fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/terminals/{terminalId}/sessions": { "post": { "operationId": "startRfidSession", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "RFID API" ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "description": "The RFID tag read mode for the session.\n\nValues:\n- `single`: Read a single RFID tag and then stop.\n- `multiple`: Continuously read multiple RFID tags until the session is completed.", "type": "string", "enum": [ "single", "multiple" ] } }, "required": [ "mode" ] }, "example": { "mode": "single" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Outcome of the request.", "type": "string" }, "data": { "description": "The started session.", "type": "object", "properties": { "sessionId": { "description": "Unique identifier of the RFID reading session.", "type": "string" } }, "required": [ "sessionId" ], "additionalProperties": true }, "message": { "description": "Human-readable result message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "sessionId": "rfid_8267defa6150700b48" }, "message": "NFC reading session started successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "get": { "operationId": "fetchAllRfidSessions", "summary": "Fetch All RFID Sessions", "description": "Retrieves all RFID reading sessions for the specified terminal.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "RFID API" ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Outcome of the request.", "type": "string" }, "data": { "description": "List of RFID reading sessions.", "type": "array", "items": { "type": "object", "properties": { "sessionId": { "description": "Unique identifier of the RFID reading session.", "type": "string" }, "action": { "description": "The action the session performed.", "type": "string" }, "mode": { "description": "The read mode used for the session.", "type": "string" } }, "required": [ "sessionId", "action", "mode" ], "additionalProperties": true } }, "message": { "description": "Human-readable result message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "sessionId": "rfid_8267defa6150700b48", "action": "start", "mode": "single" } ], "message": "Fetched all NFC reading sessions under terminal." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/terminals/{terminalId}/sessions/{sessionId}/status": { "get": { "operationId": "fetchRfidSessionStatus", "summary": "Fetch RFID Session Status", "description": "Retrieves the current status of an RFID reading session, including the RFID tags read so far.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "RFID API" ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "description": "Identifier for the session this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Outcome of the request.", "type": "string" }, "data": { "description": "Current session status.", "type": "object", "properties": { "sessionStatus": { "description": "Current status of the reading session. One of PENDING, COMPLETED, CANCELLED, TIMED_OUT, NOT_FOUND.\n\nValues:\n- `PENDING`: The session is awaiting tag reads.\n- `COMPLETED`: The session completed successfully.\n- `CANCELLED`: The session was cancelled.\n- `TIMED_OUT`: The session timed out before completing.\n- `NOT_FOUND`: No session was found for the given identifier.", "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELLED", "TIMED_OUT", "NOT_FOUND" ] }, "nfcTags": { "description": "NFC/RFID tag identifiers read in the session so far.", "type": "array", "items": {} } }, "required": [ "sessionStatus" ], "additionalProperties": true }, "message": { "description": "Human-readable result message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "sessionStatus": "PENDING", "nfcTags": [ "E280117000000123456789AB" ] }, "message": "Fetched NFC session status." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/terminals/{terminalId}/sessions/{sessionId}": { "get": { "operationId": "getRfidSessionDetails", "summary": "Get RFID Session Details", "description": "Retrieves the details of a specific RFID reading session.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "RFID API" ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "description": "Identifier for the session this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Outcome of the request.", "type": "string" }, "data": { "description": "The RFID reading session.", "type": "object", "properties": { "sessionId": { "description": "Unique identifier of the RFID reading session.", "type": "string" }, "action": { "description": "The action the session performed.", "type": "string" }, "mode": { "description": "The read mode used for the session.", "type": "string" } }, "required": [ "sessionId", "action", "mode" ], "additionalProperties": true }, "message": { "description": "Human-readable result message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "sessionId": "rfid_8267defa6150700b48", "action": "start", "mode": "single" }, "message": "Fetched all NFC reading sessions under terminal." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/terminals/{terminalId}/sessions/{sessionId}/tags": { "get": { "operationId": "fetchRfidTags", "summary": "Fetch RFID Tags", "description": "Retrieves all RFID tags read during the specified session.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "RFID API" ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "description": "Identifier for the session this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Outcome of the request.", "type": "string" }, "data": { "description": "List of RFID tags read in the session.", "type": "array", "items": { "type": "object", "properties": { "sessionId": { "description": "Identifier of the session the tag was read in.", "type": "string" }, "tagId": { "description": "The RFID tag identifier (EPC).", "type": "string" } }, "required": [ "sessionId", "tagId" ], "additionalProperties": true } }, "message": { "description": "Human-readable result message.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "sessionId": "rfid_8267defa6150700b48", "tagId": "E280117000000123456789AB" } ], "message": "Fetched all tags under session." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/terminals/{terminalId}/sessions/{sessionId}/complete": { "post": { "operationId": "completeRfidSession", "summary": "Complete RFID Session", "description": "Completes an active RFID reading session. Optionally provide the final result of the session.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "RFID API" ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "description": "Identifier for the session this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "description": "The final result to set for the session. When omitted, the session is completed without an explicit result.\n\nValues:\n- `COMPLETED`: The session finished successfully.\n- `CANCELLED`: The session was cancelled.\n- `TIMED_OUT`: The session timed out before completion.", "type": "string", "enum": [ "COMPLETED", "CANCELLED", "TIMED_OUT" ] } } }, "example": { "result": "COMPLETED" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Outcome of the request.", "type": "string" }, "message": { "description": "Human-readable result message.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "NFC reading session completed successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/service-providers": { "post": { "operationId": "createServiceProvider", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Service Providers API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "description": "Two-letter ISO country code where the service provider is registered, for example 'SE'.", "type": "string" }, "organisation": { "description": "Company details for the service provider.", "type": "object", "properties": { "corporateId": { "description": "Corporate registration number of the company, validated against the supplied country.", "type": "string" } }, "required": [ "corporateId" ] } }, "required": [ "country", "organisation" ] }, "example": { "country": "SE", "organisation": { "corporateId": "5560000000" } } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Details of the created service provider application.", "type": "object", "properties": { "applicationId": { "description": "Unique identifier for the created service provider application.", "type": "string" }, "webKybUrl": { "description": "Hosted URL where the service provider completes the KYB (Know Your Business) verification.", "type": "string" } }, "required": [ "applicationId", "webKybUrl" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "applicationId": "838ca3a7c530200810", "webKybUrl": "https://web-kyb-dev.web.app/838ca3a7c530200810?pi=QGv2Kgu9q0WAdg6FjkK0iEliyh8l61yxIXnaf0M70l4psKXW_6KihWL4wcY2aL0NfI5aM69J7bYUisZ8ecrFTNMrj4KU1ZjrN5Q3O9hcqlEgc6oQACb2eLM7SwwP0006" }, "message": "Service provider company application created successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Missing required parameter 'country' in create service provider company application" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true }, "get": { "operationId": "fetchServiceProvidersForPartner", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Service Providers API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Service providers registered under the partner.", "type": "object", "properties": { "serviceProviders": { "description": "List of service providers under the partner.", "type": "array", "items": { "type": "object", "properties": { "serviceProviderId": { "description": "Unique identifier of the service provider.", "type": "string" }, "personId": { "description": "Identifier of the associated person, null for company service providers.", "type": "string" }, "corporateId": { "description": "Corporate registration number of the service provider.", "type": "string" }, "nationalId": { "description": "National identification number, null when not applicable.", "type": "string" }, "name": { "description": "Name of the service provider, null when not specified.", "type": "string" }, "address": { "description": "Registered address of the service provider, null if unavailable.", "type": "object", "properties": { "addressLine1": { "description": "First line of the address.", "type": "string" }, "city": { "description": "City of the address.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code of the address.", "type": "string" }, "postalCode": { "description": "Postal code of the address.", "type": "string" } }, "required": [ "addressLine1", "city", "countryCode", "postalCode" ], "additionalProperties": true }, "phoneNumber": { "description": "Contact phone number of the service provider, null if unavailable.", "type": "object", "properties": { "number": { "description": "Phone number of the service provider.", "type": "string" }, "code": { "description": "Country dialing code of the phone number.", "type": "string" }, "role": { "description": "Role associated with the phone number, null when not specified.", "type": "string" } }, "required": [ "number", "code" ], "additionalProperties": true }, "email": { "description": "Email address of the service provider.", "type": "string" } }, "required": [ "serviceProviderId", "corporateId", "email" ], "additionalProperties": true } } }, "required": [ "serviceProviders" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "serviceProviders": [ { "serviceProviderId": "8385f437bc6d200b50", "personId": null, "corporateId": "5000008202", "nationalId": null, "name": null, "address": { "addressLine1": "Pacocha - Hand", "city": "Denesik Brook", "countryCode": "SE", "postalCode": "61050" }, "phoneNumber": { "number": "701208734", "code": "46", "role": null }, "email": "harish@surfboard.se" } ] }, "message": "Service providers fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to fetch service provider" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/service-providers/individual": { "post": { "operationId": "initiateIndividualServiceProviderOnboarding", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Service Providers API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "Email address of the individual service provider being onboarded.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code where the service provider is based, for example 'SE'.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant the individual service provider will be associated with.", "type": "string" }, "spType": { "description": "Type of service provider being onboarded. Included only when provided.", "type": "string" }, "config": { "description": "Optional fee configuration applied to the service provider. Included only when provided.", "type": "object", "properties": { "feePercentage": { "description": "Percentage fee taken from each applicable transaction.", "type": "number" }, "feeFixedAmount": { "description": "Fixed fee amount in the smallest currency unit taken from each applicable transaction.", "type": "number" }, "deductApplicableTransactionFee": { "description": "Whether the applicable transaction fee is deducted from the service provider.", "type": "boolean" } } } }, "required": [ "email", "countryCode", "merchantId" ] }, "example": { "email": "harish@surfboard.se", "countryCode": "SE", "merchantId": "8385f437bc6d200b50", "spType": "INDIVIDUAL", "config": { "feePercentage": 2.5, "feeFixedAmount": 100, "deductApplicableTransactionFee": true } } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Details of the initiated individual onboarding.", "type": "object", "properties": { "applicationId": { "description": "Unique identifier for the individual service provider application.", "type": "string" }, "signingLink": { "description": "Hosted URL where the individual signs the service provider agreement.", "type": "string" }, "signingSessionId": { "description": "Identifier of the signing session used to track the agreement.", "type": "string" }, "status": { "description": "Current status of the onboarding application.", "type": "string" } }, "required": [ "applicationId", "signingLink", "signingSessionId", "status" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "applicationId": "838ca3a7c530200810", "signingLink": "https://sign-dev.surfboardpayments.com/838ca3a7c530200810", "signingSessionId": "8391b7c2ad4e100722", "status": "APPLICATION_INITIATED" }, "message": "Individual SP onboarding initiated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Missing required parameter 'merchantId' in initiate individual SP onboarding" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/service-providers/applications": { "get": { "operationId": "getAllServiceProviderApplications", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Service Providers API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "applicationType", "in": "query", "required": false, "description": "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.", "schema": { "description": "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.", "type": "string", "enum": [ null, null ] } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "List of service provider applications under the partner.", "type": "array", "items": { "type": "object", "properties": { "applicationId": { "description": "Unique identifier of the application.", "type": "string" }, "country": { "description": "Two-letter ISO country code where the service provider is registered.", "type": "string" }, "corporateId": { "description": "Corporate registration number of the service provider.", "type": "string" }, "applicationStatus": { "description": "Current status of the application.", "type": "string", "enum": [ null, null, null, null, null, null, null, null, null, null, null, null ] }, "createdAt": { "description": "ISO timestamp of when the application was created.", "type": "string" }, "lastUpdatedAt": { "description": "ISO timestamp of when the application was last updated.", "type": "string" }, "webKybUrl": { "description": "Hosted URL where the service provider completes KYB verification, when available.", "type": "string" }, "legalName": { "description": "Legal name of the service provider, when available.", "type": "string" }, "endDate": { "description": "ISO timestamp marking the end date of the application, when available.", "type": "string" } }, "required": [ "applicationId" ], "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "applicationId": "838ca3a7c530200810", "country": "SE", "corporateId": "3532007322", "applicationStatus": "APPLICATION_INITIATED", "createdAt": "2025-10-10T10:32:47.565Z", "lastUpdatedAt": "2025-10-10T10:32:47.565Z", "webKybUrl": "https://web-kyb-dev.web.app/838ca3a7c530200810?pi=QGv2Kgu9q0WAdg6FjkK0iEliyh8l61yxIXnaf0M70l4psKXW_6KihWL4wcY2aL0NfI5aM69J7bYUisZ8ecrFTNMrj4KU1ZjrN5Q3O9hcqlEgc6oQACb2eLM7SwwP0006", "legalName": "Turner, Runte and Kemmer" }, { "applicationId": "838ca332c530200310", "country": "SE", "corporateId": "5834862013", "applicationStatus": "APPLICATION_STARTED", "createdAt": "2025-10-10T10:28:53.740Z", "lastUpdatedAt": "2025-10-10T10:39:34.614Z", "webKybUrl": "https://web-kyb-dev.web.app/838ca332c530200310?pi=rZzanQBc-0lZgNKHpPE0_ou4KDDcH1nXxKDuqS07IdTnTOQ-k62W--U2uyB21T2-ipMtS6E7iA6LLMb8T52FYHGd54jZX9nOdzM1YA9qNlZgT3n8_AZTcyC3ljNm0002", "legalName": "LOCO SP OBERBRUNNER LLC" } ], "message": "Applications under partner fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Bad request. Please check your request parameters" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/service-providers/applications/{applicationId}": { "get": { "operationId": "fetchServiceProviderApplicationStatus", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Service Providers API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "applicationId", "in": "path", "required": true, "description": "Identifier for the application this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Current status details of the application.", "type": "object", "properties": { "onboardingStatus": { "description": "Current onboarding status of the application, null if onboarding has not started.", "type": "string" }, "applicationStatus": { "description": "Current status of the application.", "type": "string", "enum": [ null, null, null, null, null, null, null, null, null, null, null, null ] }, "serviceProviderId": { "description": "Identifier of the created service provider once the application is approved, null while still pending.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "onboardingStatus": null, "applicationStatus": "APPLICATION_INITIATED", "serviceProviderId": null }, "message": "Service provider application status fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to fetch service provider application status" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/merchants/{merchantId}/service-providers/link": { "post": { "operationId": "linkServiceProviderToMerchant", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Service Providers API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceProviderId": { "description": "Identifier of the service provider to link to the merchant.", "type": "string" } }, "required": [ "serviceProviderId" ] }, "example": { "serviceProviderId": "8385f437bc6d200b50" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Service provider linked to merchant successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Missing required parameter 'serviceProviderId' in link service provider for merchant" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/merchants/{merchantId}/service-providers/unlink": { "delete": { "operationId": "unlinkServiceProviderFromMerchant", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Service Providers API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "serviceProviderId", "in": "query", "required": true, "description": "Identifier of the service provider to unlink from the merchant.", "schema": { "description": "Identifier of the service provider to unlink from the merchant.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Service provider unlinked from merchant successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Missing required parameter 'serviceProviderId' in unlink service provider for merchant" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/merchants/{merchantId}/service-providers": { "get": { "operationId": "fetchServiceProvidersForMerchant", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Service Providers API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Active service providers linked to the merchant.", "type": "object", "properties": { "activeServiceProviders": { "description": "List of service providers active on the merchant account.", "type": "array", "items": { "type": "object", "properties": { "merchantId": { "description": "Identifier of the merchant the service provider is linked to.", "type": "string" }, "partnerId": { "description": "Identifier of the partner that owns the merchant.", "type": "string" }, "isActive": { "description": "Whether the link between the service provider and the merchant is currently active.", "type": "boolean" }, "serviceProvider": { "description": "Summary of the linked service provider, null if the details are unavailable.", "type": "object", "properties": { "id": { "description": "Unique identifier of the service provider.", "type": "string" }, "name": { "description": "Name of the service provider.", "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": true } }, "required": [ "merchantId", "partnerId", "isActive" ], "additionalProperties": true } } }, "required": [ "activeServiceProviders" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "activeServiceProviders": [ { "merchantId": "8385f437bc6d200b50", "partnerId": "8113d3f8403b380409", "isActive": true, "serviceProvider": { "id": "839ab2f1c47d300a20", "name": "Nordic Payments AB" } } ] }, "message": "Active service providers fetched successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to fetch service provider for merchant" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/merchants/{merchantId}/stores": { "post": { "operationId": "createStore", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Stores API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeName": { "description": "Name of the store.", "type": "string" }, "email": { "description": "Email address of the store. Email address in mandatory to support online payments.", "type": "string" }, "phoneNumber": { "description": "Contact number of the store in code and number format.", "type": "object", "properties": { "code": { "description": "International dialing code identifying the country or region.", "type": "string" }, "number": { "description": "A string of numbers ranging from 0-9 with a length of 5-15 characters.", "type": "string" } }, "required": [ "code", "number" ] }, "address": { "description": "Address of the store.", "type": "object", "properties": { "careOf": { "description": "Name of the person or entity receiving correspondence on behalf of the store (c/o).", "type": "string" }, "addressLine1": { "description": "First line of address.", "type": "string" }, "addressLine2": { "description": "Second line of address.", "type": "string" }, "addressLine3": { "description": "Third line of address.", "type": "string" }, "city": { "description": "Name of the city where the store is located.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code in uppercase, representing the location of the store.", "type": "string" }, "postalCode": { "description": "Postal code of the store.", "type": "string" } }, "required": [ "addressLine1", "city", "countryCode", "postalCode" ] }, "acquirerMID": { "description": "Acquirer Merchant ID. Required for payment facilitator partners that want to support a store-based acquiring model.", "type": "string" }, "onlineInfo": { "description": "In order to start accepting online payments you need to create an online store which requires some additional properties such as the following.", "type": "object", "properties": { "merchantWebshopURL": { "description": "This is the web-shop URL of the merchant.", "type": "string" }, "paymentPageHostURL": { "description": "This is the URL of the payment page. This is required for integrating online payments using SDK mode.", "type": "string" }, "termsAndConditionsURL": { "description": "This is the URL of the T&C of the merchant’s web-shop, it has to contain the refund policy.", "type": "string" }, "privacyPolicyURL": { "description": "This is the URL of the privacy policy of the merchant.", "type": "string" }, "googlePayMerchantId": { "description": "Your Google Pay merchant identifier, used to enable Google Pay on the online store.", "type": "string" } }, "required": [ "merchantWebshopURL", "termsAndConditionsURL", "privacyPolicyURL" ] } }, "required": [ "storeName", "phoneNumber", "address" ] }, "example": { "storeName": "Trial Store", "email": "TS@gmail.com", "phoneNumber": { "code": "91", "number": "3214576980" }, "address": { "addressLine1": "Hagmarksgatan 3", "addressLine2": "Suite 724", "addressLine3": "North", "city": "Stockholm", "countryCode": "SE", "postalCode": "103 16" }, "onlineInfo": { "merchantWebshopURL": "https://testmerchantportal.com/home", "paymentPageHostURL": "https://testmerchantportal.com/payment", "termsAndConditionsURL": "https://testmerchantportal.com/terms", "privacyPolicyURL": "https://testmerchantportal.com/privacy" } } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "storeId": { "description": "Identifier of the newly created store. Use this when registering terminals or fetching the store's details.", "type": "string" }, "merchantUrlDomainVerificationKey": { "description": "Verification key to place on the merchant's webshop domain to prove ownership. Returned only when online store details were provided; null otherwise.", "type": "string" }, "paymentPageUrlDomainVerificationKey": { "description": "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.", "type": "string" } }, "required": [ "storeId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request", "type": "string" } }, "required": [ "status", "data" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "storeId": "81d64e7174dcb00b0f", "merchantUrlDomainVerificationKey": "499470649f03b53fa1175659d4389743974710260b7f410313487e6062b3d559", "paymentPageUrlDomainVerificationKey": "2179beab4f5e8c3960615205f042939a2ccc6c51a6e5923c9c068b3d9a645590" }, "message": "Store created successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Mandatory address parameters missing" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchStores", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Stores API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request. 'SUCCESS' | 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "array", "items": { "type": "object", "properties": { "storeId": { "description": "Store ID of the store.", "type": "string" }, "merchantId": { "description": "The Merchant ID of the merchant under which the store is created.", "type": "string" }, "name": { "description": "Name of the store.", "type": "string" }, "status": { "description": "Current lifecycle status of the store.\n\nValues:\n- `ACTIVE`: The store is active and ready for payments.\n- `DEACTIVATED`: The store has been deactivated.\n- `BLOCKED`: The store is blocked from further activity.\n- `INACTIVE`: The store is still in the verification stage.", "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "BLOCKED", "INACTIVE" ] }, "address": { "description": "Address of the store.", "type": "object", "properties": { "careOf": { "description": "Name of the addressee that is accepting the correspondence for the intended recipient.", "type": "string" }, "addressLine1": { "description": "The first line of the store's address.", "type": "string" }, "addressLine2": { "description": "The second line of the store's address.", "type": "string" }, "addressLine3": { "description": "The third line of the store's address.", "type": "string" }, "city": { "description": "Name of the City where the store is located.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code in uppercase, representing the location of the store.", "type": "string" }, "postalCode": { "description": "Postal Code of the place where the store is located.", "type": "string" } }, "required": [ "addressLine1", "city", "countryCode", "postalCode" ], "additionalProperties": true }, "onlineInfo": { "description": "In order to start accepting online payments you need to create an online store which requires some additional properties such as the following.", "type": "object", "properties": { "merchantWebshopURL": { "description": "This is the web-shop URL of the merchant.", "type": "string" }, "paymentPageHostURL": { "description": "This is the URL of the payment page.", "type": "string" }, "termsAndConditionsURL": { "description": "This is the URL of the T&C of the merchant’s web-shop, it has to contain the refund policy.", "type": "string" }, "privacyPolicyURL": { "description": "This is the URL of the privacy policy of the merchant.", "type": "string" }, "googlePayMerchantId": { "description": "The Google Pay merchant identifier configured for the online store.", "type": "string" } }, "required": [ "merchantWebshopURL", "termsAndConditionsURL", "privacyPolicyURL" ], "additionalProperties": true }, "phoneNumber": { "description": "Contact phone number of the store, present only when one is set.", "type": "object", "properties": { "code": { "description": "International dialing code of the store's phone number.", "type": "string" }, "number": { "description": "Local phone number of the store.", "type": "string" } }, "additionalProperties": true }, "email": { "description": "Email address of the store.", "type": "string" } }, "required": [ "storeId", "merchantId", "name", "address", "email" ], "additionalProperties": true } }, "message": { "description": "Message describing the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "storeId": "824bd4a739dc200b0f", "status": "ACTIVE", "merchantId": "81fa6b2d8d5dc8040e", "name": "Previous Store", "address": { "careOf": null, "addressLine1": "No:3, 10th street", "addressLine2": null, "addressLine3": null, "city": "Copenhagen", "countryCode": "SE", "postalCode": "576462" }, "onlineInfo": { "merchantWebshopURL": "https://testmerchantportal.com/home", "paymentPageHostURL": "https://testmerchantportal.com/payment", "termsAndConditionsURL": "https://testmerchantportal.com/terms", "privacyPolicyURL": "https://testmerchantportal.com/privacy", "googlePayMerchantId": null }, "phoneNumber": { "code": "46", "number": "12345678" }, "email": "PS@gmail.com" }, { "storeId": "st_p5Hprp71IKuPGOCqkZSt5", "status": "ACTIVE", "merchantId": "81fa6b2d8d5dc8040e", "name": "New Store", "address": { "careOf": null, "addressLine1": "No:3, 10th street", "addressLine2": null, "addressLine3": null, "city": "Copenhagen", "countryCode": "SE", "postalCode": "576462" }, "onlineInfo": null, "phoneNumber": { "code": "46", "number": "4775866734" }, "email": "NS@gmail.com" } ], "message": "Fetched stores successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/partners/{partnerId}/merchants/{merchantId}/stores/{storeId}": { "delete": { "operationId": "deactivateAStore", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Stores API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "deactivationDate", "in": "query", "required": false, "description": "Date of deactivation of the store in yyyy-mm-dd format.", "schema": { "description": "Date of deactivation of the store in yyyy-mm-dd format.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "Message describing the status of store deactivation.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Store deactivation initiated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchStoreDetails", "summary": "Fetch Store Details", "description": "Retrieves information for a specific store. Use this API to get information regarding a particular store created under a merchant.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Stores API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "storeId": { "description": "Store ID of the store.", "type": "string" }, "merchantId": { "description": "The Merchant ID of the merchant under which the store is created.", "type": "string" }, "name": { "description": "Name of the store.", "type": "string" }, "status": { "description": "Status of the store.\n\nValues:\n- `ACTIVE`: The store is active and ready for payments.\n- `DEACTIVATED`: The store is deactivated.\n- `BLOCKED`: The store is blocked from further activities.\n- `INACTIVE`: The store is in verification stage.", "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "BLOCKED", "INACTIVE" ] }, "onlineOnboardingStatus": { "description": "Onboarding status of the online store.\n\nValues:\n- `APPROVED`: The store is approved for online payments.\n- `INITIATED`: The online store verification is initiated.\n- `FAILED`: Failed to verify the online store.", "type": "string", "enum": [ "APPROVED", "INITIATED", "FAILED" ] }, "address": { "description": "Address of the store.", "type": "object", "properties": { "careOf": { "description": "Name of the addressee that is accepting the correspondence for the intended recipient.", "type": "string" }, "addressLine1": { "description": "The first line of the store's address.", "type": "string" }, "addressLine2": { "description": "The second line of the store's address.", "type": "string" }, "addressLine3": { "description": "The third line of the store's address.", "type": "string" }, "city": { "description": "Name of the City where the store is located.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code in uppercase, representing the location of the store.", "type": "string" }, "postalCode": { "description": "Postal Code of the place where the store is located.", "type": "string" } }, "required": [ "addressLine1", "city", "countryCode", "postalCode" ], "additionalProperties": true }, "onlineInfo": { "description": "In order to start accepting online payments you need to create an online store which requires some additional properties such as the following.", "type": "object", "properties": { "merchantWebshopURL": { "description": "This is the web-shop URL of the merchant.", "type": "string" }, "paymentPageHostURL": { "description": "This is the URL of the payment page.", "type": "string" }, "termsAndConditionsURL": { "description": "This is the URL of the T&C of the merchant’s web-shop, it has to contain the refund policy.", "type": "string" }, "privacyPolicyURL": { "description": "This is the URL of the privacy policy of the merchant.", "type": "string" }, "googlePayMerchantId": { "description": "The Google Pay merchant identifier configured for the online store.", "type": "string" } }, "required": [ "merchantWebshopURL", "termsAndConditionsURL", "privacyPolicyURL" ], "additionalProperties": true }, "phoneNumber": { "description": "Contact phone number of the store, present only when one is set.", "type": "object", "properties": { "code": { "description": "International dialing code of the store's phone number.", "type": "string" }, "number": { "description": "Local phone number of the store.", "type": "string" } }, "additionalProperties": true }, "email": { "description": "Email address of the store.", "type": "string" } }, "required": [ "storeId", "merchantId", "name", "address", "email" ], "additionalProperties": true }, "message": { "description": "Message describing the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "storeId": "824bd4a739dc200b0f", "merchantId": "81a641f8b3cfd0070e", "name": "TEST", "status": "ACTIVE", "onlineOnboardingStatus": "APPROVED", "address": { "careOf": null, "addressLine1": "Main Street 123", "addressLine2": "6th lane", "addressLine3": "Building C", "city": "Stockholm", "countryCode": "SE", "postalCode": "103 16" }, "onlineInfo": { "merchantWebshopURL": "https://testmerchant.com", "paymentPageHostURL": null, "termsAndConditionsURL": "https://www.termsandconditions.com", "privacyPolicyURL": "https://www.privacypolicy.com", "googlePayMerchantId": null }, "phoneNumber": { "code": "46", "number": "701234567" }, "email": "test@gmail.com" }, "message": "Fetched store by ID" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "put": { "operationId": "updateStoreDetails", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Stores API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeName": { "description": "Name of the store.", "type": "string" }, "email": { "description": "Email address of the store.", "type": "string" }, "phoneNumber": { "description": "Contact number of the store in code and number format.", "type": "object", "properties": { "code": { "description": "International dialing code identifying the country or region.", "type": "string" }, "number": { "description": "A string of numbers ranging from 0-9 with a length of 5-15 characters", "type": "string" } } }, "address": { "description": "Address of the store.", "type": "object", "properties": { "addressLine1": { "description": "First line of address.", "type": "string" }, "addressLine2": { "description": "Second line of address.", "type": "string" }, "addressLine3": { "description": "Third line of address.", "type": "string" }, "city": { "description": "City where the store is located.", "type": "string" }, "countryCode": { "description": "Two-letter ISO country code in uppercase, representing the location of the store.", "type": "string" }, "postalCode": { "description": "Postal code of the store.", "type": "string" }, "careOf": { "description": "Care-of (c/o) recipient line for the address.", "type": "string" } } }, "acquirerMID": { "description": "Acquirer Merchant ID. Required for payment facilitator partners that want to support a store-based acquiring model.", "type": "string" }, "onlineInfo": { "description": "In order to update a physical store into an online store, some additional properties are required. Online info can be updated only once.", "type": "object", "properties": { "merchantWebshopURL": { "description": "This is the web-shop URL of the merchant.", "type": "string" }, "paymentPageHostURL": { "description": "This is the URL of the payment page. Required for integrating online payments using SDK mode.", "type": "string" }, "termsAndConditionsURL": { "description": "This is the URL of the T&C of the merchant’s web-shop, it has to contain the refund policy.", "type": "string" }, "privacyPolicyURL": { "description": "This is the URL of the privacy policy of the merchant.", "type": "string" }, "googlePayMerchantId": { "description": "Your Google Pay merchant identifier, used to enable Google Pay on the online store.", "type": "string" } }, "required": [ "merchantWebshopURL", "termsAndConditionsURL", "privacyPolicyURL" ] } } }, "example": { "storeName": "Updated Store", "email": "US@gmail.com", "phoneNumber": { "code": "46", "number": "7312345678" }, "address": { "addressLine1": "Hagmarksgatan 3", "addressLine2": "Suite 724", "addressLine3": "North", "city": "Stockholm", "countryCode": "SE", "postalCode": "103 16" } } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request. 'SUCCESS' | 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "merchantUrlDomainVerificationKey": { "description": "Verification key to place on the merchant's webshop domain to prove ownership. Returned only when online store details were provided.", "type": "string" }, "paymentPageUrlDomainVerificationKey": { "description": "Verification key to place on the payment page host domain to prove ownership. Returned only when a payment page host URL was provided.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "Message describing the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "merchantUrlDomainVerificationKey": "499470649f03b53fa1175659d4389743974710260b7f410313487e6062b3d559", "paymentPageUrlDomainVerificationKey": "2179beab4f5e8c3960615205f042939a2ccc6c51a6e5923c9c068b3d9a645590" }, "message": "Store data updated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/terminals": { "get": { "operationId": "fetchAllStoreTerminals", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Stores API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalType", "in": "query", "required": false, "description": "Optional query param to filter terminals by terminal type.\n\nValues:\n- `surfpad`: Hardware terminal with a physical keypad.\n- `surftouch`: Android terminal with custom payment apps, digital receipts etc.\n- `surfprint`: Android terminal with a built-in printer.\n- `checkoutPro`: Complete checkout solution with a customer facing screen.\n- `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.\n- `PaymentPage`: Surfboard-hosted payment page where all UI and configurations are managed by Surfboard.\n- `SelfHostedPage`: Merchant-hosted payment page where Surfboard renders payment fields within the merchant’s environment.\n- `MerchantInitiated`: Used for Merchant Initiated Transactions (MIT), allowing payments to be triggered by the merchant without customer interaction.\n- `printer`: Standalone printing device.\n- `surftester`: Surfboard Android based test terminal used during integrations.", "schema": { "description": "Optional query param to filter terminals by terminal type.\n\nValues:\n- `surfpad`: Hardware terminal with a physical keypad.\n- `surftouch`: Android terminal with custom payment apps, digital receipts etc.\n- `surfprint`: Android terminal with a built-in printer.\n- `checkoutPro`: Complete checkout solution with a customer facing screen.\n- `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.\n- `PaymentPage`: Surfboard-hosted payment page where all UI and configurations are managed by Surfboard.\n- `SelfHostedPage`: Merchant-hosted payment page where Surfboard renders payment fields within the merchant’s environment.\n- `MerchantInitiated`: Used for Merchant Initiated Transactions (MIT), allowing payments to be triggered by the merchant without customer interaction.\n- `printer`: Standalone printing device.\n- `surftester`: Surfboard Android based test terminal used during integrations.", "type": "string", "enum": [ "surfpad", "surftouch", "surfprint", "checkoutPro", "checkoutX", "PaymentPage", "SelfHostedPage", "MerchantInitiated", "printer", "surftester" ] } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request. 'SUCCESS' | 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "array", "items": { "type": "object", "properties": { "terminalId": { "description": "Store ID of the terminal.", "type": "string" }, "terminalType": { "description": "Describes the type of the terminal.\n\nValues:\n- `surfpad`: Hardware terminal with a physical keypad.\n- `surftouch`: Android terminal with custom payment apps, digital receipts etc.\n- `surfprint`: Android terminal with a built-in printer.\n- `checkoutPro`: Complete checkout solution with a customer facing screen.\n- `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.\n- `PaymentPage`: Surfboard-hosted payment page where all UI and configurations are managed by Surfboard.\n- `SelfHostedPage`: Merchant-hosted payment page where Surfboard renders payment fields within the merchant’s environment.\n- `MerchantInitiated`: Used for Merchant Initiated Transactions (MIT), allowing payments to be triggered by the merchant without customer interaction.\n- `printer`: Standalone printing device.\n- `surftester`: Surfboard Android based test terminal used during integrations.", "type": "string", "enum": [ "surfpad", "surftouch", "surfprint", "checkoutPro", "checkoutX", "PaymentPage", "SelfHostedPage", "MerchantInitiated", "printer", "surftester" ] }, "softwareVersion": { "description": "Software version of the terminal.", "type": "string" }, "osType": { "description": "Describes the type of operating system running on the terminals.\n\nValues:\n- `android`: Android operating system.\n- `ios`: Apple's operating system for iPhones.\n- `sb_firmware`: Surfboard firmware.", "type": "string", "enum": [ "android", "ios", "sb_firmware" ] }, "osVersion": { "description": "Operating System(OS) version of the terminal.", "type": "string" }, "deviceVendor": { "description": "Device vendor of the terminal.", "type": "string" }, "deviceModel": { "description": "Device model of the terminal.", "type": "string" }, "serialNo": { "description": "Serial number of the terminal.", "type": "string" }, "storeId": { "description": "The Store ID of the store under which the terminal is registered.", "type": "string" }, "linkedTerminalId": { "description": "The Terminal ID of another terminal to which the current terminal is linked.", "type": "string" }, "terminalStatus": { "description": "Status of the terminal. The terminal can be in any one of these states: 'REGISTERED' | 'ACTIVE' | 'IN_ACTIVE' | 'DE_REGISTERED’.", "type": "string" }, "terminalPaymentMethods": { "description": "Payment methods supported by the terminal.", "type": "string" }, "startDate": { "description": "Timestamp at which terminal was registered.", "type": "string" }, "terminalName": { "description": "Name of the terminal used as a reference for users.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "Message describing the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "terminalId": "81ff0cea07e4300105", "softwareVersion": "1.5.3", "osType": "android", "osVersion": "1.0.0.0", "deviceVendor": "Samsung", "deviceModel": "Galaxy N10", "serialNo": null, "storeId": "81fd3113680e60030f", "linkedTerminalId": null, "terminalStatus": "ACTIVE", "startDate": "2024-02-15T06:46:44.046Z", "terminalPaymentMethods": [ "SWISH", "CASH", "SVEA_SWISH" ], "terminalName": "surf-touch", "terminalType": "unknown", "batteryPercentage": null, "powerSource": null, "deviceNetwork": null, "turnOnTime": null, "terminalCurrencyCode": "NA" }, { "terminalId": "81ff0ff487e4300b04", "softwareVersion": "4.0.12.0", "osType": "pinpad", "osVersion": "2.0.0.0", "deviceVendor": "Datecs", "deviceModel": "Datecs Bluepad 55", "serialNo": "4299989999", "storeId": "81fd3113680e60030f", "linkedTerminalId": null, "terminalStatus": "REGISTERED", "startDate": "2024-02-15T07:12:41.658Z", "terminalPaymentMethods": [ "CARD" ], "terminalName": null, "terminalType": "surfpad", "batteryPercentage": null, "powerSource": null, "deviceNetwork": null, "turnOnTime": null, "terminalCurrencyCode": "NA" } ], "message": "Terminal records fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "patch": { "operationId": "setStoreTerminalConfig", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "wifiSsid": { "description": "Name of the WiFi network. Supported for: SurfPad.", "type": "string" }, "wifiPassword": { "description": "Password for the WiFi network. Supported for: SurfPad.", "type": "string" }, "autoSleep": { "description": "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. Supported for: SurfPad.", "type": "number" }, "preferredRestartTime": { "description": "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. Supported for: SurfPad.", "type": "string" }, "preferredNetwork": { "description": "Preferred network for the terminal. It can be either 'WIFI' or 'GSM'. Supported for: SurfPad.", "type": "string" }, "alwaysShowMinorUnits": { "description": "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. Supported for: SurfPad.", "type": "number" }, "language": { "description": "Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'. Supported for: SurfPad, SurfTouch, SurfPrint, SoftPOS.", "type": "string" }, "showStatusBar": { "description": "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. Supported for: SurfPad.", "type": "boolean" }, "chipReadDelay": { "description": "Time delay in milliseconds before the card is read. Supported for: SurfPad.", "type": "number" }, "showReceipt": { "description": "Set this to determine how receipts are showcased on the terminal. Supported for: SurfTouch, SurfPrint, SoftPOS.", "type": "boolean" }, "preferredGsmOperator": { "description": "The preferred GSM operator identified by a numeric code. Supported for: SurfPad.", "type": "number" }, "openPosOnReboot": { "description": "Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'. Supported for: SurfTouch, SurfPrint.", "type": "string" }, "enableRefundLock": { "description": "Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals. Supported for: SurfTouch, SurfPrint, SoftPOS. Not live yet.", "type": "boolean" }, "refundScreenPin": { "description": "The PIN code used to authorize refunds on the screen. This is only available for android terminals. Supported for: SurfTouch, SurfPrint, SoftPOS. Not live yet.", "type": "string" }, "screenTimeout": { "description": "The duration (in milliseconds) before the screen times out due to inactivity. Supported for: SurfTouch, SurfPrint, SoftPOS.", "type": "number" }, "autoSleepInterval": { "description": "The interval (in milliseconds) before the device automatically goes to sleep. Supported for: SurfPad.", "type": "number" }, "receiptScreenTimeout": { "description": "Timeout of the receipt screen on hardware terminals. Supported for: SurfTouch, SurfPrint, SoftPOS.", "type": "number" }, "offlineMode": { "description": "Controls whether the terminal keeps accepting card payments while offline (stored and forwarded once connectivity returns). Applies to the sb_terminal_k checkout app.\n\nValues:\n- `enabled`: The terminal accepts card payments while offline.\n- `disabled`: The terminal requires connectivity to accept payments.", "type": "string", "enum": [ "enabled", "disabled" ] }, "displayContrast": { "description": "Display contrast level of the terminal screen.", "type": "number" }, "idleScreenImageUrl": { "description": "URL of the image displayed on the idle screen of the terminal.", "type": "string" }, "lockScreenPin": { "description": "PIN code used to unlock the terminal lock screen.", "type": "string" }, "enableLockScreen": { "description": "Determines whether the lock screen is enabled on the terminal.", "type": "boolean" }, "printerConfig": { "description": "Printer configuration mode for the terminal.", "type": "string" } } }, "example": { "wifiSsid": "wifiname", "wifiPassword": "wifipassword", "autoSleep": 3000, "preferredNetwork": "WIFI", "preferredRestartTime": "03:00", "alwaysShowMinorUnits": 1, "language": "en", "showStatusBar": true, "chipReadDelay": 500, "showReceipt": true, "offlineMode": "enabled" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "STORE config updated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/partners/{partnerId}/merchants/{merchantId}/stores/{storeId}/verify": { "post": { "operationId": "verifyStoreDomain", "summary": "Verify Store Domain", "description": "Use this API to trigger a verify domain request with Surfboard.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Stores API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domainType": { "description": "Specify the domain to be verified.\n\nValues:\n- `MERCHANT_WEBSHOP_URL`: Use this to verify the merchant webshop domain.\n- `PAYMENT_PAGE_HOST_URL`: To verify the payment page host domain use this.", "type": "string", "enum": [ "MERCHANT_WEBSHOP_URL", "PAYMENT_PAGE_HOST_URL" ] } }, "required": [ "domainType" ] }, "example": { "domainType": "MERCHANT_WEBSHOP_URL" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "Message describing the status of domain verification of store.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Domain verification done successfully for store: 8254c42dc430e00e0f." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/partners/{partnerId}/merchants/{merchantId}/stores/{storeId}/online": { "get": { "operationId": "fetchStoreDomains", "summary": "Fetch Store Domains", "description": "This API retrieves the details of the store's domain.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Stores API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "onlineStoreStatus": { "description": "Status of the online store.\n\nValues:\n- `APPROVED`: The online store is approved for online payments.\n- `INITIATED`: The online store verification is initiated.\n- `FAILED`: Failed to verify the online store.", "type": "string", "enum": [ "APPROVED", "INITIATED", "FAILED" ] }, "domains": { "description": "Contains the domain details.", "type": "array", "items": { "type": "object", "properties": { "status": { "description": "The current status of the domain.\n\nValues:\n- `ACTIVE`: The domain is active.\n- `DEACTIVATED`: The domain is deactivated.", "type": "string", "enum": [ "ACTIVE", "DEACTIVATED" ] }, "type": { "description": "Refers to the type of the domain.\n\nValues:\n- `MERCHANT_WEBSHOP_URL`: This represents the merchant webshop domain.\n- `PAYMENT_PAGE_HOST_URL`: This represents the payment page host.", "type": "string", "enum": [ "MERCHANT_WEBSHOP_URL", "PAYMENT_PAGE_HOST_URL" ] }, "name": { "description": "Name of the domain.", "type": "string" }, "verificationKey": { "description": "This is the key set in your domain which is used for verification.", "type": "string" }, "isDomainVerified": { "description": "Indicates whether the domain has been verified.", "type": "boolean" } }, "additionalProperties": true } } }, "additionalProperties": true }, "message": { "description": "Message describing the status of domain verification of store.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "onlineStoreStatus": "APPROVED", "domains": [ { "status": "ACTIVE", "type": "PAYMENT_PAGE_HOST_URL", "name": "www.surfpayapp.com", "verificationKey": "7fd242dd862a9f9f74ae11d62216f5729a5e5600e00b8d44300db41b4efcce68", "isDomainVerified": true }, { "status": "ACTIVE", "type": "MERCHANT_WEBSHOP_URL", "name": "test.surfboard.se", "verificationKey": "7fd242dd862a9f9f74ae11d62216f5729a5e5600e00b8d44300db41b4efcce68", "isDomainVerified": true } ] }, "message": "Online store domain details fetched successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/stores": { "post": { "operationId": "createStoreMerchantScoped", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Stores API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeName": { "description": "Name of the store as it should appear to staff and on reporting.", "type": "string" }, "email": { "description": "Contact email address for the store. Required if you plan to enable online payments for the store.", "type": "string" }, "phoneNumber": { "description": "Contact phone number of the store, split into dialing code and number.", "type": "object", "properties": { "code": { "description": "International dialing code identifying the country or region.", "type": "string" }, "number": { "description": "The local phone number, 5 to 15 digits with no separators.", "type": "string" } }, "required": [ "code", "number" ] }, "address": { "description": "Physical address of the store. City, postal code, and country code are required.", "type": "object", "properties": { "careOf": { "description": "Name of the person or entity receiving correspondence on behalf of the store (c/o).", "type": "string" }, "addressLine1": { "description": "First line of the store's street address.", "type": "string" }, "addressLine2": { "description": "Second line of the store's street address.", "type": "string" }, "addressLine3": { "description": "Third line of the store's street address.", "type": "string" }, "city": { "description": "City where the store is located.", "type": "string" }, "countryCode": { "description": "Two-letter ISO 3166-1 alpha-2 country code in uppercase, representing where the store is located.", "type": "string" }, "postalCode": { "description": "Postal or ZIP code of the store's address.", "type": "string" } }, "required": [ "addressLine1", "city", "countryCode", "postalCode" ] }, "acquirerMID": { "description": "Acquirer Merchant ID, required for payment facilitator partners that operate a store-based acquiring model.", "type": "string" }, "onlineInfo": { "description": "Online store details. Provide these to turn the store into an online store that can accept web payments; doing so initiates domain verification.", "type": "object", "properties": { "merchantWebshopURL": { "description": "The URL of the merchant's webshop.", "type": "string" }, "paymentPageHostURL": { "description": "The URL that hosts the payment page. Required when integrating online payments in SDK mode.", "type": "string" }, "termsAndConditionsURL": { "description": "URL of the webshop's terms and conditions, which must include the refund policy.", "type": "string" }, "privacyPolicyURL": { "description": "URL of the webshop's privacy policy.", "type": "string" }, "googlePayMerchantId": { "description": "Your Google Pay merchant identifier, used to enable Google Pay on the online store.", "type": "string" } }, "required": [ "merchantWebshopURL", "termsAndConditionsURL", "privacyPolicyURL" ] } }, "required": [ "storeName", "address" ] }, "example": { "storeName": "Trial Store", "email": "integrations@surfboard.se", "phoneNumber": { "code": "46", "number": "701234567" }, "address": { "addressLine1": "Hagmarksgatan 3", "city": "Stockholm", "countryCode": "SE", "postalCode": "103 16" } } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Details of the created store.", "type": "object", "properties": { "storeId": { "description": "Identifier of the newly created store. Use this when registering terminals or fetching the store's details.", "type": "string" }, "merchantUrlDomainVerificationKey": { "description": "Verification key to place on the merchant's webshop domain to prove ownership. Returned only when online store details were provided; null otherwise.", "type": "string" }, "paymentPageUrlDomainVerificationKey": { "description": "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.", "type": "string" } }, "required": [ "storeId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "storeId": "81d64e7174dcb00b0f", "merchantUrlDomainVerificationKey": null, "paymentPageUrlDomainVerificationKey": null }, "message": "Store created successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Mandatory address parameters missing" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "listStoresMerchantScoped", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Stores API" ], "parameters": [ { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The stores on the current page.", "type": "array", "items": { "type": "object", "properties": { "storeId": { "description": "Identifier of the store.", "type": "string" }, "status": { "description": "Current lifecycle status of the store.\n\nValues:\n- `ACTIVE`: The store is active and ready for payments.\n- `DEACTIVATED`: The store has been deactivated.\n- `BLOCKED`: The store is blocked from further activity.\n- `INACTIVE`: The store is still in the verification stage.", "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "BLOCKED", "INACTIVE" ] }, "merchantId": { "description": "Identifier of the merchant the store belongs to.", "type": "string" }, "name": { "description": "Name of the store.", "type": "string" }, "address": { "description": "Physical address of the store.", "type": "object", "properties": { "careOf": { "description": "Name of the person or entity receiving correspondence on behalf of the store (c/o).", "type": "string" }, "addressLine1": { "description": "First line of the store's street address.", "type": "string" }, "addressLine2": { "description": "Second line of the store's street address.", "type": "string" }, "addressLine3": { "description": "Third line of the store's street address.", "type": "string" }, "city": { "description": "City where the store is located.", "type": "string" }, "countryCode": { "description": "Two-letter ISO 3166-1 alpha-2 country code in uppercase.", "type": "string" }, "postalCode": { "description": "Postal or ZIP code of the store's address.", "type": "string" } }, "additionalProperties": true }, "onlineInfo": { "description": "Online store details, present only when the store is set up to accept online payments.", "type": "object", "properties": { "merchantWebshopURL": { "description": "The URL of the merchant's webshop.", "type": "string" }, "paymentPageHostURL": { "description": "The URL that hosts the payment page.", "type": "string" }, "termsAndConditionsURL": { "description": "URL of the webshop's terms and conditions.", "type": "string" }, "privacyPolicyURL": { "description": "URL of the webshop's privacy policy.", "type": "string" }, "googlePayMerchantId": { "description": "The Google Pay merchant identifier configured for the online store.", "type": "string" } }, "additionalProperties": true }, "phoneNumber": { "description": "Contact phone number of the store, present only when one is set.", "type": "object", "properties": { "code": { "description": "International dialing code of the store's phone number.", "type": "string" }, "number": { "description": "Local phone number of the store.", "type": "string" } }, "additionalProperties": true }, "email": { "description": "Contact email address of the store.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "storeId": "824bd4a739dc200b0f", "status": "ACTIVE", "merchantId": "81fa6b2d8d5dc8040e", "name": "Trial Store", "address": { "careOf": null, "addressLine1": "Hagmarksgatan 3", "addressLine2": null, "addressLine3": null, "city": "Stockholm", "countryCode": "SE", "postalCode": "103 16" }, "onlineInfo": null, "phoneNumber": { "code": "46", "number": "701234567" }, "email": "integrations@surfboard.se" } ], "message": "Fetched stores successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "No stores found under this merchant" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/stores/deactivate": { "post": { "operationId": "deactivateStoreMerchantScoped", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Stores API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "description": "Identifier of the store to deactivate.", "type": "string" }, "deactivationDate": { "description": "Future date on which the store should be deactivated, in yyyy-mm-dd format. When omitted, the store is deactivated immediately.", "type": "string" } }, "required": [ "storeId" ] }, "example": { "storeId": "824bd4a739dc200b0f", "deactivationDate": "2026-12-31" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the store deactivation.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Store deactivation initiated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Please provide a future date" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/stores/{storeId}": { "get": { "operationId": "fetchOneStoreMerchantScoped", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Stores API" ], "parameters": [ { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Details of the requested store.", "type": "object", "properties": { "storeId": { "description": "Identifier of the store.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant the store belongs to.", "type": "string" }, "name": { "description": "Name of the store.", "type": "string" }, "status": { "description": "Current lifecycle status of the store.\n\nValues:\n- `ACTIVE`: The store is active and ready for payments.\n- `DEACTIVATED`: The store has been deactivated.\n- `BLOCKED`: The store is blocked from further activity.\n- `INACTIVE`: The store is still in the verification stage.", "type": "string", "enum": [ "ACTIVE", "DEACTIVATED", "BLOCKED", "INACTIVE" ] }, "onlineOnboardingStatus": { "description": "Onboarding status of the store for online payments.\n\nValues:\n- `APPROVED`: The store is approved for online payments.\n- `INITIATED`: Online store verification is in progress.\n- `FAILED`: Online store verification failed.", "type": "string", "enum": [ "APPROVED", "INITIATED", "FAILED" ] }, "address": { "description": "Physical address of the store.", "type": "object", "properties": { "careOf": { "description": "Name of the person or entity receiving correspondence on behalf of the store (c/o).", "type": "string" }, "addressLine1": { "description": "First line of the store's street address.", "type": "string" }, "addressLine2": { "description": "Second line of the store's street address.", "type": "string" }, "addressLine3": { "description": "Third line of the store's street address.", "type": "string" }, "city": { "description": "City where the store is located.", "type": "string" }, "countryCode": { "description": "Two-letter ISO 3166-1 alpha-2 country code in uppercase.", "type": "string" }, "postalCode": { "description": "Postal or ZIP code of the store's address.", "type": "string" } }, "additionalProperties": true }, "onlineInfo": { "description": "Online store details, present only when the store is set up to accept online payments.", "type": "object", "properties": { "merchantWebshopURL": { "description": "The URL of the merchant's webshop.", "type": "string" }, "paymentPageHostURL": { "description": "The URL that hosts the payment page.", "type": "string" }, "termsAndConditionsURL": { "description": "URL of the webshop's terms and conditions.", "type": "string" }, "privacyPolicyURL": { "description": "URL of the webshop's privacy policy.", "type": "string" }, "googlePayMerchantId": { "description": "The Google Pay merchant identifier configured for the online store.", "type": "string" } }, "additionalProperties": true }, "phoneNumber": { "description": "Contact phone number of the store, present only when one is set.", "type": "object", "properties": { "code": { "description": "International dialing code of the store's phone number.", "type": "string" }, "number": { "description": "Local phone number of the store.", "type": "string" } }, "additionalProperties": true }, "email": { "description": "Contact email address of the store.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "storeId": "824bd4a739dc200b0f", "merchantId": "81a641f8b3cfd0070e", "name": "Trial Store", "status": "ACTIVE", "onlineOnboardingStatus": "APPROVED", "address": { "careOf": null, "addressLine1": "Hagmarksgatan 3", "addressLine2": null, "addressLine3": null, "city": "Stockholm", "countryCode": "SE", "postalCode": "103 16" }, "onlineInfo": { "merchantWebshopURL": "https://testmerchant.com", "paymentPageHostURL": null, "termsAndConditionsURL": "https://testmerchant.com/terms", "privacyPolicyURL": "https://testmerchant.com/privacy", "googlePayMerchantId": null }, "phoneNumber": { "code": "46", "number": "701234567" }, "email": "integrations@surfboard.se" }, "message": "Fetched store by ID" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to fetch store details." } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/templates": { "post": { "operationId": "createTemplate", "summary": "Create Template", "description": "This API allows you to create a new POS template.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Templates API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethodOrder": { "description": "Array of preferred payment methods that will be displayed on the POS system in the order of preference.", "type": "array", "items": {} }, "name": { "description": "Name or label for the POS template.", "type": "string" }, "productsPerPage": { "description": "Number of products to be displayed per page in the POS template.", "type": "number" }, "product": { "description": "Product categories and their order.", "type": "array", "items": { "type": "object", "properties": { "category": { "description": "Category of the product.", "type": "string" }, "productOrder": { "description": "Array of product IDs in the preferred order.", "type": "array", "items": {} } }, "required": [ "category", "productOrder" ] } }, "autoSet": { "description": "Array of time intervals during which certain automatic settings or actions should be applied.", "type": "array", "items": { "type": "object", "properties": { "start": { "description": "Start time for the interval.", "type": "string" }, "end": { "description": "End time for the interval.", "type": "string" } }, "required": [ "start", "end" ] } }, "terminal": { "description": "Terminal information for the POS template.", "type": "object", "properties": { "primaryTerminal": { "description": "ID of the primary terminal to be used.", "type": "string" }, "secondaryTerminal": { "description": "ID of the secondary terminal to be used.", "type": "string" }, "terminalOrder": { "description": "Array of terminal IDs in the preferred order.", "type": "array", "items": {} } } }, "metaData": { "description": "Additional metadata for the POS template as key-value pairs.", "type": "object", "additionalProperties": true } }, "required": [ "name" ] }, "example": { "paymentMethodOrder": [ "SWISH" ], "name": "SurfboardString", "productsPerPage": 10, "autoSet": [ { "start": "06:00", "end": "09:00" }, { "start": "11:00", "end": "18:00" } ], "product": [ { "category": "electronics", "productOrder": [ "82674cfdf77f500001", "82674cfdf77f500001" ] } ], "terminal": { "primaryTerminal": "82674beadf0f700405", "terminalOrder": [ "82674beadf0f700405" ] }, "metaData": { "we": "do", "do": "we" } } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "templateId": { "description": "The unique identifier of the newly created POS template.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "templateId": "8271dfa5782e380148" }, "message": "Pos-Template Created Successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{sId}/templates/{templateId}": { "put": { "operationId": "updateTemplate", "summary": "Update Template", "description": "This API allows you to update an existing POS template.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Templates API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "sId", "in": "path", "required": true, "description": "Identifier for the s this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "description": "Identifier for the template this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethodOrder": { "description": "Array of preferred payment methods that will be displayed on the POS system in the order of preference.", "type": "array", "items": {} }, "name": { "description": "Name or label for the POS template.", "type": "string" }, "productsPerPage": { "description": "Number of products to be displayed per page in the POS template.", "type": "number" }, "product": { "description": "Product categories and their order.", "type": "array", "items": { "type": "object", "properties": { "category": { "description": "Category of the product.", "type": "string" }, "productOrder": { "description": "Array of product IDs in the preferred order.", "type": "array", "items": {} } }, "required": [ "category", "productOrder" ] } }, "autoSet": { "description": "Array of time intervals during which certain automatic settings or actions should be applied.", "type": "array", "items": { "type": "object", "properties": { "start": { "description": "Start time for the interval.", "type": "string" }, "end": { "description": "End time for the interval.", "type": "string" } }, "required": [ "start", "end" ] } }, "terminal": { "description": "Terminal information for the POS template.", "type": "object", "properties": { "primaryTerminal": { "description": "ID of the primary terminal to be used.", "type": "string" }, "secondaryTerminal": { "description": "ID of the secondary terminal to be used.", "type": "string" }, "terminalOrder": { "description": "Array of terminal IDs in the preferred order.", "type": "array", "items": {} } } }, "metaData": { "description": "Additional metadata for the POS template as key-value pairs.", "type": "object", "additionalProperties": true } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Pos-Template updated Successfully for template id 8269d8d131d1100848" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchTemplateById", "summary": "Fetch Template by ID", "description": "This API retrieves the details of a specific POS template using its ID.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Templates API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "sId", "in": "path", "required": true, "description": "Identifier for the s this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "description": "Identifier for the template this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "templateId": { "description": "The unique identifier of the newly created POS template.", "type": "string" }, "userId": { "description": "Unique identifier of the user who created the POS template.", "type": "string" }, "paymentMethodOrder": { "description": "Array of preferred payment methods that will be displayed on the POS system in the order of preference.", "type": "array", "items": {} }, "name": { "description": "Name or label for the POS template.", "type": "string" }, "productsPerPage": { "description": "Number of products to be displayed per page in the POS template.", "type": "number" }, "product": { "description": "Product categories and their order.", "type": "array", "items": { "type": "object", "properties": { "category": { "description": "Category of the product.", "type": "string" }, "productOrder": { "description": "Array of product IDs in the preferred order.", "type": "array", "items": {} } }, "required": [ "category", "productOrder" ], "additionalProperties": true } }, "autoSet": { "description": "Array of time intervals during which certain automatic settings or actions should be applied.", "type": "array", "items": { "type": "object", "properties": { "start": { "description": "Start time for the interval.", "type": "string" }, "end": { "description": "End time for the interval.", "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": true } }, "terminal": { "description": "Terminal information for the POS template.", "type": "object", "properties": { "primaryTerminal": { "description": "ID of the primary terminal to be used.", "type": "string" }, "secondaryTerminal": { "description": "ID of the secondary terminal to be used.", "type": "string" }, "terminalOrder": { "description": "Array of terminal IDs in the preferred order.", "type": "array", "items": {} } }, "additionalProperties": true }, "metaData": { "description": "Additional metadata for the POS template as key-value pairs.", "type": "object", "additionalProperties": true }, "deleted": { "description": "Denotes whether the template was deleted or not", "type": "boolean" } }, "required": [ "name" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "templateId": "8267defa6150700b48", "userId": "u_EArLulLMogC6b-9e9Gci0", "name": "SurfboardString", "terminalOrder": { "terminalOrder": [ "82674beadf0f700405" ], "primaryTerminal": "82674beadf0f700405", "secondaryTerminal": null }, "categoryOrder": null, "productOrder": [ { "category": "electronics", "productOrder": [ "82674cfdf77f500001", "82674cfdf77f500001" ] } ], "paymentMethodOrder": [ "SWISH" ], "autoSet": [ { "start": "06:00", "end": "09:00" }, { "start": "11:00", "end": "18:00" } ], "deleted": false, "metadata": { "we": "do", "do": "we" } }, "message": "Template Data fetched successfully for the template id [8267defa6150700b48]" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "delete": { "operationId": "deleteTemplateById", "summary": "Delete Template by ID", "description": "Use this API to delete an existing template by Template ID.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Templates API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "sId", "in": "path", "required": true, "description": "Identifier for the s this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "required": true, "description": "Identifier for the template this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Template id [8271dfa5782e380148] deleted successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{sId}/templates": { "get": { "operationId": "fetchTemplates", "summary": "Fetch Templates", "description": "This API retrieves all the POS templates created under the user.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Templates API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "sId", "in": "path", "required": true, "description": "Identifier for the s this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "array", "items": { "type": "object", "properties": { "templateId": { "description": "The unique identifier of the newly created POS template.", "type": "string" }, "userId": { "description": "Unique identifier of the user who created the POS template.", "type": "string" }, "paymentMethodOrder": { "description": "Array of preferred payment methods that will be displayed on the POS system in the order of preference.", "type": "array", "items": {} }, "name": { "description": "Name or label for the POS template.", "type": "string" }, "productsPerPage": { "description": "Number of products to be displayed per page in the POS template.", "type": "number" }, "product": { "description": "Product categories and their order.", "type": "array", "items": { "type": "object", "properties": { "category": { "description": "Category of the product.", "type": "string" }, "productOrder": { "description": "Array of product IDs in the preferred order.", "type": "array", "items": {} } }, "required": [ "category", "productOrder" ], "additionalProperties": true } }, "autoSet": { "description": "Array of time intervals during which certain automatic settings or actions should be applied.", "type": "array", "items": { "type": "object", "properties": { "start": { "description": "Start time for the interval.", "type": "string" }, "end": { "description": "End time for the interval.", "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": true } }, "terminal": { "description": "Terminal information for the POS template.", "type": "object", "properties": { "primaryTerminal": { "description": "ID of the primary terminal to be used.", "type": "string" }, "secondaryTerminal": { "description": "ID of the secondary terminal to be used.", "type": "string" }, "terminalOrder": { "description": "Array of terminal IDs in the preferred order.", "type": "array", "items": {} } }, "additionalProperties": true }, "metaData": { "description": "Additional metadata for the POS template as key-value pairs.", "type": "object", "additionalProperties": true }, "deleted": { "description": "Denotes whether the template was deleted or not", "type": "boolean" } }, "required": [ "name" ], "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "templateId": "826dcc0b62e0100248", "userId": "u_EArLulLMogC6b-9e9Gci0", "name": "SurfboardString", "terminalOrder": { "terminalOrder": [ "82674beadf0f700405" ], "primaryTerminal": "82674beadf0f700405", "secondaryTerminal": null }, "categoryOrder": null, "productOrder": [ { "category": "electronics", "productOrder": [ "82674cfdf77f500001", "82674cfdf77f500001" ] } ], "paymentMethodOrder": [ "SWISH" ], "autoSet": [ { "start": "06:00", "end": "09:00" }, { "start": "11:00", "end": "18:00" } ], "deleted": false } ], "message": "Template Data fetched successfully for the user id [u_EArLulLMogC6b-9e9Gci0]" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/devices": { "post": { "operationId": "registerDevice", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "registrationIdentifier": { "description": "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.", "type": "string" }, "terminalName": { "description": "Assign a name for your terminal. An optional param to identify a terminal for the user.", "type": "string" } }, "required": [ "registrationIdentifier" ] }, "example": { "registrationIdentifier": "250901", "terminalName": "Kiosk One" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the terminal registration.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "terminalId": { "description": "Terminal ID of the registered terminal.", "type": "string" }, "publicKey": { "description": "The terminal public key. Populated for online/SDK terminals; typically null for hardware devices.", "type": "string" }, "registrationStatus": { "description": "Represents the current status of the terminal. The possible values are:\n\nValues:\n- `REGISTERED`: The terminal has been successfully registered.\n- `ALREADY_REGISTERED`: The terminal is already registered.", "type": "string", "enum": [ "REGISTERED", "ALREADY_REGISTERED" ] }, "sdkUrl": { "description": "The SDK server URL, returned when a self-hosted SDK key is provisioned for the terminal.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the terminal registration.", "type": "string" } }, "required": [ "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "terminalId": "813ca2cb12ce400405", "registrationStatus": "REGISTERED" }, "message": "Terminal registered successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/stores/{storeId}/device-registration": { "get": { "operationId": "getDeviceRegistrationCode", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data containing registration information.", "type": "object", "properties": { "registrationCode": { "description": "6-digit registration code that can be entered on the device for registration.", "type": "string" }, "registrationLink": { "description": "Deep link URL that can be used for automatic device registration.", "type": "string" } }, "required": [ "registrationCode", "registrationLink" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "registrationCode": "905788", "registrationLink": "checkoutx://com.surfboard.checkoutx/register?data=eyJyZWdpc3RyYXRpb25Db2RlIjoiOTA1Nzg4In0=" }, "message": "Registration Code Generated Successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/stores/{storeId}/online-terminals": { "post": { "operationId": "registerOnlineTerminal", "summary": "Register Online Terminal", "description": "Registers a terminal with an online store so it can accept online payments.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "onlineTerminalMode": { "description": "Online payments can be carried out using any of these following modes.\n\nValues:\n- `PaymentPage`: In this mode, the payment page and all associated configuration is managed by Surfboard. This is the simplest mode to integrate as all that is required as an integrating partner is to redirect the customer to the payment page. The payment page needs to be the top level frame in any given context.\n- `SelfHostedPage`: With SelfHostedPage, Surfboard renders the fields in your page. This provides you with maximum customization as to render the layout any way you want.\n- `iFrame`: Registers an online terminal that renders as an embeddable iFrame.\n- `MerchantInitiated`: Set this type if you want to accept Merchant Initiated Transactions (MIT).", "type": "string", "enum": [ "PaymentPage", "SelfHostedPage", "iFrame", "MerchantInitiated" ] } }, "required": [ "onlineTerminalMode" ] }, "example": { "onlineTerminalMode": "PaymentPage" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the terminal registration.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "terminalId": { "description": "Terminal ID of the registered terminal.", "type": "string" }, "publicKey": { "description": "For SelfHostedPage terminals use this key to initialize your Online SDK.", "type": "string" }, "registrationStatus": { "description": "Represents the current status of the terminal. The possible values are:\n\nValues:\n- `REGISTERED`: The terminal has been successfully registered.\n- `DEREGISTERED`: The terminal was previously registered but has now been removed from the system.\n- `FAILED`: The registration was unsuccessful.", "type": "string", "enum": [ "REGISTERED", "DEREGISTERED", "FAILED" ] }, "sdkUrl": { "description": "The SDK server URL, returned when a self-hosted SDK key is provisioned for the terminal.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the terminal registration.", "type": "string" } }, "required": [ "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "terminalId": "813ca2cb12ce400405" }, "message": "Terminal registered successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/terminals/deactivate": { "post": { "operationId": "delinkTerminalFromStore", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terminal$id": { "description": "Terminal ID of the terminal that has to be delinked.", "type": "string" }, "storeId": { "description": "Store ID of the store from which the terminal needs to be delinked.", "type": "string" } }, "required": [ "terminal$id" ] }, "example": { "terminal$id": "c_Ou8mzoVQVn6dS4hvNtKH2", "storeId": "st_GZVDbwmS86_G9pwc669U2" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "A message that describes the status of the terminal delinking.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Terminal removed from store" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/terminals/change": { "post": { "operationId": "changeStore", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terminal$id": { "description": "Terminal ID of the terminal for which the store needs to be changed.", "type": "string" }, "storeId": { "description": "Store ID of the store to which the terminal needs to be registered.", "type": "string" } }, "required": [ "terminal$id" ] }, "example": { "terminal$id": "c_Ou8mzoVQVn6dS4hvNtKH2", "storeId": "st_GZVDbwmS86_G9pwc669U2" } } } }, "responses": { "201": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the store change.", "type": "string" }, "message": { "description": "A message that describes the status of the store change.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Store successfully changed for the terminal" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/terminals/{terminalId}/link": { "put": { "operationId": "linkTerminal", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terminal$id": { "description": "Terminal ID of the terminal to link to the CheckoutPro identified by the :terminalId path parameter.", "type": "string" } }, "required": [ "terminal$id" ] }, "example": { "terminal$id": "814aae4268e6700704" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "A message that describes the status of the linking request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Terminal linked successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "delete": { "operationId": "delinkTerminal", "summary": "Delink Terminal", "description": "Delinks the terminal from its linked CheckoutPro. Use this API to swap the terminal between different Checkouts.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminal$id", "in": "query", "required": true, "description": "Terminal ID of the terminal to delink from the CheckoutPro identified by the :terminalId path parameter.", "schema": { "description": "Terminal ID of the terminal to delink from the CheckoutPro identified by the :terminalId path parameter.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "A message that describes the status of the delinking request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Terminal delinked successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "checkLinkStatus", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "linkageStatus": { "description": "Describes the linkage status of the terminal with CheckoutPro. i.e. ‘LINKED’ | ‘NOT_LINKED’.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "linkageStatus": "LINKED" }, "message": "Fetched terminal status" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/terminals/{terminalId}": { "put": { "operationId": "updateTerminalName", "summary": "Update Terminal Name", "description": "Updates the display name of a registered terminal.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "terminalName": { "description": "Assign a name for your terminal. A param to identify a terminal for the user.", "type": "string" }, "metadata": { "description": "Arbitrary key-value metadata to store against the terminal. At least one of terminalName or metadata must be provided.", "type": "object", "additionalProperties": true } } }, "example": { "terminalName": "New Terminal" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "A message that describes the status of the update request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Terminal updated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchTerminalById", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "terminalId": { "description": "Terminal ID of the terminal.", "type": "string" }, "terminalType": { "description": "Describes the type of the terminal.\n\nValues:\n- `surfpad`: Hardware terminal with a physical keypad.\n- `surftouch`: Android terminal with custom payment apps, digital receipts etc.\n- `surfprint`: Android terminal with a built-in printer.\n- `checkoutPro`: Complete checkout solution with a customer facing screen.\n- `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.\n- `PaymentPage`: In this mode, the payment page and all associated configuration is managed by Surfboard.\n- `SelfHostedPage`: With SelfHostedPage, Surfboard renders the fields in your page.\n- `iFrame`: Online terminal rendered as an embeddable iFrame.\n- `MerchantInitiated`: Set this type if you want to accept Merchant Initiated Transactions (MIT).", "type": "string", "enum": [ "surfpad", "surftouch", "surfprint", "checkoutPro", "checkoutX", "PaymentPage", "SelfHostedPage", "iFrame", "MerchantInitiated" ] }, "softwareVersion": { "description": "Software version of the terminal.", "type": "string" }, "osType": { "description": "Describes the type of Operating System (OS) running on the terminal.\n\nValues:\n- `android`: Android operating system.\n- `ios`: Apple's operating system for iPhones.\n- `sb_firmware`: Surfboard firmware.", "type": "string", "enum": [ "android", "ios", "sb_firmware" ] }, "osVersion": { "description": "Operating System (OS) version of the terminal.", "type": "string" }, "deviceVendor": { "description": "Device vendor of the terminal.", "type": "string" }, "deviceModel": { "description": "Device model of the terminal.", "type": "string" }, "serialNo": { "description": "Serial number of the terminal.", "type": "string" }, "storeId": { "description": "The Store ID of the store under which the terminal is registered.", "type": "string" }, "linkedTerminalId": { "description": "The Terminal ID of another terminal to which the current terminal is linked.", "type": "string" }, "terminalStatus": { "description": "Status of the terminal, it can be in one of these states: REGISTERED | ACTIVE | IN_ACTIVE | DE_REGISTERED.", "type": "string" }, "terminalPaymentMethods": { "description": "Payment methods supported by the terminal.", "type": "string" }, "startDate": { "description": "Timestamp at which the terminal was created.", "type": "string" }, "terminalName": { "description": "Name of the terminal used as a reference for users.", "type": "string" }, "lastAliveAt": { "description": "Time at which the terminal was last seen online.", "type": "string" }, "isCharging": { "description": "A boolean value that denotes if the terminal is charging or not.", "type": "boolean" }, "batteryPercentage": { "description": "Battery percentage of the terminal.", "type": "number" }, "powerSource": { "description": "Current power source to the terminal.\n\nValues:\n- `EXTERNAL_POWER`: Connected to an external power source.\n- `BATTERY`: Charging via battery source.", "type": "string", "enum": [ "EXTERNAL_POWER", "BATTERY" ] }, "deviceNetwork": { "description": "The current mode of communication.\n\nValues:\n- `WIFI`: The terminal is connected to WIFI.\n- `GSM`: The terminal is connected to GSM.", "type": "string", "enum": [ "WIFI", "GSM" ] }, "turnOnTime": { "description": "Last boot up time of terminal.", "type": "string" }, "terminalPublicKey": { "description": "Public key used while initializing the SelfHostedPage Online Terminal (Online SDK).", "type": "string" }, "metadata": { "description": "Arbitrary key-value metadata stored against the terminal.", "type": "object", "additionalProperties": true }, "wifiStrength": { "description": "Wi-Fi signal strength reported by the terminal.", "type": "number" }, "gsmStrength": { "description": "GSM signal strength reported by the terminal.", "type": "number" }, "signalStrength": { "description": "Overall network signal strength reported by the terminal.", "type": "number" }, "softwareMode": { "description": "Software mode the terminal is running in.", "type": "string" }, "sdkUrl": { "description": "SDK URL associated with the terminal.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "terminalId": "81f878852b3a280904", "terminalType": "surfpad", "softwareVersion": "0.0.0", "osType": "sb_firmware", "osVersion": "0.0.0", "deviceVendor": "Datecs", "deviceModel": "Datecs PinPad", "serialNo": "2922000007", "storeId": "81497439a52270000f", "linkedTerminalId": null, "terminalStatus": "ACTIVE", "startDate": "2022-11-17T09:29:51.427Z", "terminalPaymentMethods": [ "CARD" ], "terminalName": "My Terminal", "lastAliveAt": "2024-02-21T08:48:26.000Z", "isCharging": false, "batteryPercentage": 100, "powerSource": "BATTERY", "deviceNetwork": "WIFI", "turnOnTime": "2024-02-21T05:14:33.417Z" }, "message": "Fetched terminal details successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/partners/{partnerId}/terminals/{serialNo}/move": { "put": { "operationId": "moveTerminal", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "serialNo", "in": "path", "required": true, "description": "Identifier for the serial no this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetMerchantId": { "description": "Target Merchant ID to which the terminal needs to be assigned.", "type": "string" } }, "required": [ "targetMerchantId" ] }, "example": { "targetMerchantId": "81fa6b2d8d5dc8040e" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "A message that describes the status of the move terminal request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Changed merchant for terminal successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/terminals/{terminalId}": { "patch": { "operationId": "setTerminalConfig", "summary": "Set Terminal Config", "description": "Sets specific configurations for an individual terminal. Use this API to configure settings and parameters for a particular terminal.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "serialNo": { "description": "Serial number of the physical terminal. Supported for: SurfPad, SurfTouch, SurfPrint.", "type": "string" }, "wifiSsid": { "description": "Name of the WiFi network. Supported for: SurfPad.", "type": "string" }, "wifiPassword": { "description": "Password for the WiFi network. Supported for: SurfPad.", "type": "string" }, "autoSleep": { "description": "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. Supported for: SurfPad.", "type": "number" }, "preferredRestartTime": { "description": "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. Supported for: SurfPad.", "type": "string" }, "preferredNetwork": { "description": "Preferred network for the terminal. It can be either 'WIFI' or 'GSM'. Supported for: SurfPad.", "type": "string" }, "alwaysShowMinorUnits": { "description": "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. Supported for: SurfPad.", "type": "number" }, "language": { "description": "Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'. Supported for: SurfPad, SurfTouch, SurfPrint, SoftPOS.", "type": "string" }, "showStatusBar": { "description": "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. Supported for: SurfPad.", "type": "boolean" }, "chipReadDelay": { "description": "Time delay in milliseconds before the card is read. Supported for: SurfPad.", "type": "number" }, "showReceipt": { "description": "Set this to determine how receipts are showcased on the terminal. Supported for: SurfTouch, SurfPrint, SoftPOS.", "type": "boolean" }, "preferredGsmOperator": { "description": "The preferred GSM operator identified by a numeric code. Supported for: SurfPad.", "type": "number" }, "openPosOnReboot": { "description": "Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'. Supported for: SurfTouch, SurfPrint.", "type": "string" }, "enableRefundLock": { "description": "Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals. Supported for: SurfTouch, SurfPrint, SoftPOS. Not live yet.", "type": "boolean" }, "refundScreenPin": { "description": "The PIN code used to authorize refunds on the screen. This is only available for android terminals. Supported for: SurfTouch, SurfPrint, SoftPOS. Not live yet.", "type": "string" }, "screenTimeout": { "description": "The duration (in milliseconds) before the screen times out due to inactivity. Supported for: SurfTouch, SurfPrint, SoftPOS.", "type": "number" }, "autoSleepInterval": { "description": "The interval (in milliseconds) before the device automatically goes to sleep. Supported for: SurfPad.", "type": "number" }, "receiptScreenTimeout": { "description": "Timeout of the receipt screen on hardware terminals. Supported for: SurfTouch, SurfPrint, SoftPOS.", "type": "number" }, "offlineMode": { "description": "Controls whether the terminal keeps accepting card payments while offline (stored and forwarded once connectivity returns). Applies to the sb_terminal_k checkout app.\n\nValues:\n- `enabled`: The terminal accepts card payments while offline.\n- `disabled`: The terminal requires connectivity to accept payments.", "type": "string", "enum": [ "enabled", "disabled" ] }, "displayContrast": { "description": "Display contrast level of the terminal screen.", "type": "number" }, "idleScreenImageUrl": { "description": "URL of the image displayed on the idle screen of the terminal.", "type": "string" }, "lockScreenPin": { "description": "PIN code used to unlock the terminal lock screen.", "type": "string" }, "enableLockScreen": { "description": "Determines whether the lock screen is enabled on the terminal.", "type": "boolean" }, "printerConfig": { "description": "Printer configuration mode for the terminal.", "type": "string" } } }, "example": { "serialNo": "123456789", "wifiSsid": "wifiname", "wifiPassword": "wifipassword", "autoSleep": 3000, "preferredNetwork": "WIFI", "preferredRestartTime": "03:00", "alwaysShowMinorUnits": 1, "language": "en", "showStatusBar": true, "chipReadDelay": 500, "showReceipt": true, "offlineMode": "enabled" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "TERMINAL config updated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchTerminalByIdUnderStore", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "terminalId": { "description": "Terminal ID of the terminal.", "type": "string" }, "terminalType": { "description": "Describes the type of the terminal.\n\nValues:\n- `surfpad`: Hardware terminal with a physical keypad.\n- `surftouch`: Android terminal with custom payment apps, digital receipts etc.\n- `surfprint`: Android terminal with a built-in printer.\n- `checkoutPro`: Complete checkout solution with a customer facing screen.\n- `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.\n- `PaymentPage`: In this mode, the payment page and all associated configuration is managed by Surfboard.\n- `SelfHostedPage`: With SelfHostedPage, Surfboard renders the fields in your page.\n- `iFrame`: Online terminal rendered as an embeddable iFrame.\n- `MerchantInitiated`: Set this type if you want to accept Merchant Initiated Transactions (MIT).", "type": "string", "enum": [ "surfpad", "surftouch", "surfprint", "checkoutPro", "checkoutX", "PaymentPage", "SelfHostedPage", "iFrame", "MerchantInitiated" ] }, "softwareVersion": { "description": "Software version of the terminal.", "type": "string" }, "osType": { "description": "Describes the type of Operating System (OS) running on the terminal.\n\nValues:\n- `android`: Android operating system.\n- `ios`: Apple's operating system for iPhones.\n- `sb_firmware`: Surfboard firmware.", "type": "string", "enum": [ "android", "ios", "sb_firmware" ] }, "osVersion": { "description": "Operating System (OS) version of the terminal.", "type": "string" }, "deviceVendor": { "description": "Device vendor of the terminal.", "type": "string" }, "deviceModel": { "description": "Device model of the terminal.", "type": "string" }, "serialNo": { "description": "Serial number of the terminal.", "type": "string" }, "storeId": { "description": "The Store ID of the store under which the terminal is registered.", "type": "string" }, "linkedTerminalId": { "description": "The Terminal ID of another terminal to which the current terminal is linked.", "type": "string" }, "terminalStatus": { "description": "Status of the terminal, it can be in one of these states: REGISTERED | ACTIVE | IN_ACTIVE | DE_REGISTERED.", "type": "string" }, "terminalPaymentMethods": { "description": "Payment methods supported by the terminal.", "type": "string" }, "startDate": { "description": "Timestamp at which the terminal was created.", "type": "string" }, "terminalName": { "description": "Name of the terminal used as a reference for users.", "type": "string" }, "lastAliveAt": { "description": "Time at which the terminal was last seen online.", "type": "string" }, "isCharging": { "description": "A boolean value that denotes if the terminal is charging or not.", "type": "boolean" }, "batteryPercentage": { "description": "Battery percentage of the terminal.", "type": "number" }, "powerSource": { "description": "Current power source to the terminal.\n\nValues:\n- `EXTERNAL_POWER`: Connected to an external power source.\n- `BATTERY`: Charging via battery source.", "type": "string", "enum": [ "EXTERNAL_POWER", "BATTERY" ] }, "deviceNetwork": { "description": "The current mode of communication.\n\nValues:\n- `WIFI`: The terminal is connected to WIFI.\n- `GSM`: The terminal is connected to GSM.", "type": "string", "enum": [ "WIFI", "GSM" ] }, "turnOnTime": { "description": "Last boot up time of terminal.", "type": "string" }, "terminalPublicKey": { "description": "Public key used while initializing the SelfHostedPage Online Terminal (Online SDK).", "type": "string" }, "metadata": { "description": "Arbitrary key-value metadata stored against the terminal.", "type": "object", "additionalProperties": true }, "wifiStrength": { "description": "Wi-Fi signal strength reported by the terminal.", "type": "number" }, "gsmStrength": { "description": "GSM signal strength reported by the terminal.", "type": "number" }, "signalStrength": { "description": "Overall network signal strength reported by the terminal.", "type": "number" }, "softwareMode": { "description": "Software mode the terminal is running in.", "type": "string" }, "sdkUrl": { "description": "SDK URL associated with the terminal.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "terminalId": "81f878852b3a280904", "terminalType": "surfpad", "softwareVersion": "0.0.0", "osType": "sb_firmware", "osVersion": "0.0.0", "deviceVendor": "Datecs", "deviceModel": "Datecs PinPad", "serialNo": "2922000007", "storeId": "81497439a52270000f", "linkedTerminalId": null, "terminalStatus": "ACTIVE", "startDate": "2022-11-17T09:29:51.427Z", "terminalPaymentMethods": [ "CARD" ], "terminalName": "My Terminal", "lastAliveAt": "2024-02-21T08:48:26.000Z", "isCharging": false, "batteryPercentage": 100, "powerSource": "BATTERY", "deviceNetwork": "WIFI", "turnOnTime": "2024-02-21T05:14:33.417Z" }, "message": "Fetched terminal details successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true }, "delete": { "operationId": "deactivateTerminalUnderStore", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "A message that describes the status of the terminal removal.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Terminal removed from store" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/terminals": { "patch": { "operationId": "setMerchantTerminalConfig", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "wifiSsid": { "description": "Name of the WiFi network. Supported for: SurfPad.", "type": "string" }, "wifiPassword": { "description": "Password for the WiFi network. Supported for: SurfPad.", "type": "string" }, "autoSleep": { "description": "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. Supported for: SurfPad.", "type": "number" }, "preferredRestartTime": { "description": "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. Supported for: SurfPad.", "type": "string" }, "preferredNetwork": { "description": "Preferred network for the terminal. It can be either 'WIFI' or 'GSM'. Supported for: SurfPad.", "type": "string" }, "alwaysShowMinorUnits": { "description": "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. Supported for: SurfPad.", "type": "number" }, "language": { "description": "Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'. Supported for: SurfPad, SurfTouch, SurfPrint, SoftPOS.", "type": "string" }, "showStatusBar": { "description": "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. Supported for: SurfPad.", "type": "boolean" }, "chipReadDelay": { "description": "Time delay in milliseconds before the card is read. Supported for: SurfPad.", "type": "number" }, "showReceipt": { "description": "Set this to determine how receipts are showcased on the terminal. Supported for: SurfTouch, SurfPrint, SoftPOS.", "type": "boolean" }, "preferredGsmOperator": { "description": "The preferred GSM operator identified by a numeric code. Supported for: SurfPad.", "type": "number" }, "openPosOnReboot": { "description": "Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'. Supported for: SurfTouch, SurfPrint.", "type": "string" }, "enableRefundLock": { "description": "Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals. Supported for: SurfTouch, SurfPrint, SoftPOS. Not live yet.", "type": "boolean" }, "refundScreenPin": { "description": "The PIN code used to authorize refunds on the screen. This is only available for android terminals. Supported for: SurfTouch, SurfPrint, SoftPOS. Not live yet.", "type": "string" }, "screenTimeout": { "description": "The duration (in milliseconds) before the screen times out due to inactivity. Supported for: SurfTouch, SurfPrint, SoftPOS.", "type": "number" }, "autoSleepInterval": { "description": "The interval (in milliseconds) before the device automatically goes to sleep. Supported for: SurfPad.", "type": "number" }, "receiptScreenTimeout": { "description": "Timeout of the receipt screen on hardware terminals. Supported for: SurfTouch, SurfPrint, SoftPOS.", "type": "number" }, "offlineMode": { "description": "Controls whether the terminal keeps accepting card payments while offline (stored and forwarded once connectivity returns). Applies to the sb_terminal_k checkout app.\n\nValues:\n- `enabled`: The terminal accepts card payments while offline.\n- `disabled`: The terminal requires connectivity to accept payments.", "type": "string", "enum": [ "enabled", "disabled" ] }, "displayContrast": { "description": "Display contrast level of the terminal screen.", "type": "number" }, "idleScreenImageUrl": { "description": "URL of the image displayed on the idle screen of the terminal.", "type": "string" }, "lockScreenPin": { "description": "PIN code used to unlock the terminal lock screen.", "type": "string" }, "enableLockScreen": { "description": "Determines whether the lock screen is enabled on the terminal.", "type": "boolean" }, "printerConfig": { "description": "Printer configuration mode for the terminal.", "type": "string" } } }, "example": { "wifiSsid": "wifiname", "wifiPassword": "wifipassword", "autoSleep": 3000, "preferredNetwork": "WIFI", "preferredRestartTime": "03:00", "alwaysShowMinorUnits": 1, "language": "en", "showStatusBar": true, "chipReadDelay": 500, "showReceipt": true, "offlineMode": "enabled" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "MERCHANT config updated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "queryTerminalsUnderMerchant", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalType", "in": "query", "required": false, "description": "Filters the terminals by type. For example 'surfpad', 'surftouch', 'surfprint', 'checkoutPro', 'checkoutX' or 'iFrame'.", "schema": { "description": "Filters the terminals by type. For example 'surfpad', 'surftouch', 'surfprint', 'checkoutPro', 'checkoutX' or 'iFrame'.", "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "array", "items": { "type": "object", "properties": { "terminalId": { "description": "Terminal ID of the terminal.", "type": "string" }, "terminalType": { "description": "Describes the type of the terminal, for example 'surfpad', 'surftouch', 'surfprint', 'checkoutPro', 'checkoutX' or 'iFrame'.", "type": "string" }, "softwareVersion": { "description": "Software version of the terminal.", "type": "string" }, "osType": { "description": "Describes the type of Operating System (OS) running on the terminal.", "type": "string" }, "osVersion": { "description": "Operating System (OS) version of the terminal.", "type": "string" }, "deviceVendor": { "description": "Device vendor of the terminal.", "type": "string" }, "deviceModel": { "description": "Device model of the terminal.", "type": "string" }, "serialNo": { "description": "Serial number of the terminal.", "type": "string" }, "lastAliveAt": { "description": "Timestamp of the last time the terminal was seen alive.", "type": "string" }, "isCharging": { "description": "Whether the terminal is currently charging.", "type": "boolean" }, "batteryPercentage": { "description": "Current battery charge level of the terminal, as a percentage.", "type": "number" }, "wifiStrength": { "description": "Wi-Fi signal strength of the terminal.", "type": "number" }, "gsmStrength": { "description": "GSM signal strength of the terminal.", "type": "number" }, "powerSource": { "description": "Power source the terminal is currently using.", "type": "string" }, "deviceNetwork": { "description": "Network the terminal device is connected to.", "type": "string" }, "turnOnTime": { "description": "Timestamp of when the terminal was last turned on.", "type": "string" }, "softwareMode": { "description": "The software mode the terminal is running in.", "type": "string" }, "terminalPublicKey": { "description": "The public key of the terminal.", "type": "string" }, "signalStrength": { "description": "Overall signal strength reported by the terminal.", "type": "number" }, "sdkUrl": { "description": "The SDK server URL, present for self-hosted SDK terminals.", "type": "string" }, "storeId": { "description": "The Store ID of the store under which the terminal is registered.", "type": "string" }, "linkedTerminalId": { "description": "The Terminal ID of another terminal to which the current terminal is linked.", "type": "string" }, "terminalStatus": { "description": "Status of the terminal, it can be in one of these states: REGISTERED | ACTIVE | IN_ACTIVE | DE_REGISTERED.", "type": "string" }, "startDate": { "description": "Timestamp at which the terminal was created.", "type": "string" }, "terminalPaymentMethods": { "description": "Payment methods supported by the terminal.", "type": "string" }, "terminalName": { "description": "Name of the terminal used as a reference for users.", "type": "string" }, "terminalCurrencyCode": { "description": "Currency code associated with the terminal.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "terminalId": "81f878852b3a280904", "terminalType": "surfpad", "serialNo": "2922000007", "storeId": "81497439a52270000f", "terminalStatus": "ACTIVE", "terminalName": "My Terminal", "terminalCurrencyCode": "NA" } ], "message": "Fetched terminals successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/stores/{storeId}/terminals/{terminalId}/config": { "get": { "operationId": "fetchTerminalConfig", "summary": "Fetch Terminal Config", "description": "Use this API to fetch all currently active configurations for the terminal.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "wifiSsid": { "description": "Name of the WiFi network.", "type": "string" }, "wifiPassword": { "description": "Password for the WiFi network.", "type": "string" }, "autoSleep": { "description": "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.", "type": "number" }, "preferredRestartTime": { "description": "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.", "type": "string" }, "preferredNetwork": { "description": "Preferred network for the terminal. It can be either 'WIFI' or 'GSM'.\n\nValues:\n- `WIFI`: Sets the preferred network of the terminal as WiFi.\n- `GSM`: Sets the preferred network of the terminal as GSM or mobile network.", "type": "string", "enum": [ "WIFI", "GSM" ] }, "alwaysShowMinorUnits": { "description": "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.", "type": "number" }, "language": { "description": "Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'.", "type": "string" }, "showStatusBar": { "description": "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.", "type": "boolean" }, "chipReadDelay": { "description": "Time delay in milliseconds before the card is read.", "type": "number" }, "showReceipt": { "description": "Set this to determine how receipts are showcased on the terminal.", "type": "boolean" }, "preferredGsmOperator": { "description": "The preferred GSM operator identified by a numeric code.", "type": "number" }, "openPosOnReboot": { "description": "Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'.", "type": "string" }, "enableRefundLock": { "description": "Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals.", "type": "boolean" }, "screenTimeout": { "description": "The duration (in milliseconds) before the screen times out due to inactivity.", "type": "number" }, "autoSleepInterval": { "description": "The interval (in milliseconds) before the device automatically goes to sleep.", "type": "number" }, "receiptScreenTimeout": { "description": "Timeout of the receipt screen on hardware terminals.", "type": "number" }, "offlineMode": { "description": "Current offline-payments toggle for the terminal.\n\nValues:\n- `enabled`: Offline card payments are enabled.\n- `disabled`: Offline card payments are disabled.", "type": "string", "enum": [ "enabled", "disabled" ] }, "displayContrast": { "description": "Display contrast level of the terminal screen.", "type": "number" }, "idleScreenImageUrl": { "description": "URL of the image shown on the terminal idle screen.", "type": "string" }, "lockScreenPin": { "description": "PIN required to unlock the terminal lock screen.", "type": "string" }, "refundScreenPin": { "description": "PIN required to authorize refunds on the terminal.", "type": "string" }, "enableLockScreen": { "description": "Whether the terminal auto-lock screen is enabled.", "type": "boolean" }, "printerConfig": { "description": "Printer configuration mode set for the terminal.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "preferredRestartTime": "02:00", "preferredNetwork": "WIFI", "wifiSsid": "surfboard", "wifiPassword": "surfboa", "language": "da", "autoSleep": 400, "alwaysShowMinorUnits": 1, "showStatusBar": false, "showReceipt": true, "chipReadDelay": 500, "openPosOnReboot": "enabled", "enableRefundLock": true, "screenTimeout": 3000000, "preferredGsmOperator": 2, "offlineMode": "enabled" }, "message": "Terminal config queried successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/terminals/config": { "get": { "operationId": "fetchMerchantTerminalConfig", "summary": "Fetch Merchant Terminal Config", "description": "Use this API to fetch all currently active terminal configurations for the merchant.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "wifiSsid": { "description": "Name of the WiFi network.", "type": "string" }, "wifiPassword": { "description": "Password for the WiFi network.", "type": "string" }, "autoSleep": { "description": "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.", "type": "number" }, "preferredRestartTime": { "description": "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.", "type": "string" }, "preferredNetwork": { "description": "Preferred network for the terminal. It can be either 'WIFI' or 'GSM'.\n\nValues:\n- `WIFI`: Sets the preferred network of the terminal as WiFi.\n- `GSM`: Sets the preferred network of the terminal as GSM or mobile network.", "type": "string", "enum": [ "WIFI", "GSM" ] }, "alwaysShowMinorUnits": { "description": "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.", "type": "number" }, "language": { "description": "Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'.", "type": "string" }, "showStatusBar": { "description": "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.", "type": "boolean" }, "chipReadDelay": { "description": "Time delay in milliseconds before the card is read.", "type": "number" }, "showReceipt": { "description": "Set this to determine how receipts are showcased on the terminal.", "type": "boolean" }, "preferredGsmOperator": { "description": "The preferred GSM operator identified by a numeric code.", "type": "number" }, "openPosOnReboot": { "description": "Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'.", "type": "string" }, "enableRefundLock": { "description": "Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals.", "type": "boolean" }, "screenTimeout": { "description": "The duration (in milliseconds) before the screen times out due to inactivity.", "type": "number" }, "autoSleepInterval": { "description": "The interval (in milliseconds) before the device automatically goes to sleep.", "type": "number" }, "receiptScreenTimeout": { "description": "Timeout of the receipt screen on hardware terminals.", "type": "number" }, "offlineMode": { "description": "Current offline-payments toggle for the terminal.\n\nValues:\n- `enabled`: Offline card payments are enabled.\n- `disabled`: Offline card payments are disabled.", "type": "string", "enum": [ "enabled", "disabled" ] }, "displayContrast": { "description": "Display contrast level of the terminal screen.", "type": "number" }, "idleScreenImageUrl": { "description": "URL of the image shown on the terminal idle screen.", "type": "string" }, "lockScreenPin": { "description": "PIN required to unlock the terminal lock screen.", "type": "string" }, "refundScreenPin": { "description": "PIN required to authorize refunds on the terminal.", "type": "string" }, "enableLockScreen": { "description": "Whether the terminal auto-lock screen is enabled.", "type": "boolean" }, "printerConfig": { "description": "Printer configuration mode set for the terminal.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "preferredRestartTime": "02:00", "preferredNetwork": "WIFI", "wifiSsid": "surfboard", "wifiPassword": "surfboa", "language": "da", "autoSleep": 400, "alwaysShowMinorUnits": 1, "showStatusBar": false, "showReceipt": true, "chipReadDelay": 500, "openPosOnReboot": "enabled", "enableRefundLock": true, "screenTimeout": 3000000, "preferredGsmOperator": 2, "offlineMode": "enabled" }, "message": "Merchant Terminal config queried successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/terminals/config": { "get": { "operationId": "fetchStoreTerminalConfig", "summary": "Fetch Store Terminal Config", "description": "Use this API to fetch all currently active configurations for the store.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "wifiSsid": { "description": "Name of the WiFi network.", "type": "string" }, "wifiPassword": { "description": "Password for the WiFi network.", "type": "string" }, "autoSleep": { "description": "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.", "type": "number" }, "preferredRestartTime": { "description": "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.", "type": "string" }, "preferredNetwork": { "description": "Preferred network for the terminal. It can be either 'WIFI' or 'GSM'.\n\nValues:\n- `WIFI`: Sets the preferred network of the terminal as WiFi.\n- `GSM`: Sets the preferred network of the terminal as GSM or mobile network.", "type": "string", "enum": [ "WIFI", "GSM" ] }, "alwaysShowMinorUnits": { "description": "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.", "type": "number" }, "language": { "description": "Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'.", "type": "string" }, "showStatusBar": { "description": "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.", "type": "boolean" }, "chipReadDelay": { "description": "Time delay in milliseconds before the card is read.", "type": "number" }, "showReceipt": { "description": "Set this to determine how receipts are showcased on the terminal.", "type": "boolean" }, "preferredGsmOperator": { "description": "The preferred GSM operator identified by a numeric code.", "type": "number" }, "openPosOnReboot": { "description": "Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'.", "type": "string" }, "enableRefundLock": { "description": "Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals.", "type": "boolean" }, "screenTimeout": { "description": "The duration (in milliseconds) before the screen times out due to inactivity.", "type": "number" }, "autoSleepInterval": { "description": "The interval (in milliseconds) before the device automatically goes to sleep.", "type": "number" }, "receiptScreenTimeout": { "description": "Timeout of the receipt screen on hardware terminals.", "type": "number" }, "offlineMode": { "description": "Current offline-payments toggle for the terminal.\n\nValues:\n- `enabled`: Offline card payments are enabled.\n- `disabled`: Offline card payments are disabled.", "type": "string", "enum": [ "enabled", "disabled" ] }, "displayContrast": { "description": "Display contrast level of the terminal screen.", "type": "number" }, "idleScreenImageUrl": { "description": "URL of the image shown on the terminal idle screen.", "type": "string" }, "lockScreenPin": { "description": "PIN required to unlock the terminal lock screen.", "type": "string" }, "refundScreenPin": { "description": "PIN required to authorize refunds on the terminal.", "type": "string" }, "enableLockScreen": { "description": "Whether the terminal auto-lock screen is enabled.", "type": "boolean" }, "printerConfig": { "description": "Printer configuration mode set for the terminal.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "preferredRestartTime": "02:00", "preferredNetwork": "WIFI", "wifiSsid": "surfboard", "wifiPassword": "surfboa", "language": "da", "autoSleep": 400, "alwaysShowMinorUnits": 1, "showStatusBar": false, "showReceipt": true, "chipReadDelay": 500, "openPosOnReboot": "enabled", "enableRefundLock": true, "screenTimeout": 3000000, "preferredGsmOperator": 2, "offlineMode": "enabled" }, "message": "Store Terminal config queried successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/terminals/{terminalId}/apns": { "get": { "operationId": "fetchApnList", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "apns": { "description": "An array of strings depicting all APNs of the terminal.", "type": "array", "items": {} } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "apns": [ "WIFI1", "WIFI2" ] } } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/terminals/interapp": { "get": { "operationId": "getInterappCode", "summary": "Get Interapp Code", "description": "Use this API to generate the registration code used for interapp registration.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "registrationCode": { "description": "Returns the registration code for interapp. This code is valid for 120 seconds.", "type": "string" } }, "required": [ "registrationCode" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "registrationCode": "v_Z37lV0JatqBvou" }, "message": "Inter app code generated Successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/terminals/interapp/{registrationCode}": { "get": { "operationId": "getInterappDetails", "summary": "Get Interapp Details", "description": "Fetches the current status of the interapp registration for a terminal.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "registrationCode", "in": "path", "required": true, "description": "Identifier for the registration code this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "Interapp registration details returned for the terminal.", "type": "object", "properties": { "registrationStatus": { "description": "Denotes the registration status of the terminal.\n\nValues:\n- `REGISTERED`: Interapp registration successful.\n- `NOT_REGISTERED`: Terminal not registered yet.", "type": "string", "enum": [ "REGISTERED", "NOT_REGISTERED" ] }, "terminalId": { "description": "Terminal ID of the registered terminal.", "type": "string" }, "terminalName": { "description": "The name assigned to the registered terminal.", "type": "string" }, "softwareMode": { "description": "The software mode the terminal is running in.", "type": "string" } }, "required": [ "registrationStatus", "terminalId" ], "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "registrationStatus": "REGISTERED", "terminalId": "81f878852b3a280904", "terminalName": "Front Desk Terminal", "softwareMode": "online" }, "message": "Terminal details fetched successfully." } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/terminals/{terminalId}/entry-code": { "get": { "operationId": "getEntryCode", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "registrationCodeId": { "description": "Identifier of the registration code associated with the entry code.", "type": "string" }, "validUntil": { "description": "Lifetime of the entry code in seconds, returned as a string.", "type": "string" }, "entryCode": { "description": "The generated entry code for the terminal.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "registrationCodeId": "81f878852b3a280904", "validUntil": "120", "entryCode": "905788" }, "message": "Fetched entry code" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/stores/{storeId}/terminals/{terminalId}/change": { "post": { "operationId": "changeTerminalStore", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Store ID of the destination store the terminal is moved to.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the store change.", "type": "string" }, "message": { "description": "A message that describes the status of the store change.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Store successfully changed for the terminal" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/terminal-configs": { "get": { "operationId": "queryPartnerTerminalConfigs", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "query", "required": false, "description": "Selects the TERMINAL config scope. This has the highest priority.", "schema": { "description": "Selects the TERMINAL config scope. This has the highest priority.", "type": "string" } }, { "name": "storeId", "in": "query", "required": false, "description": "Selects the STORE config scope when terminalId is absent.", "schema": { "description": "Selects the STORE config scope when terminalId is absent.", "type": "string" } }, { "name": "merchantId", "in": "query", "required": false, "description": "Selects the MERCHANT config scope when terminalId and storeId are absent. When none of these are provided, the scope defaults to PARTNER.", "schema": { "description": "Selects the MERCHANT config scope when terminalId and storeId are absent. When none of these are provided, the scope defaults to PARTNER.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "allowedExternalSoftwareVersions": { "description": "List of allowed external software versions. Defaults to an empty array when none are configured.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "Type of the external software.", "type": "string" }, "version": { "description": "Version of the external software.", "type": "string" }, "softwareId": { "description": "Identifier of the external software.", "type": "string" }, "minVersion": { "description": "Minimum supported version of the external software.", "type": "string" }, "isPos": { "description": "Indicates whether the software is a POS application.", "type": "boolean" }, "terminalType": { "description": "Terminal type the software applies to.", "type": "string" }, "deviceType": { "description": "Device type the software applies to.", "type": "string" }, "overrideLevel": { "description": "Scope at which the configuration is overridden.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "allowedExternalSoftwareVersions": [ { "type": "pos", "version": "1.2.0", "softwareId": "81fa6b2d8d5dc8040e", "minVersion": "1.0.0", "isPos": true, "terminalType": "surftouch", "deviceType": "android", "overrideLevel": "PARTNER" } ] }, "message": "Terminal configs fetched successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/terminals/config": { "get": { "operationId": "fetchPartnerTerminalConfig", "summary": "Fetch Partner Terminal Config", "description": "Use this API to fetch all currently active terminal configurations for the partner.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "preferredRestartTime": { "description": "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.", "type": "string" }, "idleScreenImageUrl": { "description": "URL of the image displayed on the idle screen of the terminal.", "type": "string" }, "preferredNetwork": { "description": "Preferred network for the terminal. It can be either 'WIFI' or 'GSM'.", "type": "string" }, "wifiSsid": { "description": "Name of the WiFi network.", "type": "string" }, "wifiPassword": { "description": "Password for the WiFi network.", "type": "string" }, "language": { "description": "Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'.", "type": "string" }, "autoSleep": { "description": "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.", "type": "number" }, "alwaysShowMinorUnits": { "description": "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.", "type": "number" }, "showStatusBar": { "description": "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.", "type": "boolean" }, "showReceipt": { "description": "Set this to determine how receipts are showcased on the terminal.", "type": "boolean" }, "chipReadDelay": { "description": "Time delay in milliseconds before the card is read.", "type": "number" }, "openPosOnReboot": { "description": "Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'.", "type": "string" }, "lockScreenPin": { "description": "PIN code used to unlock the terminal's lock screen.", "type": "string" }, "refundScreenPin": { "description": "PIN code used to authorize refunds on the terminal.", "type": "string" }, "screenTimeout": { "description": "The duration (in milliseconds) before the screen times out due to inactivity.", "type": "number" }, "autoSleepInterval": { "description": "The interval (in milliseconds) before the device automatically goes to sleep.", "type": "number" }, "preferredGsmOperator": { "description": "The preferred GSM operator identified by a numeric code.", "type": "number" }, "enableRefundLock": { "description": "Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals.", "type": "boolean" }, "enableLockScreen": { "description": "Determines whether the lock screen is enabled on the terminal.", "type": "boolean" }, "printerConfig": { "description": "Printer configuration mode set for the terminal.", "type": "string" }, "receiptScreenTimeout": { "description": "Timeout of the receipt screen on hardware terminals.", "type": "number" }, "offlineMode": { "description": "Current offline-payments toggle for the terminal.\n\nValues:\n- `enabled`: Offline card payments are enabled.\n- `disabled`: Offline card payments are disabled.", "type": "string", "enum": [ "enabled", "disabled" ] }, "displayContrast": { "description": "Display contrast level of the terminal screen.", "type": "number" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "preferredRestartTime": "02:00", "preferredNetwork": "WIFI", "wifiSsid": "surfboard", "wifiPassword": "surfboa", "language": "da", "autoSleep": 400, "alwaysShowMinorUnits": 1, "showStatusBar": false, "showReceipt": true, "chipReadDelay": 500, "openPosOnReboot": "enabled", "screenTimeout": 3000000, "preferredGsmOperator": 2, "enableRefundLock": true }, "message": "Partner Terminal config queried successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/terminals/{terminalId}": { "get": { "operationId": "queryTerminalsUnderPartner", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "array", "items": { "type": "object", "properties": { "terminalId": { "description": "Terminal ID of the terminal.", "type": "string" }, "terminalType": { "description": "Describes the type of the terminal, for example 'surfpad', 'surftouch', 'surfprint', 'checkoutPro', 'checkoutX' or 'iFrame'.", "type": "string" }, "softwareVersion": { "description": "Software version of the terminal.", "type": "string" }, "osType": { "description": "Describes the type of Operating System (OS) running on the terminal.", "type": "string" }, "osVersion": { "description": "Operating System (OS) version of the terminal.", "type": "string" }, "deviceVendor": { "description": "Device vendor of the terminal.", "type": "string" }, "deviceModel": { "description": "Device model of the terminal.", "type": "string" }, "serialNo": { "description": "Serial number of the terminal.", "type": "string" }, "lastAliveAt": { "description": "Timestamp of the last time the terminal was seen alive.", "type": "string" }, "isCharging": { "description": "Whether the terminal is currently charging.", "type": "boolean" }, "batteryPercentage": { "description": "Current battery charge level of the terminal, as a percentage.", "type": "number" }, "wifiStrength": { "description": "Wi-Fi signal strength of the terminal.", "type": "number" }, "gsmStrength": { "description": "GSM signal strength of the terminal.", "type": "number" }, "powerSource": { "description": "Power source the terminal is currently using.", "type": "string" }, "deviceNetwork": { "description": "Network the terminal device is connected to.", "type": "string" }, "turnOnTime": { "description": "Timestamp of when the terminal was last turned on.", "type": "string" }, "softwareMode": { "description": "The software mode the terminal is running in.", "type": "string" }, "terminalPublicKey": { "description": "The public key of the terminal.", "type": "string" }, "signalStrength": { "description": "Overall signal strength reported by the terminal.", "type": "number" }, "sdkUrl": { "description": "The SDK server URL, present for self-hosted SDK terminals.", "type": "string" }, "storeId": { "description": "The Store ID of the store under which the terminal is registered.", "type": "string" }, "linkedTerminalId": { "description": "The Terminal ID of another terminal to which the current terminal is linked.", "type": "string" }, "terminalStatus": { "description": "Status of the terminal, it can be in one of these states: REGISTERED | ACTIVE | IN_ACTIVE | DE_REGISTERED.", "type": "string" }, "startDate": { "description": "Timestamp at which the terminal was created.", "type": "string" }, "terminalPaymentMethods": { "description": "Payment methods supported by the terminal.", "type": "string" }, "terminalName": { "description": "Name of the terminal used as a reference for users.", "type": "string" }, "merchantId": { "description": "The Merchant ID of the merchant under which the terminal is registered.", "type": "string" }, "terminalCurrencyCode": { "description": "Currency code associated with the terminal.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "terminalId": "81f878852b3a280904", "terminalType": "surfpad", "serialNo": "2922000007", "storeId": "81497439a52270000f", "terminalStatus": "ACTIVE", "terminalName": "My Terminal", "merchantId": "81fa6b2d8d5dc8040e", "terminalCurrencyCode": "NA" } ], "message": "Fetched terminals successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/terminals": { "patch": { "operationId": "updatePartnerTerminalConfig", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "preferredRestartTime": { "description": "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.", "type": "string" }, "idleScreenImageUrl": { "description": "URL of the image displayed on the idle screen of the terminal.", "type": "string" }, "autoSleep": { "description": "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.", "type": "number" }, "showStatusBar": { "description": "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.", "type": "boolean" }, "screenTimeout": { "description": "The duration (in milliseconds) before the screen times out due to inactivity.", "type": "number" }, "autoSleepInterval": { "description": "The interval (in milliseconds) before the device automatically goes to sleep.", "type": "number" }, "printerConfig": { "description": "Printer configuration mode for the terminal.", "type": "string" }, "receiptScreenTimeout": { "description": "Timeout of the receipt screen on hardware terminals.", "type": "number" }, "showReceipt": { "description": "Set this to determine how receipts are showcased on the terminal.", "type": "boolean" }, "language": { "description": "Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'.", "type": "string" }, "alwaysShowMinorUnits": { "description": "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.", "type": "number" }, "openPosOnReboot": { "description": "Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'.", "type": "string" }, "chipReadDelay": { "description": "Time delay in milliseconds before the card is read.", "type": "number" }, "lockScreenPin": { "description": "PIN code used to unlock the terminal's lock screen.", "type": "string" }, "refundScreenPin": { "description": "PIN code used to authorize refunds on the terminal.", "type": "string" }, "enableRefundLock": { "description": "Determines whether refunds require the refund PIN.", "type": "boolean" }, "enableLockScreen": { "description": "Determines whether the lock screen is enabled on the terminal.", "type": "boolean" }, "wifiSsid": { "description": "Name of the WiFi network.", "type": "string" }, "wifiPassword": { "description": "Password for the WiFi network.", "type": "string" }, "preferredGsmOperator": { "description": "The preferred GSM operator identified by a numeric code.", "type": "number" }, "preferredNetwork": { "description": "Preferred network for the terminal. It can be either 'WIFI' or 'GSM'.", "type": "string" }, "offlineMode": { "description": "Controls whether the terminal keeps accepting card payments while offline (stored and forwarded once connectivity returns). Applies to the sb_terminal_k checkout app.\n\nValues:\n- `enabled`: The terminal accepts card payments while offline.\n- `disabled`: The terminal requires connectivity to accept payments.", "type": "string", "enum": [ "enabled", "disabled" ] } } }, "example": { "wifiSsid": "wifiname", "wifiPassword": "wifipassword", "autoSleep": 3000, "preferredNetwork": "WIFI", "preferredRestartTime": "03:00", "alwaysShowMinorUnits": 1, "language": "en", "showStatusBar": true, "chipReadDelay": 500, "showReceipt": true } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "PARTNER config updated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/terminals/port": { "put": { "operationId": "portPartnerTerminals", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "terminalDetails": { "description": "List of terminals to port to the target merchant.", "type": "array", "items": { "type": "object", "properties": { "serialNo": { "description": "Serial number of the terminal to port.", "type": "string" }, "storeId": { "description": "Store ID the terminal should be assigned to under the target merchant.", "type": "string" } }, "required": [ "serialNo", "storeId" ] } }, "targetMerchantId": { "description": "Merchant ID of the merchant the terminals are ported to.", "type": "string" } }, "required": [ "terminalDetails", "targetMerchantId" ] }, "example": { "targetMerchantId": "81fa6b2d8d5dc8040e", "terminalDetails": [ { "serialNo": "2922000007", "storeId": "st_GZVDbwmS86_G9pwc669U2" } ] } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data. Each entry reports the per-terminal port outcome.", "type": "array", "items": { "type": "object", "properties": { "status": { "description": "Port status of the terminal.", "type": "string" }, "serialNo": { "description": "Serial number of the ported terminal.", "type": "string" }, "terminalId": { "description": "Terminal ID of the resulting terminal.", "type": "string" }, "registrationInfo": { "description": "Registration information of the ported terminal.", "type": "object", "additionalProperties": true }, "errorMessage": { "description": "Error message describing why the terminal failed to port, when applicable.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "status": "SUCCESS", "serialNo": "2922000007", "terminalId": "81f878852b3a280904", "registrationInfo": {}, "errorMessage": "" } ], "message": "Terminals of partner ported successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/partners/{partnerId}/merchants/{merchantId}/stores/{storeId}/terminals/{terminalId}/config": { "put": { "operationId": "publishTerminalImageAndConfig", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "description": "Identifier for the partner this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "offlineMode": { "description": "Controls whether the terminal keeps accepting card payments while offline (stored and forwarded once connectivity returns). Applies to the sb_terminal_k checkout app.\n\nValues:\n- `enabled`: The terminal accepts card payments while offline.\n- `disabled`: The terminal requires connectivity to accept payments.", "type": "string", "enum": [ "enabled", "disabled" ] } } } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "preferredRestartTime": { "description": "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.", "type": "string" }, "idleScreenImageUrl": { "description": "URL of the image displayed on the idle screen of the terminal.", "type": "string" }, "preferredNetwork": { "description": "Preferred network for the terminal. It can be either 'WIFI' or 'GSM'.", "type": "string" }, "wifiSsid": { "description": "Name of the WiFi network.", "type": "string" }, "wifiPassword": { "description": "Password for the WiFi network.", "type": "string" }, "language": { "description": "Two-letter ISO language code, in lowercase, representing the language to be displayed in the terminal. Can be 'en', 'fi', 'da', or 'se'.", "type": "string" }, "autoSleep": { "description": "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.", "type": "number" }, "alwaysShowMinorUnits": { "description": "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.", "type": "number" }, "showStatusBar": { "description": "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.", "type": "boolean" }, "showReceipt": { "description": "Set this to determine how receipts are showcased on the terminal.", "type": "boolean" }, "chipReadDelay": { "description": "Time delay in milliseconds before the card is read.", "type": "number" }, "openPosOnReboot": { "description": "Indicates whether the POS system should open automatically after reboot. Possible values are 'enabled' or 'disabled'.", "type": "string" }, "lockScreenPin": { "description": "PIN code used to unlock the terminal's lock screen.", "type": "string" }, "refundScreenPin": { "description": "PIN code used to authorize refunds on the terminal.", "type": "string" }, "screenTimeout": { "description": "The duration (in milliseconds) before the screen times out due to inactivity.", "type": "number" }, "autoSleepInterval": { "description": "The interval (in milliseconds) before the device automatically goes to sleep.", "type": "number" }, "preferredGsmOperator": { "description": "The preferred GSM operator identified by a numeric code.", "type": "number" }, "enableRefundLock": { "description": "Determines if the refund lock screen feature is enabled on the device. This is only available for android terminals.", "type": "boolean" }, "enableLockScreen": { "description": "Determines whether the lock screen is enabled on the terminal.", "type": "boolean" }, "printerConfig": { "description": "Printer configuration mode set for the terminal.", "type": "string" }, "receiptScreenTimeout": { "description": "Timeout of the receipt screen on hardware terminals.", "type": "number" }, "offlineMode": { "description": "Current offline-payments toggle for the terminal.\n\nValues:\n- `enabled`: Offline card payments are enabled.\n- `disabled`: Offline card payments are disabled.", "type": "string", "enum": [ "enabled", "disabled" ] }, "displayContrast": { "description": "Display contrast level of the terminal screen.", "type": "number" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "preferredRestartTime": "02:00", "preferredNetwork": "WIFI", "wifiSsid": "surfboard", "wifiPassword": "surfboa", "language": "da", "autoSleep": 400, "alwaysShowMinorUnits": 1, "showStatusBar": false, "showReceipt": true, "chipReadDelay": 500, "openPosOnReboot": "enabled", "screenTimeout": 3000000, "preferredGsmOperator": 2, "enableRefundLock": true }, "message": "Terminal config published successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ], "x-recently-added": true } }, "/terminals/{terminalId}/reboot": { "post": { "operationId": "rebootTerminal", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "message": { "description": "A message that describes the status of the reboot command.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Reboot command published successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/terminals/{terminalId}/metrics": { "get": { "operationId": "fetchTerminalMetrics", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Terminals API" ], "parameters": [ { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "event", "in": "query", "required": false, "description": "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.", "schema": { "description": "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.", "type": "string" } }, { "name": "queryDates", "in": "query", "required": false, "description": "One or more dates to scope the metrics query. A single value is accepted and wrapped into an array.", "schema": { "description": "One or more dates to scope the metrics query. A single value is accepted and wrapped into an array.", "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request.", "type": "string" }, "data": { "description": "List of terminal metric series, one per requested event.", "type": "array", "items": { "type": "object", "properties": { "terminalId": { "description": "Terminal ID of the terminal the metric belongs to.", "type": "string" }, "event": { "description": "Metric event type of the series.", "type": "string" }, "data": { "description": "Metric data of the series.", "type": "object", "properties": { "value": { "description": "Time-ordered list of metric samples.", "type": "array", "items": { "type": "object", "properties": { "time": { "description": "Timestamp of the sample.", "type": "string" }, "value": { "description": "Value of the sample, which can be a string or a boolean.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } }, "message": { "description": "Status message of the request.", "type": "string" } }, "required": [ "status" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "terminalId": "81f878852b3a280904", "event": "BATTERY_STATUS", "data": { "value": [ { "time": "2024-02-21T08:48:26.000Z", "value": "100" } ] } } ], "message": "Fetched terminal metrics successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ], "x-recently-added": true } }, "/merchants/{merchantId}/tips": { "patch": { "operationId": "setMerchantTipsConfig", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Tips APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tipConfig": { "description": "Specifies how tips are managed during the payment. The possible values are the following:\n\nValues:\n- `ENABLED`: Allows the terminal to display preset tip options while accepting payments.\n- `DISABLED`: Hides the tip option so the terminal shows no tip prompts during payment.\n- `OTHER_AMOUNT`: Lets the customer enter a free custom tip amount on the tips screen. Equivalent to sending tipConfig: ENABLED with freeAmountEnabled: true. When the configuration is read back it is reported as tipConfig: ENABLED with freeAmountEnabled: true, not as OTHER_AMOUNT.", "type": "string", "enum": [ "ENABLED", "DISABLED", "OTHER_AMOUNT" ] }, "tipLevel1": { "description": "The first preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "tipLevel2": { "description": "The second preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "tipLevel3": { "description": "The third preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "defaultCustomAmount": { "description": "The value pre-filled on the screen for the custom tip amount.", "type": "number" }, "displayCalculatedAmount": { "description": "Specifies whether the calculated tip amount is shown on screen.\n\nValues:\n- `ENABLED`: Shows the calculated tip amount.\n- `DISABLED`: Hides the calculated tip amount.", "type": "string", "enum": [ "ENABLED", "DISABLED" ] }, "tipDisplayFormat": { "description": "The format in which the preset tip levels are displayed.\n\nValues:\n- `PERCENTAGE`: Displays preset tip levels as percentages.\n- `AMOUNT`: Displays preset tip levels as fixed amounts.", "type": "string", "enum": [ "PERCENTAGE", "AMOUNT" ] }, "maxCustomTipAmount": { "description": "The maximum tip amount a customer can enter for a custom tip.", "type": "number" }, "freeAmountEnabled": { "description": "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).", "type": "boolean" } } }, "example": { "tipConfig": "ENABLED", "tipLevel1": 10, "tipLevel2": 20, "tipLevel3": 30, "defaultCustomAmount": 25, "displayCalculatedAmount": "ENABLED", "tipDisplayFormat": "PERCENTAGE", "maxCustomTipAmount": 100, "freeAmountEnabled": true } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "MERCHANT config updated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchMerchantTipsConfig", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Tips APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "tipConfig": { "description": "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).\n\nValues:\n- `ENABLED`: Allows the terminal to display preset tip options while accepting payments.\n- `DISABLED`: Hides the tip option so the terminal shows no tip prompts during payment.", "type": "string", "enum": [ "ENABLED", "DISABLED" ] }, "tipLevel1": { "description": "The first preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "tipLevel2": { "description": "The second preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "tipLevel3": { "description": "The third preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "defaultCustomAmount": { "description": "The value pre-filled on the screen for the custom tip amount.", "type": "number" }, "displayCalculatedAmount": { "description": "Specifies whether the calculated tip amount is shown on screen.\n\nValues:\n- `ENABLED`: Shows the calculated tip amount.\n- `DISABLED`: Hides the calculated tip amount.", "type": "string", "enum": [ "ENABLED", "DISABLED" ] }, "tipDisplayFormat": { "description": "The format in which the preset tip levels are displayed.\n\nValues:\n- `PERCENTAGE`: Displays preset tip levels as percentages.\n- `AMOUNT`: Displays preset tip levels as fixed amounts.", "type": "string", "enum": [ "PERCENTAGE", "AMOUNT" ] }, "freeAmountEnabled": { "description": "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.", "type": "boolean" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "tipConfig": "ENABLED", "tipLevel1": 10, "tipLevel2": 20, "tipLevel3": 30, "defaultCustomAmount": 25, "displayCalculatedAmount": "ENABLED", "tipDisplayFormat": "PERCENTAGE", "freeAmountEnabled": true }, "message": "merchant config queried successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/tips": { "patch": { "operationId": "setStoreTipsConfig", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Tips APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tipConfig": { "description": "Specifies how tips are managed during the payment. The possible values are the following:\n\nValues:\n- `ENABLED`: Allows the terminal to display preset tip options while accepting payments.\n- `DISABLED`: Hides the tip option so the terminal shows no tip prompts during payment.\n- `OTHER_AMOUNT`: Lets the customer enter a free custom tip amount on the tips screen. Equivalent to sending tipConfig: ENABLED with freeAmountEnabled: true. When the configuration is read back it is reported as tipConfig: ENABLED with freeAmountEnabled: true, not as OTHER_AMOUNT.", "type": "string", "enum": [ "ENABLED", "DISABLED", "OTHER_AMOUNT" ] }, "tipLevel1": { "description": "The first preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "tipLevel2": { "description": "The second preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "tipLevel3": { "description": "The third preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "defaultCustomAmount": { "description": "The value pre-filled on the screen for the custom tip amount.", "type": "number" }, "displayCalculatedAmount": { "description": "Specifies whether the calculated tip amount is shown on screen.\n\nValues:\n- `ENABLED`: Shows the calculated tip amount.\n- `DISABLED`: Hides the calculated tip amount.", "type": "string", "enum": [ "ENABLED", "DISABLED" ] }, "tipDisplayFormat": { "description": "The format in which the preset tip levels are displayed.\n\nValues:\n- `PERCENTAGE`: Displays preset tip levels as percentages.\n- `AMOUNT`: Displays preset tip levels as fixed amounts.", "type": "string", "enum": [ "PERCENTAGE", "AMOUNT" ] }, "maxCustomTipAmount": { "description": "The maximum tip amount a customer can enter for a custom tip.", "type": "number" }, "freeAmountEnabled": { "description": "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).", "type": "boolean" } } }, "example": { "tipConfig": "ENABLED", "tipLevel1": 10, "tipLevel2": 20, "tipLevel3": 30, "defaultCustomAmount": 25, "displayCalculatedAmount": "ENABLED", "tipDisplayFormat": "PERCENTAGE", "maxCustomTipAmount": 100, "freeAmountEnabled": true } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "STORE config updated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchStoreTipsConfig", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Tips APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "tipConfig": { "description": "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).\n\nValues:\n- `ENABLED`: Allows the terminal to display preset tip options while accepting payments.\n- `DISABLED`: Hides the tip option so the terminal shows no tip prompts during payment.", "type": "string", "enum": [ "ENABLED", "DISABLED" ] }, "tipLevel1": { "description": "The first preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "tipLevel2": { "description": "The second preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "tipLevel3": { "description": "The third preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "defaultCustomAmount": { "description": "The value pre-filled on the screen for the custom tip amount.", "type": "number" }, "displayCalculatedAmount": { "description": "Specifies whether the calculated tip amount is shown on screen.\n\nValues:\n- `ENABLED`: Shows the calculated tip amount.\n- `DISABLED`: Hides the calculated tip amount.", "type": "string", "enum": [ "ENABLED", "DISABLED" ] }, "tipDisplayFormat": { "description": "The format in which the preset tip levels are displayed.\n\nValues:\n- `PERCENTAGE`: Displays preset tip levels as percentages.\n- `AMOUNT`: Displays preset tip levels as fixed amounts.", "type": "string", "enum": [ "PERCENTAGE", "AMOUNT" ] }, "freeAmountEnabled": { "description": "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.", "type": "boolean" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "tipConfig": "ENABLED", "tipLevel1": 10, "tipLevel2": 20, "tipLevel3": 30, "defaultCustomAmount": 25, "displayCalculatedAmount": "ENABLED", "tipDisplayFormat": "PERCENTAGE", "freeAmountEnabled": true }, "message": "store config queried successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/merchants/{merchantId}/stores/{storeId}/terminals/{terminalId}/tips": { "patch": { "operationId": "setTerminalTipsConfig", "summary": "Set Terminal Tips Config", "description": "Sets the tips configuration for an individual terminal. Use this API to configure tips for a particular terminal.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Tips APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tipConfig": { "description": "Specifies how tips are managed during the payment. The possible values are the following:\n\nValues:\n- `ENABLED`: Allows the terminal to display preset tip options while accepting payments.\n- `DISABLED`: Hides the tip option so the terminal shows no tip prompts during payment.\n- `OTHER_AMOUNT`: Lets the customer enter a free custom tip amount on the tips screen. Equivalent to sending tipConfig: ENABLED with freeAmountEnabled: true. When the configuration is read back it is reported as tipConfig: ENABLED with freeAmountEnabled: true, not as OTHER_AMOUNT.", "type": "string", "enum": [ "ENABLED", "DISABLED", "OTHER_AMOUNT" ] }, "tipLevel1": { "description": "The first preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "tipLevel2": { "description": "The second preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "tipLevel3": { "description": "The third preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "defaultCustomAmount": { "description": "The value pre-filled on the screen for the custom tip amount.", "type": "number" }, "displayCalculatedAmount": { "description": "Specifies whether the calculated tip amount is shown on screen.\n\nValues:\n- `ENABLED`: Shows the calculated tip amount.\n- `DISABLED`: Hides the calculated tip amount.", "type": "string", "enum": [ "ENABLED", "DISABLED" ] }, "tipDisplayFormat": { "description": "The format in which the preset tip levels are displayed.\n\nValues:\n- `PERCENTAGE`: Displays preset tip levels as percentages.\n- `AMOUNT`: Displays preset tip levels as fixed amounts.", "type": "string", "enum": [ "PERCENTAGE", "AMOUNT" ] }, "maxCustomTipAmount": { "description": "The maximum tip amount a customer can enter for a custom tip.", "type": "number" }, "freeAmountEnabled": { "description": "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).", "type": "boolean" }, "serialNo": { "description": "Hardware serial number of the target terminal.", "type": "string" } } }, "example": { "tipConfig": "ENABLED", "tipLevel1": 10, "tipLevel2": 20, "tipLevel3": 30, "defaultCustomAmount": 25, "displayCalculatedAmount": "ENABLED", "tipDisplayFormat": "PERCENTAGE", "maxCustomTipAmount": 100, "freeAmountEnabled": true, "serialNo": "1850123456" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "TERMINAL config updated successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "get": { "operationId": "fetchTerminalTipsConfig", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Tips APIs" ], "parameters": [ { "name": "merchantId", "in": "path", "required": true, "description": "Identifier for the merchant this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "storeId", "in": "path", "required": true, "description": "Identifier for the store this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } }, { "name": "terminalId", "in": "path", "required": true, "description": "Identifier for the terminal this call applies to. Opaque hex string; store and return it unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, indicated as either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Response data.", "type": "object", "properties": { "tipConfig": { "description": "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).\n\nValues:\n- `ENABLED`: Allows the terminal to display preset tip options while accepting payments.\n- `DISABLED`: Hides the tip option so the terminal shows no tip prompts during payment.", "type": "string", "enum": [ "ENABLED", "DISABLED" ] }, "tipLevel1": { "description": "The first preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "tipLevel2": { "description": "The second preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "tipLevel3": { "description": "The third preset tip option shown to the customer, interpreted as a percentage or a fixed amount according to tipDisplayFormat.", "type": "number" }, "defaultCustomAmount": { "description": "The value pre-filled on the screen for the custom tip amount.", "type": "number" }, "displayCalculatedAmount": { "description": "Specifies whether the calculated tip amount is shown on screen.\n\nValues:\n- `ENABLED`: Shows the calculated tip amount.\n- `DISABLED`: Hides the calculated tip amount.", "type": "string", "enum": [ "ENABLED", "DISABLED" ] }, "tipDisplayFormat": { "description": "The format in which the preset tip levels are displayed.\n\nValues:\n- `PERCENTAGE`: Displays preset tip levels as percentages.\n- `AMOUNT`: Displays preset tip levels as fixed amounts.", "type": "string", "enum": [ "PERCENTAGE", "AMOUNT" ] }, "freeAmountEnabled": { "description": "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.", "type": "boolean" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "required": [ "status", "data", "message" ], "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "tipConfig": "ENABLED", "tipLevel1": 10, "tipLevel2": 20, "tipLevel3": 30, "defaultCustomAmount": 25, "displayCalculatedAmount": "ENABLED", "tipDisplayFormat": "PERCENTAGE", "freeAmountEnabled": true }, "message": "terminal config queried successfully" } } } }, "401": { "description": "Credentials missing, wrong, or belonging to a different environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/transactions": { "get": { "operationId": "listTransactions", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Transactions API" ], "parameters": [ { "name": "startDate", "in": "query", "required": false, "description": "Start of the date range to fetch transactions for (ISO 8601, e.g. 2026-06-01). When omitted, results are not date-filtered.", "schema": { "description": "Start of the date range to fetch transactions for (ISO 8601, e.g. 2026-06-01). When omitted, results are not date-filtered.", "type": "string" } }, { "name": "endDate", "in": "query", "required": false, "description": "End of the date range. If a startDate is supplied without an endDate, a 24-hour window from startDate is used.", "schema": { "description": "End of the date range. If a startDate is supplied without an endDate, a 24-hour window from startDate is used.", "type": "string" } }, { "name": "storeId", "in": "query", "required": false, "description": "Return only transactions that took place at this store.", "schema": { "description": "Return only transactions that took place at this store.", "type": "string" } }, { "name": "terminalId", "in": "query", "required": false, "description": "Return only transactions processed by this terminal (checkout).", "schema": { "description": "Return only transactions processed by this terminal (checkout).", "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The transactions on the current page.", "type": "array", "items": { "type": "object", "properties": { "transactionId": { "description": "Unique identifier of the transaction.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant the transaction belongs to.", "type": "string" }, "storeId": { "description": "Identifier of the store where the transaction took place.", "type": "string" }, "terminalId": { "description": "Identifier of the terminal (checkout) that processed the transaction.", "type": "string" }, "orderId": { "description": "Identifier of the order the transaction settled.", "type": "string" }, "paymentId": { "description": "Identifier of the payment that produced the transaction.", "type": "string" }, "referenceId": { "description": "Your own reference, supplied when the payment was created.", "type": "string" }, "rrn": { "description": "Retrieval reference number assigned by the acquirer.", "type": "string" }, "amount": { "description": "Transaction amount, in the smallest unit of the currency (e.g. öre for SEK).", "type": "number" }, "currency": { "description": "ISO 4217 currency code of the transaction.", "type": "string" }, "method": { "description": "Payment method used, for example CARD, SWISH or GIFT_CARD.", "type": "string" }, "type": { "description": "Transaction type, for example PURCHASE or RETURN.", "type": "string" }, "orderSummary": { "description": "Short, human-readable summary of the order.", "type": "string" }, "timestamp": { "description": "When the transaction was created, in ISO 8601 format.", "type": "string" }, "voided": { "description": "Whether the transaction was voided.", "type": "boolean" }, "issuerCountry": { "description": "Country of the card issuer, reported at settlement.", "type": "string" }, "interchangeDomain": { "description": "Interchange domain the card falls under, for example domestic or intra-regional.", "type": "string" }, "cardCategory": { "description": "Card category reported at settlement, for example consumer or commercial.", "type": "string" }, "cardUsage": { "description": "Card funding type reported at settlement, for example debit or credit.", "type": "string" }, "fee": { "description": "Surfboard fee charged on the transaction, in the smallest currency unit.", "type": "number" }, "feeVat": { "description": "VAT charged on the Surfboard fee, in the smallest currency unit.", "type": "number" }, "settlementStatus": { "description": "Settlement state of the transaction; NOT_SETTLED until it is paid out.", "type": "string" }, "payout": { "description": "Amount paid out to the merchant for this transaction, in the smallest currency unit.", "type": "number" }, "settlementRef": { "description": "Reference of the settlement batch the transaction was paid out in.", "type": "string" }, "settlementDate": { "description": "Date the transaction was paid out to the merchant.", "type": "string" }, "truncatedPan": { "description": "Last four digits of the card number (PAN), zero-padded to four characters.", "type": "string" }, "cardLabel": { "description": "Application label of the card scheme used (the AID name).", "type": "string" }, "posEntryMode": { "description": "How the card was presented at the point of sale (entry mode).", "type": "string" }, "issuerApplication": { "description": "Issuer application data returned by the card.", "type": "string" }, "terminalVerificationResult": { "description": "Terminal verification results (TVR) from the card interaction.", "type": "string" }, "aid": { "description": "Application identifier (AID) of the card scheme used.", "type": "string" }, "customerResponseCode": { "description": "Response code returned by the card issuer.", "type": "string" }, "cvmMethod": { "description": "Cardholder verification method code used during the transaction.", "type": "string" }, "cvmMethodDescription": { "description": "Human-readable description of the cardholder verification method (e.g. 'Online PIN', 'No CVM').", "type": "string" }, "authMode": { "description": "Authorization mode; ISSUER when the issuer authorized the transaction.", "type": "string" }, "cardBrand": { "description": "Card brand, for example VISA or MASTERCARD.", "type": "string" }, "authCode": { "description": "Authorization code returned by the issuer.", "type": "string" }, "adjustments": { "description": "Tip or amount adjustments applied to the transaction. Present only when adjustments exist.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "The kind of adjustment, for example TIP.", "type": "string" }, "amount": { "description": "Adjustment amount, in the smallest currency unit.", "type": "number" }, "adjustmentId": { "description": "Unique identifier of the adjustment.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "transactionId": "txn_8f21c0a9b7", "merchantId": "m_5f2c1a9b3d", "storeId": "st_2a91", "terminalId": "t_7c33", "orderId": "ord_4b19d2", "paymentId": "pay_a71f", "referenceId": "order-2026-0012", "rrn": "618234501122", "amount": 14900, "currency": "SEK", "method": "CARD", "type": "PURCHASE", "orderSummary": "2x Flat White", "timestamp": "2026-06-01T09:24:11.000Z", "voided": false, "settlementStatus": "SETTLED", "fee": 268, "feeVat": 67, "payout": 14632, "cardBrand": "VISA", "truncatedPan": "0341", "cardLabel": "VISA CREDIT", "authMode": "ISSUER" } ], "message": "Fetched all transactions under merchant" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to fetch transactions" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/transactions/range": { "get": { "operationId": "listTransactionsByDateRange", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Transactions API" ], "parameters": [ { "name": "start", "in": "query", "required": false, "description": "Start of the date range to fetch transactions for (ISO 8601, e.g. 2026-06-01).", "schema": { "description": "Start of the date range to fetch transactions for (ISO 8601, e.g. 2026-06-01).", "type": "string" } }, { "name": "end", "in": "query", "required": false, "description": "End of the date range. If start is supplied without end, a 24-hour window from start is used.", "schema": { "description": "End of the date range. If start is supplied without end, a 24-hour window from start is used.", "type": "string" } }, { "name": "storeId", "in": "query", "required": false, "description": "Return only transactions that took place at this store.", "schema": { "description": "Return only transactions that took place at this store.", "type": "string" } }, { "name": "terminalId", "in": "query", "required": false, "description": "Return only transactions processed by this terminal (checkout).", "schema": { "description": "Return only transactions processed by this terminal (checkout).", "type": "string" } }, { "name": "X-PAGE-NUMBER", "in": "header", "required": false, "description": "Which page to return. Page size is fixed at 100 and there is no page-size parameter. The total is returned in the `x-total-items` response header. Past the last page the call succeeds with an empty `data`.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The transactions on the current page.", "type": "array", "items": { "type": "object", "properties": { "transactionId": { "description": "Unique identifier of the transaction.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant the transaction belongs to.", "type": "string" }, "storeId": { "description": "Identifier of the store where the transaction took place.", "type": "string" }, "terminalId": { "description": "Identifier of the terminal (checkout) that processed the transaction.", "type": "string" }, "orderId": { "description": "Identifier of the order the transaction settled.", "type": "string" }, "paymentId": { "description": "Identifier of the payment that produced the transaction.", "type": "string" }, "referenceId": { "description": "Your own reference, supplied when the payment was created.", "type": "string" }, "rrn": { "description": "Retrieval reference number assigned by the acquirer.", "type": "string" }, "amount": { "description": "Transaction amount, in the smallest unit of the currency (e.g. öre for SEK).", "type": "number" }, "currency": { "description": "ISO 4217 currency code of the transaction.", "type": "string" }, "method": { "description": "Payment method used, for example CARD, SWISH or GIFT_CARD.", "type": "string" }, "type": { "description": "Transaction type, for example PURCHASE or RETURN.", "type": "string" }, "orderSummary": { "description": "Short, human-readable summary of the order.", "type": "string" }, "timestamp": { "description": "When the transaction was created, in ISO 8601 format.", "type": "string" }, "voided": { "description": "Whether the transaction was voided.", "type": "boolean" }, "issuerCountry": { "description": "Country of the card issuer, reported at settlement.", "type": "string" }, "interchangeDomain": { "description": "Interchange domain the card falls under, for example domestic or intra-regional.", "type": "string" }, "cardCategory": { "description": "Card category reported at settlement, for example consumer or commercial.", "type": "string" }, "cardUsage": { "description": "Card funding type reported at settlement, for example debit or credit.", "type": "string" }, "fee": { "description": "Surfboard fee charged on the transaction, in the smallest currency unit.", "type": "number" }, "feeVat": { "description": "VAT charged on the Surfboard fee, in the smallest currency unit.", "type": "number" }, "settlementStatus": { "description": "Settlement state of the transaction; NOT_SETTLED until it is paid out.", "type": "string" }, "payout": { "description": "Amount paid out to the merchant for this transaction, in the smallest currency unit.", "type": "number" }, "settlementRef": { "description": "Reference of the settlement batch the transaction was paid out in.", "type": "string" }, "settlementDate": { "description": "Date the transaction was paid out to the merchant.", "type": "string" }, "truncatedPan": { "description": "Last four digits of the card number (PAN), zero-padded to four characters.", "type": "string" }, "cardLabel": { "description": "Application label of the card scheme used (the AID name).", "type": "string" }, "posEntryMode": { "description": "How the card was presented at the point of sale (entry mode).", "type": "string" }, "issuerApplication": { "description": "Issuer application data returned by the card.", "type": "string" }, "terminalVerificationResult": { "description": "Terminal verification results (TVR) from the card interaction.", "type": "string" }, "aid": { "description": "Application identifier (AID) of the card scheme used.", "type": "string" }, "customerResponseCode": { "description": "Response code returned by the card issuer.", "type": "string" }, "cvmMethod": { "description": "Cardholder verification method code used during the transaction.", "type": "string" }, "cvmMethodDescription": { "description": "Human-readable description of the cardholder verification method (e.g. 'Online PIN', 'No CVM').", "type": "string" }, "authMode": { "description": "Authorization mode; ISSUER when the issuer authorized the transaction.", "type": "string" }, "cardBrand": { "description": "Card brand, for example VISA or MASTERCARD.", "type": "string" }, "authCode": { "description": "Authorization code returned by the issuer.", "type": "string" }, "adjustments": { "description": "Tip or amount adjustments applied to the transaction. Present only when adjustments exist.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "The kind of adjustment, for example TIP.", "type": "string" }, "amount": { "description": "Adjustment amount, in the smallest currency unit.", "type": "number" }, "adjustmentId": { "description": "Unique identifier of the adjustment.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "transactionId": "txn_8f21c0a9b7", "merchantId": "m_5f2c1a9b3d", "storeId": "st_2a91", "terminalId": "t_7c33", "orderId": "ord_4b19d2", "paymentId": "pay_a71f", "referenceId": "order-2026-0012", "rrn": "618234501122", "amount": 14900, "currency": "SEK", "method": "CARD", "type": "PURCHASE", "orderSummary": "2x Flat White", "timestamp": "2026-06-01T09:24:11.000Z", "voided": false, "settlementStatus": "SETTLED", "fee": 268, "feeVat": 67, "payout": 14632, "cardBrand": "VISA", "truncatedPan": "0341", "cardLabel": "VISA CREDIT", "authMode": "ISSUER" } ], "message": "Fetched all transactions under merchant" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Failed to fetch transactions" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/transactions/search": { "get": { "operationId": "searchTransactions", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Transactions API" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "The text to search the merchant's transactions for, such as an order reference, RRN, or card label.", "schema": { "description": "The text to search the merchant's transactions for, such as an order reference, RRN, or card label.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The search results.", "type": "object", "properties": { "transactionDetails": { "description": "The matches found for the search.", "type": "object", "properties": { "entries": { "description": "Total number of matching transactions.", "type": "number" }, "hits": { "description": "The matching transactions.", "type": "array", "items": { "type": "object", "properties": { "transactionId": { "description": "Identifier of the matching transaction.", "type": "string" }, "path": { "description": "Location within the transaction where the match was found.", "type": "string" }, "matches": { "description": "The individual field matches for this transaction.", "type": "array", "items": { "type": "object", "properties": { "field": { "description": "The transaction field that matched the search.", "type": "string" }, "matched": { "description": "The matched value.", "type": "string" }, "snippet": { "description": "A snippet of text surrounding the match.", "type": "string" } }, "additionalProperties": true } }, "transaction": { "description": "A normalized view of the matched transaction.", "type": "object", "properties": { "transactionId": { "description": "Unique identifier of the transaction.", "type": "string" }, "merchantId": { "description": "Identifier of the merchant the transaction belongs to.", "type": "string" }, "storeId": { "description": "Identifier of the store where the transaction took place.", "type": "string" }, "terminalId": { "description": "Identifier of the terminal (checkout) that processed the transaction.", "type": "string" }, "orderId": { "description": "Identifier of the order the transaction settled.", "type": "string" }, "paymentId": { "description": "Identifier of the payment that produced the transaction.", "type": "string" }, "referenceId": { "description": "Your own reference, supplied when the payment was created.", "type": "string" }, "rrn": { "description": "Retrieval reference number assigned by the acquirer.", "type": "string" }, "amount": { "description": "Transaction amount, in the smallest unit of the currency (e.g. öre for SEK).", "type": "number" }, "currency": { "description": "ISO 4217 currency code of the transaction.", "type": "string" }, "method": { "description": "Payment method used, for example CARD, SWISH or GIFT_CARD.", "type": "string" }, "type": { "description": "Transaction type, for example PURCHASE or RETURN.", "type": "string" }, "orderSummary": { "description": "Short, human-readable summary of the order.", "type": "string" }, "timestamp": { "description": "When the transaction was created, in ISO 8601 format.", "type": "string" }, "voided": { "description": "Whether the transaction was voided.", "type": "boolean" }, "issuerCountry": { "description": "Country of the card issuer, reported at settlement.", "type": "string" }, "interchangeDomain": { "description": "Interchange domain the card falls under, for example domestic or intra-regional.", "type": "string" }, "cardCategory": { "description": "Card category reported at settlement, for example consumer or commercial.", "type": "string" }, "cardUsage": { "description": "Card funding type reported at settlement, for example debit or credit.", "type": "string" }, "fee": { "description": "Surfboard fee charged on the transaction, in the smallest currency unit.", "type": "number" }, "feeVat": { "description": "VAT charged on the Surfboard fee, in the smallest currency unit.", "type": "number" }, "settlementStatus": { "description": "Settlement state of the transaction; NOT_SETTLED until it is paid out.", "type": "string" }, "payout": { "description": "Amount paid out to the merchant for this transaction, in the smallest currency unit.", "type": "number" }, "settlementRef": { "description": "Reference of the settlement batch the transaction was paid out in.", "type": "string" }, "settlementDate": { "description": "Date the transaction was paid out to the merchant.", "type": "string" }, "truncatedPan": { "description": "Last four digits of the card number (PAN), zero-padded to four characters.", "type": "string" }, "cardLabel": { "description": "Application label of the card scheme used (the AID name).", "type": "string" }, "posEntryMode": { "description": "How the card was presented at the point of sale (entry mode).", "type": "string" }, "issuerApplication": { "description": "Issuer application data returned by the card.", "type": "string" }, "terminalVerificationResult": { "description": "Terminal verification results (TVR) from the card interaction.", "type": "string" }, "aid": { "description": "Application identifier (AID) of the card scheme used.", "type": "string" }, "customerResponseCode": { "description": "Response code returned by the card issuer.", "type": "string" }, "cvmMethod": { "description": "Cardholder verification method code used during the transaction.", "type": "string" }, "cvmMethodDescription": { "description": "Human-readable description of the cardholder verification method (e.g. 'Online PIN', 'No CVM').", "type": "string" }, "authMode": { "description": "Authorization mode; ISSUER when the issuer authorized the transaction.", "type": "string" }, "cardBrand": { "description": "Card brand, for example VISA or MASTERCARD.", "type": "string" }, "authCode": { "description": "Authorization code returned by the issuer.", "type": "string" }, "adjustments": { "description": "Tip or amount adjustments applied to the transaction. Present only when adjustments exist.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "The kind of adjustment, for example TIP.", "type": "string" }, "amount": { "description": "Adjustment amount, in the smallest currency unit.", "type": "number" }, "adjustmentId": { "description": "Unique identifier of the adjustment.", "type": "string" } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "transactionDetails": { "entries": 1, "hits": [ { "transactionId": "txn_8f21c0a9b7", "path": "transaction.referenceId", "matches": [ { "field": "referenceId", "matched": "order-2026-0012", "snippet": "…order-2026-0012…" } ], "transaction": { "transactionId": "txn_8f21c0a9b7", "merchantId": "m_5f2c1a9b3d", "storeId": "st_2a91", "terminalId": "t_7c33", "orderId": "ord_4b19d2", "paymentId": "pay_a71f", "referenceId": "order-2026-0012", "rrn": "618234501122", "amount": 14900, "currency": "SEK", "method": "CARD", "type": "PURCHASE", "orderSummary": "2x Flat White", "timestamp": "2026-06-01T09:24:11.000Z", "voided": false, "settlementStatus": "SETTLED", "fee": 268, "feeVat": 67, "payout": 14632, "cardBrand": "VISA", "truncatedPan": "0341", "cardLabel": "VISA CREDIT", "authMode": "ISSUER" } } ] } }, "message": "Transaction details search done successfully." } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Please pass in the search value as a query." } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Authentication failed" } } } } }, "security": [ { "apiKey": [], "apiSecret": [] } ] } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Webhooks API" ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page of results to return. Defaults to the first page when omitted or not a number.", "schema": { "description": "Page of results to return. Defaults to the first page when omitted or not a number.", "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "The webhooks configured on the account for the current page.", "type": "array", "items": { "type": "object", "properties": { "webhookId": { "description": "Unique identifier of the webhook.", "type": "string" }, "webhookName": { "description": "The display name you gave the webhook.", "type": "string" }, "webhookUrl": { "description": "The HTTPS endpoint Surfboard delivers events to.", "type": "string" }, "active": { "description": "Whether the webhook is currently active and receiving events.", "type": "boolean" }, "alertEmail": { "description": "Email address notified when webhook delivery repeatedly fails.", "type": "string" }, "tested": { "description": "Whether the webhook has passed a delivery test against its endpoint.", "type": "boolean" }, "events": { "description": "The event types this webhook is subscribed to.", "type": "array", "items": {} }, "createdAt": { "description": "When the webhook was created, in ISO 8601 format.", "type": "string" } }, "additionalProperties": true } }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": [ { "webhookId": "wh_9c1f2a7b40", "webhookName": "Order events", "webhookUrl": "https://example.com/surfboard/webhook", "active": true, "alertEmail": "integrations@surfboard.se", "tested": true, "events": [ "PAYMENT_SUCCEEDED", "PAYMENT_FAILED" ], "createdAt": "2026-06-01T09:24:11.000Z" } ], "message": "Fetched all webhooks under merchant" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to get all webhooks. Please try again later" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "post": { "operationId": "createWebhook", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Webhooks API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookUrl": { "description": "The HTTPS endpoint Surfboard should deliver events to.", "type": "string" }, "webhookName": { "description": "A display name for the webhook, used to identify it in listings.", "type": "string" }, "events": { "description": "The event types to subscribe this webhook to.", "type": "array", "items": {} }, "alertEmail": { "description": "Email address to notify when webhook delivery repeatedly fails.", "type": "string" } }, "required": [ "webhookUrl", "webhookName", "events", "alertEmail" ] }, "example": { "webhookUrl": "https://example.com/surfboard/webhook", "webhookName": "Order events", "events": [ "PAYMENT_SUCCEEDED", "PAYMENT_FAILED" ], "alertEmail": "integrations@surfboard.se" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Details of the created webhook.", "type": "object", "properties": { "webhookId": { "description": "Unique identifier of the newly created webhook.", "type": "string" }, "webhookCertificate": { "description": "Signing certificate used to verify that deliveries to your endpoint originated from Surfboard.", "type": "string" }, "tested": { "description": "Whether the webhook has passed a delivery test against its endpoint.", "type": "boolean" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "webhookId": "wh_9c1f2a7b40", "webhookCertificate": "-----BEGIN CERTIFICATE-----\nMIIB...snip...IDAQAB\n-----END CERTIFICATE-----", "tested": false }, "message": "Webhook created successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to create webhook. Please try again later" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/webhooks/{webhookId}": { "put": { "operationId": "updateWebhook", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Webhooks API" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Identifier of the webhook to update, supplied in the URL path.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookUrl": { "description": "New HTTPS endpoint to deliver events to. Omit to leave unchanged.", "type": "string" }, "webhookName": { "description": "New display name for the webhook. Omit to leave unchanged.", "type": "string" }, "alertEmail": { "description": "New email address to notify on repeated delivery failures. Omit to leave unchanged.", "type": "string" }, "events": { "description": "New set of event types to subscribe the webhook to. Omit to leave unchanged.", "type": "array", "items": {} } } }, "example": { "webhookName": "Order and refund events", "events": [ "PAYMENT_SUCCEEDED", "PAYMENT_FAILED", "REFUND_SUCCEEDED" ] } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Webhook updated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to update webhook. Please try again later" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] }, "delete": { "operationId": "disableWebhook", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Webhooks API" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Identifier of the webhook to disable, supplied in the URL path.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "message": "Webhook disabled successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to disable webhook. Please try again later" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } }, "/webhooks/{webhookId}/activate": { "post": { "operationId": "activateWebhook", "summary": "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.\n\nReference: https://developers.surfboardpayments.com/", "tags": [ "Webhooks API" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Identifier of the webhook to activate, supplied in the URL path.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "description": "Environment to activate the webhook in.", "type": "string", "enum": [ null, null ] } }, "required": [ "type" ] }, "example": { "type": "LIVE" } } } }, "responses": { "200": { "description": "Success. `status` is `SUCCESS` and `data` carries the result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Status of the request, either 'SUCCESS' or 'ERROR'.", "type": "string" }, "data": { "description": "Details of the activated webhook.", "type": "object", "properties": { "webhookId": { "description": "Identifier of the activated webhook.", "type": "string" } }, "additionalProperties": true }, "message": { "description": "A message that describes the status of the request.", "type": "string" } }, "additionalProperties": true }, "example": { "status": "SUCCESS", "data": { "webhookId": "wh_9c1f2a7b40" }, "message": "Webhook activated successfully" } } } }, "400": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unable to activate webhook. Please try again later" } } } }, "401": { "description": "Error. `status` is `ERROR` and `message` says why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "ERROR", "message": "Unauthorized access. Please provide valid credentials to access this endpoint." } } } } }, "security": [ { "apiKey": [], "apiSecret": [], "merchantId": [] } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "API-KEY", "description": "The API key issued with your account, per environment." }, "apiSecret": { "type": "apiKey", "in": "header", "name": "API-SECRET", "description": "The API secret paired with the key. Never ship this to a browser or a mobile app." }, "merchantId": { "type": "apiKey", "in": "header", "name": "MERCHANT-ID", "description": "The merchant the call acts on. Required on merchant-scoped endpoints." } }, "schemas": { "ErrorResponse": { "type": "object", "description": "Every Carbon API failure has this shape. `status` is `ERROR`, `message` says what went wrong, and where a documented error code applies it is carried in the message or in `data`.", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ERROR" ] }, "message": { "type": "string", "description": "What went wrong, in English." }, "data": { "description": "Present when the failure has structured detail, such as a per-field validation result." } } } } }, "x-source": { "generatedFrom": "https://www.surfboardpayments.com/api/ai/docs.json", "reference": "https://developers.surfboardpayments.com/", "operations": 237, "note": "Generated from the published API reference. Where this document and the reference disagree, the reference wins." } }