Skip to main content

Introduction to Checkout APIs

The Checkout APIs represent the final touchpoint of the user experience on Webround sites. This module manages the transition from the shopping cart to the actual financial transaction, orchestrating communication between your store data and the Stripe payment infrastructure.

The goal of these APIs is to transform a purchase intent into a confirmed order, ensuring that every aspect (tax, logistics, and promotional) is validated before the user concludes the transaction.

Checkout Philosophy: Redirect & Automation​

Webround adopts a redirect-based approach to maximize security and reduce the compliance burden (PCI-DSS) on your systems.

  • Dynamic Session: The API does not directly process the payment but generates a secure Stripe Checkout Session. It returns a unique URL to which the frontend must redirect the user. From this point forward, Webround does not actively work on the order but only listens for events regarding that Checkout Session and any subscriptions or invoices generated by Stripe for that payment_intent.
  • State Management: Once the payment is completed on Stripe's protected domain, the user is redirected back to the site's home page. Meanwhile, Webround handles background order synchronization through event reception from Stripe.

Webhooks and Real-time Synchronization​

The core of Webround's reliability lies in asynchronous event management. Every payment passing through Stripe generates detailed events that we listen to on your behalf, thanks to the Stripe Connect integration. The merchant only needs to complete the Stripe onboarding via Webround to enable event listening for their specific store.

Order Lifecycle​

Webround initiates the checkout session on behalf of the merchant. This means that simply generating the checkout URL triggers the immediate creation of an order in the database with a default state of created. The order does not wait for payment to exist; it exists from the moment the user manifests an intent to purchase.

If the user finalizes the transaction, the order evolves based on signals sent by Stripe. Webround synchronizes events in real-time and employs rigorous measures (idempotency and versioning) to prevent accidental event replay, ensuring that processed data is always the most recent and never overwritten by obsolete notifications.

tip

Even in cases of temporary errors, brief downtime, or unforeseen issues, Webround organizes events via queues. The first operation is the storage of the event from Stripe. Subsequently, internal systems process them. In case of issues, the queues will retry processing "stuck" events.

1. Native Stripe Webhooks​

Webround natively listens to Stripe servers. Receiving the checkout.session.completed event almost always results in a transition to the paid state, but the system manages the entire Stripe state machine:

  • created: Default initial state. The session is open, and the order is registered but not yet processed.
  • pending: The payment has been initiated but is awaiting confirmation (e.g., bank transfers or asynchronous payments requiring technical processing time).
  • authorized: Typical of pre-authorization flows. Funds are blocked on the customer's card but not yet captured by the merchant.
  • partially_funded: Used in scenarios of split payments or partial deposits where the total amount has not yet been covered.
  • paid: The payment has been confirmed and successfully captured.
  • failed: The payment was rejected (e.g., declined card or Stripe technical error).
  • canceled: This state is automatically set when a checkout is abandoned for a period of time.
Important Note

Webround does not allow manual alteration of orders synchronized with Stripe to ensure fiscal integrity. The only modifications allowed for the merchant concern shipping logic (updating shipping status and inserting the tracking URL).

2. Custom Integrations and Merchant Autonomy​

In addition to native management, Webround guarantees maximum flexibility for the merchant:

  • Webround Webhooks: You can configure your backend to receive "clean" and processed notifications from Webround every time an order changes state.
  • Autonomy on Stripe: Being an integration based on Stripe Connect (Standard mode), you maintain full access to the Stripe dashboard. You can connect your external systems (e.g., ERPs, licensing systems, CRMs) directly to Stripe webhooks to trigger proprietary logic in total autonomy, without any interference from Webround processes.

Business Logic and Pre-validation​

To prevent payment sessions from failing or generating fiscal errors, the Checkout APIs perform a series of rigorous checks. If requirements are not met, the API returns a 400 (Bad Request) error explaining the reason.

1. Identity and Security Requirements​

  • Email Verification: For registered users, the email must be verified. This ensures the legal validity of issued invoices and reduces fraud risks.
  • Recurring Products: Subscription checkout (recurring) strictly requires the user to be authenticated (guest checkout is not permitted for subscriptions).

2. Cart Consistency​

The system prevents the creation of hybrid sessions that Stripe could not process:

  • Single Currency: All items in the cart must share the same currencyCode.
  • Uniform Cadence: It is not possible to mix products with different billing frequencies (e.g., a monthly and an annual subscription) in the same checkout.

3. Logistics and Taxation (Tax & Shipping)​

