Com afegir pagaments a la teva app: pagament, subscripcions i webhooks

La manera més senzilla d'afegir pagaments a la teva app és Stripe: fes servir un Payment Link si només necessites un botó de «Comprar» i pots gestionar les comandes a mà; Stripe Checkout si la teva app ha de saber qui ha pagat i reaccionar automàticament; i Checkout en mode subscripció més el portal de clients de Stripe per a la facturació recurrent. En tots els casos excepte el més senzill, també necessites un webhook: un endpoint al servidor que Stripe crida quan un pagament es completa correctament. I hauries de provar-ho tot amb les claus de prova i les targetes de prova de Stripe abans de passar a les claus de producció.

Aquesta guia explica cada opció, la part dels webhooks que la majoria de tutorials passen per alt i què cal comprovar abans de cobrar diners de veritat. Els detalls de Stripe provenen de la documentació pròpia de Stripe a setembre de 2026.

Per què fer servir un proveïdor de pagaments

Mai no recullis números de targeta als teus propis formularis. Gestionar dades de targetes en brut t'exposa al PCI DSS (l'estàndard de seguretat del sector de les targetes) i és una responsabilitat seriosa. Un proveïdor de pagaments com Stripe allotja el formulari de pagament, guarda la targeta, gestiona l'autenticació bancària i diu a la teva app quin ha estat el resultat. La teva app només veu «el client X ha pagat per Y».

Aquesta guia fa servir Stripe perquè és molt utilitzat, té bona documentació i la suporten la majoria de constructors d'apps amb IA. Hi ha altres proveïdors, i alguns actuen com a «comerciant registrat» que s'encarrega per a tu de la gestió dels impostos de venda; si la conformitat fiscal et preocupa, aquest model val la pena comparar-lo.

Les tres maneres de cobrar amb Stripe

Payment Links

Un Payment Link és una pàgina de pagament allotjada per Stripe que crees al Dashboard de Stripe sense codi. Obtens una URL que pots posar darrere d'un botó a la teva app, compartir en un correu o mostrar com a codi QR. La documentació de Stripe diu que els Payment Links poden vendre un producte, una subscripció o acceptar una donació, i pots deixar que els clients triïn què paguen o limitar el nombre de compres.

El problema: la teva app no sap automàticament que un usuari concret que ha iniciat sessió ha pagat. Per a una pàgina de donacions o una petita botiga en què gestiones les comandes a mà a partir de les notificacions per correu de Stripe, això és suficient. Per a «paga per desbloquejar les funcions Pro», no ho és.

Stripe Checkout

Checkout és una pàgina de pagament que el teu servidor crea sota demanda per a una compra concreta. El teu servidor diu a Stripe què s'està comprant (i, opcionalment, quin client ho compra), Stripe retorna una URL i tu hi envies el client. La documentació de Stripe el descriu com a compatible amb pagaments puntuals i de subscripció, com a pàgina completa allotjada per Stripe, com a pàgina incrustada al teu lloc o com a formulari incrustat.

El flux:

1. El client fa clic a Comprar a la teva app.
2. El teu servidor crea una sessió de Checkout amb la teva clau secreta, incloent un ID que la vincula al teu usuari o a la teva comanda.
3. El client és redirigit a Stripe i paga.
4. Stripe el redirigeix de nou a la teva pàgina d'èxit.
5. Stripe envia un esdeveniment checkout.session.completed al teu webhook, i el teu servidor marca la comanda com a pagada o desbloqueja l'accés.

El pas 2 ha de passar al servidor, perquè fa servir la teva clau secreta. Aquest és el motiu principal pel qual Checkout necessita un backend.

Subscripcions

Les subscripcions fan servir Checkout en mode subscripció amb un preu recurrent que configuris a Stripe. El primer pagament funciona com el flux de dalt. Després, les renovacions, les targetes fallides, les actualitzacions i les cancel·lacions van passant amb el temps —sovint quan el client ni tan sols és a la teva app—, així que la teva app només ho sap a través dels webhooks.

