Verify a customer in sandbox

What happens when you verify a sandbox customer today, what you cannot test, and how to keep building while sandbox verification does not complete.

Use this recipe to see what happens when you verify a sandbox customer today, what you cannot test, and how to keep building while sandbox verification does not complete.

Who it is for. A neobank that is building its onboarding screens and needs verified sandbox customers to open accounts and cards.

Status. Not yet available. A sandbox verification does not complete for a new customer, and you cannot test a rejection or a resubmission.

Money example

No money moves here, but verification decides what money can move. You create Amara in sandbox, and she finishes the hosted check. Her basic verification stays pending, so you cannot open a USD account or a card for her. You ask support for an already verified sandbox customer and test accounts and cards with that customer instead.

Before you start

A sandbox key. The customer fields follow the same rules as in live. Send a phone number in a real format, and ISO country and state codes. See Verify a person on a hosted page.

Find out what is required

GET /v1/customers/{customer_id} shows each level's status in kyc[]. Start only when basic is not_started or failed. Read status, not verified_at. Gravv sets verified_at on every row when it creates the customer.

Steps

1. Create the customer and start the hosted check

Follow Verify a person on a hosted page with your sandbox key. The web_url in the response opens the verification partner's test page.

2. See what happens today

curl --request GET \
 --url https://api.gravv.xyz/v1/customers/3f6b2a1e-8c4d-4e7f-9a2b-5c1d0e9f8a71/kyc/status \
 --header 'Api-Key: <API_KEY>'

const response = await fetch("https://api.gravv.xyz/v1/customers/3f6b2a1e-8c4d-4e7f-9a2b-5c1d0e9f8a71/kyc/status", {
method: "GET",
headers: {
"Api-Key": process.env.GRAVV_API_KEY,
},
});
console.log(response.status, await response.json());

import os

import requests

response = requests.get(
"https://api.gravv.xyz/v1/customers/3f6b2a1e-8c4d-4e7f-9a2b-5c1d0e9f8a71/kyc/status",
headers={
    "Api-Key": os.environ["GRAVV_API_KEY"],
},
)
print(response.status_code, response.json())

Within about 3 minutes of submitting, the review comes back rejected with a retry (reviewAnswer rejected, reviewRejectType RETRY), whatever you uploaded. The basic row stays pending, and Gravv sends no customer.kyc.status.completed or customer.kyc.status.failed. Stop polling after a few minutes.

3. Keep building with a verified customer

Ask Gravv support for an already verified sandbox customer, and use that customer for accounts and cards. Test the rejected screen with a recorded customer.kyc.status.failed payload.

What can go wrong

Response	Why	Fix
The row stays `pending`, and `kyc/status` shows `reviewStatus` `completed` and `reviewAnswer` `rejected`	Sandbox verification does not complete today	Changing the images or restarting does not help. Use a verified sandbox customer from support
The row stays `pending`, and `kyc/status` shows `reviewStatus` `pending`	The customer did not submit the hosted steps	Finish the hosted page. If needed, start again once the link's 1 hour has passed
`CUSTOMER_KYC_INCOMPLETE` on `POST /v2/accounts`	The customer is not verified	Use a verified sandbox customer
500 `failed to upload documents to verification provider` on a second server-to-server start	You resubmitted after the rejected review	Do not retry in a loop
413 `the uploaded file is too large — the maximum is 10MB` on a small file	Sandbox refuses files from about 600 KB	Send JPEG or PDF files under 500 KB
`associated person "<name>" must complete basic KYC before business verification can proceed`	A business's people cannot complete verification in sandbox today	You cannot test business verification today