Customers & VICs

A customer is a verified identity associated with your merchant account. Each customer reaches PersonaBlocks through one of two rails and, on success, carries a Verifiable Identity Certificate.

Identity type

A customer’s identity_type records which rail they used:

• sovereign — verified with a crypto wallet they control and sign with.
• phone — verified through delegated (custodial) phone enrollment.

The rail affects how the customer authenticates, not what you get back — both mint the same kind of VIC.

Verifiable Identity Certificates (VICs)

A VIC (Verifiable Identity Certificate) is the on-chain credential a successful verification mints. It anchors the customer’s verified attributes and their current status. Because a VIC is reusable, a customer who has already verified — with you or with another merchant — can be recognized without repeating the full flow. That reuse is the core of the model: verify once, present anywhere.

How customers become associated with you

A customer is linked to your account through an association method, recorded on the customer object:

• Invite — you invited the customer to verify.
• Address — you added them manually by address.
• Woo — they came through a WooCommerce checkout / authorize flow on your store.
• SDK session — they completed a verification session you minted via the API and opened with the SDK.

The method is informational context on where the relationship came from; all of them produce a customer you can read through the API.

Statuses

A VIC has a status reflecting its current standing — for example approved, under review, or a restricted state. A customer whose status is under review has been flagged for a closer look before their credential is fully trusted.

Note

The API surfaces status at a high level so your integration can gate access. The detailed review workflow — how a flag is raised, examined, and resolved — lives in the merchant console, not the public API. Treat under review as “not yet cleared,” and drive the resolution from the console.

Tracking status changes

There are two complementary ways to keep your records current as a customer’s status changes:

• Webhook — subscribe to customer.kyc_status.changed to be pushed an event the moment a customer’s status changes. This is the real-time path.
• Polling — pass updated_since (an ISO 8601 timestamp or unix seconds) when listing customers to fetch only those changed since your last sync. This is the reconciliation path — use it to catch up after downtime or to backfill.

Most integrations use the webhook for immediacy and updated_since polling as a safety net.

Related

• Verification sessions — the flow that mints a customer’s VIC.
• Webhooks — subscribing to customer.kyc_status.changed.
• Data minimization — what the customer object will never contain.