Web SDK

​

🚀 New features

This release introduces Apple Pay merchant tokens, a powerful new feature that enables merchants to process recurring payments, subscriptions, and automatic reloads without being tied to specific customer devices.

Ready to get started? Follow our implementation guides to request merchant tokens (MPANs) and integrate this feature into your payment flow.

​

🔧 Fixes

• Fix issue where vaulted Stripe ACH tokens could not be selected to make payments due to an error.

​

✨ Improvements

• Updated Payment types to include missing payment methods:
  • DLOCAL_PIX
  • ALMA
  • PAY_NL_RIVERTY

​

🔧 Fixes

• Google Pay - Minor bug fix in some edge cases where it was impossible to disable button through headless SDK.

​

🔧 Fixes

• Apple Pay - fixed a bug on headless that resulted in Checkout staying in loading state after cancelling Apple Pay payment sheet too quickly.

• Improves accessibility of hidden inputs

​

✨ Improvements

• Improved support for legacy mobile Safari versions by adjusting bundler settings.

• Resolved compatibility issues affecting early iOS 15 and iOS 16 releases.

Our testing confirms the SDK now works as expected on these older browsers.

​

✨ Improvements

Minor enhancements to the TypeScript types exposed by the package.

Fixed a bug that prevented the 3DS Flow from continuing in some timeout scenarios.

Bug fixes and improvements

Bug fixes and improvements

​

🚀 New feature

Introduced support for the ‘Continue payment flow’ workflow action to configure checkout outcome. See our documentation for more info.

​

🚀 New feature

• Improved TypeScript typings for vaulted payment methods

This release enhances the type safety of vaulted payment methods by refining our TypeScript definitions. These changes enforce stricter typing, which may surface TypeScript errors in projects that previously relied on loosely typed vaulted items.

​

🔧 Fixes

We’ve released a fix for Klarna payment method and added a missing onPaymentMethodAction callback. Now PAYMENT_METHOD_SELECTED and PAYMENT_METHOD_UNSELECTED events are triggered.

​

🔧 Fixes

• Fixed an issue where the payment method logo position, relative to the text, was sometimes ignored

​

✨ Improvements

• The SDK will now default to using Api version 2.4 when initialised. It is possible to use the previous defaults by setting legacy via options.apiVersion. For more information see our SDK reference, Api Reference and Migration Guides.

​

🔧 Fixes

• Surcharge information will not be displayed next to the card form when no surcharge is applied; the card form will not be automatically hidden when the surcharge is applied - use SDK Options to hide the card form if needed.

​

🔧 Fixes

• Fixed a bug in the Klarna session update flow, which may cause validation failures when the Klarna session is triggered and potentially prevent the session from updating correctly.

​

🔧 Fixes

• Fixed Google Pay OR_BIBED_15 error where the payment popup failed to open due to a network request. The popup is now triggered immediately upon clicking the Google Pay button, ensuring compliance with browser restrictions on user-initiated popups. As a result, any updates to the client session must now be refreshed manually in the SDK by calling refreshClientSession.

Deprecations

• Removed support for iDeal-V1 and the associated bank selector UI from the SDK. With iDeal-V2, users are now redirected to their own bank selector interface, making this functionality redundant. All existing integrations have been automatically migrated to iDeal-V2, requiring no further action from merchants.

​

🔧 Fixes

• Addressed an error (undefined is not an object) occurring with Apple Pay transactions.

​

🔧 Fixes

• Resolved an issue with the Klarna vaulting payment flow. Previously, the Klarna vaulting process was not operational due to missing properties. This fix ensures proper communication between the SDK, Primer and Klarna, enabling successful vaulting across all Klarna-supported payments.

​

🔧 Fixes

• Fixed missing TypeScript types for StripeACH options on showUniversalCheckout options. This resolves issues where TypeScript users encountered type errors when configuring StripeACH payments.

​

🔧 Fixes

• Fix double surcharge and top-level amount calculation for Google Pay

​

✨ Improvements

• With this release, we introduce a new property, apiVersion:

  • This property allows you to modify which API the SDK will use internally. By default, the previous API state is selected, ensuring backward compatibility. The new APIs are used by opt-in.

  • To use our new API 2.4 functionalities, set the apiVersion to “2.4”.

  • This update enables you to migrate to API 2.4 gradually without disrupting your existing integrations.

For more information, see our:

• SDK Reference

• API Reference

• Migration Guides

• Added support for iDEAL v2 via Adyen on Headless

Fixed an issue where onPaymentMethodAction wasn’t being triggered when closing a payment popup. In some specific instances, when a popup delegated payment method was closed before it fully completed its loading sequence, the SDK would fail to dispatch the relevant callbacks. This prevented merchants from constructing reliable logic for handling payment method actions.

​

🔧 Fixes

• Cardholder Name now supports non-Latin characters correctly.

​

✨ Improvements

• Removed two legacy SDK flows:

• Single Payment Flow: A simplified one-payment view that hasn’t been used in production for over a year. Its removal simplifies the codebase, improves maintainability, and strengthens the overall logic.

• Express Checkout: A legacy, unstable flow introduced in 2022, never officially released but present in TypeScript declarations and some code files. As we are not pursuing this approach further, all related code has been removed, simplifying the PayPal integration and client session logic.

• Amount checks on Apple Pay and Google Pay—We removed a client-side check for these payment methods, as it was no longer needed. Passing value 0 enables some specific vaulting flows.

​

✨ Improvements

• This release introduced several updates to the dependencies used by the web SDK, primarily related to TypeScript type generation, linting, and build pipelines.

