API and Dashboard
Integrate with a Wallet
Custom Wallet

Custom Wallet

This guide will show you how to integrate Paradym with a custom holder wallet, and what the holder wallet needs to support to work with Paradym.

💡

The Paradym Wallet is fully integrated with Paradym, and can be used as a holder wallet for issuing and verifying credentials.

If you're in need of building a custom holder wallet, feel free to reach out to us.

App linking

⚠️

Configuring custom app linking is not available on the free tier. If you want to use your own wallet with Paradym, you can upgrade to a paid plan. See the pricing page (opens in a new tab) for more information.

When using a custom wallet that you configured in the profile settings of your project, you need to make sure your wallet and website can handle the required links. This guide covers setting up the invitation page, registering deep links, and handling these in your wallet application.

Invitation Page

When an user clicks on an invitation link on their device that has your wallet installed the user will be redirected directly to your wallet. The same is true when they scan the QR on the invitation page with their mobile device with a QR scanner that supports iOS Universal Links and Android App Links.

However if they don't have the wallet installed they will be shown the fallback invitation page in the browser. By default, Paradym hosts an invitation page on https://paradym.id/invitation which is used for all invitations. But if you use a custom wallet base URL to link to your wallet, you need to ensure to also host.

You can embed the Paradym invitation as an iFrame into your website or server:

  • Set up an HTML page that matches any route under your configured wallet base URL (e.g. https://example.com/my-wallet-invitation and all paths that fall under that page, e.g. https://example.com/my-wallet-invitation/be100bbc-e563-41a4-9ae9-179f28cdc95b).
  • In the html page render an iFrame. To get the url of the iFrame to render, extract the current URL of the page (using window.location.href) and replace <baseUrl> ( the URL you configured in your profile on Paradym, e.g. https://example.com/my-wallet-invitation) with the Paradym invitation page base URL https://paradym.id/invitation. Leave all additional parameters and query parameters in place.

A minimal HTML page that embeds the Paradym invitation page as an iFrame, where the wallet base URL is configured as https://example.com/my-wallet-invitation.

<!DOCTYPE html>
<html lang="en" style="padding: 0; margin: 0">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
 
  <body style="padding: 0; margin: 0">
    <iframe
      id="dynamic-iframe"
      style="position: fixed; width: 100%; height: 100%; border: none"
    ></iframe>
    <script>
      const iframeUrl = window.location.href.replace(
        "https://example.com/my-wallet-invitation",
        "https://paradym.id/invitation"
      );
      document.getElementById("dynamic-iframe").src = iframeUrl;
    </script>
  </body>
</html>

Registering Deep Links, Android App Links and iOS Universal Links

To be able to link directly into your wallet based on a deep link, Android App Link, or an iOS Universal Link, you need to register the required schemes in your wallet application.

The following links should be registered:

  • <baseUrl> - Your <baseUrl> should be reigstered as an iOS Universal Link or Android App Link. This will allow linking directing into you wallet. It is recommended to add a path specific for invitations (e.g. https://example.com/invitation) so you can redirect these links to your wallet, and know that they came from Paradym.
  • didcomm - this will allow DIDComm deeplinks
  • openid-credential-offer - this will allow OpenID for Verifiable Credential Issuance deeplinks
  • openid4vp - this will enable OpenID for Verifiable Presentation deeplinks.

Read more on registering an Android App Link (opens in a new tab), Android Deep Link (opens in a new tab), iOS Universal Link (opens in a new tab), or iOS Deep Link (opens in a new tab).

If you're using Expo, read the guides on Expo - Android App Links (opens in a new tab) and Expo - iOS Universal Links (opens in a new tab)

Link Structure

Your wallet should be able to handle the following deep links and universal links structures used by Paradym. The deeplinks are rendered on the invitation page and allows opening the link in any identity wallet that has registered the scheme. The universal links enables you to link directly to your wallet.

The <baseUrl> will be the "Wallet base URL" that you configured in the profile page under the project settings.

Paradym WalletUse Zapier