Payment building blocks
Use this guide to understand how Paypercut payment resources fit together before choosing an integration path.
Most integrations should start with Checkout Sessions because Checkout handles payment collection, customer authentication, redirects, and the underlying Payment Intent for you. Use Payment Methods and Payment Intents directly when you need a custom flow, such as wallet buttons, deferred tokenization, manual capture, or saved payment method reuse.
Core resources
| Resource | What it represents | Use it when |
|---|---|---|
| Checkout Session | A hosted, embedded, or setup checkout flow shown to the customer. | You want Paypercut to collect payment details and orchestrate the payment page. |
| Payment Method | A tokenized customer payment instrument, such as a card or wallet-backed card. | You need to attach a payment instrument to a Payment Intent, save it for future use, or list saved methods for a customer. |
| Payment Intent | The server-side object that tracks one attempt to collect money for an order or customer session. | You build a custom payment flow or confirm a tokenized payment method from Express Checkout or another tokenization flow. |
| Setup Intent | The server-side object that sets up and saves a payment method for future payments without collecting money now. | You need to save a card for later billing, subscriptions, or customer account settings. |
| Payment | The result of a payment attempt and the best place to inspect payment outcome details. | You need reconciliation, authorization/capture state, failure details, payment method details, or 3D Secure result details. |
| Product | The thing being sold or provisioned. | You need a reusable catalog object for Checkout, invoices, or subscriptions. |
| Price | The amount, currency, and optional billing interval for a Product. | You need reusable one-time or recurring pricing. |
| Webhook Event | An asynchronous notification about a state change. | You need to update orders, provision access, or reconcile payment outcomes reliably. |
How the resources connect
Checkout Sessions are the highest-level API. In payment mode, Checkout collects a payment method and creates or confirms the Payment Intent behind the checkout. In setup mode, Checkout collects and saves a payment method through a Setup Intent.
Payment Methods are not charges. A Payment Method is the stored representation of the payment instrument. It can be single-use for one confirmation attempt, or reusable when it is attached to a customer and set up for future use.
Payment Intents are lower-level. They let your server create, confirm, capture, cancel, and inspect a payment attempt. They are useful when your frontend collects a single-use payment method through Express Checkout or another tokenization flow and your backend needs to charge it.
Payments are the money movement records. Use the Payment object to inspect what happened after a Payment Intent was confirmed, including payment_method_details, authorization state, outcome, and 3D Secure details.
Products and Prices are catalog records. Products describe what is sold, and Prices define the amount, currency, and billing terms. They become especially important for subscriptions because recurring Prices define how much to bill and how often.
Choose the right starting point
| Goal | Recommended path |
|---|---|
| Accept a normal online card or wallet payment | Create a Checkout Session in payment mode. |
| Render hosted or embedded checkout with minimal payment logic on your side | Create a Checkout Session and redirect or embed the returned checkout URL. |
| Render Apple Pay or Google Pay buttons directly on your page | Use Express Checkout to create a single-use Payment Method, then create and confirm a Payment Intent. |
| Authorize now and capture later | Use capture_method=manual on the Payment Intent, either directly or through payment_intent_data on a Checkout Session. |
| Save a payment method while taking a payment | Confirm a Payment Intent with setup_future_usage, or use Checkout payment mode with saved payment method options. |
| Save a payment method without charging now | Use a Setup Intent, or a Checkout Session in setup mode. |
| Charge a saved payment method later | Create and confirm a Payment Intent with the saved Payment Method and the correct customer. |
| Reuse the same commercial offer across Checkout, invoices, and subscriptions | Create Products and Prices in the catalog. |
Customer and payment method ownership
Customer ownership matters whenever a payment method is reused. A reusable Payment Method that already belongs to a customer must be used with that same customer. A single-use Payment Method created from tokenization can be assigned during Payment Intent confirmation when the Payment Intent has a customer.
Use setup_future_usage when a Payment Intent should prepare the payment method for future use:
| Value | Future usage |
|---|---|
on_session |
Future payments happen while the customer is present and can authenticate. |
off_session |
Future payments may happen when the customer is not present, such as subscriptions or saved-card billing. |
For off-session attempts with a saved Payment Method, use the Payment Intent off_session parameter to describe the attempted reuse. Use true or one_off for unscheduled customer-not-present charges, and recurring for scheduled recurring charges.
Where to inspect results
Do not rely only on the immediate response from the customer-facing page. Payment flows can require authentication, asynchronous provider processing, retries, or manual capture.
Use these records for post-payment logic:
| Need | Resource |
|---|---|
| Current payment lifecycle state | Payment Intent status |
| Whether manual capture is still required | Payment Intent amount_capturable and status=requires_capture |
| Final money movement and outcome details | Payment |
| Card, wallet, and 3D Secure details used for a payment | Payment payment_method_details |
| Reliable order fulfillment signal | Webhook events |