• Notable customer-facing dependency updates include:

  • card-validator and credit-card-type, which are responsible for validating and recognizing cards client-side. Keeping these up to date ensures your clients won’t encounter issues with the card form.

  • @stripe/stripe-js, used to render the Stripe ACH payment form and its components.

• We have also improved the overall code quality and ensured more reliable execution.

​

🚀 New feature

Stripe ACH Vaulting is now available ✨

• We have added support for Vaulting for ACH via Stripe. ACH lets you accept payments from customers with a US bank account.

• Read about the prerequisites here

​

🔧 Fixes

We’ve released a fix to prevent the Google Pay OR_BIBED_15 error from happening on the Firefox browser.

​

🔧 Fixes

• Fixed the bug introduced in 2.46.0, which broke the localized error messages and displayed the error code in square brackets instead.

​

🔧 Fixes

This release addresses a Google Pay display item label bug introduced in 2.46.1. We’ve implemented a fix to ensure that a default label is set if neither the fee type nor line item description is provided, preventing missing labels that cause Google Pay errors.

For merchants using Google Pay, it is advisable to set both the line items description and fee type properties. For more details, please refer to the documentation:

• Item description

• Fee type

​

🔧 Fixes

• Bug fixes and improvements

​

🔧 Fixes

Fixed a regression where Safari autofill was not populating fields.

​

✨ Improvements

We’ve updated Klarna’s branding to reflect the latest guidelines.

You can now tailor the “Pay with” label on Klarna’s payment button using the buttonOptions property, enabling a more localized and relevant checkout experience based on your customers’ region and Klarna’s available payment methods. This feature is available for both direct Klarna integrations and through Adyen.

​

🔧 Fixes

• Klarna locale now defaults to en_US if the provided locale is not supported.

​

2.46.2

Skipped due to a pipeline error

​

🔧 Fixes

We’ve ensured compatibility of the SDK with older versions of Safari. Our logs indicated crashes related to the unsupported BroadcastChannel API in Safari versions earlier than 15.4, and this patch addresses those issues.

​

✨ Improvements

We’ve rebuilt our internal error and log reporting system to enhance debugging and issue resolution for your customers. This update improves stability and performance by removing external dependencies and ensuring that all unexpected errors are captured and reported.

Why Upgrade?

• We’re able to address issues affecting your clients proactively.

• Faster resolution of support escalation tickets, thanks to more detailed session analysis.

• Continued improvements to the stability and performance of our SDK.

​

🔧 Fixes

• Fix for Paypal - remove the condition check in SDK that would break PayPal for merchants that are passing top level amount property in the create client session request

​

🔧 Fixes

• Fix the translation of “Cardholder name” in Bulgarian

​

✨ Improvements

• Bug fixes and improvements

​

🔧 Fixes

• An issue that prevented the SDK from being re-initialized when clientSessionCachingEnabled is set to true has been fixed.

​

✨ Improvements

• CDN assets improvements

​

🔧 Fixes

• Fixed typescript definitions generation

​

✨ Improvements

Finnish, Korean, Catalan, Serbian, Slovenian, Ukrainian, Hebrew, and Indonesian languages are now supported.

​

✨ Improvements

Bug fixes and improvements

​

🚀 New feature

Stripe ACH is now available ✨

• We have added support for ACH via Stripe. ACH lets you accept payments from customers with a US bank account.

• ACH Direct Debit is a reusable, delayed notification payment method. It can take up to 4 business days to receive acknowledgment of success or failure.

• This release includes one-off payments and cancellation and refund actions. We aim to add support for recurring payments in the future.

• With just a few clicks through Primer, you can easily integrate ACH via Stripe into your payment stack. Visit the integrations section of the dashboard to learn more, or consult the direct integration guide.

​

🔧 Fixes

• Fixed a bug on Firefox where the user needed to double-tab to focus on input fields.

• Added missing id properties to the Payment Method buttons.

• Fixed an issue that prevented importing the Primer package on the server

​

✨ Improvements

We simplified the Headless Checkout public interface. The options can now be set directly in the second parameter of the createHeadless method. Please update your implementation by moving the options from the previous headless.configure method, which is now deprecated. Check the updated documentation for more details.

Note: This is a necessary update if you want to set the clientSessionCachingEnabled flag to true.

Client Session caching It is now possible to cache the ClientSession configuration client-side, which can speed up certain flows in the SDK. This can be enabled via the clientSessionCachingEnabled flag, both Headless and Drop-in. Before enabling the flag to true it’s recommended to reach out to Primer support for additional verification since there are edge cases where it is not advised.

​

✨ Improvements

• Bug fixes and improvements.

​

✨ Improvements

• A default font size for APM button text was added.

​

✨ Improvements

• Performance and monitoring enhancements.

​

✨ Improvements

• Enhanced reliability of configuration requests in poor connectivity conditions.

• Improved initialization script loading.

• Performance and monitoring enhancements.

​

✨ Improvements

• Performance and monitoring enhancements.

​

🔧 Fixes

• Fixed Headless PayPal to work correctly when paymentFlow is set to PREFER_VAULT.

​

🔧 Fixes

• Fixed an issue that prevented inputting card numbers with more than 16 digits.

​

🔧 Fixes

• Fixed an issue where client session updates did not set the amount correctly on Headless Google Pay.

​

🔧 Fixes

• We have fixed an issue in AssetsManager.getPaymentMethod. Previously, the paymentMethodName parameter would return the recommended button text for a payment method, which could be null for many payment methods. We have deprecated this parameter and added two new ones:

buttonText: This is the recommended button text, e.g., “Pay with Google Pay.” However, it may be null for certain Payment Methods.

displayName: This is the payment method name. E.g., “Google Pay”. This should be available for all payment methods.

From now on, please use these new parameters based on your use case. For more information, see our docs.

​

💳 New APM

​

iDEAL via Adyen

Adds the FormWithRedirectPaymentMethodManager that provides access to the configuration and methods necessary to:

• load a list of all supported banks

• submit user’s selection

For more information, see our payment method guide, and sdk reference docs for the FormWithRedirectPaymentMethodManager.

​

🚀 New Feature

• Drop-In: Card Security Code (CSC/CVV) recapture

  • Vaulted cards can now optionally capture the customer’s CVV, which sometimes can increase approval rate

  • To enable this feature, create a client-session with the option captureVaultedCardCvv

  • CVV cannot be vaulted because of PCI DSS

​

🔧 Fixes

• Suppress noisy logs for sessionStorage.setItem and navigator.sendBeacon when the browser does not support them, or they are disallowed by the user, or when they fail for any other reason

• Prevents iframes from going opaque when the browser is set with a different color-scheme

​

🔧 Fixes

• Upgraded Paypal order creation to the latest server-driven PayPal SDK

• We were using an old way of creating a PayPal order (via actions.order.create from PayPal’s JS SDK) that PayPal is deprecating in June 2024. This version upgrades a PayPal payment method order creation using Orders v2 APIs and PayPal JavaScript SDK

• We introduced a change in the metadata field that is passed when creating a client session. Previously orderId in the client session would be passed to PayPal as the custom\_id. Now you have to pass paypal_custom_id  in the metadata.

​

🔧 Fixes

• Headless now correctly triggers onPaymentMethodAction events

• Now shows the loading spinner when a payment is being processed and the card payment method is not available

​

🔧 Fixes

• 3DS popup buttons not being clickable

• Headless hosted inputs default height

​

🔧 Fixes

• Checkout options stylesheets

• Rename icon className to avoid CSS conflicts

• Change the default CVV input size to 4 digits

• Use redirect instead of popup when in an in-app browser

• Hide the loading spinner when there are no payment methods available

• Prevent PayPal from being stuck in infinite loading

​

🔧 Fixes

• Resolved an issue that caused low authorization rate with Apple Pay for certain processors such as Cybersource when the user’s billing address was missing either the first name or last name on their Apple Pay wallet. If Apple Pay is configured to capture the billing address, users will now be prompted with an error message within Apple Pay’s sheet indicating that they need to fill out the missing first name or last name in their Apple Pay wallet in order to proceed with the payment.

• Various internal improvements to enhance overall system stability and performance.

​

🔧 Fixes

• Fixed a regression bug introduced in v2.37.0 that showed an error “This merchant is having trouble accepting your payment right now. Try using a different payment method. [OR_BIBED_06] OR_BIBED_06” when the user selected Google Pay, preventing them from paying.

• You should now be able to propose Google Pay seamlessly as before.

​

🚀 New Feature

• Support for Klarna Headless

  • Our Klarna integration is now available on Headless Checkout on Web. Flows supported:

    • Pay now

    • Pay later: Pay in 30 days

    • Pay over time: Pay in 3-4 installments. First payment right away then the rest in installments (no interest)

    • Fair financing: Installment plans of 6, 12, 24, and 36 months with flexible payments (with interest)

  • The docs are available here and the Klarna Payment Manager reference is here.

• Support for Klarna EMD

  • Klarna may request extra merchant data (EMD) based on the merchant segment or consumer services. This additional information helps Klarna enhance risk assessment and improve conversion rates.

  • You can now dynamically pass any relevant EMD package via the Client Session as described here. Available schemas are documented here

​

🔧 Fixes

• Fixed an issue with Klarna that caused the Klarna view to expand and then collapse when switching between payment categories.

• Fixed an inconsistency in the input’s metadata for Headless Vault Manager CVV recapture. Developers can now rely on the “input.metadata.valid” property to be their source of truth when checking if the validations have passed.

​

🚀 New Feature

• Added support for iDEAL via Adyen on Headless

​

🔧 Fixes

• Provide translated error message for CVV required error on Headless Checkout Vault Manager in cvvInput.metadata.error

• Note that cvvRequired errorCode is still exposed in cvvInput.metadata.errorCode property

​

🔧 Fixes

• Build artefact (webpack) that prevented npm package to run correctly in the browser

​

🚀 New Feature

• Support for co-badged cards on Headless Checkout (documentation will come soon)

​

🚀 New Feature

• Added Drop-in payment method: iDEAL via Stripe

​

🔧 Fixes

• Drop-in Checkout’s submitButton.amountVisible setting now correctly displays amount for card payments in the “Pay” button

​

🔧 Fixes

• Validation for card information when using browsers’ built-in autofill is now more reliable, especially on Safari

​

✨ Improvements

• Optimized bundling for the core package and all payment methods

  • This should result in the SDK loading up to 30% faster

​

🔧 Fixes

• Fixed an issue with Klarna items using “description” rather than “name”

​

🚀 New Feature

• Add support for initializing Paypal with a “capture” intent

​

🔧 Fixes

• Card autofill when using browsers’ built-in autofill, especially Safari

​

✨ Improvements

• Improve usage analytics

​

🔧 Fixes

• Fix Klarna’s shipping fees and calculation for tax rates

• Fix server side rendering

​

🔧 Fixes

• Fix the Drop-In and Headless Checkout not honouring the allowedCardNetworks configuration option.

​