Per deixar que els clients gestionin la seva pròpia subscripció, Stripe ofereix un portal de clients allotjat. Segons la documentació de Stripe, els clients hi poden actualitzar els mètodes de pagament i les dades de facturació, canviar o cancel·lar subscripcions, i veure i descarregar factures. El configures al Dashboard de Stripe i afegeixes un botó de «Gestiona la facturació» que envia el client allà. Així t'estalvies construir aquestes pantalles tu mateix.

Webhooks: la part que no pots saltar

Un webhook és una petició HTTP que Stripe envia al teu servidor quan passa alguna cosa. (Consulta què és un webhook per a la idea general.) La guia d'execució de Stripe és explícita: no pots confiar només en la pàgina d'èxit per executar les comandes, perquè un client pot pagar i després perdre la connexió abans que es carregui aquesta pàgina. Per a les subscripcions i els mètodes de pagament diferits, els webhooks són obligatoris.

Esdeveniments que val la pena gestionar

Regles per a un gestor de webhooks correcte

Aquestes vénen directament de la documentació de webhooks de Stripe, i els gestors generats per la IA de vegades se n'obliden:

• Verifica la signatura. Cada esdeveniment inclou una capçalera Stripe-Signature. El teu gestor la comprova amb el secret de signatura de l'endpoint (comença per whsec_). Sense això, qualsevol podria enviar un «pagament reeixit» fals al teu servidor.
• Fes servir el cos de la petició en brut. Les comprovacions de signatura fallen si el teu framework analitza o modifica el cos abans.
• Retorna una resposta 2xx ràpidament, i després fes la feina més lenta. Els temps d'espera compten com a errors.
• Gestiona els duplicats. Stripe pot entregar el mateix esdeveniment més d'una vegada. Registra els IDs d'esdeveniments processats, o fes que l'execució sigui segura si es fa dues vegades.
• No assumeixis l'ordre. Stripe no garanteix que els esdeveniments arribin en l'ordre en què van passar.
• Espera reintents. En mode producció, Stripe reintenta les entregues fallides durant fins a tres dies, així que una caiguda curta no perd pagaments, però el teu gestor ha de poder tractar esdeveniments tardans.

Els webhooks necessiten una adreça HTTPS pública, de manera que normalment només funcionen quan la teva app està publicada (la CLI de Stripe pot reenviar esdeveniments a una màquina local per als desenvolupadors).

Una indicació que cobreix tot el flux

Afegeix una compra puntual amb Stripe Checkout per al «Pro pack» (ID de preu a STRIPE_PRICE_ID). Crea la sessió de Checkout al servidor fent servir STRIPE_SECRET_KEY des dels secrets, i inclou l'ID de l'usuari que ha iniciat sessió a la sessió. Afegeix un endpoint POST /api/stripe/webhook que verifiqui la signatura de Stripe amb STRIPE_WEBHOOK_SECRET fent servir el cos de la petició en brut, gestioni checkout.session.completed i marqui aquest usuari com a posseïdor del Pro pack. Fes-lo segur si el mateix esdeveniment arriba dues vegades. Pàgines d'èxit i de cancel·lació. Mai no exposis la clau secreta al navegador.

Per a les subscripcions, afegeix: «Fes servir el mode subscripció amb STRIPE_PRICE_ID. Gestiona invoice.paid, invoice.payment_failed, customer.subscription.updated i customer.subscription.deleted. Afegeix un botó de Gestiona la facturació que obri el portal de clients de Stripe.»

Mode de prova

Stripe té entorns separats de sandbox (prova) i de producció, amb claus separades. Les claus de sandbox comencen per pk_test_, sk_test_ o rk_test_; les de producció comencen per pk_live_, sk_live_ o rk_live_. Les transaccions de prova no mouen diners.

Targetes de prova útils de la documentació de proves de Stripe (qualsevol data de caducitat futura, qualsevol CVC de tres dígits):

