Payment Intents

Use Payment Intents when your integration needs to control the lifecycle of a payment from your server. A Payment Intent tracks the amount, currency, customer, payment method, capture mode, authentication state, and final payment result for one order or customer session.

For most hosted or embedded checkout integrations, create a Checkout Session instead. Checkout creates and confirms the underlying Payment Intent for you.

When to use Payment Intents

Use a Payment Intent directly when:

Your frontend receives a single-use paymentMethodId from Express Checkout or another tokenization flow.
You need to create the payment on your server after a wallet or embedded payment UI event.
You need manual capture, where the customer authorizes funds now and you capture later.
You need to reuse a saved Payment Method for a customer.
You need to model customer-present and customer-not-present payment attempts explicitly.

Use Checkout Sessions when you want Paypercut to collect payment details and handle the payment page for you.

Lifecycle

A Payment Intent normally moves through these states:

Status	Meaning	What your integration should do
`requires_payment_method`	The Payment Intent does not have a usable payment method yet.	Collect or attach a payment method, then confirm.
`requires_confirmation`	A payment method is attached, but payment has not started.	Confirm the Payment Intent when the customer is ready to pay.
`requires_action`	Customer authentication or another client-side step is required.	Complete the action described by `next_action`, then wait for the Payment Intent to continue.
`processing`	Paypercut or the provider is still processing the payment.	Wait for the final state or a webhook.
`requires_capture`	The payment was authorized with manual capture.	Capture the authorized amount or cancel the authorization.
`succeeded`	The payment completed and funds were captured.	Fulfill the order after verifying the result through webhooks or retrieval.
`canceled`	The Payment Intent was canceled and cannot be used.	Create a new Payment Intent if the customer still needs to pay.

Create and confirm

Payment Intents can be created first and confirmed later, or created and confirmed in one request.

Create first when your backend knows the amount before the customer has selected or tokenized a payment method:

{
  "amount": 2999,
  "currency": "eur"
}

Create and confirm in one request when you already have a payment method:

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

If confirm is omitted or false, Paypercut creates the Payment Intent without starting authorization. If a payment method is included, the Payment Intent can move to requires_confirmation and can be confirmed later.

Payment methods on Payment Intents

A Payment Intent can use:

an existing reusable Payment Method that belongs to the same customer;
a single-use Payment Method created by tokenization, such as Express Checkout;
payment method data included in the request when supported by the API.

Reusable Payment Methods are customer-owned. If a reusable Payment Method already belongs to a customer, the Payment Intent customer must match. Single-use Payment Methods can be assigned during confirmation when the Payment Intent has a customer.

Saving for future use

Set setup_future_usage when the Payment Intent should prepare the payment method for reuse:

Value	Use when
`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.

You can provide setup_future_usage when creating the Payment Intent or when confirming it. If you provide it during confirmation, the confirmation value takes precedence over the value stored on the Payment Intent.

Saving for future use usually requires a customer. If you do not provide a customer, the Payment Intent can still complete as a one-off payment, but the payment method cannot be attached to a customer for future reuse by that Payment Intent.

Off-session reuse

Use off_session only when confirming a Payment Intent while the customer is not actively in your checkout flow.

Value	Meaning
`true`	Customer-not-present payment attempt.
`one_off`	Unscheduled customer-not-present reuse of a saved Payment Method.
`recurring`	Scheduled recurring reuse of an eligible saved Payment Method.

Off-session attempts should use a saved Payment Method that belongs to the same customer. If the payment method cannot be used for the requested scenario, the request fails before the payment is sent to the provider.

Manual capture

Use capture_method=manual when you want to authorize funds now and capture later. This is useful when the final amount depends on fulfillment, inventory, metered usage, fraud review, or a service outcome.

Create and confirm a manual-capture Payment Intent:

{
  "amount": 10050,
  "currency": "eur",
  "payment_method": "01KAXYZPAYMENTMETHOD123456",
  "customer": "01HVZKZ9P8K6QK8J6MZ9E2A9VN",
  "capture_method": "manual",
  "confirm": true
}

When authorization succeeds, the Payment Intent returns status=requires_capture, amount_capturable equals the authorized amount, and amount_received remains 0.

Capture the authorization when you are ready to collect funds:

{
  "amount_to_capture": 10050,
  "final_capture": true
}

You can capture less than or equal to amount_capturable. If the final amount must exceed the authorization, cancel the existing authorization and create a new Payment Intent for the updated amount.

After confirmation

The Payment Intent tells you the lifecycle state. The Payment tells you what happened to the money movement.

After confirmation, retrieve the Payment Intent or listen for webhooks to determine whether the payment succeeded, requires action, failed, was authorized for capture, or was canceled. Use the related Payment to inspect payment method details, outcome, and 3D Secure authentication details.

API reference

Payment Methods and tokenization

Payment records