DOCSEARCHbyAlgolia
Submit Docs

PayPal Checkout Components

repository·main·Indexed 23 days ago

https://github.com/paypal/paypal-checkout-components

A set of zoid-powered components for integrating PayPal Buttons and checkout flows into websites. Includes documentation on the two-phased rendering strategy for buttons, the checkout lifecycle involving the PayPal SDK, and the use of window.xprops for handling payment tokens, funding sources, and authorization callbacks like onAuthorize() and onShippingChange().

Tokens
8.4K
Snippets
13
Records
51
Agent score
79%

What's inside @paypal/checkout-components

  1. How the Checkout Component flow works

    main

    The Checkout Component follows a specific lifecycle involving the merchant's page, the PayPal SDK, and a popup window:

    1. Merchant Setup: The merchant adds the PayPal SDK script (e.g., https://www.paypal.com/sdk/js?client-id=xyz) to their page.
    2. Button Rendering: The merchant renders smart-payment-buttons using paypal.Buttons({ ...props }).render('#container').
    3. Iframe Injection: The SDK renders an iframe containing the PayPal buttons.
    4. Triggering Checkout: When a buyer clicks a button, the SDK calls paypal.Checkout({ ...props }).render('body') to load the checkout flow in a popup.
    5. Token Retrieval: The checkout app retrieves the order ID or EC token via window.xprops.payment().
    6. Completion: Once the buyer completes the flow, the child window notifies the merchant via window.xprops.onAuthorize().
    7. Capture: The merchant then calls PayPal to capture the payment.

  2. How the two-phased render works for Buttons

    main

    The Buttons component uses a two-phased rendering strategy to optimize performance and handle logos:

    1. First Render (Client-side): Buttons are rendered inside an <iframe> using the JS SDK script. At this stage, the <iframe> has no src attribute. To minimize bundle size, SVG logos are loaded as external images from the www.paypalobjects.com CDN (e.g., using <PayPalLogoExternalImage />). The __WEB__ global variable is true during this phase.

    2. Second Render (Server-side): The <iframe> is fully rendered by setting the src attribute, which triggers an HTTP request to PayPal's servers (www.paypal.com). To prevent issues during this phase, SVG logos are inlined (e.g., using <PayPalLogoInlineSVG />). The __WEB__ global variable is false during this phase.

  4. Run all testing tasks

    main

    The npm test command executes a suite of testing tasks including lint, flow, karma, jest-ssr, jest-screenshot, and check-size. You can pass the following flags to the test command:

    • --clear-cache: Clear Babel Loader and PhantomJS cache
    • --debug: Debug mode for PhantomJS, Karma, and CheckoutJS
    • --quick: Fastest testing with minimal output and no coverage
    • --browser: Choose a specific browser
    npm test

  5. Run Karma tests

    main

    Karma is used to run integration and end-to-end tests located in test/e2e/ and test/integration/ using the Mocha framework. You can use specific flags to assist with debugging:

    • --keep-open: Keeps the test browser window open to allow debugging.
    • --capture-console: Dumps the browser's console output into the terminal.
    npm run karma

# Keep browser open for debugging
npm run karma -- --keep-open

# Dump console output to terminal
npm run karma -- --capture-console

  10. Configure iframe permissions for Checkout

    main

    In some scenarios, the checkout window must be loaded within an iframe. You must handle this on both the server and the client.

    Server-side: If the request contains the sdkMeta query parameter, do not send the X-FRAME-OPTIONS header. This allows the page to be framed.

    Client-side: Validate whether iframes are permitted using paypal.allowIframe() to prevent errors in unsupported environments.

    if (window !== window.parent && !paypal.allowIframe()) {
	// Show an error page
}