> ## Documentation Index > Fetch the complete documentation index at: https://dev.enterprise.moonpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Business > Onboard business customers using MoonPay Enterprise's hosted Link flow or the programmatic Business API. MoonPay Enterprise supports two methods for onboarding business customers through KYB (Know Your Business) verification. Both follow the same [onboarding lifecycle](/onboarding) and collect the same underlying compliance data. Create a `Link` identification and receive a URL. Your customer completes KYB verification in MoonPay Enterprise's hosted interface. MoonPay Enterprise handles the entire collection, review, and approval process. Submit all KYB data directly via the API with a `Business` identification. You collect and provide company info, beneficiaries, documents, and the compliance questionnaire programmatically. ## Hosted Link Flow The simplest way to onboard a business customer. You create a `Link` identification and MoonPay Enterprise returns a URL where your customer completes the full KYB process through MoonPay Enterprise's hosted interface. MoonPay Enterprise is fully responsible for collecting all required information, performing verification, and deciding on approval. `POST /api/customers` ```bash theme={null} curl --request POST \ --header 'content-type: application/json; charset=utf-8' \ --header 'idempotency-key: ' \ --header 'x-api-key: ' \ --data '{"name": "acme_corp", "email": "admin@acme.com", "customer_type": "Business"}' \ --url 'https://api.sandbox.iron.xyz/api/customers' ``` The customer is created in `SigningsRequired` status under `X-API-Version: 2026-08-01` or later, and in `IdentificationRequired` on earlier versions. See [Create a new customer](/onboarding). Fetch the terms via `GET /api/customers/{id}/required-signings` and record acceptance via `POST /api/customers/{id}/signings` before creating the identification. The terms contain the data sharing agreement, so they come before KYB data collection. `POST /api/customers/{id}/identifications/v2` ```bash theme={null} curl --request POST \ --header 'accept: application/json; charset=utf-8' \ --header 'content-type: application/json; charset=utf-8' \ --header 'idempotency-key: ' \ --header 'x-api-key: ' \ --data '{ "type": "Link" }' \ --url 'https://api.sandbox.iron.xyz/api/customers//identifications/v2' ``` The response includes a `url` field. Pass this URL to your customer to begin the hosted KYB flow. The customer opens the link and completes the flow in MoonPay Enterprise's hosted interface, which collects company information, documents, beneficial ownership details, and the business questionnaire. Once the submission is complete, MoonPay Enterprise reviews the data, performs verification, and decides on approval. Track progress via [webhooks](/webhooks) or by polling the identification status. Once KYB is approved, MoonPay Enterprise checks that the terms have been signed. If not, the customer status is `SigningsRequired`: retrieve required signings, present them to the customer, and mark them as signed. See the [onboarding lifecycle](/onboarding) for details. ## Programmatic Business API For partners who collect KYB data within their own application, you can submit all business verification data directly via the API. This requires a [KYC/KYB sharing agreement](/sharing) with MoonPay Enterprise. You collect the company information, beneficial ownership details, identity documents, and the compliance questionnaire, then submit everything in a single API call. `POST /api/customers` ```bash theme={null} curl --request POST \ --header 'content-type: application/json; charset=utf-8' \ --header 'idempotency-key: ' \ --header 'x-api-key: ' \ --data '{"name": "acme_corp", "email": "admin@acme.com", "customer_type": "Business"}' \ --url 'https://api.sandbox.iron.xyz/api/customers' ``` Fetch the terms via `GET /api/customers/{id}/required-signings` and record acceptance via `POST /api/customers/{id}/signings` before creating the identification. `POST /api/customers/{id}/identifications/v2` Submit the full KYB payload with `type: "Business"`. Company identity, beneficiaries, and documents are nested under `company_data` (company fields sit under `company_data.company_info`). The company `phone` and the submitting device's `ip_address` are top-level, and `questionnaire` carries a `type` discriminator (`Generic` for all company types except non-US sole proprietorships, `SoleProp` for non-US sole proprietorships). The example below shows a complete submission with one beneficial owner: From API version `2026-10-15`, every beneficiary with the `UltimateBeneficialOwner` role also sets `ubo_subtype`. Add `"ubo_subtype": "Ownership"` to those beneficiaries in the examples on this page. Earlier versions reject the field. See [Migrating to API Version 2026-10-15](#migrating-to-api-version-2026-10-15). ```bash Shell theme={null} curl --request POST \ --header 'accept: application/json; charset=utf-8' \ --header 'content-type: application/json; charset=utf-8' \ --header 'idempotency-key: ' \ --header 'x-api-key: ' \ --url 'https://api.sandbox.iron.xyz/api/customers//identifications/v2' \ --data-raw '{ "type": "Business", "phone": "+4930123456789", "ip_address": "8.8.8.8", "company_data": { "company_info": { "company_name": "Acme Corp", "registration_number": "12345678", "country": "DE", "incorporation_date": "2020-06-15", "legal_address": "Friedrichstraße 123, 10117 Berlin", "postal_address": "Friedrichstraße 123, 10117 Berlin", "address": { "street_1": "Friedrichstraße 123", "city": "Berlin", "state": "Berlin", "zip_code": "10117", "country": "DE" }, "email": "info@acme.com", "tax_identification_number": "DE123456789", "website": "https://www.acme.com", "company_type": "LimitedLiabilityCompany" }, "beneficiaries": [ { "roles": ["Director", "UltimateBeneficialOwner"], "share_percentage": 100, "beneficiary_info": { "first_name": "Jane", "last_name": "Smith", "date_of_birth": "1985-03-22", "email_address": "jane@acme.com", "phone_number": "+4915112345678", "tax_identification_number": "12345678901", "tax_jurisdiction_country_code": "DE", "birth_place": { "place": "Munich", "state": "Bavaria", "country": "DE" }, "address": { "street_1": "Unter den Linden 42", "city": "Berlin", "state": "Berlin", "zip_code": "10117", "country": "DE" }, "identity": { "identity_country_code": "DE", "identity_document_type": "Passport", "identity_document_front": "", "selfie": "", "selfie_collected_at": "2026-07-01T12:00:00Z", "nationality": "DE" }, "proof_of_address": "" } } ], "documents": [ { "type": "IncorporationCert", "country": "DE", "file": "" }, { "type": "IncorporationArticles", "country": "DE", "file": "" }, { "type": "ShareholderRegistry", "country": "DE", "file": "" }, { "type": "DirectorsRegistry", "country": "DE", "file": "" } ] }, "questionnaire": { "type": "Generic", "business_details": { "industry_type": "InformationTechnologyAndSoftware", "business_model_description": "B2B SaaS platform for supply chain management, serving mid-market and enterprise logistics teams", "main_business_countries": ["DE", "FR", "NL"], "has_licenses_or_registrations": false }, "source_of_funds": { "source_of_funds": "VcPrivateEquity", "source_of_funds_description": "Series B venture round led by a European growth fund" }, "planned_activities": { "purpose_and_intended_use": "ReceivingBusinessIncome", "estimated_monthly_volume": "FiftyToOneHundredThousand", "estimated_monthly_transactions": "TenToTwentyFive", "sends_funds_on_customer_behalf": false } } }' ``` ```python Python theme={null} import requests import base64 from pathlib import Path API_KEY = "" CUSTOMER_ID = "" BASE_URL = "https://api.sandbox.iron.xyz/api" def encode_document(file_path: str) -> str: return base64.b64encode(Path(file_path).read_bytes()).decode() response = requests.post( f"{BASE_URL}/customers/{CUSTOMER_ID}/identifications/v2", headers={ "accept": "application/json; charset=utf-8", "content-type": "application/json; charset=utf-8", "idempotency-key": "", "x-api-key": API_KEY, }, json={ "type": "Business", "phone": "+4930123456789", "ip_address": "8.8.8.8", "company_data": { "company_info": { "company_name": "Acme Corp", "registration_number": "12345678", "country": "DE", "incorporation_date": "2020-06-15", "legal_address": "Friedrichstraße 123, 10117 Berlin", "postal_address": "Friedrichstraße 123, 10117 Berlin", "address": { "street_1": "Friedrichstraße 123", "city": "Berlin", "state": "Berlin", "zip_code": "10117", "country": "DE", }, "email": "info@acme.com", "tax_identification_number": "DE123456789", "website": "https://www.acme.com", "company_type": "LimitedLiabilityCompany", }, "beneficiaries": [ { "roles": ["Director", "UltimateBeneficialOwner"], "share_percentage": 100, "beneficiary_info": { "first_name": "Jane", "last_name": "Smith", "date_of_birth": "1985-03-22", "email_address": "jane@acme.com", "phone_number": "+4915112345678", "tax_identification_number": "12345678901", "tax_jurisdiction_country_code": "DE", "birth_place": { "place": "Munich", "state": "Bavaria", "country": "DE", }, "address": { "street_1": "Unter den Linden 42", "city": "Berlin", "state": "Berlin", "zip_code": "10117", "country": "DE", }, "identity": { "identity_country_code": "DE", "identity_document_type": "Passport", "identity_document_front": encode_document("passport-front.jpg"), "selfie": encode_document("selfie.jpg"), "selfie_collected_at": "2026-07-01T12:00:00Z", "nationality": "DE", }, "proof_of_address": encode_document("proof-of-address.pdf"), }, } ], "documents": [ { "type": "IncorporationCert", "country": "DE", "file": encode_document("registration.pdf"), }, { "type": "IncorporationArticles", "country": "DE", "file": encode_document("articles.pdf"), }, { "type": "ShareholderRegistry", "country": "DE", "file": encode_document("shareholders.pdf"), }, { "type": "DirectorsRegistry", "country": "DE", "file": encode_document("directors.pdf"), }, ], }, "questionnaire": { "type": "Generic", "business_details": { "industry_type": "InformationTechnologyAndSoftware", "business_model_description": "B2B SaaS platform for supply chain management, serving mid-market and enterprise logistics teams", "main_business_countries": ["DE", "FR", "NL"], "has_licenses_or_registrations": False, }, "source_of_funds": { "source_of_funds": "VcPrivateEquity", "source_of_funds_description": "Series B venture round led by a European growth fund", }, "planned_activities": { "purpose_and_intended_use": "ReceivingBusinessIncome", "estimated_monthly_volume": "FiftyToOneHundredThousand", "estimated_monthly_transactions": "TenToTwentyFive", "sends_funds_on_customer_behalf": False, }, }, }, ) identification = response.json() print(identification) ``` ```typescript TypeScript theme={null} import fs from "fs"; const API_KEY = ""; const CUSTOMER_ID = ""; const BASE_URL = "https://api.sandbox.iron.xyz/api"; function encodeDocument(filePath: string): string { return fs.readFileSync(filePath).toString("base64"); } const response = await fetch( `${BASE_URL}/customers/${CUSTOMER_ID}/identifications/v2`, { method: "POST", headers: { accept: "application/json; charset=utf-8", "content-type": "application/json; charset=utf-8", "idempotency-key": "", "x-api-key": API_KEY, }, body: JSON.stringify({ type: "Business", phone: "+4930123456789", ip_address: "8.8.8.8", company_data: { company_info: { company_name: "Acme Corp", registration_number: "12345678", country: "DE", incorporation_date: "2020-06-15", legal_address: "Friedrichstraße 123, 10117 Berlin", postal_address: "Friedrichstraße 123, 10117 Berlin", address: { street_1: "Friedrichstraße 123", city: "Berlin", state: "Berlin", zip_code: "10117", country: "DE", }, email: "info@acme.com", tax_identification_number: "DE123456789", website: "https://www.acme.com", company_type: "LimitedLiabilityCompany", }, beneficiaries: [ { roles: ["Director", "UltimateBeneficialOwner"], share_percentage: 100, beneficiary_info: { first_name: "Jane", last_name: "Smith", date_of_birth: "1985-03-22", email_address: "jane@acme.com", phone_number: "+4915112345678", tax_identification_number: "12345678901", tax_jurisdiction_country_code: "DE", birth_place: { place: "Munich", state: "Bavaria", country: "DE", }, address: { street_1: "Unter den Linden 42", city: "Berlin", state: "Berlin", zip_code: "10117", country: "DE", }, identity: { identity_country_code: "DE", identity_document_type: "Passport", identity_document_front: encodeDocument("passport-front.jpg"), selfie: encodeDocument("selfie.jpg"), selfie_collected_at: "2026-07-01T12:00:00Z", nationality: "DE", }, proof_of_address: encodeDocument("proof-of-address.pdf"), }, }, ], documents: [ { type: "IncorporationCert", country: "DE", file: encodeDocument("registration.pdf"), }, { type: "IncorporationArticles", country: "DE", file: encodeDocument("articles.pdf"), }, { type: "ShareholderRegistry", country: "DE", file: encodeDocument("shareholders.pdf"), }, { type: "DirectorsRegistry", country: "DE", file: encodeDocument("directors.pdf"), }, ], }, questionnaire: { type: "Generic", business_details: { industry_type: "InformationTechnologyAndSoftware", business_model_description: "B2B SaaS platform for supply chain management, serving mid-market and enterprise logistics teams", main_business_countries: ["DE", "FR", "NL"], has_licenses_or_registrations: false, }, source_of_funds: { source_of_funds: "VcPrivateEquity", source_of_funds_description: "Series B venture round led by a European growth fund", }, planned_activities: { purpose_and_intended_use: "ReceivingBusinessIncome", estimated_monthly_volume: "FiftyToOneHundredThousand", estimated_monthly_transactions: "TenToTwentyFive", sends_funds_on_customer_behalf: false, }, }, }), } ); const identification = await response.json(); console.log(identification); ``` MoonPay Enterprise validates the submission synchronously. A complete submission is created as `Processed` and moves into verification. An incomplete submission — any country — is rejected with `400`. See [Incomplete Submissions](#incomplete-submissions). Track progress via [webhooks](/webhooks) or by polling the identification status. Submit once. This endpoint is not an upsert, and every call that returns `201` creates a new identification record. Do not call it again to refresh status, or to correct a submission that was accepted. A `400` is the exception: nothing was created, so fixing the payload and submitting again is correct. See [Resubmitting and Correcting a Submission](#resubmitting-and-correcting-a-submission). Same as the hosted flow. Once KYB is approved, MoonPay Enterprise checks that the terms have been signed. If not, the customer status is `SigningsRequired`: retrieve required signings, present them, and mark them as signed to activate the customer. ### Migrating to API Version 2026-10-15 API version `2026-10-15` changes how a `Business` submission describes who the ultimate beneficial owners (UBOs) are. This section covers what changes, how to update your payload, and what you see if you haven't yet. Only `Business` submissions sent with `X-API-Version: 2026-10-15` or later are affected. If you send an earlier version or no version header, your submissions behave exactly as before. `Person` and `Token` submissions are not affected. #### What changes | | Before `2026-10-15` | From `2026-10-15` | | - | - | - | | A UBO | Role `UltimateBeneficialOwner` with a `share_percentage` | The same, plus `ubo_subtype: "Ownership"` | | An individual who controls the company without owning it | Not expressible | Role `UltimateBeneficialOwner` with `ubo_subtype: "Control"` and a `nature_of_control` | | A company where nobody owns enough to qualify | A `Director` alone was accepted | Submit the individual who controls the company as a `Control` UBO | | The fields `ubo_subtype` and `nature_of_control` | Rejected | Accepted | #### Migrate in four steps 1. Send `X-API-Version: 2026-10-15` on `POST /api/customers/{id}/identifications/v2`. The version is read per request, so you can move one request at a time. 2. For every beneficiary with the `UltimateBeneficialOwner` role, set `ubo_subtype` using the table below. 3. If no individual owns enough to qualify, add the individual who controls the company as a `Control` UBO. A `Director` with no `UltimateBeneficialOwner` role no longer satisfies this. 4. Submit in the sandbox first and check that the submission is accepted. #### Which subtype to use | Situation | `ubo_subtype` | `share_percentage` | `nature_of_control` | | - | - | - | - | | An individual owns 25% or more (or 10% or more when nobody reaches 25%) | `Ownership` | Required | Not allowed | | An individual controls the company without owning it, for example through voting rights, a trust, or the right to appoint the board | `Control` | Not allowed | Required, up to 255 characters | | A foundation, where a council member controls the company | `Control` | Not allowed | Required | | A company owned by another company, where no individual reaches the threshold | `Control`, for the individual who controls it | Not allowed | Required | #### Before and after An owner needs one extra field: ```jsonc theme={null} { "roles": ["UltimateBeneficialOwner"], "share_percentage": 40, "ubo_subtype": "Ownership", // new "beneficiary_info": { /* unchanged */ } } ``` A company where nobody owns enough to qualify submits the individual who controls it: ```jsonc theme={null} // Before: accepted with a Director only { "roles": ["Director"], "beneficiary_info": { /* ... */ } } // From 2026-10-15: the same person also declares how they control the company { "roles": ["Director", "UltimateBeneficialOwner"], "ubo_subtype": "Control", "nature_of_control": "Member of the foundation council with voting rights", "beneficiary_info": { /* ... */ } } ``` #### Rules to remember * `Control` is accepted only on root-level person beneficiaries of a company that isn't a sole proprietorship. * A corporate beneficiary never counts as the UBO, whatever its roles. At least one person beneficiary must have the `UltimateBeneficialOwner` role. * Inside a nested company's own `beneficiaries`, `ubo_subtype` is optional and only `Ownership` is accepted. * The new fields appear in every dated version of the OpenAPI spec, but versions before `2026-10-15` reject them. * For US companies, individuals submitted as `Control` are listed in their own section of the generated certification. Your submission doesn't change. #### If you haven't migrated yet Every case below is a `400` that creates nothing. When the problem is on one beneficiary, the error carries its `beneficiary_index`. | What you sent | Error | Fix | | - | - | - | | A UBO without `ubo_subtype` | [`ubo_subtype_invalid`](/errors#ubo_subtype_invalid) | Set `Ownership` or `Control` | | `Control` with a `share_percentage`, or without `nature_of_control` | [`ubo_subtype_invalid`](/errors#ubo_subtype_invalid) | Remove the share and add the description | | `ubo_subtype` or `nature_of_control` on an earlier version, or without the version header | [`ubo_subtype_invalid`](/errors#ubo_subtype_invalid) | Send `X-API-Version: 2026-10-15` | | No person with the `UltimateBeneficialOwner` role | [`structure_invalid`](/errors#structure_invalid) | Add the controlling individual as a `Control` UBO | | A corporate owner whose nested people include an individual with 10% or more of the company indirectly, who isn't submitted as a UBO | [`structure_invalid`](/errors#structure_invalid) | Submit that individual as an `Ownership` UBO | | `Ownership` below the disclosure threshold | [`ubo_share_below_threshold`](/errors#ubo_share_below_threshold) | Correct the share, or use `Control` if they don't own shares | ### Incomplete Submissions A Business submission must be complete to be accepted, in every country: when required company documents are missing, the request is rejected with `400` and must be resubmitted with the missing item — nothing is created. Complete submissions are created as `Processed` directly. A `201` response means the submission was complete and accepted for verification. An incomplete submission never creates a record — it's rejected with `400` instead. Check `status` on the returned identification: `Processed` means MoonPay Enterprise has everything it needs. Sandbox approves business submissions at creation regardless of completeness. The reject-on-incomplete behavior occurs in production only. A submission is rejected with `400` when: * A required document group is missing for the company's region — including for a related company in the ownership structure. See [Company Documents](#company-documents) and, for US companies, [Automatic Verification for US Companies](#automatic-verification-for-us-companies). * The registration document is missing, for a non-US sole proprietorship. * A beneficiary of a US company provides a `DriverLicense`, `ResidencePermit`, or `DigitalDriversLicense` that isn't US-issued (`Passport` and `NationalId` are accepted from any country for these beneficiaries). `DigitalDriversLicense` is Brazil-issued only, so it's never accepted for these beneficiaries. These validations always reject the request with `400`, regardless of country: * More than 8 company documents * A document that is not valid base64, exceeds 10 MB, or has an invalid country code * A document the verification provider cannot process, such as a corrupted file. The response includes the rejection detail. Fix the file before retrying. One exception: an error naming a blocked duplicate upload means the file is fine and a retry succeeds. * No root-level beneficiary holds the `Director` role, for any company other than a non-US sole proprietorship. This is checked independently of the US attestation requirement below. See [`structure_invalid`](/errors#structure_invalid). * Ownership is disclosed (a share of 10% or more, or an owner listed without `share_percentage`) but no root-level person can be listed as an owner at 25% or more (or 10% or more, if nobody owns 25%), for any company other than a non-US sole proprietorship. Before API version `2026-10-15`, a company where nobody owns 10% or more is accepted with a root `Director`, and a non-US `PrivateFoundation` is exempt. From `2026-10-15`, submit the individual who controls the company as a `Control` beneficiary instead. A beneficiary whose only role is `Representative` doesn't count toward this — Iron never independently verifies a Representative-only beneficiary's identity, so their disclosed `share_percentage` can't count as ownership evidence. See [`structure_invalid`](/errors#structure_invalid). * A `share_percentage` outside 0-100, or combined shares of beneficiaries counted as qualifying owners (any `UltimateBeneficialOwner`, or any other beneficiary who isn't `Representative`-only) above 100 for any company in the structure * A beneficiary whose only role is `UltimateBeneficialOwner` and whose `share_percentage` doesn't meet the disclosure threshold for their company (or nested company): 25% if any beneficiary at that level owns 25% or more, otherwise 10% if any beneficiary there owns 10% or more, otherwise nobody at that level qualifies. Such a beneficiary has no other role to be reported under instead. A beneficiary below the threshold that also holds another role (for example `Director`) is accepted, but submitted without the `UltimateBeneficialOwner` tag. See [`ubo_share_below_threshold`](/errors#ubo_share_below_threshold). From API version `2026-10-15` the threshold applies to `Ownership` beneficiaries only, and a person with `ubo_subtype: "Ownership"` below it is rejected even when they hold another role. * From API version `2026-10-15`, a missing or inconsistent `ubo_subtype` or `nature_of_control`. See [`ubo_subtype_invalid`](/errors#ubo_subtype_invalid). * From API version `2026-10-15`, no person beneficiary with the `UltimateBeneficialOwner` role at a company other than a sole proprietorship. See [`structure_invalid`](/errors#structure_invalid). * A missing `tax_identification_number` for a `Director` or `UltimateBeneficialOwner` person beneficiary, in any country, or for the proprietor of a non-US sole proprietorship. For a beneficiary whose `tax_jurisdiction_country_code` is a jurisdiction that doesn't issue tax IDs, a missing `identity.identity_number` instead. See [Tax ID where none is issued](#tax-id-where-none-is-issued). * A missing `company_info.tax_identification_number`, unless the company is registered in a jurisdiction that doesn't issue tax IDs. The error identifies the beneficiary by its zero-based index in the `beneficiaries` array. * A `ResidencePermit` identity document, unless it's US-issued and the beneficiary is at a US company * A `DigitalDriversLicense` identity document, unless it's Brazil-issued * Invalid attestation data: more than one attesting party, an attesting party without the `Director` role or nested below the root, a missing or future `attested_at`, or beneficial-ownership data the generated CDD certification cannot render. See [Company Documents](#company-documents). `400` responses on this endpoint return the reason as a plain string: ```json theme={null} "Beneficiary share_percentage must be between 0 and 100" ``` ### Resubmitting and Correcting a Submission `POST /api/customers/{id}/identifications/v2` is not an upsert. Every call creates a new identification record, and the newest record drives the customer's status. Calling it a second time while the first is in flight resets the customer to `IdentificationRequired` and stops the older identification counting, even if it is approved later. Once a submission is accepted, never re-call this endpoint to correct it, to add a missing document, or to check status. Each accepted call adds another identification to the customer, and a customer carrying several competing identifications needs manual reconciliation by MoonPay Enterprise before onboarding can finish. Whether a second call is correct depends on what the first one returned. A `400` created nothing, so submitting again is the fix. A `201` created a record, so submitting again creates a competing one. | Situation | What to do | | - | - | | Request returned `400` | Nothing was created. Fix the payload and submit again. This is the normal path for an incomplete submission. See [Incomplete Submissions](#incomplete-submissions) | | You want the current state | `GET /api/customers/{id}/identifications`, or subscribe to the `identification_status` [webhook](/webhooks) | | You want the specific outstanding items | `GET /api/customers/{id}/requirements`. See [Checking Outstanding Requirements](/onboarding#checking-outstanding-requirements) | | Request timed out or returned `500` | `GET /api/customers/{id}/identifications` first. Only submit again if no record exists | | Identification reached `Declined` or `Expired` | Create a new identification. This is the one case where a second call on an existing record is correct | An `Idempotency-Key` does not protect you here. MoonPay Enterprise stores successful responses only, so a retry after an error runs the submission again. In production, resubmitting the same payload while the earlier identification is live returns `409` with `existing_identification_id` instead of a second record. A changed payload creates a new record. See [Idempotency](/idempotency). The rule above is the control that prevents duplicates. ### Example Scenarios The following examples show the `company_data.beneficiaries` array for common ownership structures. All other fields (`company_data.company_info`, `company_data.documents`, `questionnaire`) remain the same as the full example above. The person objects below are abbreviated: a real submission also carries `identity`, `tax_identification_number`, and `proof_of_address` per beneficiary, as in the full example. A company with a majority shareholder/director and a minority UBO: ```json theme={null} "beneficiaries": [ { "roles": ["Director"], "beneficiary_info": { "first_name": "Jane", "last_name": "Smith", "date_of_birth": "1985-03-22", "email_address": "jane@acme.com", "phone_number": "+4915112345678", "tax_jurisdiction_country_code": "DE", "birth_place": { "place": "Munich", "state": "Bavaria", "country": "DE" }, "address": { "street_1": "Unter den Linden 42", "city": "Berlin", "state": "Berlin", "zip_code": "10117", "country": "DE" } } }, { "roles": ["UltimateBeneficialOwner"], "share_percentage": 60, "beneficiary_info": { "first_name": "Max", "last_name": "Müller", "date_of_birth": "1978-11-05", "email_address": "max@acme.com", "phone_number": "+4915198765432", "tax_jurisdiction_country_code": "DE", "birth_place": { "place": "Hamburg", "state": "Hamburg", "country": "DE" }, "address": { "street_1": "Königstraße 10", "city": "Hamburg", "state": "Hamburg", "zip_code": "20095", "country": "DE" } } }, { "roles": ["UltimateBeneficialOwner"], "share_percentage": 40, "beneficiary_info": { "first_name": "Sophie", "last_name": "Weber", "date_of_birth": "1990-07-14", "email_address": "sophie@acme.com", "phone_number": "+4915155556666", "tax_jurisdiction_country_code": "DE", "birth_place": { "place": "Frankfurt", "state": "Hessen", "country": "DE" }, "address": { "street_1": "Goethestraße 8", "city": "Frankfurt", "state": "Hessen", "zip_code": "60313", "country": "DE" } } } ] ``` When a legal entity owns or controls the company, give it the `Shareholder` role and pass a business `beneficiary_info`: an object with a single `company_data` field. It carries the full data for that entity: its `company_info`, its own `beneficiaries`, and its own `documents`. The natural persons who are UBOs through the corporate chain appear inside the nested entity: ```json theme={null} "beneficiaries": [ { "roles": ["Director"], "beneficiary_info": { "first_name": "Jane", "last_name": "Smith", "date_of_birth": "1985-03-22", "email_address": "jane@acme.com", "phone_number": "+4915112345678", "tax_jurisdiction_country_code": "DE", "birth_place": { "place": "Munich", "state": "Bavaria", "country": "DE" }, "address": { "street_1": "Unter den Linden 42", "city": "Berlin", "state": "Berlin", "zip_code": "10117", "country": "DE" } } }, { "roles": ["Shareholder"], "share_percentage": 100, "beneficiary_info": { "company_data": { "company_info": { "company_name": "Acme Holdings GmbH", "registration_number": "HRB987654", "country": "DE", "incorporation_date": "2015-01-10", "legal_address": "Kurfürstendamm 50, 10707 Berlin", "postal_address": "Kurfürstendamm 50, 10707 Berlin", "address": { "street_1": "Kurfürstendamm 50", "city": "Berlin", "state": "Berlin", "zip_code": "10707", "country": "DE" }, "email": "info@acme-holdings.com", "tax_identification_number": "DE987654321", "website": "https://www.acme-holdings.com", "company_type": "LimitedLiabilityCompany" }, "beneficiaries": [ { "roles": ["Director", "UltimateBeneficialOwner"], "share_percentage": 100, "beneficiary_info": { "first_name": "Max", "last_name": "Müller", "date_of_birth": "1978-11-05", "email_address": "max@acme-holdings.com", "phone_number": "+4915198765432", "tax_jurisdiction_country_code": "DE", "birth_place": { "place": "Hamburg", "state": "Hamburg", "country": "DE" }, "address": { "street_1": "Königstraße 10", "city": "Hamburg", "state": "Hamburg", "zip_code": "20095", "country": "DE" } } } ], "documents": [ { "type": "IncorporationCert", "country": "DE", "file": "" }, { "type": "IncorporationArticles", "country": "DE", "file": "" }, { "type": "ShareholderRegistry", "country": "DE", "file": "" }, { "type": "DirectorsRegistry", "country": "DE", "file": "" } ] } } } ] ``` Each corporate owner carries its own `company_data.documents` and `beneficiaries`. Each corporate owner needs Company Details and Ownership Structure documents, as described in [Company Documents](#company-documents). The natural persons who ultimately own 25%+ through the chain must appear as UBOs. From API version `2026-10-15`, an individual who controls the company without owning it is a `Control` beneficiary. For example, a foundation council member with voting rights. They send `nature_of_control` and no `share_percentage`: ```json theme={null} "beneficiaries": [ { "roles": ["Director", "UltimateBeneficialOwner"], "ubo_subtype": "Control", "nature_of_control": "Member of the foundation council with voting rights", "beneficiary_info": { "first_name": "Jane", "last_name": "Smith", "date_of_birth": "1985-03-22", "email_address": "jane@acme.com", "phone_number": "+4915112345678", "tax_jurisdiction_country_code": "DE", "address": { "street_1": "Unter den Linden 42", "city": "Berlin", "state": "Berlin", "zip_code": "10117", "country": "DE" } } } ] ``` ### Business API Field Reference The request envelope has four top-level fields beyond `type`: | Field | Type | Required | Description | | - | - | - | - | | `company_data` | object | Yes | Company identity, beneficiaries, and documents (`company_info`, `beneficiaries`, `documents`) | | `phone` | string | Yes | Company phone number (international format) | | `ip_address` | string | Yes | IP address of the device used to submit the identification. Must be a public, globally routable address: private, loopback, and documentation ranges are rejected with `400`. | | `questionnaire` | object | Yes | KYB compliance questionnaire. Set `type` to `Generic` (all company types except non-US sole proprietorships) or `SoleProp` (non-US sole proprietorships only) | These fields live under `company_data.company_info`. | Field | Type | Description | | - | - | - | | `company_name` | string | Legal name of the company | | `alternative_names` | string\[] | Optional list of trading or alternative names | | `registration_number` | string | Number assigned at legal registration | | `country` | string | ISO 3166-1 alpha-2 country code of registration | | `incorporation_date` | string | Date of incorporation (YYYY-MM-DD) | | `legal_address` | string | Address used during legal registration | | `postal_address` | string | Postal address of the company | | `address` | object | Structured address (`street_1`, `street_2`, `city`, `state`, `zip_code`, `country`) | | `email` | string | Company email address | | `tax_identification_number` | string | Tax ID of the company. Required unless the company is registered in a jurisdiction that doesn't issue tax IDs, where any value sent is ignored and `registration_number` is used instead. | | `website` | string | Company website URL | | `company_type` | enum | `LimitedLiabilityCompany`, `PubliclyListedCompany`, `SoleProprietorship`, `Partnership`, `Corporation`, `Trust`, `PrivateFoundation`, `Charity`, `NonprofitCorporation`, `NonprofitOrganization`, `PublicAgenciesOrAuthorities`, `StockCorporationOutOfStock`, `GeneralCorporation` | The `company_data.beneficiaries` array contains one or more `CompanyBeneficiary` objects representing UBOs, directors, representatives, or corporate shareholders. Each business level holds up to 5 beneficiaries and at most one business beneficiary, and businesses nest at most two levels below the root company. The `Director` role is only valid on person beneficiaries. Requests outside these bounds are rejected with `400`. #### `CompanyBeneficiary` | Field | Type | Required | Description | | - | - | - | - | | `roles` | enum\[] | Yes | One or more of: `UltimateBeneficialOwner`, `Director`, `Representative`, `Shareholder` | | `share_percentage` | decimal | Conditional | Ownership percentage, 0-100. Combined `UltimateBeneficialOwner` shares must not exceed 100 per company, at the root and at every nested level. Required when roles include `UltimateBeneficialOwner`, except for `Control` beneficiaries, which send none. A person below the disclosure threshold (25%, or 10% when nobody at that level owns 25%) must hold another role too (for example `Director`) — otherwise the submission is rejected; if they do hold another role, they're accepted but submitted without the `UltimateBeneficialOwner` tag. | | `ubo_subtype` | enum | Conditional | `Ownership` or `Control`. Required when roles include `UltimateBeneficialOwner`, from API version `2026-10-15`. Rejected on earlier versions and on beneficiaries without that role. `Control` is accepted only on root-level person beneficiaries of a company that isn't a sole proprietorship. | | `nature_of_control` | string | Conditional | How the individual controls the company without owning it, for example through voting rights or a trust. Up to 255 characters. Required when `ubo_subtype` is `Control`, and rejected otherwise. | | `beneficiary_info` | object | Yes | Person or Business info. | | `attesting_party` | boolean | No | Marks this beneficiary as certifying the beneficial-ownership information (31 CFR 1010.230). At most one per submission: a root-level person beneficiary with the `Director` role. Required for every US company, sole proprietorships included: see [Company Documents](#company-documents). | | `attested_at` | string | Conditional | RFC 3339 timestamp of when the beneficiary certified the information. Must be in the past. Required when `attesting_party` is `true`. | The `beneficiary_info` field takes one of two shapes: `PersonBeneficiaryInfo` for an individual, or `BusinessBeneficiaryInfo` for a corporate owner, which carries a nested `company_data`. Unlike `questionnaire`, this object has no `type` discriminator: MoonPay Enterprise detects the variant from the fields you send. #### `PersonBeneficiaryInfo` Used when the beneficial owner is a natural person. | Field | Type | Required | Description | | - | - | - | - | | `first_name` | string | Yes | First name | | `last_name` | string | Yes | Last name | | `middle_name` | string | No | Middle name | | `date_of_birth` | string | Yes | Date of birth in `YYYY-MM-DD` format | | `tax_identification_number` | string | Conditional | SSN for US persons, otherwise a national TIN. Required for `Director` and `UltimateBeneficialOwner` person beneficiaries in any country, for a `Representative` when the root company is registered outside the US, and always for the proprietor of a non-US sole proprietorship. When `tax_jurisdiction_country_code` is a jurisdiction that doesn't issue tax IDs, any value sent is ignored and `identity.identity_number` is used instead. See [Tax ID where none is issued](#tax-id-where-none-is-issued). | | `email_address` | string | Yes | Email address. Checked for format only. It doesn't have to be on the company's domain, and it isn't compared against `company_info.email`: an external director, consultant, or outside counsel can use their own firm's address. | | `phone_number` | string | Yes | Phone number in international format (e.g. `+4915112345678`) | | `tax_jurisdiction_country_code` | string | Yes | ISO 3166-1 alpha-2 country code of tax jurisdiction | | `birth_place` | object | No | Place of birth (see `BirthPlace` below). Optional, but when provided it must be complete. | | `address` | object | Yes | Residential address (see `Address` below) | | `identity` | object | Yes | Identity document and biometric data (see `BeneficiaryIdentity` below) | | `proof_of_address` | string | No | Base64-encoded proof of address document, 10 MB max. Not currently required for any beneficiary role or country: validated (base64, size) when provided, but a missing one never blocks the submission. | #### `BeneficiaryIdentity` The `identity` object on a person beneficiary. | Field | Type | Required | Description | | - | - | - | - | | `identity_country_code` | string | Yes | ISO 3166-1 alpha-2 country code of the identity document | | `identity_document_type` | enum | Yes | `Passport`, `NationalId`, `DriverLicense`, `ResidencePermit`, or `DigitalDriversLicense`. `ResidencePermit` is rejected unless it's US-issued and the beneficiary is at a US company. `DigitalDriversLicense` is rejected unless it's Brazil-issued. Beneficiaries of US companies additionally need `DriverLicense` or `ResidencePermit` to be US-issued (`Passport` and `NationalId` are accepted from any country): see [Identity Verification](#identity-verification-/-liveness-check). | | `identity_document_front` | string | Yes | Base64-encoded image of the document front, 10 MB max | | `identity_document_back` | string | Conditional | Base64-encoded image of the document back, 10 MB max. Required for `NationalId`, `DriverLicense`, and `ResidencePermit`. `Passport` and `DigitalDriversLicense` need the front only. | | `identity_document_valid_until` | string | No | Expiry date of the identity document, `YYYY-MM-DD`. Send it when the document has one. | | `identity_number` | string | Conditional | Number printed on the identity document. Required in place of `tax_identification_number` when the beneficiary needs a tax ID and `tax_jurisdiction_country_code` is a jurisdiction that doesn't issue tax IDs. | | `selfie` | string | Conditional | Base64-encoded selfie, 10 MB max. Required for every `Director`, in any country. Required for a `Representative` when the root company is registered outside the US. Not required for `UltimateBeneficialOwner`- or `Shareholder`-only beneficiaries. | | `selfie_collected_at` | string | Conditional | ISO 8601 timestamp of when the selfie was captured. Provide it together with `selfie`. | | `nationality` | string | Yes | ISO 3166-1 alpha-2 country code of nationality | #### `BusinessBeneficiaryInfo` Used when a beneficial owner is a legal entity (corporate shareholder). It carries a full `company_data` with the same shape as the top level, so the same information is collected at every level of the corporate structure. | Field | Type | Required | Description | | - | - | - | - | | `company_data` | object | Yes | `company_info`, `beneficiaries`, and `documents` for this entity. Same schema as the top-level `company_data`. Nesting continues through further business beneficiaries. | Each corporate owner carries its own `company_data.documents` and `beneficiaries`. Each corporate owner needs Company Details and Ownership Structure documents, as described in [Company Documents](#company-documents). The natural persons who ultimately own 25%+ through the chain must appear as UBOs. #### `BirthPlace` | Field | Type | Required | Description | | - | - | - | - | | `place` | string | Yes | City or town of birth | | `state` | string | Conditional | State or region of birth. Required for countries with administrative subdivisions, omit it for countries without any (Vatican City, for example). | | `country` | string | Yes | ISO 3166-1 alpha-2 country code | #### `Address` | Field | Type | Required | Description | | - | - | - | - | | `street_1` | string | Yes | Street address | | `street_2` | string | No | Additional street address | | `city` | string | Yes | City | | `state` | string | Conditional | State, province, or region. Required on the company address for countries with administrative subdivisions. | | `zip_code` | string | Yes | Postal / ZIP code | | `country` | string | Yes | ISO 3166-1 alpha-2 country code | The `company_data.documents` array contains up to 8 `CompanyDocParams` objects. Each document is uploaded as a base64-encoded file. Structurally optional at submission, but an incomplete set for the company's region is rejected with `400`. See [Company Documents](#company-documents) for the groups required per region. #### `CompanyDocParams` | Field | Type | Required | Description | | - | - | - | - | | `type` | enum | Yes | Document type (see table below) | | `country` | string | Yes | ISO 3166-1 alpha-2 country code of the issuing country | | `file` | string | Yes | Base64-encoded document content **without** the `data:` URI prefix | #### Upload requirements * Maximum file size: **10 MB** per document (after base64 decoding) * Maximum 8 documents per company. The limit applies separately to the root company and to each nested business beneficiary. More than 8 is rejected with `400`. * Encoding: standard base64 (no `data:application/pdf;base64,` prefix) * Supported formats: PDF, JPEG, PNG #### Document types | Value | Description | | - | - | | `PowerOfAttorney` | Power of attorney | | `TransparencyRegistryExtract` | Recent excerpt from a transparency company registry | | `DirectorsRegistry` | Directors registry | | `GoodStandingCert` | Certificate of good standing | | `IncorporationArticles` | Memorandum, articles of incorporation, association, or registration | | `IncorporationCert` | Certificate of incorporation or registration | | `IncumbencyCert` | Certificate of incumbency | | `InformationStatement` | Statement of information | | `PartnershipAgreement` | Partnership agreement | | `ProofOfAddress` | Proof of address (e.g. utility bill, rent contract) | | `ProofOfNatureOfBusiness` | Proof of nature of business | | `RegulatoryLicense` | Regulatory or operating license | | `SelfDeclarationForm` | Self-declaration form | | `ShareholderRegistry` | Shareholder registry | | `StateRegistry` | Recent excerpt from a state company registry | | `TradeLicense` | Commercial or trading license | | `TrustAgreement` | Trust agreement | | `Other` | Other document not covered by the types above | The `BusinessQuestionnaire` object is a required compliance questionnaire structured into three sections. Each section collects specific regulatory information about the business. Set `type` to `Generic` for all company types except non-US sole proprietorships, or `SoleProp` for non-US sole proprietorships. ```json theme={null} { "questionnaire": { "type": "Generic", "business_details": { ... }, "planned_activities": { ... }, "source_of_funds": { ... } } } ``` **Currency of the revenue and volume bands.** The numbers in `estimated_monthly_volume` (and, on the `SoleProp` questionnaire, `estimated_annual_revenue`) are band boundaries, not a currency requirement: read them in the currency the business reports in, so a company reporting 60,000 USD sends `FiftyToOneHundredThousand`. Do not convert at an FX rate, and note that there is no separate band set per currency. Neither field sets a transaction limit. #### `business_details` Industry classification and operational information about the company. | Field | Type | Required | Description | | - | - | - | - | | `industry_type` | enum | Yes | Industry sector classification (see values below) | | `industry` | enum | Required from `2026-08-01`, optional before | Full granular industry classification. See [`industry` values](#industry-values). | | `business_model_description` | string | Yes | Description of the business model and target clients. Minimum 80 characters. | | `main_business_countries` | string\[] | Yes | ISO 3166-1 alpha-2 country codes where the company primarily operates | | `has_licenses_or_registrations` | boolean | Yes | Whether the company currently holds any licenses or registrations | | `license_details` | string | Conditional | Required if `has_licenses_or_registrations` is `true`. Describe the licenses or registrations the company holds. | **`industry_type` values:** `Agriculture`, `Automotive`, `BankingAndFinancialServices`, `ConstructionAndRealEstate`, `CryptocurrencyAndBlockchain`, `CryptocurrencyMining`, `DecentralisedFinance`, `NftPlatforms`, `CryptoPaymentProcessors`, `CryptoWalletProviders`, `CryptoExchanges`, `CryptoCustodyServices`, `EcommerceAndOnlineMarketplaces`, `EducationAndTraining`, `EnergyAndUtilities`, `EntertainmentAndMedia`, `GamingAndEsports`, `HealthcareAndPharmaceuticals`, `HospitalityAndTourism`, `InformationTechnologyAndSoftware`, `Insurance`, `LegalAndProfessionalServices`, `LogisticsAndTransportation`, `ManufacturingAndIndustrial`, `MetaversePlatforms`, `MiningAndNaturalResources`, `NonProfitAndCharitable`, `RetailAndWholesaleTrade`, `Telecommunications`, `VentureCapitalAndPrivateEquity`, `CasinosAndGambling`, `MoneyServiceBusinesses`, `SocialMediaAndNetworking`, `CrowdfundingPlatforms`, `RegTech`, `Other` `industry_type` is deprecated but still accepted indefinitely. `industry` is the modern replacement, exposing the full industry taxonomy (136 values) in place of the 36 broad categories above, and is required from API version `2026-08-01` onward. Before that version it stays optional and `industry_type` alone is sufficient. If a submission includes both fields, `industry` takes precedence and `industry_type` is ignored. MoonPay Enterprise doesn't use NAICS, SIC, or MCC codes, and there's no mapping from those schemes to these fields. Classify the company directly against the [`industry` values](#industry-values). Don't classify a company under a catch-all value. `industry: "Miscellaneous"` is rejected with [`miscellaneous_industry_deprecated`](/errors#miscellaneous_industry_deprecated) on every submission, however detailed `business_model_description` is. The deprecated `industry_type` values `Other` and `NonProfitAndCharitable` pass validation, but both resolve to `Miscellaneous` internally and are sent for review that way, which slows the review and can produce a request for more information later. Pick the closest specific `industry` value instead. The full list is in the appendix: [Industry Values](#industry-values). **`estimated_annual_revenue` values** (`SoleProp` questionnaire only): | Value | Range | | - | - | | `Under100K` | 0 - 99,999 | | `From100KTo1M` | 100,000 - 999,999 | | `From1MTo10M` | 1,000,000 - 9,999,999 | | `From10MTo50M` | 10,000,000 - 49,999,999 | | `From50MTo250M` | 50,000,000 - 249,999,999 | | `Over250M` | 250,000,000+ | #### `planned_activities` Information about the company's intended account use and expected transaction patterns. | Field | Type | Required | Description | | - | - | - | - | | `purpose_and_intended_use` | enum | Yes | Primary purpose of the business account | | `estimated_monthly_volume` | enum | Yes | Expected monthly transaction volume bracket. See the currency note above. | | `estimated_monthly_transactions` | enum | Yes | Expected number of transactions per month | | `sends_funds_on_customer_behalf` | boolean | Yes | Whether the company sends funds on behalf of customers or third parties | | `sends_funds_on_customer_behalf_description` | string | Conditional | Required if `sends_funds_on_customer_behalf` is `true`. Describe how funds are sent. | | `flow_of_funds_diagram` | string | Conditional | Base64-encoded flow of funds diagram, 10 MB max. Required if `sends_funds_on_customer_behalf` is `true`. | | `source_of_funds_document` | string | Conditional | Base64-encoded source of funds supporting document, 10 MB max. Required if `sends_funds_on_customer_behalf` is `true`. | **`purpose_and_intended_use` values:** `ReceivingBusinessIncome`, `BusinessPurchasesAndExpenses`, `EmployeeAndContractorPayouts`, `EcommerceSales`, `TreasuryManagement`, `PaymentIntermediary`, `Investments`, `TaxPlanning`, `AssetProtection`, `Other` **`estimated_monthly_volume` values:** | Value | Range | | - | - | | `TenToTwentyFiveThousand` | 10,000 - 25,000 | | `TwentyFiveToFiftyThousand` | 25,000 - 50,000 | | `FiftyToOneHundredThousand` | 50,000 - 100,000 | | `OneHundredToTwoHundredFiftyThousand` | 100,000 - 250,000 | | `TwoHundredFiftyToFiveHundredThousand` | 250,000 - 500,000 | | `MoreThanFiveHundredThousand` | 500,000+ | **`estimated_monthly_transactions` values:** | Value | Range | | - | - | | `LessThanTen` | Fewer than 10 | | `TenToTwentyFive` | 10 - 25 | | `TwentyFiveToFifty` | 25 - 50 | | `FiftyToOneHundred` | 50 - 100 | | `MoreThanOneHundred` | More than 100 | #### `source_of_funds` Information about where the company's funds originate. | Field | Type | Required | Description | | - | - | - | - | | `source_of_funds` | enum | Yes | Primary source of the company's funds | | `source_of_funds_description` | string | Yes | Detailed description of the source of funds | **`source_of_funds` values:** `BusinessRevenue`, `ShareholderFunds`, `VcPrivateEquity`, `AssetSale`, `IcoProceeds`, `CryptoActivityProceeds`, `LoanProceeds`, `Other` *** ## Standard KYB Requirements ### Company Information * Country * Company name * Registration number * Company registration address * Company operations address * Type of entity * Date of registration * Website * Company email * Tax ID ### Company Documents Company documents fall into four groups. Which groups the root company needs depends on where it's registered and its type. A nested business beneficiary (a `Shareholder` that's a legal entity) always needs just two groups — Company Details and Ownership Structure — regardless of where it's registered or what the root company needs. | Company profile | Required document groups | | - | - | | Root, registered outside the US, all types except sole proprietorships | One document from each group: Company Details, Legal Presence, Ownership Structure, Control and Management Structure | | Root, registered in the US, all types | Company Details only. Legal Presence and Control and Management Structure are not required. Ownership Structure is always satisfied by a mandatory generated CDD certification (see the note below) — and Company Details itself is waived when MoonPay Enterprise can verify the company automatically (see [Automatic Verification for US Companies](#automatic-verification-for-us-companies)). | | Sole proprietorship, registered outside the US | Incorporation certificate (`IncorporationCert`) | | Nested business beneficiary, any country | Company Details and Ownership Structure only. Legal Presence and Control and Management Structure are never required, and the CDD certification doesn't apply — a nested entity always needs a real Ownership Structure document. | A submission missing a required group is rejected with `400`, in every country, and must be resubmitted with the missing item. See [Incomplete Submissions](#incomplete-submissions). Every US company submission must designate one root person beneficiary holding the `Director` role as the attesting party: set `attesting_party: true` and `attested_at` on them, after presenting the collected beneficial-ownership information to them for confirmation. MoonPay Enterprise generates a CDD certification (31 CFR 1010.230) from the submitted data and files it, satisfying the Ownership Structure group without a separately uploaded document. This is mandatory, not optional — a submission missing an attesting party, or one that cannot produce the certification (missing `share_percentage` on a beneficiary the certification must list, no SSN or tax/identity number for a listed US person, or more than two levels of beneficiaries), is rejected with `400`. The certification's ownership section lists whichever beneficiaries own 25% or more; if nobody does, it falls back to listing whoever owns 10% or more instead. From API version `2026-10-15`, individuals submitted as `Control` beneficiaries are listed in a separate section of the certification, with their `nature_of_control`. See the qualifying-owner requirement below for when a company with no owner at either threshold is accepted. ### Automatic Verification for US Companies Eligible US companies are checked automatically against official company records as part of verification. When MoonPay Enterprise can confirm the company this way, the Company Details document isn't required — the automatic match satisfies it. This happens without any extra input from you; we still recommend sending the Company Details document anyway, since it's the fastest way to speed up review if automatic verification isn't possible for a given company. The CDD attestation above is still required either way, whether or not automatic verification succeeds. Accepted document types: * Incorporation certificate (`IncorporationCert`) * Excerpt from a state company registry (`StateRegistry`) * Certificate of good standing (`GoodStandingCert`) Accepted document types: * Articles and memorandum of association (`IncorporationArticles`) Accepted document types: * Shareholder registry (`ShareholderRegistry`) * Statement of information (`InformationStatement`) * Trust agreement (`TrustAgreement`) * Certificate of incumbency (`IncumbencyCert`) The document must list all shareholders with their ownership percentages (totaling 100%), be dated within the last 12 months, and signed by a director unless publicly available. **KYC checks:** Each UBO with 25%+ ownership and all company directors must complete KYC (Proof of ID) and be individually approved before onboarding. If there is no UBO who owns 25%+, all UBOs with 10%+ ownership must be verified. **KYB checks:** Apply to all legal entities in the ownership chain. For each additional entity, the same information is required unless ownership can be verified through open sources. Accepted document types (any that contains information about appointed directors): * Director registry (`DirectorsRegistry`) * Trust agreement (`TrustAgreement`) * Statement of information (`InformationStatement`) * Certificate of incumbency (`IncumbencyCert`) ### Business Questionnaire | Section | Question | Answers | | - | - | - | | Business information | Industry type | Agriculture, Automotive, Banking and Financial Services, Construction and Real Estate, Cryptocurrency and Blockchain, Cryptocurrency Mining, DeFi, NFT Platforms, Crypto Payment Processors, Crypto Wallet Providers, Crypto Exchanges, Crypto Custody Services, E-commerce and Online Marketplaces, Education and Training, Energy and Utilities, Entertainment and Media, Gaming and Esports, Healthcare and Pharmaceuticals, Hospitality and Tourism, Information Technology and Software Development, Insurance, Legal and Professional Services, Logistics and Transportation, Manufacturing and Industrial, Metaverse Platforms, Mining and Natural Resources, Non-Profit and Charitable Organizations, Retail and Wholesale Trade, Telecommunications, Venture Capital and Private Equity, Casinos and Gambling, Money Service Businesses, Social Media and Networking Platforms, Crowdfunding Platforms, RegTech, Other | | Business information | Business description | Free text | | Business information | Main countries of operation | Dropdown country selection | | Business information | Licensed or registered | Yes / No | | Business information | Licenses or registrations required in jurisdiction | Yes / No | | Business information | Estimated annual revenue | Up to 99,999, 100,000-999,999, 1,000,000-9,999,999, 10,000,000-49,999,999, 50,000,000-249,999,999, More than 250,000,000 | | Source of funds | Source of funds | Business revenue, Shareholder funds, VC or private equity, Sale of assets, ICO proceeds, Crypto related income, Loan proceeds, Other | | Source of funds | Customer funds details | Free text | | Planned activities | Purpose and intended use | Receiving income, Expenses, Payouts, E-commerce sales, Treasury management, Payment intermediary, Investments, Tax planning, Asset protection, Other | | Planned activities | Estimated monthly volume | 10,000-25,000, 25,000-50,000, 50,000-100,000, 100,000-250,000, 250,000-500,000, More than 500,000 | | Planned activities | Monthly transaction count | Less than 10, 10-25, 25-50, 50-100, More than 100 | | Planned activities | Send funds on behalf of customers | Yes / No | The revenue and volume figures are band boundaries, not a currency requirement. Read them in the currency the business reports in, and do not convert at an FX rate. Neither answer sets a transaction limit. Upload a Source of Funds document whenever `sends_funds_on_customer_behalf` is `true`, in any currency. ### Associated Parties | Party Type | Description | | - | - | | UBO (Ultimate Beneficial Owner) | Always a natural person. Direct or indirect ownership above 25% (or 10% in high-risk cases). | | Director | Individual(s) formally appointed as director(s). | | Representative | Authorized individual acting on behalf of the company. | | Shareholder | Direct ownership above 25%. A legal entity, or a natural person whose only role is shareholder. | Example: Business Customer → owned by Company A → John Smith owns Company A → Company A is Shareholder, John Smith is UBO. ### Required Information by Party Type * First name * Last name * Middle name * Date of birth * Email * Contact number * Nationality * Percentage of ownership * Tax ID: SSN for US persons, otherwise a national TIN. Always required, in any country, including for the proprietor of a non-US sole proprietorship. * Address details * First name * Last name * Middle name * Date of birth * Email * Contact number * Nationality * Tax ID: always required for a `Director`, in any country. Required for a `Representative` only when the root company is registered outside the US. * Address details * Country * Company name * Registration number * Certificate of incorporation * Shareholder Registry or Register of Members or Excerpt from state companies registry (if it contains ownership data) ### Tax ID where none is issued Some jurisdictions don't issue tax IDs. When a party's tax residence is one of them, you don't need to send a tax ID. Any `tax_identification_number` you send is ignored, and MoonPay Enterprise uses an identifier from the submission instead: * **Person beneficiary:** `identity.identity_number`, from any identity document type. Tax residence is `tax_jurisdiction_country_code`. If the beneficiary's role needs a tax ID, `identity.identity_number` is required and a missing one returns [`tin_required`](/errors#tin_required). * **Company** (the root company or a nested business beneficiary): `registration_number`. Tax residence is `company_info.country`. US persons, meaning a US address, US nationality, or a US-issued identity document, are never covered by this. Send their SSN or ITIN as usual. Proof of address is not currently required for any person beneficiary, in any country. It's validated (base64, size) when provided, but a missing one never blocks the submission. ### Identity Verification / Liveness Check For business customers, there are typically 2-3 types of people to identify, depending on whether an authorized representative is appointed: | Party | Requirements | | - | - | | Director(s) | ID collection + liveness check, in any country | | UBO(s) | ID collection. Liveness check only if also a director | | Authorized Representative | ID collection + power of attorney signed by the company's director. Liveness check required outside the US only | Accepted identity documents are `Passport`, `NationalId`, `DriverLicense`, `ResidencePermit`, and `DigitalDriversLicense`. A `ResidencePermit` is rejected unless it's US-issued and the beneficiary is at a US company. A `DigitalDriversLicense` is rejected unless it's Brazil-issued. Beneficiaries of US companies additionally need `DriverLicense` or `ResidencePermit` to be US-issued (`Passport` and `NationalId` are accepted from any country): any other combination is rejected with `400`, not held pending. ### Sole Proprietor Onboarding This simplified onboarding path applies to **non-US sole proprietorships only**. A US sole proprietorship (`company_type: "SoleProprietorship"` with `company_data.company_info.country: "US"`) follows the standard business flow for documents, the attesting party, and the questionnaire — the standard US document set, a mandatory attesting party, and the `Generic` questionnaire, same as any other US company. See [Company Documents](#company-documents), [Required Information by Party Type](#required-information-by-party-type), and the attesting-party note above. Unlike a US LLC or corporation, though, a US sole proprietorship is still structurally a single owner: it must submit **exactly one** root-level beneficiary, who cannot be a business. That one beneficiary holds `UltimateBeneficialOwner` at 100% share, the `Director` role, and is the attesting party, all at once — it's the same person wearing three hats, not three separate beneficiaries. Submitting more than one beneficiary, or a beneficiary who doesn't own 100%, is rejected. See [`structure_invalid`](/errors#structure_invalid). Non-US sole proprietors use the same onboarding paths as any other business. Pass `company_type: "SoleProprietorship"` to the Hosted Link flow or the Programmatic Business API. The Hosted Link flow automatically adapts its UI to the smaller sole-proprietor data set. The Programmatic API uses the same wire schema as any business: the proprietor must be submitted as exactly one person beneficiary with the `UltimateBeneficialOwner` role at 100% share. Anything else is rejected with `400`. For non-US sole proprietors, set `questionnaire.type` to `"SoleProp"`. This is a simplified variant of the business questionnaire with fewer required fields. Non-US sole proprietorships need one company document: the incorporation certificate (`IncorporationCert`). Proof of address is not required for the proprietor. A non-US sole proprietorship missing the incorporation certificate is rejected with `400`. See [Incomplete Submissions](#incomplete-submissions). The hosted sole-proprietor flow walks the customer through four verification steps: * Country * Company name * Incorporated on * Registration number * Website * Custom field: Doing Business As Sole Proprietor Information (sets `questionnaire.type` to `"SoleProp"`). * Certificate of incorporation or registration The proprietor as a single UBO: * First name * Last name * Date of birth * Email * Phone * TIN ```json theme={null} { "type": "Business", "phone": "+442071234567", "ip_address": "8.8.8.8", "company_data": { "company_info": { "company_name": "Jane's Consulting Ltd", "alternative_names": null, "registration_number": "SC123456", "country": "GB", "incorporation_date": "2020-01-15", "legal_address": "10 Downing Street, London, SW1A 2AA", "postal_address": "10 Downing Street, London, SW1A 2AA", "address": { "street_1": "10 Downing Street", "street_2": null, "city": "London", "state": "London", "zip_code": "SW1A 2AA", "country": "GB" }, "email": "jane@janesconsulting.co.uk", "tax_identification_number": "GB123456789", "website": "https://janesconsulting.co.uk", "company_type": "SoleProprietorship" }, "beneficiaries": [ { "roles": ["UltimateBeneficialOwner"], "share_percentage": 100, "beneficiary_info": { "first_name": "Jane", "middle_name": null, "last_name": "Doe", "date_of_birth": "1985-06-15", "tax_identification_number": "GB987654321", "address": { "street_1": "10 Downing Street", "street_2": null, "city": "London", "state": null, "zip_code": "SW1A 2AA", "country": "GB" }, "email_address": "jane@janesconsulting.co.uk", "phone_number": "+442071234567", "tax_jurisdiction_country_code": "GB", "birth_place": { "place": "Manchester", "state": "England", "country": "GB" }, "identity": { "identity_country_code": "GB", "identity_number": null, "identity_document_type": "Passport", "identity_document_front": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAAFklEQVR42mP4z8BAEmIY1TCqYfhqAACQ+f8B8u7oVwAAAABJRU5ErkJggg==", "identity_document_back": null, "nationality": "GB" }, "proof_of_address": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAAFUlEQVR42mNgYPhPIhrVMKph2GoAAJLb/wHQPqPSAAAAAElFTkSuQmCC" } } ], "documents": [ { "type": "IncorporationCert", "country": "GB", "file": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAAFklEQVR42mP4f+A0SYhhVMOohuGrAQDBXYofzKX3pgAAAABJRU5ErkJggg==" } ] }, "questionnaire": { "type": "SoleProp", "planned_activities": { "purpose_and_intended_use": "ReceivingBusinessIncome", "estimated_monthly_volume": "TenToTwentyFiveThousand", "estimated_monthly_transactions": "LessThanTen" }, "source_of_funds": { "source_of_funds": "BusinessRevenue" }, "business_details": { "industry_type": "LegalAndProfessionalServices", "business_model_description": "Independent consulting services for small businesses, focused on operations and financial strategy", "main_business_countries": ["GB"], "estimated_annual_revenue": "Under100K" } } } ``` ## Enhanced KYB Due Diligence Business customer risk is defined through a customer risk rating process, calculating the risk score based on different factors: geography, industry, use of product, expected activities, legal form, etc. | Requirement | Details | | - | - | | KYB Information | Standard KYB | | UBO Information | Individuals holding 10%+ ownership | | Source of Wealth | Financial document outlining the corporate entity's ability to continue business | ## Appendix Industry Values `business_details.industry` accepts 136 values. 109 are accepted for onboarding. The other 27 are the 26 [prohibited industries](#prohibited-industries), rejected with [`prohibited_industry`](/errors#prohibited_industry), plus `Miscellaneous`, rejected with [`miscellaneous_industry_deprecated`](/errors#miscellaneous_industry_deprecated). These are MoonPay Enterprise's own values. NAICS, SIC, and MCC codes aren't used and don't map onto them. **Accepted values:** `Advertising`, `Aerospace`, `AgricultureAndFarming`, `Alcohol`, `ArmoredCourierServices`, `Art`, `ArtificialIntelligence`, `ATMs`, `AuctioneersAndBrokers`, `BankingAsAService`, `Biotechnology`, `BlockchainAdTech`, `BlockchainAssetManagement`, `BlockchainDeveloperTech`, `BlockchainUtilities`, `BuildingMaterialsAndSupplies`, `BusinessServices`, `BuyNowPayLaterBNPL`, `CentralizedCryptoExchangesAndTrading`, `CleaningProductsAndServices`, `CloudComputing`, `CollectibleCards`, `CommissionAgents`, `Commodities`, `ComputerHardware`, `Consulting`, `ConsumerElectronics`, `ConsumerGoods`, `ConsumerProducts`, `Crafts`, `CryptoExchange`, `CryptoHedgeFund`, `CryptoMining`, `CryptoNews`, `CryptoPayroll`, `Culture`, `CustodialWallet`, `Cybersecurity`, `DataStorageAndManagement`, `DecentralizedCryptoExchangeAndTrading`, `DeFiDecentralizedFinance`, `Design`, `DigitalBrokerage`, `ElectricVehicles`, `EmbassiesConsulatesMissions`, `EnvironmentalServices`, `EscrowServices`, `Events`, `FabricsAndTextiles`, `Fashion`, `Fintech`, `FoodAndBeverage`, `GamblingHostingEnvironmentsWebsites`, `GamblingPaymentProcessors`, `GamblingSoftware`, `Government`, `GovernmentIDsDocumentsUniforms`, `Heavy`, `HighNetWorthIndividualExclusiveServices`, `Hospitality`, `ImmersiveExperience`, `InformationTechnology`, `LeisureAndRecreation`, `LicensedPharmaceuticals`, `LogisticsAndSupplyChain`, `LoyaltyRewardsAndUserEngagementTool`, `LuxuryGoods`, `MachineryAndHeavyEquipmentManufacturing`, `Media`, `MedicalDevicesAndSupplies`, `Music`, `NeobanksChallengerBanks`, `NFTMarketplace`, `NonCustodialWallet`, `OTCTrading`, `PawnBrokers`, `PersonalServices`, `PetCareAndSupplies`, `Photography`, `PoliticalOrganizationsPACs`, `PredictionMarkets`, `Printing`, `PrivateBankingWealthManagement`, `ProfessionalServices`, `Publishing`, `RealEstate`, `RestaurantsAndFoodServices`, `Retail`, `Robotics`, `ScrapyardDealers`, `Security`, `SkinsLootBoxTrading`, `Software`, `Space`, `SportsAndFitness`, `SustainableAndEthical`, `Technology`, `Telecom`, `ThirdPartyPaymentProcessors`, `TicketBrokersAgencies`, `Timeshare`, `ToolsAndHardware`, `ToysAndGames`, `TraditionalProducts`, `Transportation`, `TravelAndTourism`, `TrustAndCompanyServiceProvidersTCSP`, `Utilities`, `WasteManagement` ### Prohibited Industries The following business activities are prohibited from using MoonPay Enterprise's services to ensure alignment with regulatory expectations and MoonPay Enterprise's risk appetite. A submission whose resolved industry is one of these is rejected with [`prohibited_industry`](/errors#prohibited_industry). The first column is the literal `business_details.industry` value to check against on your side. No `industry_type` value currently resolves to a prohibited industry, so the block only fires on `industry`. | `industry` value | Activity | | - | - | | `ForeignCorrespondentBanking` | Foreign Correspondent Banking | | `Chemical` | Chemical | | `DefenseMilitary` | Defense/Military | | `MultiLevelMarketing` | Multi-Level Marketing | | `TobaccoNicotineVapes` | Tobacco/Nicotine/Vapes | | `Cannabis` | Cannabis | | `WeaponsKnivesGuns` | Weapons/Knives/Guns | | `BailBondsmanBailiffServices` | Bail Bondsman / Bailiff Services | | `Nutraceuticals` | Nutraceuticals | | `CarDealership` | Car Dealership | | `Pharmaceutical` | Pharmaceutical | | `DiamondIndustry` | Diamond Industry | | `NomineeShareholderBearerShareEntities` | Nominee Shareholder / Bearer Share Entities | | `AdultEntertainment` | Adult Entertainment | | `DatingServices` | Dating Services | | `GemsOrPreciousMetalsDealership` | Gems or Precious Metals Dealership | | `SexualServices` | Sexual Services | | `AntiquesAndCollectibles` | Antiques and Collectibles | | `PrePaidCards` | Pre-Paid Cards | | `ExoticAnimals` | Exotic Animals | | `PrivateMilitaryOrSecurity` | Private Military or Security | | `CashFundedRemittances` | Cash-Funded Remittances | | `JewelryOrWatches` | Jewelry or Watches | | `FXTrading` | FX Trading | | `BinaryOptions` | Binary Options | | `CreditServices` | Credit Services | Don't resubmit a rejected company under a different, less accurate industry. Contact support to discuss an exception instead. ### Foundations Foundations (`company_type: PrivateFoundation`) are subject to additional restrictions on the account purposes Iron can onboard them for. If your foundation doesn't fit within these restrictions, contact us to explore whether onboarding is possible. ### Business Ownership and Constitutional Documents To comply with MoonPay Enterprise's KYB requirements, all businesses must provide clear, official documentation that reliably verifies their complete ownership structure, ultimate beneficial owners (UBOs), controlling individuals, and confirms the existence and ongoing operations of the legal entity. If the entity does not have individual beneficial shareholders, we will need to confirm the individuals who significantly control the entity instead, such as its directors and officers. **Supported entity types:** * Sole Proprietorships * Partnerships * LLCs & Corporations * Trusts * Nonprofits * DAOs * Cooperatives ### Required Documentation per Entity Type This lightweight documentation applies to **non-US sole proprietorships only**. A US sole proprietorship must instead provide the standard LLCs and Corporations-equivalent documentation for a US company — see [Company Documents](#company-documents) and [Sole Proprietor Onboarding](#sole-proprietor-onboarding). * Official sole proprietorship license or registration document clearly naming the sole proprietor and confirming active operation * Recent tax filings or official government-issued documents linking the proprietor to business operations * Partnership agreements officially certified or notarized, detailing partners and ownership shares * Officially issued partnership registration certificates clearly listing partners and their shares * Articles of Incorporation or Articles of Organization issued by the official business registry, clearly listing shareholders/members * Official shareholder/membership register or certified extracts from commercial registries clearly indicating owners and ownership percentages * Share certificates officially verified or notarized * Recent audited financial statements (for publicly traded or regulated entities), confirming the company's operations and ownership * Official trust deed or certificate clearly identifying trustees, settlors, protectors (if applicable), and beneficiaries * Notarized trustee affidavit clearly verifying trustee identity, roles, and authorities * Official formation documents (e.g., Articles of Incorporation) clearly listing controlling individuals (e.g., directors or board members) * Government-issued or officially filed annual reports or governance documents confirming ongoing operations and key individuals * Official governance documents or independently audited membership agreements clearly outlining membership, control mechanisms, and operational status * Official formation documents clearly identifying cooperative members * Independently certified membership ledgers or agreements clearly indicating members and voting rights ### Document Verification Standards All provided documents must be issued by an official governmental authority and, where applicable, certified by a notary public, lawyer, auditor, or similar independent professional, with Apostille certification where applicable. * Must be officially issued by governmental authorities * Must be verifiable online through an official registry or database (if not possible, must be independently certified) * Apostille certification or equivalent legalization required where applicable * Self-generated or internally-produced documents are NOT acceptable * Must clearly display the full legal name and registration code of the business entity * If ownership structure involves more than two layers, a clear organizational chart with ownership percentages is required * Must be recent (issued within the past three months) * Documents not in English must include certified translations Documents must clearly confirm: * The legal existence of the entity * Its current operational status * Clear identification of ultimate beneficial owners, controlling individuals, and precise ownership percentages * Self-generated, internal, unsigned, or informal documents * Simple printouts, screenshots, or unofficial emails * Internally prepared capitalization tables (unless provided by reputable equity management services) ### Requirements for Regulated Entities Entities that operate under regulatory supervision must provide additional documentation to confirm their licensing status and compliance with AML/CFT regulations. #### Regulatory Licenses and Authorizations A valid license or authorization issued by the relevant financial regulator or supervisory authority permitting the entity to conduct its business activities. If the license or authorization is not publicly accessible online, it must be certified by the issuing authority or a notary public. #### AML/CFT Policy and Procedures A copy of the entity's internal AML/CFT policy, outlining its approach to: * Customer due diligence (CDD) and enhanced due diligence (EDD) * Transaction monitoring processes * Suspicious activity reporting procedures * Sanctions screening and PEP checks - The policy must be approved by senior management and aligned with the applicable jurisdiction's AML laws and regulations - Licenses and authorizations must be verifiable online (if not, must be certified by the issuing authority, a notary public, or a licensed legal/audit professional) - The submitted AML/CFT policy must be an officially approved internal document (not a draft or template)