Hosted KYC

Hosted KYC lets you verify a user through a Payward-managed hosted UI. You create or update the user first, start a hosted verification, send the user to the hosted UI, then reconcile the final status through verification, user, and webhook endpoints. Use the Backend verification API instead when your backend already collects document or liveness evidence.

Hosted KYC is asynchronous. Treat the start response as launch material for the hosted UI, not as a final verification decision.

How it works

A typical Hosted KYC integration follows five steps:

Create or update the user

Create the Payward user and provide the profile fields required for onboarding.

Start Hosted KYC

Call POST /v1/users/{user_id}/verifications/start/hosted with the user ID in the user_id path parameter.

Send the user to the hosted UI

Launch the hosted UI with the returned launch fields, or create a one-time link and redirect the user to it.

Handle interruptions

Resume the same hosted verification when the user returns to an existing flow.

Reconcile status

Use webhooks, the verification endpoints, and Get User to decide what the user can do next.

Base URL

https://api.services.payward.com

Authentication

All requests require three headers:

Header	Description
`API-Key`	Your public API key
`API-Nonce`	Monotonically increasing integer nonce
`API-Sign`	HMAC signature computed with your private key

See Authentication for how to generate the signature.

Step 1 - Create or update the user

Before starting Hosted KYC, create the user and provide the profile fields required for onboarding. Hosted KYC uses the user’s existing Payward profile. Do not send collected evidence or verification results in the hosted-start request. Use these endpoints before starting verification:

Endpoint	Use it to
`POST /v1/users`	Create a user
`PATCH /v1/users/{user_id}`	Update an existing user
`GET /v1/users/{user_id}`	Read the latest user state

Store the user ID. The hosted verification endpoints use it as the user_id path parameter.

Step 2 - Start Hosted KYC

Call Start verification from hosted flow when the user is ready to verify:

POST /v1/users/{user_id}/verifications/start/hosted

The request body is empty:

curl -X POST "https://api.services.payward.com/v1/users/$USER_ID/verifications/start/hosted" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN" \
  -H "Content-Type: application/json" \
  -d '{}'

The response includes the public verification ID and hosted UI launch fields:

{
  "data": {
    "verification_id": "PVABCDE-FGHIJ-KLMNOP",
    "inquiry_id": "hosted_verification_test",
    "session_token": "hosted_session_test",
    "environment_id": "hosted_ui_test"
  }
}

Store verification_id. You need it to create one-time links, resume the hosted flow, reconcile status, and troubleshoot the user’s verification.

Field	Description
`verification_id`	Public ID for this hosted verification
`inquiry_id`	Opaque hosted verification identifier
`session_token`	Short-lived launch token for the hosted UI
`environment_id`	Hosted UI environment identifier returned with the launch token

Step 3 - Send the user to the hosted UI

Use the launch method agreed during onboarding. For an embedded launch, use session_token and environment_id from the hosted-start or resume response. Treat session_token as short-lived and do not store it as a long-term credential. For a redirect or shareable link, create a one-time link for the existing verification:

POST /v1/users/{user_id}/verifications/{verification_id}/otl

curl -X POST "https://api.services.payward.com/v1/users/$USER_ID/verifications/$VERIFICATION_ID/otl" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN"

The response includes a full URL and a shortened URL:

{
  "data": {
    "url": "https://verify.example.com/verify?code=us1-handle",
    "url_short": "https://verify.example.com/v/HANDLE"
  }
}

Send the user to url or url_short. One-time links are temporary. Create a fresh link if the user needs to return later.

Step 4 - Resume an interrupted flow

If the user returns to an existing hosted verification, resume that verification instead of starting a duplicate one:

POST /v1/users/{user_id}/verifications/{verification_id}/resume

curl -X POST "https://api.services.payward.com/v1/users/$USER_ID/verifications/$VERIFICATION_ID/resume" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN"

The response returns fresh hosted UI launch fields:

{
  "data": {
    "inquiry_id": "hosted_verification_test",
    "session_token": "hosted_session_test",
    "environment_id": "hosted_ui_test"
  }
}

Use the returned launch fields for embedded flows. If you need a URL, call Create one-time link for hosted verification after resuming.

Step 5 - Reconcile status

