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.

    **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.

    **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.

    **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.

    This 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `STANDARD`: Apply standard image enhancements including lighting, color correction, and quality improvements.
                    - `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.

        Reference: 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.

        Reference: 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

        Reference: 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:
                    - undefined
                    - undefined
                    - undefined
                fontType:
                  description: Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'.
                  type: string
                  enum:
                    - undefined
                    - undefined
                    - undefined
                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.

        Reference: 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.

        Reference: 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

        Reference: 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:
                    - undefined
                    - undefined
                    - undefined
                fontType:
                  description: Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'.
                  type: string
                  enum:
                    - undefined
                    - undefined
                    - undefined
                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.

        Reference: 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.

        Reference: 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

        Reference: 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:
                    - undefined
                    - undefined
                    - undefined
                fontType:
                  description: Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'.
                  type: string
                  enum:
                    - undefined
                    - undefined
                    - undefined
                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.

        Reference: 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.

        Reference: 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

        Reference: 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:
                    - undefined
                    - undefined
                    - undefined
                fontType:
                  description: Font family for the customizable page. The available font types are 'sans-serif','serif' and 'mono'.
                  type: string
                  enum:
                    - undefined
                    - undefined
                    - undefined
                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.

        Reference: 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.

        Reference: 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.

        Reference: 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:
                                - undefined
                                - undefined
                                - undefined
                            fontType:
                              description: Suggested font family for the page.
                              type: string
                              enum:
                                - undefined
                                - undefined
                                - undefined
                            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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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).

        Reference: 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.

                    Values:
                    - `FUND`: Gift card with monetary value
                    - `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.

                    Values:
                    - `OPEN`: Gift card can be used by anyone
                    - `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.

        Reference: https://developers.surfboardpayments.com/
      tags:
        - Gift Cards API
      parameters:
        - name: type
          in: query
          required: false
          description: |-
            Filter gift cards by type.

            Values:
            - `FUND`: Gift cards with monetary value
            - `ENTITLEMENT`: Gift cards with usage-based limits
          schema:
            description: |-
              Filter gift cards by type.

              Values:
              - `FUND`: Gift cards with monetary value
              - `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.

        Reference: 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.

        Reference: 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.

            Values:
            - `ISSUED`: Gift card issuance transactions
            - `CREDIT`: Credit transactions (adding value)
            - `DEBIT`: Debit transactions (using value)
          schema:
            description: |-
              Filter transactions by type.

              Values:
              - `ISSUED`: Gift card issuance transactions
              - `CREDIT`: Credit transactions (adding value)
              - `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.

        Reference: 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.

        Reference: 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:

                          Values:
                          - `ORDER_PLACED`: The order has been successfully placed.
                          - `ORDER_SHIPPED`: The order has been shipped and is in transit.
                          - `ORDER_COMPLETED`: The order has been successfully fulfilled and completed.
                          - `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.

        Reference: 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.

            Values:
            - `createdAt`: Sort by the date the device record was created.
            - `serialNo`: Sort by hardware serial number.
            - `status`: Sort by the device's current lifecycle status.
          schema:
            description: |-
              The field to order the results by.

              Values:
              - `createdAt`: Sort by the date the device record was created.
              - `serialNo`: Sort by hardware serial number.
              - `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.

            Values:
            - `ASC`: Sort in ascending order.
            - `DESC`: Sort in descending order.
          schema:
            description: |-
              The direction to sort the results in.

              Values:
              - `ASC`: Sort in ascending order.
              - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                          Values:
                          - `WARRANTY`: The warranty covers issues potentially related to factory defects.
                          - `NOT_USING_SERVICE`: Not using service applies when the merchant voluntarily leaves or their partner ends the partnership.
                          - `NON_WARRANTY_BROKEN`: Non-warranty broken applies when the terminal is damaged due to misuse or accident.
                          - `TECHNICAL_ISSUES`: Technical issues apply when the terminal's software malfunctions.
                          - `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.

        Reference: 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.

            Values:
            - `APPROVED`: Returns that have been approved for processing.
            - `CREATED`: Returns that have been created but not yet processed.
          schema:
            description: |-
              Filter returns by status.

              Values:
              - `APPROVED`: Returns that have been approved for processing.
              - `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.

                            Values:
                            - `APPROVED`: The return request has been approved for processing.
                            - `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.

        Reference: 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.

        Reference: 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:

                        Values:
                        - `daily`: Recurring charge occurs every day.
                        - `twiceWeekly`: Recurring charge occurs twice a week.
                        - `weekly`: Recurring charge occurs once per week.
                        - `tenDays`: Recurring charge occurs once every 10 days.
                        - `fortNightly`: Recurring charge occurs once every two weeks.
                        - `monthly`: Recurring charge occurs once per month.
                        - `everyTwoMonths`: Recurring charge occurs once every two months.
                        - `trimester`: Recurring charge occurs every three months.
                        - `quarterly`: Recurring charge occurs once every quarter (three months).
                        - `twiceYearly`: Recurring charge occurs twice a year.
                        - `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.

        Reference: 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.

        Reference: 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

                        Values:
                        - `onlyNext`: Applies the update to the next billing cycle only.
                        - `lifeTime`: Applies the update for the remaining lifetime of the subscription.
                        - `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.

        Reference: 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:

                          Values:
                          - `daily`: Recurring charge occurs every day.
                          - `twiceWeekly`: Recurring charge occurs twice a week.
                          - `weekly`: Recurring charge occurs once per week.
                          - `tenDays`: Recurring charge occurs once every 10 days.
                          - `fortNightly`: Recurring charge occurs once every two weeks.
                          - `monthly`: Recurring charge occurs once per month.
                          - `everyTwoMonths`: Recurring charge occurs once every two months.
                          - `trimester`: Recurring charge occurs every three months.
                          - `quarterly`: Recurring charge occurs once every quarter (three months).
                          - `twiceYearly`: Recurring charge occurs twice a year.
                          - `annually`: Recurring charge occurs once a year.
                          - `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.

        Reference: 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.

                          Values:
                          - `AMEX`: American Express cards.
                          - `DISCOVER`: Discover cards.
                          - `MASTERCARD`: Mastercard-branded cards.
                          - `VISA`: Visa-branded cards.
                          - `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.

                          Values:
                          - `STANDARD`: A standalone physical card terminal.
                          - `SOFTPOS`: A soft point-of-sale terminal running on a phone or tablet.
                          - `ONLINE`: An online or e-commerce checkout.
                        type: string
                        enum:
                          - STANDARD
                          - SOFTPOS
                          - ONLINE
                      paymentMethod:
                        description: |-
                          The payment method this plan prices.

                          Values:
                          - `ACCTOACC`: Account-to-account bank transfer.
                          - `B2BINV`: Business-to-business invoicing.
                          - `CARD`: Card payments.
                          - `DCC_INSTORE`: In-store dynamic currency conversion.
                          - `EPASSI`: ePassi benefit payments.
                          - `KLARNA`: Klarna pay-later payments.
                          - `MOBILEPAY`: MobilePay wallet payments.
                          - `SWISH`: Swish instant payments.
                          - `VIPPS`: Vipps wallet payments.
                        type: string
                        enum:
                          - ACCTOACC
                          - B2BINV
                          - CARD
                          - DCC_INSTORE
                          - EPASSI
                          - KLARNA
                          - MOBILEPAY
                          - SWISH
                          - VIPPS
                      planType:
                        description: |-
                          How this plan prices transactions.

                          Values:
                          - `FIXED`: A single flat rate applies to every transaction.
                          - `VARIABLE`: The rate varies by the card's interchange domain and card type.
                          - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                            Values:
                            - `daily`: Every business day
                            - `twiceWeekly`: Twice a week
                            - `weekly`: Once a week
                            - `tenDays`: Every ten days
                            - `fortNightly`: Every two weeks
                            - `monthly`: Once a month
                            - `everyTwoMonths`: Every two months
                            - `trimester`: Every four months
                            - `quarterly`: Every three months
                            - `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.

                                Values:
                                - `visa`: Visa card scheme
                                - `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.

                                Values:
                                - `direct`: Owns the shares directly
                                - `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.

                                  Values:
                                  - `direct`: Owns the shares directly
                                  - `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.

                                Values:
                                - `DAILY`: Multiple times per day
                                - `WEEKLY`: A few times per week
                                - `MONTHLY`: A few times per month
                                - `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.

        Reference: 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.

        Reference: 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:

                          Values:
                          - `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.
                          - `APPLICATION_STARTED`: The merchant has started filling in the Web KYB form but has not yet submitted it.
                          - `APPLICATION_SUBMITTED`: The merchant has finished filling in the Web KYB and submitted it for processing.
                          - `APPLICATION_PENDING_INFORMATION`: The application is still under processing, and additional data is required from the merchant.
                          - `APPLICATION_SIGNED`: Both the merchant signatories and UBOs have signed the application.
                          - `APPLICATION_REJECTED`: The application has been processed and rejected.
                          - `APPLICATION_COMPLETED`: The application has been processed and accepted. It is now pending merchant creation and onboarding.
                          - `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.
                          - `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.

        Reference: 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.

        Reference: 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:

                            Values:
                            - `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.
                            - `APPLICATION_SUBMITTED`: The merchant has finished filling in the Web KYB and submitted it for processing.
                            - `APPLICATION_PENDING_INFORMATION`: The application is still under processing, and additional data is required from the merchant.
                            - `APPLICATION_SIGNED`: Both the merchant signatories and UBOs have signed the application.
                            - `APPLICATION_REJECTED`: The application has been processed and rejected.
                            - `APPLICATION_COMPLETED`: The application has been processed and accepted. It is now pending merchant creation and onboarding.
                            - `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

        Reference: 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.

                          Values:
                          - `STANDARD`: A regular merchant account.
                          - `DYNAMIC_MERCHANT`: A multi-merchant (dynamic) account that shares terminals across several merchants.
                          - `MARKETPLACE_MERCHANT`: A merchant operating within a marketplace setup.
                          - `PF_MERCHANT`: A merchant onboarded through a payment facilitator.
                          - `PF_TEST_MERCHANT`: A payment facilitator merchant used for testing.
                          - `PARTNER_MERCHANT`: A merchant onboarded directly by a partner.
                          - `TEST_MERCHANT`: A merchant used for testing and integration.
                          - `DEACTIVATED_MERCHANT`: A merchant account that has been deactivated.
                          - `ISV_MERCHANT`: A merchant onboarded through an ISV partner.
                          - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                            Values:
                            - `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.

        Reference: 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.

            Values:
            - `surfpad`: Hardware terminal with a physical keypad.
            - `surftouch`: Android terminal with custom payment apps, digital receipts etc.
            - `surfprint`: Android terminal with a built-in printer.
            - `checkoutPro`: Complete checkout solution with a customer facing screen.
            - `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.
            - `softpos`: SoftPOS solution on COTS devices.
            - `PaymentPage`: In this mode, the payment page and all associated configuration is managed by Surfboard.
            - `SelfHostedPage`: With SelfHostedPage, Surfboard renders the fields in your page.
            - `MerchantInitiated`: Set this type if you want to accept Merchant Initiated Transactions (MIT).
          schema:
            description: |-
              Type of terminal to filter results.

              Values:
              - `surfpad`: Hardware terminal with a physical keypad.
              - `surftouch`: Android terminal with custom payment apps, digital receipts etc.
              - `surfprint`: Android terminal with a built-in printer.
              - `checkoutPro`: Complete checkout solution with a customer facing screen.
              - `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.
              - `softpos`: SoftPOS solution on COTS devices.
              - `PaymentPage`: In this mode, the payment page and all associated configuration is managed by Surfboard.
              - `SelfHostedPage`: With SelfHostedPage, Surfboard renders the fields in your page.
              - `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.

        Reference: 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.

                          Values:
                          - `STANDARD`: A regular merchant account.
                          - `DYNAMIC_MERCHANT`: A multi-merchant (dynamic) account that shares terminals across several merchants.
                          - `MARKETPLACE_MERCHANT`: A merchant operating within a marketplace setup.
                          - `PF_MERCHANT`: A merchant onboarded through a payment facilitator.
                          - `PF_TEST_MERCHANT`: A payment facilitator merchant used for testing.
                          - `PARTNER_MERCHANT`: A merchant onboarded directly by a partner.
                          - `TEST_MERCHANT`: A merchant used for testing and integration.
                          - `DEACTIVATED_MERCHANT`: A merchant account that has been deactivated.
                          - `ISV_MERCHANT`: A merchant onboarded through an ISV partner.
                          - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `DAILY`: Daily settlement.
                    - `WEEKLY`: Weekly settlement.
                    - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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

                    Values:
                    - `DAILY_REPORTS`: Daily merchant reports
                    - `MONTHLY_REPORTS`: Monthly merchant reports
                    - `PAYMENT_COMPLETED`: Payment completion notifications
                    - `DAILY_FILE_TRANSFER`: Daily SFTP file transfers
                    - `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers
                    - `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

                        Values:
                        - `COMMA`: Comma separator (,)
                        - `SEMICOLON`: Semicolon separator (;)
                        - `PIPE`: Pipe separator (|)
                        - `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

        Reference: 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

            Values:
            - `DAILY_REPORTS`: Daily merchant reports
            - `MONTHLY_REPORTS`: Monthly merchant reports
            - `PAYMENT_COMPLETED`: Payment completion notifications
            - `DAILY_FILE_TRANSFER`: Daily SFTP file transfers
            - `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers
            - `MONTHLY_FILE_TRANSFER`: Monthly SFTP file transfers
          schema:
            description: |-
              Filter by event type

              Values:
              - `DAILY_REPORTS`: Daily merchant reports
              - `MONTHLY_REPORTS`: Monthly merchant reports
              - `PAYMENT_COMPLETED`: Payment completion notifications
              - `DAILY_FILE_TRANSFER`: Daily SFTP file transfers
              - `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers
              - `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

            Values:
            - `EMAIL`: Email notifications
            - `SLACK`: Slack notifications
            - `SFTP`: SFTP file transfer notifications
          schema:
            description: |-
              Filter by notification channel

              Values:
              - `EMAIL`: Email notifications
              - `SLACK`: Slack notifications
              - `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

                            Values:
                            - `DAILY_REPORTS`: Daily merchant reports
                            - `MONTHLY_REPORTS`: Monthly merchant reports
                            - `PAYMENT_COMPLETED`: Payment completion notifications
                            - `DAILY_FILE_TRANSFER`: Daily SFTP file transfers
                            - `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers
                            - `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

        Reference: 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.

        Reference: 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

                    Values:
                    - `MERCHANT_ONBOARDED`: Merchant onboarding notifications
                    - `ONLINE_STORE_ONBOARDED`: Online store onboarding notifications
                    - `TERMINAL_REGISTERED`: Terminal registration notifications
                    - `LOGISTICS_TERMINAL_SHIPPED`: Logistics terminal shipping notifications
                    - `DAILY_FILE_TRANSFER`: Daily SFTP file transfers
                    - `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers
                    - `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

                        Values:
                        - `COMMA`: Comma separator (,)
                        - `SEMICOLON`: Semicolon separator (;)
                        - `PIPE`: Pipe separator (|)
                        - `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

        Reference: 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

            Values:
            - `MERCHANT_ONBOARDED`: Merchant onboarding notifications
            - `ONLINE_STORE_ONBOARDED`: Online store onboarding notifications
            - `TERMINAL_REGISTERED`: Terminal registration notifications
            - `LOGISTICS_TERMINAL_SHIPPED`: Logistics terminal shipping notifications
            - `DAILY_FILE_TRANSFER`: Daily SFTP file transfers
            - `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers
            - `MONTHLY_FILE_TRANSFER`: Monthly SFTP file transfers
          schema:
            description: |-
              Filter by event type

              Values:
              - `MERCHANT_ONBOARDED`: Merchant onboarding notifications
              - `ONLINE_STORE_ONBOARDED`: Online store onboarding notifications
              - `TERMINAL_REGISTERED`: Terminal registration notifications
              - `LOGISTICS_TERMINAL_SHIPPED`: Logistics terminal shipping notifications
              - `DAILY_FILE_TRANSFER`: Daily SFTP file transfers
              - `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers
              - `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

            Values:
            - `EMAIL`: Email notifications
            - `SLACK`: Slack notifications
            - `SFTP`: SFTP file transfer notifications
          schema:
            description: |-
              Filter by notification channel

              Values:
              - `EMAIL`: Email notifications
              - `SLACK`: Slack notifications
              - `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

                            Values:
                            - `MERCHANT_ONBOARDED`: Merchant onboarding notifications
                            - `ONLINE_STORE_ONBOARDED`: Online store onboarding notifications
                            - `TERMINAL_REGISTERED`: Terminal registration notifications
                            - `LOGISTICS_TERMINAL_SHIPPED`: Logistics terminal shipping notifications
                            - `DAILY_FILE_TRANSFER`: Daily SFTP file transfers
                            - `WEEKLY_FILE_TRANSFER`: Weekly SFTP file transfers
                            - `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

        Reference: 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.

        Reference: 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,

                        Values:
                        - `NONE`: This value indicates that no tags are allowed for reading.
                        - `SINGLE`: Single read allowed for the order.
                        - `MULTIPLE_EDITABLE`: Multiple tags can be read and edited.
                        - `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 <number><unit>, 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.

                            Values:
                            - `ADD_MONEY`: Add money to balance
                            - `BOOK`: Book a service
                            - `CHECKOUT`: Standard checkout
                            - `CONTINUE`: Continue flow
                            - `CONTRIBUTE`: Contribute to a cause
                            - `DONATE`: Donate money
                            - `ORDER`: Place an order
                            - `PAY`: Pay now
                            - `RENT`: Rent item/service
                            - `SUPPORT`: Support a creator/cause
                            - `TIP`: Leave a tip
                            - `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.

                                Values:
                                - `fixed`: A fixed amount is collected.
                                - `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.

        Reference: 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,

                        Values:
                        - `NONE`: This value indicates that no tags are allowed for reading.
                        - `SINGLE`: Single read allowed for the order.
                        - `MULTIPLE_EDITABLE`: Multiple tags can be read and edited.
                        - `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 <number><unit>, 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.

                            Values:
                            - `ADD_MONEY`: Add money to balance
                            - `BOOK`: Book a service
                            - `CHECKOUT`: Standard checkout
                            - `CONTINUE`: Continue flow
                            - `CONTRIBUTE`: Contribute to a cause
                            - `DONATE`: Donate money
                            - `ORDER`: Place an order
                            - `PAY`: Pay now
                            - `RENT`: Rent item/service
                            - `SUPPORT`: Support a creator/cause
                            - `TIP`: Leave a tip
                            - `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.

                                Values:
                                - `fixed`: A fixed amount is collected.
                                - `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.

        Reference: 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,

                              Values:
                              - `NONE`: This value indicates that no tags are allowed for reading.
                              - `SINGLE`: Single read allowed for the order.
                              - `MULTIPLE_EDITABLE`: Multiple tags can be read and edited.
                              - `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 <number><unit>, 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.

                                  Values:
                                  - `ADD_MONEY`: Add money to balance
                                  - `BOOK`: Book a service
                                  - `CHECKOUT`: Standard checkout
                                  - `CONTINUE`: Continue flow
                                  - `CONTRIBUTE`: Contribute to a cause
                                  - `DONATE`: Donate money
                                  - `ORDER`: Place an order
                                  - `PAY`: Pay now
                                  - `RENT`: Rent item/service
                                  - `SUPPORT`: Support a creator/cause
                                  - `TIP`: Leave a tip
                                  - `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.

                                      Values:
                                      - `fixed`: A fixed amount is collected.
                                      - `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.

        Reference: 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.

        Reference: 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:

                          Values:
                          - `PENDING`: An order has been created and is waiting for payment processing.
                          - `PAYMENT_COMPLETED`: The payment has been completed for the order.
                          - `PAYMENT_CANCELLED`: The payment attempt has been cancelled for the order.
                          - `PARTIAL_PAYMENT_COMPLETED`: A partial payment was completed for the order
                          - `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:

                                Values:
                                - `PAYMENT_INITIATED`: A payment attempt has been initiated.
                                - `PAYMENT_PROCESSING`: The payment is being authorized.
                                - `PAYMENT_PROCESSED`: The payment has been authorized.
                                - `PAYMENT_COMPLETED`: The payment has been completed.
                                - `PAYMENT_FAILED`: The payment attempt has failed.
                                - `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.

                                Values:
                                - `PROCESSED`: Settlement processed. Waiting on amount to be credited to merchant's bank account.
                                - `SETTLED`: The transaction was settled.
                                - `NOT_SETTLED`: The transaction is not settled.
                                - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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:
              - undefined
              - undefined
        - 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:
                            - undefined
                            - undefined
                        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.

        Reference: 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:
              - undefined
              - undefined
              - undefined
              - undefined
              - undefined
              - undefined
              - undefined
              - undefined
              - undefined
              - undefined
        - 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:
              - undefined
              - undefined
              - undefined
              - undefined
        - 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:
              - undefined
              - undefined
              - undefined
        - name: sortOrder
          in: query
          required: false
          description: Sort direction for the results.
          schema:
            description: Sort direction for the results.
            type: string
            enum:
              - undefined
              - undefined
        - 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:
                                - undefined
                                - undefined
                            statusGroup:
                              description: Status group the row is grouped by. Present only when grouping by status group.
                              type: string
                              enum:
                                - undefined
                                - undefined
                                - undefined
                                - undefined
                            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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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:
                    - undefined
                    - undefined
                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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `CARD`: Use this payment method to make card transactions for the order.
                    - `CARD_NP`: Use this payment method to process card-not-present (CNP) refunds for the order.
                    - `KLARNA`: Make payments using Klarna.
                    - `CTOKEN`: Use this payment method to make payments using tokenised card if available. Used during online payments.
                    - `GIFTCARD`: Use this to make payments with gift cards/vouchers.
                    - `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.

                            Values:
                            - `BANK`: Standard bank transfer initiated manually by the payer.
                            - `DIRECT_BANK`: Automated account-to-account (A2A) transfer using open banking or similar mechanisms.
                            - `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.

                        Values:
                        - `CUSTOMER_INITIATED_RETURN`: This type of refund refers to when a customer initiates a return of a product or service they purchased.
                        - `SUSPECTED_MALFUNCTION`: When there is a suspected system malfunction which demands a return request, this type is used.
                        - `SUSPECTED_FRAUD`: When there is a suspected irregularity/fraud requiring a return request, this type is used.
                        - `DUPLICATE_TRANSACTION`: This type of refund request is submitted when there are duplicate transactions noticed in the system.
                        - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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:

                          Values:
                          - `PAYMENT_COMPLETED`: The payment was completed and cannot be cancelled.
                          - `PAYMENT_FAILED`: Cannot cancel a failed payment.
                          - `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.

        Reference: 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.

                          Values:
                          - `NOT_INITIATED`: Void has not been initiated for the payment.
                          - `VOID_INITIATED`: Void is initiated.
                          - `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.
                          - `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.

        Reference: 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.

        Reference: 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.

                          Values:
                          - `PENDING`: Payment yet to be captured.
                          - `SUCCESS`: Payment captured successfully.
                          - `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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `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.

        Reference: 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.

                    Values:
                    - `CARD`: Use this payment method to make card transactions for the order.
                    - `CARD_NP`: Use this payment method to process card-not-present (CNP) refunds for the order.
                    - `KLARNA`: Make payments using Klarna.
                    - `CTOKEN`: Use this payment method to make payments using tokenised card if available. Used during online payments.
                    - `GIFTCARD`: Use this to make payments with gift cards/vouchers.
                    - `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.

                        Values:
                        - `CARD`: Use this payment method to make card transactions for the order.
                        - `CARD_NP`: Use this payment method to process card-not-present (CNP) refunds for the order.
                        - `KLARNA`: Make payments using Klarna.
                        - `CTOKEN`: Use this payment method to make payments using tokenised card if available. Used during online payments.
                        - `GIFTCARD`: Use this to make payments with gift cards/vouchers.
                        - `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.

                            Values:
                            - `CUSTOMER_INITIATED_RETURN`: This type of refund refers to when a customer initiates a return of a product or service they purchased.
                            - `SUSPECTED_MALFUNCTION`: When there is a suspected system malfunction which demands a return request, this type is used.
                            - `SUSPECTED_FRAUD`: When there is a suspected irregularity/fraud requiring a return request, this type is used.
                            - `DUPLICATE_TRANSACTION`: This type of refund request is submitted when there are duplicate transactions noticed in the system.
                            - `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.

                                Values:
                                - `BANK`: Standard bank transfer initiated manually by the payer.
                                - `DIRECT_BANK`: Automated account-to-account (A2A) transfer using open banking or similar mechanisms.
                                - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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,

                    Values:
                    - `PRODUCT`: Its refers to tangible things sold for the exchange of a fee.
                    - `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.

                    Values:
                    - `FIXED_UNIT`: Pre-packaged products sold in fixed units.
                    - `VARIABLE_UNIT`: Product sold by weight or volume.
                    - `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.

                          Values:
                          - `VAT`: Value-added tax.
                          - `CGST`: Central goods and services tax.
                          - `SGST`: State goods and services tax.
                          - `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.

                        Values:
                        - `NO_PENALTY`: No penalty charged for early termination.
                        - `BALANCE_AMOUNT`: Customer has to pay the balance amount if terminated early.
                        - `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.

        Reference: 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.

                                Values:
                                - `FIXED_UNIT`: Pre-packaged products sold in fixed units.
                                - `VARIABLE_UNIT`: Products sold by weight or volume.
                                - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `STOCK_UP`: Indicates an addition to the currently available stock.
                    - `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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `STOCK_UP`: Indicates an addition to the currently available variant stock.
                    - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `PROMO_CODE`: A discount the customer redeems with a code, configured in `promoCode`.
                    - `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.

                          Values:
                          - `TEXT`: Text content, shown using `headline`, `subheadline`, and `body`.
                          - `IMAGE`: An image, shown using `url`.
                          - `VIDEO`: A video, shown using `url`.
                          - `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.

                            Values:
                            - `PERCENTAGE_OFF`: A percentage discount, set by `percentage`.
                            - `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.

        Reference: 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.

                          Values:
                          - `TEXT`: Text content, shown using `headline`, `subheadline`, and `body`.
                          - `IMAGE`: An image, shown using `url`.
                          - `VIDEO`: A video, shown using `url`.
                          - `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.

                            Values:
                            - `PERCENTAGE_OFF`: A percentage discount, set by `percentage`.
                            - `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.

        Reference: 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.

        Reference: 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.

                            Values:
                            - `ACTIVE`: Currently running — within its schedule, with budget and redemption limits remaining.
                            - `CREATED`: Created but not yet started (its start time is in the future).
                            - `DEACTIVATED`: Manually switched off by the merchant.
                            - `EXPIRED`: Past its end time.
                            - `BUDGET_DEPLETED`: Stopped because spend reached the promo code budget.
                            - `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.

                            Values:
                            - `PROMO_CODE`: A discount the customer redeems with a code, configured in `promoCode`.
                            - `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.

        Reference: 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.

            Values:
            - `ACTIVE`: Currently running — within its schedule, with budget and redemption limits remaining.
            - `CREATED`: Created but not yet started (its start time is in the future).
            - `DEACTIVATED`: Manually switched off by the merchant.
            - `EXPIRED`: Past its end time.
            - `BUDGET_DEPLETED`: Stopped because spend reached the promo code budget.
            - `ATTEMPTS_EXHAUSTED`: Stopped because the redemption limit was reached.
          schema:
            description: |-
              Returns only promotions in this state. Omit to return promotions of any status.

              Values:
              - `ACTIVE`: Currently running — within its schedule, with budget and redemption limits remaining.
              - `CREATED`: Created but not yet started (its start time is in the future).
              - `DEACTIVATED`: Manually switched off by the merchant.
              - `EXPIRED`: Past its end time.
              - `BUDGET_DEPLETED`: Stopped because spend reached the promo code budget.
              - `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.

                                Values:
                                - `ACTIVE`: Currently running — within its schedule, with budget and redemption limits remaining.
                                - `CREATED`: Created but not yet started (its start time is in the future).
                                - `DEACTIVATED`: Manually switched off by the merchant.
                                - `EXPIRED`: Past its end time.
                                - `BUDGET_DEPLETED`: Stopped because spend reached the promo code budget.
                                - `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.

                                Values:
                                - `PROMO_CODE`: A discount the customer redeems with a code, configured in `promoCode`.
                                - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `TRANSACTION_RECEIPT`: The standard per-transaction receipt.
                    - `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.

        Reference: 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.

                    Values:
                    - `sv`: Swedish.
                    - `da`: Danish.
                    - `fi`: Finnish.
                    - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `single`: Read a single RFID tag and then stop.
                    - `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.

        Reference: 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.

        Reference: 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.

                          Values:
                          - `PENDING`: The session is awaiting tag reads.
                          - `COMPLETED`: The session completed successfully.
                          - `CANCELLED`: The session was cancelled.
                          - `TIMED_OUT`: The session timed out before completing.
                          - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `COMPLETED`: The session finished successfully.
                    - `CANCELLED`: The session was cancelled.
                    - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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:
              - undefined
              - undefined
      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:
                            - undefined
                            - undefined
                            - undefined
                            - undefined
                            - undefined
                            - undefined
                            - undefined
                            - undefined
                            - undefined
                            - undefined
                            - undefined
                            - undefined
                        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.

        Reference: 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:
                          - undefined
                          - undefined
                          - undefined
                          - undefined
                          - undefined
                          - undefined
                          - undefined
                          - undefined
                          - undefined
                          - undefined
                          - undefined
                          - undefined
                      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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                            Values:
                            - `ACTIVE`: The store is active and ready for payments.
                            - `DEACTIVATED`: The store has been deactivated.
                            - `BLOCKED`: The store is blocked from further activity.
                            - `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.

        Reference: 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.

        Reference: 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.

                          Values:
                          - `ACTIVE`: The store is active and ready for payments.
                          - `DEACTIVATED`: The store is deactivated.
                          - `BLOCKED`: The store is blocked from further activities.
                          - `INACTIVE`: The store is in verification stage.
                        type: string
                        enum:
                          - ACTIVE
                          - DEACTIVATED
                          - BLOCKED
                          - INACTIVE
                      onlineOnboardingStatus:
                        description: |-
                          Onboarding status of the online store.

                          Values:
                          - `APPROVED`: The store is approved for online payments.
                          - `INITIATED`: The online store verification is initiated.
                          - `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.

        Reference: 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.

        Reference: 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.

            Values:
            - `surfpad`: Hardware terminal with a physical keypad.
            - `surftouch`: Android terminal with custom payment apps, digital receipts etc.
            - `surfprint`: Android terminal with a built-in printer.
            - `checkoutPro`: Complete checkout solution with a customer facing screen.
            - `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.
            - `PaymentPage`: Surfboard-hosted payment page where all UI and configurations are managed by Surfboard.
            - `SelfHostedPage`: Merchant-hosted payment page where Surfboard renders payment fields within the merchant’s environment.
            - `MerchantInitiated`: Used for Merchant Initiated Transactions (MIT), allowing payments to be triggered by the merchant without customer interaction.
            - `printer`: Standalone printing device.
            - `surftester`: Surfboard Android based test terminal used during integrations.
          schema:
            description: |-
              Optional query param to filter terminals by terminal type.

              Values:
              - `surfpad`: Hardware terminal with a physical keypad.
              - `surftouch`: Android terminal with custom payment apps, digital receipts etc.
              - `surfprint`: Android terminal with a built-in printer.
              - `checkoutPro`: Complete checkout solution with a customer facing screen.
              - `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.
              - `PaymentPage`: Surfboard-hosted payment page where all UI and configurations are managed by Surfboard.
              - `SelfHostedPage`: Merchant-hosted payment page where Surfboard renders payment fields within the merchant’s environment.
              - `MerchantInitiated`: Used for Merchant Initiated Transactions (MIT), allowing payments to be triggered by the merchant without customer interaction.
              - `printer`: Standalone printing device.
              - `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.

                            Values:
                            - `surfpad`: Hardware terminal with a physical keypad.
                            - `surftouch`: Android terminal with custom payment apps, digital receipts etc.
                            - `surfprint`: Android terminal with a built-in printer.
                            - `checkoutPro`: Complete checkout solution with a customer facing screen.
                            - `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.
                            - `PaymentPage`: Surfboard-hosted payment page where all UI and configurations are managed by Surfboard.
                            - `SelfHostedPage`: Merchant-hosted payment page where Surfboard renders payment fields within the merchant’s environment.
                            - `MerchantInitiated`: Used for Merchant Initiated Transactions (MIT), allowing payments to be triggered by the merchant without customer interaction.
                            - `printer`: Standalone printing device.
                            - `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.

                            Values:
                            - `android`: Android operating system.
                            - `ios`: Apple's operating system for iPhones.
                            - `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.

        Reference: 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.

                    Values:
                    - `enabled`: The terminal accepts card payments while offline.
                    - `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.

        Reference: 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.

                    Values:
                    - `MERCHANT_WEBSHOP_URL`: Use this to verify the merchant webshop domain.
                    - `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.

        Reference: 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.

                          Values:
                          - `APPROVED`: The online store is approved for online payments.
                          - `INITIATED`: The online store verification is initiated.
                          - `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.

                                Values:
                                - `ACTIVE`: The domain is active.
                                - `DEACTIVATED`: The domain is deactivated.
                              type: string
                              enum:
                                - ACTIVE
                                - DEACTIVATED
                            type:
                              description: |-
                                Refers to the type of the domain.

                                Values:
                                - `MERCHANT_WEBSHOP_URL`: This represents the merchant webshop domain.
                                - `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.

        Reference: 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.

        Reference: 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.

                            Values:
                            - `ACTIVE`: The store is active and ready for payments.
                            - `DEACTIVATED`: The store has been deactivated.
                            - `BLOCKED`: The store is blocked from further activity.
                            - `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.

        Reference: 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.

        Reference: 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.

                          Values:
                          - `ACTIVE`: The store is active and ready for payments.
                          - `DEACTIVATED`: The store has been deactivated.
                          - `BLOCKED`: The store is blocked from further activity.
                          - `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.

                          Values:
                          - `APPROVED`: The store is approved for online payments.
                          - `INITIATED`: Online store verification is in progress.
                          - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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:

                          Values:
                          - `REGISTERED`: The terminal has been successfully registered.
                          - `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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `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.
                    - `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.
                    - `iFrame`: Registers an online terminal that renders as an embeddable iFrame.
                    - `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:

                          Values:
                          - `REGISTERED`: The terminal has been successfully registered.
                          - `DEREGISTERED`: The terminal was previously registered but has now been removed from the system.
                          - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                          Values:
                          - `surfpad`: Hardware terminal with a physical keypad.
                          - `surftouch`: Android terminal with custom payment apps, digital receipts etc.
                          - `surfprint`: Android terminal with a built-in printer.
                          - `checkoutPro`: Complete checkout solution with a customer facing screen.
                          - `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.
                          - `PaymentPage`: In this mode, the payment page and all associated configuration is managed by Surfboard.
                          - `SelfHostedPage`: With SelfHostedPage, Surfboard renders the fields in your page.
                          - `iFrame`: Online terminal rendered as an embeddable iFrame.
                          - `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.

                          Values:
                          - `android`: Android operating system.
                          - `ios`: Apple's operating system for iPhones.
                          - `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.

                          Values:
                          - `EXTERNAL_POWER`: Connected to an external power source.
                          - `BATTERY`: Charging via battery source.
                        type: string
                        enum:
                          - EXTERNAL_POWER
                          - BATTERY
                      deviceNetwork:
                        description: |-
                          The current mode of communication.

                          Values:
                          - `WIFI`: The terminal is connected to WIFI.
                          - `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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `enabled`: The terminal accepts card payments while offline.
                    - `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.

        Reference: 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.

                          Values:
                          - `surfpad`: Hardware terminal with a physical keypad.
                          - `surftouch`: Android terminal with custom payment apps, digital receipts etc.
                          - `surfprint`: Android terminal with a built-in printer.
                          - `checkoutPro`: Complete checkout solution with a customer facing screen.
                          - `checkoutX`: Software checkout solution for NFC-enabled Android devices to accept contactless card payments.
                          - `PaymentPage`: In this mode, the payment page and all associated configuration is managed by Surfboard.
                          - `SelfHostedPage`: With SelfHostedPage, Surfboard renders the fields in your page.
                          - `iFrame`: Online terminal rendered as an embeddable iFrame.
                          - `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.

                          Values:
                          - `android`: Android operating system.
                          - `ios`: Apple's operating system for iPhones.
                          - `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.

                          Values:
                          - `EXTERNAL_POWER`: Connected to an external power source.
                          - `BATTERY`: Charging via battery source.
                        type: string
                        enum:
                          - EXTERNAL_POWER
                          - BATTERY
                      deviceNetwork:
                        description: |-
                          The current mode of communication.

                          Values:
                          - `WIFI`: The terminal is connected to WIFI.
                          - `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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `enabled`: The terminal accepts card payments while offline.
                    - `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.

        Reference: 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.

        Reference: 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'.

                          Values:
                          - `WIFI`: Sets the preferred network of the terminal as WiFi.
                          - `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.

                          Values:
                          - `enabled`: Offline card payments are enabled.
                          - `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.

        Reference: 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'.

                          Values:
                          - `WIFI`: Sets the preferred network of the terminal as WiFi.
                          - `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.

                          Values:
                          - `enabled`: Offline card payments are enabled.
                          - `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.

        Reference: 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'.

                          Values:
                          - `WIFI`: Sets the preferred network of the terminal as WiFi.
                          - `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.

                          Values:
                          - `enabled`: Offline card payments are enabled.
                          - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                          Values:
                          - `REGISTERED`: Interapp registration successful.
                          - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

                          Values:
                          - `enabled`: Offline card payments are enabled.
                          - `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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `enabled`: The terminal accepts card payments while offline.
                    - `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.

        Reference: 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.

        Reference: 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.

                    Values:
                    - `enabled`: The terminal accepts card payments while offline.
                    - `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.

                          Values:
                          - `enabled`: Offline card payments are enabled.
                          - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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:

                    Values:
                    - `ENABLED`: Allows the terminal to display preset tip options while accepting payments.
                    - `DISABLED`: Hides the tip option so the terminal shows no tip prompts during payment.
                    - `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.

                    Values:
                    - `ENABLED`: Shows the calculated tip amount.
                    - `DISABLED`: Hides the calculated tip amount.
                  type: string
                  enum:
                    - ENABLED
                    - DISABLED
                tipDisplayFormat:
                  description: |-
                    The format in which the preset tip levels are displayed.

                    Values:
                    - `PERCENTAGE`: Displays preset tip levels as percentages.
                    - `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.

        Reference: 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).

                          Values:
                          - `ENABLED`: Allows the terminal to display preset tip options while accepting payments.
                          - `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.

                          Values:
                          - `ENABLED`: Shows the calculated tip amount.
                          - `DISABLED`: Hides the calculated tip amount.
                        type: string
                        enum:
                          - ENABLED
                          - DISABLED
                      tipDisplayFormat:
                        description: |-
                          The format in which the preset tip levels are displayed.

                          Values:
                          - `PERCENTAGE`: Displays preset tip levels as percentages.
                          - `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.

        Reference: 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:

                    Values:
                    - `ENABLED`: Allows the terminal to display preset tip options while accepting payments.
                    - `DISABLED`: Hides the tip option so the terminal shows no tip prompts during payment.
                    - `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.

                    Values:
                    - `ENABLED`: Shows the calculated tip amount.
                    - `DISABLED`: Hides the calculated tip amount.
                  type: string
                  enum:
                    - ENABLED
                    - DISABLED
                tipDisplayFormat:
                  description: |-
                    The format in which the preset tip levels are displayed.

                    Values:
                    - `PERCENTAGE`: Displays preset tip levels as percentages.
                    - `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.

        Reference: 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).

                          Values:
                          - `ENABLED`: Allows the terminal to display preset tip options while accepting payments.
                          - `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.

                          Values:
                          - `ENABLED`: Shows the calculated tip amount.
                          - `DISABLED`: Hides the calculated tip amount.
                        type: string
                        enum:
                          - ENABLED
                          - DISABLED
                      tipDisplayFormat:
                        description: |-
                          The format in which the preset tip levels are displayed.

                          Values:
                          - `PERCENTAGE`: Displays preset tip levels as percentages.
                          - `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.

        Reference: 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:

                    Values:
                    - `ENABLED`: Allows the terminal to display preset tip options while accepting payments.
                    - `DISABLED`: Hides the tip option so the terminal shows no tip prompts during payment.
                    - `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.

                    Values:
                    - `ENABLED`: Shows the calculated tip amount.
                    - `DISABLED`: Hides the calculated tip amount.
                  type: string
                  enum:
                    - ENABLED
                    - DISABLED
                tipDisplayFormat:
                  description: |-
                    The format in which the preset tip levels are displayed.

                    Values:
                    - `PERCENTAGE`: Displays preset tip levels as percentages.
                    - `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.

        Reference: 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).

                          Values:
                          - `ENABLED`: Allows the terminal to display preset tip options while accepting payments.
                          - `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.

                          Values:
                          - `ENABLED`: Shows the calculated tip amount.
                          - `DISABLED`: Hides the calculated tip amount.
                        type: string
                        enum:
                          - ENABLED
                          - DISABLED
                      tipDisplayFormat:
                        description: |-
                          The format in which the preset tip levels are displayed.

                          Values:
                          - `PERCENTAGE`: Displays preset tip levels as percentages.
                          - `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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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.

        Reference: 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-----
                    MIIB...snip...IDAQAB
                    -----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.

        Reference: 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.

        Reference: 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.

        Reference: 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:
                    - undefined
                    - undefined
              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.
