Saved Payment Methods

If your application has its own login system, you can connect it to the Embedded Checkout widget so that your users can access their saved payment methods during checkout.

By default, users check out as guests and must enter their payment information each time. By providing a getJwt callback with a JWT (JSON Web Token) from your identity provider, the widget will recognize the user and make any previously saved tenders available to them.

⚠️
Before You Begin
Saved tenders require configuration on the PaymentExpress side before they will work. Please contact your PaymentExpress representative before starting this integration so that we can:

Register your identity provider with your site.

Enable saved tenders for your site configuration.

Without this setup, the widget will raise an error if getJwt returns a token. Please ensure configuration is complete before going live.

How It Works

When the checkout widget loads, it calls your getJwt callback to obtain a JWT from your identity provider.
PaymentExpress verifies the token and validates the email address associated with it.
If the token is valid and the email is verified, the user is recognized and their saved tenders become available during checkout.
If no JWT is returned, or the email cannot be verified, the user checks out as a guest.

Callbacks

Add the getJwt and handleLogin options to your CheckoutWidget.attach call alongside the other options described on the Embedded Checkout page.

// Return a JWT from your identity provider.
// Return undefined or an empty string if the user is not logged in.
getJwt: function () {
  return yourAuthSystem.getIdToken()
},

// Trigger your application's sign-in flow when the widget needs the user
// to log in.  This may redirect or reload the page.
handleLogin: function () {
  yourAuthSystem.startLogin()
},

`getJwt`

getJwt should return the JWT string from your identity provider, or undefined if the user is not logged in. It may return a plain value or a Promise — the widget will await the result in either case.

Parameter	Type	Description
(return value)	`string \| undefined` or `Promise<string \| undefined>`	The JWT from your identity provider. Return `undefined` or an empty string when the user is not logged in.

`handleLogin`

handleLogin lets the checkout widget ask your application to start sign-in when needed. This callback does not return the user's JWT to the widget. Instead, it should trigger your normal login flow, which may redirect or reload the page. After the user is signed in, the widget obtains the user's identity through getJwt.

Parameter	Type	Description
(return value)	`void` or `Promise<void>`	No return value is expected.

If your application can always provide a valid JWT through getJwt before the widget is attached, handleLogin may be implemented as a no-op. In that case, users can still be recognized when getJwt returns a token, but login prompts inside the widget will not be able to start sign-in.

Behavior Summary

Scenario	Effect
`getJwt` not provided	Guest checkout; no saved tenders.
`getJwt` returns a valid JWT with a verified email	User is recognized; saved tenders are available.
`getJwt` returns a JWT with an unverified email	Falls back to guest checkout.
`getJwt` returns `undefined` or `""`	Guest checkout; no saved tenders.

Prerequisites Checklist

Before going live, confirm the following with your PaymentExpress representative:

Your identity provider has been registered for your site.
Saved tenders have been enabled for your site configuration.
Your JWT includes an email address for the user.