# Change Log: 2025 ## 2025 Q4 Changelog
Date (YYYY-MM-DD)CategoryNotes
2025-12-30Entity ManagementAdded Managing Tender Types documentation to the Terminal Management section to explain how tender types are configured and applied at the terminal level.
2025-12-30FAQsAdded Entity Management FAQs and Managing Tender Types FAQ to centralize common questions related to entity configuration and tender type inheritance.
2025-12-20PaymentsUpdated Payments docs to make terminal API key the preferred auth method for Payments requests. Refreshed Payments landing page plus core flow pages to use X-Api-Key and removed OAuth token language as the primary path (legacy OAuth password grant remains documented for existing integrators).
2025-12-20PaymentsUpdated Create Payment and Payment Statuses to clarify that GET /Payments/tracking/{trackingId} uses the same API key model as POST /Payments/crypto, including updated curl examples, headers, and 401/403 troubleshooting guidance.
2025-12-20FAQsUpdated Payments troubleshooting and testing pages to align with API key auth, including guidance for 401 and 403 outcomes and environment mismatch checks (Sandbox vs Production).
2025-12-20Reference GuideUpdated Reference Guide and Endpoint Index materials to reflect split auth model: Payments use X-Api-Key, other APIs use OAuth. Updated Download OpenAPI / Postman guidance to include a Payments API key environment variable and example request patterns for Payments.
2025-12-09FAQs

  • Aligned the example response with the POST /payments/crypto schema by using paymentUrls as a string array and including paymentPageId.
  • Updated instructions to launch the hosted checkout using the URL from the paymentUrls array instead of the previous object based paymentUrls[0].url pattern.
  • Clarified that Klarna tests follow the same payment creation, hosted page, and status verification flow described in the Payments and Quick Start sections.
2025-12-09Payments

  • Updated Create Payment page to use the same response model as the API (trackingId, paymentPageId, paymentUrls as an array of hosted payment URLs) and removed the outdated paymentUrls.type and paymentUrls.url object pattern.
  • Clarified how integrators should use paymentUrls and paymentPageId together, including when to store trackingId and paymentPageId for later status checks or Payment Pages operations.
  • Ensured examples and step text match the OpenAPI specification and the Payment Statuses and Payment Webhooks pages.
2025-12-09Quick Start

  • Replaced legacy POST /payments example with POST /payments/crypto using the current CryptoPaymentResponse shape (trackingId, paymentPageId, paymentUrls string array).
  • Aligned authentication snippet with current Identity realms and token URL, and clarified how to use the returned access_token across API calls.
  • Updated status check step to use GET /payments/tracking/{trackingId} with enum statusCode values and clarified when to use polling versus webhooks.
  • Refreshed step descriptions so the end to end Sandbox example matches the Payments section and OpenAPI specification.
2025-12-08Reference GuideAdded Crypto and Wallet Concepts for Integrators page under Core Concepts to describe how Bead uses crypto assets and wallets, including payment versus fee tokens, USDC on Base and Solana, Bitcoin on chain and Lightning, wallet types, swaps, and common support scenarios. Updated Compatible Crypto Wallets to list Bitcoin, Bitcoin Lightning, USDC on Base, and USDC on Solana with example wallets ordered by typical consumer usage and clarified that USDC testing uses live networks and real coin only.
2025-12-08FAQsAdded Crypto payments, environment and testing under Environment and Testing to document how crypto tenders map to environments and networks, how to fund wallets safely with small test amounts, and common testing issues with suggested checks. Added Crypto testing and fees under Payments FAQs to answer which tokens are recommended for testing, how many tokens to acquire for fees, and which fee asset is required for each crypto tender.
2025-12-08PaymentsRefreshed Test Crypto Transactions page to focus on running an end to end hosted payment flow with USDC, Bitcoin, and Bitcoin Lightning, aligned examples with the new crypto concepts and wallet matrix, and moved general testing and fee questions into the Payments FAQ so this page stays focused on the test flow itself.
2025-12-04Entity ManagementUpdated Terminal Management › Webhook Management to use the url field instead of webhookUrl, align success statuses (200 / 202 / 204) with the API, and refresh examples plus best-practice guidance for terminal webhooks.
2025-12-04Reference GuideUpdated Webhook Event Reference with terminal webhook behavior, per-payment fan-out, HMAC signature details, status enums, and retry semantics; updated Common Field Types › URL and webhook fields to describe url and webhookUrls consistently with the API.
2025-12-01FAQsAdded test payment card details to How to Test Klarna Payments.
2025-11-25OnboardingAdded minimal application flow with POST /merchant-onboarding/application-short so partners can submit a light “empty” application that still includes signer and configured fees.
2025-11-25OnboardingUpdated GET /merchant-onboarding/application/{applicationId} to return a consolidated onboarding status view, including agreement, compliance, banking, and crypto services in a single response.
2025-11-25OnboardingIntroduced PUT /merchant-onboarding/application/{applicationId} to resend an existing application back to the same signer using the current data set for full front-door resubmission.
2025-11-23Settlement

