Configurer Waffo : checkout Next.js étape par étape
Waffo existe en deux variantes distinctes, et la configuration diffère entre elles. Ce tutoriel couvre les deux, car l'intégration d'Uncorne les prend en charge via le même contrat de paiement et de webhook. À la fin, vous aurez un achat sandbox qui accorde une licence.
Étape 0 : Savoir quel Waffo vous branchez
Waffo n'est pas un produit unique. Pancake est un checkout Merchant of Record mondial — voir la documentation Waffo Pancake. Acquiring est une passerelle d'acquisition d'Asie du Sud-Est avec webhooks signés en RSA — voir la documentation Waffo Acquiring. Un Merchant of Record absorbe la taxe de vente et la TVA pour vous ; le concept est expliqué dans l'aperçu du Merchant of Record. Choisissez Pancake, sauf si vous détenez déjà un contrat d'acquisition régional.

Étape 1 : Définir la variante et l'environnement
Réglez WAFFO_FLAVOR sur pancake ou acquiring. La valeur par défaut est pancake ; l'adaptateur change les points d'accès et la signature en conséquence. Définissez WAFFO_ENVIRONMENT=test pour chaque étape de développement. Passer en production avec l'environnement de test est la façon la plus courante de perdre un premier paiement — le checkout semble correct, mais aucun argent réel ne bouge et aucune licence n'est accordée.
Étape 2 : Rassembler les identifiants
Pour Pancake, il vous faut un WAFFO_STORE_SLUG (ou WAFFO_STORE_ID / WAFFO_MERCHANT_ID) et une WAFFO_PRIVATE_KEY. Pour Acquiring, il vous faut les champs du contrat marchand — WAFFO_ACQUIRING_MERCHANT_INFO, WAFFO_ACQUIRING_USER_INFO, WAFFO_ACQUIRING_PAYMENT_INFO, WAFFO_ACQUIRING_ORDER_CURRENCY et WAFFO_ACQUIRING_ORDER_DESCRIPTION — ainsi que la clé publique de webhook par environnement. Conservez-les dans .env.local, jamais dans le dépôt.
PAYMENT_PROVIDER=waffo
WAFFO_FLAVOR=pancake
WAFFO_ENVIRONMENT=test
WAFFO_STORE_SLUG=your-store
WAFFO_PRIVATE_KEY=sk_test_xxx
WAFFO_PRICE_ID_BUYOUT=price_buyout_test
WAFFO_PRICE_ID_CARE=price_care_test
Étape 3 : Créer les produits et les prix
Dans le tableau de bord Waffo, créez un produit unique pour Buyout et un produit récurrent pour Care, puis copiez leurs ids de prix dans WAFFO_PRICE_ID_BUYOUT et WAFFO_PRICE_ID_CARE. Pour une promo Black Friday, créez des ids de prix séparés et définissez WAFFO_PRICE_ID_BUYOUT_BF et WAFFO_PRICE_ID_CARE_BF. L'inférence du plan par le webhook reconnaît automatiquement les ids BF : la promo ne nécessite aucun changement de code.

Étape 4 : Configurer le webhook
Pointez Waffo vers votre point d'accès /api/payments/webhook/waffo. Pancake vérifie avec la clé publique RSA de la plateforme (WAFFO_WEBHOOK_PUBLIC_KEY, avec variantes test et production). Acquiring signe la requête en RSA et nécessite la même clé publique. Vérifiez toujours la signature côté serveur avant de faire confiance à la charge utile — ne l'ignorez jamais. Un point d'accès webhook qui accepte des événements non vérifiés permet à n'importe qui de forger une commande payée avec une seule requête curl.
Le gestionnaire doit faire trois choses : vérifier la signature, déduire le plan depuis l'id de prix, puis appeler l'octroi de licence de manière idempotente afin qu'un événement retenté ne délivre pas deux licences. Journalisez l'id de l'événement et l'id de prix ; ce journal est le premier endroit à consulter lorsqu'un paiement n'accorde pas l'accès.
export async function POST(req: Request) {
const raw = await req.text();
if (!verifyWaffoSignature(raw, req.headers)) {
return new Response("bad signature", { status: 400 });
}
const event = JSON.parse(raw);
const plan = inferPlanFromPriceId(event.price_id);
await grantLicence(event.customer, plan, event.id);
return new Response("ok");
}
Le gestionnaire de route Next.js App Router ci-dessus s'exécute sur le serveur, exactement là où la vérification de signature doit avoir lieu — jamais dans un composant client.
Étape 5 : Définir le fournisseur
Définissez PAYMENT_PROVIDER=waffo ainsi que les variables ci-dessus. Un appel de checkout résout le bon id de prix pour le plan actif, et le webhook accorde la licence en déduisant le plan depuis l'id de prix. Si aucun id de prix n'est configuré, le checkout revient en mode affichage — utile pour un aperçu, inutile pour générer du revenu.
Étape 6 : Lancer un test sandbox
Utilisez l'environnement de test et un achat test. Confirmez que le webhook se déclenche, que le plan est correctement déduit et que la clé de licence est émise. Testez ensuite le chemin d'échec : une signature non vérifiée doit être rejetée avec un 400. Ne passez en production qu'une fois un aller-retour sandbox réel au vert.

