From dcc7ed6ed9f5cd95f21d114c4e1cdcecb9a1d37b Mon Sep 17 00:00:00 2001 From: TTyChud Date: Mon, 21 Sep 2026 15:42:04 +0530 Subject: [PATCH 1/3] docs: add identity verification sessions to the api reference --- apps/docs/src/app/pages/docs/data/connect.ts | 8 + .../data/identity-verification-sessions.ts | 1046 +++++++++++++++++ apps/docs/src/app/pages/docs/data/index.ts | 1 + apps/docs/src/app/pages/docs/docs-catalog.ts | 2 + 4 files changed, 1057 insertions(+) create mode 100644 apps/docs/src/app/pages/docs/data/identity-verification-sessions.ts diff --git a/apps/docs/src/app/pages/docs/data/connect.ts b/apps/docs/src/app/pages/docs/data/connect.ts index 2fd4ec6..8106640 100644 --- a/apps/docs/src/app/pages/docs/data/connect.ts +++ b/apps/docs/src/app/pages/docs/data/connect.ts @@ -21,6 +21,7 @@ import { INVOICE_ITEMS_SUBSECTION } from './invoice-items'; import { INVOICES_SUBSECTION } from './invoices'; import { BILLING_SUBSECTION } from './billing'; import { EVENTS_SUBSECTION } from './events'; +import { IDENTITY_VERIFICATION_SESSIONS_SUBSECTION } from './identity-verification-sessions'; import { WEBHOOK_ENDPOINTS_SUBSECTION } from './webhook-endpoints'; export const CORE_RESOURCES_SECTION: DocSection = { @@ -80,6 +81,12 @@ export const CONNECT_SECTION: DocSection = { ], }; +export const IDENTITY_SECTION: DocSection = { + id: 'identity', + title: 'Identity', + children: [IDENTITY_VERIFICATION_SESSIONS_SUBSECTION], +}; + export const WEBHOOKS_SECTION: DocSection = { id: 'webhooks-section', title: 'Webhooks', @@ -93,5 +100,6 @@ export const API_SECTIONS: DocSection[] = [ PAYMENT_LINKS_SECTION, BILLING_SECTION, CONNECT_SECTION, + IDENTITY_SECTION, WEBHOOKS_SECTION, ]; diff --git a/apps/docs/src/app/pages/docs/data/identity-verification-sessions.ts b/apps/docs/src/app/pages/docs/data/identity-verification-sessions.ts new file mode 100644 index 0000000..69473db --- /dev/null +++ b/apps/docs/src/app/pages/docs/data/identity-verification-sessions.ts @@ -0,0 +1,1046 @@ +import { DocSubSection, DocPage, Attribute } from './types'; +import { GetResourceEventAttributes } from './event-types'; +import { NODE_INIT, BuildEndpointSummaries } from './shared'; + +export const IDENTITY_VERIFICATION_SESSIONS_SUBSECTION: DocSubSection = { + id: 'identity-verification-sessions', + title: 'Verification Sessions', + children: [ + { id: 'object', title: 'The VerificationSession object' }, + { id: 'create', title: 'Create a VerificationSession' }, + { id: 'update', title: 'Update a VerificationSession' }, + { id: 'retrieve', title: 'Retrieve a VerificationSession' }, + { id: 'list', title: 'List VerificationSessions' }, + { id: 'cancel', title: 'Cancel a VerificationSession' }, + { id: 'redact', title: 'Redact a VerificationSession' }, + ], +}; + +// ============================================ +// Shared Data +// ============================================ +const VERIFICATION_SESSION_OBJECT_JSON = `{ + "id": "vs_z_7Kd2mQxT4Rb9LpVn", + "object": "identity.verification_session", + "client_secret": "vs_z_7Kd2mQxT4Rb9LpVn_token_5fJ2qL", + "created": 1784572800, + "last_error": null, + "last_verification_report": null, + "livemode": false, + "metadata": {}, + "options": null, + "provided_details": null, + "redaction": null, + "status": "requires_input", + "type": "document", + "url": "https://verify.didit.me/session/9f2c7a1d4e6b", + "related_account": "acct_z_1Nv0FGQ9RKHgCVdK", + "related_person": "person_z_1Nv0FGQ9RKHgCVdK", + "platform_account": "acct_z_Platform123abc", + "provider": "didit", + "provider_session_id": "3f8a1c92-7b64-4d0e-9a51-2c7e5b8d1046" +}`; + +const DOCUMENT_OPTION_ATTRIBUTES: Attribute[] = [ + { + name: 'allowed_types', + type: 'array of enums', + nullable: true, + description: + 'The document types the seller may present. Defaults to all supported types.', + enumValues: ['driving_license', 'id_card', 'passport'], + }, + { + name: 'require_live_capture', + type: 'boolean', + nullable: true, + description: + 'Whether the seller must capture the document with a camera instead of uploading a file.', + }, + { + name: 'require_matching_selfie', + type: 'boolean', + nullable: true, + description: + 'Whether the seller must take a selfie that matches the photo on the document.', + }, +]; + +const DETAILS_ATTRIBUTES: Attribute[] = [ + { + name: 'email', + type: 'string', + nullable: true, + description: + 'Email address the seller can be reached at. The provider emails the seller here when the flow needs attention.', + }, + { + name: 'phone', + type: 'string', + nullable: true, + description: + 'Phone number the seller can be reached at. Must be 32 characters or fewer.', + }, +]; + +const VERIFICATION_SESSION_ATTRIBUTES: Attribute[] = [ + { + name: 'id', + type: 'string', + description: + 'Unique identifier for the object. Zoneless verification session IDs are prefixed with vs_z_.', + }, + { + name: 'object', + type: 'string', + description: + "String representing the object's type. Objects of the same type share the same value. Always identity.verification_session.", + }, + { + name: 'client_secret', + type: 'string', + nullable: true, + description: + 'A short-lived secret that lets your client open the verification flow without your secret key. Zoneless returns the provider session token, or null once the session is canceled or redacted.', + }, + { + name: 'created', + type: 'timestamp', + description: + 'Time at which the object was created. Measured in seconds since the Unix epoch.', + }, + { + name: 'last_error', + type: 'object', + nullable: true, + description: 'The most recent error that occurred during the verification.', + children: [ + { + name: 'code', + type: 'string', + nullable: true, + description: + 'A short machine-readable string giving the reason for the error.', + }, + { + name: 'reason', + type: 'string', + nullable: true, + description: + 'A human-readable message giving the reason for the error. These messages can be shown to the seller.', + }, + ], + }, + { + name: 'last_verification_report', + type: 'string', + nullable: true, + description: + 'ID of the most recent verification report. Zoneless returns null: the outcome of the check is reported through status and the session webhook events.', + }, + { + name: 'livemode', + type: 'boolean', + description: + 'Has the value true if the object exists in live mode or the value false if the object exists in test mode.', + }, + { + name: 'metadata', + type: 'object', + description: + 'Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.', + }, + { + name: 'options', + type: 'object', + nullable: true, + description: 'A set of options for the verification session.', + children: [ + { + name: 'document', + type: 'object', + description: 'Options for a document verification session.', + children: DOCUMENT_OPTION_ATTRIBUTES, + }, + ], + }, + { + name: 'platform_account', + type: 'string', + description: + 'Zoneless extension: The platform account that owns this session.', + }, + { + name: 'provided_details', + type: 'object', + nullable: true, + description: + 'Details about the seller that the provider already has, so the seller is not asked for them again.', + children: DETAILS_ATTRIBUTES, + }, + { + name: 'provider', + type: 'enum', + description: + 'Zoneless extension: The identity provider that fulfils this session.', + enumValues: [ + { + value: 'didit', + description: 'The session is fulfilled by Didit.', + }, + ], + }, + { + name: 'provider_session_id', + type: 'string', + description: + "Zoneless extension: The provider's own ID for this session. Use it to match a session against the provider's dashboard or webhook payloads.", + }, + { + name: 'redaction', + type: 'object', + nullable: true, + description: + 'Redaction status of the session. Zoneless sets redacted as soon as the request succeeds, and never reports a redaction in progress.', + children: [ + { + name: 'status', + type: 'enum', + description: 'Whether the session has been redacted.', + enumValues: [ + { + value: 'redacted', + description: 'The session has been redacted.', + }, + ], + }, + ], + }, + { + name: 'related_account', + type: 'string', + description: + 'Zoneless extension: The connected account this session verifies.', + }, + { + name: 'related_person', + type: 'string', + description: + "Zoneless extension: The person on the connected account this session verifies. Defaults to the account's individual.", + }, + { + name: 'status', + type: 'enum', + description: + 'The status of the verification session. Zoneless never sets requires_action.', + enumValues: [ + { + value: 'requires_input', + description: + 'The verification has not been completed. Either the seller has not yet finished the flow, or the provider asked for another attempt.', + }, + { + value: 'processing', + description: + 'The provider is reviewing the submitted documents or the seller is midway through the flow.', + }, + { + value: 'verified', + description: + 'The verification check passed and the seller is verified.', + }, + { + value: 'canceled', + description: 'The session was canceled and can no longer be used.', + }, + ], + }, + { + name: 'type', + type: 'enum', + description: + 'The type of verification check. Defaults to document. The check the seller completes follows the workflow configured for your platform, which is the KYB workflow when the account is a business and a KYB workflow is set.', + enumValues: [ + { + value: 'document', + description: + 'The seller presents a government-issued document such as a passport or driving license.', + }, + { + value: 'id_number', + description: 'The seller is verified against an ID number.', + }, + { + value: 'address', + description: 'The seller is verified against an address.', + }, + { + value: 'verification_flow', + description: 'The checks are picked by the provider workflow.', + }, + ], + }, + { + name: 'url', + type: 'string', + nullable: true, + description: + 'The URL for the hosted verification flow. Redirect the seller to this URL to start the check. Zoneless returns null once the session is canceled or redacted.', + }, +]; + +// ============================================ +// Create Verification Session Parameters +// ============================================ +const CREATE_VERIFICATION_SESSION_PARAMETERS: Attribute[] = [ + { + name: 'metadata', + type: 'object', + description: + 'Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.', + }, + { + name: 'options', + type: 'object', + description: 'A set of options for the verification session.', + children: [ + { + name: 'document', + type: 'object', + description: 'Options for a document verification session.', + children: DOCUMENT_OPTION_ATTRIBUTES, + }, + ], + }, + { + name: 'provided_details', + type: 'object', + description: + 'Details about the seller, so the provider does not ask for them again.', + children: DETAILS_ATTRIBUTES, + }, + { + name: 'related_account', + type: 'string', + required: true, + description: + 'Zoneless extension: The connected account to verify. A platform can verify any account it owns; a connected account can only verify itself.', + }, + { + name: 'related_person', + type: 'string', + description: + "Zoneless extension: The person on the account to verify. Defaults to the account's individual.", + }, + { + name: 'return_url', + type: 'string', + description: + 'The URL the seller is redirected to when they finish or leave the verification flow. Must be a valid URL.', + }, + { + name: 'type', + type: 'enum', + description: + 'The type of verification check. Defaults to document.', + enumValues: [ + { value: 'document', description: 'A government-issued document.' }, + { value: 'id_number', description: 'An ID number.' }, + { value: 'address', description: 'An address.' }, + { value: 'verification_flow', description: 'The provider workflow.' }, + ], + }, +]; + +const CREATE_VERIFICATION_SESSION_RESPONSE_JSON = + VERIFICATION_SESSION_OBJECT_JSON; + +// ============================================ +// Update Verification Session Parameters +// ============================================ +const UPDATE_VERIFICATION_SESSION_PARAMETERS: Attribute[] = [ + { + name: 'metadata', + type: 'object', + description: + 'Set of key-value pairs that you can attach to an object. This merges into the metadata already on the session.', + }, + { + name: 'options', + type: 'object', + description: 'A set of updated options for the verification session.', + children: [ + { + name: 'document', + type: 'object', + description: 'Options for a document verification session.', + children: DOCUMENT_OPTION_ATTRIBUTES, + }, + ], + }, + { + name: 'provided_details', + type: 'object', + description: 'Updated details about the seller.', + children: DETAILS_ATTRIBUTES, + }, +]; + +const UPDATE_VERIFICATION_SESSION_RESPONSE_JSON = `{ + "id": "vs_z_7Kd2mQxT4Rb9LpVn", + "object": "identity.verification_session", + "client_secret": "vs_z_7Kd2mQxT4Rb9LpVn_token_5fJ2qL", + "created": 1784572800, + "last_error": null, + "last_verification_report": null, + "livemode": false, + "metadata": { + "order_id": "6735" + }, + "options": null, + "provided_details": null, + "redaction": null, + "status": "requires_input", + "type": "document", + "url": "https://verify.didit.me/session/9f2c7a1d4e6b", + "related_account": "acct_z_1Nv0FGQ9RKHgCVdK", + "related_person": "person_z_1Nv0FGQ9RKHgCVdK", + "platform_account": "acct_z_Platform123abc", + "provider": "didit", + "provider_session_id": "3f8a1c92-7b64-4d0e-9a51-2c7e5b8d1046" +}`; + +// ============================================ +// List Verification Sessions Parameters +// ============================================ +const LIST_VERIFICATION_SESSION_PARAMETERS: Attribute[] = [ + { + name: 'created', + type: 'object', + description: + 'Only return sessions that were created during the given date interval.', + children: [ + { + name: 'gt', + type: 'integer', + description: 'Minimum value to filter by (exclusive).', + }, + { + name: 'gte', + type: 'integer', + description: 'Minimum value to filter by (inclusive).', + }, + { + name: 'lt', + type: 'integer', + description: 'Maximum value to filter by (exclusive).', + }, + { + name: 'lte', + type: 'integer', + description: 'Maximum value to filter by (inclusive).', + }, + ], + }, + { + name: 'ending_before', + type: 'string', + description: + 'A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with vs_z_bar, your subsequent call can include ending_before=vs_z_bar in order to fetch the previous page of the list.', + }, + { + name: 'limit', + type: 'integer', + description: + 'A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.', + }, + { + name: 'related_account', + type: 'string', + description: + 'Zoneless extension: Only return sessions that verify this connected account.', + }, + { + name: 'starting_after', + type: 'string', + description: + 'A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with vs_z_foo, your subsequent call can include starting_after=vs_z_foo in order to fetch the next page of the list.', + }, + { + name: 'status', + type: 'enum', + description: 'Only return sessions with the given status.', + enumValues: [ + { value: 'requires_input' }, + { value: 'processing' }, + { value: 'verified' }, + { value: 'canceled' }, + ], + }, +]; + +const LIST_VERIFICATION_SESSION_RESPONSE_JSON = `{ + "object": "list", + "url": "/v1/identity/verification_sessions", + "has_more": false, + "data": [ + { + "id": "vs_z_7Kd2mQxT4Rb9LpVn", + "object": "identity.verification_session", + "client_secret": "vs_z_7Kd2mQxT4Rb9LpVn_token_5fJ2qL", + "created": 1784572800, + "last_error": null, + "last_verification_report": null, + "livemode": false, + "metadata": {}, + "options": null, + "provided_details": null, + "redaction": null, + "status": "requires_input", + "type": "document", + "url": "https://verify.didit.me/session/9f2c7a1d4e6b", + "related_account": "acct_z_1Nv0FGQ9RKHgCVdK", + "related_person": "person_z_1Nv0FGQ9RKHgCVdK", + "platform_account": "acct_z_Platform123abc", + "provider": "didit", + "provider_session_id": "3f8a1c92-7b64-4d0e-9a51-2c7e5b8d1046" + } + ] +}`; + +// ============================================ +// Cancel and Redact Responses +// ============================================ +const CANCEL_VERIFICATION_SESSION_RESPONSE_JSON = `{ + "id": "vs_z_7Kd2mQxT4Rb9LpVn", + "object": "identity.verification_session", + "client_secret": null, + "created": 1784572800, + "last_error": null, + "last_verification_report": null, + "livemode": false, + "metadata": {}, + "options": null, + "provided_details": null, + "redaction": null, + "status": "canceled", + "type": "document", + "url": null, + "related_account": "acct_z_1Nv0FGQ9RKHgCVdK", + "related_person": "person_z_1Nv0FGQ9RKHgCVdK", + "platform_account": "acct_z_Platform123abc", + "provider": "didit", + "provider_session_id": "3f8a1c92-7b64-4d0e-9a51-2c7e5b8d1046" +}`; + +const REDACT_VERIFICATION_SESSION_RESPONSE_JSON = `{ + "id": "vs_z_7Kd2mQxT4Rb9LpVn", + "object": "identity.verification_session", + "client_secret": null, + "created": 1784572800, + "last_error": null, + "last_verification_report": null, + "livemode": false, + "metadata": {}, + "options": null, + "provided_details": null, + "redaction": { + "status": "redacted" + }, + "status": "verified", + "type": "document", + "url": null, + "related_account": "acct_z_1Nv0FGQ9RKHgCVdK", + "related_person": "person_z_1Nv0FGQ9RKHgCVdK", + "platform_account": "acct_z_Platform123abc", + "provider": "didit", + "provider_session_id": "3f8a1c92-7b64-4d0e-9a51-2c7e5b8d1046" +}`; + +// ============================================ +// Pages +// ============================================ +export const IDENTITY_VERIFICATION_SESSIONS_OVERVIEW_PAGE: DocPage = { + id: 'object', + title: 'The VerificationSession object', + description: + 'A VerificationSession guides a connected account through an identity check and reports the result. It records the type of verification and the provider-hosted link the seller completes the check on.', + stripeDocsUrl: + 'https://docs.stripe.com/api/identity/verification_sessions/object', + endpoints: BuildEndpointSummaries(IDENTITY_VERIFICATION_SESSIONS_SUBSECTION, [ + { + method: 'POST', + path: '/v1/identity/verification_sessions', + pageId: 'create', + }, + { + method: 'POST', + path: '/v1/identity/verification_sessions/:id', + pageId: 'update', + }, + { + method: 'GET', + path: '/v1/identity/verification_sessions/:id', + pageId: 'retrieve', + }, + { + method: 'GET', + path: '/v1/identity/verification_sessions', + pageId: 'list', + }, + { + method: 'POST', + path: '/v1/identity/verification_sessions/:id/cancel', + pageId: 'cancel', + }, + { + method: 'POST', + path: '/v1/identity/verification_sessions/:id/redact', + pageId: 'redact', + }, + ]), + events: GetResourceEventAttributes('identity.verification_session'), + sections: [ + { + left: [ + { + type: 'callout', + variant: 'info', + title: 'Key concept: ', + text: 'A session moves between requires_input, processing, verified and canceled. Create one, redirect the seller to its url, then follow the result through the session webhook events rather than polling.', + html: true, + }, + { + type: 'paragraph', + text: 'Zoneless runs the check through the identity provider configured for your platform. The session holds the provider session ID and a link the seller completes the check on, and reports the outcome back on status.', + html: true, + }, + { type: 'heading', level: 2, text: 'Attributes' }, + { type: 'attributes', attributes: VERIFICATION_SESSION_ATTRIBUTES }, + ], + right: [ + { + type: 'object', + title: 'THE VERIFICATIONSESSION OBJECT', + code: VERIFICATION_SESSION_OBJECT_JSON, + }, + ], + }, + ], +}; + +export const IDENTITY_VERIFICATION_SESSIONS_CREATE_PAGE: DocPage = { + id: 'create', + title: 'Create a VerificationSession', + description: + 'Creates a VerificationSession object. Send the seller to the returned url to start the check.', + stripeDocsUrl: + 'https://docs.stripe.com/api/identity/verification_sessions/create', + endpoints: [{ method: 'POST', path: '/v1/identity/verification_sessions' }], + sections: [ + { + left: [ + { + type: 'callout', + variant: 'warning', + title: 'Provider credentials: ', + text: 'Zoneless starts the check with the API key and workflow ID saved in your platform identity settings. Without them the request is rejected.', + }, + { + type: 'paragraph', + text: 'Platforms create sessions for their connected accounts. A connected account can create a session for itself only, and must pass its own ID as related_account.', + html: true, + }, + { type: 'heading', level: 2, text: 'Parameters' }, + { + type: 'attributes', + attributes: CREATE_VERIFICATION_SESSION_PARAMETERS, + }, + { type: 'heading', level: 2, text: 'Returns' }, + { + type: 'paragraph', + text: 'Returns a VerificationSession object with the status the provider reports for the new session, typically requires_input. Raises an error if the account is not owned by your platform or identity verification is not configured.', + html: true, + }, + ], + right: [ + { + type: 'code', + endpoint: { + method: 'POST', + path: '/v1/identity/verification_sessions', + }, + tabs: [ + { + id: 'curl', + label: 'cURL', + code: `curl https://api.yourdomain.com/v1/identity/verification_sessions \\ + -H "x-api-key: sk_live_z_YOUR_API_KEY" \\ + -d type=document \\ + -d related_account=acct_z_1Nv0FGQ9RKHgCVdK \\ + --data-urlencode return_url="https://example.com/identity/return"`, + }, + { + id: 'node', + label: 'Node.js', + code: `${NODE_INIT} + +const session = await zoneless.identity.verificationSessions.create({ + type: 'document', + related_account: 'acct_z_1Nv0FGQ9RKHgCVdK', + return_url: 'https://example.com/identity/return', +});`, + }, + ], + }, + { + type: 'object', + title: 'RESPONSE', + code: CREATE_VERIFICATION_SESSION_RESPONSE_JSON, + }, + ], + }, + ], +}; + +export const IDENTITY_VERIFICATION_SESSIONS_UPDATE_PAGE: DocPage = { + id: 'update', + title: 'Update a VerificationSession', + description: + 'Updates a VerificationSession object. Only sessions with the requires_input status can be updated.', + stripeDocsUrl: + 'https://docs.stripe.com/api/identity/verification_sessions/update', + endpoints: [ + { method: 'POST', path: '/v1/identity/verification_sessions/:id' }, + ], + sections: [ + { + left: [ + { + type: 'callout', + variant: 'info', + title: 'When updates are allowed: ', + text: 'A session can only be updated while its status is requires_input. Metadata is merged into the values already on the session.', + html: true, + }, + { + type: 'paragraph', + text: 'The session type cannot be changed once it is created, and a request with no parameters is rejected.', + html: true, + }, + { type: 'heading', level: 2, text: 'Parameters' }, + { + type: 'attributes', + attributes: UPDATE_VERIFICATION_SESSION_PARAMETERS, + }, + { type: 'heading', level: 2, text: 'Returns' }, + { + type: 'paragraph', + text: 'Returns the updated VerificationSession object.', + html: true, + }, + ], + right: [ + { + type: 'code', + endpoint: { + method: 'POST', + path: '/v1/identity/verification_sessions/:id', + }, + tabs: [ + { + id: 'curl', + label: 'cURL', + code: `curl https://api.yourdomain.com/v1/identity/verification_sessions/vs_z_7Kd2mQxT4Rb9LpVn \\ + -H "x-api-key: sk_live_z_YOUR_API_KEY" \\ + -d "metadata[order_id]"=6735`, + }, + { + id: 'node', + label: 'Node.js', + code: `${NODE_INIT} + +const session = await zoneless.identity.verificationSessions.update( + 'vs_z_7Kd2mQxT4Rb9LpVn', + { + metadata: { + order_id: '6735', + }, + } +);`, + }, + ], + }, + { + type: 'object', + title: 'RESPONSE', + code: UPDATE_VERIFICATION_SESSION_RESPONSE_JSON, + }, + ], + }, + ], +}; + +export const IDENTITY_VERIFICATION_SESSIONS_RETRIEVE_PAGE: DocPage = { + id: 'retrieve', + title: 'Retrieve a VerificationSession', + description: 'Retrieves a VerificationSession object.', + stripeDocsUrl: + 'https://docs.stripe.com/api/identity/verification_sessions/retrieve', + endpoints: [ + { method: 'GET', path: '/v1/identity/verification_sessions/:id' }, + ], + sections: [ + { + left: [ + { type: 'heading', level: 2, text: 'Parameters' }, + { type: 'paragraph', text: 'No parameters.' }, + { type: 'heading', level: 2, text: 'Returns' }, + { + type: 'paragraph', + text: 'Returns a VerificationSession object for a session your platform owns. Raises an error if the session does not exist.', + html: true, + }, + ], + right: [ + { + type: 'code', + endpoint: { + method: 'GET', + path: '/v1/identity/verification_sessions/:id', + }, + tabs: [ + { + id: 'curl', + label: 'cURL', + code: `curl https://api.yourdomain.com/v1/identity/verification_sessions/vs_z_7Kd2mQxT4Rb9LpVn \\ + -H "x-api-key: sk_live_z_YOUR_API_KEY"`, + }, + { + id: 'node', + label: 'Node.js', + code: `${NODE_INIT} + +const session = await zoneless.identity.verificationSessions.retrieve( + 'vs_z_7Kd2mQxT4Rb9LpVn' +);`, + }, + ], + }, + { + type: 'object', + title: 'RESPONSE', + code: VERIFICATION_SESSION_OBJECT_JSON, + }, + ], + }, + ], +}; + +export const IDENTITY_VERIFICATION_SESSIONS_LIST_PAGE: DocPage = { + id: 'list', + title: 'List VerificationSessions', + description: + 'Returns a list of VerificationSessions your platform created. The sessions are returned sorted by creation date, with the most recent appearing first.', + stripeDocsUrl: + 'https://docs.stripe.com/api/identity/verification_sessions/list', + endpoints: [{ method: 'GET', path: '/v1/identity/verification_sessions' }], + sections: [ + { + left: [ + { + type: 'callout', + variant: 'info', + title: 'Platform only: ', + text: 'Listing sessions requires your secret key. Connected accounts can create a session for themselves but cannot list sessions.', + }, + { type: 'heading', level: 2, text: 'Parameters' }, + { + type: 'attributes', + attributes: LIST_VERIFICATION_SESSION_PARAMETERS, + }, + { type: 'heading', level: 2, text: 'Returns' }, + { + type: 'paragraph', + text: 'A dictionary with a data property that contains an array of up to limit verification sessions, starting after session starting_after. Each entry in the array is a separate VerificationSession object. If no more sessions are available, the resulting array is empty.', + html: true, + }, + ], + right: [ + { + type: 'code', + endpoint: { + method: 'GET', + path: '/v1/identity/verification_sessions', + }, + tabs: [ + { + id: 'curl', + label: 'cURL', + code: `curl -G https://api.yourdomain.com/v1/identity/verification_sessions \\ + -H "x-api-key: sk_live_z_YOUR_API_KEY" \\ + -d limit=3 \\ + -d status=verified`, + }, + { + id: 'node', + label: 'Node.js', + code: `${NODE_INIT} + +const sessions = await zoneless.identity.verificationSessions.list({ + limit: 3, + status: 'verified', +});`, + }, + ], + }, + { + type: 'object', + title: 'RESPONSE', + code: LIST_VERIFICATION_SESSION_RESPONSE_JSON, + }, + ], + }, + ], +}; + +export const IDENTITY_VERIFICATION_SESSIONS_CANCEL_PAGE: DocPage = { + id: 'cancel', + title: 'Cancel a VerificationSession', + description: + 'Cancels a VerificationSession. The seller can no longer use the session URL to complete the check.', + stripeDocsUrl: + 'https://docs.stripe.com/api/identity/verification_sessions/cancel', + endpoints: [ + { method: 'POST', path: '/v1/identity/verification_sessions/:id/cancel' }, + ], + sections: [ + { + left: [ + { + type: 'callout', + variant: 'warning', + title: 'Not allowed after completion: ', + text: 'Sessions that are already canceled or verified cannot be canceled.', + }, + { type: 'heading', level: 2, text: 'Parameters' }, + { type: 'paragraph', text: 'No parameters.' }, + { type: 'heading', level: 2, text: 'Returns' }, + { + type: 'paragraph', + text: 'Returns the VerificationSession object with status set to canceled. The url and client_secret are cleared, and the person on the account goes back to unverified so a new session can be created.', + html: true, + }, + ], + right: [ + { + type: 'code', + endpoint: { + method: 'POST', + path: '/v1/identity/verification_sessions/:id/cancel', + }, + tabs: [ + { + id: 'curl', + label: 'cURL', + code: `curl -X POST https://api.yourdomain.com/v1/identity/verification_sessions/vs_z_7Kd2mQxT4Rb9LpVn/cancel \\ + -H "x-api-key: sk_live_z_YOUR_API_KEY"`, + }, + { + id: 'node', + label: 'Node.js', + code: `${NODE_INIT} + +const session = await zoneless.identity.verificationSessions.cancel( + 'vs_z_7Kd2mQxT4Rb9LpVn' +);`, + }, + ], + }, + { + type: 'object', + title: 'RESPONSE', + code: CANCEL_VERIFICATION_SESSION_RESPONSE_JSON, + }, + ], + }, + ], +}; + +export const IDENTITY_VERIFICATION_SESSIONS_REDACT_PAGE: DocPage = { + id: 'redact', + title: 'Redact a VerificationSession', + description: + 'Redacts a VerificationSession. The session is kept for reporting but its link, client secret, details and metadata are removed.', + stripeDocsUrl: + 'https://docs.stripe.com/api/identity/verification_sessions/redact', + endpoints: [ + { method: 'POST', path: '/v1/identity/verification_sessions/:id/redact' }, + ], + sections: [ + { + left: [ + { + type: 'callout', + variant: 'warning', + title: 'Redaction is irreversible: ', + text: 'The session cannot be used again once it is redacted. Redact sessions when you no longer need the check, for example after your retention period ends.', + }, + { + type: 'paragraph', + text: 'Zoneless marks the session redacted as soon as the request succeeds, rather than reporting a redaction in progress.', + html: true, + }, + { type: 'heading', level: 2, text: 'Parameters' }, + { type: 'paragraph', text: 'No parameters.' }, + { type: 'heading', level: 2, text: 'Returns' }, + { + type: 'paragraph', + text: 'Returns the redacted VerificationSession object with empty metadata, a null url, client_secret and provided_details, and redaction.status set to redacted.', + html: true, + }, + ], + right: [ + { + type: 'code', + endpoint: { + method: 'POST', + path: '/v1/identity/verification_sessions/:id/redact', + }, + tabs: [ + { + id: 'curl', + label: 'cURL', + code: `curl -X POST https://api.yourdomain.com/v1/identity/verification_sessions/vs_z_7Kd2mQxT4Rb9LpVn/redact \\ + -H "x-api-key: sk_live_z_YOUR_API_KEY"`, + }, + { + id: 'node', + label: 'Node.js', + code: `${NODE_INIT} + +const session = await zoneless.identity.verificationSessions.redact( + 'vs_z_7Kd2mQxT4Rb9LpVn' +);`, + }, + ], + }, + { + type: 'object', + title: 'RESPONSE', + code: REDACT_VERIFICATION_SESSION_RESPONSE_JSON, + }, + ], + }, + ], +}; + +export const IDENTITY_VERIFICATION_SESSIONS_PAGES: DocPage[] = [ + IDENTITY_VERIFICATION_SESSIONS_OVERVIEW_PAGE, + IDENTITY_VERIFICATION_SESSIONS_CREATE_PAGE, + IDENTITY_VERIFICATION_SESSIONS_UPDATE_PAGE, + IDENTITY_VERIFICATION_SESSIONS_RETRIEVE_PAGE, + IDENTITY_VERIFICATION_SESSIONS_LIST_PAGE, + IDENTITY_VERIFICATION_SESSIONS_CANCEL_PAGE, + IDENTITY_VERIFICATION_SESSIONS_REDACT_PAGE, +]; diff --git a/apps/docs/src/app/pages/docs/data/index.ts b/apps/docs/src/app/pages/docs/data/index.ts index fb573c0..afeefd1 100644 --- a/apps/docs/src/app/pages/docs/data/index.ts +++ b/apps/docs/src/app/pages/docs/data/index.ts @@ -40,6 +40,7 @@ export * from './event-types'; export * from './webhook-endpoints'; export * from './migrate-from-stripe'; export * from './identity-verification'; +export * from './identity-verification-sessions'; export * from './connect'; export * from './products'; export * from './prices'; diff --git a/apps/docs/src/app/pages/docs/docs-catalog.ts b/apps/docs/src/app/pages/docs/docs-catalog.ts index 882b67a..43766fb 100644 --- a/apps/docs/src/app/pages/docs/docs-catalog.ts +++ b/apps/docs/src/app/pages/docs/docs-catalog.ts @@ -25,6 +25,7 @@ import { PRIMARY_GUIDE_SECTIONS, IDEMPOTENT_REQUESTS_PAGE, IDENTITY_VERIFICATION_PAGE, + IDENTITY_VERIFICATION_SESSIONS_PAGES, INVOICE_ITEMS_PAGES, INVOICES_PAGES, LOCAL_DEVELOPMENT_PAGE, @@ -87,6 +88,7 @@ export const docPageGroups: Record = { billing: BILLING_PAGES, events: EVENTS_PAGES, 'webhook-endpoints': WEBHOOK_ENDPOINTS_PAGES, + 'identity-verification-sessions': IDENTITY_VERIFICATION_SESSIONS_PAGES, }; export const docSinglePages: DocPage[] = [ From 2a2339e9006065c6aedf658987ce2d9a77759040 Mon Sep 17 00:00:00 2001 From: TTyChud Date: Mon, 21 Sep 2026 15:42:20 +0530 Subject: [PATCH 2/3] docs: document identity verification session events --- .../src/app/pages/docs/data/event-types.ts | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/apps/docs/src/app/pages/docs/data/event-types.ts b/apps/docs/src/app/pages/docs/data/event-types.ts index fdca4a4..f8d7c42 100644 --- a/apps/docs/src/app/pages/docs/data/event-types.ts +++ b/apps/docs/src/app/pages/docs/data/event-types.ts @@ -270,6 +270,53 @@ export const EVENT_TYPE_DEFINITIONS: EventTypeDefinition[] = [ description: 'Occurs whenever an external wallet is deleted.', }, + // Identity verification session events + { + name: 'identity.verification_session.created', + resource: 'identity.verification_session', + objectType: 'VerificationSession', + objectHref: '#identity-verification-sessions-object', + description: 'Occurs whenever a verification session is created.', + }, + { + name: 'identity.verification_session.processing', + resource: 'identity.verification_session', + objectType: 'VerificationSession', + objectHref: '#identity-verification-sessions-object', + description: + 'Occurs whenever a verification session transitions to processing, once the seller submits their documents or moves through the flow.', + }, + { + name: 'identity.verification_session.requires_input', + resource: 'identity.verification_session', + objectType: 'VerificationSession', + objectHref: '#identity-verification-sessions-object', + description: + 'Occurs whenever a verification session transitions to requires_input, when the seller needs to provide more information or try again.', + }, + { + name: 'identity.verification_session.verified', + resource: 'identity.verification_session', + objectType: 'VerificationSession', + objectHref: '#identity-verification-sessions-object', + description: + 'Occurs whenever a verification session transitions to verified, once the check passes.', + }, + { + name: 'identity.verification_session.canceled', + resource: 'identity.verification_session', + objectType: 'VerificationSession', + objectHref: '#identity-verification-sessions-object', + description: 'Occurs whenever a verification session is canceled.', + }, + { + name: 'identity.verification_session.redacted', + resource: 'identity.verification_session', + objectType: 'VerificationSession', + objectHref: '#identity-verification-sessions-object', + description: 'Occurs whenever a verification session is redacted.', + }, + // Invoice events { name: 'invoice.created', From a0b3ed97b077948cfbd38b5de62d0a3dea3e6909 Mon Sep 17 00:00:00 2001 From: TTyChud Date: Tue, 22 Sep 2026 20:29:10 +0530 Subject: [PATCH 3/3] docs: render the cancel verification session callout as html --- .../src/app/pages/docs/data/identity-verification-sessions.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/apps/docs/src/app/pages/docs/data/identity-verification-sessions.ts b/apps/docs/src/app/pages/docs/data/identity-verification-sessions.ts index 69473db..f1932da 100644 --- a/apps/docs/src/app/pages/docs/data/identity-verification-sessions.ts +++ b/apps/docs/src/app/pages/docs/data/identity-verification-sessions.ts @@ -922,6 +922,7 @@ export const IDENTITY_VERIFICATION_SESSIONS_CANCEL_PAGE: DocPage = { variant: 'warning', title: 'Not allowed after completion: ', text: 'Sessions that are already canceled or verified cannot be canceled.', + html: true, }, { type: 'heading', level: 2, text: 'Parameters' }, { type: 'paragraph', text: 'No parameters.' },