Ir al contenido
ArionPay

Base de conocimiento · 6 min de lectura

API de marca blanca: el pago en tu propio sitio

Crea una factura con la moneda ya elegida, muestra el importe exacto y la dirección en tu propia página de pago, y sigue el pago con la API y los webhooks.

API de marca blanca: el pago en tu propio sitio

Cuándo usarla

Normalmente envías al cliente a invoice_url, la página de pago de ArionPay. Con la API de marca blanca, en cambio, es tu propia página la que muestra el pago: tu diseño, tu idioma, tu dominio, y el cliente nunca sale de tu sitio. El dinero sigue yendo directamente a tu propia billetera, y ArionPay sigue vigilando la blockchain y te avisa cuando se paga la factura. La comisión es la misma: 0.5% por pago. Consulta la página de marca blanca para ver un resumen.

1. Crea la factura con la moneda elegida

Primero, deja que el cliente elija una moneda en tu página. Después envía POST /api/v1/invoices desde tu servidor con asset configurado con esa moneda, por ejemplo USDT_TRC20, USDC_POLYGON o BTC. Los códigos que puede usar tu tienda aparecen en GET /api/v1/currencies. La respuesta ya trae todo lo que necesita tu página:

  • data.amount_crypto: el importe exacto que hay que enviar. Sus últimas cifras nos indican a qué factura corresponde un pago.
  • data.address: la dirección a la que pagar. En todas las redes es la dirección principal de tu billetera.
  • data.expires_at: cuándo vence la factura (30 minutos de forma predeterminada; ajusta expiresMin entre 5 y 1440).
  • data.id: el id de la factura, para los pasos siguientes.

Si la dirección no se puede asignar por un motivo temporal, recibes el estado 503. Sin un idempotencyKey, esa factura se cancela y un reintento crea una nueva. Con un idempotencyKey, la factura se conserva: reintenta con la misma clave y se completa.

2. Muéstralo en tu página

  • Muestra el importe completo con todas sus cifras y un botón para copiarlo. Un importe redondeado no se puede asignar automáticamente: pasa a Payment Radar y espera tu decisión.
  • Muestra la dirección, un código QR y la red, por ejemplo “USDT en TRON (TRC-20)”.
  • Muestra el tiempo que queda hasta expires_at.
  • Añade un enlace a invoice_url, como “¿Algún problema? Paga en la página de ArionPay”. Allí el cliente encuentra botones para apps de billetera, 9 idiomas y el formulario para indicar un ID de transacción.

3. Sigue el pago

  • Webhooks: invoice.pending cuando se ve el pago, invoice.paid cuando la red lo ha confirmado. Comprueba la firma y libera el pedido con invoice.paid (cómo verificar los webhooks).
  • Mientras el cliente está en tu página, tu servidor también puede consultar GET /api/v1/invoices/:id para obtener status (por ejemplo NEW, PENDING, PAID o EXPIRED), amountReceived, confirmations y requiredConfirmations. La consulta también le indica a ArionPay que alguien está esperando, así que el pago se comprueba con más frecuencia.

Mantenlo seguro y dentro de los límites

  • Llama a la API solo desde tu servidor. El secreto de API nunca debe llegar al navegador: tu página consulta a tu propio servidor, y tu servidor consulta a ArionPay.
  • Consulta cada factura abierta aproximadamente cada 10 segundos, y deja de hacerlo cuando el cliente salga de la página. Cada solicitud firmada se acepta una sola vez, y un servidor puede enviar unas 120 solicitudes por minuto (300 por minuto por tienda).
  • Prueba primero: con test: true la dirección es TEST-MODE-DO-NOT-SEND-FUNDS, y POST /api/v1/invoices/:id/simulate simula un pago. Consulta el modo de prueba.
// Node.js 18+, as an ES module (for example checkout.mjs), on your server only:
// the API secret must never reach the browser
import crypto from 'node:crypto';

async function arionpay(method, path, payload) {
  const ts = Math.floor(Date.now() / 1000);
  const body = payload ? JSON.stringify(payload) : '';
  // POST is signed over "timestamp.body", GET over "timestamp.GET path"
  const signed = method === 'GET' ? `${ts}.GET ${path}` : `${ts}.${body}`;
  const signature = crypto.createHmac('sha256', process.env.ARIONPAY_API_SECRET).update(signed).digest('hex');
  // ARIONPAY_BASE_URL: the API address from the docs
  const res = await fetch(process.env.ARIONPAY_BASE_URL + path, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.ARIONPAY_API_KEY, // pk_...
      'x-timestamp': String(ts),
      'x-signature': signature,
    },
    body: payload ? body : undefined,
  });
  if (!res.ok) throw new Error(`ArionPay answered ${res.status}`);
  return res.json();
}

// 1. The customer chose USDT on TRON on your page
const { data } = await arionpay('POST', '/api/v1/invoices', {
  amount: '49.00', currency: 'USD', orderId: 'ORD-1042', asset: 'USDT_TRC20',
});
// show data.amount_crypto, data.address and data.expires_at; keep data.id

// 2. While the customer waits (about every 10 seconds), or wait for the invoice.paid webhook
const invoice = await arionpay('GET', `/api/v1/invoices/${data.id}`);
if (invoice.status === 'PAID') {
  // release the order
}