# Surfboard Payments API > Secure and certified API-Centric Payments Platform for software companies. Easy to implement, easy to use. At Surfboard Payments, we empower developers to transform any software into a fully integrated payment solution. With our easy-to-use APIs, detailed documentation, and robust SDKs, you can quickly and efficiently implement both in-person and online payment capabilities tailored to your needs. ## In-Store Payments - [Overview](https://ai.developers.surfboardpayments.com/guides/in-store-payments/overview.md): Surfboard Payments offers in-store (hardware, softPOS) & online payment solutions, with integration via API/SDKs. Create a developer account, test, then go live - [How to guides](https://ai.developers.surfboardpayments.com/guides/in-store-payments/how-to-guides/home.md): Guides on implementing in-store payment flow from onboarding to accepting payments and other post payment functionalities. - [home](https://ai.developers.surfboardpayments.com/guides/in-store-payments/onboarding/home.md): Surfboard Payments onboards merchants via KYB checks, verifying business details, owners, signatories & PEPs. Partners use a portal/link or API for merchant onboarding. - [Create Merchant](https://ai.developers.surfboardpayments.com/guides/in-store-payments/onboarding/create-merchant.md): Partners can onboard merchants to Surfboard via a Create Merchant API, generating a KYB URL for merchant details, then track status via the Check Application Status - [Setup Store](https://ai.developers.surfboardpayments.com/guides/in-store-payments/onboarding/setup-store.md): Merchants/Partners can create & manage physical stores via the Create Store API, linking them to a Merchant ID. Requires store details, returns a unique Store Id - [home](https://ai.developers.surfboardpayments.com/guides/in-store-payments/terminals/home.md): Surfboard Payments offers API/SDK-integrated payment terminals (SurfPad, SurfTouch, SurfPrint, SoftPOS) with flexible connectivity, supporting diverse payment m - [Order terminals](https://ai.developers.surfboardpayments.com/guides/in-store-payments/terminals/order-terminals.md): Partners can manage Surfboard terminal orders/shipments for merchants during onboarding or via API, including returns, using product/order IDs. - [Terminal registration](https://ai.developers.surfboardpayments.com/guides/in-store-payments/terminals/terminal-registration.md): Guide for partners on registering merchant payment terminals to Surfboard stores via the Register Terminal API using a `registrationId` & `storeId` to get a `terminalId` - [Configure terminals](https://ai.developers.surfboardpayments.com/guides/in-store-payments/terminals/setup-terminal-configuration.md): Configure terminal settings (WiFi, language, auto-sleep, etc.) at Partner, Merchant, Store, or Terminal levels via API or partner portal, with hierarchical overrides. - [Manage terminals integrated with your checkout system](https://ai.developers.surfboardpayments.com/guides/in-store-payments/terminals/manage-terminal.md): Manage checkout-integrated terminals: register, change/delink stores, reboot, update name, and link/delink/check status with CheckoutPro via API or Merchant Portal - [home](https://ai.developers.surfboardpayments.com/guides/in-store-payments/accept-payments/home.md): Surfboard lets merchants accept in-store payments (Card, Swish, Klarna) via terminals which involves create order, initiate payment, & fetch order status. - [Create order](https://ai.developers.surfboardpayments.com/guides/in-store-payments/accept-payments/create-order.md): Create orders (via POST request) against a registered terminal ID. Includes item, customer, and control details. `orderId` is essential for payment processing. - [Initiate a payment](https://ai.developers.surfboardpayments.com/guides/in-store-payments/accept-payments/initiate-payment.md): Initiate payments for an order (using orderId) via the Initiate Payment API, specifying paymentMethod (CARD, KLARNA, SWISH), amount, and get a `paymentId` which is used to get information about the payment. - [Check payment status](https://ai.developers.surfboardpayments.com/guides/in-store-payments/accept-payments/check-payment-status.md): Merchants can check payment status (initiated, processing, completed, failed, or canceled) via API using `paymentId`, or use webhooks for real-time updates. - [Fetch order status](https://ai.developers.surfboardpayments.com/guides/in-store-payments/accept-payments/fetch-order-status.md): Use the Fetch Order Status API with an `orderId` to retrieve order status (PENDING, PAYMENT_COMPLETED/CANCELLED, PARTIAL_PAYMENT_COMPLETED). You can also get the updates via webhooks. - [Accept partial payments](https://ai.developers.surfboardpayments.com/guides/in-store-payments/accept-payments/accept-partial-payments.md): API enables partial payments for orders, allowing smaller, separate payments via various methods. Create/update orders, initiate payments, check payment status, & return/refund an order. - [Return/Refund an Order](https://ai.developers.surfboardpayments.com/guides/in-store-payments/post-payments/return-refund.md): Process order returns/refunds via refund API: Create a 'return' order, get a new orderId, initiate a refund payment (full or partial), and check status. - [Fetch payment information by ID](https://ai.developers.surfboardpayments.com/guides/in-store-payments/post-payments/manage-your-payments/fetch-payment.md): API retrieves payment details (status, IDs, amount, method, etc.) using a `paymentId`. Receipts can be generated from the response. - [Cancel a payments](https://ai.developers.surfboardpayments.com/guides/in-store-payments/post-payments/manage-your-payments/cancel-payment.md): Payments can be cancelled via API before completion using paymentId; after completion, they must be voided. Status is returned in paymentStatus. - [Void a payment](https://ai.developers.surfboardpayments.com/guides/in-store-payments/post-payments/manage-your-payments/void-payment.md): API enables voiding (undoing) initiated payments before 23:00 UTC via a PUT request with `paymentId`, returning `voidStatus` (INITIATED, CANNOT_VOID, VOIDED). - [Fetch Transactions by ID](https://ai.developers.surfboardpayments.com/guides/in-store-payments/post-payments/manage-your-transactions/fetch-transactions-by-id.md): API endpoint retrieves transaction details by order, transaction, or payment ID; useful for handling multiple payments within a single order. - [Fetch information about all transactions](https://ai.developers.surfboardpayments.com/guides/in-store-payments/post-payments/manage-your-transactions/fetch-all-transactions.md): API endpoint to fetch all transactions for a merchant, filterable by date range, providing detailed transaction attributes like ID, amount, status, and method. - [Fetch transaction by search](https://ai.developers.surfboardpayments.com/guides/in-store-payments/post-payments/manage-your-transactions/fetch-transaction-search.md): API allows partners to search transaction data via a `POST` request with a `query` parameter (e.g., orderId, amount). Returns matching transaction details. - [Fetch settlement reports](https://ai.developers.surfboardpayments.com/guides/in-store-payments/post-payments/fetch-settlement-reports.md): Surfboard Payments API allows fetching merchant settlement reports (daily/monthly) using `partnerId` & `merchantId`, detailing transactions, fees, & payouts. - [Manage your merchants](https://ai.developers.surfboardpayments.com/guides/in-store-payments/administration/manage-merchants.md): Partners can manage merchants via a portal/API: create/view merchant groups, fetch merchant/contract/terminal details, & update merchant info. - [Setup Multi merchant terminals](https://ai.developers.surfboardpayments.com/guides/in-store-payments/administration/setup-multi-merchant-terminals.md): Multi-merchant terminals allow multiple businesses to process payments on one device. Setup involves creating a group, adding merchants via API, and registering multi merchant terminal. - [Customer Identification on Card Tap](https://ai.developers.surfboardpayments.com/guides/in-store-payments/administration/customer-identification.md): Surfboard enables customer ID via card tap on Android terminals, triggering a webhook with a card token for order updates & personalized offers before payment. - [Manage additional terminals](https://ai.developers.surfboardpayments.com/guides/in-store-payments/administration/manage-additional-terminals.md): Merchants can order, track, & return payment terminals/accessories via partner portals & APIs, managing shipments, & returns, using Create/Get Shipment/Return API. - [Configure tips](https://ai.developers.surfboardpayments.com/guides/in-store-payments/administration/configure-tips.md): Merchants/Partners can enable/disable tips, set preset tip percentages, and configure settings via API or partner/merchant portal at Partner, Merchant, Store, or Terminal level. - [Branding: In-store](https://ai.developers.surfboardpayments.com/guides/in-store-payments/administration/branding.md): Surfboard Payments enables in-store branding on payment terminals such as SurfPad, SurfTouch, SoftPOS via checkoutX, with customizable UI and API-configurable settings. - [Manage your reports](https://ai.developers.surfboardpayments.com/guides/in-store-payments/administration/manage-your-reports.md): Surfboard provides reporting via email, dashboard, & APIs, offering settlement details, customization, export (CSV, PDF), and scheduling. - [CheckoutX](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/prebuilt-apps/checkoutX.md): CheckoutX is an Android app (pre-built or SoftPOS) for contactless payments, transforming devices into PCI-certified terminals. API-driven, supports orders, refunds and ECR features. - [CheckoutX: Inter-app](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/prebuilt-apps/Inter-app.md): CheckoutX enables Android/iOS apps to integrate payment & tag scanning via bi-directional app switching, requiring terminal registration & specific URL schemes. - **Tools and Resources** - [Surfboard APIs](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/api.md): Surfboard APIs enable POS integration for managing orders & payments, offering documentation, and categorized API references for developers integrating our payment solutions. - [Integrate Surfboard APIs](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/integrate-api.md): Integrate Surfboard APIs using API-KEY/API-SECRET for authentication. Send JSON requests, handle JSON responses (status: SUCCESS/ERROR), and follow HTTP status. - [Environments](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/environments.md): Surfboard offers Demo (testing, voided transactions) & Live (real payments) environments for payment integration development and deployment. - [Client side tokens](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/client-side-tokens.md): Surfboard client-side tokens enable secure, direct API access (Orders, Payments, etc.) from clients without API keys, using bearer token authorization. - [Pagination](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/pagination.md): APIs use page-based pagination (100 items/page), sorted newest-oldest, using `X-PAGE-NUMBER` header. `x-total-items` in response header shows item count. - [SurfTouch](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/surftouch/home.md): SurfTouch is an Android payment terminal by Surfboard Payments, supporting various payment methods, offering CheckoutX (integrated) & SurfPay (standalone) modes - [Accept payments in CheckoutX mode](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/surftouch/payment-cx.md): In SurfTouch’s CheckoutX mode, your POS creates an order via API, and SurfTouch processes card payments (contactless or chip) and issues digital receipts. - [Accept tips in CheckoutX mode](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/surftouch/tips-cx.md): SurfTouch CheckoutX mode enables customers to add preset or custom tips during payment, configured via the Merchant Dashboard, enhancing payment flexibility. - [SurfPad](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/surfpad/home.md): SurfPad is a handheld payment terminal with card/contactless readers, API & app integration (CheckoutX/Pro), and WiFi/mobile connectivity. - [Initial setup](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/surfpad/initial-setup.md): For SurfPad setup, unbox it, power it on, connect to WiFi (code 6268) or mobile network (code 4760), troubleshoot connection errors, register it with the serial number, and restart. Tampering is prohibited to ensure security. - [Accept payments using SurfPad](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/surfpad/accept-payments.md): This guide details how to accept card payments (contactless and chip) using SurfPad, covering setup, order creation, and payment processing steps. - [Screens and special functions](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/surfpad/key-functions.md): SurfPad UI guide covers Status bar icons, Connection (9434 WiFi, 4760 Mobile, 6268 WiFi Select), Retry screens, & Info screen (1337, Cancel key to exit). - [Configure your SurfPad](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/surfpad/configure-surfpad.md): SurfPad configuration: Autosleep (battery saving), OTA updates (LED indicator), daily auto-restart (2 AM, configurable), and manual shutdown. - [Customize your SurfPad](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/surfpad/customize-surfpad.md): SurfPad customization: Change the logo (320x240px GIF, via email) and status bar (show/hide, colors via API or Merchant Dashboard). - [Error handling and troubleshooting](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/surfpad/error-handling.md): SurfPad troubleshooting guide: Identifies & resolves connection, card read, and payment errors with steps for Wi-Fi, card insertion, & retries. - [SurfTester: Integration tester app](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/surftester.md): SurfTester (Android) simulates payment integration, enabling devs to test terminal registration, orders, payments (with test cards & PIN), refunds, and app switch. - [Webhooks](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/webhooks.md): Surfboard webhooks provide real-time HTTP notifications for order, payment, logistics, & merchant events, with HMAC-SHA512 signatures & retries. - [Database connectivity](https://ai.developers.surfboardpayments.com/guides/in-store-payments/integrations/database-connectivity.md): Surfboard provides daily transaction & payout data dumps to any database for reporting & BI, suitable for high-volume merchants (>10k daily txs). ## Online Payments - [Overview](https://ai.developers.surfboardpayments.com/guides/online-payments/overview.md): Surfboard Payments offers in-store (terminal, CPOC) & online payment solutions, with developer onboarding via API key, demo environment, testing, and certificate. - [How to guides](https://ai.developers.surfboardpayments.com/guides/online-payments/how-to-guides/home.md): Guides on integrating online payment acceptance from onboarding to implementing payment flow and other post payment functionalities. - [home](https://ai.developers.surfboardpayments.com/guides/online-payments/onboarding/home.md): Online payment onboarding includes KYB, UBO, PEP checks, bank setup & online store configuration for secure integration, mirroring in-store processes with added steps. - [Create merchant](https://ai.developers.surfboardpayments.com/guides/online-payments/onboarding/create-merchant.md): Onboard merchants via WebKYB links which can be created via Create Merchant API or Partner Portal, with online store creation detailed. - [Setup online store](https://ai.developers.surfboardpayments.com/guides/online-payments/onboarding/online-store.md): This guide details creating/updating online stores via API that requires a merchantId, online-specific parameters, domain verification, and an approval process detailed. - [home](https://ai.developers.surfboardpayments.com/guides/online-payments/terminals/home.md): Surfboard's available online terminals (PaymentPage, SelfHostedPage, MerchantInitiated) integrate with web-shops for payment processing, mirroring in-store flows. - [**Terminals registration**](https://ai.developers.surfboardpayments.com/guides/online-payments/terminals/terminal-registration.md): Register online payment terminals (Payment Page, SDK, MerchantInitiated) via API POST request to `registerOnlineTerminal`, specifying type & storing the returned terminalId. - [home](https://ai.developers.surfboardpayments.com/guides/online-payments/online-payment-terminals/home.md): Integrate online payments after terminal registration using Payment Page, SDK, or Merchant-Initiated transactions. - [Payment page](https://ai.developers.surfboardpayments.com/guides/online-payments/online-payment-terminals/payment-page.md): Surfboard’s Payment Page supports online (CNP) payment acceptance via Customer Initiated Transaction/Merchant Initiated Transaction with the Create Order API, offering delayed capture, tokenization, and 3DSecure. - [Online SDK](https://ai.developers.surfboardpayments.com/guides/online-payments/online-payment-terminals/online-sdk-guide.md): Surfboard Online SDK enables customizable in-webshop payments, initialized with publicKey, orderId, & nonce. It supports card, Swish, Apple Pay, and Klarna payments. - [Merchant Initiated Transactions](https://ai.developers.surfboardpayments.com/guides/online-payments/online-payment-terminals/merchant-initiated-transactions.md): Merchant Initiated Transactions (MIT) allow merchants to process repeat payments by tokenizing card details after the customer’s initial payment via a registered Payment Page or Self-Hosted Page terminal, using API-driven requests. - [Delay capture](https://ai.developers.surfboardpayments.com/guides/online-payments/post-payments/delay-capture.md): Surfboard allows delayed payment capture via API. Set `delayCapture=true` on order creation, then use the Capture Payment API to finalize. - [Refunds](https://ai.developers.surfboardpayments.com/guides/online-payments/post-payments/refunds.md): Surfboard's API enables online (CNP) refunds via a two-step process: creating a 'return' order, then initiating a refund using the initiate payments endpoint with CARD_NP as payment method. - [Tokens](https://ai.developers.surfboardpayments.com/guides/online-payments/post-payments/tokens.md): Tokenization, enabled via `enforceTokenization`, secures card details for future (MIT) payments. you can retrieve `tokenId` after payment via the Tokens API. - [Void a payment](https://ai.developers.surfboardpayments.com/guides/online-payments/post-payments/void-a-payment.md): API allows voiding (canceling) successful, unsettled online payments before 23:00 UTC via a PUT request, preventing fund capture. Refunds are needed if settled. - [Configure branding](https://ai.developers.surfboardpayments.com/guides/online-payments/administration/branding.md): Surfboard allows branding customization (colors, fonts, logos, etc.) of online payment checkouts via API at Partner, Merchant, & Store levels. - [Manage your merchants](https://ai.developers.surfboardpayments.com/guides/online-payments/administration/manage-your-merchants.md): Partners can manage merchants via partner portal or APIs such as fetching merchant(s) details/contracts/terminals, updating merchant details (email, phone, logo). - **Tools and Resources** - [Surfboard APIs](https://ai.developers.surfboardpayments.com/guides/online-payments/integrations/api.md): Surfboard APIs enable secure online/mobile payment integration (acceptance, processing, management) with docs categorized by function (merchants, payments). - [Integrate Surfboard APIs](https://ai.developers.surfboardpayments.com/guides/online-payments/integrations/integrate-api.md): Integrate Surfboard APIs using API-KEY and API-SECRET for authentication. Make JSON requests (e.g., payments), handle JSON responses (status, data, message), an - [Environments](https://ai.developers.surfboardpayments.com/guides/online-payments/integrations/environments.md): Surfboard offers Demo (testing, test cards) & Live (real transactions) environments for payment integrations, accessed via distinct API credentials. - [Client side tokens](https://ai.developers.surfboardpayments.com/guides/online-payments/integrations/client-side-tokens.md): Surfboard client-side tokens enable secure API access (Orders, Payments, etc.) without API keys, using bearer tokens in the authorization header, but exclude ad - [Pagination](https://ai.developers.surfboardpayments.com/guides/online-payments/integrations/pagination.md): APIs use page-based pagination (100 items/page), sorted by creation time (newest first), with `X-PAGE-NUMBER` header, returning total items in `x-total-items`. - [Webhooks](https://ai.developers.surfboardpayments.com/guides/online-payments/integrations/webhooks.md): Surfboard webhooks provide real-time, signed HTTP POST notifications for order, logistics, & merchant events, with retries and signature verification. - [Database connectivity](https://ai.developers.surfboardpayments.com/guides/online-payments/integrations/database-connectivity.md): Surfboard provides daily transaction & payout data dumps for reporting & business intelligence (recommended for 10k+ daily transactions), contact for access. ## API Reference - [Orders API](https://ai.developers.surfboardpayments.com/api/orders.json): 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.). - Create New Order: Creates a new order. You can use this endpoint to create an order that can be processed by the checkout or the payment terminal. You can create orders for both purchase and return. The order created can be paid either by card or other activated payment methods by using the Initiate a Payment API. - Update Order: Updates the Order details. You can use this API to modify the order details. The Order ID will remain the same as the original order even after updating. However, the order cannot be updated once you initiate a payment for that order. - Fetch Order Status: Retrieves the status of a specific order. Use this API to obtain information about the current status of the order. - Cancel an Order: 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. - Add Receipt Information: This API allows you to store cash register details for receipts. - Fetch Order By ID: Fetch Order details through this API. - Fetch Order Adjustments: Fetch all adjustments created under an order. - Fetch Tokens from Order: Fetch all tokenized card information collected for order. - Fetch Online Orders: This API retrieves a list of all online orders created under a terminal. - [Payments API](https://ai.developers.surfboardpayments.com/api/payments.json): 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. - Initiate a Payment: 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. - Check Payment Status: Retrieves the status of a specific payment. Use this API to obtain information about the current status of the payment. - Cancel a Payment: 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. - Get Payment by ID: Retrieves the information of a specific payment. You can use this API to get payment information allowing you to generate and display a receipt for a specific payment. You can also pass in a text/html header to retrieve the response in text format. This allows you to directly print a receipt from the API response without further processing. - Void a Payment: 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:00 UTC. For orders with delayCapture set to true, void can be initiated anytime before the capture call. - Capture Payment: Use this API to complete the authorisation and capture a payment while using the pre-auth flow or to capture a payment when the delayCapture flag is set to true. - Check Capture Status: 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 capturePayments request is made, please make this call after approximately 30 minutes to get the response. - [Transactions API](https://ai.developers.surfboardpayments.com/api/transactions.json): The transactions API enables merchants to retrieve transaction details. Each transaction represents a completed payment. - Fetch Transactions by ID: Retrieves the list of transactions made for the order. You can use this API to get information regarding a transaction. A Transaction can be fetched only after completing the corresponding payment or refund. - Fetch All Transactions: Retrieves a list of all transactions associated with a specific merchant. You can use this API to get information regarding all the transactions under the merchant. - Transaction Search: Use this API to do a free text search on transactions data. - [Receipts API](https://ai.developers.surfboardpayments.com/api/receipts.json): Receipts API facilitates the management and retrieval of receipts for finalized transactions. - Email Receipt: Use this API to send payment receipts to the required email address. - Print Receipt: Use this API to print receipts from the terminals. - Print ESCPOS Receipt: This API helps you print receipts on the terminal through ECS/POS commands. - Add Receipt Information: This API allows you to store cash register details for receipts. - Fetch Receipt Link: This API allows you to retrieve a direct URL link to the receipt for a particular transaction. - [Merchants API](https://ai.developers.surfboardpayments.com/api/merchants.json): 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. - Create Merchant: As a partner, use the Create Merchant API to onboard your sub-merchants for using Surfboard's payment solutions. You can also display products ( terminals, accessories etc. from Surfboard) for your merchants to choose, set product pricing plans for your merchant, display the product catalogue, and pre-select products for your merchants. - Check Application Status: Retrieves the status of the merchant onboarding. After initiating the onboarding for the merchant, use the Check Application Status API to get updates regarding the application’s progress. After the merchant is created, the Merchant ID and Store ID are also available through the webhook. - Create Multi-merchant Group: 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. - Fetch All Merchant Applications: Retrieves a list of all merchants applications with a specific partner. - Fetch Merchant Details: Retrieves information for a specific merchant. As a partner you can use this API to get information regarding your merchants - Fetch All Multi-Merchant Groups: Fetch all existing multi-merchants groups under partner. - Update Merchant Details: Updates the merchant details. You can use this API to edit the email address, merchant logo URL, and phone number of a merchant. - Fetch All Merchant Terminals: Retrieves a list of all terminals associated with a specific merchant. You can use this API to get information regarding all the terminals registered under a merchant. - Fetch All Merchants: Retrieves a list of all merchants associated with a specific partner. Partners can use this API to get information regarding all their merchants. - Fetch All Merchant Contracts: Retrieves the list all contracts under the specific merchant. - Activate Terminal: This API is available for partners who manage their own storage and terminal delivery solution and requires a PCI compliant storage setup. The API can be used to activate terminals that are tagged to you as a partner. This API will return an error if the entered serial number is not available to you. - Fetch Transaction Analytics: Retrieves aggregated transaction analytics for a specific merchant. This can include analytics by store, terminal, date range, card brand, and more. - [Branding APIs](https://ai.developers.surfboardpayments.com/api/branding.json): Branding API’s enables you to customize all customer facing pages provided by Surfboard. The branding can be configured at various levels similar to the terminal config. - Create Branding for Merchant: Create a branding configuration for customizable pages at merchant level - Create Branding for Store: Create a branding configuration for customizable pages at store level - Create Branding for Partner: Create a branding configuration for customizable pages at partner level - Fetch Branding for Merchant: Fetch existing branding configuration at merchant level. - Fetch Branding for Store: Fetch existing branding configuration at store level. - Fetch Branding for Partner: Fetch existing branding configuration at partner level. - Remove Branding for Merchant: Removes the existing branding configuration at the merchant level. - Remove Branding for Store: Removes the existing branding configuration at the store level. - Remove Branding for Partner: Removes the existing branding configuration at the partner level. - [Stores API](https://ai.developers.surfboardpayments.com/api/stores.json): 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. - Create Store: 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. - Deactivate 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. - Fetch Store Details: Retrieves information for a specific store. Use this API to get information regarding a particular store created under a merchant. - Update Store Details: Updates the store details. You can use this API to edit the name, address information, email address, and phone number of a store. - Fetch All Store Terminals: 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. - Fetch Stores: 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. - Verify Store Domain: Use this API to trigger a verify domain request with Surfboard. - Fetch Store Domains: This API retrieves the details of the store's domain. - [Terminals API](https://ai.developers.surfboardpayments.com/api/terminals.json): 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. - Register Terminal: Registers the new terminal to a store. For SDK-based workflows, this API call is unnecessary as SDK methods covers 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. - Register Online Terminal: Register a terminal with an online store to start accepting online payments using this API. - Delink Terminal from Store: 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. - Change Store: 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. - Link Terminal: Links the terminal to the CheckoutPro. You can use this API to link the terminal to a CheckoutPro integration to accept payments. - Delink Terminal: Delinks the terminal from its linked CheckoutPro. Use this API to swap the terminal between different Checkouts or vice-versa. - Check Link Status: Retrieves the linkage status between the terminal and CheckoutPro. Use this API to obtain the current link state between the terminal and CheckoutPro. - Update Terminal Name: Update terminal name of a registered terminal using this call. - Move Terminal: 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. - Set Terminal Config: Sets specific configurations for an individual terminal. Use this API to configure settings and parameters for a particular terminal. - Set Merchant Terminal Config: 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. - Set Store Terminal Config: 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. - Reboot Terminal: Issue a remote terminal restart command. - Fetch Terminal Config: Use this API to fetch all currently active configurations for the terminal. - Fetch Merchant Terminal Config: Use this API to fetch all currently active terminal configurations for the merchant. - Fetch Store Terminal Config: Use this API to fetch all currently active configurations for the store. - Fetch Terminal by ID: Retrieves information about a specific terminal. Use this API to get information regarding a particular terminal registered under a merchant. - Fetch APN List: Retrieves the list of APN's of the terminal. The terminal has to be active for a successful read and the response will be received in exactly 10 seconds. - Get Interapp Code: Use this API to generate registration code used for interapp registration. - Get Interapp Details: Make use of this API to fetch the current status of the interapp registration. - [Payment Methods API](https://ai.developers.surfboardpayments.com/api/payment-methods.json): 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. - Activate AMEX for Merchant: Adds AMEX payment method for a specific merchant. Use this API to activate the American Express (AMEX) as a payment method for the merchant. - Activate SWISH for Merchant: Adds SWISH payment method for a specific merchant. Use this API to activate SWISH as a payment method for the merchant. - Activate KLARNA for Merchant: Adds KLARNA payment method for a specific merchant. Use this API to activate KLARNA as a payment method for the merchant. - Activate VIPPS for Merchant: Adds VIPPS payment method for a specific merchant. Use this API to activate VIPPS as a payment method for the merchant. - Activate Mobile Pay for Merchant: Adds Mobile Pay payment method for a specific merchant. Use this API to activate Mobile Pay as a payment method for the merchant. - Deactivate Payment Method: Deactivates a specific payment method. Use this API to deactivate the payment method added to the merchant or store using its Payment Method ID. - Fetch Payment Method Details: Retrieves information for a specific payment method. Use this API to get information regarding the payment method using its Payment Method ID. - Fetch All Payment Methods: 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. - [payment-methods](https://ai.developers.surfboardpayments.comapi/payment-methods.json): API to manage (add, remove, get) merchant payment methods (AMEX, SWISH, KLARNA, VIPPS, Mobile Pay) beyond the default CARD. Requires API key. - [Logistics API](https://ai.developers.surfboardpayments.com/api/logistics.json): 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. - Create Shipment: Creates a shipment order for terminals and other accessories. Use this API to initiate an order to ship terminals and other accessories to merchants. - Get Shipment Status: Retrieves the status of the shipment order. Use this API to get the shipment status of ordered terminals and other accessories. - Create Return Request: Creates a return request for terminals. - Fetch All Return Requests: Fetches all return requests under a partner. - [Reporting APIs](https://ai.developers.surfboardpayments.com/api/reporting.json): 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. - Fetch Settlement Reports: 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. - [NFC Reading](https://ai.developers.surfboardpayments.com/api/nfc-reading.json): The NFC Reading API's enables you to read NFC tags for an order. - Create Read Session: Use this API to start a NFC reading session on the terminal. - Fetch Sessions for Terminal: This API lets you fetch all reading sessions created under the terminal - Fetch Tags for Session: This API retrieves all the tags read during the specified session. - Fetch Session Status: This API retrieves the current status of the NFC reading session. - Complete NFC Reading Session: This endpoint completes an ongoing NFC (RFID) reading session. You must provide both the terminal ID and session ID in the path, as well as an optional result in the request body. - [Tips APIs](https://ai.developers.surfboardpayments.com/api/tips.json): 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. - Set Merchant Tips Config: Sets tips configurations for all the terminals registered to a specific merchant. Use this API to configure the same tips configurations across multiple terminals associated with a specific merchant. - Set Store Tips Config: Sets tips configurations for all the terminals registered to a specific store. Use this API to configure the same tips configurations across multiple terminals associated with a specific store. - Set Terminal Tips Config: Sets tips configuration for an individual terminal. Use this API to configure tips for a particular terminal. - Fetch Merchant Tips Config: Retrieves the tips configurations for all terminals registered to a specific merchant. Use this API to get all the tips configurations for all the terminals registered to a merchant. - Fetch Store Tips Config: Retrieves the tips configurations for all terminals registered to a specific store. Use this API to get all the tips configurations for all the terminals registered to a store. - [Adjustments API](https://ai.developers.surfboardpayments.com/api/adjustments.json): Adjustments API takes care of handling additional amounts to orders like tips, surcharges, insurance payments etc included while performing a transaction. - Fetch Adjustments: Fetch all adjustments created under a merchant or store. - [billing](https://ai.developers.surfboardpayments.com/api/billing.json): The Billing APIs allow partners to manage charges for merchants, including creating, updating, and retrieving details of one-time or recurring fees. - [Promotions API](https://ai.developers.surfboardpayments.com/api/promotions.json): The Promotions API enables businesses to manage, update and retrieve promotional campaigns effectively. - Create Promotion: The Create Promotion API enables users to create new marketing promotions by defining attributes such as title, content, schedule, and priority. - Update Promotion: The Update Promotion API allows users to modify existing marketing promotions by updating attributes. - Fetch Promotion by ID: The Fetch Promotion by ID API retrieves detailed information about a specific promotion using its unique promotion ID. - Fetch Promotions: The Fetch All Promotions API retrieves detailed information about all the camapigns. - Delete Promotion: The Delete Promotion by ID API allows users to remove a specific promotion by its unique promotion ID. This API permanently deletes the promotion and its associated data, ensuring that it is no longer active or visible. - [Client Auth Tokens API](https://ai.developers.surfboardpayments.com/api/auth.json): 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. - Create Token: Creates a token for a given externalUserID. The token must be passed via the authorization header as a bearer token in subsequent requests. ## Webhooks - [Order Events](https://ai.developers.surfboardpayments.com/webhooks/orders.json): The Order events reference details the various triggers and notifications associated with order processes. These events provide real-time updates on the status and progress of orders, from initiation to completion. By monitoring order events, you can obtain insights into the payment flow, detect issues, and optimize the checkout experience. Each event is linked to specific order attributes, enabling detailed tracking, ensuring seamless order and payment management. - Order Updated: This event is triggered when an order is updated. - Order Payment Initiated: This event is triggered when a payment is initiated for an order. - Order Payment Processed: This event is triggered when a payment is processed for an order. - Order Payment Completed: This event is triggered when a payment is completed for an order. - Order Payment Failed: This event is triggered when a payment for an order is failed. - Order Payment Cancelled: This event is triggered when a payment for an order is cancelled. - Order Cancelled: This event is triggered when an order is cancelled. - Order Terminal Event: This event is triggered for every state the terminal undergoes during a transaction. - [Logistics Events](https://ai.developers.surfboardpayments.com/webhooks/logistics.json): The Logistics events reference details the notifications and triggers associated with product shipment orders, specifically terminals and accessories, made with the Logistics API. These events offer real-time updates on product order statuses from placement to delivery. By monitoring these events, partners can ensure efficient order tracking and timely fulfillment for the products for the merchants. - Logistics Order Update: This event is triggered whenever there's a change in the shipment status of the terminals and accessories ordered. - [Merchant Application Events](https://ai.developers.surfboardpayments.com/webhooks/merchants.json): The Merchant application events reference details the various events that arise during the merchant onboarding process in Surfboard. From the moment a partner initiates the onboarding by creating a merchant application, to the Know Your Business (KYB) step, theses webhooks provides real-time updates on the progress of each merchant application. By tracking these events, partners can ensure timely and accurate completion of merchant onboarding, enhancing the overall efficiency of the onboarding experience. - Application Initiated: This event is triggered when the merchant application is created, and the KYB URL is generated. At this point, the merchant needs to provide the necessary details via the Web KYB. - Application Submitted: This event is triggered once the merchant has completed and submitted the KYB for review. - Application Signed: This event is triggered when both the merchant signatories and UBOs have signed the application. - Application Started: This event is triggered once the merchant has started filling out the application. - Application Pending Merchant Information: This event is triggered when the application is being processed but requires additional data from the merchant for completion. - Application Completed: This event is triggered when the application has been processed and accepted. The next steps involve merchant creation and onboarding. - Application Merchant Created: This event is triggered when the merchant is created in Surfboard. The accompanying event data will include both the Merchant ID and Store ID. - Application Expired: This event is triggered when the merchant application has reached its expiration. For the continuation of the onboarding process, a new application must be created for the merchant. - Application Rejected: This event is triggered post-processing when the merchant application doesn't meet the necessary criteria and is subsequently rejected by Surfboard.