KYC and Profile Data Requirements

A user must complete their profile before they can start identity verification or transact. Rather than tracking that yourself, ask Paytrie: GET /v2/users/{userId}/requirements returns every requirement with its status, and names the exact fields anything outstanding is waiting on. You submit those fields with PATCH /v2/users/{userId} and read the requirements again.

Use this page as a planning reference for what the requirements mean. The live response is what counts — which requirements apply varies by user, and the set changes as compliance rules change. Render whatever the API returns rather than hardcoding a list of steps.

Before you start

These endpoints act on a specific user, so they need both credentials:

• Your API key, sent as x-api-key.
• An access token for that user, sent as Authorization: Bearer.

Create the user first with POST /v2/users, then obtain an access token for them through Authentication — send a login code to their email, and exchange the code they give you for a token. Tokens are valid for one hour.

Read a user's requirements

curl -X GET "https://api.paytrie.com/v2/users/550e8400-e29b-41d4-a716-446655440000/requirements" \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer <access-token>"

{
  "success": true,
  "data": {
    "requirements": {
      "emailVerification": { "status": "satisfied", "requiredFields": [] },
      "personalInfo": { "status": "satisfied", "requiredFields": [] },
      "address": { "status": "satisfied", "requiredFields": [] },
      "occupation": { "status": "satisfied", "requiredFields": [] },
      "additionalInfo": {
        "status": "pending",
        "requiredFields": [
          "olderUserInfo.sourceOfFunds",
          "olderUserInfo.intendedUseOfUSDC",
          "olderUserInfo.walletProvider",
          "olderUserInfo.walletAddress",
          "olderUserInfo.howDidYouHear",
          "olderUserInfo.whoReferredYou",
          "olderUserInfo.previousCryptoExperience"
        ]
      },
      "kyc": { "status": "pending", "requiredFields": [] }
    }
  }
}

Status

Reason

Some requirements carry a reason when the status alone does not say enough.

Required fields

requiredFields lists what is still outstanding as dot-paths into the PATCH /v2/users/{userId} body, so you can submit them back exactly as they are returned. It is empty when a requirement is already satisfied, or when it is not field-driven — kyc is completed through the verification flow rather than by submitting fields.

What each requirement means

additionalInfo is the one integrations meet unexpectedly. It applies only to users who were 50 or over when they signed up, and it blocks the KYC link until it is filled in — GET /v2/users/{userId}/kyc-url returns 422 while it is outstanding.

Submit the outstanding fields

Send whatever the requirements response named. Every field is optional, so you can submit them all at once or a few at a time.

curl -X PATCH "https://api.paytrie.com/v2/users/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "olderUserInfo": {
      "sourceOfFunds": "Salary",
      "intendedUseOfUSDC": "Savings",
      "walletProvider": "MetaMask"
    }
  }'

Reading the requirements again narrows requiredFields to what is still missing:

"additionalInfo": {
  "status": "pending",
  "requiredFields": [
    "olderUserInfo.walletAddress",
    "olderUserInfo.howDidYouHear",
    "olderUserInfo.whoReferredYou",
    "olderUserInfo.previousCryptoExperience"
  ]
}

Repeat until nothing is pending except kyc, then generate the verification link.

Verify a user's phone

Users created with POST /v2/users start with a verified phone. A user who signed up with Paytrie some other way may not, and phoneVerification stays pending until they confirm a number. Both calls act on the user behind the access token, so they need Authorization: Bearer as well as your API key.

curl -X POST "https://api.paytrie.com/v2/users/me/phone/send-verification" \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"phone":"4161234567"}'

curl -X POST "https://api.paytrie.com/v2/users/me/phone/verify" \
  -H "x-api-key: your-api-key" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"code":"1234"}'

Updating a user's information

PATCH is also how you update a user's details after they are created — for example when verification fails because an address no longer matches their identity document. Submit the corrected fields and generate a new verification link.