初級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、App 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 APIs で対応しています。
注文ステータス照会	✅	Public Key に紐づく加盟店の注文のみ照会できます。
管理系 API 全般	❌	Public Key モードではブラウザに公開されません。
ブラウザで API Key を公開	❌	絶対に行わないでください。Public Key のみ使用してください。

セキュリティ

Public Key は公開可能ですが、ホワイトリスト内のドメインでのみ動作します。
Session Token は短期有効で、有効期限前に更新する必要があります。
バックエンドは timestamp、Origin ドメイン、加盟店のフロントエンド制限を検証します。
本番環境では必ず HTTPS を使用してください。

サーバー側の管理 API が必要な場合は API Key モード.