Sandbox Testing

Use Grid sandbox magic values to trigger specific API responses

The Grid sandbox environment simulates real payment flows without moving real money. You can control test outcomes using special account number patterns and test addresses.

KYC/KYB verification

In sandbox, you can trigger specific KYC/KYB verification outcomes using magic suffixes in customer and beneficial owner fields. These let you test different verification flows without waiting for real review.

On POST /verifications, the first submission emits VERIFICATION.IN_PROGRESS and then one VERIFICATION.<STATUS> event for the outcome. A later submission emits one VERIFICATION.<STATUS> event when its status or errors change. The matching CUSTOMER.KYC_* or CUSTOMER.KYB_* event fires when kycStatus or kybStatus changes.

Individual customer verification (KYC)

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.
• 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. Creation emits the matching CUSTOMER.KYC_* webhook only; it creates no verification and emits no VERIFICATION.* event. 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. Before the first POST /verifications, a PATCH that changes fullName re-derives the status from the new suffix while the customer is not final.
• Regulated platforms — the customer is APPROVED at creation. The suffix is not read, and Skip verification paperwork does not apply.

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
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.

With Skip verification paperwork on, 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 a submission is required — the default unregulated path, and 001/003 with the switch on — 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:

{
  "verificationStatus": "RESOLVE_ERRORS",
  "errors": [
    {
      "resourceId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "type": "MISSING_FIELD",
      "field": "identifier",
      "reason": "Identifier is required"
    },
    {
      "resourceId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "type": "MISSING_IDENTITY_DOCUMENT",
      "acceptedDocumentTypes": ["PASSPORT", "DRIVERS_LICENSE", "NATIONAL_ID"],
      "reason": "Identity document is required"
    }
  ]
}

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 with Skip verification paperwork on, since 001 and 003 always require a complete packet; a terminal suffix on that path resolves at creation, and POST /verifications then returns 400.

1. Create a customer with a 001 suffix

   A fullName ending in 001 leaves the customer submittable rather than resolving it terminally — UNVERIFIED on an unregulated platform, PENDING with Skip verification paperwork on. Persist the returned id for the following steps.

   curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
     -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{
       "customerType": "INDIVIDUAL",
       "fullName": "Jane Doe 001",
       "birthDate": "1990-01-15",
       "nationality": "US"
     }'
   
2. Submit for verification

   The first attempt returns verificationStatus: RESOLVE_ERRORS with every missing field and document listed in errors.

   curl -X POST "https://api.lightspark.com/grid/2025-10-13/verifications" \
     -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{ "customerId": "Customer:..." }'
   
3. Supply the missing fields and document

   Patch the missing fields onto the customer, then upload the identity document. Any JPEG, PNG, or PDF works in sandbox.

   curl -X PATCH "https://api.lightspark.com/grid/2025-10-13/customers/Customer:..." \
     -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{
       "customerType": "INDIVIDUAL",
       "idType": "SSN",
       "identifier": "111-22-3333",
       "address": { "line1": "123 Main St", "city": "Seattle", "state": "WA", "postalCode": "98101", "country": "US" }
     }'
   
   curl -X POST "https://api.lightspark.com/grid/2025-10-13/documents" \
     -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
     -F "documentHolder=Customer:..." \
     -F "documentType=PASSPORT" \
     -F "country=US" \
     -F "documentNumber=A12345678" \
     -F "issuingAuthority=U.S. Department of State" \
     -F "file=@./passport.jpg"
   
4. Resubmit

   The verification now advances to verificationStatus: PENDING_MANUAL_REVIEW and the customer’s kycStatus is PENDING.

   curl -X POST "https://api.lightspark.com/grid/2025-10-13/verifications" \
     -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{ "customerId": "Customer:..." }'
   

Business customer verification (KYB)

The last 3 characters of businessInfo.registrationNumber decide the business’s kybStatus. The same suffix applies whether you submit with POST /verifications or the applicant completes the hosted flow. When that outcome applies depends on your platform:

