> 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.

# Business Wallet Onboarding

## Overview

Business Wallet Onboarding lets partners create a business entity and provision a wallet for it. The flow is the same wallet onboarding flow used for consumers: the entity type decides how identity is verified (KYB for a business), and the selected wallet product decides which sponsor bank the wallet is set up at.

> **Note**
>
> Business onboarding endpoints require a partner token. User-scoped (customer) tokens cannot create or read businesses or their onboardings.

## 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 business's wallet has been provisioned. See [Webhooks](#webhooks) for the other onboarding events.

### 2. Create the Business

Create the business entity. The `pcid` is your identifier for the business and must be unique across your consumers and businesses.

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

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

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

Body

```json
{
  "pcid": "pcid-acme",
  "name": "Acme Holdings LLC",
  "email": "ops@acme.example.com",
  "phone_number": "(205) 555-0142",
  "date_of_incorporation": "1957-09-06",
  "address_line1": "9061 Trinity Overpass",
  "address_city": "Tuscaloosa",
  "address_state": "Alabama",
  "address_zip": "35405",
  "tax_identifier": "123451803"
}
```

Response `201 Created`

```json
{
  "id": "{business id}",
  "pcid": "pcid-acme",
  "name": "Acme Holdings LLC",
  "email": "ops@acme.example.com",
  "is_active": true,
  "kyb_status": "Not Started",
  "phone_number": "+12055550142",
  "date_of_incorporation": "1957-09-06",
  "tax_id_type": "EIN",
  "tax_identifier": "***-**-1803",
  "address_line1": "9061 Trinity Overpass",
  "address_line2": null,
  "address_city": "Tuscaloosa",
  "address_state": "AL",
  "address_zip": "35405"
}
```

You can [list your businesses](/api-access/api-reference/businesses/list-businesses) or [fetch a single business](/api-access/api-reference/businesses/get-business).

### 3. Start Wallet Onboarding

Start an onboarding for the business by posting its `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-acme",
  "onboarding_template_id": "wallet_onboarding"
}
```

The response is the onboarding object. For a business, the onboarded entity is returned under `business` (instead of `consumer`). Save the onboarding `id` for the following steps.

### 4. Select the Wallet Product

Select the wallet product for the business. 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**
>
> Business wallets must use a wallet product configured for a sponsor bank that supports business accounts. Contact your Upward representative for the correct `product_id`.

### 5. Verify the Business's Identity (KYB)

Run the identity verification step. No request body is needed for a business.

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/`

Once the business is approved, its `kyb_status` becomes `Approved` and the onboarding moves to the next step.

### 6. Accept Terms

Record the business'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 business'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 business is in the flow.

## Webhooks

Upward sends onboarding workflow webhooks as the business 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" (KYB) 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 |

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).