> ## Documentation Index > Fetch the complete documentation index at: https://docs.zbx.boomfi.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Create Sub-Merchant > Onboard a merchant under your partner account. In an environment where a custody provider owns merchant identity, this registers the merchant with that provider and returns a one-time verification_url to send them to; the merchant's accounts are provisioned once they clear KYC, and kyc_status reports where they are. Repeating the call with the same external_reference returns the org you already created rather than a second one. ## OpenAPI ````yaml /openapi.yaml post /partners/orgs openapi: 3.1.0 info: contact: email: support@boomfi.xyz name: API Support description: >- The BoomFi Merchants API provides a set of endpoints for merchants to manage their accounts, transactions, and more. Hosts differ per brand/environment; use the brand-specific base URL from the docs. title: ZBX Merchants API version: '1.0' servers: - url: https://mapi.zbx.boomfi.xyz/v1 description: Production security: [] tags: - description: Payment links name: Paylinks - description: Billing plans name: Plans - description: Subscriptions name: Subscriptions - description: Customer records name: Customers - description: Invoices name: Invoices - description: Payments name: Payments - description: Organisation events name: Events - description: Organisation profile and display settings name: Organisation - description: Webhook and request-signing secrets name: Secrets - description: Settlement accounts name: Accounts - name: Bank Address Book - description: Managed virtual accounts, balances, pay-in, and payout name: Virtual Accounts - description: Partner-managed accounts, virtual accounts, pay-in, and payout name: Partners - description: Partner virtual account automations and run history name: Partner Automations - description: Partner maintain-balance automations name: Partner Balance Monitoring - description: Tradeable currencies, instruments, and swap targets name: Instruments - description: RFQ quotes name: Quotes - description: RFQ orders and one-click trades name: Orders - description: Executed trades name: Trades paths: /partners/orgs: post: tags: - Partners summary: Create Sub-Merchant description: >- Onboard a merchant under your partner account. In an environment where a custody provider owns merchant identity, this registers the merchant with that provider and returns a one-time verification_url to send them to; the merchant's accounts are provisioned once they clear KYC, and kyc_status reports where they are. Repeating the call with the same external_reference returns the org you already created rather than a second one. requestBody: content: application/json: schema: $ref: '#/components/schemas/onboarding.CreateZBXOrgRequest' description: Merchant to onboard required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/partners.SubMerchantResponse' '201': description: Created content: application/json: schema: $ref: '#/components/schemas/partners.SubMerchantResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '424': description: Failed Dependency content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/internal.ErrorResponse' security: - ApiKeyAuth: [] components: schemas: onboarding.CreateZBXOrgRequest: properties: address: allOf: - $ref: '#/components/schemas/onboarding.CreateOrgAddress' description: Postal address. Country and city are required when present. country_of_incorporation: description: alpha-3 type: string dba_name: description: Dba name for this resource. type: string end_user_ip: description: >- EndUserIP is the merchant's own IP at signup, which ZBX documents as "required for risk assessment and compliance" on user registration. Optional here because only the partner can know it: this is a server-to-server call, so the connecting address is their backend, not the merchant's browser. Absent falls back to that connecting address — which keeps working, but feeds ZBX's risk engine a datacenter IP. A partner who can supply the real one should. Top-level rather than on the shared owner object: it means nothing on the self-custody path and does not belong in its contract. type: string external_reference: description: External reference for this resource. type: string legal_name: description: >- LegalName is the optional field that earns its keep here: it becomes zbx.expected_holder_name, which is how an inbound IBAN — a payload carrying no uid — gets attributed to this merchant. Absent falls back to Name. type: string mcc: allOf: - $ref: '#/components/schemas/onboarding.OrgMCC' description: >- Mcc for this resource. Optional, but all three sub-fields are required when it is present — a half-filled MCC is a mistake, an absent one is a choice. mid: description: Mid for this resource. type: string name: description: Display name. type: string owner: allOf: - $ref: '#/components/schemas/onboarding.CreateOrgOwnerRequest' description: >- Owner for this resource. owner.phone must be a verified E.164 mobile. partner_id: description: >- Identifier of the partner organisation, when this org is under a partner. type: string payment_fee_pct: description: Payment fee percentage. type: number principal_place_of_business: description: alpha-3 country code type: string registration_number: description: Registration number for this resource. type: string settlement_accounts: description: >- Accounts exists only to be rejected, and is untyped so that any shape gets the explanation below rather than a binding error about a missing sub-field. items: {} type: array webhook_url: description: HTTPS URL that receives webhook events. type: string required: - external_reference - name - owner type: object partners.SubMerchantResponse: properties: data: allOf: - $ref: '#/components/schemas/onboarding.CreateOrgResponse' description: The merchant organisation. error: description: True when the request failed. type: boolean message: description: Human-readable status or error message. type: string type: object internal.ErrorResponse: properties: error: allOf: - $ref: '#/components/schemas/internal.ErrorStruct' description: Error details including HTTP-style code and message. type: object onboarding.CreateOrgAddress: properties: building_number: description: Building number for this resource. type: string city: description: City for the postal address. type: string country: description: ISO 3166-1 alpha-2 country code. type: string flat_number: description: Flat number for this resource. type: string postal_code: description: Postal or ZIP code. type: string state: description: State, province, or region. type: string street: description: Street for this resource. type: string required: - city - country type: object onboarding.OrgMCC: properties: code: description: Machine-readable code (error, MCC, or reason code). type: string description: description: Human-readable description. type: string risk_tier: description: Risk tier for this resource. type: string required: - code - description - risk_tier type: object onboarding.CreateOrgOwnerRequest: properties: email: description: Email address. type: string name: description: Display name. type: string phone: description: Phone number. type: string required: - email - name type: object onboarding.CreateOrgResponse: properties: created_at: description: When the resource was created (RFC3339). type: string kyc_status: description: >- Identity verification state of the merchant with the custody provider: "pending" until they clear KYC, "accepted" once they have. Empty in self-custody environments, which have no such gate. type: string name: description: Display name. type: string org_id: description: Organisation ID that owns this resource. type: string owner: allOf: - $ref: '#/components/schemas/onboarding.CreateOrgOwnerResponse' description: Owner for this resource. partner_id: description: >- Identifier of the partner organisation, when this org is under a partner. type: string settlement_accounts: description: Settlement accounts for this resource. items: $ref: '#/components/schemas/onboarding.CreateOrgAccountResponse' type: array verification_url: description: >- One-time identity verification (KYC/KYB) url. Only set while the custody provider still needs the merchant to complete verification. type: string type: object internal.ErrorStruct: properties: code: description: |- Error code Example: 400 example: 400 type: integer errors: description: List of errors items: $ref: '#/components/schemas/internal.SingleError' type: array message: description: |- Error message Example: Insufficient quantity example: Insufficient quantity type: string type: object onboarding.CreateOrgOwnerResponse: properties: email: description: Email address. type: string name: description: Display name. type: string phone: description: Phone number. type: string user_id: description: Identifier of the user associated with this resource. type: string type: object onboarding.CreateOrgAccountResponse: properties: address: description: >- On-chain wallet address or postal street address, depending on context. type: string chain_id: description: Blockchain chain ID. type: integer currencies: description: Supported currency codes for this account or chain. items: type: string type: array id: description: Unique resource identifier. type: integer name: description: Display name. type: string reference: description: Merchant-defined reference string. type: string type: object internal.SingleError: properties: domain: description: |- Domain Example: orders example: orders type: string reason: description: |- Error Reason Example: InsufficientQuantity example: InsufficientQuantity type: string type: object securitySchemes: ApiKeyAuth: in: header name: X-API-KEY type: apiKey ````