✨ Improvements

• Improve performance of analytics on the SDK, now calls will be made when the user device is idle and won’t slow down the payment flow

​

🔧 Fixes

• Prevent unwanted retries of calls to Primer API

​

✨ Improvements

• Add addEventListener alias for the addListener method of CVVInput

​

🔧 Fixes

• Fix CVVInput events not being triggered

​

🔧 Fixes

• Update Klarna button to better adhere with their guidelines

• Fix an issue with Drop-in that could happen when both Multibanco and Blik were active in the same session (which is extremely unlikely)

​

🔧 Fixes

• Activate 3DS when cards are not configured in checkout builder. This ensures that 3DS can be triggered even if only Google Pay or Apple Pay are presented.

​

🔧 Fixes

• Fix 3DS not appearing properly in Headless Checkout

• Fix an issue that prevented users to pay with a vaulted PayPal account if a card is also present in the vault

​

🔧 Fixes

• Fix an issue that caused onResumeSuccess to be called with an undefined resume token when forceRedirect is set to true

• Improve the logic for setting the size of the 3DS window

• Fix an issue raised in 2.32.0: the CVV input now forwards a cvvRequired error if the user has not yet interacted with it

​

🚀 New Feature

​

Headless Vault Manager

Add PrimerHeadlessCheckout.createVaultManager() which returns an instance of HeadlessVaultManager. It provides the following features:

• fetch a list of vaulted payment methods

• delete a vaulted payment method

• perform a payment using a vaulted payment method

• create an input to collect the CVV for a vaulted payment method

​

🐛 Known issues

• The CVV input does not forward a cvvRequired error if the user has not interacted with it.

• This has been fixed in 2.32.2

​

✨ Improvements

• Allow PayPal button to take the full width available

​

🔧 Fixes

• Fix a regression introduced in 2.28.1 that prevented onCheckoutFail from returning the payment object when available

​

🚀 New Feature

​

Validate cardholder name

Add validation for cardholder name so that only Unicode Latin alphabet no.1 characters are allowed, which should improve 3DS pass rates.

​

✨ Improvements

• Change the “CVV” label to “Security code” in Japanese.

​

🔧 Fixes

• Fix an issue that caused a crash when closing Adyen Klarna’s redirect popup window. The issue was introduced in 2.30.0.

• Fix onPaymentMethodAction on Web not being triggered with Klarna.

​

🚀 New Feature

​

Popup windows fallback to redirect

When popup windows are not supported - either because they were blocked by the browser, or one of its extensions/plugins, or any other reason - payment methods that would open them will instead redirect the current page.

Read the guide on how to handle redirects in order to ensure maximum compatibility.

• This is a fallback mechanism, when popup windows are supported they will continue to open as expected.

• forceRedirect is still supported.

​

✨ Improvements

• Update english translations

​

🔧 Fixes

• Fix a bug where the submit button was disabled when moving to another screen and coming back to the checkout home, while any vaulted payment method was present.

• Enable the Apple pay button to work within a form tag

​

🔧 Fixes

• Fix an issue that caused onCheckoutFail to not be called when the payment ends up with a PENDING status and no required action. This could happen in the case of Atome when the user clicks “Back to merchant”

• Fix a bug that caused the flag form.inputLabelsVisible to also hide surcharge labels

• Improve surcharging support for PayPal when paypal.paymentFlow is set to PREFER_VAULT

​

✨ Improvements

• Improve internal visibility

​

🔧 Fixes

• Fix a race condition on Drop-in Checkout that caused card input fields to not appear

• Fix an issue that broke server-side rendering (crypto not defined or navigation not defined)

• Fix an issue causing screens to disappear after calling refreshClientSession

• Improve API error handling

​

🔧 Fixes

• Fix a race condition on Headless that caused card input fields to not appear

• Fix an issue that prevented surcharging to be displayed for amex and diners club

• Fix the typescript definitions of the main SDK functions

​

🔧 Fixes

• Fix an issue that prevented the UI of card surcharge to be updated after refreshClientSession() is called

• Add warning messages when Adyen via Klarna does not receive any payment method to display

​

🐛 Known issues

• If a surcharge for a card network is set, then removed after calling refreshClientSession(): the UI can fail to display the card fields

• The checkout behaves strangely when surcharge is setup then removed or the other way around

​

✨ Improvements

​

Google Pay now capture billing address information! 🥳

Universal Checkout | Payment Methods

When initializing the checkout, you can now pass an additional setting to enforce billing address capture when your customers checkout with Google Pay.

    Primer.showUniversalCheckout(clientToken, {
    googlePay: {
    captureBillingAddress: true // defaults to false - not required
    }
    })

​

🔧 Fixes

• Improve error handling when initializing the SDK

• Fix a regression from 2.25.1 issue that raised a malformed client token bug when the user selects a redirect-based payment method

​

✨ Improvements

​

The SDK now speaks Chinese, Thai and Malay 🌐

Universal Checkout | Locales

Your checkout can now display in any of the following new languages:

• Mainland Chinese (simplified characters) zh-CN

• Thai th

• Malay ms

It also has partial support for:

• Chinese from Hong-Kong zh-HK

• Chinese from Taiwan zh-TW

Chinese card details

​

✨ Improvements

Universal Checkout | Payment methods

This new version now forwards to Klarna all updates of the client session’s order.

This enables you to display a checkout with Klarna right next to a cart view or a voucher field that can modify the amount.

To implement this, make sure to call checkout.refreshClientSession()

const checkout = await Primer.showUniversalCheckout(clientToken, options);
// After you patched the client session
await checkout.refreshClientSession();

