diff --git a/src/content/docs/dropins/payment-services/containers/paypal-buttons.mdx b/src/content/docs/dropins/payment-services/containers/paypal-buttons.mdx index 14f499c14..1d9c79788 100644 --- a/src/content/docs/dropins/payment-services/containers/paypal-buttons.mdx +++ b/src/content/docs/dropins/payment-services/containers/paypal-buttons.mdx @@ -7,6 +7,7 @@ sidebar: import TableWrapper from '@components/TableWrapper.astro'; import Link from '@components/Link.astro'; +import { Aside } from '@astrojs/starlight/components'; The `PayPalButtons` container renders a set of checkout buttons that enable shoppers to pay using — including PayPal, Venmo, Pay Later, and debit/credit card, depending on which funding sources are enabled for the merchant. @@ -17,6 +18,7 @@ The `PayPalButtons` container provides the following configuration options: | Option | Type | Req? | Description | |--------|------|------|-------------| +| `location` | string | Yes | Location where the PayPal buttons are rendered. Possible values are: `CHECKOUT` and `PRODUCT_DETAIL`. | | `onButtonClick` | function | No | Called when the shopper clicks a PayPal button. Receives a `showPaymentSheet` function, which must be called synchronously to begin the PayPal checkout and show the payment sheet. If not provided, clicking the button automatically triggers the payment sheet. | | `onSuccess` | function | No | Called when the payment completes successfully. Receives `{ cartId: string }`. If the function returns a promise, it is awaited before marking the payment as successful. If the promise rejects, the payment is marked as failed and the error is passed to `onError` (if provided). | | `onError` | function | No | Called when the payment flow fails or is aborted. Receives `{ name: string, message: string }`, containing localized, user-facing error details. These values can be translated using `PaymentServices.PayPalButtons.errors` [language definitions](/dropins/payment-services/dictionary/). | @@ -38,9 +40,35 @@ The following example demonstrates how to use the `PayPalButtons` container on t import PayPalButtons from '@dropins/storefront-payment-services/containers/PayPalButtons.js'; import { render as PaymentServices } from '@dropins/storefront-payment-services/render.js'; import * as orderApi from '@dropins/storefront-order/api.js'; +import { PaymentLocation } from '@dropins/storefront-payment-services/api.js'; const $content = document.createElement('div'); PaymentServices.render(PayPalButtons, { + location: PaymentLocation.CHECKOUT, + onSuccess: ({ cartId }) => orderApi.placeOrder(cartId), + onError: (error) => { console.error(error) }, +})($content); +``` + +### Product details page example + +The `PayPalButtons` container builds its own shadow cart from the Product Details drop-in's and events on the product details page. + + + +The following example demonstrates how to use the `PayPalButtons` container on the product details page. + +```js +import PayPalButtons from '@dropins/storefront-payment-services/containers/PayPalButtons.js'; +import { render as PaymentServices } from '@dropins/storefront-payment-services/render.js'; +import * as orderApi from '@dropins/storefront-order/api.js'; +import { PaymentLocation } from '@dropins/storefront-payment-services/api.js'; + +const $content = document.createElement('div'); +PaymentServices.render(PayPalButtons, { + location: PaymentLocation.PRODUCT_DETAIL, onSuccess: ({ cartId }) => orderApi.placeOrder(cartId), onError: (error) => { console.error(error) }, })($content); diff --git a/src/content/docs/dropins/payment-services/events.mdx b/src/content/docs/dropins/payment-services/events.mdx index e51d28cb5..85262a86e 100644 --- a/src/content/docs/dropins/payment-services/events.mdx +++ b/src/content/docs/dropins/payment-services/events.mdx @@ -7,6 +7,7 @@ sidebar: --- import TableWrapper from '@components/TableWrapper.astro'; +import Link from '@components/Link.astro'; The Payment Services drop-in uses the [event bus](/sdk/reference/events) to emit and listen for events, enabling communication between drop-ins and external integrations. @@ -21,8 +22,8 @@ The Payment Services drop-in uses the [event bus](/sdk/reference/events) to emit | [checkout/updated](#checkoutupdated-listens) | Listens | Fired by the [Checkout](/dropins/checkout/events/) drop-in when the checkout state is updated. Read by the `GooglePay` container at button click time to determine the selected shipping method and billing address. | | [payment-services/initialized/checkout](#payment-servicesinitializedcheckout-emits) | Emits | Emitted when the drop-in finishes initializing for the `CHECKOUT` location. | | [payment-services/initialized/product-detail](#payment-servicesinitializedproduct-detail-emits) | Emits | Emitted when the drop-in finishes initializing for the `PRODUCT_DETAIL` location. | -| [pdp/data](#pdpdata-listens) | Listens | Fired by the [Product Details](https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpdata-emits-and-listens) drop-in with product data for the page. Used by the `GooglePay` container on the `PRODUCT_DETAIL` location to build the shadow cart. | -| [pdp/values](#pdpvalues-listens) | Listens | Fired by the [Product Details](https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpvalues-emits-and-listens) drop-in with the shopper's selected product SKU, quantity, and options. Used by the `GooglePay` container on the `PRODUCT_DETAIL` location to build the shadow cart. | +| [pdp/data](#pdpdata-listens) | Listens | Emitted by the drop-in with product data for the page. The `GooglePay` and `PayPalButtons` containers listen to this event on the `PRODUCT_DETAIL` location to build the shadow cart. | +| [pdp/values](#pdpvalues-listens) | Listens | Sent by the drop-in containing the shopper's selected product SKU, quantity, and options. The `GooglePay` and `PayPalButtons` containers use this event on the `PRODUCT_DETAIL` location to build the shadow cart. | ## Event details @@ -137,9 +138,9 @@ See [Payment method availability](/dropins/payment-services/initialization/#paym ### `pdp/data` (listens) -Fired by the [Product Details](https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpdata-emits-and-listens) drop-in with product data for the page. The `GooglePay` container listens to this event, together with [`pdp/values`](#pdpvalues-listens), to build a shadow cart when the shopper clicks the Google Pay button on the `PRODUCT_DETAIL` location. +Emitted by the drop-in with product data for the page. The `GooglePay` and `PayPalButtons` containers listen to this event, together with [`pdp/values`](#pdpvalues-listens), to build a shadow cart when the shopper clicks a Google Pay or PayPal button on the `PRODUCT_DETAIL` location. -Both events must have been emitted at least once on the event bus before clicking the Google Pay button. +Both events must have been emitted at least once on the event bus before clicking a Google Pay or PayPal button. #### Event payload @@ -163,9 +164,9 @@ events.on('pdp/data', (payload) => { ### `pdp/values` (listens) -Fired by the [Product Details](https://experienceleague.adobe.com/en/tools/commerce-storefront/dropins/product-details/events/#pdpvalues-emits-and-listens) drop-in with the shopper's currently selected product SKU, quantity, and options. The `GooglePay` container listens to this event, together with [`pdp/data`](#pdpdata-listens), to build a shadow cart when the shopper clicks the Google Pay button on the `PRODUCT_DETAIL` location. +Sent by the drop-in with the shopper's currently selected product SKU, quantity, and options. The `GooglePay` and `PayPalButtons` containers listen to this event, together with [`pdp/data`](#pdpdata-listens), to build a shadow cart when the shopper clicks a Google Pay or PayPal button on the `PRODUCT_DETAIL` location. -Both events must have been emitted at least once on the event bus before clicking the Google Pay button. +Both events must have been emitted at least once on the event bus before clicking a Google Pay or PayPal button. #### Event payload