coinboxPay — integración
Plataforma de pagos cripto. Cobrás con un link y un QR, el sistema detecta el pago on-chain, descuenta la comisión y reenvía al wallet que configuraste.
Base: https://coinboxpay.snotrasys.com
Auth: x-api-key: pc_live_... # no es Bearer
Modos: test y live
El prefijo de la credencial dice en qué entorno opera:
| Prefijo | Entorno |
|---|---|
pc_test_ | Test. Faucet disponible, sin plata real. |
pc_live_ | Producción. |
Una key de test no puede tocar datos live, ni al revés: el prefijo y el modo de la
app tienen que coincidir o la API responde 401.
Onboarding, entero por API
# 1. Una persona emite una credencial de organización desde el dashboard (una sola vez)
POST /orgs/:orgId/api-keys
{ "name": "onboarding", "permissions": ["apps:create"], "mode": "TEST" }
# -> { rawKey: "pc_test_...", ... } la rawKey se muestra UNA sola vez
# 2. Con esa credencial se crean apps, sin sesión humana ni email verificado
POST /orgs/:orgId/apps/by-key
x-api-key: pc_test_...
{ "name": "mi-app", "chain": "base", "acceptedTokens": ["USDT"] }
# La app nace en modo TEST.
# 3. Fondear una address de prueba
POST /v1/test/fund
{ "chain": "base", "token": "0x...", "to": "0x...", "amount": "1000000" }
Cobrar
POST /v1/payment-requests
x-api-key: pc_test_...
{
"reference_id": "orden-123",
"asset_alias": "USDT",
"chain": "base",
"expected_amount": "100000000",
"callback_url": "https://tu-app.com/webhooks/coinboxpay"
}
Devuelve payment_address, expires_at y un id. Mandá al pagador a
/pay/:appId/:requestId, que muestra el QR y el estado en vivo.
Los montos van en la unidad mínima del token, siempre como string. Nunca number:
un entero grande no sobrevive a JSON.parse sin perder precisión, y esto es plata.
Qué pasa cuando llega el pago
Se configura por app, en Ajustes → Modo de cobro:
- Router (
FORWARD_ON_CONFIRMATION): se descuenta la comisión y el resto se reenvía a tusettlement_address. Comisión de lista: 0,5%. - Custodia (
MANUAL): la plata se queda en la address derivada de ese usuario. El saldo es el balance on-chain, consultable enGET /v1/balances/:reference_idy verificable por cualquiera en el explorer.
Casos de borde: pasan seguido
No hay banda de tolerancia. Un cobro se salda solo si recibido >= esperado.
La causa más común de faltante no es un error del pagador: es que su exchange le
descuenta la comisión de retiro — manda 100 y llegan 99,7. En ese caso la orden queda
abierta hasta expires_at, la página de pago muestra cuánto falta, y el pagador
completa sobre la misma address.
reason | Cuándo |
|---|---|
UNDERPAID | Llegó menos de lo pedido |
OVERPAID | Llegó de más. Se salda igual; el excedente lo decidís vos |
DELAYED | Llegó después de expirar |
MULTIPLE | Llegó con la orden ya saldada |
Los eventos traen reason y missing_amount. No hay devolución automática nunca.
Webhooks
Firmados con HMAC-SHA256 en el header x-webhook-signature, formato sha256=<hex>.
import { verifyWebhook } from '@coinboxpay/sdk';
// rawBody tiene que ser el cuerpo EXACTO recibido. JSON.parse + JSON.stringify
// reordena claves y cambia el hash: la verificación falla.
if (!verifyWebhook(rawBody, req.headers['x-webhook-signature'], secret)) {
return res.status(400).end();
}
Eventos: payment_request.cleared (con settlement: forwarded | custody | pending),
payment.forwarded (con fees como lista, no escalar), payment_request.underpaid,
payment_request.overpaid.
Si una entrega falla, se puede reenviar desde el dashboard sin recrear el cobro.
Retirar
POST /v1/payouts
{ "reference_id": "wd-123", "to_address": "0x...", "amount": "50000000", "chain": "base" }
Por encima del umbral de aprobación configurado, el retiro requiere que otra persona lo apruebe.
SDK
npm install @coinboxpay/sdk
import { CoinboxPay, isPaymentForwarded } from '@coinboxpay/sdk';
const cbp = new CoinboxPay({ apiKey: process.env.COINBOXPAY_KEY! });
const cobro = await cbp.paymentRequests.create({
reference_id: 'orden-123',
asset_alias: 'USDT',
chain: 'base',
expected_amount: '100000000',
});
Los errores llegan como CoinboxPayError con status y code. Ramificá por code: la
redacción del mensaje cambia, el código no.