Tax calculation is dynamic and based on the destination:

  • Shipping Country: For physical products, the destination country is mandatory. Without it, the system cannot resolve the correct Tax Zone or calculate shipping costs.
  • Availability: If the chosen country has no shipping methods configured in the store's back-office and the product requires shipping, the checkout is proactively blocked.

4. Promotional Engine​

Discount codes are validated in real-time, checking:

  • Usage Limits: Time expiration, global usage caps, or per-customer limits.
  • Compatibility: Exclusion of specific products or variants that the merchant has decided not to discount.

Authentication and Context​

  • Store Context: Every request requires the store-id header to load the correct tax configurations and connected Stripe accounts.
  • Customer Context: If present, the customer's authentication token is used to apply personal coupon usage limits and enable subscription activation.

Important Notes & FAQ​

Is guest checkout supported?​

A user who has never registered on your Webround site can purchase directly without issues: the entire payment flow is orchestrated through Stripe. Webround collects only essential data:

  • Order items
  • Customer email
  • Billing address
  • Shipping address (if applicable)

Technical Constraint: If the cart contains recurring products (subscriptions), guest checkout is not allowed. In this case, the API will return a 400 error as authentication is mandatory for managing recurrences.

Where are customers' payment methods stored?​

Webround never stores customer payment method details. Everything is stored on Stripe. Make sure to use the Stripe Customer Portal URL (configurable in your store settings) to give your customers a point of access for managing their orders, subscriptions, and payment methods.

Why am I receiving a Stripe resource configuration error?​

This error only occurs if the SKU configuration is incomplete or inconsistent. If a product has a standard price on Webround without advanced Stripe options, everything works smoothly. The block only triggers if:

  • You entered a Product ID without the relative Price ID (or vice versa).
  • You enabled "Use Stripe Tax" without providing a Tax Code ID.
  • You enabled "Use Stripe Tax" without correctly configuring the Product ID, Price ID, or Tax Code ID.

Are invoices sent by Stripe legally compliant?​

In general, Stripe invoices are only technical documentation of successful payment. Unless there are third-party or customized integrations, they do not guarantee 100% fiscal compliance (specifically in jurisdictions like Italy).

An international customer is subject to Reverse Charge. How do I avoid VAT for that customer?​

Simply set the VAT exemption flag in the customer's profile in Webround Commerce. Remember to do the same on Stripe.

Can I issue a refund from Webround?​

No, Webround is only a synchronized mirror of what happens on Stripe. Any operation performed—whether it's a refund, credit note, or dispute—must be handled directly through Stripe.

Does Webround manage tax rates on a global scale?​

You can set your rates via Tax Zones and manage everything required. If a Tax Zone is not present for the purchase country, the final price at checkout will correspond to the net price entered in Webround. Caution: To calculate taxes on physical products, it is essential for the customer to provide the destination country; otherwise, the API will return a 400 error.

Can I integrate Stripe Tax?​

Yes, Webround allows you to integrate Stripe Tax, delegating rate calculation to Stripe. You must manage this per SKU by entering the Tax Code ID, Product ID, and Price ID. Compatibility Constraint: You cannot mix Stripe Tax products and Webround manual tax products in the same cart; the system will block the checkout with a 400 error to avoid calculation conflicts.

What are the cart limits?​

For performance reasons and limits imposed by payment gateways, the cart has structural constraints:

  • Quantity: Maximum 20 items for recurring products and 100 for one-time products.
  • Consistency: All items must have the same currency and, for subscriptions, the same billing cadence.

Why isn't my promo code working?​

Coupons are subject to rigorous validation. A code may be rejected if it is expired, has reached its usage limit (global or per customer), if the order does not reach the minimum amount, if you are trying to combine an "exclusive" code with other discounts, or if the product/variant is explicitly excluded.

What is the Tax Rate ID?​

The Tax Rate ID is an identifier you can save within a Tax Zone or on the product's default tax rate (we recommend always working by Tax Zone). This ID maps directly to a Tax Rate created on your Stripe dashboard.

Correctly configuring the Tax Rate ID allows Stripe to populate the VAT/Tax field in its receipts with the correct label and rate. It is important to distinguish two scenarios:

  • If you use Stripe Tax: You do not need to configure this field, as Stripe handles everything autonomously.
  • If you use Webround manual calculation: Webround calculates the rate based on the Tax Zone to determine the order total. The Tax Rate ID serves "only" to make the Stripe invoice cleaner and more professional, explicitly showing the amount of tax applied.

Tip: We recommend always including it. Otherwise, the Stripe order will still show the correct total including tax, but an explicit "Tax" field will not appear in the price breakdown on the Stripe receipt.