Abonnements et paiements automatiques
Un commerçant peut demander à un utilisateur Heth.me d'autoriser des paiements récurrents. Le payeur vérifie et signe les conditions avec son HethWallet habituel déverrouillé. Aucun compte email ni accès séparé au Customer Portal n'est nécessaire. Les paiements débitent le solde du compte Heth dans la devise et le réseau convenus.
Pour le payeur
- Ouvrez Paramètres → Abonnements et paiements automatiques. Les nouvelles demandes sont séparées des abonnements existants.
- Vérifiez le commerçant, le montant par paiement, la devise/le réseau et la période. Le lien de confirmation ouvre le même écran. Un portefeuille verrouillé demande son PIN habituel, puis revient à la demande.
- Choisissez Confirmer l’abonnement ou Refuser. Ouvrir un lien ou recevoir une notification n'accorde aucune autorisation.
- Après accord, le premier paiement est planifié. La liste affiche le montant, la période et la date du prochain prélèvement ; en cas de nouvelle tentative après échec, elle affiche sa date.
- Révoquez l'abonnement pour arrêter les futurs prélèvements. Cela ne rembourse pas les paiements déjà effectués.
La confirmation enregistre l'accord et planifie un paiement ; elle ne signifie pas que le paiement a réussi. Vérifiez le statut de la transaction. Le solde doit être suffisant au moment de l'exécution.
Notification des nouvelles demandes
Pour un payeur identifié, le serveur envoie une notification de demande d’abonnement aux appareils enregistrés pour les push, avec le lien /subscriptions/confirm/<request_id>?env=<env>. Une entrée est aussi conservée sous la cloche des notifications, même si aucun appareil ne peut recevoir le push. Les demandes en attente restent accessibles dans Paramètres → Abonnements et paiements automatiques.
Les PWA installées utilisent le web push. Heth.me pour iOS et Android, à partir de la version 1.0.0 (build 5), utilise les notifications système. Activez les notifications dans le portefeuille et autorisez-les dans les réglages de l’appareil. Toucher une demande d’abonnement ouvre son écran de confirmation ; un portefeuille verrouillé demande d’abord le PIN habituel ou une clé d’accès disponible. Recevoir ou ouvrir une notification n’autorise pas l’abonnement. Si la notification n’arrive pas, ouvrez les demandes en attente ou le lien fourni par le commerçant.
Pour le commerçant
Dans HethWallet, ouvrez Business → Abonnements et paiements automatiques. Indiquez l'adresse du portefeuille, le @username ou le numéro de carte Heth du payeur, le nom de l'abonnement, le montant par paiement, la devise/le réseau et la période. Envoyez la demande et copiez son lien de confirmation. Vous pouvez consulter vos demandes et annuler celles qui sont encore en attente.
L'opérateur doit activer les abonnements Heth pour l'organisation et configurer un circuit de paiement fonctionnel. Créer une demande n'autorise aucun débit.
Créer une demande par API
Utilisez la clé API du commerçant ou sa session Bearer partenaire habituelle. Sur app.heth.me, l'organisation est déterminée par le domaine. Une clé en lecture seule ne peut ni créer ni annuler de demande.
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"
}'
| Champ | Description | Type | Exemple |
|---|---|---|---|
request_id | UUID unique idempotent. Réutilisez-le avec les mêmes conditions pour réessayer la même demande. | String | b56b2c66-4ae5-4cb9-92ea-7a3297b72b55 |
payer | Adresse du portefeuille, nom d'utilisateur ou numéro de carte Heth. | String | @alice |
description | Nom de l'abonnement : 1–250 caractères sans saut de ligne. | String | Monthly membership |
amount | Entier positif dans les unités minimales du token. Pour USDT à 6 décimales, 1000000 signifie 1 USDT. | String | 1000000 |
currency, network | Paire token/réseau activée dans l'environnement choisi. Réseaux : ETH, TRX, BASE. | String | USDT, ETH |
interval | daily, weekly, monthly ou yearly. | String | monthly |
period | Nombre d'intervalles de 1 à 365 ; valeur par défaut 1. | Number | 1 |
env | prod (par défaut). Conservez cette valeur à l’ouverture et à la confirmation de la demande. | String | prod |
HTTP 201 renvoie directement la demande, dont id, status, amount_decimals, confirm_url, expires_at, subscription_id et next_charge_at. Les demandes expirent après sept jours. La création réussie ne révèle pas si le payeur indiqué existe ; seul le destinataire réel peut lire et approuver la demande.
Opérations API
Tous les chemins ci-dessous commencent par /api/v1. Les opérations du commerçant nécessitent sa clé API ou sa session Bearer partenaire.
| Méthode et chemin | Fonction |
|---|---|
POST /heth/subscription-requests | Créer une demande. |
GET /heth/subscription-requests?env=prod&limit=50 | Lister les demandes du commerçant dans data et total. |
POST /heth/subscription-requests/:id/cancel | Annuler une demande en attente ; corps {"env":"prod"}. |
Pour la première page, omettez page. Utilisez page=1 pour la suivante, puis incrémentez la valeur ; limit fixe la taille des pages.
Les opérations du portefeuille nécessitent la session Bearer habituelle du payeur. La clé API du commerçant ne peut pas approuver à sa place.
| Méthode et chemin | Fonction |
|---|---|
GET /heth/subscriptions?env=prod&limit=50 | Abonnements du payeur dans data/total, demandes en attente dans requests/requests_total. |
GET /heth/subscription-requests/:id?env=prod | Lire la demande reçue et le message canonique message à signer. |
POST /heth/subscription-requests/:id/confirm | Après vérification des conditions exactes, approuver avec {"signature":"<wallet signature>","env":"prod"}. |
POST /heth/subscription-requests/:id/reject | Refuser ; corps {"env":"prod"}. |
POST /heth/subscriptions/:id/revoke-mandate | Arrêter les futurs prélèvements ; corps {"env":"prod"}. |
La signature lie le commerçant, le payeur, l'organisation, l'environnement, la description, le montant et son échelle, la devise/le réseau, l'intervalle et la période, la règle du premier paiement, le nonce et l'expiration. Modifier les conditions exige une nouvelle demande et un nouvel accord. Réessayer une confirmation ou un paiement planifié ne peut pas débiter deux fois la même période. Les dates API sans fuseau sont en UTC ; l'application affiche l'heure locale de l'appareil.
Statuts et erreurs
Statuts de demande : pending, signed, rejected, expired. Une demande approuvée contient un subscription_id. Suivez l'exécution réelle des paiements avec l'API des transactions et les webhooks configurés.
401 indique une authentification absente/invalide ; 403, des abonnements désactivés ou une clé API en lecture seule. Une demande inaccessible renvoie 404. 422 indique des conditions invalides, un UUID réutilisé avec d'autres conditions, une signature invalide ou une demande expirée/fermée. Le commerçant ne peut pas modifier les conditions signées d'un abonnement actif sans nouvel accord du payeur.