• Regulated platforms — the business is APPROVED at creation. The suffix is not read, and Skip verification paperwork does not apply.
• Unregulated platforms (the default, with Skip verification paperwork off) — the business is created UNVERIFIED and stays there until you submit with POST /verifications. The packet is validated first. An incomplete submission returns RESOLVE_ERRORS whatever the suffix; the suffix decides the result once the submission is complete.
• Unregulated platforms with Skip verification paperwork turned on in the sandbox dashboard’s Configuration — the suffix resolves the business at creation. No documents, beneficial owners, or POST /verifications call are needed. Creation emits the matching CUSTOMER.KYB_* webhook only; it creates no verification and emits no VERIFICATION.* event. Before the first POST /verifications, a PATCH that changes registrationNumber re-derives the status from the new suffix while the business is not final. On POST /verifications, the suffix is read before the packet check.

Suffix	Resolved kybStatus	Behavior on POST /verifications
001	PENDING	With a complete packet: verificationStatus: IN_PROGRESS, kybStatus: PENDING, and every beneficial owner PENDING — simulates a business waiting on review
002	REJECTED	Returns 400 once resolved — the business is terminally rejected
003	UNVERIFIED	verificationStatus: RESOLVE_ERRORS with a POOR_QUALITY_DOCUMENT error — simulates a correctable provider rejection. Change the suffix and resubmit to reach a final outcome
Any other	APPROVED	Returns 400 once resolved — the business is approved

Once a business customer reaches APPROVED or REJECTED, that status is final: further POST /verifications calls return 400, and changing registrationNumber does not re-derive it. Create a new business customer when you want to exercise a different outcome.

With Skip verification paperwork on, a registration number that doesn’t end in 001, 002, or 003 is approved at creation. 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 with the switch on.

For direct API onboarding with Skip verification paperwork off, every suffix requires complete business information, business documents, and at least one beneficial owner before POST /verifications moves past RESOLVE_ERRORS — an incomplete 002 business reports its missing data before it rejects. With the switch on, POST /verifications reads the suffix before the packet check: a 003 business returns RESOLVE_ERRORS with a POOR_QUALITY_DOCUMENT error with no packet, and a 001 business still needs the complete packet before POST /verifications moves past RESOLVE_ERRORS. For the hosted flow, see Configuring customers.

Beneficial owner KYC

When POST /verifications resolves a business from its registration-number suffix, each of its beneficial owners is resolved at the same moment using the last 3 characters of the lastName in that owner’s personalInfo:

Suffix	kycStatus	Behavior
001	PENDING	KYC verification remains pending
002	REJECTED	KYC verification is rejected, and the business is REJECTED with it
003	UNVERIFIED	KYC verification can be retried
Any other	APPROVED	KYC verification is approved

A 001 registration number does not read owner suffixes: the business and every owner go to PENDING. On a 003 business, owners with an approving suffix keep their current status until the business reaches a final outcome. With Skip verification paperwork on, a business with a final suffix resolves at creation before any owner exists, so use a 003 registration number when you want to test owners.

Adding external accounts

The flows for creating external accounts in sandbox are the same as in production. The last 3 digits of an external account’s primary identifier (account number, IBAN, CLABE, Spark wallet address, etc.) determine the test scenario when that account is used in transfers or quotes. For identifiers with a domain part (e.g. PIX email keys), append the test digits to the username portion — for example, [e-mail].

Suffix	Behavior
002	Insufficient funds — transfer fails immediately
003	Account closed/invalid — transfer fails immediately
004	Transfer rejected — bank rejects the transfer
005	Timeout/delayed failure — stays pending ~30s, then fails
Any other	Success — transfer completes normally

These outcomes apply whenever the account is used, as the source of a pull or the destination of a payout.

Beneficiary name verification

