@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)

SDK 초기화 함수. OozooPayClient 인스턴스를 반환합니다.

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

client.pay(options)

결제 창을 열고 사용자에게 결제를 받습니다.

await client.pay({
  price: 100,
  unit: 'usd',
  onCreateInvoice: async (params) => {
    // 가맹점 서버에서 인보이스 생성 후 invoiceId 반환
    return invoiceId;
  },
  successUrl: '/payment/success',
  failUrl: '/payment/fail',
});

| Option | Type | Required | Description | | ----------------- | ----------------------------- | -------- | ---------------------------------------------------- | | price | number | Yes | 결제 금액 | | unit | 'usd' | No | 통화 단위 (기본: 'usd') | | onCreateInvoice | (params) => Promise<string> | Yes | 인보이스 생성 콜백 | | successUrl | string | Yes | 결제 성공 시 리다이렉트 URL (?invoiceId={id} 추가) | | failUrl | string | Yes | 결제 실패/취소 시 리다이렉트 URL |

onCreateInvoice Parameters

| Field | Type | Description | | -------------- | -------- | -------------------- | | price | number | 결제 금액 | | unit | string | 통화 단위 | | chainId | string | 블록체인 네트워크 ID | | tokenAddress | string | 토큰 컨트랙트 주소 | | sender | string | 결제자 지갑 주소 |

failUrl Query Parameters

| 상황 | Query Parameters | 예시 | | ----------- | ------------------------------------- | --------------------------------------- | | 사용자 취소 | ?code=CANCELLED | /fail?code=CANCELLED | | 결제 에러 | ?code={ERROR_CODE}&message={메시지} | /fail?code=PAYMENT_FAILED&message=... |

client.transfer(options)

출금 창을 열고 사용자에게 출금합니다. pay()와 동일한 인터페이스이며, onCreateInvoice 파라미터에 sender 대신 receiver가 전달됩니다.

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',
});