# 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 ```bash # 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 ```bash 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**. | `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=`. ```ts 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 ```bash 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 ```bash npm install @coinboxpay/sdk ``` ```ts 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.