Composite Checkout
A set of React components, custom Hooks, and helper functions that together can be used to create a purchase and checkout flow.
Installation
This package is still in development and not yet published.
Once published, you'll be able to install this package using npm with:
yarn add @automattic/composite-checkout
Description
This package provides a context provider, CheckoutProvider
, a default component, Checkout
, and the CheckoutStepArea
component which creates a checkout form.
The form has two default steps:
- Payment method
- Review order
These steps can be customized or replaced, and additional steps can be added.
It's also possible to build an entirely custom form using the other components exported by this package.
How to use this package
Most components of this package require being inside a CheckoutProvider. That component requires an array of Payment Method objects which define the available payment methods (stripe credit cards, apple pay, paypal, credits, etc.) that will be displayed in the form.
Any component which is a child of CheckoutProvider
gets access to the following custom hooks:
- useAllPaymentMethods
- useEvents
- useFormStatus
- useTransactionStatus
- usePaymentProcessor
- usePaymentProcessors
- useDispatch
- useLineItems
- useLineItemsOfType
- usePaymentMethod
- usePaymentMethodId
- useRegisterStore
- useRegistry
- useSelect
- useTotal
The Checkout component creates a wrapper for Checkout. Within the component you can render any children to create the checkout experience, but a few components are provided to make this easier:
- CheckoutSummaryArea (optional) can be used to render an invisible area that, by default, floats beside the checkout steps on larger screens and collapses behind a toggle at the top of smaller screens.
- CheckoutSummaryCard (optional) can be used inside CheckoutSummaryArea to render a bordered area.
- CheckoutStepArea (required) supplies a styled wrapper for the CheckoutStepBody and CheckoutStep components, and creates the Checkout form itself with a submit button.
- CheckoutStepBody (optional) can be used to render something that looks like a checkout step. A series of these can be used to create a semantic form.
- CheckoutSteps (with CheckoutStep children) can be used to create a series of steps that are joined by "Continue" buttons which are hidden and displayed as needed.
-
CheckoutStep (optional) children of
CheckoutSteps
can be used to create a series of steps that are joined by "Continue" buttons which are hidden and displayed as needed. - Button (optional) a generic button component that can be used to match the button styles of those buttons used inside the package (like the continue button on each step).
- CheckoutErrorBoundary (optional) a React error boundary that can be used to wrap any components you like.
Each CheckoutStep
has an isCompleteCallback
prop, which will be called when the "Continue" button is pressed. It can perform validation on that step's contents to determine if the form should continue to the next step. If the function returns true, the form continues to the next step, otherwise it remains on the same step. If the function returns a Promise
, then the "Continue" button will change to "Please wait…" until the Promise resolves allowing for async operations. The value resolved by the Promise must be a boolean; true to continue, false to stay on the current step.
Any component within a CheckoutStep
gets access to the custom hooks above as well as useIsStepActive, useIsStepComplete, and useSetStepComplete.
Submitting the form
When the payment button is pressed, the form data will be validated and submitted in a way appropriate to the payment method. If there is a problem with either validation or submission, or if the payment method's service returns an error, the showErrorMessage
prop on Checkout
will be called with an object describing the error.
If the payment method succeeds, the onPaymentComplete
prop will be called instead.
Example
See the demo for an example of using this package.
Styles and Themes
Each component will be styled using @emotion/styled and many of the styles will be editable by passing a theme
object to the CheckoutProvider
. The checkoutTheme
object is available from the package API, and can be merged with new values to customize the design.
For style customization beyond what is available in the theme, each component will also include a unique static className using BEM syntax.
When using the individual API components, you can also pass a className
prop, which will be applied to that component in addition to the above.
Payment Methods
Each payment method is an object with the following properties:
-
id: string
. A unique id. -
label: React.ReactNode
. A component that displays that payment method selection button which can be as simple as the name and an icon. -
activeContent: React.ReactNode
. A component that displays that payment method (this can return null or something like a credit card form). -
submitButton: React.ReactNode
. A component button that is used to submit the payment method. This button should include a click handler that performs the actual payment process. When disabled, it will be provided with thedisabled
prop and must disable the button. -
inactiveContent: React.ReactNode
. A component that renders a summary of the selected payment method when the step is inactive. -
getAriaLabel: (localize: () => string) => string
. A function to return the name of the Payment Method. It will receive the localize function as an argument.
Within the components, the Hook usePaymentMethod()
will return an object of the above form with the key of the currently selected payment method or null if none is selected. To retrieve all the payment methods and their properties, the Hook useAllPaymentMethods()
will return an array that contains them all.
When a payment method is ready to submit its data, it can use an appropriate "payment processor" function. These are functions passed to CheckoutProvider with the paymentProcessors
prop and each one has a unique key.
Payment method components (probably the submitButton
) can access these functions using the usePaymentProcessor hook, passing the key used for that function in paymentProcessors
as an argument. However, for convenience, the submitButton
will be provided with an onClick
handler that can do this automatically. The onClick
function takes two arguments, a string which is the key of the payment processor to be used, and an object that contains the data needed by the payment processor.
If you use the onClick
function, the payment processor function's response will control what happens next. Each payment processor function must return a Promise that either resolves to one of four results on success (see makeManualResponse, makeRedirectResponse, makeSuccessResponse), or makeErrorResponse on failure.
If not using the onClick
function, when the submitButton
component has been clicked, it should do the following (these are normally handled by onClick
):
- Call
setTransactionPending()
from useTransactionStatus. This will change the form status to.SUBMITTING
and disable the form. - Call the payment processor function returned from usePaymentProcessor, passing whatever data that function requires. Each payment processor will be different, so you'll need to know the API of that function explicitly.
- Payment processor functions return a
Promise
. When thePromise
resolves, check its value (it will be one of makeManualResponse, makeRedirectResponse, or makeSuccessResponse). Then callsetTransactionComplete(responseData: unknown)
from useTransactionStatus if the transaction was a success. If the transaction requires a redirect, callsetTransactionRedirecting(url: string)
instead. - If the
Promise
resolves to makeErrorResponse, callsetTransactionError(message: string)
. - At this point the CheckoutProvider will automatically take action if the transaction status is
.COMPLETE
(call onPaymentComplete),.ERROR
(display the error and re-enable the form), or.REDIRECTING
(redirect to the url). If for some reason the transaction should be cancelled, callresetTransaction()
.
Line Items
Each item is an object with the following properties:
-
id: string
. A unique identifier for this line item within the array of line items. Do not use the product id; never assume that only one instance of a particular product is present. -
type: string
. Not used internally but can be used to organize line items (eg:tax
for a VAT line item). -
label: string
. The displayed title of the line item. -
sublabel?: string
. An optional subtitle for the line item. -
amount: { currency: string, value: number, displayValue: string }
. The price of the line item. For line items without a price, set value to 0 and displayValue to an empty string.
Data Stores
Each Payment Method or component can create a Redux-like data store by using the registerStore
function. Code can then access that data by using dispatch
, select
, and subscribe
. These functions can be accessed by calling the useRegistry
hook. Components can most easily use the data with the useDispatch
and useSelect
hooks. Read the @wordpress/data docs to learn more about the details of this system.
In addition to the features of that package, we provide a useRegisterStore
hook which takes the same arguments as registerStore
and will allow creating a new store just before a component first renders.
The registry used for these stores is created by default but you can use a custom one by including the registry
prop on CheckoutProvider
. If you want to use the default registry, you can import it directly from this package using #defaultRegistry, and for convenience, #registerStore.
API
While the Checkout
component takes care of most everything, there are many situations where its appearance and behavior will be customized. In these cases it's appropriate to use the underlying building blocks of this package. The following are in alphabetical order.
Button
A generic button component that is used internally for almost all buttons (like the "Continue" button on each step). You can use it if you want a button with a similar appearance. It has the following explicit props, and any additional props will be passed on directly to the HTML button
(eg: onClick
).
-
buttonType?: 'paypal'|'primary'|'secondary'|'text-button'|'borderless'
. An optional special button style. -
fullWidth?: bool
. The button width defaults to 'auto', but if this is set it will be '100%'. -
isBusy?: bool
. If true, the button will be displayed as a loading spinner.
Checkout
The main wrapper component for Checkout. It has the following props.
-
className?: string
. The className for the component.
CheckoutCheckIcon
An icon that is displayed for each complete step.
Requires an id
prop, which is a string that is used to construct the SVG id
.
CheckoutErrorBoundary
A React error boundary that can be used to wrap any components you like. There are several layers of these already built-in to CheckoutProvider
and its children, but you may use this to manually wrap components. It has the following props.
-
errorMessage: React.ReactNode
. The error message to display to the user if there is a problem; typically a string but can also be a component. -
onError?: (string) => void
. A function to be called when there is an error. Can be used for logging.
CheckoutProvider
Renders its children
prop and acts as a React Context provider. All of checkout should be wrapped in this.
It has the following props.
-
items: object[]
. An array of line item objects that will be displayed in the form. -
total: object
. A line item object with the final total to be paid. -
theme?: object
. A theme object. -
onPaymentComplete?: ({paymentMethodId: string | null, transactionLastResponse: unknown }) => null
. A function to call for non-redirect payment methods when payment is successful. Passed the current payment method id and the transaction response as set by the payment processor function. -
onPaymentRedirect?: ({paymentMethodId: string | null, transactionLastResponse: unknown }) => null
. A function to call for redirect payment methods when payment begins to redirect. Passed the current payment method id and the transaction response as set by the payment processor function. -
onPaymentError?: ({paymentMethodId: string | null, transactionError: string | null }) => null
. A function to call for payment methods when payment is not successful. -
onEvent?: (action) => null
. A function called for all sorts of events in the code. The callback will be called with a Flux Standard Action. -
paymentMethods: object[]
. An array of Payment Method objects. -
paymentProcessors: object
. A key-value map of payment processor functions (see Payment Methods). -
registry?: object
. An object returned by createRegistry. If not provided, the default registry will be used. -
isLoading?: boolean
. If set and true, the form will be replaced with a loading placeholder and the form status will be set to.LOADING
(see useFormStatus). -
isValidating?: boolean
. If set and true, the form status will be set to.VALIDATING
(see useFormStatus). -
redirectToUrl?: (url: string) => void
. Will be used by useTransactionStatus if it needs to redirect. If not set, it will changewindow.location.href
. -
initiallySelectedPaymentMethodId?: string | null
. If set, is used to preselect a payment method when thepaymentMethods
array changes. Default isnull
, which yields no initial selection. To change the selection in code, see theusePaymentMethodId
hook.
The line items are for display purposes only. They should also include subtotals, discounts, and taxes. No math will be performed on the line items. Instead, the amount to be charged will be specified by the required prop total
, which is another line item.
In addition, CheckoutProvider
monitors the transaction status and will take actions when it changes.
- If the
transactionStatus
changes to.PENDING
, the form status will be set to.SUBMITTING
. - If the
transactionStatus
changes to.ERROR
, the transaction status will be set to.NOT_STARTED
, the form status will be set to.READY
, and the error message will be displayed. - If the
transactionStatus
changes to.COMPLETE
, the form status will be set to.COMPLETE
(which will cause theonPaymentComplete
function to be called). - If the
transactionStatus
changes to.REDIRECTING
, the page will be redirected to thetransactionRedirectUrl
(or will display an error as above if there is no url). - If the
transactionStatus
changes to.NOT_STARTED
, the form status will be set to.READY
.
CheckoutReviewOrder
Renders a list of the line items and their displayValue
properties followed by the total
line item, and whatever submitButton
is in the current payment method.
CheckoutStep
A checkout step. This should be a direct child of CheckoutSteps and is itself a wrapper for CheckoutStepBody. If you want to make something that looks like a step but is not connected to other steps, use a CheckoutStepBody instead.
This component's props are:
-
stepId: string
. A unique ID for the step. -
className?: string
. A className for the step wrapper. -
titleContent: React.ReactNode
. Displays as the title of the step. -
activeStepContent?: React.ReactNode
. Displays as the content of the step when it is active. It is also displayed when the step is inactive but is hidden by CSS. -
completeStepContent?: React.ReactNode
. Displays as the content of the step when it is inactive and complete as defined by theisCompleteCallback
. -
isCompleteCallback: () => boolean | Promise<boolean>
. Used to determine if a step is complete for purposes of validation. Note that this is not called for the last step! -
editButtonAriaLabel?: string
. Used to fill in thearia-label
attribute for the "Edit" button if one exists. -
nextStepButtonAriaLabel?: string
. Used to fill in thearia-label
attribute for the "Continue" button if one exists. -
editButtonText?: string
. Used in place of "Edit" on the edit step button. -
nextStepButtonText?: string
. Used in place of "Continue" on the next step button. -
validatingButtonText?: string
. Used in place of "Please wait…" on the next step button whenisCompleteCallback
returns an unresolved Promise. -
validatingButtonAriaLabel:? string
. Used for thearia-label
attribute on the next step button whenisCompleteCallback
returns an unresolved Promise.
CheckoutStepArea
Creates the Checkout form and provides a wrapper for CheckoutStep and CheckoutStepBody objects. Should be a direct child of Checkout.
This component's props are:
-
submitButtonHeader: React.ReactNode
. Displays with the Checkout submit button. -
submitButtonFooter: React.ReactNode
. Displays with the Checkout submit button. -
disableSubmitButton: boolean
. If true, the submit button will always be disabled. If false (the default), the submit button will be enabled only on the last step and only if the formStatus is.READY
.
CheckoutStepAreaWrapper
A styled div, controlled by the theme, that's used as the inner wrapper for the CheckoutStepArea component. You shouldn't need to use this manually.
CheckoutStepBody
A component that looks like a checkout step. Normally you don't need to use this directly, since CheckoutStep creates this for you, but you can use it manually if you wish.
This component's props are:
-
stepId: string
. A unique ID for this step. -
isStepActive: boolean
. True if the step should be rendered as active. RendersactiveStepContent
. -
isStepComplete: boolean
. True if the step should be rendered as complete. RenderscompleteStepContent
. -
stepNumber: number
. The step number to display for the step. -
totalSteps: number
. The total number of steps in the current connected group of steps. -
errorMessage?: string
. The error message to display in the React error boundary if there is an error thrown by any component in this step. -
onError?: (string) => void
. A callback to be called from the React error boundary if there is an error thrown by any component in this step. -
editButtonText?: string
. The text to display instead of "Edit" for the edit step button. -
editButtonAriaLabel?: string
. The text to display foraria-label
instead of "Edit" for the edit step button. -
nextStepButtonText?: string
. LikeeditButtonText
but for the "Continue" button. -
nextStepButtonAriaLabel?: string
. LikeeditButtonAriaLabel
but for the "Continue" button. -
validatingButtonText?: string
. LikeeditButtonText
but for the "Please wait…" button whenformStatus
isvalidating
. -
validatingButtonAriaLabel?: string
. LikeeditButtonAriaLabel
but for the "Please wait…" button. -
className?: string
. A className for the component. -
goToThisStep?: () => void
. A function to be called when the "Edit" button is pressed. -
goToNextStep?: () => void
. A function to be called when the "Continue" button is pressed. -
nextStepNumber?: number
. The step number of the step that will be active after the "Continue" button is pressed. -
formStatus?: string
. The current form status. See useFormStatus. -
titleContent: React.ReactNode
. Displays as the title of the step. -
activeStepContent?: React.ReactNode
. Displays as the content of the step when it is active. It is also displayed when the step is inactive but is hidden by CSS. -
completeStepContent?: React.ReactNode
. Displays as the content of the step when it is inactive and complete as defined byisStepComplete
andisStepActive
.
CheckoutSteps
A wrapper for CheckoutStep objects that will connect the steps and provide a way to switch between them. Should be a direct child of Checkout. It has the following props.
-
areStepsActive?: boolean
. Whether or not the set of steps is active and able to be edited. Defaults totrue
.
CheckoutSubmitButton
The submit button for the form. This actually renders the submit button for the currently active payment method, but it provides the onClick
handler to attach it to the payment processor function, a disabled
prop when the form should be disabled, and a React Error boundary. Normally this is already rendered by CheckoutStepArea, but if you want to use it directly, you can.
The props you can provide to this component are as follows.
-
className?: string
. An optional className. -
disabled?: boolean
. The button will automatically be disabled if the form status is notready
, but you can disable it for other cases as well. -
onLoadError?: ( error: string ) => void
. A callback that will be called if the error boundary is triggered.
CheckoutSummaryArea
Renders its children
prop and acts as a wrapper to flow outside of the CheckoutSteps
wrapper (floated on desktop, collapsed on mobile). It has the following props.
-
className?: string
. The className for the component.
CheckoutSummaryCard
Can be used inside CheckoutSummaryArea to render a bordered area.
FormStatus
An enum that holds the values of the form status.
.LOADING
.READY
.SUBMITTING
.VALIDATING
.COMPLETE
MainContentWrapper
A styled div, controlled by the theme, that's used as the inner wrapper for the Checkout component. You shouldn't need to use this manually.
OrderReviewLineItems
Renders a list of line items passed in the items
prop. Each line item must have at least the props label
, id
, and amount.displayValue
.
An optional boolean prop, collapsed
, can be used to simplify the output for when the review section is collapsed.
This component provides just a simple list of label and price. If you want to modify how each line item is displayed, or if you want to provide any actions for that item (eg: the ability to delete the item from the order), you cannot use this component; instead you should create a custom component.
OrderReviewSection
A wrapper for a section of a list of related line items. Renders its children
prop.
OrderReviewTotal
Renders the total
prop like a line item, but with different styling.
An optional boolean prop, collapsed
, can be used to simplify the output for when the review section is collapsed.
PaymentLogo
Renders a logo for a credit card.
Takes two props:
-
brand: string
. This is a lower-case card name, likevisa
ormastercard
. -
isSummary: boolean
. If true, will display a more compact version of the logo.
RadioButton
Renders a radio button wrapper for payment methods or other similar boxes.
Props:
name: string
id: string
label: React.ReactNode
disabled?: boolean
checked?: boolean
value: string
onChange?: () => void
ariaLabel: string
children?: React.ReactNode
PaymentProcessorResponseType
An enum that holds the values of the payment processor function return value's type
property (each payment processor function returns a Promise that resolves to {type: PaymentProcessorResponseType, payload: string | unknown }
where the payload varies based on the response type).
-
.SUCCESS
(the payload will be anunknown
object that is the server response). -
.REDIRECT
(the payload will be astring
that is the redirect URL). -
.MANUAL
(the payload will be anunknown
object that is determined by the payment processor function). -
.ERROR
(the payload will be astring
that is the error message).
SubmitButtonWrapper
A styled div, controlled by the theme, that's used as the inner wrapper for the submit button that's rendered by each CheckoutStepArea component. You shouldn't need to use this manually.
TransactionStatus
An enum that holds the values of the transaction status.
.NOT_STARTED
.PENDING
.COMPLETE
.REDIRECTING
.ERROR
checkoutTheme
An @emotion/styled theme object that can be merged with custom theme variables and passed to CheckoutProvider in order to customize the default Checkout design.
createRegistry
Creates a data store registry to be passed (optionally) to CheckoutProvider. See the @wordpress/data
docs for this function.
defaultRegistry
The default registry. See [#data-stores](Data Stores) for more details.
getDefaultOrderReviewStep
Returns a step object whose properties can be added to a CheckoutStep (and customized) to display an itemized order review.
getDefaultOrderSummaryStep
Returns a step object whose properties can be added to a CheckoutStep (and customized) to display a brief order summary.
getDefaultPaymentMethodStep
Returns a step object whose properties can be added to a CheckoutStep (and customized) to display a way to select a payment method. The payment methods displayed are those provided to the CheckoutProvider.
makeErrorResponse
An action creator function to be used by a payment processor function for a ERROR response. It takes one string argument and will record the string as the error.
makeManualResponse
An action creator function to be used by a payment processor function for a MANUAL response; it will do nothing but pass along its argument as a payload
property to the resolved Promise of the onClick
function.
makeRedirectResponse
An action creator function to be used by a payment processor function for a REDIRECT response. It takes one string argument and will cause the page to redirect to the URL in that string.
makeSuccessResponse
An action creator function to be used by a payment processor function for a SUCCESS response. It takes one object argument which is the transaction response. It will cause checkout to mark the payment as complete and run the onPaymentComplete
function on the CheckoutProvider.
registerStore
The registerStore
function on the [#defaultRegistry](default registry). Don't use this if you create a custom registry.
useAllPaymentMethods
A React Hook that will return an array of all payment method objects. See usePaymentMethod()
, which returns the active object only. Only works within CheckoutProvider.
useDispatch
A React Hook that will return all the bound action creators for a Data store. Only works within CheckoutProvider.
useEvents
A React Hook that will return the onEvent
callback as passed to CheckoutProvider
. Only works within CheckoutProvider.
useFormStatus
A React Hook that will return an object with the following properties. Used to represent and change the current status of the checkout form (eg: causing it to be disabled). This differs from the status of the transaction itself, which is handled by useTransactionStatus.
-
formStatus:
FormStatus
. The current status of the form. -
setFormReady: () => void
. Function to change the form status to.READY
. -
setFormLoading: () => void
. Function to change the form status to.LOADING
. -
setFormValidating: () => void
. Function to change the form status to.VALIDATING
. -
setFormSubmitting: () => void
. Function to change the form status to.SUBMITTING
. Usually you can use setTransactionPending instead, which will call this. -
setFormComplete: () => void
. Function to change the form status to.COMPLETE
. Note that this will triggeronPaymentComplete
from CheckoutProvider. Usually you can use setTransactionComplete instead, which will call this.
Only works within CheckoutProvider which may sometimes change the status itself based on its props.
useIsStepActive
A React Hook that will return true if the current step is the currently active step. Only works within a step.
useIsStepComplete
A React Hook that will return true if the current step is complete as defined by the isCompleteCallback
of that step. Only works within a step.
useLineItems
A React Hook that will return a two element array where the first element is the current array of line items (matching the items
from the CheckoutProvider
), and the second element is the current total (matching the total
from the CheckoutProvider
). Only works within CheckoutProvider.
useLineItemsOfType
A React Hook taking one string argument that will return an array of line items from the cart (derived from the same data returned by useLineItems) whose type
property matches that string. Only works within CheckoutProvider.
usePaymentMethod
A React Hook that will return an object containing all the information about the currently selected payment method (or null if none is selected). The most relevant property is probably id
, which is a string identifying whatever payment method was entered in the payment method step. Only works within CheckoutProvider.
usePaymentMethodId
A React Hook that will return a two element array. The first element is a string representing the currently selected payment method (or null if none is selected). The second element is a function that will replace the currently selected payment method. Only works within CheckoutProvider.
usePaymentProcessor
A React Hook that returns a payment processor function as passed to the paymentProcessors
prop of CheckoutProvider. Takes one argument which is the key of the processor function to return. Throws an Error if the key does not match a processor function. See Payment Methods for an explanation of how this is used. Only works within CheckoutProvider.
usePaymentProcessors
A React Hook that returns all the payment processor functions in a Record.
useProcessPayment
A React Hook that will return the function passed to each payment method's submitButton component. Call it with a payment method ID and data for the payment processor and it will handle the transaction.
useRegisterStore
A React Hook that can be used to create a @wordpress/data store. This is the same as calling registerStore()
but is easier to use within functional components because it will only create the store once. Only works within CheckoutProvider.
useRegistry
A React Hook that returns the @wordpress/data
registry being used. Only works within CheckoutProvider.
useSelect
A React Hook that accepts a callback which is provided the select
function from the Data store. The select()
function can be called with the name of a store and will return the bound selectors for that store. Only works within CheckoutProvider.
useSetStepComplete
A React Hook that will return a function to set a step to "complete". Only works within a step. The function looks like ( stepNumber: number, isComplete: boolean ) => void;
.
useTotal
A React Hook that returns the total
property provided to the CheckoutProvider. This is the same as the second return value of useLineItems but may be more semantic in some cases. Only works within CheckoutProvider
.
useTransactionStatus
A React Hook that returns an object with the following properties to be used by payment methods for storing and communicating the current status of the transaction. This differs from the current status of the form, which is handled by useFormStatus. Note, however, that CheckoutProvider will automatically perform certain actions when the transaction status changes. See CheckoutProvider for the details.
-
transactionStatus:
TransactionStatus
. The current status of the transaction. -
previousTransactionStatus:
TransactionStatus.
. The last status of the transaction. -
transactionError: string | null
. The most recent error message encountered by the transaction if its status is.ERROR
. -
transactionRedirectUrl: string | null
. The redirect url to use if the transaction status is.REDIRECTING
. -
transactionLastResponse: unknown | null
. The most recent full response object as returned by the transaction's endpoint and passed tosetTransactionComplete
. -
resetTransaction: () => void
. Function to change the transaction status to.NOT_STARTED
. -
setTransactionComplete: ( transactionResponse: unknown ) => void
. Function to change the transaction status to.COMPLETE
and save the response object intransactionLastResponse
. -
setTransactionError: ( string ) => void
. Function to change the transaction status to.ERROR
and save the error intransactionError
. -
setTransactionPending: () => void
. Function to change the transaction status to.PENDING
. -
setTransactionRedirecting: ( string ) => void
. Function to change the transaction status to.REDIRECTING
and save the redirect URL intransactionRedirectUrl
.
FAQ
How do I use Credits and Coupons?
Credits, coupons, and discounts are all ways that the line items and the total can be modified, so they must be handled by the parent component.
Do line items need to be products?
No, line items can be anything. The most common use is for products, taxes, subtotals, discounts, and other adjustments to the total price. However, line items can also contain other information that you'd like to display in the review step. If you customize the Order Review step, you will also be able to decide how each line item is presented. Just be aware that line items may be passed along to the server when the purchase is made, depending on the payment method. Check the documentation for each payment method to determine if there are any specific requirements there.
Do line items amount properties have to have an integer value?
The primary properties used in a line item by default are id
(which must be unique), label
(with an optional sublabel
), and amount.displayValue
. The other properties (type
, amount.currency
, amount.value
) are not used outside custom implementations, but it's highly recommended that you provide them. As requirements and customizations change, it can be helpful to have a way to perform calculations, conversions, and sorting on line items, which will require those fields. If any required field is undefined, an error will be thrown to help notice these errors as soon as possible.
Can I add custom properties to line items?
If you need specific custom data as part of a line item so that it can be used in another part of the form, you can add new properties to the line item objects.
Development
In the root of the monorepo, run yarn run composite-checkout-demo
which will start a local webserver that will display the component.
To run the tests for this package, run yarn run test-packages composite-checkout
.