Prova almenys:

• Un pagament correcte desbloqueja la cosa correcta per a l'usuari correcte
• Una targeta rebutjada mostra un missatge clar i no desbloqueja res
• Tancar la pestanya del navegador just després de pagar encara dona accés (això demostra que el webhook funciona, no només la pàgina d'èxit)
• Cancel·lar a la pàgina de Stripe torna l'usuari a la teva app sense cap cobrament
• Per a les subscripcions: cancel·la al portal de clients i confirma que l'accés acaba quan toca

Sortir en directe

1. Activa el teu compte de Stripe amb les dades de la teva empresa i del banc.
2. Substitueix les claus de prova per les de producció als secrets de la teva app. Stripe recomana claus restringides amb només els permisos que necessiti la teva integració, en lloc d'una clau secreta sense restriccions.
3. Crea un endpoint de webhook de producció que apunti a la teva app publicada. Té el seu propi secret de signatura, diferent del de prova; actualitza'l.
4. Torna a crear els productes i els preus en mode de producció; els IDs del mode de prova no existeixen allà.
5. Fes una compra real petita i reembossa-la.

Guarda totes les claus als secrets del teu projecte, mai al codi ni al xat. La nostra llista de comprovació de seguretat explica amb més detall les claus i la verificació dels webhooks.

Impostos, reemborsaments i paperassa

Els pagaments porten obligacions que el codi no resol. Això no és assessorament fiscal; consulta un comptable.

• Impost de vendes, IVA i GST. Segons on siguis tu i els teus clients, potser necessites registrar-te, cobrar i presentar l'impost. Stripe Tax pot calcular i cobrar l'impost al pagament, vigilar en quins llocs les teves vendes poden generar una obligació i ajudar amb els registres i la presentació, però la responsabilitat continua sent teva. Els proveïdors de comerciant registrat són una alternativa que n'assumeix més part.
• Reembossaments i disputes. Decideix la teva política de reembossaments abans del llançament i publica-la al teu lloc. Les disputes (contracàrrecs) passen; guarda registres del que s'ha comprat i lliurat.
• Rebuts i factures. Stripe pot enviar rebuts per correu; les empreses poden necessitar factures en forma.
• Comissions. Tots els proveïdors cobren per transacció. Consulta la pàgina de preus actual del proveïdor en lloc de confiar en xifres d'articles.

Quina configuració encaixa amb la teva app

• Donacions o un grapat de productes: Payment Links. Consulta com construir un lloc web de donacions per a entitats sense ànim de lucre.
• Una botiga amb cistella: Checkout amb línies de producte i un webhook. Consulta com construir una botiga en línia.
• SaaS o membresies: Checkout en mode subscripció, webhooks i el portal de clients. Consulta com construir un MVP de SaaS i com fixar el preu d'un producte SaaS.
• Un mercat que paga als venedors: una configuració diferent i més regulada (Stripe Connect o similar). Planifica-la per separat.

Afegir pagaments a Mythex

Els pagaments a les apps que construeixes a Mythex fan servir el teu propi compte i les teves pròpies claus de Stripe; no hi ha un «Connecta Stripe» d'un sol clic per a la teva app. El flux habitual:

1. Obtén les claus de prova de Stripe.
2. Afegeix STRIPE_SECRET_KEY (i el secret del webhook més endavant) als secrets del projecte —a través de /secrets, la configuració del projecte, o la targeta de secrets que mostra l'agent quan necessita una clau.
3. Demana a l'agent un Checkout amb una indicació com la de dalt.
4. Prova-ho a la Vista prèvia amb targetes de prova. Publica abans de registrar el webhook, perquè necessita la teva URL pública.
5. Després de passar a les claus de producció, torna a publicar perquè l'app en directe les recollixi.

Consulta Accepta pagaments amb Stripe i Gestiona webhooks al teu backend a la documentació.

Preguntes