Onboard for Crypto

To hold a crypto wallet or receive fiat through a virtual account, a player completes a one-time crypto onboarding — an extension of the create & verify step. Two things must be true before crypto features activate:

1. Identity is verified — the player completes KYC (hosted verification link).
2. Terms of service are accepted — the player accepts the applicable terms of service.

When both are satisfied, Pathly automatically provisions the player's crypto wallet and virtual account — you don't call anything to create them.

The onboarding chain

1. Retrieve the KYC verification link

Fetch the hosted identity-verification link(s) issued for the player and redirect them there. Pass accountId to read a player you onboarded.

curl -i -X GET \
  'https://sandbox-api.pathly.io/kyx/verification-links?accountId=5b3f0c2e-1d4a-4e8b-9c7a-2f6d8e0a1b22' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response:

{
  "status": "success",
  "data": [
    {
      "url": "https://verify.pathly.io/v/9f3d4a7e8b1c...",
      "status": "pending"
    }
  ],
  "code": 200,
  "message": "Successful request"
}

Redirect the player to url. status moves from pending → approved (or rejected) as verification completes. To learn the outcome, subscribe to the individual.activated / individual.rejected webhooks (or kyx.approved / kyx.rejected) — or poll the player's status on GET /individuals/{id}. For the full contract see the Retrieve verification links reference.

2. Retrieve & accept the terms of service

Read the player's terms-of-service state:

curl -i -X GET \
  https://sandbox-api.pathly.io/individuals/5b3f0c2e-1d4a-4e8b-9c7a-2f6d8e0a1b22/tos \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Response:

{
  "status": "success",
  "data": {
    "terms_of_service_url": "https://verify.pathly.io/terms?session=7a0d1e2c3f4...",
    "accepted": false,
    "required": true
  },
  "code": 200,
  "message": "Successful request"
}

Field	Meaning
terms_of_service_url	Hosted page to redirect the player to. null when no terms step applies.
accepted	Whether the player has already accepted.
required	Whether a terms step applies to this player at all.

In production, when required is true and accepted is false, redirect the player to terms_of_service_url. Acceptance is recorded and reflected back on the next GET …/tos. See the Retrieve terms-of-service state reference.

Sandbox shortcut

In sandbox there's no hosted page to click through. Mark the terms accepted directly so you can exercise the rest of the flow:

curl -i -X POST \
  https://sandbox-api.pathly.io/individuals/5b3f0c2e-1d4a-4e8b-9c7a-2f6d8e0a1b22/tos/accept \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

This endpoint is sandbox-only. See Accept terms of service (sandbox).

3. Provisioning happens automatically

Once KYC is approved and terms are accepted, Pathly provisions the player's crypto instruments and flips their status to active. No further calls are required:

• a crypto wallet (type: "crypto-wallet") — an on-chain USDC address; and
• a virtual account (type: "bank-account") — bank coordinates for fiat deposits.

Both then appear in GET /payment-methods?accountId=<player>. Confirm the player is ready with:

curl -i -X GET \
  https://sandbox-api.pathly.io/individuals/5b3f0c2e-1d4a-4e8b-9c7a-2f6d8e0a1b22 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

A status of active means the wallet and virtual account are ready to use.

Provisioning is asynchronous

The wallet and virtual account are created moments after verification and terms are complete (asynchronously). A payment_method.created webhook fires as each one is provisioned — subscribe to it rather than polling. The player's status also flips to active (a individual.activated webhook), after which both instruments appear in GET /payment-methods.