For account types that support beneficiary name verification, you can simulate different verification outcomes in sandbox. Use account identifiers with a 1xx suffix to trigger verification scenarios (this range is reserved for verification and does not conflict with transfer or quote test patterns):

Suffix	beneficiaryVerificationStatus	Behavior
102	NOT_MATCHED	Account is valid but name does not match
103	PARTIAL_MATCH	Account is valid, name is a fuzzy match
104	PENDING	Verification still in progress
105	(error)	Returns 400 — invalid account
106	UNSUPPORTED	Payment rail does not support name verification
107	CHECKED_BY_RECEIVING_FI	Verification deferred to receiving financial institution (e.g., ACH)
Any other	MATCHED	Account is valid, name matches exactly

Funding an internal account

Internal accounts are funded from their payment instructions or by pulling from an external account — see Internal Accounts for both. Sandbox adds a shortcut that skips the wait:

curl -X POST https://api.lightspark.com/grid/2025-10-13/sandbox/internal-accounts/{accountId}/fund \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 100000 }'

To exercise the pull path instead, create a quote with an external account as the source and immediatelyExecute set to true. The account’s suffix decides the outcome.

Creating quotes

When creating a quote with an external account destination, the account number suffix determines the payment outcome after quote execution:

Suffix	Behavior
002	Quote execution failed
003	Long payment — completes after approximately 6 minutes
004	Counterparty delivery failed
005	Receiving bank returned payment (completes then transitions to failed)
006	User cancellation
007	Payout and refund failed
Any other	Successful payment

Executing a quote

After creating a quote, you need to fund it to trigger execution. There are two ways to do this in sandbox:

Prefunded internal account — If your quote’s source is an internal account, fund the account using one of the methods described in funding an internal account, then call the quote execute endpoint to trigger the transaction:

curl -X POST https://api.lightspark.com/grid/2025-10-13/quotes/{quoteId}/execute \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

Real-time funding via sandbox send — If your quote uses real-time funding, the quote response includes payment instructions for you to transfer funds to. Use /sandbox/send to simulate this payment:

curl -X POST https://api.lightspark.com/grid/2025-10-13/sandbox/send \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "currencyCode": "USD"
  }'

Sending to a UMA address

For UMA-based payments, use these sandbox addresses to simulate different scenarios:

UMA Address	Behavior
$[e-mail]	Payment succeeds (USD)
$[e-mail]	Payment succeeds (EUR)
$[e-mail]	Payment succeeds (MXN)
$[e-mail]	Simulates a long-pending payment
$[e-mail]	Simulates a compliance check failure

Simulating incoming UMA payments

Use the sandbox receive endpoint to simulate an incoming UMA payment to one of your platform’s users:

curl -X POST https://api.lightspark.com/grid/2025-10-13/sandbox/uma/receive \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "senderUmaAddress": "$[e-mail]",
    "receiverUmaAddress": "$[e-mail]",
    "receivingCurrencyCode": "USD",
    "receivingCurrencyAmount": 5000
  }'

Global Account magic values

The Grid sandbox lets you exercise Global Account auth flows without moving real money. Email OTP and SMS OTP use the fixed sandbox code 000000 — HPKE-encrypt that code in the encryptedOtpBundle just like production. Passkey auth can use the same browser WebAuthn ceremony as production, and signed wallet actions can use the same session signing key and Grid-Wallet-Signature stamp as production. OAuth uses JWT-shaped sandbox OIDC tokens: sandbox skips real IdP signature verification, but still validates token claims, freshness, credential identity, and verify-time nonce binding.

Sandbox runs real HPKE end-to-end for EMAIL_OTP and SMS_OTP: clients build a real encryptedOtpBundle against the sandbox otpEncryptionTargetBundle and sign a real verificationToken with their TEK keypair. The only sandbox shortcut is the magic OTP code the user “receives” instead of a real email or SMS delivery.

Authentication failures return 401 UNAUTHORIZED with a reason field that names the specific check that failed. A malformed OIDC JWT can return 400 INVALID_INPUT before authentication starts.

