Customers and KYC

Choose the recipe for creating a person or a business, verifying them, fixing a rejection, downloading a document, and the limits that apply once KYC passes.

Use these recipes to get a customer ready to hold and move money. You create the customer, verify their identity (KYC) and fix what goes wrong. Every account and every payout starts here, because Gravv opens an account only for a customer whose basic KYC is completed.

Money example. Amara, a nurse in Lagos, signs up with your app. Before KYC, the standard limits let her move 500.00 USD a day. She passes the hosted ID check, her KYC is completed, and the limit becomes 50,000.00 USD a day. You can now open the USD account that her employer pays her 1,200.00 USD salary into.

Choose your recipe

You want to	Status	Recipe
Create a person and verify them on Gravv's hosted page, with a liveness check	Available	Verify a person on a hosted page
Verify a person with an ID and selfie you already hold	Available	Verify a person with documents you upload
Create a company with its owners and directors, and verify all of them	Available	Onboard a business and its owners
Try again after KYC `failed`	Available	Resubmit KYC after a rejection
Get a copy of an uploaded ID for a compliance review	Available	Download a KYC document
Know how much a customer can send, and raise it	Available	Raise a customer's limits with KYC
A payout paused for the sender's name or date of birth	Available	Avoid a payout pause for sender details

The intermediate KYC level is Not yet available. Every customer has the row, but no API call starts it. Card KYC with liveness is in the card KYC flow.

Which way to verify

Customer	Hosted page (`/kyc/start`)	Documents you upload (`/kyc/upload-document` + `/kyc/start-s2s`)
A person	Available, with a liveness check	Available, no liveness check
A business's associated person	Available, with the person's own id	Available, with the person's own id
A business	Available, after every associated person is verified	Available, with four company documents, after every person is verified
On a business Gravv set up for automatic verification	Not supported. The API refuses the start	Available. KYC completes from the documents

Gravv bills a hosted start once, and a restart after a failure or an expired link is free. Gravv bills every server-to-server start again.

Rules every recipe relies on

Send every request to one host, https://api.gravv.xyz, with the Api-Key header. A key that starts with grvSec_sandbox_ reaches sandbox; any other key is live. Sandbox and live data are separate, so an id from one is "not found" in the other.
Every POST needs its own new Idempotency-Key. Gravv replays a 4xx response for 24 hours under its key, so use a new key after you fix a request. Keep the same key only after a timeout or a 5xx.
Customer and KYC errors return {"data": null, "error": "<text>"}, with error as a string. KYC error texts start with a code such as INVALID_REQUEST:. Gateway errors, such as a reused key, carry an object instead.
A scoped key needs customer:create to create, customer:update to update, upload or download, and customer:update or customer:kyc_override to start KYC.
The decision that counts is kyc[type=basic].status on GET /v1/customers/{customer_id}, or the customer.kyc.status.* webhook. Deduplicate webhooks on the body's event_id.
Sandbox KYC does not complete today. Create, upload, start and the hosted link work. The basic row stays pending and Gravv sends no outcome webhook, so you cannot finish steps that need a verified customer in sandbox yet.