Skip to content

Simulate KYC / KYB

TL;DR - New customers in dev stay created - nothing auto-approves. You decide the outcome: open the customer's KYC link and click one of three buttons, or make one Simulation API call. Once verified, the virtual account provisions by itself and the customer goes active.

Why your customer is stuck in created

In production, the customer completes the provider's hosted document flow and the status moves on its own - see KYC / KYB status for the lifecycle. The sandbox replaces that flow with an explicit decision: nothing moves until you move it. This is deliberate - it lets you hold a customer in any pre-verification state for as long as a demo or test needs.

Option A - the hosted verification page

  1. Create the customer as usual - see Create a customer.
  2. Open the customer detail page. While the customer is in created or verifying, it shows the amber "Customer verification pending" notice with the KYC link - the same link the customer would receive by email.
  3. Open the link. In dev it lands on the sandbox's verification page, which shows the customer's name, email, user ID, and current status, plus three buttons:
    • Approve - mark Verified
    • Send to manual Review
    • Reject - mark Failed
  4. Pick one. The page confirms the new status and redirects back to the dashboard.

You can change your mind - until you approve

Re-opening the page lets you pick a different outcome while the customer sits in review or rejected. Verified is final - once approved, the onboarding continues and there is no way back.

Option B - the Simulation API

One call, no browser:

curl -X POST \
  "https://dev.magma.builders/api/v1/sandbox/organizations/{orgId}/kyc?result=verified" \
  -H "Authorization: Bearer $TOKEN"

{orgId} is the customer's Magma id - the one you see in the dashboard URL or get back from POST /api/v1/organizations. Auth requirements are on the Simulation API reference.

result Customer status you'll see
verified (default) verified, then active once the virtual account provisions
review review
failed rejected

The statuses are exactly the production vocabulary - see the Status reference.

What happens after verified

The same thing as production, just faster: the platform provisions the customer's fiat virtual account and the status moves verified → active. With auto-advance on (the dev default) this takes seconds; refresh the customer page and the amber notice is gone.

From active you can do everything - fund, add recipients, send payouts.

Block or unblock a customer

The provider can block a user for compliance reasons; the sandbox lets you simulate that:

curl -X POST \
  "https://dev.magma.builders/api/v1/sandbox/organizations/{orgId}/block?blocked=true" \
  -H "Authorization: Bearer $TOKEN"

blocked defaults to true; pass blocked=false to lift it. While blocked, payout attempts for that customer fail with a BLOCKED error.

The reliable failure demo

Blocking is the cleanest way to show a payout failing: it works no matter how fast the sandbox auto-settles, and it's reversible. Compare with forcing failed on an in-flight payout, which races auto-advance - see Simulate payout settlement.

What's next