초급10 분 읽기

Public Key 모드

Public Key 모드는 브라우저 통합을 위한 방식입니다. 프론트엔드는 public_key로 짧은 Session Token을 발급받고, 이 Token으로 주문 생성과 상태 조회를 수행하며 API Key를 브라우저에 노출하지 않습니다.

통합 흐름

상점 대시보드에서 Public Key를 생성하고 프론트엔드 통합을 활성화합니다.
허용할 도메인 화이트리스트를 설정합니다.
브라우저가 Public Key로 /api/v1/sdk/token을 호출합니다.
반환된 Session Token으로 /api/v1/sdk/orders를 호출합니다.
payment_url로 리디렉션하거나 주문 상태를 조회합니다.

현재 Public Key 모드는 프론트엔드에서 파라미터 서명을 만들 필요가 없습니다. JavaScript SDK 사용 또는 아래 수동 API 호출 방식을 권장합니다.

Public Key 받기

PonponPay 상점 대시보드에 로그인합니다.
"Frontend Integration" 페이지를 엽니다.
프론트엔드 통합을 활성화합니다.
pub_xxx 형식의 Public Key를 생성하고 복사합니다.

도메인 화이트리스트

Public Key는 허용된 도메인에서만 사용할 수 있습니다. 백엔드는 Origin 또는 Referer를 검증합니다.

개발 환경에서만 localhost를 허용하세요.
운영 환경에서는 실제 도메인만 사용하세요.
*.example.com 같은 와일드카드 서브도메인을 지원합니다.

페이지가 iframe, 앱 WebView, 중간 결제 페이지에서 열리면 Origin 헤더가 안정적으로 전달되지 않을 수 있습니다. 운영 전 Origin과 Referer 동작을 확인하세요.

권장: JavaScript SDK

npm install @ponponpay/sdk

클라이언트 초기화

import { PonponPayClient } from '@ponponpay/sdk/browser';

const client = new PonponPayClient({
  publicKey: 'pub_your_public_key',
  baseUrl: 'https://api.ponponpay.com'
});

주문 생성

const order = await client.createOrder({
  currency: 'USDT',
  network: 'tron',
  amount: 100,
  orderId: 'ORDER_123456',
  notifyUrl: 'https://your-site.com/webhook',
  redirectUrl: 'https://your-site.com/success'
});

window.location.href = order.paymentUrl;

주문 상태 조회

const status = await client.getOrderStatus(order.tradeId);
console.log(status.status);

SDK 세부 내용은 JavaScript SDK 섹션 또는 저장소 README를 참고하세요.

수동 API 통합

1. 짧은 Token 발급

const tokenRes = await fetch('https://api.ponponpay.com/api/v1/sdk/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    public_key: 'pub_your_public_key',
    timestamp: Date.now()
  })
});

const tokenData = await tokenRes.json();
const token = tokenData.data.token;

2. Token으로 주문 생성

const orderRes = await fetch('https://api.ponponpay.com/api/v1/sdk/orders', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${token}`
  },
  body: JSON.stringify({
    currency: 'USDT',
    network: 'tron',
    amount: 100,
    order_id: 'ORDER_123456',
    notify_url: 'https://your-site.com/webhook',
    redirect_url: 'https://your-site.com/success'
  })
});

const orderData = await orderRes.json();
window.location.href = orderData.data.payment_url;

3. 주문 상태 조회

const statusRes = await fetch(
  'https://api.ponponpay.com/api/v1/sdk/orders/T20240101120000123456/status',
  {
    headers: {
      Authorization: `Bearer ${token}`
    }
  }
);

const statusData = await statusRes.json();
console.log(statusData.data.status);

기능 범위

기능	지원	설명
주문 생성	✅	SDK token order API로 지원됩니다.
상태 조회	✅	Public Key와 연결된 상점의 주문만 조회할 수 있습니다.
전체 관리자 API	❌	Public Key 모드에서는 브라우저에 노출되지 않습니다.
브라우저에 API Key 노출	❌	절대 하지 마세요. 브라우저에서는 Public Key만 사용하세요.

보안 안내

Public Key는 공개 가능하지만 허용된 도메인에서만 동작합니다.
Session Token은 짧은 유효기간을 가지며 만료 전에 갱신해야 합니다.
백엔드는 timestamp, origin 도메인, 상점의 프론트엔드 제한을 검증합니다.
운영 환경에서는 항상 HTTPS를 사용하세요.

서버 측 관리 API가 필요하다면 API Key 모드.