Customer onboarding flow
1
App
→
OMS
POST /customers
2
OMS
→
App
\{id: "cst\_...", endorsements: \[]}
3
App
→
User
Collect identity documents
4
User
→
App
KYC/KYB data
5
App
→
OMS
Submit verification (KYC flow)
6
OMS
→
App
Webhook: customer.endorsement.granted
7
App
→
OMS
POST /customers/\{id}/wallets
8
OMS
→
Polygon
Derive wallet address
9
OMS
→
App
\{id: "wlt\_...", address: "0x..."}
10
App
→
OMS
POST /customers/\{id}/external-accounts (optional)
11
OMS
→
App
\{id: "cpUsBank\_..."}
***
## Prerequisites
* An OMS API key.
* Webhook subscriptions configured for `customer.endorsement.*` events in the OMS Dashboard.
***
## Step 1: Create a customer
Register the end user with a `POST /customers` call. OMS creates the record and returns an ID.
### Request
```text theme={null}
POST /v0.9/customers
Authorization: Bearer {token}
Idempotency-Key: cst-alice-001
Content-Type: application/json
```
```json theme={null}
{
"type": "individual",
"firstName": "Alice",
"lastName": "Martin",
"email": "alice@example.com",
"phone": "+12125551234",
"birthDate": "1990-05-15",
"nationality": "US",
"externalId": "usr_7890",
"signedAgreement": true
}
```
**Required fields:** `type` must be `individual`. Only the individual customer type is supported in the v0.9 API. All other fields are optional but needed before endorsements can be granted.
**`externalId`** is the recommended way to link the OMS customer record to your internal user ID. Pass it at creation to avoid a separate update call later.
### Response, `201 Created`
```json theme={null}
{
"id": "cst_01H9Xa...",
"object": "customer",
"type": "individual",
"firstName": "Alice",
"lastName": "Martin",
"email": "alice@example.com",
"externalId": "usr_7890",
"status": "active",
"endorsements": [],
"createdAt": "2024-01-15T10:00:00Z"
}
```
The `endorsements` array is empty at creation. No money movement is possible until endorsements are granted.
***
## Step 2: Collect identity and get endorsements
OMS uses an endorsement model to gate access to financial operations. The three endorsements are:
| Endorsement | Unlocks |
| --------------- | ------------------------------------------------------ |
| `basic` | Standard operations. Required for all transactions. |
| `cryptoCustody` | Crypto custody and advanced wallet features. |
| `usd` | USD stablecoin operations, including virtual accounts. |
Your KYC/KYB flow submits identity documents to OMS for review. When verification completes, OMS grants the appropriate endorsements and fires a webhook.
### Webhook: `customer.endorsement.granted`
```json theme={null}
{
"event": "customer.endorsement.granted",
"data": {
"id": "cst_01H9Xa...",
"object": "customer",
"endorsements": ["basic", "cryptoCustody", "usd"]
}
}
```
Check `endorsements` in this payload to confirm which operations are now available for the customer.
***
## Step 3: Provision a wallet
Once the customer has at least the `cryptoCustody` endorsement, create a custodial wallet. OMS derives the onchain address and manages the keys.
### Request
```text theme={null}
POST /v0.9/customers/cst_01H9Xa.../wallets
Authorization: Bearer {token}
Idempotency-Key: wlt-alice-polygon-001
Content-Type: application/json
```
```json theme={null}
{
"asset": "usdc",
"chain": "polygon"
}
```
The customer is identified in the path. The request body declares the `asset` and `chain` the wallet will hold.
### Response, `201 Created`
```json theme={null}
{
"id": "wlt_01H9Xb...",
"object": "wallet",
"customerId": "cst_01H9Xa...",
"address": "0xBEEF4a2c891D56e72b67a3f21d0cf94F1D7c5911",
"asset": "usdc",
"chain": "polygon",
"status": "active",
"createdAt": "2024-01-15T10:01:00Z"
}
```
The `address` is the onchain address where deposits for this customer will be received. Store the `wlt_` ID, you will use it as the source or destination in quotes.
***
## Step 4: Add an external bank account (optional)