Skip to Content
QvaPay API
User

Lightning Address

Recibir sats en [email protected] desde cualquier wallet Lightning (LUD-16), activar y gestionar la dirección del usuario autenticado.

Cada usuario puede activar una Lightning Address con la forma [email protected]. Cualquier wallet Lightning del mundo (Phoenix, Wallet of Satoshi, Blink, Alby, Zeus, Breez…) puede pagarle a esa dirección y el pago se acredita al momento en el saldo de QvaPay en USD, al precio de BTC del momento, con la misma comisión que un depósito por Lightning (la vigente sale en fees.usd_pct de GET /user/lightning-address; las cuentas GOLD tienen la suya). Cuando la opción está disponible, el usuario puede elegir recibir en sats: entran sin conversión y sin comisión a su saldo de satoshis (satoshis).

La dirección implementa LUD-16 sobre LUD-06 (payRequest) y admite comentarios (LUD-12) de hasta 255 caracteres.

  • Quién puede activarla: toda cuenta con la verificación de identidad (KYC) aprobada, sea personal o de empresa, también las de US persons. No hay excepciones por rol ni por tipo de cuenta.
  • El nombre es fijo: por defecto es tu nombre de usuario en minúsculas y no cambia aunque cambies tu nombre de usuario. Si cambias el nombre de la dirección, la anterior deja de funcionar y queda reservada: nadie más puede usarla.
  • Límites (se ajustan sin aviso): un mínimo y un máximo por pago y un máximo por usuario en 24 horas. Los valores vigentes salen en limits de GET /user/lightning-address, y los montos que acepta la dirección en minSendable / maxSendable de la consulta LNURL.

GET /user/lightning-address

Estado de la Lightning Address del usuario y sus últimos cobros.

Autenticación

Bearer Token (Authorization: Bearer {token}).

Request

curl https://api.qvapay.com/user/lightning-address \
  -H "Authorization: Bearer {token}"
ParámetroTipoDescripción
pagenumberPágina de payments (20 por página). Opcional.

Response

{
  "data": {
    "visible": true,
    "available": true,
    "receiving": true,
    "reason_code": null,
    "message": null,
    "address": {
      "uuid": "0b9f3c1e-6a2d-4c5b-9e7f-2a1b3c4d5e6f",
      "name": "erich",
      "address": "[email protected]",
      "lnurl": "LNURL1DP68GURN8GHJ7AMHWUH8ZANPWPSHJTNRDAKJ7TNHV4KXCTTTDEHHWM30D3H82UNVWQHK2UNFVD5QNY3K9Z",
      "qr": "lightning:LNURL1DP68GURN8GHJ7AMHWUH8ZANPWPSHJTNRDAKJ7TNHV4KXCTTTDEHHWM30D3H82UNVWQHK2UNFVD5QNY3K9Z",
      "status": "active",
      "receive_as": "usd",
      "created_at": "2026-10-30T12:00:00.000Z"
    },
    "domain": "qvpay.me",
    "suggested_name": null,
    "renames_left": 2,
    "limits": { "min_usd": 0.1, "max_usd": 500, "daily_usd": 1000, "used_24h_usd": 14.61, "remaining_usd": 985.39 },
    "receive": { "as": "usd", "effective": "usd", "sats_available": true },
    "fees": { "usd_pct": 0.5, "sats_pct": 0 },
    "satoshis": 1250,
    "payments": [
      {
        "uuid": "6c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
        "address": "[email protected]",
        "sats": 21000,
        "credit_usd": "14.54",
        "credit_unit": "usd",
        "comment": "Gracias por el café",
        "paid_at": "2026-10-30T12:05:00.000Z",
        "transaction_uuid": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
      }
    ]
  }
}

Campos de respuesta

CampoTipoDescripción
data.visiblebooleanLa función está abierta para esta cuenta
data.availablebooleanLa cuenta cumple los requisitos para recibir
data.receivingbooleanHay una dirección activa que está recibiendo pagos
data.reason_codestring | nullPor qué no recibe: KYC, ROLE, DEPOSITS_DISABLED, PAUSED, BLOCKED, UNAVAILABLE, MODE_OFF, NOT_BETA…
data.messagestring | nullExplicación del motivo para mostrar al usuario
data.addressobject | nullLa dirección vigente, o null si no la ha activado
data.address.lnurlstringLa misma dirección como LNURL (LUD-01), en mayúsculas para el QR
data.address.qrstringValor recomendado para el QR (lightning: + LNURL)
data.address.statusstringactive, paused o blocked
data.address.receive_asstringusd o sats: cómo eligió recibir el usuario
data.domainstringDominio de las direcciones ({name}@{domain}), para mostrarlo junto al campo del nombre antes de activar
data.suggested_namestring | nullNombre propuesto para activar (tu nombre de usuario, si está libre)
data.renames_leftnumberCambios de nombre que quedan
data.limitsobjectLímites vigentes en USD y lo usado en las últimas 24 h. En sats rigen los mismos, por su equivalente en USD
data.receive.asstringusd o sats: lo que eligió el usuario
data.receive.effectivestringEn qué se acreditará un pago nuevo. Es usd aunque el usuario haya elegido sats si la opción no está disponible
data.receive.sats_availablebooleanSe puede elegir recibir en sats
data.fees.usd_pctnumberComisión (en %) de un cobro que entra en USD: la de depósito por Lightning, la de GOLD si la cuenta es GOLD
data.fees.sats_pctnumberComisión (en %) de un cobro que entra en sats: 0
data.satoshisnumberSaldo de satoshis del usuario
data.paymentsarrayCobros acreditados, más recientes primero. comment lo escribió quien pagó y no está verificado
data.payments[].credit_usdstringEn USD, lo que se acreditó al saldo, ya descontada la comisión. En sats, el equivalente en USD de los sats recibidos
data.payments[].credit_unitstringusd (se acreditó credit_usd al saldo) o sats (se acreditaron sats al saldo de satoshis, sin comisión)

