An app integrating PayPal Checkout with Smart Payment Buttons with a VTEX IO store. This allows a store to place PayPal's Smart Buttons in the VTEX cart, offering a quick checkout via the familiar PayPal experience. The app also makes PayPal available within VTEX's native checkout. This app utilizes VTEX's Payment Provider Framework SDK.

Because they allow a user to skip the normal VTEX checkout, the Smart Buttons cannot be used in combination with gift cards or other split payment methods.

Please reference PayPal's documentation in regard to supported currencies.

For best results, we recommend configuring your PayPal account to obtain the buyer's phone number during checkout.

• Adds PayPal's Smart Payment Buttons to your store's cart page, allowing users to place orders using PayPal's checkout experience instead of the standard VTEX checkout
• Also allows the user to use PayPal as a payment method in the standard VTEX checkout
• Allows the VTEX Payment Gateway's auto-settle behavior to be configured or disabled
• Allows PayPal Credit ("Pay Later") messaging to be displayed on the PDP and in product shelves

Only users with access to the Payments section in the VTEX admin (or assigned the PCI Gateway role in License Manager) will be able to configure the app.

1. Install this app from the VTEX App Store by clicking Get App.
2. In your VTEX admin dashboard, go to Payments > PayPal.
3. Confirm your PayPal account email address. If you don't already have a PayPal account, you will be walked through the steps to create one. If you want to use an email other than your VTEX account's email address, click the Change button. Clicking Change will also allow you to toggle into Sandbox Mode for testing purposes. (Note: If you onboard in Sandbox Mode, you will eventually need to disconnect your sandbox account and perform the onboarding again with a production PayPal account when you are ready to accept live payments.)
4. Click Connect and follow PayPal's prompts to complete the onboarding. This process will grant VTEX permission to process PayPal transactions on your behalf.
5. When onboarding is complete, you should be returned to the VTEX admin dashboard, where you will see a PayPal Account Status page. You can also return to this page by going to Payments > PayPal from the VTEX admin sidebar. On this page, if you see the message You are ready to accept PayPal payments in checkout!, you may proceed to the next step. If not, the page will list the necessary actions to be completed before you are able to accept payments.

7. In your VTEX admin dashboard, go to Payments > Settings.
8. Click the Gateway Affiliations tab at the top of the screen, and then the green + button in the upper right corner to create a new Gateway Affiliation.
   • Choose PayPalCP from the list of connectors.
   • Enter a name of your choice for the affiliation.
   • If the Test/Live toggle is set to Test mode, a workspace input field will appear, allowing you to test the PayPal app in a workspace other than master. Note that you may need to save the affiliation and then edit it again before the field will appear. After testing is complete, make sure to set this back to master. Do not erase the contents of this field.
   • Application Key and Application Token should be left blank.
   • The Payment Capture dropdown allows you to control (or disable) VTEX's auto-settle behavior. If you choose the default Use Behavior Recommended By The Payment Processor option, payments will be automatically settled 24 hours after authorization.
   • If the Deactivated: Not Automatically Captured option is chosen, the payment will be captured at the moment the Order associated with that payment is invoiced.
   • After configuring the above options, click Save.
9. ⚠️ Important note: Completing the next step (step 10) will cause a new payment option to appear in your store's checkout. Do not complete this step until you are ready to begin accepting PayPal orders. Alternatively, consider making the Payment Condition active only for an employees-only sales channel so that the payment method can be tested prior to going live.
10. Return to Payments > Settings and click the Payment Conditions tab at the top of the screen, and then the green + button in the upper right corner to create a new Payment Condition. Choose PayPalCP from the list of payment methods. Verify that the condition is set to process with the affiliation that you named in step 8 and that the toggle is set to Active. Click Save.

11. Run the following command in the VTEX CLI: vtex install vtex.paypalcp-checkout-ui-settings
    • This step is optional if you do not wish to display the Smart Payment Buttons on the VTEX checkout's shopping cart page.
    • This will install a secondary app that will inject the necessary scripts into the VTEX checkout environment. Note that the buttons will not yet appear in checkout until the following steps are completed.
12. In your VTEX admin dashboard, return to Payments > PayPal.
13. In the PayPal Settings section, adjust the Smart Payment Buttons layout and appearance settings as desired.
    • You may also disable the PayPal Credit "Pay Later" button here, if desired. If you are not in a region where PayPal Credit is available, this setting will have no effect.
    • Similarly, you may disable the "Debit or Credit Card" smart button here, if desired. This button is related to PayPal's Guest Checkout feature.
    • You may also enable Immediate Capture here, if desired. If enabled, PayPal payments will be captured immediately at time of checkout. Behind the scenes, the PayPal order is created using intent: 'CAPTURE' rather than intent: 'AUTHORIZE'. This setting must be enabled if you are a merchant located in Brazil or Mexico and wish to offer PayPal payments in installments.
14. If you are ready to enable the Smart Payment Buttons for your store users, activate the Show PayPal Buttons toggle and click Save.
15. The PayPal Smart Payment Buttons will now appear on the Cart page within checkout, directly below the standard Checkout button (and, if using Customization, wherever the block has been placed).

• Enable Pickup in Store via Smart Buttons - Choose whether to allow shoppers to select from your store pickup options when checking out via the Smart Buttons. Note that only the pickup point's name will be displayed in PayPal's UI, so make sure that your pickup points have descriptive names in VTEX before enabling. Shoppers will be able to see the full pickup address after placing the order.
• Invoice ID - Choose which value to use as the invoice_id in PayPal orders. Default is set to VTEX order sequence (reference) number.
• Custom ID - Choose which value to use as the custom_id in PayPal orders. Default is set to VTEX order ID.

To display PayPal Credit promotional messaging on your PDP and/or product shelves, simply modify your store-theme to place the product-installments block in the desired location. This block is provided by the core Product Price app, so no change to your store-theme's dependencies should be needed. When the PayPal app is installed in the same account, it will automatically fill the product-installments block with PayPal's messaging.

Note that promotional messaging will not be displayed if you have chosen to disable the PayPal Credit Smart Payment Button, or if the product-installments block is not present in your store-theme.

If you wish to display the PayPal Smart Payment Buttons in another place in addition to the cart page, such as within the minicart, you may follow these instructions:

1. Install this app in your account (see step 1 of Installation & Onboarding above).
2. Modify your store-theme's manifest.json file to add this app to its peerDependencies like so:

3. Modify the JSON within your store-theme's store folder to place the block "one-click-buy.paypal-checkout-button" in the desired location. The block accepts no props.
4. Continue following the Installation & Onboarding instructions from step 3.

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.

CSS Handles
payPalButtonContainer
payPalErrorModal
payPalProcessingModal
payPalPayLaterMessageContainer