Skip to main content

Payments Overview

The ONE SDK (@one_deploy/sdk v1.1.0) provides a complete payments layer that covers every movement of value your users need: buying crypto with fiat, selling crypto back to fiat, swapping between tokens, sending peer-to-peer transfers, funding e-wallets, and paying bills.

Payment Flow​

                         +------------------+
                         |    Your User     |
                         +--------+---------+
                                  |
            +---------------------+---------------------+
            |          |          |          |           |
            v          v          v          v           v
       +---------+ +--------+ +------+ +--------+ +---------+
       | On-ramp | |Off-ramp| | Swap | |Transfer| | Top-up  |
       | (Buy)   | | (Sell) | |      | | (P2P)  | | / Bills |
       +---------+ +--------+ +------+ +--------+ +---------+
            |          |          |          |           |
            v          v          v          v           v
       +---------------------------------------------------+
       |           @one_deploy/sdk  Payments API            |
       |                                                    |
       |   Widgets (Web)    |    OneEngineClient (All)      |
       +---------------------------------------------------+
            |          |          |          |           |
            v          v          v          v           v
       +---------------------------------------------------+
       |              ONE Engine API (engine.one23.io)      |
       +---------------------------------------------------+
            |                    |                   |
            v                    v                   v
     Fiat Payment          Blockchain           Local Payment
     Processors            Networks             Providers

Payment Capabilities​

CapabilityDescriptionWidget (Web)API (All Platforms)
On-rampBuy crypto with fiat (card, bank, mobile money)OneOnrampWidgetgetOnrampQuote, createOnrampSession
Off-rampSell crypto to fiat (bank payout, mobile money)OneOfframpWidgetgetOfframpQuote, createOfframpTransaction
SwapExchange token-to-token, same-chain or cross-chainOneSwapWidgetgetSwapQuote, executeSwap
P2P TransferSend tokens to any wallet addressOneSendWidgetsendTransaction
Top-upFund e-wallets via local payment methodsOnePayWidgetcreateTopup
Bill PaymentsPay utility bills, airtime, subscriptions-- (coming soon)payBill, getBillProviders

Widgets vs. API​

The ONE SDK exposes two complementary interfaces for payments:

Web Widgets (React DOM only)​

Pre-built React components that handle the full UI flow -- input fields, quote display, confirmation, and status tracking. Drop them into any React DOM application.

import { OneOnrampWidget, OneSwapWidget, OnePayWidget } from '@one_deploy/sdk';
Web Only

All payment widgets render to the DOM and require a browser environment. They are not available in React Native or Node.js. Use the API methods directly on those platforms.

API Methods (All Platforms)​

Every payment action is also available as a method on OneEngineClient. Use these in React Native, Node.js backends, or when you need full control over the UI.

import { OneEngineClient } from '@one_deploy/sdk';

const engine = new OneEngineClient({
  apiKey: process.env.ONE_API_KEY!,
  projectId: process.env.ONE_PROJECT_ID!,
});

// Works on Web, React Native, and Node.js
const quote = await engine.getOnrampQuote('USD', 100, 'USDT');
const swapQuote = await engine.getSwapQuote({ fromToken: 'ETH', toToken: 'USDC', amount: '1.0' });

Supported Chains​

Payment methods are available on the following networks (varies by capability):

ChainOn-rampOff-rampSwapTransfer
EthereumYesYesYesYes
PolygonYesYesYesYes
ArbitrumYesYesYesYes
OptimismYes--YesYes
BaseYes--YesYes
BSCYesYesYesYes
AvalancheYes--YesYes

Common Types​

Several types are shared across payment APIs:

/** Identifies a token across chains */
interface TokenIdentifier {
  symbol: string;
  chainId: number;
  address?: string; // native tokens omit address
}

/** Fiat currency reference */
interface FiatCurrency {
  code: string;        // ISO 4217 -- "USD", "EUR", "NGN"
  name: string;
  symbol: string;      // "$", "€", "₦"
  decimals: number;
}

/** Generic payment status used across all flows */
type PaymentStatus =
  | 'pending'
  | 'processing'
  | 'completed'
  | 'failed'
  | 'expired'
  | 'refunded';

/** Callback shape used by all payment widgets */
interface PaymentCallbacks {
  onSuccess?: (result: { transactionId: string; status: PaymentStatus }) => void;
  onError?: (error: { code: string; message: string }) => void;
  onClose?: () => void;
}

Next Steps​