@pingpay/onramp-sdk

The Onramp SDK provides the core functionality for integrating Pingpay Onramp into any web application. It exposes the PingpayOnramp class, which manages the entire onramp flow through a popup window.

Core Concepts

• PingpayOnramp Class: The main entry point for the SDK. It handles the creation and management of the onramp popup.
• initiateOnramp Method: Starts the onramp process, opening a popup window and returning a promise that resolves with the onramp result.
• Lifecycle Events: Optional callbacks (onPopupReady, onPopupClose) allow developers to hook into the onramp lifecycle.
• Communication: The SDK uses postMessage to establish a secure communication channel with the popup window for exchanging messages and data.

Installation

npm install @pingpay/onramp-sdk

Quick Start

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

const onramp = new PingpayOnramp({
  onPopupReady: () => console.log("Popup is ready"),
  onPopupClose: () => console.log("Popup was closed"),
});

try {
  const result = await onramp.initiateOnramp({ chain: "NEAR", asset: "wNEAR" });
  console.log("Onramp successful:", result);
} catch (error) {
  console.error("Onramp failed:", error);
}

Configuration

The PingpayOnrampConfig object accepts the following options:

| Option | Type | Description | |--------|------|-------------| | appFees | OneClickFee[] | Optional fees to be applied to the onramp transaction. Each fee specifies a recipient address and a fee amount in basis points. | | destinationAddress | string | Optional pre-filled destination wallet address. When set, the address field in the popup is read-only and non-editable by the end user. | | popupUrl | string | Override the popup URL. Useful for local development and testing. | | onPopupReady | () => void | Callback invoked when the popup window signals it's ready. | | onPopupClose | () => void | Callback invoked when the popup window is closed. |

App Fees

You can charge fees on each onramp transaction by passing appFees:

const onramp = new PingpayOnramp({
  appFees: [
    { recipient: "fees.yourapp.near", fee: 50 }, // 50 basis points = 0.5%
  ],
});

Destination Address

Pre-fill and lock the recipient wallet address so end users cannot change it. This is useful for apps that manage wallets on behalf of users:

const onramp = new PingpayOnramp({
  destinationAddress: "alice.near",
});

await onramp.initiateOnramp({ chain: "NEAR", asset: "wNEAR" });
// The popup will show "alice.near" as a read-only field

Cleanup

Call close() to shut down the popup and release resources:

onramp.close();

After calling close(), the instance cannot be reused — create a new PingpayOnramp instance instead.