Iniciante10 min de leitura

Modo Public Key

O modo Public Key foi criado para integrações no navegador. O frontend usa a public_key para obter um token curto, criar pedidos e consultar status sem expor a API Key.

Fluxo de integração

Gere uma Public Key no painel do comerciante e ative a integração frontend.
Configure a lista de domínios permitidos.
O navegador chama /api/v1/sdk/token com a Public Key.
Use o token de sessão retornado para chamar /api/v1/sdk/orders.
Redirecione para payment_url ou consulte o status do pedido.

O modo Public Key atual não exige assinatura de parâmetros no frontend. Recomendamos usar o SDK JavaScript ou chamar manualmente as APIs de token e pedido.

Obter a Public Key

Entre no painel PonponPay.
Abra a página "Frontend Integration".
Ative a integração frontend.
Gere e copie a Public Key no formato pub_xxx.

Lista de domínios permitidos

A Public Key só pode ser usada a partir de domínios permitidos. O backend valida Origin ou Referer.

Permita localhost apenas em desenvolvimento.
Use domínios reais em produção.
Subdomínios wildcard como *.example.com são suportados.

Se a página abrir em iframe, WebView ou camada intermediária, o Origin pode não ser enviado de forma consistente. Valide Origin e Referer antes do lançamento.

Recomendado: SDK JavaScript

npm install @ponponpay/sdk

Inicializar cliente

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

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

Criar pedido

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;

Consultar status

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

Para mais detalhes do SDK, veja a seção JavaScript SDK ou o README do repositório.

Integração manual da API

1. Obter token curto

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. Criar pedido com o 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. Consultar status do pedido

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

Limites de capacidade

Capacidade	Suportado	Descrição
Criar pedido	✅	Suportado pelas APIs de pedido com token do SDK.
Consultar status	✅	Apenas para pedidos do comerciante associado à Public Key.
APIs administrativas completas	❌	Não expostas ao navegador no modo Public Key.
Expor API Key no navegador	❌	Nunca faça isso. Use apenas Public Key.

Notas de segurança

A Public Key pode ser pública, mas só funciona em domínios permitidos.
Tokens de sessão são curtos e devem ser renovados antes de expirar.
O backend valida timestamp, domínio de origem e limites frontend.
Use sempre HTTPS em produção.

Se precisar de APIs de gestão no servidor, use modo API Key.