Start a headless payment for an invoice that already exists, without sending the shopper to a WHMCS payment page. Instead, this renders and confirms the payment from within your integration. A payment method may still redirect the shopper to their bank and then back to a URL that you own (see Redirect methods below).

Behavior

• This endpoint returns the session as the data.payment_session value. The POST /cart/{cart_id}/checkout endpoint only returns the same PaymentSession object as the data.payment.next_action.session value when its next_action.type value is payment_session.
• Issuing a session is not a payment. This endpoint does not place the order, change the invoice status, or record a transaction, so you can safely abandon and repeat the call.
• Unlike checkout, this endpoint refuses a gateway that cannot handle headless payment with a 422 error instead of returning a redirect. To avoid this, check the supports_headless_payment_session value on the GET /store/billing/gateways endpoint in advance.

Choosing a Gateway This endpoint uses the invoice's own payment_method value unless you provide a gateway value, which pays with that gateway instead and records it on the invoice.

Redirect Methods With the stripe_dynamic gateway, an issued session offers the same redirect methods that WHMCS's own invoice payment pages offer, such as iDEAL or Bancontact, where the merchant enabled them. A session that the POST /cart/{cart_id}/checkout endpoint issues does not offer them, because the order form does not.

• For sessions that include a redirect, give the SDK a return URL of your own when you confirm. The shopper returns to your own page, not to WHMCS.
• Redirect methods update the invoice status asynchronously. As a result, expect the invoice to still be unpaid when they return.

Do Not Trust Input from the Return URL Never mark an order paid, grant access, or provision a service because a redirect_status value is succeeded. Instead, confirm the invoice status with WHMCS directly.

• For more information, see the settlement value's description on the PaymentSession schema.

Whether webhook handling recovers a confirmation you never make depends on the gateway, so read the per-gateway behavior on the confirmation endpoint before relying on it. Where it does apply, treat it as a backstop rather than as your settlement path, because it reports no outcome to your integration.

{
  "data": {
    "payment_session": {
      "provider": "stripe",
      "params": {
        "publishableKey": "pk_live_...",
        "clientSecret": "pi_3Abc..._secret_XyZ",
        "paymentIntentId": "pi_3Abc...",
        "mode": "payment"
      },
      "settlement": "sync_confirm",
      "sdk": {
        "scriptUrl": "https://js.stripe.com/v3/",
        "apiVersion": "2023-10-16"
      }
    }
  }
}