​

​

🔧 Fixes

• Headless Checkout’s onAvailablePaymentMethodsLoad is now working properly

• Improved the support for specific versions of Webpack (window is undefined error)

• Improved the error handling of the client token

​

✨ Improvements

​

Load time improved by ~20% 🏃‍♂️

Universal Checkout | Performance

We are on a journey to create the most performant checkout available out there 🚀

Of course, this means reducing the time to load the SDK and present payment methods to your user 💪

This new version brings a few internal changes to how the SDK is loaded that decreases the load time by about 20%!

​

Known issues

Headless Checkout’s onAvailablePaymentMethodsLoad is not working properly on this release. This has been addressed on v2.26.1.

The validation of arguments passed to the main Primer functions is not working. This will be addressed in a new release. This has been addressed on v2.26.1

​

✨ Improvements

​

Add Processor 3DS to Headless Checkout

Headless Checkout | Processor 3DS

When a processor does not enable Primer to use their agnostic 3DS, Primer automatically falls back to using their proprietary 3DS when possible.

This was already possible with the Drop-in Checkout - it is now supported by Headless Checkout! 🎉

When Processor 3DS is requested, Headless Checkout automatically displays an in-context modal view with the 3DS challenge!

​

✨ Improvements

​

✨ Improvements to Google Pay!

Universal Checkout | Payment method

Google Pay SDK has recently received a face lift that enables merchants to further customize the Google Pay button!

Pass buttonSizeMode to the Google Pay options to define if the button should take the full size of the container, or if it should be static.

• Supported values are fill and static

• ⚠️ This mechanism replaces the buttonType values short and long.

Pass buttonType to set what should be displayed on the Google Pay button.

• buy (default)

• book

• checkout

• donate

• order

• pay

• plain

• subscribe

Google Pay Buttons

Primer.showUniversalCheckout(clientToken, {
/\* Other options \*/
googlePay: {
buttonSizeMode: 'fill',
buttonType: 'subscribe'
}
});

​

​

🔧 Fixes

• Fixed an issue with the sub-units of the currencies CRC, COP and HUF

​

✨ Improvements

​

iDeal via Worldpay! 🥳

Universal Checkout | Payment Methods

This version introduces another iDeal integration method: this time with Worldpay 🎉

Select your bank

​

✨ Improvements

​

Better support for manager types

Universal Checkout | Integration

In the previous version, the callback onAvailablePaymentMethodTypes only returned a list of payment method strings. This made it difficult for developers to know how to implement each payment method.

The new callback introduces the concept of managerType : each payment method has a managerType that describes which payment method manager to instantiate.

This enables you to implement a whole payment method category in one go!

// Before
headless.configure({
// Other options
onAvailablePaymentMethodsLoad(paymentMethods) {
// paymentMethods is a list of strings representing the unique id of the payment method
}
})
// Now
headless.configure({
// Other options
onAvailablePaymentMethodsLoad(paymentMethods) {
// paymentMethods is a list of objects containing
// - `type`: the unique id of the payment method
// - `managerType`: the type of payment method manager. Can be `CARD`, `NATIVE`, or `REDIRECT`
}
})

​

​

Get access to the icons and names of payment methods on headless

Universal Checkout | Integration

For most payment methods, you have full control over how the payment method should be presented. To assist you, Primer exposes the AssetsManager  that enables you to retrieve the logo and main colors attached to each payment method.

const assetsManager = headless.getAssetsManager()
const { iconUrl, paymentMethodName, backgroundColor } = await assetsManager.getPaymentMethodAsset('ADYEN\_IDEAL') // ADYEN\_IDEAL comes from `paymentMethod.type`

​

​

Redirect payment methods are on Headless Checkout 🚀

Universal Checkout | Integration

Some payment methods require the user to be redirected to another web page to capture its payment details. Headless Checkout on Web now supports these types of payment methods👩‍💻

Head over to the documentation to implement these payment methods!

When the user selects the payment method, call the start function. This function automatically:

• opens a popup to present a loading indicator, then the payment method web page

• shows an overlay on top of your page that prompts the user to focus on the popup

​

🔨 Fixed

• Fixed a bug causing Apple Pay to not properly handle currencies without minor units

​

🔨 Fixed

• Address bug which caused an internal API validation error when receiving a billing address back from Apple Pay without the state field.

​

✨ Improvements

​

Added onPaymentCreationStart callback

Universal Checkout

• You will now be able to rely on the onPaymentCreationStart callback to get notified before the checkout attempts to perform the following actions:

• Tokenize the selected payment method

Create a payment

