How to test your Buy integration

This guide shows you how to test your Buy provider integration in Ledger Wallet. Complete this final step before deploying your Buy widget to Ledger Wallet’s production environment.

Test these three flows on desktop, iOS, and Android:

1. New user flow (registration)
2. Returning user flow (sign-in)
3. Buy again flow, which appears on the initial Buy screen in Ledger Wallet after you initiate a purchase

Before you start

Complete these steps before running the flows below:

• Backend integration guide — server-side integration
• LiveApp guide — building and publishing the LiveApp
• Load a manifest in developer mode — how to add a local app

Prerequisites for testing

• Technical integration: Complete the backend and LiveApp integration steps linked above.
• Accounts in Ledger Wallet: To start and complete a purchase, you need accounts in Ledger Wallet, such as Bitcoin or Ethereum accounts. You need a Ledger signer to set up these accounts.
• Authentication and payment methods: Use your own KYC-verified account and payment methods to run real transactions in your widget.

Test in your own environment

Test your LiveApp in different environments to check how it works in Ledger Wallet. Ledger Wallet uses a manifest, which is a JSON configuration file, to load an embedded LiveApp with specific parameters.

Set these two manifest attributes to switch the widget environment, such as to localhost or staging:

• providerTestId: Specifies the provider to test. After you set this value, the Buy/Sell section displays only that provider. Contact Ledger if you do not know your provider ID.
• providerTestBaseUrl: Sets the base URL for the environment, such as http://localhost:3000/buy or https://provider.staging.

After you add these attributes, Ledger Wallet replaces the LiveApp’s base URL with the specified providerTestBaseUrl.

Example:

Original LiveApp URL loaded in Ledger Wallet:

https://yourwidget.com?[accountAddress]=x0…&[cryptoCurrency]=bitcoin&[fiatCurrency]=EUR&[fiatAmount]=50&[cryptoAmount]=0.0009490481&[mode]=buy&[paymentMethod]=bank&[bankResidency]=fr&[buySessionId]=cd12538-b02a-4282-99de-4d90f10769a0&[language]=en&[theme]=dark&[platform]=desktop

LiveApp URL after you load the buy-sell-ui manifest locally with "providerTestId" and "providerTestBaseUrl":

http://providerTestBaseUrl?[accountAddress]=x0…&[cryptoCurrency]=bitcoin&[fiatCurrency]=EUR&[fiatAmount]=50&[cryptoAmount]=0.0009490481&[mode]=buy&[paymentMethod]=bank&[bankResidency]=fr&[buySessionId]=cd12538-b02a-4282-99de-4d90f10769a0&[language]=en&[theme]=dark&[platform]=desktop

Your test environment must accept the query string parameters that Ledger Wallet generates for your widget. You cannot modify these parameters with providerTestBaseUrl because Ledger Wallet’s backend generates some of them. This behavior lets you test the actual flow in your local environment.

To test the flow:

1. Obtain the manifest from Ledger. Before loading it in Ledger Wallet, add the "providerTestId" and "providerTestBaseUrl" attributes described above. Follow Add a local app  to load the manifest.
2. Open the Buy/Sell section. The list of available providers displays only the provider specified by "providerTestId".
3. Select the provider. Ledger Wallet opens the URL specified by "providerTestBaseUrl".

Test in pre-production

You must also test in Ledger Wallet’s pre-production environment, which uses your production keys and endpoints. Run real transactions to test the integration under real-world conditions.

Ledger will provide a manifest that connects the Buy/Sell section to the pre-production environment. Load this manifest in Ledger Wallet without modifying it. This configuration directs users to your widget’s actual URL.

What to test

UX requirements

• Non-editable wallet address: Confirm that the review page shows the wallet address before the user completes the transaction and that the address is not editable.
• Persistent session: Confirm that users remain signed in to your widget after closing and reopening either the widget or Ledger Wallet.
• Dark and light modes: Confirm that your widget automatically adjusts its layout, if available, to match the user’s selected theme in Ledger Wallet.
• Automatic payment method selection: Confirm that the widget automatically selects the payment method that the user chose in Ledger Wallet.
• Responsive LiveApp: Confirm that your widget adjusts its layout to fit mobile screens.

Authentication and account creation

• New account creation: Complete the full account creation process in your widget within Ledger Wallet. Confirm that each step works, including KYC steps that use the device’s camera or file upload feature.
• Sign-in: Confirm that you can sign in to and out of your widget within Ledger Wallet. The session must persist so that users do not need to sign in each time they open the widget.

Transactions

• Quote accuracy: Confirm that the quotes shown in Ledger Wallet match those in your widget, including all fees.
• Buy transaction: Perform real transactions using as many supported blockchains as possible, along with various fiat currencies and payment methods. Confirm each transaction and verify on-chain that the funds reach the expected Ledger wallet address.
• Buy again transaction: After you initiate a purchase in Ledger Wallet with your provider, confirm that the Buy again with button appears on the initial Buy screen and that the flow works as expected.

Next steps

After you complete the tests, share your results with Ledger. We will evaluate each potential issue, prioritize it, and implement the appropriate fixes.