Skip to main content
Hosted KYC collects verification evidence through Payward-managed web or embedded methods. You create the user and request the methods currently available to the user.
Hosted KYC is asynchronous. A hosted method starts or continues collection. It is not a verification decision.

​
How it works

1

Create the user

Call POST /v1/users with the user’s email and your external reference.
2

Check verification requirements

Call GET /v1/users/{user_id}/verifications/requirements. If user_action_required is true and required_actions contains an action_type: "verification" item, create a hosted verification.
3

Create or retry a hosted verification

Call POST /v1/users/{user_id}/verifications/hosted. After a retryable failure, send the same request again. PWS determines whether to continue or replace the existing attempt.
4

Start collection

Use the returned methods.web or methods.embedded value before it expires. If the response contains not_required, do not start another verification.
5

Reconcile status

Use webhooks, Get Verification, and Get Verification Requirements.

​
Create the user

Create the account-owned user resource first: All requests use PWS API authentication.
Store the returned user id.

​
Check verification requirements

Fetch the user’s current verification state and required actions:
Use the response as the current source of truth for the user’s verification requirements and access state:
  • required_actions lists the current outstanding requirements.
  • user_action_required indicates whether the user or your application can act on a requirement now.
  • state indicates whether the user can use PWS services. An ok user is active. A disabled or closed user cannot use the services.
Call Create hosted verification only when user_action_required is true and required_actions contains an action_type: "verification" item. If the response contains only an action_type: "wait" item, Payward is performing additional review. The user does not need to complete another verification. Calling Create Hosted Verification while the user is waiting returns not_required.
Verification requirements can be added after a user has already been verified. Do not cache this response as a permanent eligibility decision. Fetch it again when you need the user’s current state, and when you receive a verification.requirements_updated webhook.

​
Create a hosted verification

Call Create hosted verification when Get verification requirements reports a user-actionable verification:
The response contains one or more available methods. web and embedded are independently optional, but methods always contains at least one of them:
Redirect the user to methods.web.url, or initialize Sumsub with the data in methods.embedded.sumsub. If no verification is required, the response contains not_required instead:
Use this operation for initial onboarding, a failed attempt, or a later verification requirement. If you retry, send the same request. You do not need to select a retry mode or track the previous attempt. PWS selects the required verification flow from the user’s current KYC state. Each call returns the currently available methods or not_required. On a retry, not_required can mean that PWS successfully reconciled the previous submission and the user no longer has an actionable verification requirement. Do not send the user back to the hosted flow. Fetch Get verification requirements to refresh the state shown in your application.

​
Handle errors

If the operation returns 500, 503, or 504, PWS could not complete or reconcile the request. Display a temporary message such as “Verification is temporarily unavailable. Try again shortly.” Retry the same request after a backoff. A 403 response means your account is not allowed or configured to create hosted verifications. Stop automatic retries and contact Payward support. Do not treat an error response as a completed verification.

​
Reconcile status

When the hosted response contains methods, use its verification_id to fetch that verification. A not_required response does not contain a verification ID because there is no hosted verification to reconcile:
Each item returned by Get Verification or List Verifications includes a types array describing the document roles it covers. Its values are proof_of_identity, proof_of_address, proof_of_liveness, validated_tax_id, and other. Register webhooks to avoid continuous polling. Subscribe to verification.requirements_updated, then call Get verification requirements when it arrives. Subscribe to verification.updated, then call Get Verification with the payload’s user_id and verification_id. The webhook payloads contain only the IDs required for those follow-up calls. Treat them as notifications because delivery can be delayed, duplicated, or reordered. The GET response is the current state.

​
API reference