Payment Methods and tokenization

Payment Methods represent tokenized payment instruments. They let your integration use card or wallet-backed payment details without handling raw card data on your servers.

Use this guide to understand how tokenization, single-use Payment Methods, reusable Payment Methods, Payment Intents, and Setup Intents fit together.

Tokenization

Tokenization is the process of collecting payment details in a customer-facing Paypercut-controlled surface and returning a tokenized object your backend can use.

In Express Checkout, the SDK emits a payment_method_created event with a paymentMethodId. Your backend sends that ID to the Payment Intents API to charge the customer.

{
  "amount": 2999,
  "currency": "eur",
  "customer": "01HVZKZ9P8K6QK8J6MZ9E2A9VN",
  "payment_method": "01KAXYZPAYMENTMETHOD123456",
  "confirm": true
}

Do not store raw card numbers, CVC values, wallet cryptograms, or live secrets in your systems or examples. Store Paypercut resource IDs such as customer, payment_method, payment_intent, and payment.

Single-use and reusable Payment Methods

Payment Methods can be single-use or reusable.

Type	Meaning	Typical source	What happens next
Single-use Payment Method	Can be used for one confirmation attempt unless promoted for future use.	Express Checkout or deferred tokenization.	Use it promptly with a Payment Intent.
Reusable Payment Method	Attached to a customer and available for later payments.	Setup Intent, Checkout setup mode, or Payment Intent with `setup_future_usage`.	Use it with future Payment Intents for the same customer.

A single-use Payment Method is useful when your frontend collects payment details before the backend creates or confirms the Payment Intent. If the Payment Intent has a customer and requests future usage, Paypercut can promote the single-use method to a reusable customer Payment Method during confirmation.

A reusable Payment Method that already belongs to a customer must be used with that same customer. This protects customer ownership and prevents accidental cross-customer reuse.

Save during payment

Use setup_future_usage on a Payment Intent when you want to take a payment now and prepare the payment method for future use.

Value	Future use case
`on_session`	The customer will be present for future payments.
`off_session`	Future payments may happen while the customer is not present.

When setup_future_usage is provided during confirmation, it overrides the value stored on the Payment Intent from creation.

For Checkout Sessions in payment mode, saved_payment_method_options.payment_method_save=enabled controls whether Checkout displays an option to save a new payment method for future on-session use.

Save without charging now

Use a Setup Intent when the customer is adding a payment method for future payments and you do not need to collect money immediately. A Setup Intent guides the payment method through any required authentication and saves it for later use.

Common uses include:

customer account settings where a card is added for later;
subscription signup flows that start with a trial;
platform or marketplace onboarding flows that need a payment method before the first charge;
backup payment methods for invoices or recurring billing.

You can also create a Checkout Session in setup mode when you want Paypercut to host or embed the collection flow.

Reuse later

When charging a saved Payment Method later, create and confirm a Payment Intent with:

the saved payment_method;
the matching customer;
off_session=true, off_session=one_off, or off_session=recurring when the customer is not present.

Use off_session=recurring for scheduled recurring reuse. Use off_session=true or off_session=one_off for unscheduled customer-not-present reuse.

If the customer is present and can authenticate, omit off_session.

3D Secure and payment method details

3D Secure can be required when a customer confirms a card payment. When more customer action is needed, the Payment Intent returns status=requires_action and includes the next step in next_action.

After the payment is attempted, inspect the Payment object for payment method details:

payment.payment_method_details.card.three_d_secure

This is where the API exposes 3D Secure result details such as authentication flow, ECI, result, transaction ID, exemption indicator, and protocol version when they are available.

Operational rules

Create a new Payment Intent for each order or customer checkout session.
Use idempotency keys when creating server-side resources that might be retried.
Use Checkout Sessions unless your flow needs direct Payment Intent control.
Treat single-use Payment Methods as short-lived and use them promptly.
Do not reuse a Payment Method across customers.
Use webhooks for fulfillment and reconciliation instead of relying only on browser redirects.

API reference

Checkout Sessions

Payment Intents