​
Introduction

Stablepay UI Builder is a package that helps you generate QR codes and wallet URLs for handling on-chain transactions. This guide will walk you through using the UI Builder to create deep links and QR codes for payment processing.

​
Prerequisites

Before you begin, ensure you have the following:

  • Node.js (version 18.10.0 or higher)
  • npm or yarn package manager
  • Basic knowledge of TypeScript and Solana blockchain

​
Installation

Step 1: Install the Stable Pay UI Builder in your project.

Using npm:

npm i @stable-pay/ui-builder

Using yarn:

yarn add @stable-pay/ui-builder

​
Understanding the URL Generator

The generateWalletUrl function helps create deep links for various Solana wallets to initiate Stablepay transactions.

​
Function Signature

import { PublicKey } from '@solana/web3.js';
import { Wallets } from './const';

function generateWalletUrl(
  wallet: Wallets,
  amount: string,
  reference: PublicKey,
  recipient: PublicKey,
  acquirer: string,
  merchantReference: string
): URL | null

​
Parameters

  • wallet: The target wallet (e.g., Phantom, Solflare)
  • amount: The transaction amount as a string
  • reference: The unique transaction reference as a Solana public key
  • recipient: The recipient’s Solana wallet address
  • acquirer: The acquirer identifier
  • merchantReference: Merchant’s custom reference for tracking

​
Using the URL Generator

Here’s an example of how to use the generateWalletUrl function to create a wallet deep link:

import { PublicKey } from '@solana/web3.js';
import { generateWalletUrl, Wallets } from '@stable-pay/ui-builder';

async function createPaymentLink() {
  const recipient = new PublicKey('DUoEBVe3KEmsazfteQwKcwYMvJ4gRujnN2EW67Sng95C');
  const reference = new PublicKey('Rf1yQmLZJByCq7ZPAzN3u2hYt8MsrNmKdMKMNzsw5M2');
  
  const url = generateWalletUrl(
    Wallets.Scalex,
    "1.5",
    reference,
    recipient,
    "stable-pay",
    "ORDER-123"
  );

  if (!url) {
    throw new Error('Failed to generate wallet URL');
  }

  return url.toString();
}

​
Best Practices

  1. Input Validation
    • Always validate public keys before using them
    • Ensure amounts are properly formatted strings
    • Use unique merchant references for transaction tracking
  2. Error Handling
    • Check for null returns from generateWalletUrl
    • Implement proper error messages for failed URL generation
    • Handle wallet-specific edge cases
  3. URL Management
    • Encode merchant references to handle special characters
    • Follow wallet-specific URL format requirements
    • Test URLs across different wallet types
  4. Security
    • Generate unique references for each transaction
    • Validate all input parameters
    • Implement proper error handling

​
Code Generator for non-JavaScript Frontend Applications

To implement the QR code generator in a non-JavaScript frontend application, you can use the following HTML code block as a standalone implementation. This example demonstrates how to create a QR code with a custom logo, styled dots, and proper image handling.

​
—

Note: Data field on the generator must be the returned data of a stable pay transaction request.

<!doctype html>
<html lang="en">

<head>
    <meta charset="UTF-8" />
    <title>QR Code Styling</title>
</head>

<body>
    <div id="canvas"></div>
    <button type="button"
        id="dl">Download</button>
    <script type="module">
        import { QRCodeStyling, browserUtils } from 'https://unpkg.com/@liquid-js/qr-code-styling/lib/qr-code-styling.js'

        const qrCode = new QRCodeStyling({
            width: 300,
            height: 300,
            type: 'svg',
            data: 'solana:FaXWdwxSm3s7A6G2qP7ztNV1jCjATUtcQU9T7qGsy5Xn?amount=1&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&reference=DcHzMsR7b9ZGqSMqqeW7vbrAwur9Hy8ed2k57tDPJZRQ&label=Chicken+and+Chips&message=Thanks+for+your+purchase%21',
            image: 'https://media-hosting.imagekit.io//dbc2e8ed0c7443da/stablepay_logo.svg?Expires=1833433291&Key-Pair-Id=K2ZIVPTIP2VGHC&Signature=DVH6W2gJBTqAl50AbMhF~YKJdTQpYMEVMQfdvjt4i2XmtrA5Qq8YNZvSy9WqOih5HaHzZK-lMIUOyzyWnrOnVcz7ccPwOg69BcOfSzUxg6WEfRePMKbtF2XZ83zUZk9Dke9D8Ee7iAJD15nMe9dsMbcgZnYCVtBPUwr7198racKdr1ozGcimRqmw6EipxJV2xt6ter4JKVUYx1JirrKcFjP~TSMCFOzj8jGhAJxvF1b3vPFoyYiK-6lwYTZn1JjGLqIOcyuqdXl~P2hPMBX-aWNJIuPrbd0XttThnW~ioWTfpI3650l-VxEmZ362NVCTyPb0JNDxImrh~1pWRK3AkQ__',
            dotsOptions: {
                color: '#000000',
                type: 'extra-rounded',
            },
            backgroundOptions: {
                color: '#e9ebee',
                margin: 1
            },
            cornersSquareOptions: {
              type: 'extra-rounded'
            },
            imageOptions: {
                crossOrigin: 'anonymous',
                margin: 1,
            }
        })

        qrCode.append(document.getElementById('canvas'))

        document.getElementById('dl').addEventListener('click', () => {
            browserUtils.download(qrCode, { extension: 'png' }, { width: 1200, height: 1200 })
        })
    </script>
</body>

</html>

​
Examples

​
Basic URL Generation

import { PublicKey } from '@solana/web3.js';
import { generateWalletUrl, Wallets } from '@stable-pay/ui-builder';

// Generate URL for Phantom wallet
const phantomUrl = generateWalletUrl(
  Wallets.Pay,
  "1.0",
  new PublicKey("transaction-reference"),
  new PublicKey("merchant-address"),
  "stable-pay",
  "ORDER-123"
);

// Generate URL for Chipper wallet
const Chipper = generateWalletUrl(
  Wallets.Chipper,
  "1.0",
  new PublicKey("transaction-reference"),
  new PublicKey("merchant-address"),
  "stable-pay",
  "ORDER-123"
);

​
With Error Handling

try {
  const url = generateWalletUrl(
    Wallets.Pay,
    amount,
    reference,
    recipient,
    acquirer,
    merchantReference
  );
  
  if (!url) {
    throw new Error('Failed to generate URL');
  }
  
  // Use the URL for QR code or redirect
  const paymentUrl = url.toString();
  
} catch (error) {
  console.error('Error generating payment URL:', error);
  // Handle error appropriately
}

​
Conclusion

This guide provides a foundational understanding of how to use the Stablepay UI Builder to generate wallet URLs for payments. As you develop, ensure to handle errors appropriately and follow the best practices outlined above.

For further assistance or to report issues, please contact the Stablepay support team or visit our GitHub repository.

Happy coding with Stablepay!