---
title: "Create express session"
method: POST
path: "/platform/v1/wallet-sessions"
tags: ["Embedded Express"]
---

# Create express session

`POST /platform/v1/wallet-sessions`

## Request

- Base URL: `https://api.sandbox.bvnk.com`
- URL: `https://api.sandbox.bvnk.com/platform/v1/wallet-sessions`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/docs/platform/v1/wallet-sessions/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a wallet session URL for Embedded Express customers, allowing them to access their branded stablecoin wallet. The URL is returned in `walletSessionUrl` and can be shared via web view, redirect, or other integration methods. Each session link is time-bound and user-specific for security. BVNK verifies the user's identity before granting access. For details on the customer experience, consult your Account Manager.

To maintain consistent branding, include the optional `theme` object with each session creation. This ensures your customer sees your colors and logo in their wallet interface.

The endpoint automatically manages onboarding based on the customer's status with BVNK:

• New customers receive an onboarding link.

• Existing BVNK customers who have not used Express receive an Express registration link.

• Existing Express customers receive a login link.

• Customers with an active session token can access the wallet interface directly.

For existing BVNK customers receiving an Express link for the first time, ensure the link is accessible only by the intended customer.

Use this endpoint to enable Express features for your customers.

## Request body

- union
  - CreateExpressSessionExistingCustomerRequest: Request payload for your existing embedded customer who is already registered on the BVNK platform.
    - `customerReference` string, uuid, required: Reference of the existing customer in BVNK.
    - `theme` ExpressTheme: Optional theme customization for the Express interface. Allows you to customize the Express interface to match your brand.
      - `logo` string, uri: URL to your company logo. The logo will be displayed throughout the Express interface.
      - `primary` string: Primary brand color as a hex code.
      - `secondary` string: Secondary color as a hex code.
      - `accent` string: Accent color as a hex code.
  - CreateExpressSessionNewCustomerRequest: Request payload for a new customer who doesn't exist on the BVNK platform yet.
    - `type` 'INDIVIDUAL' | 'COMPANY', required: Type of customer to create.
    - `countryCode` string, required: Country code of the customer's address in the ISO 3166-1 alpha-2 format.
    - `externalCustomerReference` string, uuid, required: Your internal customer identifier. This should be a unique identifier for the customer in your platform.
    - `theme` ExpressTheme: Optional theme customization for the Express interface. Allows you to customize the Express interface to match your brand.
      - `logo` string, uri: URL to your company logo. The logo will be displayed throughout the Express interface.
      - `primary` string: Primary brand color as a hex code.
      - `secondary` string: Secondary color as a hex code.
      - `accent` string: Accent color as a hex code.

## Response `200`

Express session created successfully

- ExpressSessionResponse: Response containing the wallet session URL and customer information.
  - `externalCustomerReference` string, uuid: Your internal customer identifier. Present in responses for new customers.
  - `customerReference` string, uuid: BVNK's internal customer identifier. Present in responses for existing customers.
  - `customerType` 'INDIVIDUAL' | 'COMPANY': Type of customer.
  - `useCase` 'STABLECOIN_PAYOUTS' | 'EMBEDDED_STABLECOIN_WALLETS' | 'EMBEDDED_FIAT_ACCOUNTS': Type of product to which the customer agreement applies.
  - `countryCode` string: Country code of the customer's address in the ISO 3166-1 alpha-2 format. Present in responses for new customers.
  - `theme` ExpressTheme: Optional theme customization for the Express interface. Allows you to customize the Express interface to match your brand.
    - `logo` string, uri: URL to your company logo. The logo will be displayed throughout the Express interface.
    - `primary` string: Primary brand color as a hex code.
    - `secondary` string: Secondary color as a hex code.
    - `accent` string: Accent color as a hex code.
  - `walletSessionUrl` string, uri, required: URL that redirects the customer to the wallet interface. The customer then either completes onboarding or logs in through this interface. Provide this URL to your customer via a web view, redirect, or another integration method.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized

## Changes

- **2026-06-16** `97d6c0d2fe2e`: 1 breaking
  - the request property `oneOf[subschema #2: New Customer]/externalCustomerReference` became required

[Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/platform/v1/wallet-sessions/post.md)

---

[API](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints.md) - [All operations](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/revisions/c386d436bf2c?raw)