Principiante10 min de lectura

Modo Public Key

El modo Public Key está diseñado para integraciones en navegador. El frontend usa una public_key para obtener un token de sesión temporal, crear pedidos y consultar estados sin exponer una API Key.

Flujo de integración

Genera una Public Key en el panel del comercio y activa la integración frontend.
Configura la lista blanca de dominios permitidos.
El navegador llama a /api/v1/sdk/token con la Public Key.
Usa el token de sesión devuelto para llamar a /api/v1/sdk/orders.
Redirige al payment_url o consulta el estado del pedido.

El modo Public Key actual no requiere firmar parámetros en el frontend. Se recomienda usar el SDK JavaScript o llamar manualmente a las APIs de token y pedido.

Obtener la Public Key

Inicia sesión en el panel de PonponPay.
Abre la página "Frontend Integration".
Activa la integración frontend.
Genera y copia la Public Key con formato pub_xxx.

Lista blanca de dominios

La Public Key solo puede usarse desde dominios autorizados. El backend valida el origen con Origin o Referer.

Permite localhost solo en desarrollo.
Usa dominios reales en producción.
Se admiten subdominios comodín como *.example.com.

Si la página se abre dentro de un iframe, WebView o capa intermedia, los encabezados Origin pueden no enviarse de forma estable. Valida Origin y Referer antes de producción.

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

Crear 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 estado

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

Para más detalles del SDK, consulta la sección JavaScript SDK o el README del repositorio.

Integración manual con API

1. Obtener un token temporal

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. Crear un pedido con el 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 el estado

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

Límites de capacidad

Capacidad	Soportado	Descripción
Crear pedido	✅	Disponible mediante las APIs de pedido con token del SDK.
Consultar estado	✅	Solo para pedidos del comercio asociado a la Public Key.
APIs administrativas completas	❌	No se exponen al navegador en modo Public Key.
Exponer API Key en navegador	❌	Nunca expongas la API Key. Usa solo Public Key.

Notas de seguridad

La Public Key puede ser pública, pero solo funciona en dominios autorizados.
Los tokens de sesión son temporales y deben renovarse antes de expirar.
El backend valida timestamp, dominio de origen y límites frontend del comercio.
Usa siempre HTTPS en producción.

Si necesitas APIs de gestión del servidor, usa modo API Key.