Fumadocs on TanStack Start

The PingPay Onramp SDK provides a simple way to integrate cryptocurrency onramp functionality into your application. It allows users to purchase cryptocurrency using fiat payment methods through a popup flow.

Installation

npm install @pingpay/onramp-sdk
# or
yarn add @pingpay/onramp-sdk
# or
pnpm add @pingpay/onramp-sdk
# or
bun add @pingpay/onramp-sdk

Quick Start

import { PingpayOnramp } from "@pingpay/onramp-sdk";

// Create a new instance with configuration
const onramp = new PingpayOnramp({
  onPopupReady: () => console.log("Popup is ready"),
  onProcessComplete: (result) => console.log("Process complete", result),
  onProcessFailed: (errorInfo) => console.error("Process failed", errorInfo),
  onPopupClose: () => console.log("Popup was closed"),
});

// Initiate the onramp process
try {
  // Specify the target asset you want to onramp into
  const targetAsset = { chain: "NEAR", asset: "wNEAR" };
  
  // Start the onramp flow
  const result = await onramp.initiateOnramp(targetAsset);
  
  // Handle successful completion
  console.log("Onramp successful:", result);
} catch (error) {
  // Handle errors
  console.error("Onramp failed:", error);
}

API Reference

`PingpayOnramp`

The main class for interacting with the PingPay Onramp service.

Constructor

constructor(config: PingpayOnrampConfig)

Creates a new instance of the PingPay Onramp SDK.

Parameters:

config: Configuration object containing callback functions and optional settings

Configuration Options

The PingpayOnrampConfig object supports the following properties:

Property	Type	Description
`popupUrl`	`string`	Optional custom URL for the popup window (useful for development)
`onPopupReady`	`() => void`	Called when the popup window is ready
`onFlowStarted`	`(data) => void`	Called when the onramp flow is started
`onStepChange`	`(step, details) => void`	Called when the onramp flow step changes
`onFormDataSubmitted`	`(payload) => void`	Called when form data is submitted
`onWalletConnected`	`(walletInfo) => void`	Called when a wallet is connected
`onTransactionSigned`	`(txInfo) => void`	Called when a transaction is signed
`onOnrampInitiated`	`(serviceInfo) => void`	Called when an external onramp service is initiated
`onProcessComplete`	`(result) => void`	Called when the onramp process completes successfully
`onProcessFailed`	`(errorInfo) => void`	Called when the onramp process fails
`onPopupClose`	`() => void`	Called when the popup window is closed

Methods

`initiateOnramp`

initiateOnramp(target: TargetAsset): Promise<OnrampResult>

Initiates the onramp process for the specified target asset. This opens a popup window that guides the user through the onramp flow.

Parameters:

target: The target asset specification containing chain and asset identifiers

Returns:

A Promise that resolves with the onramp result when the process completes successfully

Throws:

PingpayOnrampError when:
- Onramp is already active
- SDK instance has been closed
- Popup fails to open (browser settings)
- User closes popup before completion
- Onramp process fails at any step

`close`

close(): void

Closes the onramp instance and cleans up all resources. This method closes any open popup windows, clears intervals, and terminates communication channels. After calling this method, the instance cannot be reused.

Types

`TargetAsset`

The TargetAsset type specifies which cryptocurrency the user wants to purchase (onramp into).

type TargetAsset = {
  chain: string;  // The blockchain network (e.g., "NEAR", "ETH", "SOL")
  asset: string;  // The specific asset/token (e.g., "wNEAR", "USDC", "ETH")
}

Examples:

// NEAR wNEAR token
const targetAsset = { chain: "NEAR", asset: "wNEAR" };

// Ethereum USDC token
const targetAsset = { chain: "ETH", asset: "USDC" };

`OnrampResult`

The result of a successful onramp process.

type OnrampResult = {
  success: boolean;
  message: string;
  data?: any;
}

Example: Complete Integration

Here's a complete example showing how to integrate the SDK into a web application:

import { PingpayOnramp, type PingpayOnrampConfig } from "@pingpay/onramp-sdk";

// Add event listener to a button
const openOnrampButton = document.getElementById("openOnrampButton");

if (openOnrampButton) {
  openOnrampButton.addEventListener("click", () => {
    try {
      // Define the target asset (cryptocurrency to purchase)
      const targetAsset = { chain: "NEAR", asset: "wNEAR" };
      
      // Configure the onramp process
      const onrampOptions: PingpayOnrampConfig = {
        onPopupReady: () => {
          console.log("Popup is ready");
          // You might want to show a loading indicator
        },
        onProcessComplete: (result) => {
          console.log("Process complete", result);
          // Handle successful completion
          if (result.success) {
            showSuccessMessage(result.message);
          }
        },
        onProcessFailed: (errorInfo) => {
          console.error("Process failed", errorInfo);
          // Handle failure
          showErrorMessage(errorInfo.error);
        },
        onPopupClose: () => {
          console.log("Popup was closed");
          // Clean up any UI state
        },
      };

      // For local development, you can override the popup URL
      if (globalThis._importMeta_.env.POPUP_URL) {
        onrampOptions.popupUrl = globalThis._importMeta_.env.POPUP_URL;
      }

      // Create and start the onramp process
      const onramp = new PingpayOnramp(onrampOptions);
      onramp.initiateOnramp(targetAsset);
    } catch (error) {
      console.error("Error initializing or opening PingPay Onramp:", error);
      // Handle initialization errors
      showErrorMessage(error instanceof Error ? error.message : "Unknown error");
    }
  });
}

// Helper functions for UI feedback
function showSuccessMessage(message) {
  const messageElement = document.getElementById("statusMessage");
  if (messageElement) {
    messageElement.textContent = `Success: ${message}`;
    messageElement.style.color = "green";
  }
}

function showErrorMessage(message) {
  const messageElement = document.getElementById("statusMessage");
  if (messageElement) {
    messageElement.textContent = `Error: ${message}`;
    messageElement.style.color = "red";
  }
}

Error Handling

The SDK throws PingpayOnrampError instances when errors occur. These errors contain:

message: A description of what went wrong
details: Additional error information (when available)
step: The step in the onramp flow where the error occurred (when available)

try {
  await onramp.initiateOnramp({ chain: "NEAR", asset: "wNEAR" });
} catch (error) {
  if (error.name === "PingpayOnrampError") {
    console.error(`Error during ${error.step || "unknown"} step: ${error.message}`);
    console.debug("Error details:", error.details);
  } else {
    console.error("Unexpected error:", error);
  }
}

Onramp SDK

On this page