coinboxPay

Guía de integración

/skill.md

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:

PrefijoEntorno
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 tu settlement_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 en GET /v1/balances/:reference_id y 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.

reasonCuándo
UNDERPAIDLlegó menos de lo pedido
OVERPAIDLlegó de más. Se salda igual; el excedente lo decidís vos
DELAYEDLlegó después de expirar
MULTIPLELlegó 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.