Conceitos de pagamento

Adding payments is the moment your app touches real money, real fraud, and real regulation. A bug here is not a cosmetic glitch — it can double-charge a customer or leak card data.

When you vibe-code payments, your job shifts from "make it work" to "make it provably correct". You describe intent precisely and let the AI scaffold the integration, but you stay accountable for the money flow.

You almost never talk to banks directly. A payment provider (Stripe, Paddle, Adyen, RevenueCat for mobile) abstracts cards, wallets, and bank rails behind one API.

The provider hosts the sensitive parts so card numbers never hit your server. Your code orchestrates the provider; the provider moves the money.

A one-time payment charges a fixed amount once: a course, a credit pack, a lifetime unlock. A subscription charges on a repeating schedule and must handle renewals, upgrades, and cancellations.

These need different data models. Conflating them is a classic early mistake — subscriptions carry state over time, one-time charges do not.

Every charge follows a path: the customer authorizes, the provider captures funds, money settles into your account days later, and fees are deducted along the way.

Authorization is not settlement. A charge can be authorized and still fail to settle. Designing for this gap — pending, succeeded, failed — is core to a correct integration.

PCI DSS is the security standard for handling card data. Touching raw card numbers drags you into a heavy compliance scope you do not want.

The escape hatch is to never let card data reach your server. Use the provider's hosted checkout page or tokenizing client-side fields. The card becomes a token; you only ever store the token.

After a card is entered, the provider returns a token or a saved payment-method ID. This opaque reference can be charged again without ever re-handling the number.

Storing tokens lets you bill subscriptions and offer one-click repurchase, all while the actual PAN stays inside the provider's vault.

Money is never a float. $19.99 is stored as the integer 1999 in the smallest currency unit (cents). Floating point introduces rounding errors that corrupt totals.

Always pair an amount with a currency code. "1999" means nothing until you know it is USD cents versus JPY (which has no minor unit at all).

Networks retry. A user double-clicks, a request times out and retries, a webhook is redelivered. Without protection, you charge twice.

An idempotency key is a unique value you attach to a charge request so the provider recognizes a retry and returns the original result instead of creating a second charge. Treat it as mandatory, not optional.

The user's browser is not a reliable witness. They may close the tab right after paying. The provider tells you what really happened through webhooks — server-to-server events like payment_succeeded.

Never grant access based purely on a client redirect. The webhook is your source of truth for fulfilment.

Every serious provider has a test mode with fake card numbers and separate API keys. You can simulate successful charges, declines, disputes, and expired cards without moving a cent.

Build and verify the entire flow in test mode first. Only swap to live keys once webhooks, refunds, and edge cases all behave.

Before writing any code, describe the full journey to your AI assistant: who pays, for what, how access is granted, and what happens when payment fails.

A clear spec produces a coherent integration. A vague prompt produces a happy-path demo that breaks on the first declined card.

Payments differ from normal code because real money and regulation are involved. You orchestrate a provider, store tokens instead of cards, and keep card data off your server to shrink PCI scope.

Money is integer cents plus a currency code. Idempotency keys stop duplicate charges, and webhooks — not the browser — are the truth about what was paid. Spec the entire flow, including failures, before coding.