PayPal JS SDK Libraries

The @paypal/react-paypal-js/sdk-v6 entry provides components and hooks for over 45 regional Local Payment Methods (e.g., iDEAL, Bancontact, BLIK, Pix, Klarna).

Integration Patterns

Every LPM provides three primary integration points:

1. <MethodName>OneTimePaymentButton: A self-contained component that renders both required buyer fields (like full name) and the payment button.
2. use<MethodName>OneTimePaymentSession: A hook for full control over the click handler, pending/error states, and custom button UI.
3. <MethodName>PaymentButton: A standalone button that reads its session from context, useful when required fields need to be laid out separately from the button.

Important Constraints

• Presentation Mode: LPMs only support presentationMode="popup". Other modes like "auto" or "modal" are not supported and will cause type errors.
• Dynamic Selection: If you need to select an LPM dynamically (e.g., via an lpm string), use the generic exports: LPMOneTimePaymentButton, useLPMOneTimePaymentSession, LPM_REGISTRY, and LPMName.

import {
  PayPalProvider,
  IdealOneTimePaymentButton,
} from "@paypal/react-paypal-js/sdk-v6";

// ... createOrder and onApprove logic ...

export default function App() {
  return (
    <PayPalProvider
      clientId="YOUR_CLIENT_ID"
      environment="sandbox"
      components={["ideal-payments"]}
      pageType="checkout"
    >
      <IdealOneTimePaymentButton
        presentationMode="popup"
        createOrder={createOrder}
        onApprove={onApprove}
        onCancel={() => console.log("Payment cancelled")}
      />
    </PayPalProvider>
  );
}

For advanced use cases requiring full control over the payment flow (e.g., using custom web components), use the session hooks directly.

Note on Configuration: One-time payment session hooks (like usePayPalOneTimePaymentSession) accept either a static orderId or a createOrder callback. These are mutually exclusive. Use orderId if the order is already created, or createOrder to defer creation until the user clicks the button.

| Hook | Payment Type |
| -------------------------------------- | ------------------- |
| `usePayPalOneTimePaymentSession` | PayPal |
| `useVenmoOneTimePaymentSession` | Venmo |
| `usePayLaterOneTimePaymentSession` | Pay Later |
| `usePayPalGuestPaymentSession` | Basic Card |
| `usePayPalSubscriptionPaymentSession` | Subscriptions |
| `usePayPalSavePaymentSession` | Save Payment Method |
| `usePayPalCreditOneTimePaymentSession` | Credit (One-time) |
| `usePayPalCreditSavePaymentSession` | Credit (Save) |
| `useGooglePayOneTimePaymentSession` | Google Pay |
| `useApplePayOneTimePaymentSession` | Apple Pay |

The react-paypal-js library is composed of two main parts that work together using React's Context API:

1. Context Provider: The <PayPalScriptProvider /> component manages the loading of the PayPal JS SDK script. It should be added to the root of your React application. It handles state management and supports reloading the script when configuration parameters change.
2. SDK Components: Components like <PayPalButtons />, <PayPalHostedField />, or <PayPalCardFieldsForm /> are used to render the actual UI for PayPal products served by the JS SDK.

This architecture ensures that the SDK is loaded once and its state is shared across all UI components.

import { PayPalScriptProvider, PayPalButtons } from "@paypal/react-paypal-js";

export default function App() {
  return (
    <PayPalScriptProvider options={{ clientId: "test" }}>
      <PayPalButtons style={{ layout: "horizontal" }} />
    </PayPalScriptProvider>
  );
}

A complete checkout process involves three tiers: the React application (client), your backend server, and PayPal. The React components are designed to be secure by never handling secret keys or payment amounts directly; these responsibilities remain on your server.

The 4-Step Lifecycle

1. Load: Use PayPalProvider to fetch a browser-safe clientId (or client token) from your server. This loads the SDK once and provides a single checkout-scoped instance.
2. Eligibility: Use the useEligibleMethods() hook to query your server's find-eligible-methods endpoint. This determines which payment methods (e.g., Apple Pay, Google Pay, PayPal) should be rendered based on the buyer, merchant, and amount.
3. Create order: When a user clicks a payment button, the component's createOrder callback triggers a call to your server. Your server then calls PayPal's Orders API to generate an orderId.
4. Capture: Once the buyer approves the transaction, the onApprove callback triggers a call to your server to capture the order via the PayPal Orders API.

Note: Steps 3 and 4 are intentionally server-side to ensure security and integrity.