Email and SMS OTP code

HPKE-encrypt the code 000000 (together with your TEK public key) inside encryptedOtpBundle. The sandbox skips email and SMS delivery but runs real HPKE decryption and signature verification.

See Encrypt the OTP code for how to build the bundle. The flow is the same for both EMAIL_OTP and SMS_OTP:

1. Call POST /auth/credentials/{id}/challenge to get otpEncryptionTargetBundle
2. Generate a TEK key pair and HPKE-encrypt {otp_code: "000000", public_key: tekPublicKeyHex}
3. Submit encryptedOtpBundle to POST /auth/credentials/{id}/verify
4. Receive 202 with payloadToSign and requestId
5. Sign payloadToSign with the TEK private key and retry with Grid-Wallet-Signature + Request-Id headers

# First leg — returns 202 with payloadToSign
curl -X POST https://api.lightspark.com/grid/2025-10-13/auth/credentials/AuthMethod:abc123/verify \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "EMAIL_OTP",
    "encryptedOtpBundle": "{\"encappedPublic\":\"044f631a...\",\"ciphertext\":\"1fa1023390...\"}"
  }'

# Signed retry — returns 200 with AuthSession
curl -X POST https://api.lightspark.com/grid/2025-10-13/auth/credentials/AuthMethod:abc123/verify \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "Grid-Wallet-Signature: eyJwdWJsaWNLZXkiOiIwMmExYjIuLi4i..." \
  -H "Request-Id: Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21" \
  -d '{
    "type": "EMAIL_OTP",
    "encryptedOtpBundle": "{\"encappedPublic\":\"044f631a...\",\"ciphertext\":\"1fa1023390...\"}"
  }'

Any other code (once decrypted) returns 401 UNAUTHORIZED with reason: "Invalid OTP code".

Passkey WebAuthn ceremony

For new sandbox integrations, use the same WebAuthn calls you plan to use in production.

1. Create a WebAuthn credential

   Generate your own WebAuthn registration challenge and call navigator.credentials.create().

2. Register the passkey

   Register the passkey with POST /auth/credentials, passing the challenge and attestation returned by the browser.

3. Request a challenge

   Reauthenticate with POST /auth/credentials/{id}/challenge, passing the P-256 clientPublicKey that Grid should seal the session signing key to.

4. Run the browser assertion

   Pass the returned challenge into navigator.credentials.get() using the returned credentialId in allowCredentials.

5. Verify the assertion

   Verify with POST /auth/credentials/{id}/verify, passing the browser assertion and echoing Request-Id from the challenge response.

The sandbox validates the registered credential ID, WebAuthn challenge, origin/RP binding, user-presence bit, assertion signature, and signature counter. A successful verify response includes encryptedSessionSigningKey, sealed to the clientPublicKey, just like production.

# 1. /challenge with clientPublicKey
curl -X POST https://api.lightspark.com/grid/2025-10-13/auth/credentials/AuthMethod:abc123/challenge \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "clientPublicKey": "04f45f2a..."
  }'

# 2. /verify with the browser assertion returned by navigator.credentials.get()
curl -X POST https://api.lightspark.com/grid/2025-10-13/auth/credentials/AuthMethod:abc123/verify \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "Request-Id: Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21" \
  -d '{
    "type": "PASSKEY",
    "assertion": {
      "credentialId": "...",
      "clientDataJson": "...",
      "authenticatorData": "...",
      "signature": "..."
    }
  }'

The legacy sandbox-only assertion signature sandbox-valid-passkey-signature is still accepted for compatibility, but it skips WebAuthn verification and should not be used for production-shaped sandbox tests.

OAuth (OIDC) token

OAuth does not use a fixed magic token in sandbox. Pass a JWT-shaped OIDC token as oidcToken. The JWT signature segment can be a dummy value, but the payload must look like a real ID token.

