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.

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 to register for the Onboarding.Completed webhook. This webhook tells you when the business’s wallet has been provisioned. See 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.

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

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

Body

{
  "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

{
  "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 or fetch a single 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.

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

Body

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

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

Body

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

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.

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.

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

Body

{
  "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:

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 in the Event Catalog. To subscribe, see Registration.