{"id":27996489,"url":"https://github.com/bold-commerce/checkout-express-pay-library","last_synced_at":"2025-10-26T08:17:19.460Z","repository":{"id":171125336,"uuid":"553770159","full_name":"bold-commerce/checkout-express-pay-library","owner":"bold-commerce","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-03T16:15:06.000Z","size":940,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-09-10T23:44:38.979Z","etag":null,"topics":["pci-scoped","snyk-scan"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bold-commerce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-10-18T18:36:36.000Z","updated_at":"2024-12-03T16:14:26.000Z","dependencies_parsed_at":"2023-12-22T16:48:18.762Z","dependency_job_id":"d4e831d7-168d-4bfe-8d86-2927a43ca907","html_url":"https://github.com/bold-commerce/checkout-express-pay-library","commit_stats":null,"previous_names":["bold-commerce/checkout-express-pay-library"],"tags_count":67,"template":false,"template_full_name":null,"purl":"pkg:github/bold-commerce/checkout-express-pay-library","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bold-commerce%2Fcheckout-express-pay-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bold-commerce%2Fcheckout-express-pay-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bold-commerce%2Fcheckout-express-pay-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bold-commerce%2Fcheckout-express-pay-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bold-commerce","download_url":"https://codeload.github.com/bold-commerce/checkout-express-pay-library/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bold-commerce%2Fcheckout-express-pay-library/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281075002,"owners_count":26439569,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-26T02:00:06.575Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pci-scoped","snyk-scan"],"created_at":"2025-05-08T21:44:23.836Z","updated_at":"2025-10-26T08:17:19.431Z","avatar_url":"https://github.com/bold-commerce.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Checkout Express Pay Library\n\n## Description\nThe Checkout Express Pay Library is a Bold Javascript library, which contains reusable methods to implement the wallet payment using Bold's [Headless Checkout APIs.](https://developer.boldcommerce.com/default/guides/checkout)\n\nThis library adds a series of wallet pay buttons in your application container.\n\nUser interaction with the buttons and the payment dialogs will update the order that was initialized from [Initialize Order](https://developer.boldcommerce.com/default/api/orders#tag/Orders) endpoint and provided during the checkout initialization.\n\nThe library sends responses to a callback function in order to communicate the actions taken by the user throughout the checkout experience. For more information on how to define this callback function, refer to [Initializing Express Pay Library](#initializing-express-pay-library).\n\nCurrently, the library supports the following payment gateways:\n\n* Stripe (Google \u0026 Apple Pay)\n* Braintree (Google \u0026 Apple Pay)\n* PayPal\n\n\u003e Bold provides a template checkout experience that utilizes this Express Pay Library. The examples throughout this document link to various places in the following repository: [Checkout Experience Templates](https://github.com/bold-commerce/checkout-experience-templates)\n\n## Installation\n\n### Prerequisites\n\nTo correctly implement the Checkout Express Pay library, complete the following steps:\n\n\n#### ▸ Install Checkout Frontend Library\n\nThe [Checkout Frontend Library](https://github.com/bold-commerce/checkout-frontend-library) is a peer dependency for the Checkout Express Pay Library, which means that both packages **NEED** to be used together.\n\nCheckout Express Pay library uses the methods from the Checkout Frontend Library to call to the [Bold Checkout APIs](https://developer.boldcommerce.com/default/guides/checkout).\n\nCheckout Frontend Library is NOT yet published in the NPM Registry.\n\nTo install is this library, follow the instructions in the Checkout Frontend  Repository readme, linked below. You must link this library as a package in your application.\n\n\u003e [Checkout Frontend Library Repository](https://github.com/bold-commerce/checkout-frontend-library) - Package name @boldcommerce/checkout-frontend-library\n\u003e \n\u003e [NPM LINK OPTION: documentation](https://docs.npmjs.com/cli/v8/commands/npm-link)\n\u003e \n\u003e [YARN LINK OPTION: documentation](https://classic.yarnpkg.com/lang/en/docs/cli/link/)\n\n#### ▸ Install Checkout Express Pay Library\n\nAfter Checkout Frontend Library is installed, you can then install the Checkout Express Pay Library. You must link this library as a package in the project you would like to include it in.\n\nCheckout Express Pay Library is NOT yet published in the NPM Registry.\n\n\u003e [NPM LINK OPTION: documentation](https://docs.npmjs.com/cli/v8/commands/npm-link)\n\u003e\n\u003e [YARN LINK OPTION: documentation](https://classic.yarnpkg.com/lang/en/docs/cli/link/)\n\n#### ▸ Initialize Checkout Frontend Library\n\nBefore initializing the Checkout Express Pay Library, you **MUST** initialize the Checkout Frontend Library in your application by using the `initialize` method.\n\n**initialize**(`initData`, `shopIdentifier`, `environment`): Promise \u003c[IApiReturnObject](https://github.com/bold-commerce/checkout-frontend-library/blob/main/docs/interfaces/IApiReturnObject.md) \u003e\n\nInitialize the library with order data and environment variables. The library needs to be initialized with required data before using any other functionality. The following TypeScript snippet shows an example of how to initialize this library.\n\n```typescript\nimport {IApiReturnObject, initialize} from '@boldcommerce/checkout-frontend-library';\n\n const environment = {type: 'production'};\n const response: IApiReturnObject = await initialize(initData, shopIdentifier, environment);\n```\n\n\u003e In Template Example: [Checkout Experience Templates - session.ts](https://github.com/bold-commerce/checkout-experience-templates/blob/5703757ccef3cc1832be0adaed9983dd40dd3ccc/src/library/session.ts#L9) \n\n**Parameters**\n\n| Parameter| Type| Description|\n| ---------| ----|-----------|\n| `initData`| [IInitializeOrderResponse](https://github.com/bold-commerce/checkout-frontend-library/blob/main/docs/interfaces/IInitializeOrderResponse.md) | The order data obtain from [Initialize Order](https://developer.boldcommerce.com/default/api/orders#tag/Orders) endpoint.  |\n| `shopIdentifier`| `string` | The identifier of the shop. Can be retrieved by making a request to the [Get Info](https://developer.boldcommerce.com/default/api/shops#tag/Shop) endpoint.|\n| `environment`| [IEnvironment](https://github.com/bold-commerce/checkout-frontend-library/blob/main/docs/interfaces/IEnvironment.md) | Defined the bold API environment. Use `{\"type\":\"production\"}` even for test stores, other types are for Bold internal use. |\n\n\n**Returns**\n\n`Promise`\u003c[IApiReturnObject](https://github.com/bold-commerce/checkout-frontend-library/blob/main/docs/interfaces/IApiReturnObject.md) \u003e\n\nA promise that resolves the API response. \n\nYour application can use this response to handle errors or update the application state of the order.\n\n\u003e In Template Example: [Checkout Experience Templates - session.ts](https://github.com/bold-commerce/checkout-experience-templates/blob/5703757ccef3cc1832be0adaed9983dd40dd3ccc/src/library/session.ts#L13)\n\n#### ▸ Create placeholder container div\nCreate a placeholder `\u003cdiv\u003e` within your application with an id of `express-payment-container`. \n\nThis `\u003cdiv\u003e` holds all the wallet pay DOM elements. The library creates individual `\u003cdiv\u003e` elements for each button that will be rendered by the payment gateways.\n\nMore details on each payment gateway classes for styling can be found in [Payment Gateways](#payment-gateways)\n\nThe action callback function returns the [Enable Disable Section Action](#actions) when the Payment Gateways are rendering buttons in order to inform the template to show or hide this container.\n\nSee more information in [Usage](#usage) and [Actions](#actions).\n\n\u003e In Template Example: [Checkout Experience Templates - expressPaymentGateway.tsx](https://github.com/bold-commerce/checkout-experience-templates/blob/5703757ccef3cc1832be0adaed9983dd40dd3ccc/src/components/express-payment-gateway/expressPaymentGateway.tsx#L13)\n\n#### ▸ Configure wallet payment gateway\n\nFollow the official documentation of each payment gateway to create your credentials. Ensure you enable the wallet pay functionalities of the payment gateway.\n\nWith the credentials in hand, configure the wallet payment gateway in the Bold Checkout admin.\n\n## Usage\n\n### Initializing Express Pay library\n\nThe `initialize` function expects an `onAction` callback in the parameter properties. \n\nThis callback is used whenever the library needs to communicate with the rest of your application. \nIt does this by passing the callback actions, which consist of a `type` and an optional `payload`.\n\nIt can be triggered at any moment of the process since the library was initialized.\n\nEach of the actions occurs at a different point in the checkout process. For example:\n- `ORDER_PROCESSING` occurs when user finalizes the payment process and all validation succeeds.\n- `ENABLE_DISABLE_SECTION` occurs when the payment gateway is loaded using the credentials - `true` when at least 1 payment gateway loaded successfully and `false` when none have loaded.\n- `DISPLAY_ERROR` occurs when any error occurs from an API call that is not handled internally by the payment gateways.\n- `RERESH_ORDER` occurs when cancelling a wallet pay and the order state should be updated with the changes from the wallet pay.\n\nFor a full list of all actions the library will emit, see the [actions](#actions) section below.\n\n\u003e In Template Example: [Checkout Experience Templates - initializeExpressPay.ts](https://github.com/bold-commerce/checkout-experience-templates/blob/5703757ccef3cc1832be0adaed9983dd40dd3ccc/src/library/initializeExpressPay.ts#L18)\n\nThe following TypeScript example shows how you can handle the actions.\n\n```typescript\nimport {initialize, actionTypes} from '@boldcommerce/checkout-express-pay-library';\n\nconst handleExpressPayActions = async (type, payload) =\u003e {\n    switch (type) {\n        case actionTypes.ENABLE_DISABLE_SECTION:\n            // Implement a template behavior, if any, desired for the action in each case.\n            // For instance, show or hide the express pay container or section in the template.\n            // Or move the the thank you page if order is processed.\n        default:\n            break;\n        }\n    };\ninitialize({onAction: handleExpressPayActions});\n```\n\n#### `Initialize` parameters\n\n| Parameter| Type| Description|\n| ---------| ----|-----------|\n| `props`| [IInitializeProps](https://github.com/bold-commerce/checkout-express-pay-library/blob/main/docs/interfaces/IInitializeProps.md)| The prop to initialize the express payment library. Your application can provide onAction functionality in object {onAction} |\n\n\n### Import Express Pay library Style\n\nThe library also exports a style sheet with some default styling for the express payment section of the checkout. Your application can import this default css file for styling using the following statement:\n\n```\n@import '~@boldcommerce/checkout-express-pay-library/lib/style.css';\n```\n\n\u003e In Template Example: [Checkout Experience Templates - app.css](https://github.com/bold-commerce/checkout-experience-templates/blob/5703757ccef3cc1832be0adaed9983dd40dd3ccc/public/app.css#L54)\n\n## Rendering payment button\n\nThe express pay buttons will render in the checkout after the following steps occur:\n\n1. Checkout Frontend Library is initialized.\n1. Container `\u003cdiv\u003e` is present in the DOM.\n1. Payment gateway credentials are valid.\n1. Express Pay Library is initialized.\n1. Payment gateway considers the session ready to pay.\n\n\n## Actions\n\nBecause each unique checkout experience can have different implementations, the library uses actions to inform the application what happens in the checkout experience so that the application can decide what to do next.\n\nWhenever the library needs to communicate with the rest of the application, it does so through the action callback function provided during the library initialization.\n\nThe callback will be called with `type` and an optional `payload` and can be triggered at any moment on the process since the library was initialized.\n\n\u003e In Template Example: [Checkout Experience Templates - initializeExpressPay.ts](https://github.com/bold-commerce/checkout-experience-templates/blob/5703757ccef3cc1832be0adaed9983dd40dd3ccc/src/library/initializeExpressPay.ts#L18)\n\nYour application can define the following actions in order to implement a complete checkout experience.\n\n#### Enable Disable Section\n\nThis action will happen when the payment gateway is loaded using the credentials.\n\n* `string` type: `ENABLE_DISABLE_SECTION`\n* `object`payload:\n  * `boolean` show - `true` means at least 1 payment gateway loaded successfully and `false` means none have loaded\n\nThis action can be used to define whether the template needs to show the express pay section or not.\n\n#### Order Processing\n\nThis action occurs when the user finalizes the payment process and all validations succeed.\n\n* `string` type: `ORDER_PROCESSING`\n\nThis action indicates that the payment was successfully added to the order but order was not processed by the Checkout Express Pay Library. \n\nIn response to this action, the application must call [Process Order](https://developer.boldcommerce.com/default/api/checkout#tag/Order/operation/post-process_order) endpoint separately to complete the order.\n\n#### Display Error\n\nThis action occurs when any error occurs in response to an API call that is not handled internally by the payment gateways.\n\n* `string` type: `DISPLAY_ERROR`\n* `object`payload:\n  * `string` message - The error message\n  * `object` details - The details about `language_blob` for translation. Retrieve the `language_blob` from the [Initialize Order](https://developer.boldcommerce.com/default/api/orders#tag/Orders/operation/post-init) endpoint.\n    * `string` section: The section in the `language_blob` \n    * `string` term: The term in the `language_blob`\n\nThis action sends error details to your application in case of any failure so the application can choose to show an error message in some manner.\n\n## Payment Gateways\n\nThe library creates specific DOM element for each payment gateway inside the `express-payment-container` `\u003cdiv\u003e` container. The below information can be used to apply custom styling if needed.\n\n| Payment Gateway| Description |\n| ---------| -----------|\n| `Stripe`|  The Stripe container will create a div with `stripe-express-payment` id and `stripe-express-payment express-payment` classnames. |\n| `Braintree Google`|  The Braintree Google container will create a div with `braintree-google-express-payment` id and `braintree-google-express-payment express-payment` classnames. |\n| `Braintree Apple`|  The Braintree Apple container will create a div with `braintree-apple-express-payment` id and `braintree-apple-express-payment express-payment` classnames. |\n| `PayPal`|  The Paypal container will create a div with `paypal-express-payment` id and `paypal-express-payment express-payment` classnames. |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbold-commerce%2Fcheckout-express-pay-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbold-commerce%2Fcheckout-express-pay-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbold-commerce%2Fcheckout-express-pay-library/lists"}