Backend verification API

Use the backend verification API when your backend already collects KYC evidence and needs Payward to process it. Your backend submits HTTPS evidence URLs and metadata. Payward starts asynchronous verification processing and updates the user’s verification state. This API is similar to Submit Verification from URL. Use Submit Verification from URL when your integration already verified the evidence and Payward should trust the verifier result. Use Start Verification from URL when Payward should verify the submitted evidence. Do not call this API from a browser or mobile client. It uses your API credentials and points to sensitive document evidence.

Backend verification is asynchronous. Treat the start response as confirmation that Payward recorded the verification, not as a final verification decision.

How it works

Create or update the user

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

Store evidence

Store the document or liveness image files behind HTTPS presigned URLs on domains allowlisted for your integration.

Start a backend verification

Call POST /v1/users/{user_id}/verifications/start/url once for each verification type you need to submit.

Track status

Use Get verification to fetch one verification by ID, or list attempts with List verifications until each reaches a terminal status.

Reconcile the user

Fetch the user with Get User and use verification failure details according to your integration’s handling rules.

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 backend verification, create the user and provide the profile fields required for onboarding. 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. Start Verification from URL uses it as the user_id path parameter.

Step 2 - Store evidence

Store files behind HTTPS presigned URLs on domains allowlisted for your Payward integration. Evidence URL fields must use https:// URLs. Accepted evidence depends on the verification type:

Start `type`	Status `types` value	Required file fields	Description
`identity_document`	`proof_of_identity`	`front_url`, optional `back_url`	Government identity document verification
`residence_document`	`proof_of_address`	`document_url`	Residence or address document verification
`liveness`	`proof_of_liveness`	`left_url`, `center_url`, and `right_url`	Three-point liveness image verification

Status responses report document roles in types and the evidence collection channel in method. Backend URL submissions use method: "url" and include one value in types. The start request does not include verifier, verified_at, verifier_response, or verifier_response_url. Those fields belong to Submit Verification from URL because that endpoint trusts a verifier result supplied by your integration.

Step 3 - Start a backend verification

Submit one verification per Start Verification from URL request:

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

The request body uses a type discriminator.

Identity document

curl -X POST "https://api.services.payward.com/v1/users/$USER_ID/verifications/start/url" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity_document",
    "metadata": {
      "identity": {
        "full_name": {
          "first_name": "Alex",
          "last_name": "Morgan"
        },
        "birth": {
          "date": "1990-01-31"
        }
      },
      "document_type": "passport",
      "document_number": "A1234567",
      "issuing_country": "US"
    },
    "front_url": "https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256"
  }'

Residence document

{
  "type": "residence_document",
  "metadata": {
    "address": {
      "line1": "800 Market Street",
      "line2": "Suite 210",
      "city": "San Francisco",
      "postal_code": "94102",
      "province": "CA",
      "country": "US"
    },
    "document_type": "utility_bill"
  },
  "document_url": "https://your-allowlisted-bucket.s3.amazonaws.com/address.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256"
}

Liveness

{
  "type": "liveness",
  "left_url": "https://your-allowlisted-bucket.s3.amazonaws.com/liveness-left.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256",
  "center_url": "https://your-allowlisted-bucket.s3.amazonaws.com/liveness-center.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256",
  "right_url": "https://your-allowlisted-bucket.s3.amazonaws.com/liveness-right.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256"
}

A successful response returns the public verification ID:

{
  "data": {
    "verification_id": "PVABCDE-FGHIJ-KLMNOP"
  }
}

Store verification_id. You need it for reconciliation and support.

Step 4 - Track status

Use GET /v1/users/{user_id}/verifications/{verification_id} to fetch the latest state for one 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:

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"

verifications is returned in reverse chronological order. Example status response:

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

Statuses

Status	What it means	What to do
`started`	Payward recorded the verification and started processing	Wait for an update
`pending`	The verification is waiting on asynchronous review	Wait for an update
`completed`	The verification finished successfully	Fetch the user and confirm the final user status before enabling activity
`failed`	The verification reached a terminal failure state	Fetch the user and verification state to determine the next available step

Failure reasons

Failure reasons use this shape:

{
  "code": "expired",
  "details": ["Document expired before submission."]
}

Treat code as informational unless your Payward integration defines specific handling. Display details, but do not parse or branch on it.

API reference

Endpoint	Reference
`POST /v1/users/{user_id}/verifications/start/url`	Start verification from URL
`GET /v1/users/{user_id}/verifications/{verification_id}`	Get verification
`GET /v1/users/{user_id}/verifications`	List verifications

Get started

Market data

Accounts

Verifications

Trade

Earn

Payments

How it works

Base URL

Authentication

Step 1 - Create or update the user

Step 2 - Store evidence

Step 3 - Start a backend verification

Identity document

Residence document

Liveness

Step 4 - Track status

Statuses

Failure reasons

API reference

​How it works

​Base URL

​Authentication

​Step 1 - Create or update the user

​Step 2 - Store evidence

​Step 3 - Start a backend verification

​Identity document

​Residence document

​Liveness

​Step 4 - Track status

​Statuses

​Failure reasons

​API reference

How it works

Base URL

Authentication

Step 1 - Create or update the user

Step 2 - Store evidence

Step 3 - Start a backend verification

Identity document

Residence document

Liveness

Step 4 - Track status

Statuses

Failure reasons

API reference