surfboard_white
Book a demo

Developers Changelog Carbon Platform

Carbon Platform v2026.9

Create Merchant now returns a prefilled web KYB link. Pass the corporate ID and a business description and Surfboard resolves the registry data, classifies the merchant, and works out which documents it needs. The merchant adds a bank account, the documents, and the signatures.

Released
Product
Carbon Platform
Version
v2026.9

🚀 Prefilled Merchant Applications

Category: Merchants API

POST /partners/{partnerId}/merchants still creates the application and returns the web KYB link, but the link now comes back already populated. Two things happen before it is returned:

  • Registry prefill. The legal name, registered address, and where available the directors and beneficial owners are resolved from the national business registry for the merchant’s country. organisation.legalName and organisation.address can be omitted
  • Business classification. The free-text preEnteredInformation.businessDescription is classified into a merchant category (MCC), which decides which documents the merchant must supply and any category-specific questions. Describe what the merchant actually takes payment for, not the general company purpose: “Selling coffee and pastries at our café”, not “Food and beverage services”. If you already know the MCC, pass organisation.mccCode instead

The merchant then only adds what a partner cannot know for them: the bank account, the category documents, and the signing. If any part of the prefill cannot be resolved, the call still succeeds and the merchant fills that section in the flow as before. Prefill is additive; nothing you send is discarded and nothing you omit blocks the link.

👥 People and Signing

Category: Merchants API

preEnteredInformation can now carry the people involved, so the signing invitations go out without the merchant typing anyone in.

  • applicant: the main contact, with isSignatory, isUbo and isChairman flags. A person can hold more than one role
  • signatories[], ubos[] and chairpersons[]: additional people, each with at least name and email
  • Beneficial owners take ownershipPercent and ownershipType (direct or indirect). An indirect owner must name the intermediary company in entityName
  • Only signatories and beneficial owners receive a signing link. An applicant or chairperson signs only if they also hold one of those roles

🧩 New Request Fields

Category: Merchants API

  • localeSelected: language of the web KYB (sv, da, fi, en); defaults to the country’s language
  • country now accepts SE, NO, DK, FI and IE, with corporateId validated per country
  • controlFields.store.paymentChannels: { physical, online, physicalSharePercent }, where the share only matters when both channels are used
  • controlFields.disableFields.onlineInfo: locks the webshop URLs against merchant edits; requires store.onlineInfo in the same request
  • controlFields.linkUsers: existing user IDs to link to the new merchant
  • controlFields.directMerchantCreation: creates the merchant directly instead of an application; only for programmes with a direct acquirer agreement
  • controlFields.acquirerConfig.acquirerIID alongside acquirerMID
  • merchantConfig.settlementFrequency values are now daily, twiceWeekly, weekly, tenDays, fortNightly, monthly, everyTwoMonths, trimester, quarterly and twiceYearly
  • preEnteredInformation.giftcards.revenueSharePercent replaces amountPerYear
  • preEnteredInformation.fundsInfo.estimatedFrequencyOfTransactions is one of DAILY, WEEKLY, MONTHLY, YEARLY

📨 Response and Status

Category: Merchants API

  • Create Merchant returns validUntil, the expiry of the onboarding link, next to applicationId, webKybUrl, shortLinkUrl, merchantId and storeId
  • GET /partners/{partnerId}/merchants/{applicationId}/status carries the current webKybUrl while the application is open, so a lost link is recovered from status rather than by creating a second application. Each Create Merchant call creates a new application
  • Status paymentMethods[] entries now read { paymentMethod, enabledSchemes, status }, and domainVerification[] lists the merchant’s online-store verification records

📗 Documentation

Category: Documentation