Dépannage de trois échecs courants
Si le checkout s'ouvre mais qu'aucune licence n'apparaît, l'id de prix est presque certainement erroné — comparez-le au journal du webhook. Si la vérification de signature échoue en test, vous utilisez la clé publique de production au lieu de celle de test. Si le plan est toujours Buyout, l'id de prix Care n'a jamais été copié dans l'environnement.
Changer de passerelle plus tard
Sur Uncorne, les cinq adaptateurs de fournisseurs partagent ce contrat : le même chemin de code fonctionne pour Creem, Stripe, PayPal et Lemon Squeezy — seules les variables d'environnement changent. Lisez le tutoriel de configuration Creem pour les étapes parallèles, ou la comparaison des passerelles pour choisir avant de vous engager.
Ce que fait réellement l'appel de checkout
Lorsqu'un visiteur clique sur Buyout ou Care, une server action lit l'offre active, résout l'id de prix correspondant et ouvre une session de checkout hébergée par Waffo. L'id de prix vient du serveur : un client ne peut donc pas modifier un paramètre d'URL pour acheter Care au prix de Buyout. La session porte une référence à votre identifiant utilisateur interne dans les metadata ; c'est cette référence qui dit au webhook quel compte créditer une fois le paiement confirmé.
Pancake et Acquiring : ce qui change vraiment
Les deux variantes partagent le contrat de checkout et de webhook, mais le chemin de signature diffère. Pancake vérifie la charge utile avec la clé publique RSA de la plateforme ; Acquiring signe chaque requête en RSA et attend la même clé publique de votre côté. Votre fonction de vérification doit donc prendre la variante en paramètre plutôt que de coder en dur une branche d'algorithme. Gardez une clé publique distincte pour le test et la production, et estampillez l'environnement dans chaque ligne de journal webhook — une entrée sans étiquette d'environnement est presque inutile pendant un incident.
Les événements de webhook qui méritent un journal
Waffo envoie des événements pour les paiements réussis, les remboursements et les litiges. Journalisez chacun avec trois champs : l'id de l'événement, l'id de prix et la référence client. Comme l'id de prix est dans le journal, vous pouvez répondre des mois plus tard à « quelle offre cette personne a-t-elle réellement achetée ? » sans deviner. Un événement de litige doit signaler la licence pour examen plutôt que la révoquer silencieusement — vous voulez qu'un humain lise les preuves avant de couper un client qui a payé.
L'idempotence n'est pas optionnelle
Waffo retente les livraisons de webhook lorsque votre point d'accès répond trop lentement. Si votre gestionnaire émet une licence avant d'accuser réception de l'événement, un appel de base de données lent peut accorder deux licences pour un seul achat. Stockez l'id de l'événement dans une colonne unique et traitez un doublon comme un no-op réussi. C'est la cause la plus fréquente des tickets « pourquoi ce client a-t-il deux sièges ? », et elle est invisible dans un test de chemin nominal.
Une matrice sandbox, pas un seul chemin heureux
Un achat réussi est une démo, pas un test. Avant de passer en production, exécutez cette courte matrice en mode test :
- Buyout avec l'id de prix standard — licence émise, offre correctement déduite.
- Care avec l'id de prix standard — offre récurrente active, date de renouvellement enregistrée.
- Id de prix BF avec la promo active — offre BF déduite, aucun changement de code.
- Un webhook rejoué avec le même id d'événement — aucune seconde licence, aucun doublon de débit.
- Une requête à la signature falsifiée — rejetée avec un 400 et journalisée.
La ligne 5 détecte une clé publique mal configurée. Un chemin nominal au vert avec une vérification de signature cassée est une faille de sécurité que vous venez de déployer.
Liste de contrôle avant production
Basculez WAFFO_ENVIRONMENT en production, remplacez par la clé privée réelle et la clé publique de webhook réelle, et pointez l'URL du webhook vers votre domaine de production en HTTPS. Faites ensuite un petit achat réel et suivez toute la chaîne : paiement, webhook, déduction de l'offre, licence. Gardez les ids de prix de test hors de la production — ils sont la cause la plus fréquente des tickets « ça marchait en staging ».
Pour aller plus loin
Le contrat à cinq adaptateurs signifie que ces habitudes opérationnelles se transposent directement. La comparaison des passerelles explique quand un Merchant of Record vaut ses frais, et le guide des passerelles de facturation couvre la décision plus large.
FAQ
Quelle variante Waffo utiliser ?+
Utilisez pancake pour un checkout Merchant of Record mondial. N'utilisez acquiring que si vous détenez déjà un contrat d'acquisition régional qui exige ses champs spécifiques et la signature RSA.
Dois-je vérifier la signature du webhook Waffo ?+
Oui. L'intégration la vérifie côté serveur avec la clé publique de la plateforme pour les deux variantes. L'ignorer permettrait à quiconque de forger un événement payé avec une requête non signée.
Comment la licence est-elle émise ?+
Le webhook déduit le plan depuis l'id de prix (y compris les ids BF) et appelle l'octroi de licence de façon idempotente. Sans id de prix configuré, le checkout revient en mode affichage.
Que vérifier lorsqu'un paiement n'accorde pas l'accès ?+
Comparez l'id de prix dans le journal du webhook avec vos variables d'environnement. Un id erroné, une clé publique de production en test, ou un id de prix Care manquant sont les trois causes les plus courantes.
Toutes les questions fréquentes · Version Markdown (pour les agents IA)