Paano Magdagdag ng Payments sa Iyong App: Checkout, Subscriptions at Webhooks

Ang pinakasimpleng paraan para magdagdag ng payments sa app mo ay Stripe: gamitin ang Payment Link kung kailangan mo lang ng "Buy" button at kaya mong hawakan ang mga order nang manu-mano; gamitin ang Stripe Checkout kung kailangang malaman ng app mo kung sino ang nagbayad at tumugon nang awtomatiko; at gamitin ang Checkout sa subscription mode kasama ang customer portal ng Stripe para sa recurring billing. Sa bawat kaso maliban sa pinakasimple, kailangan mo rin ng webhook, isang server endpoint na tinatawag ng Stripe kapag nagtagumpay ang bayad, at dapat mong subukan ang lahat gamit ang test keys at test card ng Stripe bago lumipat sa live keys.

Ipinapaliwanag ng gabay na ito ang bawat opsyon, ang bahagi ng webhook na nilalampasan ng karamihan ng tutorial, at kung ano ang dapat suriin bago tumanggap ng totoong pera. Galing ang mga detalye ng Stripe sa sarili nilang dokumentasyon, ayon sa Setyembre 2026.

Bakit gumamit ng payment provider

Huwag kailanman mangolekta ng card number sa sarili mong form. Ang paghawak ng raw na card data ay naglalagay sa iyo sa saklaw ng PCI DSS (ang security standard ng card industry) at isang malaking pananagutan. Ang payment provider gaya ng Stripe ang nagho-host ng payment form, nag-iimbak ng card, humahawak ng bank authentication, at sinasabi sa app mo ang resulta. Ang nakikita lang ng app mo ay "nagbayad ang customer X para sa Y".

Ginagamit ng gabay na ito ang Stripe dahil malawak itong ginagamit, maayos ang dokumentasyon, at sinusuportahan ng karamihan ng AI app builder. May iba pang provider, at ang ilan ay kumikilos bilang "merchant of record" na tumatanggap ng paghawak ng sales tax para sa iyo; kung nakakabahala sa iyo ang pagsunod sa buwis, sulit itong pagkumparahin.

Ang tatlong paraan ng pagtanggap ng bayad gamit ang Stripe

Payment Links

Ang Payment Link ay payment page na naka-host ng Stripe na ginagawa mo sa Stripe Dashboard nang walang code. Makakakuha ka ng URL na maaari mong ilagay sa likod ng button sa app mo, ibahagi sa email, o ipakita bilang QR code. Ayon sa docs ng Stripe, maaaring magbenta ng produkto, subscription, o tumanggap ng donasyon ang Payment Links, at maaari mong hayaang pumili ang customer ng babayaran o limitahan ang bilang ng pagbili.

Ang hamon: hindi awtomatikong nalalaman ng app mo na nagbayad ang isang partikular na naka-login na user. Para sa donation page o maliit na tindahan kung saan manu-mano mong pinapadala ang mga order mula sa email notification ng Stripe, ayos lang iyon. Para sa "magbayad para i-unlock ang Pro features", hindi ito sapat.

Stripe Checkout

Ang Checkout ay payment page na ginagawa ng server mo kapag hiniling, para sa isang partikular na pagbili. Sinasabi ng server mo sa Stripe kung ano ang binibili (at opsyonal kung sino ang bumibili), ibinabalik ng Stripe ang isang URL, at ipinapadala mo ang customer doon. Sinasabi ng docs ng Stripe na sinusuportahan nito ang one-time at subscription na bayad, bilang buong page na naka-host ng Stripe, page na naka-embed sa site mo, o embedded na form.

Ang daloy:

1. Ina-click ng customer ang Buy sa app mo.
2. Gumagawa ang server mo ng Checkout Session gamit ang secret key mo, kasama ang ID na nag-uugnay dito sa user o order mo.
3. Dinidirekta ang customer sa Stripe at nagbabayad.
4. Ibinabalik sila ng Stripe sa success page mo.
5. Nagpapadala ang Stripe ng checkout.session.completed event sa webhook mo, at minamarkahan ng server mo ang order bilang bayad o ina-unlock ang access.

Dapat mangyari ang hakbang 2 sa server, dahil ginagamit nito ang secret key mo. Iyon ang pangunahing dahilan kung bakit kailangan ng Checkout ng backend.

Subscriptions

