Configurando um checkout

A checkout is the moment of conversion: the screen where a customer commits to pay. Your goal is to get them through it with the fewest steps and zero security risk.

The simplest robust option is a provider-hosted checkout page. The provider renders the form, collects the card, and redirects back. You write almost no payment UI.

Hosted checkout sends the user to the provider's page, then back to you. Embedded checkout renders the provider's secure fields inside your own page using their JavaScript SDK.

Hosted is fastest to ship and lowest in compliance scope. Embedded gives more design control but more code. For a first integration, prefer hosted.

Never let the browser decide the price. The amount, currency, and product must be set on your server, where the user cannot tamper with them.

Your backend creates a checkout session with the trusted price, then hands the browser only a session ID or URL. The client redirects; it never names the amount.

A hosted checkout needs two return paths: a success URL for completed payment and a cancel URL for abandonment. The provider appends a session ID so you can look the result up.

The success page is a confirmation, not an authorization. Show "thank you", but unlock access only after the webhook confirms payment.

A session contains line items: which product, what quantity, what price. Define products and prices in the provider's dashboard or API so you reference stable IDs rather than ad-hoc numbers.

Pre-defined prices let you change a number in one place and keep checkout code untouched. They also enable coupons and tax rules cleanly.

Checkout can collect email, billing address, and tax IDs. Email is essential — it links the payment to a customer record and lets you send receipts.

Ask only for what you need. Every extra field is friction. But always capture enough to reconcile the payment with a user account on your side.

The payment must map back to a specific account in your system. Pass your internal user ID into the session as metadata or a client_reference_id.

When the webhook arrives, that ID tells you exactly whose access to grant. Without it, you have a payment floating with no owner.

Selling across borders means VAT, GST, and sales tax. Some providers (or merchant-of-record platforms) calculate and remit tax for you; others expect you to handle it.

Decide early. Retrofitting tax onto a live checkout is painful. If you sell globally and want it handled, a merchant-of-record model removes the burden.

After payment the user lands on your success URL. Verify the session server-side using its ID before showing sensitive confirmation details.

Even here, do not flip the access flag. Display a pending or success message, and let the webhook be the gate that actually unlocks the product.

Web checkout does not apply on iOS and Android. Apple and Google require their in-app purchase systems for digital goods and take a platform cut.

Tools like RevenueCat wrap both stores behind one SDK so you manage products, entitlements, and receipts uniformly across platforms.

With test keys, run the full path: create session, redirect, pay with a test card, return, and confirm the webhook fires. Then test the cancel path and a declined card.

Only when every branch behaves — success, cancel, decline, and webhook fulfilment — do you switch to live keys.

Confirm the most important checkout safety rule.

A hosted checkout is the fastest, lowest-risk way to start: the provider renders the form and you ship almost no payment UI. Your server creates the session with a trusted price and attaches your user ID so the result maps to an account.

Success and cancel URLs handle returns, but fulfilment waits for the webhook. Plan tax early, remember that mobile needs in-app purchases, and test every branch in test mode before going live.