This is the human-readable version.
GET /spec/versions lists the supported versions machine-readably, and each version’s full shape is at /spec/<date>. See API Versions for the header itself.2026-08-01
Customers sign the terms and conditions before identification.
A customer created on this version starts in
SigningsRequired instead of IdentificationRequired: the terms carry the data-sharing agreement, so acceptance now comes before MoonPay Enterprise collects KYC data.
GET /customers/{id}/required-signings also changes: when nothing is outstanding it returns 200 with an empty list, where earlier versions return 409 Conflict.
Because the lifecycle plays out in webhooks and background work with no request header to read, this version is pinned to the customer when you create it and drives that customer’s onboarding for its lifetime. Customers created earlier keep the original order whatever header you send later, so adopting it only affects customers created from then on. See Onboarding.
On its initial release, an empty list from
required-signings did not always mean “nothing to sign”: before identification was approved there was no verified region to derive terms from, so a customer in SigningsRequired also returned 200 [], and you had to fetch the terms with GET /terms-and-conditions?country={ISO3} instead. The update below removed that ambiguity — required-signings now returns the outstanding document at any point in the lifecycle, including before identification.This version cannot be verified from the OpenAPI document alone — the shapes are identical to
2026-07-01. Rehearse the status sequence in sandbox, which reproduces the pre-identification flow including the empty required-signings response.required-signings and terms-and-conditions?country= return has changed: MoonPay Enterprise now serves one global document to every customer created on this version, rather than a document specific to their country’s region. Response shapes are unchanged — you still get a list of {id, url, display_name} — and country is still a required parameter on GET /terms-and-conditions?country={ISO3} for backward compatibility, but its value no longer affects which document comes back.
The region-mismatch re-sign case this section originally described (validating the signed terms against the verified identification’s region, and asking for a re-sign on a mismatch) no longer applies to customers created on this version: there is only one document to sign, so nothing to mismatch against.
GET /customers/{id}/required-signings also covers the whole lifecycle for these customers, returning the outstanding document before identification as well as after — so a single code path replaces the earlier split between terms-and-conditions?country= and required-signings. country is still accepted for backward compatibility. Note that re-signing does not disappear entirely: publishing a new document still returns affected customers to SigningsRequired. See Signing new terms later.
Identification failures return structured, machine-readable errors.
A failed
Business, Person, or Token identification submission now returns 400 with an array of {code, message, docs_url, beneficiary_index} objects instead of a plain error string, so your integration can branch on code instead of pattern-matching English text. See Identification Errors for the full list of codes.
Most checks return a single entry, but the four document-requirement codes (company_details_required, legal_presence_required, ownership_structure_required, control_structure_required) can each appear once per company in the submission that’s missing that group — a non-US Business submission checks all four independently, so several can genuinely be missing at once.
Callers on an earlier or unversioned
X-API-Version keep receiving today’s plain error string on 400, unchanged.industry field.
business_details on a Business submission gains a new field, industry, which exposes Sumsub’s full industry taxonomy (~151 values) in place of the 36 broad categories on the existing industry_type field. industry_type is now deprecated — it keeps working indefinitely, so no integration needs to change immediately — but industry is required for any submission made under this version or later. Callers on an earlier or unversioned X-API-Version can keep sending industry_type alone; industry stays optional for them. If a submission includes both fields, industry takes precedence and industry_type is silently ignored.
A nested business beneficiary now needs only Company Details and Ownership Structure documents.
A
Shareholder that’s a legal entity (a nested company) previously needed the same document groups as the root company — up to all four for a non-US root. It now always needs just Company Details and Ownership Structure, regardless of the root company’s own requirement or the nested entity’s registered country. See Company Documents.
A US company Business submission’s CDD certification falls back to a 10% ownership threshold instead of requiring 25%.
Previously, a US non-sole-proprietorship
Business submission was rejected with cdd_certification_invalid if no beneficiary owned 25% or more, even when that’s genuinely true of the company. The generated CDD certification (31 CFR 1010.230) now lists whoever owns 25% or more in its ownership section as before, but if nobody does, it falls back to listing whoever owns 10% or more instead of rejecting the submission. A submission where nobody owns even 10% is still rejected — see the qualifying-owner requirement below, which applies this same threshold to every country, not just US CDD certifications. The attesting party’s control-person section is still required as before. See Company Documents.
A ubo_share_below_threshold beneficiary now falls back to a 10% disclosure threshold, in every country.
Previously, a beneficiary whose only role was
UltimateBeneficialOwner was rejected with ubo_share_below_threshold whenever their share_percentage was 25 or below, with no fallback — the only way to submit such a beneficiary was to give them an additional role (for example Director), which dropped the UltimateBeneficialOwner tag entirely. Now, if nobody at that beneficiary’s level (the root company, or a nested company) owns 25% or more, the threshold for keeping the UltimateBeneficialOwner tag drops to 10% instead of rejecting outright. A UBO-only beneficiary owning, say, 15% is now accepted and keeps the tag as long as nobody else at that level already owns 25% or more; nobody rejects until nobody at that level owns even 10%. This applies in every country, not just US submissions. See ubo_share_below_threshold.
A beneficiary’s birth_place.state is optional for countries with no administrative subdivisions.
Previously, every beneficiary’s
birth_place.state was required, even for countries with no ISO 3166-2 administrative subdivisions (Vatican City, Malta, and Hong Kong, for example), leaving no legitimate value to send. state is now optional, and validation only rejects a missing value for a birth country that actually has subdivisions. Existing integrations that already send state are unaffected. See Business API Field Reference.
A Business submission now requires a root-level Director and a root-level qualifying owner, in every country.
Previously, a non-sole-proprietorship
Business submission outside the US could validate with zero beneficiaries, or with beneficiaries holding only, say, Shareholder or UltimateBeneficialOwner roles — nobody holding Director, and nobody disclosing enough ownership to matter. US submissions never fully hit this: the mandatory CDD attesting party always requires a Director, and (as of the CDD fallback-tier change above) a qualifying owner — but that’s incidental to the US CDD flow, not an independent floor, and ROW had no equivalent at all. Every non-sole-proprietorship company, in every country, now must name at least one root-level beneficiary with the Director role, and at least one root-level beneficiary owning 25% or more (or 10% or more, if nobody owns 25% or more) — or the submission is rejected with structure_invalid. A Representative-only beneficiary never satisfies the ownership half of this, regardless of their disclosed share_percentage: Iron never independently verifies a Representative-only beneficiary’s identity, so their disclosure can’t count as ownership evidence. Combined shares of everyone who does count as a qualifying owner (any UltimateBeneficialOwner, or any other non-Representative-only beneficiary) still can’t exceed 100%. Neither requirement applies to sole proprietorships (still exactly one beneficiary, 100% owned, no Director needed) or to nested business beneficiaries’ own sub-beneficiary lists (which remain documentation-only). See structure_invalid.
2026-07-01
Adds the FedNow deposit rail.
The
deposit_rails array can now include a FedNow member, for autoramps whose deposit account supports FedNow. This is additive to the DepositRail union: every existing member (Iban, AchWire, Swift, and the rest) is unchanged.
2025-03-13
Initial version. Served when noX-API-Version header is sent.