2025-11-22Payments

2025-11-21Reference Guide

2025-11-21Reporting

2025-11-21Entity Management

2025-10-30Changelog

  • Added Changelog page

    • Consolidated all previous changelog pages and entries into single page
    • Organized changelog entries by quarter, date, section, and type
    • Updated changelog entry formatting for consistency
  • Removed all previous changelog pages
## 2025 Q3 Changelog
Date (YYYY-MM-DD)CategoryNotes
2025-09-17Onboarding

  • Updated documentation

    • Added Onboarding documentation with complete flow: create application, signer email + onboardingUrl, status tracking, resume signing, webhooks, and manual risk feedback.

    • Added Onboarding section to root navigation.

      • Old path under Entity Management will point here going forward.
    • Updated fee units (Submit Application, Sample Payloads) for clarity: transactionRate.sellRate is a percentage (e.g., 2.50 = 2.50%), per-item and fixed fees are USD. Standardized response examples to include applicationId and onboardingUrl.
    • Added webhook event list and example envelope; documented retry behavior and signature validation.
    • Added comprehensive sample payload with randomized values covering signer, merchant data, banking, and tender fees.
2025-09-02Entity Management

  • Updated Create Location schema:

    • Removed maxTransactionAmount.
    • Added averageTicketSize and maximumTicketSize.
    • Added optional highestMonthlyVolume.
    • Added externalId.
    • Added required business detail fields (where applicable).

  • Updated documentation:

    • All Location Management pages:

      • Updated error codes and headers for clarity.

        • Possible responses include 400, 401, 403, 404.
        • Some flows can return 409 for duplicates and 422 for business rule failures. Examples include Authorization and Accept headers.

    • Location Management (parent page):

      • Removed mention of maxTransactionAmount.
      • Added lifecycle wording for create, configure, operate, retire.
      • Added tender inheritance note.

    • Get Location, List Locations:

      • Updated read responses:

        • Removed maxTransactionAmount.
        • Added ticket size fields.
        • terminals returned as an array of terminal identifiers.
        • Added immutable fields: id, merchantId, created, updated cannot be changed.

    • Get Location:

      • Added immutable fields: id, merchantId, created, updated cannot be changed.

    • List Locations:

      • Updated and expanded List guidance. Endpoint returns the full array. Recommend client side caching and UI pagination.

    • Update Location:

      • Update semantics clarified.
      • PUT is a full object update.
      • Website is required when business type is virtual.
      • Required field set expanded to include business details and ticket sizes.
      • Documented immutable: id, merchantId, created, updated cannot be changed.

    • Delete Location:

      • Updated delete semantics for clarity.
      • Success returns 204 No Content.
      • Deletion requires zero terminals under the location.
2025-09-02Reporting

  • Updated documentation:

    • Partner Payments:

      • Partner history endpoint corrected to GET /Partners/{id}/payments.
      • Model aligned with Merchant.

    • Merchant Payments:

      • Merchant history endpoint corrected to GET /Merchants/{id}/payments.
      • Query parameters and response envelope standardized.
