Начинающий10 мин чтения

Режим Public Key

Режим Public Key предназначен для браузерной интеграции. Фронтенд использует public_key для получения короткоживущего session token, затем создает заказы и проверяет статус без раскрытия API Key.

Поток интеграции

Создайте Public Key в кабинете мерчанта и включите frontend-интеграцию.
Настройте белый список доменов.
Браузер вызывает /api/v1/sdk/token с Public Key.
Используйте полученный session token для вызова /api/v1/sdk/orders.
Перенаправьте пользователя на payment_url или опрашивайте статус заказа.

Текущий режим Public Key не требует подписи параметров на фронтенде. Рекомендуется использовать JavaScript SDK или вручную вызывать API token и orders.

Получить Public Key

Войдите в панель PonponPay.
Откройте страницу "Frontend Integration".
Включите frontend-интеграцию.
Создайте и скопируйте Public Key формата pub_xxx.

Белый список доменов

Public Key можно использовать только с разрешенных доменов. Backend проверяет Origin или Referer.

Разрешайте localhost только для разработки.
В production используйте реальные домены.
Поддерживаются wildcard-поддомены, например *.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 APIs.
Проверка статуса	✅	Только для заказов мерчанта, связанного с Public Key.
Полные admin APIs	❌	Не доступны браузеру в режиме Public Key.
Раскрытие API Key в браузере	❌	Никогда не делайте этого. Используйте только Public Key.

Безопасность

Public Key может быть публичным, но работает только на разрешенных доменах.
Session tokens короткоживущие и должны обновляться до истечения.
Backend проверяет timestamp, origin домена и frontend-лимиты мерчанта.
Всегда используйте HTTPS в production.

Если нужны серверные management APIs, используйте режим API Key.