const checkout = await Primer.showUniversalCheckout(clientToken, {
container: '#container',
onPaymentCreationStart() {
// will be called before tokenization and payment creation
// will be followed by calls of either onCheckoutComplete
// or onCheckoutFail
},
onCheckoutComplete({ payment }) {
console.log('onCheckoutComplete', payment);
},
onCheckoutFail(error, { payment }, handler) {
console.error('onCheckoutFail', error, payment);
handler?.showErrorMessage(');
},
});

​

​

🔨 Fixed

• Addressed bug which caused iframe events to not be fired with headless checkout implementation.

​

✨ Improvements

​

Apple Pay, Google Pay and PayPal are landing on Headless Checkout 🚀

Universal Checkout | Integration

Headless Checkout on Web now supports Apple Pay, Google Pay and PayPal 👩‍💻

With this new release, you can now ask Primer to display a button anywhere on the screen - and the SDK takes it from there!

Payment methods

Head over to the documentation to implement these payment methods!

​

🔨 Fixed

Fix an issue that prevented headless to work using our npm package

​

🔨 Fixed

• Address bug which caused the cardholder name to not be tokenized along with the other card information.

• Addressed bug which caused the onPaymentMethodAction callback to not be called.

​

✨ Improvements

​

Klarna via Adyen! 🥳

Universal Checkout | Payment Methods

You will now be able to avail Klarna via Adyen for your customers. Klarna allows multiple payment options depending on the country in which the order is created.

Klarna

​

🔨 Fixed

• Fix bug where the card number input could not detect the AMEX card network type.

• Addressed edge case where a payment is created with an empty card form, resulting in an error. In this case, onCheckoutFail will now be called.

​

🔨 Fixed

• Fix an issue with a 404 happening when loading the SDK in server-driven environments

​

✨ Improvements

​

[BETA] Introducing Headless Checkout for complete customization! 🚀

Universal Checkout | Integration

Universal Checkout on Web currently features an amazing drop-in UI that you can integrate with just a couple of lines of code 👩‍💻

A few months ago, we introduced Headless Universal Checkout for mobile platforms, providing more flexibility and control over the checkout experience. Headless checkout has received positive adoption, so it’s time to bring this integration type to our Web SDK! 🎉

From this version onward, in addition to the drop-in integration, Web SDK enables you to start a headless checkout integration 🚀

What’s truly amazing is that headless checkout brings all the core Primer concepts that simplify your life as a developer 💪

So the creation of client sessions, the handling of payments in a PCI-compliant way, and the configuration of checkout via the Dashboard without a line a code work exactly the same way as with the drop-in integration 🎉

With Headless Universal Checkout: you just have to focus on the UI while we take care of the rest 👌

const headless = await Primer.createHeadless(clientToken);
await headless.configure({
onAvailablePaymentMethodsLoad(paymentMethodTypes) {
// Handle payment methods
},
onCheckoutComplete({ payment }) {
// Show success screen
},
onCheckoutFail(error, { payment }, handler) {
// Show checkout fail
return handler.showErrorMessage();
}
});

​

Check our guide on headless checkout to get started!

​

✨ Improvements

​

Bancontact Debit via Adyen 🏦

Universal Checkout | Payment Methods

Your customers can now checkout with Bancontact Debit via Adyen using their bank card.

When your customer selects ‘Bancontact Pay with card’, they are then taken to a card form to enter their card details, where the CVV is not required.

Bancontact

​

✨ Improvements

​

Gift Card via PayNL KaartDirect! 🎁

Universal Checkout | Payment Methods

You will now be able to offer a tailored gift card payment method button to your customers via PayNL KaartDirect.

​

🔨 Fixed

• Fix submit button being disabled when no APMs are loaded

​

✨ Improvements

​

Disable checkout autofocus! 👀

Universal Checkout | Customization

When initializing the checkout, you can now pass an additional setting within the style object which disables the checkout from autofocusing the first available payment method or card input field.

​

EPS via Adyen 🏦

Universal Checkout | Payment Methods

Your customers can now checkout with EPS via Adyen. This payment method exposes a list of banks which your customer can select to complete a payment with.

​

🔨 Fixed

Add back support for onErrorMessageShow and onErrorMessageHide callbacks which notifies you of when to display your custom error message when using the manual payment flow.

​

The start of Server Driven Payment Methods! 👏

To speed up the implementation of payment methods, we have begun building out a frontend framework so we don’t need to build the frontend of every new payment method we integrate with! Instead, we can leverage the framework and render the frontend using a preset configuration. This also means that merchants will no longer need to keep upgrading SDK versions to get access to new APMs.

We have started this big project by rolling out this framework for Redirect APMs. So, going forward from this version onwards, all Redirect APMs will be server-driven and don’t require an SDK upgrade to get access to any new ones we integrate with! 🥳

​

🔧 Fixes

• Update Clearpay naming to be Afterpay in the overlay dialog and loading page

• Enable our instance of PayPal to work if another instance of PayPal is running within the same window. The PayPal button now renders even if the merchant application is running a separate instance.

​

✨ Improvements

​

Apple Pay now capture billing address information! 🥳

Universal Checkout | Payment Methods

When initializing the checkout, you can now pass an additional setting to enforce billing address capture when your customers checkout with Apple Pay.

Primer.showUniversalCheckout(clientToken, {
applePay: {
captureBillingAddress?: true // defaults to false - not required
}
})

​

​

setClientToken → refreshClientToken 😎

We’ve improved the experience when patching a client session

When you patch a client session by calling the PATCH /client session endpoint, you now no longer have to notify the checkout by calling setClientoken(clientToken) , there’s now a simpler alternative:

const checkout = await Primer.showUniversalCheckout(clientToken, {
// provide your settings
})
// This will result in the checkout
// being updated after patching a client session
checkout.refreshClientToken();

​

​

🔨 Fixed

• The checkout now no longer fails to apply surcharging to American Express cards

​

✨ Improvements

​

Better Klarna support! 🤯

Universal Checkout | Payment Methods

We’ve introduced a bunch of changes to ensure that Klarna is now much more stable across many more scenarios:

• We’ve expanded the locale, country code and currency support for Klarna. You’ll now be able to serve your customers better with Klarna across multiple territories.

• Klarna now works when passing tax in the client session. Feel free to add your tax amounts to each line items and Klarna will be able to interpret it as such.

• Klarna now also supports passing a discount amount. Passing a discount amount in the client session will be interpreted correctly by Klarna.

​

🔨 Fixed

• Fixed bug which caused SDK to crash in Safari browsers. This bug has been persisting since v2.5.0 of the Web SDK

​

✨ Improvements

Klarna now accepts the state property passed in the customer.billingAddress and customer.shippingAddress fields.

​

🔨 Fixed

• Adyen now receives the required information for performing 3DS

​

✨ Improvements

More payment methods incoming!

​

Bancontact - Payconiq via Adyen! 🤯

Universal Checkout | Payment Methods

When checkout out using Bancontact - Payconiq your customer is redirected to the app either directly on their mobile device, or by scanning a QR code on Desktop.

​

Omise from the far east 🌅

Universal Checkout | Payment Methods

We’ve added support for PromptPay and Truemoney via Omise. These payment methods can be used to serve your customers in Thailand. PromptPay

Your customers will be able to pay using PromptPay by following a redirect after scanning the provided QR code using their mobile phones.

Truemoney

A popular e-wallet in Thailand, your customers can now select it as an option in the checkout and be redirected to complete their payment.

​

✨ Improvements

The release train has arrived! 🚂

​

Multibanco via Adyen has arrived! 🎉

Universal Checkout | Payment Methods

You can avail Multibanco via Adyen to your customers! Multibanco is a Portuguese Payment Method which allows customers to complete payments outside of the checkout’s context.

​

PacyPay payment methods incoming! 🎉

Universal Checkout | Payment Methods

We’ve added support for both Alipay+ and WeChat pay via Onerway

AliPay+ & WeChat Pay

​

We’ve added support for Afterpay! 🎉

Universal Checkout | Payment Methods

Afterpay (Clearpay) is a Buy Now Pay Later payment method in the UK, France, Spain and Italy which offers customers the option to pay in 4 interest free instalments! 😎

​

Increased control over payment method actions 🔍

Universal Checkout | Payment Method Callback

There are times when you would want to know (in real time), which payment method was selected by the customer. This added transparency allows you to perform actions, like updating your UI when a payment method is selected/unselected.

To receive updates on which payment method was selected by a customer, you can now make use of the onPaymentMethodAction callback.

const options = {
/\* Other checkout options ... \*/
onPaymentMethodAction(action, { paymentMethodType }) {
// Notifies you when a specific payment method has been selected or unselected
// action will either be 'PAYMENT\_METHOD\_SELECTED' or 'PAYMENT\_METHOD\_UNSELECTED'
},
};

​

As an example, selecting a payment method could result in displaying product recommendations that are commonly associated with customers who use that payment method. Additional context on when a customer unselects a payment method is also provided, which again gives you an opportunity to customize the customer experience.

More visibility. More control. More happy customers.

​

✨ Improvements

A small release, but we all know about dynamite and small packages

​

MB all the WAY 💸

Universal Checkout | Payment Methods

We’ve added support for MBWAY via Adyen 🎉 MBWAY is a leading payments app in Portugal. Our integration will allow your customers to pay using their phone numbers and complete their payments from their MBWAY apps.

​

✨ Improvements

New payment methods and a couple of UI improvements!

​

Paytrail and Payshop via Adyen is now supported 💰

You can now use Paytrail and Payshop via Adyen.

Paytrail & Payshop

​

Improved error handling 🔴

Universal Checkout | Payment Methods

If no payment methods are returned, you will now be notified in onCheckoutFail

Before, an error would be logged in the console if no payment methods were loaded, but now you can adapt your UI in the case that no payment methods could be retrieved for the given checkout session.

​

Bug fixes 🐛

• Autofocus will now be applied to the first field in the card form and won’t automatically jump to the cardholder name input.

​

✨ Improvements

This release contains a host of exciting new features!

​

Amount on submit button 💰

You can now display the amount charged to the customer on the submit button 😎

Submit Button

To avail the amount on the submit button, you can pass submitButton.amountVisible: true as a checkout option:

const checkout = await Primer.showUniversalCheckout(clientToken, {
container: '#container',
submitButton: {
amountVisible: true,
}
}

​

​

Trigger card form submission on enter press ↩️

Universal Checkout

You no longer need a mouse to make card payments 🙃

Submit on Enter

​

iDEAL via PayNL now uses a dedicated bank list 🏦

Universal Checkout | Payment Methods

Select a bank

In order to create a more native experience when using iDEAL via PayNL - customers are now able to select the bank of their choosing via the checkout’s UI.

Before, iDEAL via PayNL would redirect customers away to a page where they could select a bank of their choosing.

In the future, we will be able to support this feature for all processors supporting iDEAL which returns a bank list.

​

Klarna now supports passing a product type 🤝

Universal Checkout | Payment Methods

Klarna is now able to receive information regarding the product type of a specific line item.

When creating a client session, a productType can now be specified for each lineItem:

{
// other client session options
"order": {
"countryCode": "SE",
"lineItems": [
{
"amount": 500,
"description": "Voucher",
"quantity": 1,
"itemId": "ABC123",
"productType": "DIGITAL" // digital product
},
{
"amount": 1500,
"description": "Blue Shoes",
"quantity": 2,
"itemId": "XYZ123",
"productType": "PHYSICAL" // physical product
}
]
},
}

​

​

🔨 Fixed

We’ve been on a bit of a rampage… 🐛 🔨

• The submit button is no longer enabled when the PayPal dialog is closed quickly, leaving no payment method in a selected state

• Expanded locale and country code support for Klarna. The Klarna button should now render for the Irish 🇮🇪 🍀

• All inputs within the checkout now display custom focus and hover styles correctly

• Addressed issue where some payment methods failed when using currencies without minor units

​

✨ Improvements

This release adds support for several new payment methods and languages, meaning your checkout is accessible to even more people around the world 🌍

​

Added support for four new payment methods 🎉

Universal Checkout | Payment Methods

Thanks to our work with Rapyd, your checkout can now support the following payment methods:

• GrabPay

• Poli

• Gcash

• PromptPay

• Fast

​

New locales 💬

Universal Checkout | Locales

Your checkout can now display in any of the following new languages:

• Czech cs

• Estonian et

• Croatian hr

• Japanese ja

• Lithuanian lt

• Portuguese - Brazil pt-BR

• Vietnamese vi

​

🔨 Fixed

• Fix position of saved payment method dropdown on mobile

• Klarna now allows updating the amount while the SDK is rendered

​

🔨 Fixed

• Fixed a misalignment issue occurring in the vault when a Right-to-Left language is used

• Improved support for currencies: non-decimal currencies such as the Japanese Yen and Vietnamese Dong are now supported 🎉

​

✨ Improvements

This release is all about better localization 🗣️age

​

Right to left language support ↪️ ↩️

Right to left languages will now read the way they should 😎

Submit

Arabic reading right-to-left

ALT

No additional setup is required to enable right-to-left ✨

​

New locales 💬

Universal Checkout | Locales

The SDK now supports an additional Spanish dialect - Argentinian:

Argentinian Spanish es-AR

​

🔨 Fixed

• Fixed a TypeScript bug that cause showUniversalCheckout to return an instance of VaultManager. showUniversalCheckout now returns type UniversalCheckout.

​

✨ Improvements

Added new locales!

​

New locales 💬

Universal Checkout | Locales

The SDK now supports the following languages:

• Bulgarian bg

• Hungarian hu

• Romanian ro

• Russian ru

• Slovak sk

​

✨ Improvements

Added support for processing payments using processor’s 3DS flow for Stripe and Rapyd.

​

[BETA] Pay in installments with 2c2p ! 🎉

Universal Checkout | Payment Methods

Universal Checkout now enables customers to pay in installments with their cards or bank accounts using 2c2p! This processor will display a “Pay in installments” button that redirects the user to 2c2p’s hosted payment page.

This processor is currently in beta while we finalise the implementation of additional actions

​

Updated buttons for Coinbase and Opennode! 💅

Universal Checkout | Payment Methods

We’ve applied a few tweaks to the buttons of the payment methods Coinbase and Opennode!

Coinbase

This button now features a nice wallet icon!

​

Improved support for PayPal! 🎉

Universal Checkout | Payment Methods

Universal Checkout now sends additional information to PayPal:

• If lineItems is provided in the client session, the item breakdown will be passed to the PayPal

• If orderId is provided in the client session, PayPal’s custom\_id will be passed to PayPal

​

🔨 Fixed

• Fixed a bug that prevented formSpacings from being applied to the friendly card name

• Fixed an error raised in the console in the Vault Manager when the user clicks on a saved payment method

​

✨ Improvements

The version 2 of the SDK is out! This includes a simplified way to integrate Primer

​

🚀 Get started in one line of code!

Universal Checkout | SDK

Now you can harness the power of Primer even faster! We’ve followed our mantra of; “The best DX is no DX”, and slimmed down the Web SDK integration to just a single line of code 🤯

Before 🥱

const Primer = await loadPrimer(); // If the package is loaded from npm
const primer = new Primer({ credentials: { clientToken }});
const checkout = await primer.checkout(options);

​

Now 🚀

// To initialize Universal Checkout
const universalCheckout = await Primer.showUniversalCheckout(clientToken, options);
// To initialize Vault Manager
const vaultManager = await Primer.showVaultManager(clientToken, options);

​

By calling Primer.showUniversalCheckout , you’re configuring, initializing and availing the checkout to your customers in just one step.

The boilerplate might have been reduced, but all the great functionality of the checkout has been maintained 💪

​

✨ Payments created automatically

Universal Checkout | SDK

Creating payments with Universal Checkout is now seamless. There’s no more need for callbacks, API calls and headaches to create a payment. It’s all done under the hood 🧙

In the past, creating payments involved manual payment handling: On the client side, you would have had to implement the dreaded onTokenizeSuccess and onResumeSuccess callbacks:

primer.checkout({
onTokenizeSuccess(paymentMethodTokenData) {
// Implement some verbose logic 🤢
},
onResumeSuccess(resumeTokenData) {
// Do it all again 😵
}
})

​ On the server side, you had to manually call our Payments API in order to create a payment 🤷

Rejoice! As from version 2.0.0 no manual payment handling is required! Payment creation is now, as mentioned above, :chef-kiss: - seamless.

Feel free to rip out the above mentioned callbacks when migrating to version 2.0.0 and enjoy the feeling of utter relaxation as all your payment handling is now done by Universal Checkout 💆

​

💳 Dummy Payment Methods

Universal Checkout | Payment Methods

We want you to start creating payments with Universal Checkout as quickly as possible, so we’ve added some dummy payment methods - no credentials required 😎

The following payment methods have been added:

• PayPal via Primer

• iDeal via Primer

• Klarna via Primer

• Cards via Primer

These payment methods are purely for demonstrative purposes and aren’t tied to any payment method specific environment.

You can now create payments in different states (authorized, declined, failed) and see them in the dashboard’s Payments page.

No need to create sandbox accounts with different processors/payment methods, the dashboard and all its great features can now be used without any setup.

​

🔨 Deprecation

The Web SDK’s move to version 2 has brought a lot of exciting changes and along with these changes, some deprecations.