Documentation

Checkout and order details

What your customer sees when they pay with Paddle, how the plugin brings them back if they don't finish, and what lands on the order afterwards.

Checkout flow

Payment happens in Paddle's hosted checkout, which the plugin opens for the customer once the order exists.

  1. Customer selects Paddle as the payment method and clicks "Place Order".
  2. Order is created immediately with Pending status.
  3. Customer is redirected to the order-received page, where the Paddle checkout opens automatically with pre-filled email, name, and cart items.
  4. After successful payment, the transaction ID is sent via AJAX to the server.
  5. The server validates the transaction with the Paddle API — verifies status, custom data, and amount.
  6. If valid, the order status is updated and the page reloads with the order confirmation.

Final order status is driven by Paddle webhooks, which are the authoritative source of truth.

Checkout display: overlay or inline

The Checkout Display setting on the gateway settings screen decides how Paddle's payment form is presented.

  • Overlay (popup) — the default. Paddle's checkout opens in a popup on top of your page. This is the simpler, more thoroughly tested path and the right choice for most stores.
  • Inline (embedded in the page) — Paddle renders the payment form into a container in the page, so the customer never leaves it. Paddle renders the payment form only; your page stays responsible for showing the order summary, and custom checkout templates may need styling work.

Worth knowing before you switch to inline:

  • The container is printed on the order-received page and, on the order-pay page, inside the payment box. The regular checkout page never opens Paddle in place, so no container is printed there.
  • Space for the frame is reserved only when the checkout actually opens, so an empty container never pushes the page around.
  • If the container is missing — a theme overriding the checkout templates, for example — the plugin logs an error to the browser console and falls back to the overlay.
  • Once the embedded form has loaded, the "Pay Now" button is hidden: re-opening the checkout would re-render the frame and wipe whatever the customer had typed. If the form never loads, the button stays visible and opens the overlay instead.

Cart & Checkout Blocks

The gateway is registered with the WooCommerce Cart & Checkout Blocks as well as the classic checkout, so it works either way with no extra configuration.

  • The title, gateway logo, description, and place-order button label shown in the block checkout all come from the gateway settings.
  • Availability is decided on the server, so the method disappears from the block checkout when the Paddle API is not configured or a cart item has not been synced to Paddle.
  • Registration is guarded, so a site running a WooCommerce version without Blocks is unaffected.
  • Payment completes on the order-received page exactly as in the classic flow.

Cart recovery

Paddle can send recovery emails to customers with pending payments. The plugin auto-detects recovery links and routes the customer back to their order.

  • URLs with ?_paction=recovery&_ptxn=… are intercepted automatically.
  • Orders are found by stored transaction ID, or by Paddle API lookup using custom_data.order_id as a fallback.
  • Pending orders redirect to the order-pay page; completed orders redirect to order-received.

Paddle details on the order screen

Orders paid with Paddle get a Paddle Transaction Details panel in the side column of the order edit screen, on both the classic and HPOS order screens. It shows:

  • Transaction ID — linked to the transaction in the Paddle dashboard, using the environment the order was processed in, so sandbox orders link to the sandbox dashboard.
  • Status — the Paddle transaction status.
  • Payment method — card brand, last four digits, and expiry, when Paddle reported them.
  • Totals — subtotal, tax, grand total, Paddle fee, and your earnings.
  • Subscription ID and billing period, when the transaction carries them.
  • View invoice (PDF) — opens the Paddle invoice for the transaction.

Paddle's invoice URLs expire after about an hour, so none is stored: the link mints a fresh URL when you click it. It requires the same permissions as the rest of the order screen, and will not open for an order processed in a different Paddle environment than the one currently configured.

Refunds are issued from this same screen — see Refunds.