Sign in

v1

latestOpenAPI 3.0.02026-07-24103118224.7 KB
Connect

Create Connect sub-merchant account

Creates a SUB_MERCHANT user under the authenticated marketplace account, provisions a KYC provider account, and immediately returns unified nextUrl/nextSteps for the initial KYC flow based on account type.

post/api/connect/accounts

Request body

customerType'individual' | 'business'

Account type for this sub-merchant. Determines the KYC flow: individual triggers a personal KYC, business triggers a KYB.

emailstring email required

Email of the sub-merchant account

firstNamestring

First name of the sub-merchant (individual accounts only). If omitted, derived from merchantName or the email prefix.

lastNamestring

Last name of the sub-merchant (individual accounts only). If omitted, defaults to Merchant.

merchantNamestring

Display name / merchant name for the sub-merchant

marketplaceMetadataobject

Arbitrary marketplace metadata attached to the sub-merchant

redirectUrlKycstring uri

Optional redirect URL used to build the initial hosted KYC link returned at sub-merchant creation

bridgeCustomerType'individual' | 'business'

Example request

{
  "email": "seller@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "merchantName": "Seller Alpha",
  "redirectUrlKyc": "https://marketplace.example.com/connect/kyc-complete"
}

Response

Create Connect sub-merchant account successful

idstring required
emailstring required
merchantNamestring nullable required
firstNamestring nullable required
lastNamestring nullable required
accountType'INDIVIDUAL' | 'MARKETPLACE' | 'SUB_MERCHANT' required
marketplaceUserIdstring required
marketplaceMetadataobject nullable required
customerIdstring nullable required

KYC provider customer id linked to this sub-merchant

custodialWalletAddressstring nullable required

Custodial wallet address for this sub-merchant

stopProcessingSettlementboolean required
createdAtstring date-time required
updatedAtstring date-time required

Example response

{
  "id": "usr_01JABCDEF0123456789XYZ",
  "email": "seller@example.com",
  "merchantName": "Seller Alpha",
  "firstName": "John",
  "lastName": "Doe",
  "marketplaceUserId": "usr_marketplace123",
  "customerId": "cus_abc123",
  "custodialWalletAddress": "0xABC123…"
}