Gumagamit ang subscriptions ng Checkout sa subscription mode na may recurring price na itinakda mo sa Stripe. Gumagana ang unang bayad gaya ng daloy sa itaas. Pagkatapos nito, ang mga renewal, pumapalyang card, upgrade at pagkansela ay nangyayari sa paglipas ng panahon — madalas kapag wala na ang customer sa app mo — kaya nalalaman lang ito ng app mo sa pamamagitan ng webhooks.

Para hayaang pamahalaan ng customer ang sarili nilang subscription, may nakahandang customer portal ang Stripe. Ayon sa docs ng Stripe, puwedeng i-update ng customer doon ang payment method at billing details, baguhin o kanselahin ang subscription, at tingnan at i-download ang mga invoice. Ino-configure mo ito sa Stripe Dashboard at nagdadagdag ng "Manage billing" button na nagdidirekta sa customer doon. Hindi mo na kailangang buuin ang mga screen na iyon.

Webhooks: ang bahaging hindi puwedeng laktawan

Ang webhook ay HTTP request na ipinapadala ng Stripe sa server mo kapag may nangyari. (Tingnan ang ano ang webhook para sa pangkalahatang ideya.) Malinaw ang fulfilment guide ng Stripe: hindi ka dapat umasa lang sa success page para tuparin ang mga order, dahil maaaring magbayad ang customer at mawalan ng koneksyon bago pa mag-load ang page na iyon. Para sa subscription at mga delayed na payment method, kailangan ang webhooks.

Mga event na dapat hawakan

Mga tuntunin para sa tamang webhook handler

Nanggagaling ang mga ito mismo sa dokumentasyon ng webhook ng Stripe, at minsan nalilimutan ng mga AI-generated na handler:

• I-verify ang signature. May Stripe-Signature header ang bawat event. Sinusuri ito ng handler mo gamit ang signing secret ng endpoint (nagsisimula sa whsec_). Kung wala ito, sinuman ay makapagpapadala ng pekeng "nagtagumpay ang bayad" sa server mo.
• Gamitin ang raw request body. Pumapalya ang signature check kung babaguhin o pa-parse muna ng framework mo ang body.
• Magbalik ng 2xx nang mabilis, tapos saka gawin ang mas mabagal na trabaho. Bilang failure ang timeout.
• Hawakan ang mga duplicate. Maaaring maihatid nang higit sa isang beses ng Stripe ang parehong event. Itala ang mga naprosesong event ID, o gawing ligtas ang fulfilment kahit dalawang beses itong tumakbo.
• Huwag ipagpalagay ang pagkakasunod. Hindi ginagarantiyahan ng Stripe na darating ang mga event sa pagkakasunod ng pangyayari.
• Asahan ang mga retry. Sa live mode, nag-re-retry ang Stripe ng mga pumalyang delivery hanggang tatlong araw, kaya hindi mawawala ang mga bayad dahil sa maikling outage — pero dapat kayang hawakan ng handler mo ang mga huling event.

Kailangan ng webhooks ng pampublikong HTTPS address, kaya kadalasan gumagana lang ang mga ito kapag na-publish na ang app mo (maaaring i-forward ng CLI ng Stripe ang mga event sa lokal na makina para sa mga developer).

Isang prompt na sumasaklaw sa buong daloy

Magdagdag ng one-time na pagbili gamit ang Stripe Checkout para sa "Pro pack" (price ID sa STRIPE_PRICE_ID). Gumawa ng Checkout Session sa server gamit ang STRIPE_SECRET_KEY mula sa secrets, at isama ang ID ng naka-login na user sa session. Magdagdag ng POST /api/stripe/webhook na nagve-verify ng Stripe signature gamit ang STRIPE_WEBHOOK_SECRET at raw request body, humahawak ng checkout.session.completed, at minamarkahan ang user na iyon bilang may Pro pack. Dapat ligtas ito kapag dumating nang dalawang beses ang parehong event. Magdagdag ng success at cancel na page. Huwag kailanman ilantad ang secret key sa browser.

Para sa subscription, idagdag: "Gumamit ng subscription mode gamit ang STRIPE_PRICE_ID. Hawakan ang invoice.paid, invoice.payment_failed, customer.subscription.updated at customer.subscription.deleted. Magdagdag ng Manage billing button na nagbubukas ng Stripe customer portal."

Test mode

May hiwalay na sandbox (test) at live na environment ang Stripe na may hiwalay na keys. Nagsisimula ang sandbox keys sa pk_test_, sk_test_ o rk_test_; nagsisimula ang live keys sa pk_live_, sk_live_ o rk_live_. Hindi gumagalaw ang pera sa mga test transaction.

