Buy now, pay later
PaymentKit.js supports three buy now, pay later (BNPL) payment methods: Klarna, Afterpay, and Affirm. All three share the same flow — there are no input elements to mount. When you submit, the customer completes approval on the BNPL provider’s page. You choose how that page opens with the required flowType option: in a popup window, where PaymentKit.js polls for the result and resolves your onSuccess or onError callback, or by redirect, where the customer leaves your page and comes back on your checkout session’s success_url. See Popup or redirect.
Setup
Register only the BNPL methods you plan to offer — each one is independent.
CDN
NPM/ES Modules
Submit payment
Like PayPal, BNPL methods don’t need input elements. Submit directly when the customer clicks your Klarna, Afterpay, or Affirm button. Pass the matching paymentMethod name ('klarna', 'afterpay', or 'affirm') and the required flowType:
With flowType: 'popup', PaymentKit.js opens the provider’s approval page in a 600×700 popup window and polls the payment status every 2 seconds. If the customer closes the popup without completing approval, the submission fails with a “popup closed by user” error after a grace period. The grace period is 3 seconds for Klarna and Affirm, and 5 minutes for Afterpay, because Afterpay’s popup can report closed while the customer is still paying. If status requests get no answer for the whole grace period plus 30 seconds, the error is “payment status could not be confirmed” instead, because the payment may have succeeded.
With flowType: 'popup', the submit must be triggered by a direct user action (button click) to avoid being blocked by popup blockers. If the browser blocks the popup, the submission fails with an error before any payment starts.
Need to run your own validation before the charge? Pass beforeConfirm in options. With flowType: 'popup', the popup opens synchronously on tap, but PaymentKit waits for beforeConfirm before navigating it to the provider. Reject and the popup closes without the provider ever seeing the request. See Pre-charge validation.
Popup or redirect
flowType is required on every BNPL submit, and PaymentKit.js never switches between the two on its own. You choose, because the two flows hand you the result in different ways:
Some in-app browsers refuse to open popups at all. The Google app on iOS (user agent contains GSA/) does this every time, and some social-app in-app browsers such as Instagram and Facebook can too. In those browsers the popup flow fails with Failed to open Klarna popup. Please allow popups for this site., and the customer has no way to allow it. Detect those browsers yourself (for example from the user agent) and submit with flowType: 'redirect' instead:
With flowType: 'redirect':
- PaymentKit.js starts the payment and sends the customer to the provider in the same tab. Your page unloads, so
onSuccessandonErrornever fire for a submit that left the page.onErrorstill fires for a submit that fails before leaving: invalid options, a rejectedbeforeConfirm, or a failed start request. - After the customer approves, cancels, or fails at the provider, PaymentKit verifies and records the outcome, then redirects the customer:
- on success, to the checkout session’s
success_url; - on cancel or failure, to the checkout session’s
return_url. PaymentKit appendscheckout_session_idandstatus(success,cancelled, orfailed) to that URL as query parameters. It also replaces a{CHECKOUT_SESSION_ID}placeholder in either URL with the session id. Set these URLs when you create the checkout session.
- on success, to the checkout session’s
- On that page, read the result from the query string and verify it on your backend (for example by fetching the checkout session or from your webhooks). Do not treat the landing alone as proof of payment.
If the customer comes back before the provider has settled the payment, PaymentKit shows a short “finishing your payment” page that keeps checking and redirects the customer as soon as the outcome is final.
If you route PaymentKit.js through your own custom domain (the apiBaseUrl constructor option), the return trip from the provider goes through that domain too, as long as it is your account’s active custom checkout domain. Otherwise the return trip uses the PaymentKit platform host.
Options
Saving Klarna for future payments
Klarna supports saving the payment method during checkout for future off-session charges (for example, subscriptions). Pass setupFutureUsage: true in the submit options:
setupFutureUsage is only supported by Klarna. Afterpay and Affirm do not support saving the payment method — their TypeScript submit option types omit the field, and the SDK never sends it for those methods.
Error handling
Each BNPL method returns its errors under its own key — errors.klarna, errors.afterpay, or errors.affirm — as descriptive strings. Validation errors use errors.processor_id and errors.customer_name; a missing or invalid flowType is reported under the method’s own key:
The table below uses Klarna as the example; for Afterpay and Affirm the error field is afterpay / affirm and the provider name in the message changes accordingly. The popup-blocked, closed, status, and polling errors apply only to flowType: 'popup'. A flowType: 'redirect' submit reports only the errors that happen before the customer leaves your page: validation, start failed, no approval URL, could not start, and checkout error. After the page leaves, the outcome reaches your session’s return URL, not onError.