2025-09-02Reference Guide

  • Updated documentation:

    • Reference Guide (parent page):

      • Refreshed Reference Guide landing.
      • Unified conventions for pagination and the error envelope.
      • Added environment snippet.

    • Authentication & OAuth:

      • Unified authentication content.
      • Standardized token URL.
      • Added lifetimes and refresh policy.
      • Updated Postman quick start for correctness and clarity.

    • Tender Types › Crypto:

      • Updated Crypto tender strings to be more authoritative.
      • Updated current Crypto tender types to usdcBase and usdcSolana.
      • Added future entries for planning.

    • Common Field Types:

      • Updated Common Field Types for correctness and clarity.
      • Added address, contact, identifiers, monetary fields, pagination envelope, headers, and unified error object.

    • Endpoint Index:

      • Corrected Endpoint Index.
      • Updated Merchant and Partner history method to GET.
      • Updated terminal webhook paths to standard.
      • Added webhookUrl body field.
      • Added locations terminals listing.

    • Download OpenAPI / Postman:

      • Updated downloads page with aligned hosts and token URL plus environment variables.

    • Environments & Base URLs:

      • Updated base URLs and token endpoint for correctness.
      • Updated sandbox retention to 180 days.
2025-07-24Reporting

  • Updated Payment-history endpoints:

    • Now use GET (breaking)

      • /Partners/{id}/payments, /Merchants/{id}/payments, and /Terminals/{id}/payments all switch from POST to GET.
      • No request body—filters stay in the query string.

  • Updated documentation:

2025-07-24Reference Guide

  • Updated documentation:

    • Updated methods for partner, merchant, and terminal payments from POST to GET.
    • Updated Index and OpenAPI.
2025-07-09Payments

  • Updated per-payment webhook override:

    • Added webhookUrls (string array) to POST /payments/crypto. Events now fan-out to the terminal’s default webhook plus every URL in the array.

  • Updated redirectUrl:

    • Updated to be optional. If omitted in Create Payment request, Bead shows a “Payment complete / cancelled” screen.

    • Updated hosted page UX:

      • When the customer object is omitted, checkout no longer prompts the shopper for name or address.

  • Updated documentation:

    • Create Payment

      • Updated to ensure extra endpoints are ready to receive callbacks.
      • Removed client-side rule that requires a redirect URL: Collect customer data yourself if required for your flow.

    • Payment Webhooks:

      • Updated to ensure extra endpoints are ready to receive callbacks.
2025-07-09Entity Management

  • Updated documentation:

    • Terminal Management › Webhook Management:

      • Updated to explain that a terminal’s default webhook always receives events, even when a webhookUrls array is supplied in POST /payments/crypto.
      • Added best-practice tips, signature-verification reminder, and updated examples (no API change).
2025-07-09Reference Guide

  • Updated documentation:

    • Updated Payments schema.
    • Added webhookUrls to crypto create.
    • Updated redirectUrl as optional.
    • Updated status codes to be returned as enum strings.
## 2025 Q2 Changelog
Date (YYYY-MM-DD)CategoryNotes
2025-06-14Entity Management

  • Updated documentation:

    • Added Get Merchant page.

    • Added Update Location page:

      • Removed all PATCH references. Clarified Disable before delete guidance in Best Practices.

    • List Locations:

      • Updated to clarify that current endpoint returns the entire array with no pagination.
      • Added client side caching tips.
2025-06-04Entity Management

  • Updated documentation:

    • Added Location Management page:

      • Added parent lifecycle overview plus Create, Get, List, Delete, and section level Changelog pages.
2025-06-04Reference Guide
2025-06-01Reference Guide

  • Updated documentation:

    • Added webhook signing secret and HMAC verification documentation.
    • Added sample payment.status.updated payload.
2025-05-27Reference Guide

  • Updated documentation:

    • Formalized default rate limits and documented 429 handling with headers and error object.
2025-05-15Reference Guide
2025-05-13Payments

  • Updated Status Code field:

    • statusCode now returns enum strings (e.g., completed, underpaid) instead of numeric values in the Payment Status endpoint.

  • Updated Webhook payload:

    • statusCode now returns enum strings instead of numeric values.

  • Updated documentation

2025-05-01Entity Management
2025-04-24Entity Management

  • Updated documentation:

    • Added Terminal Management (initial public release).

    • List Terminals

      • Response trimmed.

    • Updated hierarchy:

      • Documented Partner → Merchant → Location → Terminal → Payment structure.
2025-04-24Reporting

  • Added Reporting endpoints (initial public release)

    • Added /Partners/{id}/payments, /Merchants/{id}/payments
    • Added /Terminals/{id}/payments.
    • Added shared query parameters (page, pageSize, sortBy, sortDirection, fromDate, toDate, status).
2025-04-01Reference Guide