Recargar saldo (TopUp Cripto)

Generar una billetera cripto para recibir un depósito en tu cuenta de QvaPay. Funciona tanto para usuarios recargando su propio saldo como para apps/merchants que integren depósitos.

`POST /api/topup`

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ón

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 limit

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

Request

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

Parámetros

Parámetro	Tipo	Requerido	Descripción
`amount`	number	Si	Monto en USD a recibir (mayor al `min_in` de la moneda, máximo 100,000)
`pay_method`	string	Si	Tick de la moneda (ej: `BTC`, `USDT`, `ETH`, `TRX`, `SOL`, `LTC`, `DOGE`, `BTCLN`...)
`webhook_url`	string	No	URL pública (HTTPS recomendado) donde QvaPay enviará la notificación al acreditarse el pago. Máx. 191 caracteres.
`fee_mode`	string	No	Solo depósitos con tarjeta (`CARD`). `on_top` (default): el fee se suma al cobro y se acredita el `amount` completo. `included`: se cobra exactamente el `amount` y se acredita el `amount` menos el fee.
`compliance`	object	No*	Atestación de propósito del fondeo. *Obligatoria para el navegador web en depósitos por transferencia bancaria (`BANK`); opcional (recomendada) para apps móviles, apps de comercio y clientes API. Ver Atestación en depósitos bancarios

Response

{
  "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 respuesta

Campo	Tipo	Descripción
`wallet`	string	Dirección de la billetera donde se debe enviar los fondos
`memo`	string \| null	Memo o tag (cuando aplica, ej. Stellar/TON)
`coin`	string	Tick de la moneda
`value`	number	Cantidad de cripto que se debe enviar para acreditar el `amount` solicitado en USD
`price`	number	Precio de la moneda en USD al momento de la cotización
`transaction_id`	string	ID numérico interno de la transacción (BigInt como string)
`transaction_uuid`	string	UUID único de la transacción — guárdalo para reconciliar contra el webhook
`transaction_url`	string	URL de pago corta de QvaPay (opcional para redirigir al usuario)
`payment_id`	string	ID interno del proveedor cripto
`redirect_url`	string \| null	URL de redirección si el proveedor lo provee (PayPal, etc.)

Proveedores cripto soportados

QvaPay rutea automáticamente a uno de estos proveedores según pay_method:

TronDealer: BTC, LTC, TRX, USDT, ETH, SOL, TON, MATIC, ARB y otras 30+ monedas.
QryptoMe: BTCLN, ADA, BCH, DOGE, XRP, XLM, XMR y similares.
NowPayments: BNB, CAKE, DASH, SHIB, DOT, PEPE y otras altcoins.

Atestación en depósitos bancarios

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.

Errores

Código	Descripción
`400`	Datos inválidos: `amount` fuera de rango, `pay_method` no soportado, `webhook_url` no válida
`400`	Depósito `BANK` desde el navegador sin el objeto `compliance`
`403`	`KYC_REQUIRED`: la cuenta no tiene verificación de identidad aprobada (`kyc_url` indica dónde completarla)
`401`	Credenciales de app o bearer token ausentes/inválidos
`429`	Rate limit excedido (más de 5 requests por minuto)
`500`	Error interno al crear la transacción o billetera

Notas importantes

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.

Recargar saldo (TopUp Cripto)

On this page