Recargar saldo (TopUp Cripto)

POST /api/topupCopy Anchor Link

Crea una transacción de depósito y genera una billetera cripto (BTC, USDT, ETH, etc.) en la red elegida. Cuando se envíen fondos a esa billetera, el proveedor cripto notificará a QvaPay, QvaPay acreditará el saldo en USD a la cuenta y, si se proporcionó webhook_url, disparará un webhook saliente (ver TopUp Webhook).

AutenticaciónCopy Anchor Link

Acepta dos modos:

• Bearer token de usuario (Authorization: Bearer <token>) — caso típico de un usuario recargando su propio saldo. El TOPUP queda asociado a app_id = 0 y los webhooks (si se configura webhook_url) se enviarán sin firma.
• Credenciales de App (app-id + app-secret en headers) — pensado para integraciones merchant que quieran recibir webhooks firmados con HMAC.

Rate limitCopy Anchor Link

5 requests por minuto por usuario (ArcJet, token bucket). Usuarios vip quedan exentos.

RequestCopy Anchor Link

{
  "amount": 100,
  "pay_method": "BTC",
  "webhook_url": "https://mitienda.com/webhook/topup"
}

ParámetrosCopy Anchor Link

ResponseCopy Anchor Link

{
  "result": "OK",
  "data": {
    "wallet": "1A1z7agoat8Hs3zNx2EN1234567890",
    "memo": null,
    "coin": "BTC",
    "value": 0.0025,
    "price": 43000,
    "transaction_id": "1234567",
    "transaction_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "transaction_url": "https://pay.qvapay.com/?token=N2M5ZTY2NzktNz...",
    "payment_id": "abc123",
    "redirect_url": null
  }
}

Campos de respuestaCopy Anchor Link

Cómo se recibe cada monedaCopy Anchor Link

QvaPay elige el camino según pay_method; la forma de la respuesta es siempre la misma:

• Dirección de depósito propia (BTC, LTC, TRX, USDT, USDC, ETH, SOL, TON, BNB, MATIC, ARB y otras): wallet es una dirección de un solo uso para este depósito.
• Lightning (BTCLN): wallet es una factura Lightning (bolt11) por exactamente value BTC; caduca en 1 hora. Se acredita el amount en cuanto se paga.
• Monedas convertidas al recibirse (DOGE, ZEC, ATOM, BCH, AVAX en C-Chain, ADA, VET, XTZ, DASH, ALGO, SUI, XRP, LINK, SHIB y CAKE en BSC, DAI en Ethereum, TRUMP en Solana, HMSTR y NOT en TON, USDCALGO, RVN): ver la sección siguiente.

Monedas convertidas al recibirseCopy Anchor Link

Estas monedas se convierten automáticamente a USD al llegar, a la tasa de mercado del momento (tasa flotante):

• value es una estimación de cuánto enviar para que se acrediten amount USD. Se acredita lo que realmente resulte de la conversión, menos el fee de la moneda: si se envía de más se acredita el excedente (con el recargo de sobrepago) y si se envía de menos se acredita lo recibido (is_partial: true en el webhook).
• La acreditación tarda lo que tarde la conversión (normalmente 5–30 minutos tras las confirmaciones de la red de origen). El webhook llega igual que en el resto de depósitos.
• Si memo viene informado (p. ej. ATOM, USDCALGO, o el destination tag de XRP), el envío debe llevarlo.
• Cada moneda tiene un mínimo por debajo del cual la conversión no sale (o cuesta demasiado: algunas redes tienen un coste fijo por envío). La respuesta lo indica con 400 BELOW_MIN y min_usd, que puede cambiar con el mercado.

Atestación de cuentas US personCopy Anchor Link