Hosted KYC does not finish in the start response. Reconcile status from webhooks and the latest API state. Use GET /v1/users/{user_id}/verifications/{verification_id} to fetch the latest state for one hosted verification:

curl -X GET "https://api.services.payward.com/v1/users/$USER_ID/verifications/$VERIFICATION_ID" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN"

If you do not have the verification ID, use GET /v1/users/{user_id}/verifications to list hosted verification attempts:

curl -X GET "https://api.services.payward.com/v1/users/$USER_ID/verifications" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN"

Example response:

{
  "data": {
    "verifications": [
      {
        "verification_id": "PVABCDE-FGHIJ-KLMNOP",
        "types": ["proof_of_identity", "proof_of_address", "proof_of_liveness"],
        "method": "hosted",
        "status": "pending",
        "created_at": "2026-05-20T14:30:00Z",
        "updated_at": "2026-05-20T14:45:00Z"
      }
    ]
  }
}

Hosted verification status responses use method: "hosted" and include each covered document role in types. Use the verification status together with Get User:

Status	What it means	What to do
`started`	The hosted verification was created	Send the user to the hosted UI
`pending`	The verification is still in progress	Wait for an update, or resume the flow if the user returns
`completed`	The hosted verification finished successfully	Fetch the user and confirm the final user status before enabling activity
`failed`	The hosted verification did not complete	Fetch the user and verification state to determine the next available step

The reasons field only appears when a verification status is failed.

Webhook events

Register webhooks for user lifecycle events so your system does not need to poll continuously after a final user-state change. Webhook events are signals to fetch the latest state, not the complete state by themselves.

Event	Meaning	Recommended action
`user.verified`	The user has been verified and can trade on the platform	Fetch the user, update your local status, and enable eligible activity
`user.closed`	The user’s account has been permanently closed	Stop account activity and update your local status
`user.disabled`	The user’s account has been disabled	Stop account activity and wait for the latest user state

Webhook delivery can be repeated. Deduplicate events by event_id, return a 2xx response only after accepting the event, and fetch the latest user and verification state before changing what the user can do.

Retry guidance

Use Start verification from hosted flow to create a hosted verification. Do not call it repeatedly to refresh a session or link. Use these follow-up endpoints for the same verification_id:

Need	Endpoint
Create a fresh one-time link	`POST /v1/users/{user_id}/verifications/{verification_id}/otl`
Refresh launch fields	`POST /v1/users/{user_id}/verifications/{verification_id}/resume`
Check verification state	`GET /v1/users/{user_id}/verifications/{verification_id}`
List verification attempts	`GET /v1/users/{user_id}/verifications`
Check user state	`GET /v1/users/{user_id}`

Only start a new hosted verification after a previous attempt reaches a terminal state and your Payward integration allows another attempt.

API reference

Endpoint	Reference
`POST /v1/users`	Create User
`PATCH /v1/users/{user_id}`	Update User
`GET /v1/users/{user_id}`	Get User
`POST /v1/users/{user_id}/verifications/start/hosted`	Start verification from hosted flow
`POST /v1/users/{user_id}/verifications/{verification_id}/otl`	Create one-time link for hosted verification
`POST /v1/users/{user_id}/verifications/{verification_id}/resume`	Resume hosted verification
`GET /v1/users/{user_id}/verifications/{verification_id}`	Get verification
`GET /v1/users/{user_id}/verifications`	List verifications
`POST /v1/webhooks`	Register Webhook

Get started

Market data

Accounts

Verifications

Trade

Earn

Payments

How it works

Base URL

Authentication

Step 1 - Create or update the user

Step 2 - Start Hosted KYC

Step 3 - Send the user to the hosted UI

Step 4 - Resume an interrupted flow

Step 5 - Reconcile status

Webhook events

Retry guidance

API reference

​How it works

​Base URL

​Authentication

​Step 1 - Create or update the user

​Step 2 - Start Hosted KYC

​Step 3 - Send the user to the hosted UI

​Step 4 - Resume an interrupted flow

​Step 5 - Reconcile status

​Webhook events

​Retry guidance

​API reference

How it works

Base URL

Authentication

Step 1 - Create or update the user

Step 2 - Start Hosted KYC

Step 3 - Send the user to the hosted UI

Step 4 - Resume an interrupted flow

Step 5 - Reconcile status

Webhook events

Retry guidance

API reference