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

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

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

Body

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

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

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

Body

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

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

Body

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

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.

6. Accept Terms

Record the consumer’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 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:

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:

The consumer’s KYC progress is also reported through the 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 in the Event Catalog. To subscribe, see Registration.