BVbvnk
Embedded Express

Create express session

Changed on

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.

post/platform/v1/wallet-sessions

Request

Request body

OR

Example request

{
  "customerReference": "22c8168d-f735-43f8-9a3b-a1578efeb86c",
  "theme": {
    "logo": "https://ok14static.oktacdn.com/fs/bco/1/fs0waisynotIeKa80697",
    "primary": "#121212",
    "secondary": "#382457",
    "accent": "#DEF832"
  }
}

Response

Express session created successfully

externalCustomerReferencestring uuid

Your internal customer identifier. Present in responses for new customers.

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

countryCodestring

Country code of the customer's address in the ISO 3166-1 alpha-2 format. Present in responses for new customers.

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

Example response

{
  "externalCustomerReference": "22c8168d-f735-43f8-9a3b-a1578efeb86n",
  "customerReference": "22c8168d-f735-43f8-9a3b-a1578efeb86c",
  "customerType": "INDIVIDUAL",
  "useCase": "EMBEDDED_STABLECOIN_WALLETS",
  "countryCode": "DE",
  "theme": {
    "logo": "https://ok14static.oktacdn.com/fs/bco/1/fs0waisynotIeKa80697",
    "primary": "#121212",
    "secondary": "#382457",
    "accent": "#DEF832"
  },
  "walletSessionUrl": "https://wallet.staging.bvnk.com/welcome?sessionId=f5b2d8cd-887d-421c-ae00-9d3f82b5a45f#token=jafR7d-LarxRQrlXQ5fWgg"
}

Changes

  • 97d6c0d2fe2eRevision changes
    • breaking

      the request property / became required