From b7b83a9b97de08932e7586495be83bc210fa21f8 Mon Sep 17 00:00:00 2001 From: Peng Ying Date: Sat, 5 Sep 2026 00:18:03 +0000 Subject: [PATCH 1/6] docs(sandbox): correct KYC/KYB resolution timing in the sandbox snippets --- mintlify/changelog.mdx | 3 +-- .../snippets/kyc/kyb-sandbox-suffixes.mdx | 8 ++++--- mintlify/snippets/sandbox-verification.mdx | 21 ++++++++++++------- 3 files changed, 19 insertions(+), 13 deletions(-) diff --git a/mintlify/changelog.mdx b/mintlify/changelog.mdx index 0020a5767..98c86a060 100644 --- a/mintlify/changelog.mdx +++ b/mintlify/changelog.mdx @@ -39,8 +39,7 @@ submit, and resolve loop you run in production. individuals resolve at create, businesses at their first submission. Turn it off when you want to test the full flow again. -See [sandbox testing](/api-reference/sandbox-testing) for the suffix values and the -outcome each one produces. +Walk through the fix-and-resubmit loop in [sandbox testing](/api-reference/sandbox-testing). diff --git a/mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx b/mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx index 8d6a516d2..edd474381 100644 --- a/mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx +++ b/mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx @@ -4,11 +4,13 @@ Business customers are always created with `kybStatus: UNVERIFIED`. The **last 3 |--------|---------| | **003** | No auto-decision. Document and UBO verification run for real — the hosted flow asks for company documents and beneficial owners, and `POST /verifications` applies normal validation (`RESOLVE_ERRORS` until the data is complete). **Use this to test the link flow.** | | **001** | Same as `003` — no auto-decision, normal validation applies | -| **002** | Immediate `kybStatus: REJECTED` (`verificationStatus: REJECTED`), skipping data and document validation | -| **Any other** | Immediate `kybStatus: APPROVED` (`verificationStatus: APPROVED`), skipping data and document validation | +| **002** | `kybStatus: REJECTED` (`verificationStatus: REJECTED`), skipping data and document validation | +| **Any other** | `kybStatus: APPROVED` (`verificationStatus: APPROVED`), skipping data and document validation | + +On an **unregulated platform**, the packet is checked before any of these outcomes apply: a business with incomplete data returns `RESOLVE_ERRORS` whatever its suffix, and the suffix resolves only once the submission is complete. Turn on **Skip verification paperwork** in the sandbox dashboard's Configuration to resolve from the suffix alone. -A registration number that doesn't end in `001`, `002`, or `003` is **auto-approved on the spot**. The hosted flow then has nothing left to verify, so it asks for no documents and no beneficial owners — which looks exactly like a broken KYB flow but isn't. Always use a `003` suffix when you want to exercise document and UBO collection. +Where the suffix resolves without a packet, a registration number that doesn't end in `001`, `002`, or `003` is **auto-approved at its first submission**. The hosted flow then has nothing left to verify, so it asks for no documents and no beneficial owners — which looks exactly like a broken KYB flow but isn't. Always use a `003` suffix when you want to exercise document and UBO collection. Once a business customer is approved or rejected, further `POST /verifications` calls return `400`. diff --git a/mintlify/snippets/sandbox-verification.mdx b/mintlify/snippets/sandbox-verification.mdx index d84b21860..a448efc11 100644 --- a/mintlify/snippets/sandbox-verification.mdx +++ b/mintlify/snippets/sandbox-verification.mdx @@ -4,16 +4,21 @@ In sandbox, you can trigger specific KYC/KYB verification outcomes using magic s ### Individual customer verification (KYC) -The **last 3 characters** of the `fullName` on `POST /customers` (with `customerType: INDIVIDUAL`) determine the customer's `kycStatus` **immediately at creation**: +The **last 3 characters** of the `fullName` on `POST /customers` (with `customerType: INDIVIDUAL`) decide the customer's `kycStatus`. When that outcome applies depends on your platform: -| Suffix | `kycStatus` at creation | Behavior on `POST /verifications` | -|--------|-------------------------|-----------------------------------| +- **Unregulated platforms** — the customer is created `UNVERIFIED` and stays there until you submit with `POST /verifications`. The suffix decides the result once the submission is complete. +- **Regulated platforms**, and any platform with **Skip verification paperwork** turned on in the sandbox dashboard's Configuration — the suffix resolves the customer at creation, with no documents required. + +| Suffix | `kycStatus` | Behavior on `POST /verifications` | +|--------|-------------|-----------------------------------| | **001** | `PENDING` | With complete data and an identity document: `verificationStatus: PENDING_MANUAL_REVIEW` — simulates an applicant waiting on manual review | -| **002** | `REJECTED` | Returns `400` — the customer was terminally rejected at creation | +| **002** | `REJECTED` | Returns `400` once resolved — the customer is terminally rejected | | **003** | `UNVERIFIED` | With complete data: `verificationStatus: RESOLVE_ERRORS` with a `POOR_QUALITY_DOCUMENT` error — simulates a correctable provider rejection | -| **Any other** | `APPROVED` | Returns `400` — the customer was approved at creation | +| **Any other** | `APPROVED` | Returns `400` once resolved — the customer is approved | + +Once a customer reaches `APPROVED` or `REJECTED`, that status is final: further `POST /verifications` calls return `400`, and renaming the customer does not re-derive it. Create a new customer when you want to exercise a different outcome. -Because terminal suffixes resolve at creation, only `001` and `003` customers can be submitted for verification. Use any non-suffixed name to mint ready-to-transact approved customers, and a `001` name to exercise the full submission flow. +Where the suffix resolves at creation, only `001` and `003` customers can be submitted for verification. Use any non-suffixed name to mint ready-to-transact approved customers, and a `001` name to exercise the full submission flow. Submitting for verification has the same data requirements as production: full name, birth date, nationality, `idType` + `identifier`, address, and an identity document uploaded via `POST /documents`. Anything missing comes back as `verificationStatus: RESOLVE_ERRORS` with one entry per problem in `errors`: @@ -41,7 +46,7 @@ Fix-and-resubmit example — the standard integration loop: - A `fullName` ending in `001` keeps the customer `PENDING`, so submission is allowed. Persist the returned `id` for the following steps. + A `fullName` ending in `001` leaves the customer submittable rather than resolving it terminally — `UNVERIFIED` on an unregulated platform, `PENDING` where the suffix resolves at creation. Persist the returned `id` for the following steps. ```bash curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \ @@ -108,7 +113,7 @@ Fix-and-resubmit example — the standard integration loop: -For direct API onboarding, `001` and `003` both require complete business information, business documents, and at least one beneficial owner before `POST /verifications` moves past `RESOLVE_ERRORS`. For the hosted flow, see [Configuring customers](/payouts-and-b2b/onboarding/configuring-customers#hosted-kyc-and-kyb-link-flow). +For direct API onboarding, `001` and `003` both require complete business information, business documents, and at least one beneficial owner before `POST /verifications` moves past `RESOLVE_ERRORS`. On an unregulated platform every suffix goes through that check first, so an incomplete `002` business reports its missing data before it rejects. For the hosted flow, see [Configuring customers](/payouts-and-b2b/onboarding/configuring-customers#hosted-kyc-and-kyb-link-flow). ### Beneficial owner KYC From 313a0d38af325c70904972248d6d8a24aadfc66e Mon Sep 17 00:00:00 2001 From: Peng Ying Date: Sat, 5 Sep 2026 00:29:50 +0000 Subject: [PATCH 2/6] docs(sandbox): clarify suffix outcome timing in the remaining sandbox guides Co-Authored-By: pengying --- mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx | 2 +- mintlify/rewards/platform-tools/sandbox-testing.mdx | 2 +- mintlify/snippets/kyc/kyc-unregulated.mdx | 2 +- mintlify/snippets/sandbox-verification.mdx | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx b/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx index 7bea16655..cba6c44d3 100644 --- a/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx +++ b/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx @@ -251,7 +251,7 @@ While sandbox closely mimics production, there are some differences: - **Instant settlement**: All transfers complete immediately (success cases) or fail immediately (error cases), except timeout scenarios (005) - **No real bank validation**: Account numbers aren't validated against real banking networks -- **Simplified KYC**: KYC processes are simulated and complete instantly. You must add customers via the `/customers` endpoint, rather than using the KYC link flow. +- **Simplified KYC**: KYC processes are simulated rather than reviewed for real. On an unregulated platform the result resolves once you submit with `POST /verifications`; elsewhere it resolves at creation. You must add customers via the `/customers` endpoint, rather than using the KYC link flow. - **Fixed exchange rates**: Currency conversion rates may not reflect real-time market rates. diff --git a/mintlify/rewards/platform-tools/sandbox-testing.mdx b/mintlify/rewards/platform-tools/sandbox-testing.mdx index 6d208dabb..0b6e0ed19 100644 --- a/mintlify/rewards/platform-tools/sandbox-testing.mdx +++ b/mintlify/rewards/platform-tools/sandbox-testing.mdx @@ -337,7 +337,7 @@ While sandbox closely mimics production, there are some differences: - **Instant settlement**: All Bitcoin transfers complete instantly (success cases) or fail immediately (error cases), except timeout scenarios (005) - **Uses Regtest funds**: Spark bitcoin funds are regtest funds so that they're compatible with real regtest spark wallets. -- **Simplified KYB**: KYB processes are simulated and complete instantly with automatic approval +- **Simplified KYB**: KYB processes are simulated rather than reviewed for real, resolving at the first `POST /verifications` submission - **Fixed exchange rates**: Currency conversion rates may not reflect real-time market rates diff --git a/mintlify/snippets/kyc/kyc-unregulated.mdx b/mintlify/snippets/kyc/kyc-unregulated.mdx index 17c451734..145286adb 100644 --- a/mintlify/snippets/kyc/kyc-unregulated.mdx +++ b/mintlify/snippets/kyc/kyc-unregulated.mdx @@ -164,7 +164,7 @@ The response field is named `kycUrl` for both customer types; for a `BUSINESS` c -Testing the business flow in sandbox: a `businessInfo.registrationNumber` **not** ending in `001`, `002`, or `003` auto-approves the customer on the spot, leaving the hosted flow nothing to verify — so it asks for no documents and no beneficial owners. Use a `003` suffix to exercise document and UBO collection. See [Sandbox testing](/api-reference/sandbox-testing). +Testing the business flow in sandbox: a `businessInfo.registrationNumber` **not** ending in `001`, `002`, or `003` auto-approves the customer at its first verification submission, leaving the hosted flow nothing to verify — so it asks for no documents and no beneficial owners. Use a `003` suffix to exercise document and UBO collection. See [Sandbox testing](/api-reference/sandbox-testing). ### Direct API Onboarding diff --git a/mintlify/snippets/sandbox-verification.mdx b/mintlify/snippets/sandbox-verification.mdx index a448efc11..9b36003da 100644 --- a/mintlify/snippets/sandbox-verification.mdx +++ b/mintlify/snippets/sandbox-verification.mdx @@ -9,8 +9,8 @@ The **last 3 characters** of the `fullName` on `POST /customers` (with `customer - **Unregulated platforms** — the customer is created `UNVERIFIED` and stays there until you submit with `POST /verifications`. The suffix decides the result once the submission is complete. - **Regulated platforms**, and any platform with **Skip verification paperwork** turned on in the sandbox dashboard's Configuration — the suffix resolves the customer at creation, with no documents required. -| Suffix | `kycStatus` | Behavior on `POST /verifications` | -|--------|-------------|-----------------------------------| +| Suffix | Resolved `kycStatus` | Behavior on `POST /verifications` | +|--------|----------------------|-----------------------------------| | **001** | `PENDING` | With complete data and an identity document: `verificationStatus: PENDING_MANUAL_REVIEW` — simulates an applicant waiting on manual review | | **002** | `REJECTED` | Returns `400` once resolved — the customer is terminally rejected | | **003** | `UNVERIFIED` | With complete data: `verificationStatus: RESOLVE_ERRORS` with a `POOR_QUALITY_DOCUMENT` error — simulates a correctable provider rejection | From 12230335bbf868d2cdd771365388934111700a01 Mon Sep 17 00:00:00 2001 From: Peng Ying Date: Sat, 5 Sep 2026 00:34:14 +0000 Subject: [PATCH 3/6] docs(sandbox): scope suffix resolution to the skip-paperwork configuration Co-Authored-By: pengying --- .../payouts-and-b2b/platform-tools/sandbox-testing.mdx | 2 +- mintlify/ramps/platform-tools/sandbox-testing.mdx | 2 +- mintlify/rewards/platform-tools/sandbox-testing.mdx | 4 ++-- mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx | 7 +++++-- mintlify/snippets/kyc/kyc-unregulated.mdx | 2 +- mintlify/snippets/sandbox-verification.mdx | 4 ++-- 6 files changed, 12 insertions(+), 9 deletions(-) diff --git a/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx b/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx index cba6c44d3..82ca043a2 100644 --- a/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx +++ b/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx @@ -251,7 +251,7 @@ While sandbox closely mimics production, there are some differences: - **Instant settlement**: All transfers complete immediately (success cases) or fail immediately (error cases), except timeout scenarios (005) - **No real bank validation**: Account numbers aren't validated against real banking networks -- **Simplified KYC**: KYC processes are simulated rather than reviewed for real. On an unregulated platform the result resolves once you submit with `POST /verifications`; elsewhere it resolves at creation. You must add customers via the `/customers` endpoint, rather than using the KYC link flow. +- **Simplified KYC**: KYC processes are simulated rather than reviewed for real. On an unregulated platform the result resolves after a complete packet is submitted with `POST /verifications` — an incomplete one returns `RESOLVE_ERRORS` first. On a regulated platform, or with **Skip verification paperwork** on, it resolves at creation. You must add customers via the `/customers` endpoint, rather than using the KYC link flow. - **Fixed exchange rates**: Currency conversion rates may not reflect real-time market rates. diff --git a/mintlify/ramps/platform-tools/sandbox-testing.mdx b/mintlify/ramps/platform-tools/sandbox-testing.mdx index 24478827a..1f9621004 100644 --- a/mintlify/ramps/platform-tools/sandbox-testing.mdx +++ b/mintlify/ramps/platform-tools/sandbox-testing.mdx @@ -85,7 +85,7 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers' \ }' ``` -In sandbox, customers are automatically approved for testing. +In sandbox, a `fullName` not ending in `001`, `002`, or `003` yields an approved customer rather than a real review. On a regulated platform, or with **Skip verification paperwork** on, that lands at creation and the customer is ready for the next step. On an unregulated platform the customer stays `UNVERIFIED` until you submit a complete verification — see [Sandbox testing](/api-reference/sandbox-testing) for that flow. ### Step 2: Create an external account for the destination wallet diff --git a/mintlify/rewards/platform-tools/sandbox-testing.mdx b/mintlify/rewards/platform-tools/sandbox-testing.mdx index 0b6e0ed19..32e0d30f0 100644 --- a/mintlify/rewards/platform-tools/sandbox-testing.mdx +++ b/mintlify/rewards/platform-tools/sandbox-testing.mdx @@ -176,7 +176,7 @@ curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \ }' ``` -In sandbox, customers are automatically approved. In production, KYB verification may take several minutes. +In sandbox, a `fullName` not ending in `001`, `002`, or `003` yields an approved customer rather than a real review. On an unregulated platform the customer stays `UNVERIFIED` until you submit a complete verification with `POST /verifications`; with **Skip verification paperwork** on, or on a regulated platform, the name resolves the customer at creation. In production, verification may take several minutes. ## Testing Insufficient Balance @@ -337,7 +337,7 @@ While sandbox closely mimics production, there are some differences: - **Instant settlement**: All Bitcoin transfers complete instantly (success cases) or fail immediately (error cases), except timeout scenarios (005) - **Uses Regtest funds**: Spark bitcoin funds are regtest funds so that they're compatible with real regtest spark wallets. -- **Simplified KYB**: KYB processes are simulated rather than reviewed for real, resolving at the first `POST /verifications` submission +- **Simplified KYB**: KYB processes are simulated rather than reviewed for real. On an unregulated platform the result resolves after a complete packet is submitted; with **Skip verification paperwork** on, or on a regulated platform, a final suffix resolves on the first submission without packet validation - **Fixed exchange rates**: Currency conversion rates may not reflect real-time market rates diff --git a/mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx b/mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx index edd474381..231cbda2f 100644 --- a/mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx +++ b/mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx @@ -7,10 +7,13 @@ Business customers are always created with `kybStatus: UNVERIFIED`. The **last 3 | **002** | `kybStatus: REJECTED` (`verificationStatus: REJECTED`), skipping data and document validation | | **Any other** | `kybStatus: APPROVED` (`verificationStatus: APPROVED`), skipping data and document validation | -On an **unregulated platform**, the packet is checked before any of these outcomes apply: a business with incomplete data returns `RESOLVE_ERRORS` whatever its suffix, and the suffix resolves only once the submission is complete. Turn on **Skip verification paperwork** in the sandbox dashboard's Configuration to resolve from the suffix alone. +Business customers never resolve at creation — the outcome lands on the first `POST /verifications`. What happens on that submission depends on your platform: + +- **Unregulated platforms** (the default, with **Skip verification paperwork** off) — the packet is validated first. A business with incomplete data returns `RESOLVE_ERRORS` whatever its suffix, and the suffix resolves only once the submission is complete. +- **Regulated platforms**, and unregulated platforms with **Skip verification paperwork** on — a final suffix (`002` or any non-`001`/`003` value) resolves before the packet is validated, so it lands even on an incomplete submission. `001` and `003` still require a complete packet. -Where the suffix resolves without a packet, a registration number that doesn't end in `001`, `002`, or `003` is **auto-approved at its first submission**. The hosted flow then has nothing left to verify, so it asks for no documents and no beneficial owners — which looks exactly like a broken KYB flow but isn't. Always use a `003` suffix when you want to exercise document and UBO collection. +Where a final suffix resolves without packet validation — a regulated platform, or **Skip verification paperwork** on — a registration number that doesn't end in `001`, `002`, or `003` is **auto-approved at its first submission**. The hosted flow then has nothing left to verify, so it asks for no documents and no beneficial owners — which looks exactly like a broken KYB flow but isn't. Always use a `003` suffix when you want to exercise document and UBO collection. Once a business customer is approved or rejected, further `POST /verifications` calls return `400`. diff --git a/mintlify/snippets/kyc/kyc-unregulated.mdx b/mintlify/snippets/kyc/kyc-unregulated.mdx index 145286adb..c1cebb63e 100644 --- a/mintlify/snippets/kyc/kyc-unregulated.mdx +++ b/mintlify/snippets/kyc/kyc-unregulated.mdx @@ -164,7 +164,7 @@ The response field is named `kycUrl` for both customer types; for a `BUSINESS` c -Testing the business flow in sandbox: a `businessInfo.registrationNumber` **not** ending in `001`, `002`, or `003` auto-approves the customer at its first verification submission, leaving the hosted flow nothing to verify — so it asks for no documents and no beneficial owners. Use a `003` suffix to exercise document and UBO collection. See [Sandbox testing](/api-reference/sandbox-testing). +Testing the business flow in sandbox: by default the hosted flow collects the full packet, and a `businessInfo.registrationNumber` **not** ending in `001`, `002`, or `003` auto-approves the customer once that submission is complete. With **Skip verification paperwork** on, that suffix resolves before any packet validation, leaving the hosted flow nothing to verify — so it asks for no documents and no beneficial owners. Use a `003` suffix to exercise document and UBO collection. See [Sandbox testing](/api-reference/sandbox-testing). ### Direct API Onboarding diff --git a/mintlify/snippets/sandbox-verification.mdx b/mintlify/snippets/sandbox-verification.mdx index 9b36003da..bac45774a 100644 --- a/mintlify/snippets/sandbox-verification.mdx +++ b/mintlify/snippets/sandbox-verification.mdx @@ -6,8 +6,8 @@ In sandbox, you can trigger specific KYC/KYB verification outcomes using magic s The **last 3 characters** of the `fullName` on `POST /customers` (with `customerType: INDIVIDUAL`) decide the customer's `kycStatus`. When that outcome applies depends on your platform: -- **Unregulated platforms** — the customer is created `UNVERIFIED` and stays there until you submit with `POST /verifications`. The suffix decides the result once the submission is complete. -- **Regulated platforms**, and any platform with **Skip verification paperwork** turned on in the sandbox dashboard's Configuration — the suffix resolves the customer at creation, with no documents required. +- **Unregulated platforms** (the default, with **Skip verification paperwork** off) — the customer is created `UNVERIFIED` and stays there until you submit with `POST /verifications`. An incomplete submission returns `RESOLVE_ERRORS`; the suffix decides the result once the submission is complete. +- **Regulated platforms**, and unregulated platforms with **Skip verification paperwork** turned on in the sandbox dashboard's Configuration — the suffix resolves the customer at creation, with no documents required. | Suffix | Resolved `kycStatus` | Behavior on `POST /verifications` | |--------|----------------------|-----------------------------------| From 837a9c81d84ef1441f71ea90309601e21fe3e9e0 Mon Sep 17 00:00:00 2001 From: Peng Ying Date: Sat, 5 Sep 2026 00:41:20 +0000 Subject: [PATCH 4/6] docs(sandbox): scope the verification walkthroughs to their configuration Co-Authored-By: pengying --- mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx | 2 +- mintlify/ramps/platform-tools/sandbox-testing.mdx | 6 +++++- mintlify/snippets/sandbox-verification.mdx | 4 ++-- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx b/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx index 82ca043a2..1889c56c2 100644 --- a/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx +++ b/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx @@ -251,7 +251,7 @@ While sandbox closely mimics production, there are some differences: - **Instant settlement**: All transfers complete immediately (success cases) or fail immediately (error cases), except timeout scenarios (005) - **No real bank validation**: Account numbers aren't validated against real banking networks -- **Simplified KYC**: KYC processes are simulated rather than reviewed for real. On an unregulated platform the result resolves after a complete packet is submitted with `POST /verifications` — an incomplete one returns `RESOLVE_ERRORS` first. On a regulated platform, or with **Skip verification paperwork** on, it resolves at creation. You must add customers via the `/customers` endpoint, rather than using the KYC link flow. +- **Simplified KYC**: KYC processes are simulated rather than reviewed for real. On an unregulated platform the result resolves after a complete packet is submitted with `POST /verifications` — an incomplete one returns `RESOLVE_ERRORS` first. On a regulated platform, or with **Skip verification paperwork** on, an individual resolves at creation; a business always resolves on its first submission. You must add customers via the `/customers` endpoint, rather than using the KYC link flow. - **Fixed exchange rates**: Currency conversion rates may not reflect real-time market rates. diff --git a/mintlify/ramps/platform-tools/sandbox-testing.mdx b/mintlify/ramps/platform-tools/sandbox-testing.mdx index 1f9621004..289b37b3e 100644 --- a/mintlify/ramps/platform-tools/sandbox-testing.mdx +++ b/mintlify/ramps/platform-tools/sandbox-testing.mdx @@ -63,6 +63,10 @@ curl -X PATCH 'https://api.lightspark.com/grid/2025-10-13/config' \ Simulate the complete on-ramp flow in sandbox: + + This walkthrough assumes a customer who is approved at creation — a regulated sandbox platform, or an unregulated one with **Skip verification paperwork** turned on in the dashboard's Configuration. On the default unregulated path a new customer stays `UNVERIFIED` until you submit a complete verification, so run through [KYC/KYB verification](/api-reference/sandbox-testing#kyckyb-verification) before Step 2. + + ### Step 1: Create a test customer ```bash @@ -85,7 +89,7 @@ curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers' \ }' ``` -In sandbox, a `fullName` not ending in `001`, `002`, or `003` yields an approved customer rather than a real review. On a regulated platform, or with **Skip verification paperwork** on, that lands at creation and the customer is ready for the next step. On an unregulated platform the customer stays `UNVERIFIED` until you submit a complete verification — see [Sandbox testing](/api-reference/sandbox-testing) for that flow. +A `fullName` not ending in `001`, `002`, or `003` yields an approved customer rather than a real review. Under the configuration above, `Alice Test` is `APPROVED` at creation and ready for Step 2. ### Step 2: Create an external account for the destination wallet diff --git a/mintlify/snippets/sandbox-verification.mdx b/mintlify/snippets/sandbox-verification.mdx index bac45774a..f20b81409 100644 --- a/mintlify/snippets/sandbox-verification.mdx +++ b/mintlify/snippets/sandbox-verification.mdx @@ -20,7 +20,7 @@ Once a customer reaches `APPROVED` or `REJECTED`, that status is final: further Where the suffix resolves at creation, only `001` and `003` customers can be submitted for verification. Use any non-suffixed name to mint ready-to-transact approved customers, and a `001` name to exercise the full submission flow. -Submitting for verification has the same data requirements as production: full name, birth date, nationality, `idType` + `identifier`, address, and an identity document uploaded via `POST /documents`. Anything missing comes back as `verificationStatus: RESOLVE_ERRORS` with one entry per problem in `errors`: +Where a submission is required — the default unregulated path, and `001`/`003` on any path — it carries the same data requirements as production: full name, birth date, nationality, `idType` + `identifier`, address, and an identity document uploaded via `POST /documents`. Anything missing comes back as `verificationStatus: RESOLVE_ERRORS` with one entry per problem in `errors`: ```json { @@ -42,7 +42,7 @@ Submitting for verification has the same data requirements as production: full n } ``` -Fix-and-resubmit example — the standard integration loop: +Fix-and-resubmit example — the standard integration loop on the default unregulated path, with **Skip verification paperwork** off. A `001` suffix behaves the same way where the suffix resolves at creation, since `001` and `003` always require a complete packet; a terminal suffix on that path resolves without one, and `POST /verifications` then returns `400`. From 00dae341db30d6564e38848aecac2af3b7d300bd Mon Sep 17 00:00:00 2001 From: Peng Ying Date: Sat, 5 Sep 2026 00:57:55 +0000 Subject: [PATCH 5/6] docs(sandbox): scope the no-document paths to terminal suffixes Co-Authored-By: pengying --- mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx | 2 +- mintlify/snippets/sandbox-verification.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx b/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx index 1889c56c2..94fff9fd3 100644 --- a/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx +++ b/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx @@ -251,7 +251,7 @@ While sandbox closely mimics production, there are some differences: - **Instant settlement**: All transfers complete immediately (success cases) or fail immediately (error cases), except timeout scenarios (005) - **No real bank validation**: Account numbers aren't validated against real banking networks -- **Simplified KYC**: KYC processes are simulated rather than reviewed for real. On an unregulated platform the result resolves after a complete packet is submitted with `POST /verifications` — an incomplete one returns `RESOLVE_ERRORS` first. On a regulated platform, or with **Skip verification paperwork** on, an individual resolves at creation; a business always resolves on its first submission. You must add customers via the `/customers` endpoint, rather than using the KYC link flow. +- **Simplified KYC**: KYC processes are simulated rather than reviewed for real. On an unregulated platform the result resolves after a complete packet is submitted with `POST /verifications` — an incomplete one returns `RESOLVE_ERRORS` first. On a regulated platform, or with **Skip verification paperwork** on, an individual resolves at creation; a business never does — a terminal registration-number suffix resolves it on the first submission, while `001` and `003` still require a complete packet. You must add customers via the `/customers` endpoint, rather than using the KYC link flow. - **Fixed exchange rates**: Currency conversion rates may not reflect real-time market rates. diff --git a/mintlify/snippets/sandbox-verification.mdx b/mintlify/snippets/sandbox-verification.mdx index f20b81409..e9a92cd26 100644 --- a/mintlify/snippets/sandbox-verification.mdx +++ b/mintlify/snippets/sandbox-verification.mdx @@ -7,7 +7,7 @@ In sandbox, you can trigger specific KYC/KYB verification outcomes using magic s The **last 3 characters** of the `fullName` on `POST /customers` (with `customerType: INDIVIDUAL`) decide the customer's `kycStatus`. When that outcome applies depends on your platform: - **Unregulated platforms** (the default, with **Skip verification paperwork** off) — the customer is created `UNVERIFIED` and stays there until you submit with `POST /verifications`. An incomplete submission returns `RESOLVE_ERRORS`; the suffix decides the result once the submission is complete. -- **Regulated platforms**, and unregulated platforms with **Skip verification paperwork** turned on in the sandbox dashboard's Configuration — the suffix resolves the customer at creation, with no documents required. +- **Regulated platforms**, and unregulated platforms with **Skip verification paperwork** turned on in the sandbox dashboard's Configuration — the suffix resolves the customer at creation, with no documents required. `002` and any value other than `001`/`003` are terminal there. `001` and `003` land at `PENDING` and `UNVERIFIED`, which you can still submit for verification — and that submission carries the full data and document requirements below. | Suffix | Resolved `kycStatus` | Behavior on `POST /verifications` | |--------|----------------------|-----------------------------------| From 21f4efb697bef4a909927b4cb488a7c442ffcfb5 Mon Sep 17 00:00:00 2001 From: Peng Ying Date: Sat, 5 Sep 2026 01:13:43 +0000 Subject: [PATCH 6/6] docs(sandbox): qualify skipped validation and correct the hosted-link claim Co-Authored-By: pengying --- mintlify/changelog.mdx | 6 +++--- mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx | 2 +- mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/mintlify/changelog.mdx b/mintlify/changelog.mdx index 98c86a060..d8774cc60 100644 --- a/mintlify/changelog.mdx +++ b/mintlify/changelog.mdx @@ -35,9 +35,9 @@ submit, and resolve loop you run in production. - Renaming a customer no longer overwrites a settled result—`APPROVED` and `REJECTED` stay put. Create a new customer when you want to exercise a different outcome. - To keep the previous fast path, open **Configuration** in your sandbox dashboard and turn - on **Skip verification paperwork**. Results then come from the suffix with no documents: - individuals resolve at create, businesses at their first submission. Turn it off when you - want to test the full flow again. + on **Skip verification paperwork**. A terminal suffix then resolves with no documents: + individuals at create, businesses at their first submission. `001` and `003` still require + a complete packet. Turn it off when you want to test the full flow again. Walk through the fix-and-resubmit loop in [sandbox testing](/api-reference/sandbox-testing). diff --git a/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx b/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx index 94fff9fd3..969794fe1 100644 --- a/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx +++ b/mintlify/payouts-and-b2b/platform-tools/sandbox-testing.mdx @@ -251,7 +251,7 @@ While sandbox closely mimics production, there are some differences: - **Instant settlement**: All transfers complete immediately (success cases) or fail immediately (error cases), except timeout scenarios (005) - **No real bank validation**: Account numbers aren't validated against real banking networks -- **Simplified KYC**: KYC processes are simulated rather than reviewed for real. On an unregulated platform the result resolves after a complete packet is submitted with `POST /verifications` — an incomplete one returns `RESOLVE_ERRORS` first. On a regulated platform, or with **Skip verification paperwork** on, an individual resolves at creation; a business never does — a terminal registration-number suffix resolves it on the first submission, while `001` and `003` still require a complete packet. You must add customers via the `/customers` endpoint, rather than using the KYC link flow. +- **Simplified KYC**: KYC processes are simulated rather than reviewed for real. On an unregulated platform the result resolves after a complete packet is submitted with `POST /verifications` — an incomplete one returns `RESOLVE_ERRORS` first. On a regulated platform, or with **Skip verification paperwork** on, an individual resolves at creation; a business never does — a terminal registration-number suffix resolves it on the first submission, while `001` and `003` still require a complete packet. Customers can be onboarded through `POST /customers` or the hosted link flow, as in production. - **Fixed exchange rates**: Currency conversion rates may not reflect real-time market rates. diff --git a/mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx b/mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx index 231cbda2f..e033296c2 100644 --- a/mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx +++ b/mintlify/snippets/kyc/kyb-sandbox-suffixes.mdx @@ -4,10 +4,10 @@ Business customers are always created with `kybStatus: UNVERIFIED`. The **last 3 |--------|---------| | **003** | No auto-decision. Document and UBO verification run for real — the hosted flow asks for company documents and beneficial owners, and `POST /verifications` applies normal validation (`RESOLVE_ERRORS` until the data is complete). **Use this to test the link flow.** | | **001** | Same as `003` — no auto-decision, normal validation applies | -| **002** | `kybStatus: REJECTED` (`verificationStatus: REJECTED`), skipping data and document validation | -| **Any other** | `kybStatus: APPROVED` (`verificationStatus: APPROVED`), skipping data and document validation | +| **002** | `kybStatus: REJECTED` (`verificationStatus: REJECTED`). Data and document validation is skipped only on a regulated platform or with **Skip verification paperwork** on; by default the packet is validated first | +| **Any other** | `kybStatus: APPROVED` (`verificationStatus: APPROVED`). Data and document validation is skipped only on a regulated platform or with **Skip verification paperwork** on; by default the packet is validated first | -Business customers never resolve at creation — the outcome lands on the first `POST /verifications`. What happens on that submission depends on your platform: +Business customers never resolve at creation — the outcome lands on the first verification submission, whether you make it with `POST /verifications` or the applicant completes the hosted flow. What happens on that submission depends on your platform: - **Unregulated platforms** (the default, with **Skip verification paperwork** off) — the packet is validated first. A business with incomplete data returns `RESOLVE_ERRORS` whatever its suffix, and the suffix resolves only once the submission is complete. - **Regulated platforms**, and unregulated platforms with **Skip verification paperwork** on — a final suffix (`002` or any non-`001`/`003` value) resolves before the packet is validated, so it lands even on an incomplete submission. `001` and `003` still require a complete packet.