POST /user/lightning-address

Activa, renombra, pausa o reanuda la dirección, o elige si los cobros entran en USD o en sats. Responde el mismo objeto que GET.

Autenticación

Bearer Token (Authorization: Bearer {token}). Requiere la verificación de identidad (KYC) aprobada.

Request

curl -X POST https://api.qvapay.com/user/lightning-address \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "action": "activate", "name": "erich" }'
CampoTipoDescripción
actionstringactivate, rename, pause, resume o receive
namestringNombre de la dirección. Opcional en activate (por defecto, tu nombre de usuario); obligatorio en rename. De 3 a 32 caracteres: letras minúsculas, números y . _ -, empezando y acabando en letra o número
receive_asstringCon action: "receive": usd o sats. Se aplica a los pagos nuevos; un pago en camino se acredita como estaba

Errores

Código HTTPcodeSignificado
400LN_NAME_INVALIDEl nombre no cumple el formato (problem: length, format o reserved)
403LN_ADDRESS_UNAVAILABLELa cuenta no puede recibir (reason_code y message explican por qué)
403KYC_REQUIREDLa cuenta no tiene la verificación de identidad aprobada
409LN_NAME_TAKENEl nombre no está disponible
409LN_RENAME_LIMITYa se usaron todos los cambios de nombre
409LN_ADDRESS_EXISTSYa hay una dirección activada (usa rename)
409LN_SATS_DISABLEDRecibir en sats no está disponible (volver a usd siempre se puede)
429Demasiadas solicitudes

Endpoints LNURL públicos

Los usa la wallet de quien paga; no llevan autenticación y responden con Access-Control-Allow-Origin: *.

GET https://qvpay.me/.well-known/lnurlp/{name}

Respuesta payRequest de LUD-06. Los montos van en millisatoshis y siempre son sats enteros (múltiplos de 1000).

{
  "tag": "payRequest",
  "callback": "https://www.qvapay.com/.well-known/lnurlp/erich/callback",
  "minSendable": 143000,
  "maxSendable": 714285000,
  "metadata": "[[\"text/plain\",\"Pago a erich en QvaPay\"],[\"text/identifier\",\"[email protected]\"]]",
  "commentAllowed": 255
}

[email protected] funciona igual que [email protected] (el tag se ignora).

GET {callback}?amount={msat}&comment={texto}

Devuelve la factura Lightning por exactamente amount msat, con description_hash = sha256 de metadata. La factura vence a los pocos minutos y el precio queda fijado durante ese tiempo.

{
  "pr": "lnbc210u1p...",
  "routes": [],
  "successAction": { "tag": "message", "message": "Pago enviado a [email protected]. ¡Gracias!" }
}

Errores LNURL

Siguen LUD-06: { "status": "ERROR", "reason": "…" }.

Código HTTPCuándo
404La dirección no existe (o se renombró)
200La dirección no puede recibir ahora, el monto está fuera de rango o no es un número entero de sats
429Demasiadas solicitudes

Notificación al recibir

Cuando un pago se acredita, el usuario recibe un email, un mensaje de Telegram (si lo tiene vinculado) y un push con data.type = "ln_address_received", data.transaction_uuid y data.unit (usd o sats). En el historial el cobro es una transacción con la descripción Lightning Address {name}@qvpay.me: {sats} sats. Si se acreditó en sats, la descripción acaba en (saldo en sats) y el importe de la transacción es el equivalente en USD: el saldo en USD no cambia.

Los sats recibidos se pueden usar como descuento en la tienda o retirar por Lightning con POST /withdraw usando source: "satoshis" y pay_method: "BTCLN".

Para enviarle dinero a otro usuario de QvaPay usa una transferencia: los retiros BTCLN a una Lightning Address de QvaPay (la dirección, su LNURL o una factura suya) se rechazan con 400 y code: "LN_SELF_PAY", en POST /withdraw y en POST /lightning/decode.