​
Introduction

Stablepay is a solution for handling on-chain transactions for fintech wallets. This guide will walk you through the process of integrating Stablepay into your application, from installation to sending transactions.

​
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 Stablepay transaction handler in your project.

Using npm:

npm i @stable-pay/ui-builder

Using yarn:

yarn add @stable-pay/ui-builder

​
Understanding the QR code UI Builder

The @stable-pay/ui-builder package provides a TypeScript function that helps Merchants build a QR code destop solution for their checkout.

​
Key Features

  • Handles Stablepay transactions
  • Supports custom references for merchant tracking
  • Allows optional sponsor for transaction fees

​
Using the Transaction Handler

The main function provided by the package is handleTransferRequest. Here’s its signature:

async function handleTransferRequest(
    connection: Connection,
    sender: PublicKey | Keypair,
    { recipient, amount, reference, customReference }: CreateTransferFields,
    { commitment }: { commitment?: Commitment } = {},
    sponsor?: Keypair | null,
): Promise<Transaction>

​
Parameters

  • connection: A Connection object to interact with the Solana network
  • sender: The PublicKey or Keypair of the transaction sender
  • CreateTransferFields: An object containing:
    • recipient: The receiving address (PublicKey)
    • amount: The amount to transfer
    • reference: A unique identifier for the transaction
    • customReference: A custom reference (e.g., for merchant tracking)
  • commitment: (Optional) The desired commitment level for the transaction
  • sponsor: (Optional) A Keypair object for a sponsor to pay transaction fees

​
Return Value

The function returns a Promise that resolves to a Transaction object.

​
Sending a Stablepay Transaction

Here’s an example of how to use the handleTransferRequest function to create and send a Stablepay transaction:

import { Connection, PublicKey, sendAndConfirmTransaction } from '@solana/web3.js';
import { handleTransferRequest } from '@stable-pay/handler';
import BigNumber from 'bignumber.js';

async function sendStablePayTransaction() {
  // Initialize connection to Solana network
  const connection = new Connection('https://api.mainnet-beta.solana.com', 'confirmed');

  // Set up transaction parameters
  const sender = new PublicKey('DUoEBVe3KEmsazfteQwKcwYMvJ4gRujnN2EW67Sng95C');
  const recipient = new PublicKey('F9SV1tbmr1Xtug552YwFU4ePnJEX2XdyP1EuTJnkSfL9');
  const amount = new BigNumber(0.1); // Amount in SOL
  const reference = 'Ee79adtuYt4ecrJ6NFP8WF7FTcMb5hDuxRwLHsdu4VQM';
  const customReference = 'ST-10022'; // Custom reference for merchant tracking
  const sponsor = Keypair.generate(); // Optional: Generate a sponsor keypair

  // Create the transaction
  const tx = await handleTransferRequest(
    connection,
    sender,
    {
      recipient,
      amount,
      reference,
      customReference,
    },
    { commitment: 'confirmed' },
    sponsor
  );

  // Send and confirm the transaction
  const signature = await sendAndConfirmTransaction(connection, tx, [sponsor]);

  console.log('Transaction signature:', signature);
  return signature;
}

// Call the function
sendStablePayTransaction().catch(console.error);

​
Best Practices

  1. Error Handling: Always wrap your Stablepay transactions in try-catch blocks to handle potential errors gracefully.
  2. Transaction Confirmation: Use the appropriate commitment level for your use case. ‘Confirmed’ is a good balance between speed and security.
  3. Custom References: Utilize the customReference field for internal tracking and reconciliation purposes.
  4. Sponsorship: Consider using a sponsor for transaction fees to improve user experience, especially for new users who might not have SOL.

​
Conclusion

This guide provides a foundational understanding of how to integrate and use Stablepay in your application. As you develop, refer to the official Stablepay documentation for more advanced features and up-to-date information.

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

Happy coding with Stablepay!