Mga kapaki-pakinabang na test card mula sa testing docs ng Stripe (anumang future na expiry date, anumang tatlong-digit na CVC):

Subukan nang hindi bababa sa:

• Ang matagumpay na bayad ay nag-u-unlock ng tamang bagay para sa tamang user
• Ang tinanggihang card ay nagpapakita ng malinaw na mensahe at walang na-unlock
• Ang pagsasara ng browser tab kaagad pagkatapos magbayad ay nagbibigay pa rin ng access (pinatutunayan nitong gumagana ang webhook, hindi lang ang success page)
• Ang pagkansela sa Stripe page ay nagbabalik sa user sa app mo nang walang nasingil
• Para sa subscription: magkansela sa customer portal at kumpirmahing natatapos ang access kapag dapat

Pag-go live

1. I-activate ang Stripe account mo gamit ang detalye ng negosyo at bangko.
2. Ipalit ang live keys sa secrets ng app mo. Inirerekomenda ng Stripe ang restricted keys na may permiso lang na kailangan ng integration mo, sa halip na unrestricted na secret key.
3. Gumawa ng live webhook endpoint na nakaturo sa na-publish mong app. May sarili itong signing secret, na iba sa test — i-update ito.
4. Gumawa muli ng mga produkto at price sa live mode; wala roon ang mga test-mode ID.
5. Gumawa ng isang maliit na totoong pagbili at i-refund ito.

Itago ang bawat key sa secrets ng project mo, hindi sa code o sa chat. Sakop ng security checklist namin ang mga key at webhook verification nang mas detalyado.

Buwis, refund at papeles

May mga obligasyon ang mga bayad na hindi nalulutas ng code. Hindi ito payo sa buwis; kumonsulta sa accountant.

• Sales tax, VAT at GST. Depende sa lokasyon mo at ng mga customer mo, maaaring kailangan mong magparehistro, maningil at mag-file ng buwis. Kayang kalkulahin at kolektahin ng Stripe Tax ang buwis sa checkout, subaybayan kung saan maaaring lumikha ng obligasyon ang mga benta mo, at tumulong sa pagpaparehistro at pag-file — pero nananatili sa iyo ang responsibilidad. Alternatibo ang merchant-of-record na mga provider na mas maraming hinahawakan para sa iyo.
• Refund at dispute. Magpasya sa refund policy mo bago mag-launch at ilagay ito sa site mo. Nangyayari ang mga dispute (chargeback); magtago ng talaan ng kung ano ang binili at naihatid.
• Resibo at invoice. Kayang mag-email ng resibo ang Stripe; maaaring kailanganin ng mga negosyo ang tamang invoice.
• Bayarin. Naniningil ang bawat provider kada transaksyon. Tingnan ang kasalukuyang pricing page ng provider sa halip na umasa sa mga numero sa artikulo.

Aling setup ang akma sa app mo

• Donasyon o ilang produkto: Payment Links. Tingnan ang paano gumawa ng donation website para sa nonprofit.
• Tindahan na may cart: Checkout na may line items at webhook. Tingnan ang paano gumawa ng online store.
• SaaS o membership: Checkout sa subscription mode, webhooks at customer portal. Tingnan ang paano gumawa ng SaaS MVP at paano magpresyo ng SaaS product.
• Marketplace na nagbabayad sa mga seller: ibang setup na mas regulated (Stripe Connect o katulad). Magplano para dito nang hiwalay.

Pagdaragdag ng payments sa Mythex

Gumagamit ang mga payment sa app na ginawa mo sa Mythex ng sarili mong Stripe account at keys; walang one-click na "Connect Stripe" para sa app mo. Ang karaniwang daloy:

1. Kumuha ng Stripe test keys.
2. Idagdag ang STRIPE_SECRET_KEY (at ang webhook secret mamaya) sa project secrets — sa pamamagitan ng /secrets, project settings, o secrets card na ipinapakita ng agent kapag kailangan nito ng key.
3. Humiling sa agent ng Checkout gamit ang prompt na tulad ng nasa itaas.
4. Subukan sa Preview gamit ang test card. I-publish bago irehistro ang webhook, dahil kailangan nito ang pampublikong URL mo.
5. Pagkatapos lumipat sa live keys, i-publish ulit para makuha ng live na app ang mga ito.

Tingnan ang Tumanggap ng bayad gamit ang Stripe at Pangasiwaan ang webhooks sa backend mo sa docs.

Mga tanong