npm - @primer-io/checkout-web - Versions diffs - 2.0.0-alpha.3 → 2.0.0 - Mend

@primer-io/checkout-web 2.0.0-alpha.3 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,1071 +1,668 @@
-# `@primer-io/checkout-web`
+<br/>
-Using the [Primer](https://primer.io) SDK for the web, you can quickly and easily create a checkout page for your site to securely collect card information and offer a multitude of alternative payment methods to your customers through one simple integration.
+<h1 align="center"><img src="https://github.com/primer-io/example-web-checkout/blob/master/images/primer-logo.png?raw=true" height="24px"> Primer Web SDK</h1>
-# Get Started!
+<div align="center">
+  <h3 align="center">
-Check out our guides on how to get started [here](https://primer.io/docs/guides/quick-start-guide).
+[Primer's](https://primer.io) Official Universal Checkout Web SDK
-Since the SDK must be loaded through our CDN. This npm package exposes a function `loadPrimer` that loads the Primer SDK from our CDN.
-This function returns a promise that resolves to a `class Primer`.
+  </h3>
+</div>
+<p align="center">
+<img src="https://img.shields.io/npm/v/@primer-io/checkout-web" />
+<!-- Potentially add test coverage in the future -->
+</p>
+<br/>
+<div align="center"><img src="https://github.com/primer-io/example-web-checkout/blob/master/images/checkout-banner.gif?raw=true"  width="50%"/></div>
+<br/>
+<br/>
+# 💪 Features of the Web SDK
+<p>💳 &nbsp; Create great payment experiences with our highly customizable Universal Checkout</p>
+<p>🧩 &nbsp; Connect and configure any new payment method without a single line of code</p>
+<p>✅ &nbsp; Dynamically handle 3DS 2.0 across processors and be SCA ready</p>
+<p>♻️ &nbsp; Store payment methods for one-click checkout, recurring and repeat payments</p>
+<p>📱 &nbsp; Proprietary Apple & Google Pay integrations that work with any PSP</p>
+<p>🔒 &nbsp; Always PCI compliant without redirecting customers</p>
+<br/>
+# 📚 Documentation
+Consider looking at the following resources:
+- [Documentation](https://primer.io/docs)
+- [Client session creation](https://primer.io/docs/accept-payments/manage-client-sessions/#create-a-client-session)
+- [API reference](https://apiref.primer.io/docs)
+- [Changelogs](https://primer.io/docs/changelog/sdk-changelog/web)
+<br/>
+# 💡 Support
+For any support or integration related queries, feel free to [Contact Us](mailto:https://support@primer.io).
+<br/>
+## 🚀 Quick start
+Take a look at our [Quick Start Guide](https://primer.io/docs/integration-builder/) for accepting your first payment with Universal Checkout.
+<br/>
+# 📋 Prerequisites
+- 🔑 Generate a client token by [creating a client session](https://primer.io/docs/api/#operation/create_client_side_token_client_session_post) in your backend
+- 🧱 Prepare a container in which to render Universal Checkout
+- 🎉 _That's it!_
+<br/>
+# 🧱 Installation
+## With npm (recommended)
+Our Web SDK is available on npm under the name [`@primer-io/checkout-web`](https://www.npmjs.com/package/@primer-io/checkout-web).
+This package includes TypeScript definitions.
+```bash
+# With yarn
+yarn add @primer-io/checkout-web
+# With npm
+npm install --save @primer-io/checkout-web
 ```
-import {loadPrimer} from '@primer-io/checkout-web'
-const Primer = await loadPrimer();
-const client = new Primer({
-  credentials: { clientToken: "...", },
+```typescript
+import { Primer } from '@primer-io/checkout-web';
+Primer.showUniversalCheckout(clientToken, {
+  /* Options */
 });
 ```
-# Reference
+## With our CDN
-## Global
+Include the `Primer.min.js` script on the page where you want the checkout to be rendered.
-### `class Primer(options: PrimerClientOptions)`
+Ensure that you're providing the desired version in the script tag. In the case below, it's `v2.0.0`:
-Creates a primer client
+```html
+<link rel="stylesheet" href="https://sdk.primer.io/web/v2.0.0/Checkout.css" />
-### `type PrimerClientOptions`
+<script
+  src="https://sdk.primer.io/web/v2.0.0/Primer.min.js"
+  crossorigin="anonymous"
+></script>
+```
-Options to configure the primer client
+`Primer.min.js` will add the Primer object to the global scope:
 ```typescript
-type PrimerClientOptions {
-  credentials: {
-    // Your server-generated client token
-    clientToken: string;
-  };
-  // maximum time in milliseconds to wait for third party scripts to load [default=10000]
-  thirdPartyScriptTimeout?: number;
-}
+const { Primer } = window;
+Primer.showUniversalCheckout(clientToken, {
+  /* Options */
+});
 ```
----
+<br/>
-## Primer (checkout)
+## 👩‍💻 Usage
-### `Primer#checkout(options: Options): Promise<PrimerCheckout>`
+### 🔍 &nbsp;Rendering the checkout
-Create a Primer checkout component. The structure of `options` depends on `options.uxFlow`, which can have three values:
+Availing Universal Checkout is as easy as implementing one line of code:
-- `CHECKOUT`: to render a checkout that displays multiple payment methods and the vaulted payment methods
-- `SINGLE_PAYMENT_METHOD_CHECKOUT`: to render a checkout that displays a single payment method
-- `MANAGE_PAYMENT_METHODS`: to render a UI for managing saved payment methods
+```javascript
+import { Primer } from '@primer-io/checkout-web';
-By default, `uxFlow` is `CHECKOUT`.
+const universalCheckout = await Primer.showUniversalCheckout(
+  clientToken,
+  options,
+);
+```
-### Common options
+Below is an example of a basic implementation of Universal Checkout:
-Some options are common to all `uxFlow`.
+```javascript
+const clientToken = '...'; // client token retrieved from your backend
-```typescript
- type Options = {
-  // Optimise the UX for managing saved payment methods by specifying 'MANAGE_PAYMENT_METHODS' for uxFlow
-  uxFlow: 'CHECKOUT' | 'MANAGE_PAYMENT_METHODS' | 'SINGLE_PAYMENT_METhOD_CHECKOUT,
+const options = {
+  // Container element which will contain the checkout
+  container: '#container',
-  // An HTML element (or a selector to the HTML element) in which to place the checkout component
-  container: string | Element;
+  onCheckoutComplete({ payment }) {
+    // Notifies you that a payment was created
+    // Move on to next step in your checkout flow:
+    // e.g. Show a success message, giving access to the service, fulfilling the order
+  },
+};
-  // Override the locale
-  // By default translations will be provided for the browser's locale
-  locale?: string;
+const universalCheckout = await Primer.showUniversalCheckout(
+  clientToken,
+  options,
+);
+```
-  // 3DS options. These must be provided if you want to perform SCA
-  // See the section on 3DS below for more info.
-  threeDSecure?: ThreeDSecureVerifyOptions;
+Note that there are more options which can be passed to Universal Checkout. Please refer to the section below for more information.
-  // A callback for when tokenization begins
-  onTokenizeStart?: () => void;
+<br/>
-  // A callback for tokenization success. This will receive the payment method token.
-  onTokenizeSuccess: (data: PaymentMethodToken) => Promise<SuccessCallbackReturnType>;
+## 🧰 &nbsp;Checkout Options
-  // A callback for when tokenization fails. See the error message here for more information
-  onTokenizeError: (message: string) => void;
+When calling `showUniversalCheckout` you can provide Universal Checkout with some configuration options.
-  // A callback for when changes have been made to the totalAmount provided to the checkout
-  onAmountChange?: (data: AmountChange) => void;
+These options range from callbacks notifying you of the current payment's status, to styling options for certain UI elements.
-  // A callback for when changes totalAmount is being updated
-  onAmountChanging?: (isChanging: boolean) => void;
+Below are some options to consider when integrating Universal Checkout:
-  // A callback for when an error occured while updating the totalAmount
-  onAmountChangeError?: (message: PrimerError) => void;
+### 🚀 **General Options**
-  // A callback for receiving actions which can be used to update the client session
-  onClientSessionActions?: (data: onClientSessionActionData) => Promise<{ clientToken: string } | false>;
+#### ⚙️ _Container and locale_
-  // Options and callbacks relating to scenes
-  scene?: SceneOptions;
+| option      | Type                  | Description                                                                               |          |
+| ----------- | --------------------- | ----------------------------------------------------------------------------------------- | -------- |
+| `container` | `string` or `Element` | The container element in which the checkout should be rendered                            | required |
+| `locale`    | `string`              | This option forces the locale. By default, the locale will be set to the browser's locale | optional |
-  // Style of the Checkout
-  style?: CheckoutStyle;
+<br/>
-  // Set options relating to the card form
-  form?: FormOptions;
+#### ⚙️ _Payment Lifecycle Callbacks_
-  submitButton?: {
-    // Deprecated in favor of using `useBuiltInButton`
-    visible?: boolean;
+Callbacks can be provided to Universal Checkout which will notify you on certain checkout events such as payment creation.
-    // Set whether to use built-in submit button
-    // Or use your own submit button
-    // Defaults to true
-    useBuiltInButton?: boolean;
+These callbacks can be used to inform you on the current state of the checkout.
-    // The following callbacks can be used to update your custom submit button
-    // Ensuring that your button has the correct state and content for a specific scene
+We strongly recommend you to implement `onCheckoutComplete` to redirect the user to an order confirmation page when the payment is successful:
-    // Callback for receiving the submit button's visible state in the current scene
-    onVisible: (isVisible: boolean, context: { currentSceneId: string; } ) => void;
+```javascript
+const options = {
+  /* Other checkout options ... */
-    // Callback for receiving the submit button's disabled state in the current scene
-    onDisable: (isDisabled: boolean, context: { currentSceneId: string }) => void;
+  onBeforePaymentCreate(data, handler) {
+    // Notifies you that a payment will be created
+    // Update your UI accordingly
+    // e.g. Show custom loading UI, etc.
+    // Abort or continue with payment creation
+    // Primer will continue with payment creation if onBeforePaymentCreate is not implemented
-    // Callback for receiving the submit button's loading state in the current scene
-    onLoading: (isLoading: boolean, context: { currentSceneId: string }) => void;
+    // ⚠️ You MUST call one of the functions of the `handler` if `onBeforePaymentCreate` is implemented
-    // Callback for receiving the submit button's content in the current scene
-    onContentChange: (content: string, context: { currentSceneId: string }) => void;
-  };
-  processingIndicator?: {
-    // Show a processing indicator overlay on top of the checkout when submitting a form
-    // Default to false if the submit button is visible
-    // Default to true if the submit button is hidden
-    visible?: boolean;
-  };
-  // Handles the error message displayed below the submit button when an error occurs
-  errorMessage?: {
-    // Disable the appearance of the default error message
-    // Default to false
-    disabled?: boolean;
-    // A callback for when the error message is displayed
-    onErrorMessageShow?: (message: string) => void;
-    // A callback for when the error message is hidden
-    onErrorMessageHide?: () => void;
-  }
-  /* PAYMENT METHOD SPECIFIC */
-  // Card networks allowed for checkout
-  // An error will be showed to the customer if they attempt to pay with a card network that is not allowed, whether it is using a card form, or via Google Pay/Apple Pay/...
-  // By default, all card networks are allowed
-  allowedCardNetworks: CardNetwork[];
-  card?: CheckoutCardOptions;
-  paypal?: PayPalOptions;
-  googlePay?: GooglePayOptions;
-  applePay?: ApplePayOptions;
-  directDebit?: DirectDebitOptions;
-  redirect?: {
-    // URL to return to in case of a redirect
-    returnUrl?: string;
-    // Default to false. Set to true to force a redirect for testing purposes.
-    forceRedirect?: boolean;
-  }
-}
-```
+    // Choose to abort a payment
+    return handler.abortPaymentCreation();
-```typescript
-type CardNetwork =
-  | 'american-express'
-  | 'diners-club'
-  | 'discover'
-  | 'elo'
-  | 'hiper'
-  | 'hipercard'
-  | 'interac'
-  | 'jcb'
-  | 'maestro'
-  | 'mastercard'
-  | 'mir'
-  | 'unionpay'
-  | 'visa';
-```
+    // Choose to continue with payment creation
+    return handler.continuePaymentCreation();
+  },
-```typescript
-type SuccessCallbackReturnType =
-  | /* Show success screen (for backward compability) */ undefined
-  | /* Show success screen */ true
-  | /* Refresh client token and perform new step */ { clientToken: string };
-```
+  onCheckoutComplete({ payment }) {
+    // Notifies you that a payment was created
+    // Move on to next step in your checkout flow:
+    // e.g. Show a success message, giving access to the service, fulfilling the order, ...
+  },
-### Client session actions
+  onCheckoutFail(error, { payment }, handler) {
+    // Notifies you that the checkout flow has failed and a payment could not be created
+    // This callback can also be used to display an error state within your own UI.
-The checkout has the ability to return actions in the `onClientSessionActions` callback. These actions should be sent to your backend and forwarded to Primer's `/client-session/actions` endpoint. Actions have the ability to mutate the client session when certain events occur, based on pre-defined conditions. The following types describe what could be returned in `onClientSessionActions`:
+    // ⚠️ `handler` is undefined if the SDK does not expect anything from you
+    if (!handler) {
+      return;
+    }
-```typescript
-// The data returned in onClientSessionActions
-type ClientSessionActionData = {
-  actions: ClientSessionAction[];
-  clientToken: string;
-};
-```
+    // ⚠️ If `handler` exists, you MUST call one of the functions of the handler
-```typescript
-type ClientSessionAction = {
-  type: ActionType;
-  params: ActionsParameters;
+    // Show a default error message
+    return handler.showErrorMessage();
+    // Show a custom error message
+    return handler.showErrorMessage('This is my custom error message');
+  },
 };
 ```
-```typescript
-// The currently supported action types forwarded to onClientSessionActions
-type ActionType = 'SELECT_PAYMENT_METHOD' | 'UNSELECT_PAYMENT_METHOD';
-```
+<br/>
-```typescript
-type ActionParameters = SelectPaymentMethodParamters | DefaulActionParameters;
-```
+#### ⚙️ _Client Session Lifecycle Callbacks_
-```typescript
-type SelectPaymentMethodParamters = {
-  paymentMethodType: string;
-  binData?: BinData;
-};
-```
+Callbacks can be provided to Universal Checkout which will notify you on client session update events.
-```typescript
-type DefaulActionParameters = {
-  type: string;
-};
-```
+```javascript
+const options = {
+  /* Other checkout options ... */
-### Specific options to `CHECKOUT`
+  onBeforeClientSessionUpdate() {
+    // Notifies you that the client session is in the process of being updated
+    // Use it to show a loading indicator on your UI
+  },
-```typescript
-type CheckoutOptions = {
-  // By default, all payment methods configured in the dashboard are proposed in the Checkout
-  // This filters the payment methods available
-  allowedPaymentMethods?: PaymentMethodType[];
-  // Additional information relating to merchant operating address. Used for tax calculation
-  businessDetails?: {
-    address: {
-      countryCode: string;
-      state: string;
-      postalCode: string;
-      city: string;
-      addressLine1: string;
-    };
-    nexusAddresses: [
-      {
-        countryCode: string;
-        state: string;
-        postalCode: string;
-        city: string;
-        addressLine1: string;
-      },
-    ];
-  };
-  // Additional information relating to customer. Details can be used for tax calculation
-  customerDetails?: {
-    customerTaxId: string;
-    shippingAddress: {
-      countryCode: string;
-      state: string;
-      postalCode: string;
-      city: string;
-      addressLine1: string;
-    };
-  };
-  // Options regarding the vault and one-click checkout feature
-  vault?: {
-    // Fetch the vaulted payment methods of the customerId of the current session and display them
-    // Default to true
-    visible?: boolean;
-    // Disable the option to delete a saved payment method.
-    // Default to false
-    deletionDisabled?: boolean;
-  };
-  // A callback for when a resume action succeeds. This will receive the resume token used to resume a payment
-  onResumeSuccess: (data: ResumeToken) => Promise<SuccessCallbackReturnType>;
-  // A callback for when an error happened when resuming
-  onResumeError: (error: PrimerClientError) => void;
+  onClientSessionUpdate(clientSession) {
+    // Notifies you when the client session has been updated by the checkout
+    // Returns updated client session
+    // Updated client session can be used to inform your UI
+    // e.g. update tax, shipping or discount amounts displayed to your customers
+  },
 };
 ```
-```typescript
-enum PaymentMethodType {
-  PAYMENT_CARD = 'PAYMENT_CARD',
-  APPLE_PAY = 'APPLE_PAY',
-  GOOGLE_PAY = 'GOOGLE_PAY',
-  PAYPAL = 'PAYPAL',
-  GO_CARDLESS = 'GOCARDLESS',
-}
-```
+---
-```typescript
-interface FormOptions {
-  inputLabelsVisible?: boolean; // Show or hide form input labels
-}
-```
+### 💳 **Payment Methods Options**
-```typescript
-type SceneOptions = {
-  // A callback for receiving the current scene that is entering
-  onEntering?: (sceneId: string) => void;
-  // Specify options relating to scene transitions
-  // Setting to false disables all scene transitions
-  // Defaults to a 'SLIDE_UP' type transition with a duration of 700ms
-  transition?: SceneTransitionOptions | false
-}
-type SceneTransitionOptions = {
-  // The type of transition animation which will be used
-  type: TransitionType;
-  // The duration of the transition animation
-  duration: number;
-};
+Learn more about the [payment method specific options](https://www.notion.so/primerio/Checkout-Documentation-589aeae3387a4025917db6e29810ebaf).
-type TransitionType =
-  | 'SLIDE_UP'
-  | 'SLIDE_DOWN'
-  | 'SLIDE_HORIZONTAL
-```
+<!--
+#### ⚙️ _Redirect Options_
-#### Dynamic Checkout Flow: `onTokenizeSuccess` and `onResumeSuccess`
+Handling redirects is required for Payment Methods like iDeal that present a webpage for the customer to enter their credentials and validate their payment.
-When a payment method is chosen and the customer clicks 'Pay', the payment method is tokenized and you'll receive a payment method token in the `onTokenizeSuccess` callback. Send it to your server to **create a payment** using Primer's Payments API.
+When the user selects such a Payment Method, Universal Checkout will first attempt to show the webpage in a popup or a browser tab to maintain the context, and will then safely bring the user back to the initial page to continue the flow.
-The checkout stays in a loading state while you perform this request. The Payments API may return a new client token: pass it as a return value of `onTokenizeSuccess` to perform the action tied to the new token, such as performing 3DS.
+This however does not work properly in some scenario involving third-party apps through deep linking.
-```typescript
-// Called after a payment method is tokenized
-// The checkout stays is a loading state until this Promise is resolved or rejected
-async onTokenizeSuccess(paymentMethod) {
-  // Send the payment method token to your server to then create a payment
-  const response = await sendPaymentMethodToken(paymentMethod);
-  // If a new client token is available, resolve the Promise with it to refresh the checkout session
-  // The checkout will automatically perform the action required by the Workflow
-  // e.g. Perform a 3D Secure challenge
-  if (response.clientToken) {
-    return { clientToken: response.clientToken };
-  }
-  // Display the success screen
-  return true;
-}
-```
+| option                   | Type    | Description                                                                                                                                                      | Default |          |
+| ------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
+| `redirect.returnUrl`     | String  | If creating a popup or tab is not possible, Universal Checkout will automatically redirect the user back to this URL.                                            |         | optional |
+| `redirect.forceRedirect` | Boolean | Forces redirect instead of using popups. <br /> _This negatively affects the User Experience. We recommend to only use this option in your testing environment._ | false   | optional |
-When the new action commanded by the Payments API is completed, you'll receive a resume token via the `onResumeSuccess` callback. Send it to your server to **resume a payment** using Primer's Payments API.
+#### ⚙️ _Card Options_
-The checkout stays in a loading state while you perform this request. The Payments API may return a new client token: pass it as a return value of `onResumeSuccess` to perform the action tied to the new token.
+These options only apply to the native Card implementation (`PAYMENT_CARD`).
-```typescript
-// Called after an extra-step - such as performing 3D Secure - is completed
-// The checkout stays is a loading state until this Promise is resolved or rejected
-async onResumeSuccess({resumeToken}) {
-  // Send the payment method token to your server to then create a payment
-  const response = await sendResumeToken(resumeToken);
-  // If a new client token is available, resolve the Promise with it to refresh the checkout session
-  // The checkout will automatically perform the action required by the Workflow
-  if (response.clientToken) {
-    // e.g. Trigger a 3D Secure challenge
-    return { clientToken: response.clientToken };
-  }
-  // Display the success screen
-  return true;
-}
-```
+| option                        | Type                                    | Description                                                                                                                                                                                                                       | Default                                      |          |
+| ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------- |
+| `card.preferredFlow`          | `DEDICATED_SCENE` or `EMBEDDED_IN_HOME` | `DEDICATED_SCENE`<br />Attempt to display a card button in the home scene. Clicking on this button will show the card form. <br /> <br /> `EMBEDDED_IN_HOME`<br /> Attempt to display the entire card form within the home scene. | `EMBEDDED_IN_HOME`                           | optional |
+| `card.cardNumber.placeholder` | String                                  | Placeholder for the card number field.                                                                                                                                                                                            | `1234 1234 1234 1234`                        | optional |
+| `card.expiryDate.placeholder` | String                                  | Placeholder for the card number field.                                                                                                                                                                                            | Localized version of `MM/YY`                 | optional |
+| `card.expiryDate.cvv`         | String                                  | Placeholder for the card number field.                                                                                                                                                                                            | `***` or `****` depending on the card scheme | optional |
-### Specific options to `MANAGE_PAYMENT_METHODS`
+---
-```typescript
-orderDetails?: {
-  currencyCode: string;
-};
+#### ⚙️ _Apple Pay Options_
-  // Disable the option to delete a saved payment method.
-  // Default to false
-  deletionDisabled?: boolean;
-```
+These options only apply to the native Apple Pay implementation (`APPLE_PAY`).
-### Specific options to `SINGLE_PAYMENT_METHOD_CHECKOUT`
+| option                 | Type                                                                | Description                                  | Default |          |
+| ---------------------- | ------------------------------------------------------------------- | -------------------------------------------- | ------- | -------- |
+| `applePay.buttonType`  | `plain`, `buy`, `set-up`, `donate`, `check-out`, `book`, `suscribe` | Control the content of the Apple Pay button. | `plain` | optional |
+| `applePay.buttonStyle` | `white`, `white-outline`, `black`                                   | Control the style of button.                 | `black` | optional |
-```typescript
-type SinglePaymentMethodCheckoutOptions = {
-  // The single payment method to render
-  // Only "GOCARDLESS" at the moment
-  paymentMethod: PaymentMethodType;
-};
-```
+#### ⚙️ _Google Pay Options_
-### Specific to payment methods
+These options only apply to the native Google Pay implementation (`GOOGLE_PAY`).
-#### `CheckoutCardOptions`
+| option                 | Type                        | Description                                 | Default   |          |
+| ---------------------- | --------------------------- | ------------------------------------------- | --------- | -------- |
+| `googlePay.buttonType` | `long`, `short`             | Control the size of the Google Pay button.  | `long`    | optional |
+| `google.buttonColor`   | `default`, `black`, `white` | Control the color of the Google Pay button. | `default` | optional |
-```typescript
-type CheckoutCardOptions = {
-    // A stylesheet to inject into each input element
-    // For more information see the guide on styling
-    css?: string;
-    // deprecated after v1.2.0
-    // Choose if the cardholder name should be required or not
-    // default value is true
-    cardholderNameRequired?: boolean;
-    cardholderName?: {
-      // Choose if the cardholder name should be visible
-      // default value is true
-      visible?: boolean;
-      // Choose if the cardholder name should be required
-      // If visible, the default value is true
-      required?: boolean;
-      // Placeholder text which will be displayed within input
-      // defaults to localized placeholder if not provided
-      placeholder?: string;
-    };
-    cardNumber?: {
-      // Placeholder card number which will be displayed within input
-      // default card number placeholder displayed if not provided
-      placeholder?: string;
-    };
-    expiryDate?: {
-      // Placeholder expiry date which will be displayed within input
-      // default expiry date placeholder displayed if not provided
-      placeholder?: Label;
-    };
-    cvv?: {
-      // Placeholder cvv which will be displayed within input
-      // default cvv placeholder displayed if not provided
-      placeholder?: Label;
-    };
-    // Choose if the card form should be embedded in the home scene
-    // Or have a dedicated card scene accessible by a card button
-    // Note that the preferredFlow will not necessarily be the chosen flow
-    preferredFlow?: CardPreferredFlow;
-    // Checkout will ask the customer id they want to save their card.
-    // To disable this feature provide a value for the vault option.
-    // When true: the card will be vaulted
-    // When false: the card will not be vaulted
-    vault?: boolean | () => boolean;
-  };
-  // DEDICATED_SCENE: can be used if more than one payment method is available
-  // EMBEDDED_IN_HOME: is provided by default. It will override the dedicated scene option
-  // When card is the only available payment method
-  type CardPreferredFlow = 'DEDICATED_SCENE' | 'EMBEDDED_IN_HOME';
-```
+#### ⚙️ _PayPal Options_
-#### `PayPalOptions`
+These options only apply to the native PayPal implementation (`PAYPAL`).
-```typescript
-type PayPalOptions = {
-  buttonColor?: 'gold' | 'blue' | 'silver' | 'white' | 'black';
-  buttonShape?: 'pill' | 'rect';
-  buttonSize?: 'small' | 'medium' | 'large' | 'responsive';
-  buttonHeight?: number;
-  buttonLabel?:
-    | 'checkout'
-    | 'credit'
-    | 'pay'
-    | 'buynow'
-    | 'paypal'
-    | 'installment';
-  buttonTagline?: boolean;
-  paymentFlow?: PaymentFlow;
-};
-```
+| option               | Type                                                           | Description                                                                                                                                                                                                                                                                                                     | Default   |          |
+| -------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------- |
+| `paypal.buttonColor` | `gold`, `blue`, `silver`, `white`, `black`                     | Control the color of the PayPal button.                                                                                                                                                                                                                                                                         | `gold`    | optional |
+| `paypal.buttonLabel` | `checkout`, `credit`, `pay`, `buynow`, `paypal`, `installment` | Control the label written in the PayPal button.                                                                                                                                                                                                                                                                 | `PayPal`  | optional |
+| `paypal.paymentFlow` | `DEFAULT`, `PREFER_VAULT`                                      | `DEFAULT`<br />Prepare everything to make a payment with PayPal. <br /><br />`PREFER_VAULT`<br />Vaut PayPal before making a payment. <br />Make sure the [`customerId`](https://apiref.primer.io/reference/create_client_side_token_client_session_post#request.body.customerId) is set in the client session. | `DEFAULT` | optional |
-#### `DirectDebitOptions`
+#### ⚙️ _Klarna Options_
-```typescript
-type DirectDebitOptions = {
-  customerCountryCode: Alpha2CountryCode;
-  // The following options are used in the Direct Debit mandate
-  companyName: string;
-  companyAddress: string;
-  // The following options are used to prefill the Direct Debit form
-  customerName?: string;
-  customerEmail?: string;
-  customerAddressLine1?: string;
-  customerAddressLine2?: string;
-  customerCity?: string;
-  customerPostalCode?: string;
-  iban?: string;
-  // Label of the submit button
-  submitButtonLabels?: {
-    // Label of the submit button in the form
-    form?: string;
-    // Label of the submit button in the mandate
-    mandate: string;
-  };
-};
-```
+These options only apply to the native Klarna implementation (`KLARNA`).
-#### `ApplePayOptions`
+| option                               | Type                                                               | Description                                                                                                                                                                                                                                                                                                     | Default                                     |          |
+| ------------------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | -------- |
+| `klarna.recurringPaymentDescription` | String                                                             |  Payment description used for recurring payments                                                                                                                                                                                                                                                                |                                             | optional |
+| `klarna.allowedPaymentCategories`    | Array of categories <br /> `pay_now`, `pay_later`, `pay_over_time` | List of categories allowed to be presented to the customer                                                                                                                                                                                                                                                      | `['pay_now', 'pay_later', 'pay_over_time']` | optional |
+| `klarna.paymentFlow`                 | `DEFAULT`, `PREFER_VAULT`                                          | `DEFAULT`<br />Prepare everything to make a payment with Klarna. <br /><br />`PREFER_VAULT`<br />Vaut Klarna before making a payment. <br />Make sure the [`customerId`](https://apiref.primer.io/reference/create_client_side_token_client_session_post#request.body.customerId) is set in the client session. | `DEFAULT`                                   | optional |
-```typescript
-type ApplePayOptions = {
-  buttonType?:
-    | 'plain'
-    | 'buy'
-    | 'set-up'
-    | 'donate'
-    | 'check-out'
-    | 'book'
-    | 'subscribe';
-  buttonStyle?: 'white' | 'white-outline' | 'black';
-};
-```
+-->
-#### `GooglePayOptions`
+---
-```typescript
-	buttonType?: "long" | "short";
-	buttonColor?: "default" | "black" | "white";
-```
+### 🎨 **Customization Options**
-### Setters
+Learn more about the [customization options](https://primer.io/docs/accept-payments/customize-universal-checkout/web).
-The checkout provides setter methods which can be called to update options after initialization.
+#### ⚙️ _Styling_
-```typescript
-const checkout = await primer.checkout(checkoutOptions);
+| option  | Type   | Description                                                                                                                                                                              | Default       |          |
+| ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------- |
+| `style` | Object | Custom style applied to the UI. <br /> Learn more about the capabilities in our [Customization Guide](docs/accept-payments/customize-universal-checkout/web/#styling-universal-checkout) | Default style | optional |
-checkout.setClientToken(clientToken);
-```
+#### ⚙️ _Form Options_
-### Manual Form Submission
+| option                    | Type    | Description                                   | Default |          |
+| ------------------------- | ------- | --------------------------------------------- | ------- | -------- |
+| `form.inputLabelsVisible` | Boolean | Choose whether to show the label above inputs | true    | optional |
-The checkout provides a method for manually calling submit.
-This is useful when using your own custom submit button.
+#### ⚙️ _Submit Button Options & Callbacks_
-```typescript
-const checkout = await primer.checkout(checkoutOptions);
+Universal Checkout allows you to use your own submit button for submitting forms. By default, the built-in submit button will be favored:
-const handleMySubmitButtonClick = () => {
-  // Forward all submit button clicks to the SDK
-  checkout.submit();
-};
-```
+| option                          | Type    | Description                                                                    | Default |          |
+| ------------------------------- | ------- | ------------------------------------------------------------------------------ | ------- | -------- |
+| `submitButton.useBuiltInButton` | Boolean | Set whether to use built-in submit button or to display your own custom button | true    | optional |
-### Style
+<br/>
-```typescript
-interface CheckoutStyle {
-  fontFaces?: Array<FontFace>; // Injected into hosted fields
-  stylesheets?: Array<Stylesheet>; // Injected into hosted fields
-  loadingScreen?: {
-    // Color of the loading screen indicator
-    color?: string;
-  };
-  // Style of the inputs
-  input?: {
-    // Base style
-    base?: InputStyle & {
-      hover?: InputStyle; // :hover
-      focus?: InputStyle; // :focus
-      placeholder?: InputStyle; //  ::placeholder
-      webkitAutofill?: InputStyle; // :-webkit-autofill
-      selection?: InputStyle; // ::selection
-    };
-    // Error
-    error?: InputStyle & {
-      hover?: InputStyle;
-      focus?: InputStyle;
-      placeholder?: InputStyle;
-      webkitAutofill?: InputStyle;
-      selection?: InputStyle;
-    };
-  };
-  // Style of the label displayed above the input fields
-  inputLabel?: TextStyle;
-  // Style of the error messages displayed below the input fields
-  inputErrorText?: TextStyle & TextAlignmentStyle;
-  formSpacings?: {
-    // Vertical spacing between a label and an input field
-    betweenLabelAndInput?: string;
-    // Vertical spacing between inputs
-    betweenInputs: string;
-  };
-  showMorePaymentMethodsButton?: {
-    base?: TextStyle;
-    disabled?: TextStyle;
-  }
-  // Style APM buttons
-  // PayPal, Apple Pay, Google Pay and Klarna can only be styled in height and borderRadius.
-  paymentMethodButton: {
-    background?: string;
-    borderRadius?: number | string;
-    boxShadow?: string;
-    borderColor?: string;
-    height?: number;
-    primaryText?: TextStyle;
-    logoColor?: logoColor;
-    marginTop?: string;
-  };
-  submitButton?: {
-    base?: {
-      hover?: TextStyle & BlockStyle;
-      focus?: TextStyle & BlockStyle;
-    };
-    loading?: {
-      hover?: TextStyle & BlockStyle;
-      focus?: TextStyle & BlockStyle;
-    };
-  };
-  // Small print in direct debit
-  smallPrint?: TextStyle;
-  directDebit?: {
-    mandate?: {
-      header?: TextStyle;
-      label?: TextStyle;
-      content?: TextStyle;
-      creditorDetails?: TextStyle:
-    };
-    success?: {
-      icon?: {
-        color?: string;
-      }
-    };
-  };
-  backButton?: {
-    color?: string;
-  };
-  // Pop-up menu to manage the vaulted payment methods
-  vaultMenu?: {
-    // Pencil icon
-    editButton?: {
-      // Backend of the pencil icon
-      background?: string;
-      // Color of the pencil icon
-      color?: string;
-    };
-    item?: {
-      label?: textStyle;
-      // Delete & Cancel button
-      actionButton?: TextStyle;
-      confirmButton?: TextStyle & BlockStyle;
-    };
-  }
-}
-interface FontFace {
-  fontFamily?: string;
-  src?: string;
-  unicodeRange?: string;
-  fontVariant?: string;
-  fontFeatureSettings?: string;
-  fontVariationSettings?: string;
-  fontStretch?: string;
-  fontWeight?: string;
-  fontStyle?: string;
-}
-interface Stylesheet {
-  href: string;
-}
-interface TextStyle {
-  color?: string;
-	fontFamily?: string;
-	fontWeight?: string;
-	fontSize?: string;
-	fontSmoothing?: string;
-	lineHeight?: string;
-  textTransform?: string;
-  letterSpacing?: string;
-}
-interface BlockStyle {
-  background?: string;
-	borderRadius?: number | string;
-	boxShadow?: string;
-  borderStyle?: string;
-	borderColor?: number | string;
-	borderWidth?: number | string;
-}
-interface TextAlignmentStyle {
-  	textAlign?: string;
-}
-type IconColor = 'black' | 'white' | 'color';
+Note that when **disabling** the built-in submit button and using your own custom submit button, it is **required** to implement the `submit()` function in order to notify Universal Checkout of form submissions. <br />
+Read more about the `submit()` function in the [Manual Form Submission](#manual-form-submission) section referenced below.
-```
+<br/>
-#### Input Style
+When using your own custom submit button, it's important to use the following callbacks to ensure that your submit button is in the correct state and in sync with the checkout as your customers interact with it:
-```typescript
-interface InputStyle {
-  height?: number;
-  paddingHorizontal?: number;
-  background?: string;
-  borderRadius?: number | string;
-  boxShadow?: string;
-  borderStyle?: string;
-  borderColor?: number | string;
-  borderWidth?: number | string;
-  color?: string;
-  fontFamily?: string;
-  fontWeight?: string;
-  fontSize?: string;
-  fontSmoothing?: string;
-  lineHeight?: string;
-}
-```
+```javascript
+const options = {
+  /* Other options ... */
-#### Success Screen
+  submitButton: {
+    useBuiltInButton: false, // Default to true
-By default, what happens after `onTokenizeSuccess` is called (and the Promise is resolved) depends on the payment method that the customer chooses. Some of them such as GoCardless requires us to display a screen that sums up the order to be displayed. Others, such as Card, does not require anything.
+    // Callback for receiving the submit button's visible state in the current scene
+    onVisible(isVisible, context: { currentSceneId }) {
+      // Show or hide your custom submit button
+    },
-However, it is good practice to show a success screen once the payment is validated. You can use the `successScreen` options to define which of the built-in success screens you want to show, or to disable the default behavior and display a custom success screen.
+    // Callback for receiving the submit button's disabled state in the current scene
+    onDisable(isDisabled, context: { currentSceneId }) {
+      // Disable or enable your custom submit button
+    },
-Note that when the `successScreen` is `undefined`, the `CHECK` success screen will be used by default. Also, when explicitly using `{ type: 'CHECK' }` a custom title can be defined.
+    // Callback for receiving the submit button's loading state in the current scene
+    onLoading(isLoading, context: { currentSceneId }) {
+      // Show your submit button in a loading state
+    },
-```typescript
-enum SuccessScreenType {
-  PAYMENT_METHOD = 'PAYMENT_METHOD',
-  CHECK = 'CHECK',
-}
-export type CheckSuccessScreenOptions = {
-  type: SuccessScreenType.CHECK;
-  title: Label;
+    // Callback for receiving the submit button's content in the current scene
+    onContentChange(content, context: { currentSceneId }) {
+      // Set your submit button's content with either the content provided or your own custom content
+    },
+  },
 };
+```
-export type PaymentMethodSuccessScreenOptions = {
-  type: SuccessScreenType.PAYMENT_METHOD;
-};
+<br/>
-type SuccessScreenOptions =
-  | /* No success screen will be displayed */ false
-  | /* Show the default success screen of the payment method*/ undefined
-  // Proposed success screens
-  | CheckSuccessScreenOptions
-  | PaymentMethodSuccessScreenOptions;
-```
+#### ⚙️ _Processing Indicator Options_
-## Primer (Advanced usage)
+Show a processing indicator overlay on top of the checkout when submitting a form:
-### `Primer#render(options: PrimerClientRenderOptions): Promise<void>`
+| option                        | Type    | Description                                                                      | Default |          |
+| ----------------------------- | ------- | -------------------------------------------------------------------------------- | ------- | -------- |
+| `processingIndicator.visible` | Boolean | Choose whether a processing indicator overlay should be shown on form submission | true    | optional |
-Securely render a credit card form or alternative payment method buttons.
+<br/>
-### `type PrimerClientRenderOptions`
+#### ⚙️ _Error Message Options & Callbacks_
-```typescript
-type PrimerClientRenderOptions {
-  // Override the locale
-  // By default translations will be provided for the browser's locale
-  locale?: string;
-  // Additional information relating to merchant operating address
-  // [required for tax calculation via TaxJar]
-  businessDetails?: {
-    address: {
-      countryCode: string;
-      state: string;
-      postalCode: string;
-      city: string;
-      addressLine1: string;
+When Universal Checkout encounters errors processing payments, these errors will be shown to your users by default, below the submit button.
+If you want to show your own error messages, you have the option to disable the default, built-in error messages:
+| option                  | Type    | Description                                                       | Default |          |
+| ----------------------- | ------- | ----------------------------------------------------------------- | ------- | -------- |
+| `errorMessage.disabled` | Boolean | Choose whether to allow Universal Checkout to show error messages | false   | optional |
+<br/>
+You can use the following callbacks to get notified when Universal Checkout intends to display an error message. By using these callbacks, you can respond with your own UI changes and avail a custom error message:
+```javascript
+const options = {
+  /* Other options ... */
+  errorMessage: {
+    disabled: false, // Default to false
+    // A callback for when the error message should be displayed
+    onErrorMessageShow(message) {
+      // Choose to use provided message for own purposes
     },
-    nexusAddresses: [
-      {
-        countryCode: string;
-        state: string;
-        postalCode: string;
-        city: string;
-        addressLine1: string;
-      },
-    ],
-  },
-  // Additional information relating to customer
-  // [required for tax calculation via TaxJar]
-  customerDetails?: {
-    customerTaxId: string;
-    shippingAddress: {
-      countryCode: string;
-      state: string;
-      postalCode: string;
-      city: string;
-      addressLine1: string;
+    // A callback for when the error message should be hidden
+    onErrorMessageHide() {
+      // Update own UI accordingly
     },
   },
+};
+```
-  // A success callback, receives the payment method token.
-  onTokenizeSuccess: (data: PaymentMethodToken) => void;
+<br/>
-  // A callback for when tokenization begins
-  onTokenizeStart?: () => void;
+#### ⚙️ _Success Screen Options_
-  // A callback for when there is a tokenization error
-  onTokenizeError?: (message: string) => void;
+When the checkout is succefully complete, Universal Checkout displays a success scene with a default success message _"Your payment was successful!"_.
-  // A callback for when tokenization ends
-  onTokenizeEnd?: () => void;
+Set the option `successScreen` to modify the behavior of the success scene.
-  // A callback for when changes have been made to the totalAmount provided to the checkout
-  onAmountChange?: (data: AmountChange) => void;
+```javascript
+const options = {
+  /* Other options ... */
-  // A callback for when changes totalAmount is being updated
-  onAmountChanging?: (isChanging: boolean) => void;
+  // Remove the success screen
+  successScreen: false,
-  // A callback for when an error occured while updating the totalAmount
-  onAmountChangeError?: (message: PrimerError) => void;
+  // Change the message of the default success screen
+  successScreen: {
+    type: 'CHECK',
+    title: 'This is a custom success message!',
+  },
+};
+```
-  // A callback for receiving actions which can be used to update the client session
-  onClientSessionActions?: (data: ClientSessionActionData) => Promise<{ clientToken: string } | false>;
+---
-  // Configuration for a credit card form
-  card?: {
-    // The name of the cardholder
-    // If a function is set, the function will be called when calling the `tokenize` function
-    cardholderName?: string | () => string;
+### 🔨 **Advanced Options**
-    // A callback for form metadata
-    onChange?: (state: FormState) => void;
+#### ⚙️ _Manual Payment Creation & Tokenization Lifecycle Callbacks_
-    // A callback for extra card information (brand etc)
-    onCardMetadata?: (meta: CardMetadata) => void;
+By default, Universal Checkout will automatically create payments and manage their lifecycles on your behalf. The manual payment creation flow used in previous Web SDK versions is still supported.
-    // Whether or not the form is disabled - this will prevent tokenization if it returns true
-    disabled?: () => boolean;
+Check our [Manual Payment Creation guide](https://primer.io/docs/accept-payments/advanced-checkout-configuration/manual).
-    // A stylesheet to inject into each input element
-    // For more information see the guide on styling
-    css?: string;
+<!--
-    // A DOM selector for a button which will begin the tokenization
-    submitButton: string;
+By default, Universal Checkout will automatically create payments and manage their lifecycles on your behalf.
-    // Credit card field configuration
-    fields: {
-      // Card number field configuration
-      cardNumber: CreditCardFieldConfig;
-      // Expiry Date field configuration
-      expiryDate: CreditCardFieldConfig;
-      // CVV field configuration
-      cvv: CreditCardFieldConfig;
-    };
-  };
+The manual payment creation flow used in previous Web SDK versions is still supported. To activate it, make sure to:
-  // Configuration for alternative payment methods
-  // The container property should be a DOM selector for a visible element n the page.
-  applePay?: { container: string; };
-  googlePay?: { container: string; };
-  paypal?: { container: string; };
-}
-```
+- set `paymentHandling` to `MANUAL`
+- implement `onTokenizeSuccess` and `onResumeSuccess`
-### `type PaymentMethodToken`
+```javascript
+const options = {
+  /* Other checkout options ... */
-A tokenized payment method. Use the token property to authorize transactions. The token object also contains some other metadata describing the payment method which it represents.
+  paymentHandling: 'MANUAL',
-```typescript
-type PaymentMethodToken {
-  // The token used to authorize transactions
-  token: string;
-  // The type of payment method which this token represents
-  paymentMethodType: 'PAYMENT_CARD' | 'GOOGLE_PAY' | 'APPLE_PAY' | 'PAYPAL';
-  // Additional data about the payment method
-  paymentMethodData: object;
-}
-```
+  async onTokenizeSuccess(paymentMethodTokenData, handler) {
+    // Send the Payment Method Token to your server
+    // to create a payment using Payments API
+    // const response = await createPayment(paymentMethodTokenData.token);
-### `type FormState`
+    // Call `handler.handleFailure` to cancel the flow and display an error message
+    if (!response) {
+      return handler.handleFailure(
+        'The payment failed. Please try with another payment method.',
+      );
+    }
-Form metadata
+    // If a new clientToken is available, call `handler.continueWithNewClientToken` to refresh the client session.
+    // The checkout will automatically perform the action required by the Workflow.
+    if (response.requiredAction.clientToken) {
+      return hander.continueWithNewClientToken(response.requiredAction.clientToken);
+    }
-```typescript
-type FormState {
-  // Whether any field is dirty
-  dirty: boolean;
-  // Whether any field was been touched
-  touched: boolean;
-  // Whether any field is active
-  active: boolean;
-  // Whether all fields are valid
-  valid: boolean;
-  // Whether the card form was submitted
-  submitted: boolean;
-}
-```
+    // Display the success screen
+    return hander.handleSuccess();
+  },
-### `type CardMetadata`
+  async onResumeSuccess(resumeTokenData, handler) {
+    // Send the resume token to your server to resume the payment
+    // const response = await resumePayment(resumeTokenData.resumeToken);
-Additional Card information
+    // Call `handler.handlehandleFailureError` to cancel the flow and display an error message
+    if (!response) {
+      return handler.handleFailure(
+        'The payment failed. Please try with another payment method.',
+      );
+    }
-```typescript
-type CardMetadata {
-  // The card type - 'visa' | 'mastercard' etc
-  type?: string;
-  // The possible types of the card given the current value
-  possibleTypes: string[];
-}
+    // If a new clientToken is available, call `handler.continueWithNewClientToken` to refresh the client session.
+    // The checkout will automatically perform the action required by the Workflow
+    if (response.requiredAction.clientToken) {
+      return hander.continueWithNewClientToken(response.requiredAction.clientToken);
+    }
+    // Display the success screen
+    return hander.handleSuccess();
+  },
+};
 ```
-### `type CreditCardFieldConfig`
+Additional optional callbacks are available:
-Configuration for credit card fields
+```javascript
+const options = {
+  /* Other checkout options ... */
-```typescript
-type CreditCardFieldConfig {
-  // A DOM selector specifying where to render the input
-  container: string;
-  // Whether to append or prepend the input to the container element
-  placement?: 'append' | 'prepend';
-  // A placeholder to display when the input is empty
-  placeholder?: string;
-  // A callback which receives input metadata
-  onChange: (data: { meta: FieldMetadata; }) => void;
-}
+  async onTokenizeShouldStart({ paymentMethodType }) {
+    // Return true if tokenization is allowed to start
+    return true;
+    // Return false if tokenization is not allowed to start
+    // This is likely to happen if the user has not properly filled in a form owned by you
+    return false;
+  },
+  onTokenizeDidNotStart(reason) {
+    // Tokenization did not start
+    if (reason === 'TOKENIZATION_DISABLED') {
+      // Tokenization has been disabled with `setTokenizationEnabled`
+    } else if (reason === 'TOKENIZATION_SHOULD_NOT_START') {
+      // Tokenization has been disabled by returning false in `onTokenizeShouldStart`
+    }
+  },
+  onTokenizeStart() {
+    // Tokenization has started
+  },
+  onResumeError(error) {
+    // Resuming has failed
+  },
+};
 ```
-### `type FieldMetadata`
+-->
-Input metadata for a Credit card field
+#### ⚙️ _Show the flow for a single payment method_
-```typescript
-type FieldMetadata {
-  // A validation error
-  error?: string;
-  // Whether or not the input contains valid information
-  valid: boolean;
-  // Whether or not the input is focussed
-  active: boolean;
-  // Whether or not the input's value has been changed
-  dirty: boolean;
-  // Whether or not the customer has focussed the field
-  touched: boolean;
-  // Whether or not the form has been submitted
-  submitted: boolean;
-}
+The payment methods featuring a dedicated screen allows you to directly display their flow. For that, make sure to:
+- Set `uxFlow` to `SINGLE_PAYMENT_METHOD_CHECKOUT`
+- Set `paymentMethod` to the payment method you want to display
+```javascript
+const options = {
+  /* Other options ... */
+  uxFlow: 'SINGLE_PAYMENT_METHOD_CHECKOUT',
+  paymentMethod: 'PAYMENT_CARD',
+};
 ```
----
+Payment methods that supports this flow
-### `Primer#threeDSecure: ThreeDSecure`
+- Card: `PAYMENT_CARD`
+- Klarna: `KLARNA`
+- GoCardless: `GOCARDLESS`
-Primer 3DS verification API
+#### ⚙️ _Customizable Payment Method Button options_
-### `ThreeDSecure#verify(options: ThreeDSecureVerifyOptions): Promise<ThreeDSecureVerification>`
+Some payment methods enables you to customize the payment method button.
-Perform a 3DS verification on a payment method token
+| option       | Type   | Description                                                                      | Default             |          |
+| ------------ | ------ | -------------------------------------------------------------------------------- | ------------------- | -------- |
+| `logoSrc`    | String | Data URL representing the logo you want to display in the payment method button. |                     | required |
+| `background` | String | Color of the background of the payment method button.                            |                     | required |
+| `logoAlt`    | String | Accessibility marker for the payment method button                               |                     | required |
+| `text`       | String | Label to display to the right of `logoSrc`                                       | Only show `logoSrc` | optional |
-### `type ThreeDSecureVerifyOptions`
+Payment methods that supports this flow
-Options provided to 3DS verification
+- Gift Cards with Mollie: `PAYMENT_CARD`
-```typescript
-type ThreeDSecureVerifyOptions {
-  // A Payment method token to perform 3DS verification for
-  token: string;
-  // An element selector for the parent of the 3DS challenge UI
-  container: string;
-  // A callback for when the 3DS challenge starts
-  onChallengeStart?: () => void;
-  // A callback for when the 3DS challenge ends
-  onChallengeEnd?: () => void;
-  // 3DS order details
-  order: {
-    // Your order ID
-    orderId: string;
-    amount: {
-      // The sale amount
-      value: number | string;
-      // The alpha3 currency code of the sale
-      currency: string;
-    };
-    // The customer's email address
-    email: string;
-    billingAddress: {
-      // Billing first name
-      firstName: string;
-      // Billing last name
-      lastName: string;
-      // Street address
-      addressLine1: string;
-      // Extended street address
-      addressLine2?: string
-      // Extended street address
-      addressLine3?: string
-      // City or town
-      city: string;
-      // State, region or province
-      state?: string;
-      // The alpha2 country code of the address
-      countryCode: string;
-      // The postal or zip code
-      postalCode: string;
-    }
-  };
-}
+## 🔧 &nbsp;<a id="checkout-methods"></a> Checkout Methods
+Universal Checkout exposes some methods which can be called to perform some specific actions:
+### **Set Client Token**
+When updating the client session, after the checkout has been initialized, you will receive a client token in the response returned from `PATCH /client-session`.
+In order for the checkout to know that you have updated the client session, you will need to pass this new client token back to the checkout:
+```javascript
+const universalCheckout = await Primer.showUniversalCheckout(
+  clientToken,
+  options,
+);
+// Pass the new client token to Universal Checkout by calling setClientToken
+// This will result in Universal Checkout having access to the latest changes made to the client session
+universalCheckout.setClientToken(clientToken);
 ```
-### `type ThreeDSecureVerification`
+### **Manual Form Submission**
-The result of a 3DS verification. If successful, a new token will be returned.
+The checkout provides a method for manually calling submit. This is useful when using your own custom submit button.
-```typescript
-{
-  // The result status of the verification
-  status: 'AUTH_SUCCESS' | 'AUTH_FAILED' | 'SKIPPED';
-  // Optional error if something unexpected happened
-  error?: Error;
-  // Data object containing the new token
-  data?: PaymentMethodToken;
-}
+```javascript
+const universalCheckout = await Primer.showUniversalCheckout(
+  clientToken,
+  options,
+);
+const handleMySubmitButtonClick = () => {
+  // Forward all submit button clicks to the SDK
+  universalCheckout.submit();
+};
+```
+<br/>
+### **Disabling Tokenization and Payment Creation**
+The checkout provides `setPaymentCreationEnabled` and `setTokenizationEnabled` to enable or disable tokenization and payment creation. Use this if you would like to prevent users from paying because your side of the checkout is not valid.
+These two functions can be used interchangibly.
+```javascript
+const universalCheckout = await Primer.showUniversalCheckout(
+  clientToken,
+  options,
+);
+// Disable payment creation
+universalCheckout.setPaymentCreationEnabled(false);
+universalCheckout.setTokenizationEnabled(false);
+// Enable payment creation
+universalCheckout.setPaymentCreationEnabled(true);
+universalCheckout.setTokenizationEnabled(true);
 ```