Onboarding customers

Every Spritz user belongs to your integration. Onboarding has three beats: create the user, verify their identity, and read their capabilities to see what they can do. If the person already has a Spritz account, with you or with another integrator, you don’t create a new user. You connect to them instead, with their consent.

1. Create a user

Create a user with their email address. Spritz returns a user API key (prefixed ak_) that you use to authenticate requests on that user’s behalf.

curl -X POST https://platform.spritz.finance/v1/integrator/users \
  -H "Content-Type: application/json" \
  # plus your integrator signing headers (see Authentication)
  -d '{ "email": "user@example.com" }'

{
  "userId": "63d12d3b577fab6c6382136e",
  "email": "user@example.com",
  "apiKey": "ak_..."
}

Store the apiKey securely. You send it as the Authorization bearer for every request you make on this user’s behalf (see Authentication). You can also pass an optional timezone.

2. Verify identity

Before a user can move money, they complete identity verification (KYC). Start a verification session for the user:

curl -X POST https://platform.spritz.finance/v1/users/me/verification-sessions/ \
  -H "Content-Type: application/json" \
  # plus your integrator signing headers and the user's Authorization (see Authentication)
  -d '{}'

{
  "sessionId": "inq_2Q3x7k9m1n",
  "provider": "persona",
  "sessionToken": "...",
  "verificationUrl": "https://verify.spritz.finance/...",
  "verificationUrlExpiresAt": "2026-06-30T12:34:56.000Z"
}

Spritz uses Persona for identity verification. The session response gives you what Persona’s SDKs need: sessionId is the Persona inquiry ID and sessionToken is the session token. Recommended: embed Persona natively. For the best experience, run verification inside your own app with the Persona SDK that matches your platform, passing the inquiry ID and session token. Persona provides:

Web: the embedded flow
React Native: Persona’s React Native SDK
iOS and Android: Persona’s native mobile SDKs

See Persona’s docs for each SDK. Passing the session token resumes the same inquiry, so the result stays in sync with the user’s verification.status. Fallback: hosted flow. If you’d rather not embed, open verificationUrl in a browser tab, iframe, or mobile web view. It’s single-use and short-lived; if it expires before the user finishes, create another session. The user’s verification state is reported on their profile as verification.status: not_started, verified, failed, retry, or disabled. A retry status means they can try again; create a new session to do so.

3. Read capabilities

GET /v1/users/me returns the user’s verification status and their capabilities. Capabilities are the source of truth for what a user can do right now, and what’s blocking anything they can’t.

{
  "id": "63d12d3b577fab6c6382136e",
  "email": "user@example.com",
  "verification": { "status": "verified", "country": "US" },
  "capabilities": [
    {
      "product": "crypto_to_fiat",
      "method": "ach_credit",
      "name": "ACH Bank Transfer",
      "description": "Pay out to a US bank account via ACH",
      "status": "active",
      "requirements": []
    },
    {
      "product": "fiat_to_crypto",
      "method": "ach_debit",
      "name": "ACH Debit",
      "status": "requirements_needed",
      "nextRequirement": "terms_acceptance",
      "requirements": [
        {
          "type": "terms_acceptance",
          "description": "Accept the deposit terms to enable ACH debit",
          "actionUrl": "https://...",
          "retryable": false,
          "status": "not_started"
        }
      ]
    }
  ]
}

Each capability is a product, and for ramps a method:

Products: fiat_to_crypto, crypto_to_fiat, bill_pay, crypto_card
Methods: ach_credit, ach_debit, wire, sepa_credit_transfer, rtp, push_to_card, canadian_eft

Its status tells you where it stands:

Status	Meaning
`active`	Ready to use now
`requirements_needed`	The user has something to complete first
`pending`	In progress, for example verification under review
`not_available`	Not offered for this user (for example, their region)

When a capability is requirements_needed, its requirements[] lists what to do, and nextRequirement points to the one to tackle first. Each requirement has a type, a human-readable description, an actionUrl where the user completes it, a retryable flag, and its own status (not_started, pending, completed, failed).

Requirement type	What it means
`identity_verification`	Complete KYC (see step 2)
`terms_acceptance`	Accept the relevant terms
`additional_verification`	An extra verification step is needed
`document_submission`	Submit supporting documents
`region_restriction`	Not available in the user’s region. This one is terminal; no user action clears it

Drive your UI from capabilities

Render your onboarding and product UI off the capabilities list rather than tracking state yourself:

Show a capability as available when its status is active.
When it’s requirements_needed, surface the requirement description and send the user to its actionUrl.
After the user completes a requirement, re-fetch GET /v1/users/me, or react to the capabilities.updated webhook so you update without polling.

Connect an existing Spritz user

If the person already has a Spritz account, with you or with another integrator, use Integrator Connect to gain access with their consent instead of creating a new user. It’s an OAuth-style authorization flow.

Create a connect session

From your backend, create a session with a pre-registered HTTPS redirect URI and an optional state value you can use to tie the result back to a request.

curl -X POST https://platform.spritz.finance/v1/integrator/connect/sessions \
  -H "Content-Type: application/json" \
  # plus your integrator signing headers (see Authentication)
  -d '{
    "redirectUri": "https://app.example.com/spritz/callback",
    "state": "opaque-value"
  }'

{
  "sessionId": "...",
  "authorizationUrl": "https://app.spritz.finance/connect?session_id=...",
  "expiresAt": "2026-06-30T12:40:00.000Z"
}

Send the user to approve

Redirect the user to authorizationUrl. They sign in to Spritz, review your integration, and approve. The session is valid for about 10 minutes.

Receive the authorization code

On approval, Spritz redirects the user back to your redirectUri with a code and the state you sent.

Exchange the code for a user key

From your backend, exchange the code for that user’s API key. The code is single-use and expires after a few minutes.

curl -X POST https://platform.spritz.finance/v1/integrator/connect/token \
  -H "Content-Type: application/json" \
  # plus your integrator signing headers
  -d '{ "code": "..." }'

{
  "apiKey": "ak_...",
  "userId": "63d12d3b577fab6c6382136e",
  "email": "user@example.com",
  "grantId": "..."
}

You now hold a user API key for that user and can act on their behalf, exactly like a user you created.

Authentication

Use the user API key to sign requests.

What we support

Rails, tokens, and regions behind each capability.

Off-ramp

Put an active capability to work.

Webhooks

React to capabilities.updated and verification changes.

Get Started

Europe (EEA)

Core Concepts

Use Cases

Onboarding customers

1. Create a user

2. Verify identity

3. Read capabilities

Drive your UI from capabilities

Connect an existing Spritz user

Next

Authentication

What we support

Off-ramp

Webhooks

​1. Create a user

​2. Verify identity

​3. Read capabilities

​Drive your UI from capabilities

​Connect an existing Spritz user

​Next

Authentication

What we support

Off-ramp

Webhooks

1. Create a user

2. Verify identity

3. Read capabilities

Drive your UI from capabilities

Connect an existing Spritz user

Next