Una cuenta US person (se declaró persona estadounidense, verificó con un documento emitido en EE. UU. o sus territorios, o tiene SSN/ITIN en su ficha) tiene que enviar el objeto compliance en todo depósito, sea cripto, bancario o de cualquier otro método, y desde cualquier canal (web, apps móviles, apps de comercio y clientes API). Si falta o no es válido, la respuesta es 400 con code: "US_PERSON_ATTESTATION_REQUIRED". Vigente desde el 29 sep 2026. El formato y los códigos (P-1…P-4) son los mismos de la sección siguiente.

Atestación en depósitos bancariosCopy Anchor Link

Un depósito por transferencia bancaria (pay_method: "BANK") entra en la cuenta bancaria estadounidense de QvaPay, por lo que el cliente declara el propósito del fondeo con el mismo objeto compliance que usan los retiros:

{
  "amount": 500,
  "pay_method": "BANK",
  "compliance": {
    "purposeCode": "P-1",
    "attestations": {
      "notProhibitedOfficial": true,
      "notProhibitedPartyMember": true,
      "notRestrictedList": true,
      "lawfulPurpose": true
    }
  }
}

Códigos válidos en este ámbito: P-1 (remesa familiar), P-2 (pago al sector privado), P-3 (donativo), P-4 (recarga / telecomunicaciones). Las cuatro casillas de attestations deben ser true.

La exigencia se despliega por canal: el navegador web recibe 400 si falta; las apps móviles (x-qvapay-client-platform: ios|android), las apps de comercio (app-id) y los clientes API con Bearer propio pueden omitirla hoy (se registra la ausencia) y deberían enviarla desde ya. Los depósitos cripto no la requieren, salvo que la cuenta sea US person (ver arriba).

ErroresCopy Anchor Link

Notas importantesCopy Anchor Link

• BANK solo para cuentas elegibles: los depósitos por transferencia bancaria están disponibles para cuentas VIP, cuentas con TrustScore de 85 o más, y cuentas empresa (cuenta de tipo empresa o titular de una empresa registrada y aprobada en Ajustes) — la misma regla que PAYPAL. Cualquier otra cuenta recibe 403 con code: "COMPANY_ACCOUNT_REQUIRED" (el código se mantiene por compatibilidad); el wizard de depósito no muestra el método a esas cuentas.
• CARD (depósito con tarjeta): misma elegibilidad que PAYPAL y, además, la petición debe venir desde fuera de Cuba. Monto entre min_in y max_in de la moneda. El tope diario cuenta intentos (cada depósito creado, se pague o no): 3 por día en cuentas personales, que depositan a su propio saldo. Una cuenta empresa puede cobrar a sus clientes con tarjeta por este método (crea el depósito con webhook_url y envía al cliente a transaction_url; el webhook de TopUp llega al acreditarse), por lo que tiene un tope diario propio y mucho mayor. Al superarlo, 429 con code: "CARD_DAILY_LIMIT". El contracargo de una tarjeta de cliente se descuenta del saldo de la cuenta que cobró.
• Nivel «SSN verificado» (solo apps móviles): una persona de EE. UU. GOLD que verificó su SSN (ver Verificación del SSN) puede depositar con CARD y PAYPAL sin ser VIP, TrustScore ≥ 85 ni empresa, con un tope combinado de $500 sobre lo cobrado en los últimos 30 días (ventana rodante). Solo desde x-qvapay-client-platform: ios|android. Antes de ofrecer el método, consulta GET /user/deposit-eligibility, que devuelve el nivel (full sin tope, ssn con tope) y el cupo restante.
• Cap al monto solicitado: si se envía cripto que excede el amount solicitado, QvaPay solo acredita el amount y el excedente queda en cuenta interna. Pide el monto exacto que indica value en la respuesta.
• Subpago: si se envía menos del solicitado, se acredita lo que valga en USD después del fee. El webhook indicará is_partial: true (ver TopUp Webhook).
• Idempotencia del webhook: el mismo transaction_uuid puede llegar 1–3 veces al webhook (política de reintentos). Tu endpoint debe ser idempotente.