For POST /auth/credentials with type: "OAUTH", the sandbox token must include:

• iss: a supported issuer, such as https://accounts.google.com, accounts.google.com, or https://appleid.apple.com
• aud: a non-empty string, or a single-element string array
• sub: a non-empty subject identifier for the user
• iat: a numeric issued-at timestamp no more than 60 seconds before the request, with 5 seconds of clock skew allowed
• exp: a numeric expiration timestamp later than the request time

Grid stores the OAuth credential’s registered identity from iss, aud, and sub. On POST /auth/credentials/{id}/verify, the fresh oidcToken must carry the same iss, aud, and sub as the credential being verified. It must also include nonce equal to sha256(clientPublicKey), where clientPublicKey is the exact hex public key sent in the verify request.

export PUBLIC_KEY="04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2"
OIDC_TOKEN=$(node - <<'NODE'
const crypto = require("crypto");

const publicKey = process.env.PUBLIC_KEY || "04f45f2a22c908b9ce09a7150e514afd24627c401c38a4afc164e1ea783adaaa31d4245acfb88c2ebd42b47628d63ecabf345484f0a9f665b63c54c897d5578be2";
const now = Math.floor(Date.now() / 1000);
const b64url = (value) =>
  Buffer.from(JSON.stringify(value)).toString("base64url");

const payload = {
  iss: "https://accounts.google.com",
  sub: "sandbox-user-123",
  aud: "grid-sandbox-oauth-client-id",
  iat: now,
  exp: now + 300,
  nonce: crypto.createHash("sha256").update(publicKey).digest("hex"),
  email: "[e-mail]",
  email_verified: true
};

console.log(
  `${b64url({ alg: "RS256", typ: "JWT" })}.${b64url(payload)}.sandbox-signature`
);
NODE
)

curl -X POST https://api.lightspark.com/grid/2025-10-13/auth/credentials/AuthMethod:abc123/verify \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "OAUTH",
    "oidcToken": "'"$OIDC_TOKEN"'",
    "clientPublicKey": "'"$PUBLIC_KEY"'"
  }'

The old literal sandbox-valid-oidc-token is no longer accepted. Use a freshly generated sandbox JWT for both OAuth credential registration and OAuth verification. Production requires a real ID token from your provider and verifies the provider signature.

Wallet signature header

For PASSKEY and OAUTH credentials, decrypt encryptedSessionSigningKey with the private key matching the clientPublicKey you supplied on verify or refresh. For EMAIL_OTP, the TEK private key you generated for the encrypted OTP flow is the session signing key — no decryption step needed. Use the session signing key to build a Grid wallet signature over the exact payloadToSign string returned by Grid, then pass that full signature as the Grid-Wallet-Signature HTTP header on signed flows:

• POST /auth/credentials (add-additional-credential signed retry)
• DELETE /auth/credentials/{id} (revoke credential)
• DELETE /auth/sessions/{id} (revoke session)
• POST /internal-accounts/{id}/export (export wallet)
• PATCH /internal-accounts/{id} (update wallet privacy)
• POST /quotes/{quoteId}/execute (when source is an embedded wallet)

This example uses the sample signer in the Grid API repo’s scripts directory. See the scripts README for setup, or replace SIGN with your own Grid wallet-signature implementation.

SIGN="node $(pwd)/scripts/embedded-wallet-sign.js"
STAMP=$($SIGN stamp "$SESSION_PRIV_HEX" "$PAYLOAD_TO_SIGN")

curl -X POST https://api.lightspark.com/grid/2025-10-13/quotes/Quote:abc123/execute \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21" \
  -H "Grid-Wallet-Signature: $STAMP"

Sandbox validates that the signature is a P-256 signature over the exact pending Grid payload and that the public key belongs to an active sandbox session for the wallet.

The legacy sandbox-only Grid-Wallet-Signature: sandbox-valid-signature value is still accepted for compatibility. Use a real session stamp when you want the client implementation to match production.