curl

curl -X POST "https://api.services.payward.com/v1/users/AA45N8G4MLDYWAR7/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"
  }'

import requests

url = "https://api.services.payward.com/v1/users/{user_id}/verifications/start/url"

payload = {
    "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"
}
headers = {
    "API-Key": "<api-key>",
    "API-Nonce": "<api-key>",
    "API-Sign": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'API-Key': '<api-key>',
    'API-Nonce': '<api-key>',
    'API-Sign': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.services.payward.com/v1/users/{user_id}/verifications/start/url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.services.payward.com/v1/users/{user_id}/verifications/start/url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "API-Key: <api-key>",
    "API-Nonce: <api-key>",
    "API-Sign: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.services.payward.com/v1/users/{user_id}/verifications/start/url"

	payload := strings.NewReader("{\n  \"type\": \"identity_document\",\n  \"metadata\": {\n    \"identity\": {\n      \"full_name\": {\n        \"first_name\": \"Alex\",\n        \"last_name\": \"Morgan\"\n      },\n      \"birth\": {\n        \"date\": \"1990-01-31\"\n      }\n    },\n    \"document_type\": \"passport\",\n    \"document_number\": \"A1234567\",\n    \"issuing_country\": \"US\"\n  },\n  \"front_url\": \"https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("API-Key", "<api-key>")
	req.Header.Add("API-Nonce", "<api-key>")
	req.Header.Add("API-Sign", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.services.payward.com/v1/users/{user_id}/verifications/start/url")
  .header("API-Key", "<api-key>")
  .header("API-Nonce", "<api-key>")
  .header("API-Sign", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"identity_document\",\n  \"metadata\": {\n    \"identity\": {\n      \"full_name\": {\n        \"first_name\": \"Alex\",\n        \"last_name\": \"Morgan\"\n      },\n      \"birth\": {\n        \"date\": \"1990-01-31\"\n      }\n    },\n    \"document_type\": \"passport\",\n    \"document_number\": \"A1234567\",\n    \"issuing_country\": \"US\"\n  },\n  \"front_url\": \"https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.services.payward.com/v1/users/{user_id}/verifications/start/url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["API-Key"] = '<api-key>'
request["API-Nonce"] = '<api-key>'
request["API-Sign"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"identity_document\",\n  \"metadata\": {\n    \"identity\": {\n      \"full_name\": {\n        \"first_name\": \"Alex\",\n        \"last_name\": \"Morgan\"\n      },\n      \"birth\": {\n        \"date\": \"1990-01-31\"\n      }\n    },\n    \"document_type\": \"passport\",\n    \"document_number\": \"A1234567\",\n    \"issuing_country\": \"US\"\n  },\n  \"front_url\": \"https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "type": "<string>",
    "status": 400,
    "instance": "<string>",
    "code": "bad_request",
    "doc_url": "<string>",
    "causes": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 401,
    "instance": "<string>",
    "code": "unauthenticated",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 403,
    "instance": "<string>",
    "code": "forbidden",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 429,
    "instance": "<string>",
    "code": "resource_exhausted",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 500,
    "instance": "<string>",
    "code": "internal",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 501,
    "instance": "<string>",
    "code": "unimplemented",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 503,
    "instance": "<string>",
    "code": "unavailable",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 504,
    "instance": "<string>",
    "code": "deadline_exceeded",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

Verifications

Start Verification from URL

Start a Payward-performed verification for a user with evidence provided via presigned URLs.

This endpoint accepts the same verification families as Submit Verification from URL: identity document, residence document, and liveness. Liveness checks use three-point images. Use this endpoint when Payward should verify the submitted evidence. Use Submit Verification from URL when your integration already verified the evidence and Payward should trust the verifier result you provide.

URL and file requirements

Evidence URLs must be HTTPS URLs on allowlisted domains, up to 4096 characters. Each redirect target must also use HTTPS and an allowlisted domain. The server follows up to three redirects.

The server extracts the decoded filename from the submitted URL path. The filename must be 255 bytes or less, cannot be . or .., and cannot contain path separators or control characters. It must include an extension matching the detected file content.

Downloaded files can be up to 150 MiB (157286400 bytes). The size limit is enforced from the Content-Length header and while streaming the response body. Accepted file types are JPEG/JPG, PNG, PDF, MP4/M4V, WebM, and MOV/QuickTime. Passport identity document submissions must omit back_url.

Verification result fields

Do not send verifier, verified_at, verifier_response, or verifier_response_url to this endpoint. Those fields belong to Submit Verification from URL because that endpoint trusts a verification result supplied by your integration.

Domain allowlisting

For security, the domains you use for presigned URLs must be allowlisted before you can use this endpoint. Contact your account manager to configure the allowed domains for your integration.

POST

users

{user_id}

verifications

start

url

curl

curl -X POST "https://api.services.payward.com/v1/users/AA45N8G4MLDYWAR7/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"
  }'

import requests

url = "https://api.services.payward.com/v1/users/{user_id}/verifications/start/url"

payload = {
    "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"
}
headers = {
    "API-Key": "<api-key>",
    "API-Nonce": "<api-key>",
    "API-Sign": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'API-Key': '<api-key>',
    'API-Nonce': '<api-key>',
    'API-Sign': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.services.payward.com/v1/users/{user_id}/verifications/start/url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.services.payward.com/v1/users/{user_id}/verifications/start/url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "API-Key: <api-key>",
    "API-Nonce: <api-key>",
    "API-Sign: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.services.payward.com/v1/users/{user_id}/verifications/start/url"

	payload := strings.NewReader("{\n  \"type\": \"identity_document\",\n  \"metadata\": {\n    \"identity\": {\n      \"full_name\": {\n        \"first_name\": \"Alex\",\n        \"last_name\": \"Morgan\"\n      },\n      \"birth\": {\n        \"date\": \"1990-01-31\"\n      }\n    },\n    \"document_type\": \"passport\",\n    \"document_number\": \"A1234567\",\n    \"issuing_country\": \"US\"\n  },\n  \"front_url\": \"https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("API-Key", "<api-key>")
	req.Header.Add("API-Nonce", "<api-key>")
	req.Header.Add("API-Sign", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.services.payward.com/v1/users/{user_id}/verifications/start/url")
  .header("API-Key", "<api-key>")
  .header("API-Nonce", "<api-key>")
  .header("API-Sign", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"identity_document\",\n  \"metadata\": {\n    \"identity\": {\n      \"full_name\": {\n        \"first_name\": \"Alex\",\n        \"last_name\": \"Morgan\"\n      },\n      \"birth\": {\n        \"date\": \"1990-01-31\"\n      }\n    },\n    \"document_type\": \"passport\",\n    \"document_number\": \"A1234567\",\n    \"issuing_country\": \"US\"\n  },\n  \"front_url\": \"https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.services.payward.com/v1/users/{user_id}/verifications/start/url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["API-Key"] = '<api-key>'
request["API-Nonce"] = '<api-key>'
request["API-Sign"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"identity_document\",\n  \"metadata\": {\n    \"identity\": {\n      \"full_name\": {\n        \"first_name\": \"Alex\",\n        \"last_name\": \"Morgan\"\n      },\n      \"birth\": {\n        \"date\": \"1990-01-31\"\n      }\n    },\n    \"document_type\": \"passport\",\n    \"document_number\": \"A1234567\",\n    \"issuing_country\": \"US\"\n  },\n  \"front_url\": \"https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "type": "<string>",
    "status": 400,
    "instance": "<string>",
    "code": "bad_request",
    "doc_url": "<string>",
    "causes": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 401,
    "instance": "<string>",
    "code": "unauthenticated",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 403,
    "instance": "<string>",
    "code": "forbidden",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 429,
    "instance": "<string>",
    "code": "resource_exhausted",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 500,
    "instance": "<string>",
    "code": "internal",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 501,
    "instance": "<string>",
    "code": "unimplemented",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 503,
    "instance": "<string>",
    "code": "unavailable",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

{
  "error": {
    "type": "<string>",
    "status": 504,
    "instance": "<string>",
    "code": "deadline_exceeded",
    "doc_url": "<string>",
    "causes": [
      {}
    ]
  }
}

Authorizations

API-Key

string

header

required

Your public API key. Identifies the partner making the request.

API-Nonce

string

header

required

Monotonically increasing nonce included in the request signature.

API-Sign

string

header

required

HMAC signature over the request, computed with your private key.

Path Parameters

user_id

string

required

ID of the user the request applies to. For partners operating in the B2B2C model, this is the Sub-User the request is acting on behalf of. Canonical identifier for a user in the Payward public API.

Required string length: 14 - 42

Body

application/json

Option 1
Option 2
Option 3

Verification request body. The type discriminator selects exactly one start verification payload.

type

enum<string>

required

Available options:

identity_document

metadata

object

required

Metadata about the identity document to verify.

Show child attributes

front_url

string<uri>

required

Presigned URL to the front side of the identity document. The filename is extracted from the URL path and must meet the URL and file requirements.

Required string length: 1 - 4096

Pattern: ^https://

Example:

"https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256"

back_url

string<uri> | null

Presigned URL to the back side of the identity document. The filename is extracted from the URL path and must meet the URL and file requirements. Passport submissions must omit this field.

Required string length: 1 - 4096

Pattern: ^https://

Example:

"https://your-allowlisted-bucket.s3.amazonaws.com/front.png?X-Amz-Algorithm=AWS4-HMAC-SHA256"

Response

Verification started.

data

object

required

Show child attributes

Submit Verification from URL Start verification from hosted flow

⌘I