# Onboarding SDK: Coinme App Platform > Every page and skill for the Onboarding SDK, in one file: the SDK documents and guides, and the Agent Skills that integrate it. The Onboarding SDK belongs to the Coinme-as-a-Service (CaaS) integration; https://platformdocs.coinme.com/agents/surfaces.md explains the two surfaces. The index of the whole site is https://platformdocs.coinme.com/llms.txt. --- --- title: "Coinme Onboarding SDK" url: "https://platformdocs.coinme.com/#/docs/coinme-onboarding-sdk" markdown: "https://platformdocs.coinme.com/docs/coinme-onboarding-sdk.md" summary: "The Coinme Onboarding SDK onboards a new customer to Coinme-as-a-Service (CAAS) from your own application and takes them through non-documentary KYC. Identity is verified from the details the customer types, with no document upload: your app collects email, name, address, phone and date of birth in ordinary inputs, the Social Security Number goes into a secure field hosted by the Coinme Vault, and the SDK submits everything to Coinme and hands you back the new `customerId`. It then verifies the customer's phone with a code texted to the number they onboarded with; until that code checks out, the customer has not completed KYC." surface: "caas" updated: "2026-10-25" --- # Coinme Onboarding SDK The Coinme Onboarding SDK onboards a new customer to Coinme-as-a-Service (CAAS) from your own application and takes them through non-documentary KYC. Identity is verified from the details the customer types, with no document upload: your app collects email, name, address, phone and date of birth in ordinary inputs, the Social Security Number goes into a secure field hosted by the Coinme Vault, and the SDK submits everything to Coinme and hands you back the new `customerId`. It then verifies the customer's phone with a code texted to the number they onboarded with; until that code checks out, the customer has not completed KYC. ## What it does The SDK covers the onboarding call and everything around it that would otherwise put your app in scope for handling an SSN. The customer types the SSN into the vault's secure field, and it travels from that field to the vault without passing through your code or your servers. On the web the field is an iframe, so the SSN never enters your page; in React Native it is a JavaScript component, so the SSN is in your app's runtime until the vault receives it, and the [React Native guide](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md#security) lists what to keep away from it. Your code sees whether the SSN is valid, never the number. Every other field is a plain input whose value you own, so you can prefill it, read it and validate it. Client-side validation runs before anything is sent, and every failure, from a malformed ZIP code to a sanctions match, arrives as one typed error with a `kind` you can branch on and a flag that tells you whether retrying is worth it. You choose how much of the form you build. A drop-in form collects every field and calls you back with the customer ID. Headless building blocks, a provider, individual field components and one hook, let teams that own their UI wire the same behaviour into their own layout. Styling passes straight through to the elements underneath, with no theme contract and no Coinme branding. Phone verification follows the same pattern: a drop-in step texts the code, takes it in one box per digit and calls you back once it checks out, and a hook gives teams that own their UI the same calls. It always verifies the number the customer onboarded with, which the form hands back alongside the `customerId`, and it runs again whenever a customer who never verified signs back in. ## What you need first Before a customer reaches your onboarding form: 1. **Two tokens from your backend.** The onboarding request carries an `Authorization` header with a [Transient Auth Token](https://platformdocs.coinme.com/docs/transient-auth-token.md) your backend mints with `scope=onboarding` for the customer's sign-up session. Phone verification needs a second one, minted the same way for the `customerId` that onboarding returns. Your app fetches each from your backend just in time for each request and never stores it in the browser or on the device. Never give the SDK your partner access token in their place. 2. **A place for phone verification.** Plan the verification step right after onboarding, and on later sign-ins of a customer whose phone is not verified yet. Keep the `customerId` and the phone number on your backend so you can send that customer back to it. The onboarding endpoint itself is described in Coinme's [customer onboarding guide](https://docs.coinme.com/docs/customer-onboarding-overview). ## Platforms | Platform | Package | Status | | --- | --- | --- | | JavaScript: React, or any web app through the core API | `@coinme-security/onboarding-sdk-react` | Available | | React Native: iOS and Android apps, Expo included | `@coinme-security/onboarding-sdk-react-native` | Available | The JavaScript & React SDK is one package with two layers. The React layer is the drop-in form, the field components, the `useCustomerOnboarding` hook, and the `PhoneVerificationStep` and `usePhoneVerification` hook for phone verification. Underneath it is a framework-agnostic core that the React layer is built on and that any web app can call directly: `createOnboardingVault`, the secure SSN field, `validateCustomerOnboardingInput`, `submitCustomerOnboarding`, `sendPhoneVerificationCode`, `validatePhoneVerificationCode` and the typed errors. A plain JavaScript or non-React framework app imports it from the package's `/core` entry, which contains no React code, and does not install React: React is a peer dependency of the React layer only. The React Native SDK has the same drop-in form, field components, phone verification step and hooks, built from native components, and shares the fields, validation rules and error kinds; its secure SSN field is a React Native component from the vault rather than an iframe. ## How it relates to the other SDKs The secure SSN field is a hosted field from the [Coinme Vault SDK](https://platformdocs.coinme.com/docs/coinme-vault-sdk.md), which the Onboarding SDK installs and configures for you; you never set up a vault yourself. The Onboarding SDK is one of the Coinme-as-a-Service SDKs, for apps that keep their own customers: alongside it, the [Vault SDK](https://platformdocs.coinme.com/docs/coinme-vault-sdk.md) captures payment methods and the [Risk SDK](https://platformdocs.coinme.com/docs/coinme-risk-sdk.md) supplies the device and behavioural signals Coinme requires before transactional calls. It is not used with the Coinme Widget, which onboards its users itself. ## Where to go next Start with the [JavaScript & React SDK](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md): the quickstart puts the drop-in form on a page in a few lines, and the rest of the document covers layout control, the headless API, styling, the core API, validation and error handling. For an iOS or Android app built with React Native, start with the [React Native SDK](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md), which covers the same ground with native components. --- --- title: "Onboarding SDK for JavaScript & React" url: "https://platformdocs.coinme.com/#/docs/onboarding-sdk-react" markdown: "https://platformdocs.coinme.com/docs/onboarding-sdk-react.md" summary: "The Coinme Onboarding SDK onboards a customer to Coinme-as-a-Service (CAAS) from your web app, returns the new `customerId`, and then verifies the customer's phone with a code texted to the number they onboarded with. Use it from a React app through its drop-in form, field components and hooks, or from any JavaScript web app (vanilla JS, Vue, Angular, Svelte, …) through the framework-agnostic core the React layer is built on; see Core API (without React). Either way it is the one package, `@coinme-security/onboarding-sdk-react`." surface: "caas" platform: "web" package: "@coinme-security/onboarding-sdk-react" version: "1.7.1" peerDependencies: {"react":">=18","react-dom":">=18"} updated: "2026-11-06" --- # Onboarding SDK for JavaScript & React The Coinme Onboarding SDK onboards a customer to Coinme-as-a-Service (CAAS) from your web app, returns the new `customerId`, and then verifies the customer's phone with a code texted to the number they onboarded with. Use it from a React app through its drop-in form, field components and hooks, or from any JavaScript web app (vanilla JS, Vue, Angular, Svelte, …) through the framework-agnostic core the React layer is built on; see [Core API (without React)](#core-api-without-react). Either way it is the one package, `@coinme-security/onboarding-sdk-react`. This SDK leverages the Coinme Vault so that the customer's Social Security Number is typed into a secure field hosted by the vault, and the raw SSN never touches your JavaScript or your servers. Everything else (email, name, address, phone, date of birth) is collected in ordinary inputs that you style however you like. The endpoint itself is described in Coinme's [customer onboarding guide](https://docs.coinme.com/docs/customer-onboarding-overview). > **See it running.** > > Every approach in this guide, from the drop-in form to the bare fields, is on the [examples page](https://platformdocs.coinme.com/docs/onboarding-sdk-examples.md) as the code and the live form it produces, with simulated submits you can try. ## Why use it Collecting an SSN yourself puts your app, your logs and your servers in scope for handling it. This SDK keeps it out of your code: the customer types it into the vault's secure field, an iframe, and it goes from that iframe to the vault without passing through your page's code. Your code only sees whether the SSN is valid, never the number. You get: - **A drop-in form.** `` collects every field the endpoint requires and calls you back with `{ customerId, phoneNumber }` or a typed error. - **Headless building blocks.** A provider, individual field components (including the secure SSN field) and a `useCustomerOnboarding` hook, for teams that build their own UI. - **Phone verification after onboarding.** `` (or the `usePhoneVerification` hook) texts the new customer a code and checks it, so you know the number they onboarded with is verified before you treat their KYC as complete. - **Pass-through styling.** Every field accepts the same props or options as the element underneath it. There's no theme contract to learn and no Coinme branding. - **A framework-agnostic core.** `@coinme-security/onboarding-sdk-react/core` has no React code, for vanilla JS and every other stack. - **Typed outcomes.** `CoinmeOnboardingError` tells you whether a failure is terminal (duplicate, age, jurisdiction, sanctions) or worth retrying. ## Install The package is published to Coinme's private npm registry. Configure the `@coinme-security` scope with the registry token Coinme provides, then install. `.npmrc` (npm / Yarn Classic): ```properties @coinme-security:registry=https://npm.coinme.com/coinme-security-wrapper/ //npm.coinme.com/coinme-security-wrapper/:_authToken=${COINME_REGISTRY_TOKEN} //npm.coinme.com/coinme-security-wrapper/:always-auth=true ``` `.yarnrc.yml` (Yarn Berry v2+): ```yaml nodeLinker: node-modules npmScopes: coinme-security: npmRegistryServer: 'https://npm.coinme.com/coinme-security-wrapper/' npmAuthToken: '${COINME_REGISTRY_TOKEN}' npmAlwaysAuth: true ``` Then export the token and install: ```bash export COINME_REGISTRY_TOKEN= npm install @coinme-security/onboarding-sdk-react # or: yarn add @coinme-security/onboarding-sdk-react ``` `COINME_REGISTRY_TOKEN` is the registry access token. Request it from your Coinme integration contact. `react` and `react-dom` 18 or later are peer dependencies of the React API (the package root). They're optional: an app without React imports from `@coinme-security/onboarding-sdk-react/core` and doesn't install them. The Coinme Vault SDK (`@coinme-security/vault-sdk-js`), which loads the secure field, is installed with the package. ## Compatibility | Requirement | Supported | | --- | --- | | React | 18 or later (`react` and `react-dom` peers), for the React API only; the `/core` entry needs no React | | Browsers | Chrome / Edge 111+, Firefox 114+, Safari 16.4+ (desktop and iOS) | | Secure field script | Pinned by the SDK and loaded from our vault provider's CDN at runtime | | Server-side rendering | Importing the package on the server is safe; the secure field is created in the browser after mount (see [Server-side rendering](#server-side-rendering)) | | TypeScript | Full typings ship with the package | ### Content-Security-Policy If your site sets a CSP, allow our vault provider's domains and the two Coinme hosts for your environment. The secure SSN field is an iframe served by the vault provider, its script loads from the vault provider's CDN, the onboarding submit goes to the Coinme onboarding host, and the phone verification calls go to the Coinme API host. | Environment | Coinme onboarding host | Coinme API host | | --- | --- | --- | | `live` | `https://secure.apis.coinme.com` | `https://caas.coinme.com` | | `sandbox` | `https://secure.apis.coinme.org` | `https://caas-staging.coinme.com` | With `` and `` replaced by the hosts above: ``` script-src https://js.verygoodvault.com https://js3.verygoodvault.com frame-src https://js.verygoodvault.com https://js3.verygoodvault.com connect-src https://js.verygoodvault.com https://js3.verygoodvault.com https://vgs-collect-keeper.apps.verygood.systems ``` `js3.verygoodvault.com` is the vault provider's fallback CDN, and `vgs-collect-keeper` receives its product-interaction analytics. ## Before you start The SDK covers two steps: onboarding the customer, then verifying their phone. Before a customer reaches your onboarding form: 1. **Have a way to get two tokens from your backend.** The onboarding request needs a token minted for the customer's sign-up session. Phone verification needs a second token, minted for the `customerId` that onboarding returns. Never your partner access token. You write the backend routes that mint them; [You build](#you-build) lists what each one does. 2. **Plan for phone verification right after onboarding, and on later sign-ins with incomplete 2FA.** A newly onboarded customer needs to confirm the code texted to the phone number they onboarded with. If the code isn't confirmed, the customer should not be considered to have completed KYC. See the [recommended integration flow](#recommended-integration-flow). ## Recommended integration flow Onboarding is complete only once the customer's phone is verified. Build your integration in this order: > **Every call after onboarding uses a token for that customer.** > > Sending the code and checking it are authorized by a Transient Auth Token your backend mints for the `customerId` that onboarding returned (step 4). Never use your partner access token or the sign-up session token for them. That token is the only thing that ties the two calls to the customer: there's no challenge ID, session or cookie to carry from one call to the other. See [You build](#you-build) for the backend routes this takes. 1. **Mint an onboarding token for the sign-up session.** When the customer reaches your onboarding screen, your app asks your backend for a token. Your backend calls `POST /services/browserAuth` with `scope=onboarding` and your own identifier for the sign-up session as `customerId`: any ID you choose, such as your internal session ID. The customer doesn't exist at Coinme yet. 2. **Onboard the customer with that token.** Return it from the form's (or provider's) `getHeaders`. When onboarding succeeds, `onSuccess` receives `{ customerId, phoneNumber }`. 3. **Send the real `customerId` to your backend.** From `onSuccess`, send the `customerId` to your backend and link it to the sign-up session, together with `phoneNumber`, the number the customer onboarded with. Keep both: you need them for verification now and whenever the customer comes back. 4. **Mint a new token for the real `customerId`.** Your backend calls `POST /services/browserAuth` again, this time with the `customerId` from onboarding as `customerId`. Use **this** token for every phone verification call; the sign-up session token from step 1 won't work for them. Your backend reads the `customerId` from the record it saved in step 3, not from the browser, so a page can only ever get a token for its own customer. 5. **Start phone verification with that same number.** Your page renders `PhoneVerificationStep` (or uses `usePhoneVerification`) with `phoneNumber` from the onboarding result, and its `getHeaders` returns the token from step 4. Coinme texts the customer a code. 6. **Validate the code for that number.** The customer types the code. Once it checks out, `onVerified` runs; record on your backend that this customer's phone is verified. 7. **Only now treat the customer as onboarded.** A customer whose phone isn't verified hasn't completed KYC. Don't give them access to anything that needs a completed onboarding. 8. **Send a returning customer back to verification.** If a customer whose phone isn't verified signs in again later, take them to phone verification before anything else: mint a fresh token for their `customerId` as in step 4, and use the `phoneNumber` you stored in step 3. Two rules hold in every case: - **No verified phone, no completed onboarding.** Never consider a customer onboarded or KYC-complete until their phone number is verified, whatever your own records or UI show. - **The verification number is the onboarding number.** Never let the customer give one phone number for onboarding and another for verification. Pass `phoneNumber` from the onboarding result (or the copy you stored in step 3), and don't offer a phone input at the verification step. Coinme texts whatever number the SDK sends and, once the code checks out, records it as the customer's verified phone. It doesn't compare it with the onboarded number, so passing the onboarded number is up to you. ## Quickstart The quickest integration is the drop-in form followed by the drop-in phone verification step. The form collects every field the endpoint needs, the SSN included, and calls you back with the new `customerId` and the phone number it onboarded. The step then texts that number a code and checks it. The SDK runs in your page, but it needs a few routes on **your** backend, which you write. The code below calls them; the [You build](#you-build) table after it says what each one does. ```tsx import { useState } from 'react'; import { CustomerOnboardingForm, // Coinme SDK PhoneVerificationStep, // Coinme SDK type CustomerOnboardingResult, // Coinme SDK } from '@coinme-security/onboarding-sdk-react'; // YOUR code, not part of the SDK. These two helpers call routes on YOUR backend (see "You build" // below). The paths are examples. Keep the tokens in memory only: never store or log them. const getTokenFromYourBackend = async (path: string): Promise => { const response = await fetch(path, { method: 'POST', credentials: 'include' }); if (!response.ok) throw new Error(`Token request failed (${response.status})`); const { token } = await response.json(); return token; }; const postToYourBackend = async (path: string, body: unknown): Promise => { const response = await fetch(path, { method: 'POST', credentials: 'include', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body), }); if (!response.ok) throw new Error(`Request to ${path} failed (${response.status})`); }; export const Onboarding = () => { const [onboarded, setOnboarded] = useState(); if (!onboarded) { return ( ({ Authorization: `Bearer ${await getTokenFromYourBackend('/your-api/onboarding/token')}`, })} // Save the result on YOUR backend before moving on: the next token is minted from it. onSuccess={(result) => { void postToYourBackend('/your-api/onboarding/complete', result).then(() => setOnboarded(result) ); }} /> ); } return ( ({ Authorization: `Bearer ${await getTokenFromYourBackend('/your-api/phone-verification/token')}`, })} onVerified={() => { void postToYourBackend('/your-api/phone-verification/verified', {}).then(() => { // YOUR code: take the customer to your next screen. }); }} /> ); }; ``` > **This is one way to do it, not the only way.** > > The route paths, the helper names, the use of cookies (`credentials: 'include'`) and how you show errors are all yours to choose. What matters is what each route does, in the table below. A real integration also handles a failed request (show a retry), and shows the verification step again to a customer who signs back in before verifying (step 8 of the [recommended integration flow](#recommended-integration-flow)). ### You build These routes run on **your** backend. Coinme doesn't provide them: the paths are examples, so name them however you like. Only the Coinme API calls they make are fixed. | Your route (example path) | What it does | | --- | --- | | `POST /your-api/onboarding/token` | Mints a Transient Auth Token for the sign-up session: calls Coinme's `POST /services/browserAuth` with `scope=onboarding` and your own ID for the session as `customerId`. Returns `{ token }`. | | `POST /your-api/onboarding/complete` | Saves the `customerId` and `phoneNumber` from the onboarding result on the signed-in user, in your own database. | | `POST /your-api/phone-verification/token` | Looks up the signed-in user, reads the `customerId` you saved for them, and mints a Transient Auth Token for **that** `customerId` (`scope=onboarding`). Returns `{ token }`. It never takes a `customerId` from the page. | | `POST /your-api/phone-verification/verified` | Records on the signed-in user that their phone is verified. | Your partner access token (from Coinme's `POST /services/authorize`) is what these routes use to call `browserAuth`. It stays on your backend and never reaches the page. **This is how customer IDs can't get mixed up.** Each of your users has one saved `customerId`, and the verification token route only ever mints for that one. The page never says which customer it is, so it can't ask for the wrong one. Example code for all four routes is in [Example: both tokens, end to end](#example-both-tokens-end-to-end). The later examples reuse `getTokenFromYourBackend`, `postToYourBackend` and these route paths, and `getHeaders` and `onSuccess` stand for the onboarding form's functions shown here. `goToWelcome`, `startPhoneVerification`, `reportOnboardingFailure` and `reportVerificationFailure` stand for your own navigation and error display. Switch `environment` to `'live'` for real customers. ## How it works - **`environment` selects everything else.** `'sandbox'` or `'live'` picks the onboarding vault and the Coinme onboarding endpoint, both built into the package. You never configure a vault ID or URL. - **The vault is created in the browser.** The form (or `CoinmeOnboardingProvider`) creates it after mount, which loads the secure field script from the vault provider's CDN, and disposes of it on unmount. - **The SSN goes from the secure field to the vault.** The customer types the SSN into the vault's iframe. When you submit, the iframe sends the request to the vault with the SSN in it. The SSN never passes through your page's code. - **The other fields are plain inputs.** Their values are in React state, so you can prefill, read and validate them. - **You see only metadata for the SSN.** Whether it's valid, empty, focused or touched. Never the number. - **Every failure is one error type.** Client-side validation failures, network failures, HTTP errors and CAAS error codes all become a `CoinmeOnboardingError` with a `kind` and a `retryable` flag. **Terms used in this guide:** - **Vault:** the Coinme Vault connection that holds the secure SSN field. The form or `CoinmeOnboardingProvider` creates one and cleans it up for you. - **Secure field / SSN field:** the vault's iframe the customer types the SSN into. - **Plain fields:** every other field. They're ordinary inputs whose values live in React state. - **Mount:** when React first puts a component on the page. A prop that's "read once on mount" is read then; changing it later has no effect. - **Touched:** a field the customer has left (blurred) at least once. After a submit attempt, every field counts as touched. Inline errors show only for touched fields. ## Authentication and headers You supply the request headers through `getHeaders`, which the SDK calls just before each request. It can be async, so fetch a fresh token inside it. Whatever it returns is sent as the request headers. | Header | Value | | --- | --- | | `Authorization` | `Bearer `, with a [Transient Auth Token](https://platformdocs.coinme.com/docs/transient-auth-token.md) your backend minted with `scope=onboarding`. | | `X-Device-Fingerprint` | Optional from 1.7.0, which always sends one; see [Device fingerprint](#device-fingerprint). With an older release, send the value you give the Risk SDK. | > **Never give the Onboarding SDK your partner access token.** > > `getHeaders` must always return a Transient Auth Token your backend mints from `POST /services/browserAuth` with `scope=onboarding`, never your partner access token (from `POST /services/authorize`). The two steps need different tokens, both minted by your backend with `POST /services/browserAuth` and both lasting 10 minutes: | Step | Minted for (`customerId` when minting) | Passed through | | --- | --- | --- | | Onboarding | Your identifier for the customer's sign-up session, with `scope=onboarding`. The customer doesn't exist at Coinme yet. | The form's or provider's `getHeaders` | | Phone verification | The `customerId` that onboarding returned, with `scope=onboarding`. | `PhoneVerificationStep`'s or `usePhoneVerification`'s `getHeaders` | > **`scope=onboarding` is sandbox-only for now.** > > Coinme's `live` environment doesn't mint `scope=onboarding` tokens yet, so neither step can run in `live` until it does. Check with your Coinme integration contact before going live. Each phone verification call (sending a code, checking it) asks `getHeaders` again, so mint a fresh token there rather than reusing one: a customer who waits for the text can easily pass the 10 minutes. - **Never put your Coinme credentials or your partner access token in the browser.** Only the Transient Auth Tokens reach the page, and only for the requests that need them. Never pass your partner access token (from `POST /services/authorize`) to this SDK. - **Don't store the token.** Fetch it just in time and don't keep it in `localStorage`, `sessionStorage` or cookies. **The verification token is what ties verification to the customer.** Sending the code sends only the phone number, and checking it sends only the code. Coinme works out which customer the calls are for from the token, so there's no challenge ID, session or cookie to carry between them. That's why the token must be minted for that one `customerId`, and why your partner access token must never be used in its place: it isn't tied to any customer, and it must never reach the browser. The SDK refuses a request whose `Authorization` header carries a partner access token and throws a `configuration` `CoinmeOnboardingError` before anything is sent. If you see it, your backend is returning the partner access token to the browser. Change that route to mint a Transient Auth Token from `POST /services/browserAuth` (with `scope=onboarding`) and return only its `access_token`. The partner access token is a long-lived credential that must stay on your backend. The SDK also adds tracing headers (`X-B3-TraceId`, `X-B3-SpanId`) to each request. ### Device fingerprint Coinme ties risk checks to a device ID sent as the `X-Device-Fingerprint` header, and phone verification is refused without it. From 1.7.0, with Risk SDK for Web 1.2.0 or later, the SDK adds it to the onboarding submit and to both phone verification calls, so you don't have to supply one. With an older release of either, send it yourself from `getHeaders`, with the same value you give the Risk SDK. - If you pass a fingerprint (an `X-Device-Fingerprint` header from `getHeaders`, any casing), this SDK uses it and shares it with the other Coinme SDKs in your app. Pass the same value to every Coinme SDK, or pass it to the Risk SDK first, which shares it with the others. - If you don't, the SDK uses the one another Coinme SDK already set in your app, or creates one. - Every Coinme SDK in your app must send the same value. If they differ, adding a payment method and placing orders fail with `WEB_SESSION_ID_MISMATCH`. - Calls your server makes to Coinme for this user (for example orders) must send the same value. Read it in the browser with `getDeviceFingerprint()` and send it to your server with the request. Never call `getDeviceFingerprint()` on your server. - A `:` in the value is replaced with `-`. - A risk session tag lives 30 minutes from when it was first issued. Call the Risk SDK's `getSessionTag()` right before adding a payment method or placing an order, and send the tag it returns as `webSessionId`. The value is shared through `localStorage` under `coinme.deviceFingerprint`, so it survives page reloads. Like `localStorage`, it belongs to your site's origin, not to the device. If storage is blocked, it is shared for the current page only. ### Questions about the two tokens **How do I make sure I don't mix up customer IDs? How does my backend know which customer to mint the verification token for?** From its own records, never from the page. When onboarding succeeds, the page sends the result to your backend, which saves the `customerId` on the signed-in user. When the page later asks for the verification token, your backend looks up the signed-in user and mints the token for the `customerId` it saved. Each user has one saved `customerId`, so the page can't ask for someone else's. **Do I pass the `customerId` to the send or check calls?** No. Neither takes one. The token carries the customer, which is why it has to be minted for that `customerId`. **Can I use my partner access token for phone verification?** No. It isn't tied to any customer, and it must never reach the browser. Use it only on your backend, to mint Transient Auth Tokens. **Can I reuse the onboarding token?** No. It was minted for the sign-up session, before the customer existed at Coinme. Mint a new one for the `customerId` that onboarding returned. ### Example: both tokens, end to end > **This is one way to do it, not the only way.** > > The route names, paths, session handling, framework and storage are yours to choose; only the Coinme API calls and the SDK's props are fixed. It does follow what we recommend: > > - your backend reads the `customerId` from its own record, never from the browser; > - your partner access token is minted and cached on your server only; > - each `getHeaders` call fetches a fresh token, kept in memory only and never stored or logged; > - the phone number is the one from the onboarding result. Who provides what: | | What | Where it runs | | --- | --- | --- | | **Coinme provides** | `POST https://caas-staging.coinme.com/services/authorize`: your partner access token (Coinme API) | Called from your backend only | | **Coinme provides** | `POST https://caas-staging.coinme.com/services/browserAuth`: a Transient Auth Token (Coinme API) | Called from your backend only | | **Coinme provides** | `CustomerOnboardingForm`, `PhoneVerificationStep` and their props (this SDK) | Your page | | **You build** | `POST /your-api/onboarding/token`, `/your-api/onboarding/complete`, `/your-api/phone-verification/token`, `/your-api/phone-verification/verified` (what each does: [You build](#you-build)) | Your backend. These are examples: Coinme doesn't provide them, so name and shape them however you like. | In production, use the base URL your Coinme integration contact gives you in place of `https://caas-staging.coinme.com`. **Your backend** (YOUR code, shown with Express; the routes are examples): ```typescript import express from 'express'; // Your own code: `requireSession` loads YOUR app's session for the person on the page, and `users` is // YOUR user store. `mintTransientAuthToken` wraps the two Coinme API calls above; the // Transient Auth Token guide has a complete version. import { mintTransientAuthToken, requireSession, users } from './your-app'; const app = express(); app.use(express.json()); // Token 1: for the sign-up session. The customer doesn't exist at Coinme yet. app.post('/your-api/onboarding/token', requireSession, async (req, res) => { const { token } = await mintTransientAuthToken(req.session.id, 'onboarding'); res.json({ token }); }); // Save what onboarding returned against YOUR user, so later tokens come from your record. app.post('/your-api/onboarding/complete', requireSession, async (req, res) => { const { customerId, phoneNumber } = req.body; await users.update(req.session.userId, { coinmeCustomerId: customerId, onboardedPhone: phoneNumber, phoneVerified: false, }); res.sendStatus(204); }); // Token 2: for this customer. The browser never says which customer: the ID comes from your // record, so a page can only get a token for its own customer. app.post('/your-api/phone-verification/token', requireSession, async (req, res) => { const user = await users.get(req.session.userId); if (!user?.coinmeCustomerId) return res.sendStatus(409); const { token } = await mintTransientAuthToken(user.coinmeCustomerId, 'onboarding'); res.json({ token }); }); // The page reports that the code checked out. Coinme checked the code itself. app.post('/your-api/phone-verification/verified', requireSession, async (req, res) => { await users.update(req.session.userId, { phoneVerified: true }); res.sendStatus(204); }); ``` **Your page** is the [Quickstart](#quickstart) code: it calls these four routes through `getTokenFromYourBackend` and `postToYourBackend`. ## Field keys and field paths Each field has two names, used by different props: - **Field key**, such as `firstName`. Used by the drop-in form and `OnboardingFormField`: `fieldProps`, `labels`, `hiddenFields`, the custom layout's `fields`, `OnboardingFormField`'s `field` and each row's `data-field` attribute. - **Field path**, such as `fullName.firstName`. The field's place in the onboarding data, used for values and errors: `defaultValues`, `values`, `setValue`, `fieldErrors`, `touched` and `OnboardingInputField`'s `path`. | Field | Field key | Field path | Required | In the drop-in form | | --- | --- | --- | --- | --- | | Email | `email` | `email` | yes | yes | | First name | `firstName` | `fullName.firstName` | yes | yes | | Middle name | `middleName` | `fullName.middleName` | no | yes; can be hidden | | Last name | `lastName` | `fullName.lastName` | yes | yes | | Other names (for example a second last name) | — | `fullName.otherNames.0`, `fullName.otherNames.1`, … | no | no; render with `OnboardingInputField` | | Street address | `addressLine1` | `address.line1` | yes | yes | | Apartment, suite, etc. | `addressLine2` | `address.line2` | no | yes; can be hidden | | City | `city` | `address.city` | yes | yes | | State | `state` | `address.state` | yes | yes | | ZIP code | `postalCode` | `address.postalCode` | yes | yes | | Country | — | `address.country` | no; defaults to `USA` | no | | Phone number | `phoneNumber` | `phoneNumber` | yes | yes | | Date of birth | `dateOfBirth` | `dateOfBirth` | yes | yes | | SSN | `ssn` | none: the SSN never leaves the secure field, so it can't be prefilled or read | yes | yes | Other-name paths are numbered with whole numbers from `0`, with no gaps; any other index is ignored. ```tsx … ``` ## Drop-in form `` renders: - a label, field and inline error for each of: email, first, middle and last name, street address, apartment, city, state, ZIP, phone number, date of birth and SSN; - a message for submit failures; - a submit button. Inline errors appear once a field has been left (blurred). The submit button stays disabled until every field, including the SSN, is valid, while a submit is in flight, and after a successful submit. It doesn't collect other names or a country; the country is sent as `USA`. No CSS is bundled. Unstyled, each row stacks label, field and error. **Style it through pass-through props:** ```tsx ``` The SSN is an iframe, so give its container a fixed height and make the iframe fill it, or it keeps the browser's default 150px height: ```css .input { height: 44px; box-sizing: border-box; padding: 0 12px; } .input iframe { display: block; width: 100%; height: 100%; border: 0; } ``` See [Styling](#styling) for the rest. **Essential** | Prop | Type | Default | Description | | --- | --- | --- | --- | | `environment` | `'sandbox' \| 'live'` | — | **Required.** Which Coinme environment to onboard into: `'sandbox'` for testing, `'live'` for real customers. Read once on mount. | | `getHeaders` | `() => Record \| Promise>` | — | Returns the headers for the onboarding request, for example `{ Authorization: 'Bearer ' }`. Called just before each submit, so it can fetch a fresh token. Optional in the types but needed in practice: without an `Authorization` header, every submit fails as `unauthorized`. See [Authentication and headers](#authentication-and-headers). | | `verifiedPhone` | `{ countryCode: string; number: string }` (`VerifiedPhone`) | — | Optional: a phone number the customer already verified with your own checks, for example `{ countryCode: '1', number: '2065550100' }`. While it's set, the phone field is read-only and shows this number, and the request sends it. Changes apply as they happen. See [Lock the phone to the verified number](#lock-the-phone-to-the-verified-number). | **Callbacks** | Prop | Type | Default | Description | | --- | --- | --- | --- | | `onSuccess` | `(result: { customerId: string; phoneNumber: string }) => void` (`CustomerOnboardingResult`) | — | Called once the customer is onboarded, with their new Coinme customer ID and the phone number they onboarded with (10 digits). Send the `customerId` to your backend from here, since the phone verification token is minted for it, then move the customer on to [phone verification](#phone-verification) (see below). If it throws, the form still counts the submit as a success and stays locked, so the customer can't be sent twice. | | `onError` | `(error: CoinmeOnboardingError) => void` | — | Called when a submit fails: Coinme rejected it, or it didn't complete. Branch on `error.kind`; see [Error handling](#error-handling). | | `onVaultError` | `(error: CoinmeOnboardingError) => void` | — | Called when the form can't load its secure SSN field, for example because the vault provider is blocked. The form can't be submitted until it's mounted again. | **Text** | Prop | Type | Default | Description | | --- | --- | --- | --- | | `defaultValues` | `Partial>` | `{}` | Values to prefill, keyed by [field path](#field-keys-and-field-paths), for example `{ email: user.email, 'address.state': 'WA' }`. The SSN can't be prefilled. Read once on mount. | | `labels` | `Partial>` | English (`DEFAULT_FORM_LABELS`) | Label per field, keyed by [field key](#field-keys-and-field-paths), for example `{ ssn: 'SSN' }`. Text or JSX. | | `validationMessages` | `Partial>` | English (`DEFAULT_VALIDATION_MESSAGES`) | Inline error text per validation code (listed under [Input and validation](#input-and-validation)), for example `{ required: 'Required' }`. `invalidSsn` is the SSN field's message. | | `errorMessages` | `Partial>` | English (`DEFAULT_ERROR_MESSAGES`) | Text shown when a submit fails, per error kind (listed under [Error handling](#error-handling)), for example `{ duplicate: 'You already have an account.' }`. Without an entry, a non-retryable `invalidRequest` shows the terminal text rather than "try again". | | `hiddenFields` | `('middleName' \| 'addressLine2')[]` | `[]` | Optional fields to leave out, for example `['middleName']`. Required fields can't be hidden. | **Styling** | Prop | Type | Default | Description | | --- | --- | --- | --- | | `fieldProps` | `CustomerOnboardingFormFieldProps` (an object keyed by [field key](#field-keys-and-field-paths)) | `{}` | Props passed straight to each field, for example `{ email: { className: 'input', placeholder: 'you@example.com' } }`. Every key except `ssn` takes anything an `` accepts (a ` setValue('phoneNumber', event.target.value)} readOnly={lockedPaths.includes('phoneNumber')} /> ); }; ``` ## Layout control Choose how much of the structure you control. Styling works the same way at every level. | Level | What you control | How | | --- | --- | --- | | **Drop-in** | Styling and copy | `` with `fieldProps`, `classNames`, `labels`, … | | **CSS layout** | Column and row arrangement, order | Target each row's `data-field` attribute with CSS grid or flexbox. No code changes. | | **Custom layout** | The whole structure: sections, headings, columns, your own content between fields | The form's `children` render prop, which receives the pre-wired rows, the alert and the submit button | | **Headless** | Everything, including the submit button and the form element | `CoinmeOnboardingProvider` with `OnboardingFormField` rows or the bare field components, and `useCustomerOnboarding` | **CSS layout.** Every row is `
`, where `data-field` is the field's key (`email`, `firstName`, …, `ssn`). For example, to put fields side by side and keep some full width: ```css .my-form { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: 0 16px; } .my-form [data-field='email'], .my-form [data-field='addressLine1'], .my-form [data-field='ssn'], .my-form .coinme-onboarding-form__alert, .my-form .coinme-onboarding-form__submit { grid-column: 1 / -1; } .my-form input, .my-form select { width: 100%; box-sizing: border-box; } ``` ```tsx ``` Give inputs `width: 100%` and use `minmax(0, 1fr)` columns, so narrow screens don't overflow. **Custom layout.** The render prop keeps the SDK's labels, inline errors, `aria-*` wiring, failure alert and submit button, and lets you place them: ```tsx {({ fields, alert, submitButton }) => ( <>

About you

{fields.firstName} {fields.lastName}
{fields.email} {fields.dateOfBirth}

Home address

{fields.addressLine1}
{fields.city} {fields.state} {fields.postalCode}
{fields.phoneNumber} {fields.ssn} {alert} {submitButton} )}
``` - `fields` holds one row per field. Rows in `hiddenFields` are `null`, and optional fields you don't place are left out. - **Place every required field**, or the form can never become valid. - The render prop also receives `isValid`, `status` and `error`. - The SDK keeps the `
` element and the submit handling. **Headless with the SDK's rows.** `OnboardingFormField` is one labelled row (label, field and linked inline error). Use it anywhere inside `CoinmeOnboardingProvider`: ```tsx
About you
``` `SubmitButton` is yours; see [Headless React](#headless-react). | Prop | Type | Default | Description | | --- | --- | --- | --- | | `field` | `CustomerOnboardingFormFieldKey` | — | **Required.** Which field the row renders, by [field key](#field-keys-and-field-paths), for example `'email'` or `'ssn'`. | | `label` | `ReactNode` | The English label | The row's label. Text or JSX. | | `fieldProps` | Depends on `field` | — | As the drop-in form's `fieldProps` entry for that field, for example `{ className: 'input' }`. | | `validationMessages` | `Partial>` | English | As for the drop-in form. | | `classNames` | `{ row?, label?, control?, fieldError?: string }` | — | Extra classes for the row's parts. | ## Headless React Build your own onboarding UI from a provider, field components and one hook. ```tsx import { AddressLine1Field, CityField, CoinmeOnboardingError, CoinmeOnboardingProvider, CoinmeSsnField, DateOfBirthField, EmailField, FirstNameField, LastNameField, PhoneField, PostalCodeField, StateField, useCustomerOnboarding, } from '@coinme-security/onboarding-sdk-react'; const SubmitButton = () => { const { isValid, submit, status, error } = useCustomerOnboarding({ getHeaders: async () => ({ // YOUR backend route; see "You build". Authorization: `Bearer ${await getTokenFromYourBackend('/your-api/onboarding/token')}`, }), onSuccess: (result) => { // Save the result on YOUR backend first: the verification token is minted from it. void postToYourBackend('/your-api/onboarding/complete', result).then(() => startPhoneVerification(result) ); }, }); return ( <> {error && (

{error.retryable ? 'Please try again.' : "We couldn't onboard you."}

)} ); }; export const Onboarding = () => ( ); ``` `submit()` returns a promise that rejects when the submit fails, and the hook also exposes the failure as `error`. When you render from `error`, as above, catch the `CoinmeOnboardingError` so the rejection isn't reported as unhandled, and rethrow anything else, such as an error thrown by your `onSuccess`. The fields in this example have placeholders but no labels. In a real form, give each one a `