### Getting Started with Surfboard APIs Source: https://developers.surfboardpayments.com/guides/online-payments/integrations/apis-and-environments New developers should begin their integration process with the 'Initial Setup' guide to understand the fundamental steps. ```APIDOC ## Getting Started New developers should start with our **Initial Setup** to begin the integration process. ``` -------------------------------- ### Create Merchant API Source: https://developers.surfboardpayments.com/guides/online-payments/create-merchant-and-store-setup/create-merchant-and-store-setup Initiates a merchant application and creates an online store. Requires API credentials and merchant organization details. Returns an applicationId and a KYB URL for merchant completion. ```APIDOC ## POST /partners/:partnerId/merchants ### Description Initiates a merchant application and creates an online store. This endpoint is used by partners to onboard new merchants for online payment acceptance. It requires the partner's API credentials and specific details about the merchant's organization and online store. ### Method POST ### Endpoint `/partners/:partnerId/merchants` ### Parameters #### Path Parameters - **partnerId** (string) - Required - The unique identifier of the partner initiating the merchant creation. #### Query Parameters None #### Request Body - **country** (string) - Required - The two-letter ISO country code of the merchant (e.g., 'SE', 'DK'). - **organisation** (object) - Required - Details about the merchant's organization. - **corporateId** (string) - Required - The corporate identifier of the merchant organization. - **legalName** (string) - Optional - The legal name of the merchant organization. - **mccCode** (string) - Optional - The Merchant Category Code. - **address** (object) - Optional - The merchant's address details. - **careOf** (string) - Optional - **addressLine1** (string) - Optional - **addressLine2** (string) - Optional - **city** (string) - Optional - **countryCode** (string) - Optional - **postalCode** (string) - Optional - **phone** (object) - Optional - The merchant's phone number. - **code** (integer) - Optional - **number** (string) - Optional - **email** (string) - Optional - The merchant's contact email. - **acquirerMID** (string) - Optional - The acquirer merchant ID. - **multiMerchantId** (string) - Optional - A multi-merchant identifier. - **controlFields** (object) - Optional - Contains various control fields for the merchant setup. - **displayProducts** (array) - Optional - List of products to display. - **productId** (string) - Optional - **pricingPlans** (array of strings) - Optional - **showProductCatalogue** (boolean) - Optional - **transactionPricingPlan** (string) - Optional - **preSelectProducts** (array) - Optional - List of pre-selected products. - **productId** (string) - Optional - **quantity** (integer) - Optional - **pricingPlanId** (string) - Optional - **store** (object) - Required - Online store details. - **name** (string) - Required - The name of the online store. - **email** (string) - Required - The email address for the online store. - **phoneNumber** (object) - Optional - Phone number for the online store. - **code** (integer) - Optional - **number** (string) - Optional - **address** (object) - Optional - Address for the online store. - **careOf** (string) - Optional - **addressLine1** (string) - Optional - **city** (string) - Optional - **countryCode** (string) - Optional - **postalCode** (string) - Optional - **onlineInfo** (object) - Required - Specific online information for the store. - **merchantWebshopURL** (string) - Required - The URL of the merchant's webshop. - **paymentPageHostURL** (string) - Required - The host URL of the payment page. - **termsAndConditionsURL** (string) - Required - The URL for the merchant's terms and conditions, including refund policy. - **privacyPolicyURL** (string) - Required - The URL for the merchant's privacy policy. ### Request Example ```json { "country": "SE", "organisation": { "corporateId": "1234567890", "legalName": "Legal Name", "mccCode": "5192", "address": { "careOf": "John Doe", "addressLine1": "Main Street 123", "addressLine2": "Building C", "city": "Stockholm", "countryCode": "SE", "postalCode": "123 45" }, "phone": { "code": 46, "number": "123456789" }, "email": "contact@test.com" }, "acquirerMID": "PF123456", "multiMerchantId": "8132483499c658050e", "controlFields": { "displayProducts": [ { "productId": "815db2c5adc9b00301", "pricingPlans": ["816192c7efa2b0091a"] } ], "showProductCatalogue": true, "transactionPricingPlan": "816192c7efa2b0091a", "preSelectProducts": [ { "productId": "815db2c5adc9b00301", "quantity": 2, "pricingPlanId": "816192c7efa2b0091a" } ], "store": { "name": "Test Store", "email": "test@test.com", "phoneNumber": { "code": 46, "number": "987654321" }, "address": { "careOf": "Jane Doe", "addressLine1": "Second Street 456", "city": "Stockholm", "countryCode": "SE", "postalCode": "123 46" }, "onlineInfo": { "merchantWebshopURL": "https://merchant-shop.com", "paymentPageHostURL": "https://payments.merchant-shop.com", "termsAndConditionsURL": "https://merchant-shop.com/terms", "privacyPolicyURL": "https://merchant-shop.com/privacy" } } } } ``` ### Response #### Success Response (200) - **applicationId** (string) - A unique identifier for the merchant application. - **webKybUrl** (string) - The URL that the merchant needs to visit to complete their application (KYB process). #### Response Example ```json { "applicationId": "app_12345abcde", "webKybUrl": "https://kyb.surfboardpayments.com/start?token=abcdef12345" } ``` ``` -------------------------------- ### Initiate Payment via API Call (Bash) Source: https://developers.surfboardpayments.com/guides/online-payments/integrations/api-architecture This example demonstrates how to initiate a payment using a cURL command. It requires specifying order details, payment method, and authentication credentials in the request headers. ```bash curl -d '{ "orderId": "o_RelSnor1A6gqgKzZxrbM7", "paymentMethod": "CARD" }' -H 'Content-Type: application/json' -H 'API-KEY: YOUR_API_KEY' -H 'API-SECRET: YOUR_API_SECRET' -H 'MERCHANT-ID: MERCHANT_ID' YOUR_API_URL/payments ``` -------------------------------- ### Create Merchant API Request (cURL) Source: https://developers.surfboardpayments.com/guides/online-payments/create-merchant-and-store-setup/create-merchant-and-store-setup This cURL command demonstrates how to create a new merchant account using the Create Merchant API. It includes essential parameters for merchant details, organization information, and online store configuration. Ensure you replace placeholders like YOUR_API_KEY, YOUR_API_SECRET, and YOUR_API_URL with your actual credentials and endpoint. ```curl curl -d \ {\ "country": "SE",\ "organisation": {\ "corporateId": "1234567890",\ "legalName": "Legal Name",\ "mccCode": "5192",\ "address": {\ "careOf": "John Doe",\ "addressLine1": "Main Street 123",\ "addressLine2": "Building C",\ "city": "Stockholm",\ "countryCode": "SE",\ "postalCode": "123 45"\ },\ "phone": {\ "code": 46,\ "number": "123456789"\ },\ "email": "contact@test.com"\ },\ "acquirerMID": "PF123456",\ "multiMerchantId": "8132483499c658050e",\ "controlFields": {\ "displayProducts": [\ ``` -------------------------------- ### GET /transactions - Pagination Example Source: https://developers.surfboardpayments.com/guides/in-store-payments/integrations/pagination This section demonstrates how to retrieve paginated transaction data using the Surfboard Payments API. It includes examples of request headers and the expected response structure for both successful data retrieval and requests for non-existent pages. ```APIDOC ## GET /transactions ### Description Retrieves a paginated list of transactions. The API defaults to page-based pagination, sorting results from newer to older. ### Method GET ### Endpoint `/transactions` ### Parameters #### Query Parameters - **page** (integer) - Optional - The page number to retrieve. Defaults to the first page if not specified. #### Request Headers - **API-KEY** (string) - Required - Your API key for authentication. - **API-SECRET** (string) - Required - Your API secret for authentication. - **MERCHANT-ID** (string) - Required - The ID of the merchant. - **X-PAGE-NUMBER** (integer) - Optional - Specifies the desired page number for the request. If omitted, the first page is returned. ### Request Example ```bash curl YOUR_API_URL/transactions \ -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ -H 'API-SECRET: YOUR_API_SECRET' \ -H 'MERCHANT-ID: YOUR_MERCHANT_ID' \ -H 'X-PAGE-NUMBER: 2' ``` ### Response #### Success Response (200) - **status** (string) - The status of the request (e.g., "SUCCESS"). - **data** (array) - An array of transaction objects. The page size is maintained at 100 items. - **message** (string) - A message indicating the outcome of the request. - **X-TOTAL-ITEMS** (integer, Header) - The total number of available items across all pages. - **X-PAGE-NUMBER** (integer, Header) - The current page number returned. #### Response Example (Data Found) ```json { "status": "SUCCESS", "data": [ {...}, {...}, {...} ], "message": "Fetched transactions" } ``` #### Response Example (Page Not Found) ```json { "status": "SUCCESS", "data": [], "message": "No transactions available in the specified page" } ``` #### Headers Example (Success) ``` HTTP/2 200 access-control-allow-origin: * ... content-type: application/json; charset=utf-8 ... x-page-number: 2 x-total-items: 230 ``` #### Headers Example (Page Not Found) ``` HTTP/2 200 access-control-allow-origin: * ... content-type: application/json; charset=utf-8 ... x-page-number: 4 x-total-items: 230 ``` ``` -------------------------------- ### Create Merchant Charge API Examples Source: https://developers.surfboardpayments.com/api/billing Examples for creating a merchant charge via the API. Supports cURL and common backend languages. Includes parameters for charge description, currency, amount, VAT, billing date, and recurring settings. ```curl curl -X POST \ -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ -H 'API-SECRET: YOUR_API_SECRET' \ -H 'MERCHANT-ID: YOUR_MERCHANT_ID' \ -d '{ "description": "Fee", "currency": "752", "amount": 5000000, "vat": 35, "billingDate": "2025-02-11", "recurring": { "billingEndDate": "2025-02-12", "frequency": "daily" } }' \ 'YOUR_API_URL//partners/:partnerId/merchants/:merchantId/charges' ``` -------------------------------- ### Fetch All Merchant Charges API Examples Source: https://developers.surfboardpayments.com/api/billing Examples for retrieving a list of all merchant charges associated with a merchant. Supports cURL and various backend languages. This endpoint facilitates paginated retrieval of charge data. ```curl curl -X GET \ -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ -H 'API-SECRET: YOUR_API_SECRET' \ 'YOUR_API_URL//partners/:partnerId/merchants/:merchantId/charges' ``` -------------------------------- ### Register Terminal API Source: https://developers.surfboardpayments.com/guides/in-store-payments/administration/setup-multi-merchant-terminals API to register a physical terminal to a multi-merchant group, making it ready to accept payments. ```APIDOC ## POST /partners/:partnerId/terminals ### Description Registers a physical terminal to a multi-merchant group, associating it with a specific store. ### Method POST ### Endpoint `/partners/:partnerId/terminals` ### Parameters #### Path Parameters - **partnerId** (string) - Required - The unique identifier for the partner. #### Request Body - **registrationId** (string) - Required - The 6-digit registration code from the terminal display or the terminal's serial number (if SurfPad). - **storeId** (string) - Required - The unique identifier for the store where the terminal will be used. ### Request Example ```json { "registrationId": "123456", "storeId": "store123" } ``` ### Response #### Success Response (200) - **terminalId** (string) - The unique identifier for the registered terminal. - **status** (string) - The current status of the terminal registration (e.g., "registered"). #### Response Example ```json { "terminalId": "term789", "status": "registered" } ``` ``` -------------------------------- ### Create Merchant API Source: https://developers.surfboardpayments.com/guides/in-store-payments/administration/setup-multi-merchant-terminals API to add a new merchant to an existing multi-merchant group. The merchant must complete an onboarding application. ```APIDOC ## POST /partners/:partnerId/merchants ### Description Adds a merchant to a multi-merchant group and initiates their onboarding process. The merchant must complete the `webKYB` application. ### Method POST ### Endpoint `/partners/:partnerId/merchants` ### Parameters #### Path Parameters - **partnerId** (string) - Required - The unique identifier for the partner. #### Request Body - **country** (string) - Required - The country code for the merchant. - **organisation** (object) - Required - Details of the merchant's organization. - **corporateId** (string) - Required - The organization's corporate ID. - **legalName** (string) - Required - The legal name of the organization. - **mccCode** (string) - Required - The Merchant Category Code. - **address** (object) - Required - The organization's address. - **careOf** (string) - Optional - Attention to. - **addressLine1** (string) - Required - First line of the address. - **addressLine2** (string) - Optional - Second line of the address. - **city** (string) - Required - The city. - **countryCode** (string) - Required - The country code. - **postalCode** (string) - Required - The postal code. - **phone** (object) - Required - The organization's phone number. - **code** (integer) - Required - The country calling code. - **number** (string) - Required - The phone number. - **email** (string) - Required - The organization's email address. - **acquirerMID** (string) - Required - The acquirer Merchant ID. - **multiMerchantId** (string) - Required - The ID of the multi-merchant group to link to. - **controlFields** (object) - Optional - Fields to control product display and selection. - **displayProducts** (array) - Optional - List of products to display. - **productId** (string) - Required - The product ID. - **pricingPlans** (array) - Required - List of pricing plan IDs. - **showProductCatalogue** (boolean) - Optional - Whether to show the product catalogue. - **transactionPricingPlan** (string) - Optional - The default transaction pricing plan ID. - **preSelectProducts** (array) - Optional - List of products to pre-select. - **productId** (string) - Required - The product ID. - **quantity** (integer) - Required - The quantity. - **pricingPlanId** (string) - Required - The pricing plan ID. - **store** (object) - Required - Details of the store. - **name** (string) - Required - The store name. - **email** (string) - Required - The store email address. - **phoneNumber** (object) - Required - The store phone number. - **code** (integer) - Required - The country calling code. - **number** (string) - Required - The phone number. - **address** (object) - Required - The store address. - **careOf** (string) - Optional - Attention to. - **addressLine1** (string) - Required - First line of the address. - **city** (string) - Required - The city. - **countryCode** (string) - Required - The country code. - **postalCode** (string) - Required - The postal code. ### Request Example ```json { "country": "SE", "organisation": { "corporateId": "12345678901", "legalName": "Legal Name", "mccCode": "5192", "address": { "careOf": "John Doe", "addressLine1": "Main Street 123", "addressLine2": "Building C", "city": "Stockholm", "countryCode": "SE", "postalCode": "123 45" }, "phone": { "code": 46, "number": "123456789" }, "email": "contact@test.com" }, "acquirerMID": "PF123456", "multiMerchantId": "8132483499c658050e", "controlFields": { "displayProducts": [ { "productId": "815db2c5adc9b00301", "pricingPlans": ["816192c7efa2b0091a"] } ], "showProductCatalogue": true, "transactionPricingPlan": "816192c7efa2b0091a", "preSelectProducts": [ { "productId": "815db2c5adc9b00301", "quantity": 2, "pricingPlanId": "816192c7efa2b0091a" } ], "store": { "name": "Test Store", "email": "test@test.com", "phoneNumber": { "code": 46, "number": "987654321" }, "address": { "careOf": "Jane Doe", "addressLine1": "Second Street 456", "city": "Stockholm", "countryCode": "SE", "postalCode": "123 46" } } } } ``` ### Response #### Success Response (200) - **applicationId** (string) - Unique identifier for the merchant's application. - **webKYB** (string) - URL for the merchant onboarding application. #### Response Example ```json { "applicationId": "app456", "webKYB": "https://onboarding.example.com/kyb/app456" } ``` ``` -------------------------------- ### Stores API - New Parameters Source: https://developers.surfboardpayments.com/console/changelogs New response parameters added to Stores APIs for online payment setup. ```APIDOC ## Stores API - New Parameters ### Description New response parameters have been added to various Store endpoints to facilitate online payment setup. ### Method POST (Create Store), PUT (Update Store Details), GET (Fetch Store Details, Fetch Stores) ### Endpoint - `/stores` - `/stores/{storeId}` ### Parameters #### Response Parameters - `merchantWebShopUrl` (string) - The web-shop URL of the merchant. - `paymentPageHostURL` (string) - The URL of the payment page. - `termsAndConditionsURL` (string) - URL of the merchant's T&C, including refund policy. - `privacyPolicyURL` (string) - URL of the merchant's privacy policy. ### Response Example ```json { "storeId": "store_123", "merchantWebShopUrl": "https://merchant.com/shop", "paymentPageHostURL": "https://pay.surfboard.com/pay", "termsAndConditionsURL": "https://merchant.com/terms", "privacyPolicyURL": "https://merchant.com/privacy" } ``` ``` -------------------------------- ### Create Multi-Merchant Group API Source: https://developers.surfboardpayments.com/guides/in-store-payments/administration/setup-multi-merchant-terminals API to create a multi-merchant group, which serves as a container for multiple merchants sharing a single terminal. ```APIDOC ## POST /partners/:partnerId/multi-merchant ### Description Creates a multi-merchant group, allowing multiple merchants to use the same terminal for accepting payments within a designated store. ### Method POST ### Endpoint `/partners/:partnerId/multi-merchant` ### Parameters #### Path Parameters - **partnerId** (string) - Required - The unique identifier for the partner. #### Request Body - **country** (string) - Required - The country code for the merchant (e.g., "SE"). - **zipCode** (string) - Required - The postal code for the merchant. ### Request Example ```json { "country": "SE", "zipCode": "123456" } ``` ### Response #### Success Response (200) - **applicationId** (string) - Unique identifier for the application. - **merchantId** (string) - Unique identifier for the multi-merchant group. - **storeId** (string) - Unique identifier for the multi-merchant store. #### Response Example ```json { "applicationId": "app123", "merchantId": "multiMerchant123", "storeId": "store123" } ``` ``` -------------------------------- ### Get Interapp Details (cURL) Source: https://developers.surfboardpayments.com/api/terminals Fetches the current status of an interapp registration using a provided interapp code. The cURL example shows the GET request with all necessary identifiers. ```shell curl -X GET \ -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ -H 'API-SECRET: YOUR_API_SECRET' \ -H 'MERCHANT-ID: YOUR_MERCHANT_ID' \ 'YOUR_API_URL//merchants/merchantId/stores/:storeId/terminals/interapp/:interappcode' ``` -------------------------------- ### Check Order Status via API (GET) Source: https://developers.surfboardpayments.com/guides/in-store-payments/administration/accept-partial-payments Fetches the current status of an order using a GET request to the Fetch Order Status API. Requires the orderId. The response includes the orderStatus, which can be one of several states: PENDING, PAYMENT_INITIATED, PAYMENT_PROCESSED, PAYMENT_CANCELLED, PARTIAL_PAYMENT_COMPLETED, PAYMENT_COMPLETED. ```get GET YOUR_API_URL/orders/{orderId}/status ``` -------------------------------- ### Create Merchant API Source: https://developers.surfboardpayments.com/guides/in-store-payments/create-merchant-and-store-setup/home Initiates the merchant onboarding process by creating a merchant application and generating a unique onboarding URL. ```APIDOC ## POST /partners/:partnerId/merchants ### Description Creates a new merchant application and returns a unique `webKybUrl` for the merchant to complete their onboarding. ### Method POST ### Endpoint `/partners/:partnerId/merchants` ### Parameters #### Path Parameters - **partnerId** (string) - Required - Your partner identifier. #### Query Parameters None #### Request Body - **country** (string) - Required - Two-letter ISO country code of the merchant (e.g., 'SE', 'DK'). - **organisation** (object) - Required - Contains details about the merchant's organization. - **corporateId** (string) - Required - The organization's corporate ID. - **legalName** (string) - Required - The legal name of the organization. - **mccCode** (string) - Required - Merchant Category Code. - **address** (object) - Required - Organization's address details. - **careOf** (string) - Optional - Care of information. - **addressLine1** (string) - Required - First line of the address. - **addressLine2** (string) - Optional - Second line of the address. - **city** (string) - Required - The city. - **countryCode** (string) - Required - Two-letter ISO country code. - **postalCode** (string) - Required - The postal code. - **phone** (object) - Required - Organization's phone number. - **code** (integer) - Required - Country calling code. - **number** (string) - Required - Phone number. - **email** (string) - Required - Contact email address. - **acquirerMID** (string) - Optional - Acquirer Merchant ID. - **multiMerchantId** (string) - Optional - Multi-merchant identifier. - **controlFields** (object) - Optional - Fields to control the merchant application experience. - **displayProducts** (array) - Optional - List of products to display. - **productId** (string) - Required - Product ID. - **pricingPlans** (array) - Required - List of pricing plan IDs. - **showProductCatalogue** (boolean) - Optional - Whether to show the product catalogue. - **transactionPricingPlan** (string) - Optional - Default transaction pricing plan ID. - **preSelectProducts** (array) - Optional - List of products to pre-select. - **productId** (string) - Required - Product ID. - **quantity** (integer) - Required - Quantity. - **pricingPlanId** (string) - Required - Pricing plan ID. - **store** (object) - Optional - Store information to pre-fill. - **name** (string) - Required - Store name. - **email** (string) - Required - Store email. - **phoneNumber** (object) - Required - Store phone number. - **code** (integer) - Required - Country calling code. - **number** (string) - Required - Phone number. - **address** (object) - Required - Store address. - **careOf** (string) - Optional - Care of information. - **addressLine1** (string) - Required - First line of the address. - **city** (string) - Required - The city. - **countryCode** (string) - Required - Two-letter ISO country code. - **postalCode** (string) - Required - The postal code. ### Request Example ```json { "country": "SE", "organisation": { "corporateId": "12345678901", "legalName": "Legal Name", "mccCode": "5192", "address": { "careOf": "John Doe", "addressLine1": "Main Street 123", "addressLine2": "Building C", "city": "Stockholm", "countryCode": "SE", "postalCode": "123 45" }, "phone": { "code": 46, "number": "123456789" }, "email": "contact@test.com" }, "acquirerMID": "PF123456", "multiMerchantId": "8132483499c658050e", "controlFields": { "displayProducts": [ { "productId": "815db2c5adc9b00301", "pricingPlans": ["816192c7efa2b0091a"] } ], "showProductCatalogue": true, "transactionPricingPlan": "816192c7efa2b0091a", "preSelectProducts": [ { "productId": "815db2c5adc9b00301", "quantity": 2, "pricingPlanId": "816192c7efa2b0091a" } ], "store": { "name": "Test Store", "email": "test@test.com", "phoneNumber": { "code": 46, "number": "987654321" }, "address": { "careOf": "Jane Doe", "addressLine1": "Second Street 456", "city": "Stockholm", "countryCode": "SE", "postalCode": "123 46" } } } } ``` ### Response #### Success Response (200) - **applicationId** (string) - The unique identifier for the merchant application. - **webKybUrl** (string) - The URL for the merchant to complete their onboarding. #### Response Example ```json { "applicationId": "app_12345", "webKybUrl": "https://onboarding.surfboardpayments.com/kyb?token=abcde12345" } ``` ``` -------------------------------- ### Environments Overview Source: https://developers.surfboardpayments.com/guides/in-store-payments/integrations/api Surfboard provides two key environments: the Demo Environment for testing and development, and the Live Environment for processing real transactions. ```APIDOC ## Environments Overview Surfboard provides two key environments: * **Demo Environment**: For testing and development without affecting real transactions. Supports test cards and online integrations. * **Live Environment**: For processing real payments. Requires certification and provides live API credentials for actual transactions and payouts. ### Environment Comparison | Environment | Supported Terminals | Cards Supported | |---|---|---| | Demo | All hardware terminals, Surfboard Tester App, CheckoutX(mobile) | Live cards can be tested in hardware terminals. (Only inbuilt test cards can be used in Surfboard tester app) | | Live | All hardware terminals, CheckoutX(mobile) | Live cards can be used. Transactions will be settled, and you'll receive payouts. | ``` -------------------------------- ### Environments Overview Source: https://developers.surfboardpayments.com/guides/online-payments/integrations/apis-and-environments Surfboard provides two key environments: Demo and Live. The Demo environment is for testing integrations with test cards, while the Live environment is for processing real transactions and requires certification. ```APIDOC ## Environments Overview Surfboard provides two key environments: ### Demo Environment * **Purpose:** Testing and development without affecting real transactions. * **Terminals Supported:** Payment page mode. * **Cards Supported:** Only test cards. * **Features:** Use test cards, test online integrations with APIs and SDKs. * **Important Note:** Transactions made with real cards in the demo environment are voided after 30 minutes. ### Live Environment * **Purpose:** Processing live payments. * **Access:** Provided after Surfboard certifies your integration. * **Terminals Supported:** All online terminals. * **Cards Supported:** Live cards. * **Features:** Create orders, perform live transactions, display receipts, branding, etc. * **Requirements:** Obtain new API credentials, update URLs, and replace API keys/secrets. ``` -------------------------------- ### Fetch Transactions by ID - cURL Example Source: https://developers.surfboardpayments.com/guides/in-store-payments/post-payments/manage-your-transactions/fetch-transactions-by-id This snippet demonstrates how to make a GET request to the Fetch Transactions by ID endpoint using cURL. It includes necessary headers for authentication and specifies the endpoint URL with a placeholder for the transaction ID. ```curl curl -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ -H 'API-SECRET: YOUR_API_SECRET' \ -H 'MERCHANT-ID: YOUR_MERCHANT_ID' \ YOUR_API_URL/transactions/{{id}}/list ``` -------------------------------- ### Fetch Store Terminal Config (cURL) Source: https://developers.surfboardpayments.com/api/terminals Retrieves all currently active terminal configurations for a specific store within a merchant. The cURL example shows the required GET request parameters and headers. ```shell curl -X GET \ -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ -H 'API-SECRET: YOUR_API_SECRET' \ -H 'MERCHANT-ID: YOUR_MERCHANT_ID' \ 'YOUR_API_URL//merchants/:merchantId/stores/:storeId/terminals/config' ``` -------------------------------- ### Initialize Surfboard Online SDK and Set Callbacks Source: https://developers.surfboardpayments.com/guides/online-payments/online-payment-terminals/online-sdk-guide This snippet demonstrates how to initialize the Surfboard Online SDK with public key, order ID, and nonce. It also shows how to set up error and payment status callback functions to handle real-time feedback during the payment process. The `remountOnlineSDK` function is included for re-initializing the SDK for new orders. ```javascript SurfboardOnlineSDK.errorCallback((code, message) => { console.log("Entered the callback here"); console.error(code, message); }); SurfboardOnlineSDK.paymentStatusCallback = function (data) { // Your payment status handling function here // structure of data //{ // paymentStatus: 'PAYMENT_INITIATED'|'PAYMENT_CANCELLED' | 'PAYMENT_COMPLETED' | 'PAYMENT_FAILED' | 'PAYMENT_PROCESSING' | 'PAYMENT_PROCESSED', // failureReason? : string // } }; SurfboardOnlineSDK.initialiseOnlineSDK({ publicKey: "", //Your public key orderId: "", //Include the orderId nonce: "", //Include the nonce }); SurfboardOnlineSDK.remountOnlineSDK({ publicKey: "", // Your public key orderId: "", // New orderId nonce: "", // New nonce }); ``` -------------------------------- ### Initiate Klarna Payment with Customer Information Source: https://developers.surfboardpayments.com/guides/online-payments/online-payment-terminals/online-sdk-guide Example of how to add customer information and initiate a Klarna payment using the SurfboardOnlineSDK. This involves providing customer details like phone, name, email, and billing address before calling initiatePayments with 'KLARNA'. ```JSX SurfboardOnlineSDK.order.addCustomerInformation({ phone: { countryCode: "+46", number: "701740615" }, name: "customer name", email: "customer@email.se", billingAddress: { city: "Stockholm", postalCode: "60320", countryCode: "SE", addressLine1: "16th Süxtreet", }, }); SurfboardOnlineSDK.order.initiatePayments("KLARNA"); ``` -------------------------------- ### Fetch Store Tips Configuration Source: https://developers.surfboardpayments.com/guides/in-store-payments/administration/configure-tips/configure-tips Retrieves the tip configuration details for all terminals registered to a specific store. ```APIDOC ## GET /stores/{storeId}/tips ### Description Fetches the current tip configuration settings for all terminals associated with a specified store. This allows partners to view tip settings at the store level. ### Method GET ### Endpoint `/stores/{storeId}/tips` ### Parameters #### Path Parameters - **storeId** (string) - Required - The unique identifier for the store whose tip configurations are to be fetched. ### Response #### Success Response (200) - **storeId** (string) - The identifier of the store. - **terminals** (array) - A list of tip configurations for each terminal registered to the store. - **terminalId** (string) - The identifier of the terminal. - **tipConfig** (object) - The tip configuration for the terminal. - **tipLevel1** (integer) - The first preset tip percentage. - **tipLevel2** (integer) - The second preset tip percentage. - **tipLevel3** (integer) - The third preset tip percentage. - **defaultCustomAmount** (number) - The default custom tip amount. - **displayCalculatedAmount** (string) - Whether the calculated tip amount is displayed (`ENABLED` or `DISABLED`). - **tipDisplayFormat** (string) - The format used for displaying tips (`PERCENTAGE` or `AMOUNT`). #### Response Example ```json { "storeId": "STORE001", "terminals": [ { "terminalId": "TERMABC", "tipConfig": { "tipLevel1": 5, "tipLevel2": 10, "defaultCustomAmount": 3.00, "tipDisplayFormat": "PERCENTAGE" } } ] } ``` ``` -------------------------------- ### Fetch Terminal Tips Configuration Source: https://developers.surfboardpayments.com/guides/in-store-payments/administration/configure-tips/configure-tips Retrieves the tip configuration details set at the individual terminal level. ```APIDOC ## GET /terminals/{terminalId}/tips ### Description Fetches the specific tip configuration settings applied directly to an individual terminal. This is useful for understanding the exact tip preferences for a particular device. ### Method GET ### Endpoint `/terminals/{terminalId}/tips` ### Parameters #### Path Parameters - **terminalId** (string) - Required - The unique identifier for the terminal whose tip configuration is to be fetched. ### Response #### Success Response (200) - **terminalId** (string) - The identifier of the terminal. - **tipConfig** (object) - The tip configuration for the terminal. - **tipLevel1** (integer) - The first preset tip percentage. - **tipLevel2** (integer) - The second preset tip percentage. - **tipLevel3** (integer) - The third preset tip percentage. - **defaultCustomAmount** (number) - The default custom tip amount. - **displayCalculatedAmount** (string) - Whether the calculated tip amount is displayed (`ENABLED` or `DISABLED`). - **tipDisplayFormat** (string) - The format used for displaying tips (`PERCENTAGE` or `AMOUNT`). #### Response Example ```json { "terminalId": "TERMXYZ", "tipConfig": { "tipLevel1": 15, "displayCalculatedAmount": "ENABLED", "tipDisplayFormat": "AMOUNT" } } ``` ``` -------------------------------- ### Terminals API - Get Interapp Code Source: https://developers.surfboardpayments.com/console/changelogs Addition of the Get Interapp Code endpoint to the Terminals API. ```APIDOC ## Terminals API - Get Interapp Code ### Description This new endpoint retrieves the interapp code for a given terminal. ### Method GET ### Endpoint /terminals/{terminalId}/interapp-code ### Parameters #### Path Parameters - `terminalId` (string) - Required - The ID of the terminal. ### Response #### Success Response (200) - `interappCode` (string) - The interapp code for the terminal. ``` -------------------------------- ### API - New API in Terminal APIs - Get Interapp Details Source: https://developers.surfboardpayments.com/console/changelogs New endpoint to get interapp details in Terminal APIs. ```APIDOC ## API - New API in Terminal APIs - Get Interapp Details ### Description Added **Get Interapp Details** in Terminal APIs. ### Method GET ### Endpoint /api/v1/terminals/interapp/details ### Parameters N/A ### Request Example ```http GET /api/v1/terminals/interapp/details ``` ### Response #### Success Response (200) - **interappDetails** (object) - Details related to interapp communication. #### Response Example ```json { "interappDetails": { "sdkVersion": "1.2.3", "connectionStatus": "connected" } } ``` ``` -------------------------------- ### Set Store Tips Configuration Source: https://developers.surfboardpayments.com/guides/in-store-payments/administration/configure-tips/configure-tips Allows partners to set tip configurations for a specific store. This involves sending a PATCH request with optional tip configuration parameters. ```APIDOC ## PATCH /stores/{storeId}/tips ### Description Configures tip settings for a specific store. This endpoint allows for customization of preset tip amounts, default custom amounts, display formats, and whether calculated amounts are shown. ### Method PATCH ### Endpoint `/stores/{storeId}/tips` ### Parameters #### Path Parameters - **storeId** (string) - Required - The unique identifier for the store. #### Request Body - **tipConfig** (object) - Optional - Contains the tip configuration settings. - **tipLevel1** (integer) - Optional - The first preset tip percentage (e.g., 5). - **tipLevel2** (integer) - Optional - The second preset tip percentage (e.g., 10). - **tipLevel3** (integer) - Optional - The third preset tip percentage (e.g., 15). - **defaultCustomAmount** (number) - Optional - A default custom tip amount to be pre-filled. - **displayCalculatedAmount** (string) - Optional - Controls whether the calculated tip amount is displayed. Values: `ENABLED` or `DISABLED`. - **tipDisplayFormat** (string) - Optional - The format for displaying tips. Values: `PERCENTAGE` or `AMOUNT`. ### Request Example ```json { "tipConfig": { "tipLevel1": 7, "tipLevel2": 12, "tipDisplayFormat": "PERCENTAGE" } } ``` ### Response #### Success Response (200) - **message** (string) - Confirms the tip configuration has been updated for the store. ``` -------------------------------- ### Initialize Surfboard SDK and Mount Widgets Source: https://developers.surfboardpayments.com/guides/online-payments/online-payment-terminals/online-sdk-guide Initializes the Surfboard Online SDK with provided keys and mounts various payment widgets (Card, Apple Pay, Google Pay, Klarna) to specified DOM elements. It retrieves the nonce from URL parameters and logs the order ID and nonce. ```javascript const nonce = urlParams.get('n') || urlParams.get('pi'); console.log({ orderId, nonce }); // Fetch Surfboard SDK fetchSurfboardSDK(); // Initialize Surfboard Online SDK SurfboardOnlineSDK.initialiseOnlineSDK({ // TODO: Replace with your terminal's public key publicKey: '{{PUBLIC_KEY}}', orderId: orderId, nonce: nonce, }).then(() => { // Uncomment the following line to change locale if needed // SurfboardOnlineSDK.changeLocale('sv'); SurfboardOnlineSDK.mount({ mountCardWidget: 'card-details', mountApplePayWidget: 'apple-pay', mountGooglePayWidget: 'google-pay', mountKlarnaWidget: 'klarna', }); }); ```