# 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 [#api-integration]

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

### Check whether the user already exists [#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:

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

```json
{
  "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](#generate-the-kyc-link), or straight to [Authentication](/v2/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](/v2/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](/v2/authentication#knowing-how-you-can-act-on-a-user).

<Card title="API Reference: Search users by email" href="/v2/api-reference/users/listUsers" icon="arrow-right-left">
  View complete request parameters and response schema
</Card>

### Quick start [#quick-start]

```bash
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.

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

<Card title="API Reference: Create a new user" href="/v2/api-reference/users/createUser" icon="arrow-right-left">
  View complete request parameters and response schema
</Card>

### (OPTIONAL) Check what the user still needs to provide [#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.

<Card title="KYC and profile data requirements" href="/v2/profile-data-requirements" icon="list-checks">
  Read a user's outstanding requirements and submit the fields they name
</Card>

### Generate the KYC link [#generate-the-kyc-link]

```bash
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.

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

<Card title="API Reference: Generate a KYC verification URL" href="/v2/api-reference/users/getUserKycUrl" icon="arrow-right-left">
  View complete request parameters and response schema
</Card>

## KYC verification flow [#kyc-verification-flow]

After registration, users must complete identity verification:

Paytrie uses [Sumsub](https://sumsub.com), 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.

<Card title="Sumsub user verification guide" href="https://docs.sumsub.com/docs/user-verification" icon="shield-check">
  See what your users will encounter during the Sumsub verification flow
</Card>

<Steps>
  <Step>
    ### Redirect to verification [#redirect-to-verification]

    Use the `url` from the `GET /v2/users/{userId}/kyc-url` response to redirect the user to our KYC partner.
  </Step>

  <Step>
    ### User completes verification [#user-completes-verification]

    The user submits identity documents and completes the verification process.
  </Step>

  <Step>
    ### Verification complete [#verification-complete]

    Once verified, the user's status changes and you receive a webhook notification (if configured).
  </Step>

  <Step>
    ### Ready to transact [#ready-to-transact]

    The user can now authenticate and make transactions.
  </Step>
</Steps>

<Callout type="info">
  Set up [Webhooks](/v2/webhooks) to receive notifications when users complete
  verification.
</Callout>

## Alternative: Sumsub reusable KYC [#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](/v2/integrations/sumsub-kyc) for details.