SDK 연동

@oozoopay/sdk를 사용하여 프론트엔드에서 결제 UI를 연동하는 방법을 안내합니다.

설치

npm install @oozoopay/sdk

yarn add @oozoopay/sdk

pnpm add @oozoopay/sdk

SDK 초기화

Client Key를 사용하여 SDK 클라이언트를 초기화합니다.

import { OozooPayClient } from '@oozoopay/sdk';

const client = new OozooPayClient({
  clientKey: 'pk_xxxxxxxxxxxxxxxx',
});

옵션	타입	필수	설명
clientKey	string	✓	Client Key (pk_xxx)

결제 요청

requestPayment() 메서드를 호출하면 결제 UI가 표시됩니다. 사용자가 토큰과 네트워크를 선택하면 onCreateInvoice 콜백이 호출되며, 가맹점 서버에서 인보이스를 생성하여 invoiceId를 반환해야 합니다.

await client.requestPayment({
  amount: 100,
  successUrl: '/payment/success',
  failUrl: '/payment/fail',
  onCreateInvoice: async ({ amount, chainId, tokenAddress, sender }) => {
    // 가맹점 서버에 인보이스 생성 요청
    const res = await fetch('/api/create-invoice', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ amount, chainId, tokenAddress, sender }),
    });
    const data = await res.json();
    return data.invoiceId;
  },
});

옵션	타입	필수	설명
amount	number	✓	결제 금액 (USD)
successUrl	string	✓	결제 성공 시 리다이렉트 URL
failUrl	string	✓	결제 실패 시 리다이렉트 URL
onCreateInvoice	function	✓	인보이스 생성 콜백 (아래 참고)

onCreateInvoice 콜백

사용자가 결제 UI에서 토큰과 네트워크를 선택하면 호출됩니다. 가맹점 서버에서 HMAC 서명을 사용하여 인보이스를 생성하고, 생성된 invoiceId를 반환해야 합니다.

파라미터	타입	설명
amount	number	결제 금액 (USD)
chainId	string	선택된 블록체인 네트워크 Chain ID
tokenAddress	string	선택된 토큰의 컨트랙트 주소
sender	string	결제자의 지갑 주소

결제 흐름

1. SDK 초기화 — OozooPayClient에 Client Key를 전달하여 초기화합니다.
2. 결제 요청 — requestPayment()를 호출하면 결제 UI가 표시됩니다.
3. 토큰 선택 — 사용자가 결제할 토큰과 네트워크를 선택합니다.
4. 인보이스 생성 — onCreateInvoice 콜백이 호출되며, 가맹점 서버에서 HMAC 서명으로 인보이스를 생성합니다.
5. 블록체인 결제 — 사용자가 지갑에서 결제를 승인합니다.
6. 결제 완료 — 블록체인 입금이 확인되면 successUrl로 리다이렉트됩니다.
7. 웹훅 수신 — 서버에서 invoice.confirmed 웹훅을 수신하여 결제를 확정 처리합니다.

결제 확정은 웹훅으로 처리

successUrl 리다이렉트만으로 결제를 확정하지 마십시오. 반드시 서버에서 invoice.confirmed 웹훅을 수신한 후 주문을 완료 처리해야 합니다.

가맹점 서버 연동

SDK의 onCreateInvoice 콜백에서 호출할 가맹점 서버 API를 구현해야 합니다. 아래는 Next.js API Route 예시입니다.

// app/api/create-invoice/route.ts
import * as crypto from 'crypto';

export async function POST(req: Request) {
  const { amount, chainId, tokenAddress, sender } = await req.json();

  const clientKey = process.env.OOZOO_CLIENT_KEY!;
  const secretKey = process.env.OOZOO_SECRET_KEY!;

  // 1. HMAC Key
  const hmacKey = crypto.createHash('sha256').update(secretKey).digest('hex');

  // 2. 서명 생성
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const method = 'POST';
  const path = '/api/invoices';
  const body = JSON.stringify({
    price: amount,
    unit: 'usd',
    chainId,
    tokenAddress,
    sender,
  });

  const message = `${timestamp}.${method}.${path}.${body}`;
  const signature = crypto.createHmac('sha256', hmacKey).update(message).digest('hex');

  // 3. OOZOO PAY API 호출
  const res = await fetch('https://api.oozoo.com/api/invoices', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Client-Key': clientKey,
      'X-Timestamp': timestamp,
      'X-Signature': signature,
    },
    body,
  });

  const data = await res.json();
  return Response.json({ invoiceId: data.id });
}

Secret Key 보안

Secret Key는 반드시 서버 사이드에서만 사용해야 합니다. 환경변수로 관리하고 클라이언트에 노출되지 않도록 주의하시기 바랍니다.