Customer Onboarding

Before users can make transactions, they must be registered and verified. You can either direct users to the Paytrie signup page or use the API to register them through your own interface.

API integration

For a seamless user experience, use the API to register users through your own interface.

Check whether the user already exists

A person may already hold a Paytrie account — created in our own app, or through another integration. Look them up by email before creating a new record:

curl -X GET "https://api.paytrie.com/v2/users?email=john.doe@example.com" \
  -H "x-api-key: your-api-key"

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "accessibleBy": ["jwt"]
    }
  ]
}

An empty array means the email is not registered — create the user as below. Otherwise take the id from the response and skip to generating the KYC link, or straight to Authentication if they are already verified.

accessibleBy reports what you need to send to act on that user. Your API key is required either way; jwt means you also need an access token the user grants you, which is the standard Authentication flow. Some integrations are separately approved to act with their API key on its own; those also see apiKey listed. See Knowing how you can act on a user.

Quick start

curl -X POST "https://api.paytrie.com/v2/users" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "dob": "1990-01-15",
    "phone": "4165551234",
    "addressLine1": "123 Main Street",
    "addressLine2": "Suite 100",
    "city": "Toronto",
    "province": "on",
    "postalCode": "M5V1A1",
    "occupation": "Software Engineer",
    "pep": false,
    "tpd": false
  }'

The response will include the id of the newly created user record. You can subsequently use that to generate the kyc link.

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@example.com",
    ...
  }
}

(OPTIONAL) Check what the user still needs to provide

Users created with POST /v2/users normally have everything they need, so you can go straight to generating the KYC link. If you would rather confirm first, or the KYC link comes back with a 422, you can read the user's outstanding requirements and submit whatever they name. The same endpoints let you update a user's details later.

Generate the KYC link

curl -X GET "https://api.paytrie.com/v2/users/550e8400-e29b-41d4-a716-446655440000/kyc-url" \
  -H "x-api-key: your-api-key"

Using the id from the previous response, you can call the generate KYC link endpoint to complete the onboarding flow.

{
  "success": true,
  "data": {
    "url": "https://sumsub.com/verify/...",
    "expiresAt": "2024-01-01T00:30:00.000Z"
  }
}

KYC verification flow

After registration, users must complete identity verification:

Paytrie uses Sumsub, a third-party identity verification provider, to handle KYC. The kyc-url opens Sumsub's hosted flow, where users upload identity documents and complete a liveness check.

Alternative: Sumsub reusable KYC

If your users have already completed KYC through Sumsub on your platform, you can import their verification data to skip the KYC step. See Sumsub Reusable KYC for details.