@team-oozoo/oozoo-pay

OOZOO PAY JavaScript SDK for browser-based crypto payments.

Installation

npm install @team-oozoo/oozoo-pay
# or
pnpm add @team-oozoo/oozoo-pay
# or
yarn add @team-oozoo/oozoo-pay

Quick Start

npm / ES Module

import { loadOozooPay } from '@team-oozoo/oozoo-pay';

const client = await loadOozooPay('pk_your_client_key');

await client.pay({
  price: 100,
  unit: 'usd',
  onCreateInvoice: async ({ price, chainId, tokenAddress, sender }) => {
    const res = await fetch('/api/create-invoice', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ price, chainId, tokenAddress, sender }),
    });
    const data = await res.json();
    return data.invoiceId;
  },
  successUrl: '/payment/success',
  failUrl: '/payment/fail',
});

Script Tag (Standalone)

<script src="https://unpkg.com/@team-oozoo/oozoo-pay/dist/standalone.global.js"></script>
<script>
  async function handlePay() {
    const client = await OozooPay.load('pk_your_client_key');
    await client.pay({
      price: 100,
      unit: 'usd',
      onCreateInvoice: async (params) => {
        const res = await fetch('/api/create-invoice', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(params),
        });
        const data = await res.json();
        return data.invoiceId;
      },
      successUrl: '/payment/success',
      failUrl: '/payment/fail',
    });
  }
</script>

API

loadOozooPay(clientKey)

Initializes the SDK and returns an OozooPayClient instance.

| Parameter | Type | Required | Description | | ----------- | -------- | -------- | ------------------------- | | clientKey | string | Yes | API Client Key (pk_xxx) |

client.pay(options)

Opens the payment window and processes a payment from the user.

await client.pay({
  price: 100,
  unit: 'usd',
  onCreateInvoice: async (params) => {
    // Create an invoice on your merchant server and return the invoiceId
    return invoiceId;
  },
  successUrl: '/payment/success',
  failUrl: '/payment/fail',
});

| Option | Type | Required | Description | | ----------------- | ----------------------------- | -------- | ------------------------------------------------------------------------- | | price | number | Yes | Payment amount | | unit | 'usd' | No | Currency unit (default: 'usd') | | onCreateInvoice | (params) => Promise<string> | Yes | Invoice creation callback | | successUrl | string | Yes | Redirect URL on success (?invoiceId={id} appended) | | failUrl | string | No | Redirect URL on failure/cancel. If omitted, modal closes without redirect |

onCreateInvoice Parameters

| Field | Type | Description | | -------------- | -------- | ---------------------- | | price | number | Payment amount | | unit | string | Currency unit | | chainId | string | Blockchain chain ID | | tokenAddress | string | Token contract address | | sender | string | Payer's wallet address |

client.transfer(options)

Opens the checkout window to send a payout (withdrawal) to a user. Same interface as pay(), except the onCreateInvoice callback receives receiver instead of sender.

await client.transfer({
  price: 50,
  unit: 'usd',
  onCreateInvoice: async ({ price, chainId, tokenAddress, receiver }) => {
    const res = await fetch('/api/create-transfer', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ price, chainId, tokenAddress, receiver }),
    });
    const data = await res.json();
    return data.invoiceId;
  },
  successUrl: '/transfer/success',
  failUrl: '/transfer/fail',
});

| Option | Type | Required | Description | | ----------------- | ----------------------------- | -------- | ------------------------------------------------------------------------- | | price | number | Yes | Transfer amount | | unit | 'usd' | No | Currency unit (default: 'usd') | | onCreateInvoice | (params) => Promise<string> | Yes | Invoice creation callback | | successUrl | string | Yes | Redirect URL on success (?invoiceId={id} appended) | | failUrl | string | No | Redirect URL on failure/cancel. If omitted, modal closes without redirect |

failUrl Query Parameters

| Scenario | Query Parameters | Example | | ------------- | ---------------------------------- | --------------------------------------- | | User cancel | ?code=CANCELLED | /fail?code=CANCELLED | | Payment error | ?code={ERROR_CODE}&message={msg} | /fail?code=PAYMENT_FAILED&message=... |

Error Handling

The SDK exports typed error classes:

import { OozooPayError, ConfigError, ApiError } from '@team-oozoo/oozoo-pay';

| Error Class | Description | | --------------- | ----------------------------------------------------- | | OozooPayError | Base error class for all SDK errors | | ConfigError | Invalid configuration (missing clientKey, price, etc) | | ApiError | API request failure |

TypeScript

All types are exported for TypeScript users:

import type {
  PayOptions,
  TransferOptions,
  PayInvoiceParams,
  TransferInvoiceParams,
  PaymentConfig,
  PaymentRouter,
  PaymentSetting,
} from '@team-oozoo/oozoo-pay';