> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.upwardli.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.upwardli.com/_mcp/server.

# Consumer Wallet Onboarding

## Overview

Consumer Wallet Onboarding lets partners create a consumer and provision a wallet for them. The flow is the same wallet onboarding flow used for businesses: the entity type decides how identity is verified (KYC for a consumer), and the selected wallet product decides which sponsor bank the wallet is set up at.

## Partner Steps

### 1. Register to Onboarding Completed Webhook

Use the [register webhook](/api-access/api-reference/webhooks/create-register-webhook) API to register for the `Onboarding.Completed` webhook. This webhook tells you when the consumer's wallet has been provisioned. See [Webhooks](#webhooks) for the other onboarding and KYC events.

### 2. Create the Consumer

Create the consumer. The `pcid` is your identifier for the consumer and must be unique across your consumers and businesses. Only `pcid` and `email` are required, but providing the consumer's personal data up front lets KYC run without collecting it again.

See the [create consumer](/api-access/api-reference/consumers/create-new-consumer) API.

POST `https://api-sandbox.upwardli.com/v2/consumers/`

```json
Header
{
    "Authorization":"Bearer [access_token]"
}
```

Body

```json
{
  "pcid": "pcid-jane",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com",
  "phone_number": "205-555-0142",
  "date_of_birth": "1990-04-12",
  "tax_identifier": "123-45-6789",
  "address_line1": "121 Big Creek",
  "address_city": "Tuscaloosa",
  "address_state": "AL",
  "address_zip": "35405"
}
```

Response `201 Created`

```json
{
  "id": "{consumer id}",
  "pcid": "pcid-jane",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com",
  "is_active": true,
  "kyc_status": "Not Started",
  "phone_number": "205-555-0142",
  "date_of_birth": "1990-04-12",
  "tax_id_type": "SSN",
  "tax_identifier": "***-**-6789",
  "address_line1": "121 Big Creek",
  "address_line2": null,
  "address_city": "Tuscaloosa",
  "address_state": "AL",
  "address_zip": "35405"
}
```

You can [list your consumers](/api-access/api-reference/consumers/list-consumers) or [fetch a single consumer](/api-access/api-reference/consumers/retrieve-consumer).

### 3. Start Wallet Onboarding

Start an onboarding for the consumer by posting their `pcid` with an `onboarding_template_id` of `wallet_onboarding`.

See the [create onboarding](/api-access/api-reference/onboarding/create-onboarding) API.

POST `https://api-sandbox.upwardli.com/v2/onboarding/`

Body

```json
{
  "pcid": "pcid-jane",
  "onboarding_template_id": "wallet_onboarding"
}
```

The response is the onboarding object, with the onboarded entity returned under `consumer`. Save the onboarding `id` for the following steps.

### 4. Select the Wallet Product

Select the wallet product for the consumer. The product's account configuration determines the sponsor bank the wallet is opened at.

See the [select product](/api-access/api-reference/onboarding/create-select-product) API.

POST `https://api-sandbox.upwardli.com/v2/onboarding/{onboarding id}/select-product/`

Body

```json
{
  "product_id": "{wallet product id}"
}
```

> **Note**
>
> Contact your Upward representative for the correct wallet `product_id`.

### 5. Verify the Consumer's Identity (KYC)

Run the identity verification step. No request body is needed: Upward starts a KYC check using the consumer's data and adds its ID to `kyc.inquiry_ids` on the onboarding.

See the [verify identity](/api-access/api-reference/onboarding/create-verify-identity) API.

POST `https://api-sandbox.upwardli.com/v2/onboarding/{onboarding id}/verify-identity/`

KYC completes asynchronously. Once the consumer is approved, their `kyc_status` becomes `Approved`, the `Consumer.KYC.Approved` webhook is sent, and the onboarding moves to the next step on its own. If KYC needs more information from the consumer, see [Handling a Fallback Inquiry](/guides/onboarding-and-kyc/handling-a-fallback-inquiry).

### 6. Accept Terms

Record the consumer's acceptance of the wallet terms.

See the [accept terms](/api-access/api-reference/onboarding/create-accept-terms) API.

POST `https://api-sandbox.upwardli.com/v2/onboarding/{onboarding id}/accept-terms/`

Body

```json
{
  "agreement_accepted": true
}
```

### 7. Wallet Provisioning

After terms are accepted, Upward automatically provisions the consumer's wallet at the sponsor bank. No further calls are required. When provisioning finishes, the onboarding `status` becomes `done` and the `Onboarding.Completed` webhook is sent.

If provisioning fails (for example, the sponsor bank is temporarily unavailable), the accepted terms are kept and the setup step can be retried.

### 8. Check Onboarding Status

You can check progress at any time with the [get onboarding](/api-access/api-reference/onboarding/get-onboarding) API:

GET `https://api-sandbox.upwardli.com/v2/onboarding/{onboarding id}/`

Use `current_steps` and `previous_steps` in the response to see where the consumer is in the flow.

## Webhooks

Upward sends onboarding workflow webhooks as the consumer moves through the wallet onboarding flow. The events relevant to this flow are:

| Webhook                                      | Description                                                      |
| -------------------------------------------- | ---------------------------------------------------------------- |
| Onboarding.Started                           | Sent when the wallet onboarding is created                       |
| Onboarding.SelectProduct.Completed / Failed  | Sent when the "Select Product" step succeeds or fails            |
| Onboarding.VerifyIdentity.Completed / Failed | Sent when the "Verify Identity" (KYC) step succeeds or fails     |
| Onboarding.AcceptTerms.Completed / Failed    | Sent when the "Accept Terms" step succeeds or fails              |
| Onboarding.Completed                         | Sent when the wallet has been provisioned and onboarding is done |

The consumer's KYC progress is also reported through the [Consumer KYC Webhooks](/concepts/webhooks/event-catalog#consumer-kyc-webhooks), such as `Consumer.KYC.Approved` and `Consumer.KYC.Failed`.

For payload details and the full list of events, see [Onboarding Workflow Webhooks](/concepts/webhooks/event-catalog#onboarding-workflow-webhooks) in the Event Catalog. To subscribe, see [Registration](/concepts/webhooks/registration).