Suscripciones y pago automático
Una tienda puede pedirle a un usuario de Heth.me que apruebe pagos recurrentes. El pagador revisa y firma las condiciones con su HethWallet ordinaria desbloqueada. No se necesita una cuenta de correo electrónico separada ni iniciar sesión en el Portal del Cliente. Los pagos cargan el saldo de la cuenta Heth en la moneda y red acordadas.
Para el pagador
- Abra Configuración → Suscripciones y pago automático. Las nuevas solicitudes aparecen por separado de las suscripciones existentes.
- Abra una solicitud y verifique la tienda, el monto por pago, la moneda/red y el período de facturación. Un enlace de confirmación abre la misma pantalla. Una billetera bloqueada solicita su PIN habitual y vuelve a la solicitud.
- Elija Habilitar suscripción o Rechazar. Abrir un enlace o recibir una notificación nunca aprueba una suscripción.
- Después de la aprobación, se programa el primer pago. La lista muestra el monto, período y próxima fecha de pago; al volver a intentar un pago fallido, muestra la hora del próximo reintento.
- Revocar la suscripción para detener futuros cargos. La revocación no reembolsa los pagos completados.
La aprobación registra el consentimiento y programa un pago; no significa que el pago se haya realizado correctamente. Verifique el estado de la transacción. El saldo debe ser suficiente cuando se ejecuta un pago.
Cómo se anuncian las nuevas solicitudes
Para un pagador reconocido, el servidor envía una solicitud de suscripción a los dispositivos registrados, con un enlace a /subscriptions/confirm/<request_id>?env=<env>. También se guarda una entrada en la campana de notificación, incluso cuando ningún dispositivo puede recibir la notificación. Las solicitudes pendientes permanecen disponibles en Configuración → Suscripciones y pago automático.
Las PWA instaladas utilizan web push. Heth.me para iOS y Android, a partir de la versión 1.0.0 (compilación 5), utiliza notificaciones del sistema. Habilite las notificaciones en la billetera y permítalas en la configuración de su dispositivo. Al tocar una solicitud de suscripción, se abre su pantalla de confirmación; una billetera bloqueada primero solicita la PIN habitual o la clave de acceso disponible. Recibir o abrir una notificación no aprueba la suscripción. Si no llega una notificación, abre la lista de solicitudes pendientes o el enlace de confirmación de la tienda.
Para la tienda
En HethWallet, abra Negocios → Suscripciones y pago automático. Ingrese la dirección de la billetera del pagador, @username o el número de tarjeta Heth, el nombre de la suscripción, el monto por pago, la moneda/red y el período. Envíe la solicitud y luego copie su enlace de confirmación. Puede enumerar sus solicitudes y cancelar una solicitud mientras aún está pendiente.
El operador debe habilitar las suscripciones Heth para la organización y configurar una ruta de pago funcional. Crear una solicitud no autoriza un débito.
Crear una solicitud a través del API
Utilice la clave API de la tienda o su sesión portadora de socio ordinario. En app.heth.me, la organización se resuelve desde el host. Una clave de solo lectura no puede crear ni cancelar solicitudes.
curl -X POST 'https://app.heth.me/api/v1/heth/subscription-requests' \
-H "x-api-key: $HETH_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"request_id": "b56b2c66-4ae5-4cb9-92ea-7a3297b72b55",
"payer": "@alice",
"description": "Monthly membership",
"amount": "1000000",
"currency": "USDT",
"network": "ETH",
"interval": "monthly",
"period": 1,
"env": "prod"
}'
| Campo | Descripción | Tipo | Ejemplo |
|---|---|---|---|
request_id | Único idempotente UUID. Reutilícelo con términos idénticos cuando vuelva a intentar la misma solicitud. | String | b56b2c66-4ae5-4cb9-92ea-7a3297b72b55 |
payer | Dirección de billetera, nombre de usuario o número de tarjeta Heth. | String | @alice |
description | Nombre de la suscripción, caracteres 1–250 sin saltos de línea. | String | Monthly membership |
amount | Entero positivo en unidades menores simbólicas. Para 6- decimal USDT, 1000000 significa 1 USDT. | String | 1000000 |
currency, network | Par de token/red habilitado para el cuenta. Redes: ETH, TRX, BASE. | String | USDT, ETH |
interval | daily, weekly, monthly o yearly. | String | monthly |
period | Número de intervalos, 1–365; predeterminado 1. | Number | 1 |
env | prod (predeterminado). Conserve este valor al abrir y confirmar la solicitud. | String | prod |
HTTP 201 devuelve la solicitud directamente, incluyendo id, status, amount_decimals, confirm_url, expires_at, subscription_id y next_charge_at. Las solicitudes caducan después de siete días. Una creación exitosa no revela si el pagador suministrado existe; sólo el destinatario real puede leer y aprobar la solicitud.
Operaciones API
Todas las rutas siguientes comienzan con /api/v1. Las operaciones de la tienda requieren la clave API de la tienda o la sesión de portador del socio.
| Método y camino | Propósito |
|---|---|
POST /heth/subscription-requests | Crea una solicitud. |
GET /heth/subscription-requests?env=prod&limit=50 | Enumere las solicitudes de la tienda en data y total. |
POST /heth/subscription-requests/:id/cancel | Cancelar una solicitud pendiente; cuerpo {"env":"prod"}. |
Para la primera página, omita page. Utilice page=1 para la página siguiente y luego increméntelo; limit controla el tamaño de la página.
Las operaciones de billetera requieren la sesión ordinaria de portador de billetera del pagador. La clave API de una tienda no puede aprobarse para el pagador.
| Método y camino | Propósito |
|---|---|
GET /heth/subscriptions?env=prod&limit=50 | Suscripciones propias en data/total, solicitudes pendientes en requests/requests_total. |
GET /heth/subscription-requests/:id?env=prod | Lea la solicitud dirigida y la firma canónica message. |
POST /heth/subscription-requests/:id/confirm | Aprobar con {"signature":"<wallet signature>","env":"prod"} después de revisar las condiciones exactas. |
POST /heth/subscription-requests/:id/reject | Rechazar; cuerpo {"env":"prod"}. |
POST /heth/subscriptions/:id/revoke-mandate | Detener cargos futuros; cuerpo {"env":"prod"}. |
La firma vincula la tienda, el pagador, la organización, la descripción, el monto y su escala, la moneda/red, el intervalo y el período, la regla del primer pago, el nonce y el vencimiento. Cambiar las condiciones requiere una nueva solicitud y un nuevo consentimiento. Reintentar la aprobación o un pago programado no puede debitar el mismo período dos veces. Las marcas de tiempo API sin un sufijo de zona horaria son UTC; la aplicación muestra la hora local del dispositivo.
Estados y errores
Los estados de solicitud son pending, signed, rejected y expired. Una solicitud aprobada tiene un subscription_id. Realice un seguimiento de la finalización del pago real a través de la transacción API y los webhooks configurados.
401 significa autenticación faltante/no válida; 403 significa que las suscripciones están deshabilitadas o que la clave API es de solo lectura. Una solicitud inaccesible devuelve 404. 422 indica términos no válidos, un UUID reutilizado con diferentes condiciones, una firma no válida o una solicitud caducada/cerrada. Una tienda no puede cambiar las condiciones firmadas de una suscripción activa sin el consentimiento del nuevo pagador.