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; ajustaexpiresMinentre 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.pendingcuando se ve el pago,invoice.paidcuando la red lo ha confirmado. Comprueba la firma y libera el pedido coninvoice.paid(cómo verificar los webhooks). - Mientras el cliente está en tu página, tu servidor también puede consultar
GET /api/v1/invoices/:idpara obtenerstatus(por ejemplo NEW, PENDING, PAID o EXPIRED),amountReceived,confirmationsyrequiredConfirmations. 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: truela dirección esTEST-MODE-DO-NOT-SEND-FUNDS, yPOST /api/v1/invoices/:id/simulatesimula 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
}