Paypal Knowledge Patch

PayPal Knowledge Patch

Use this skill when implementing or reviewing PayPal Orders API behavior, PayPal JavaScript SDK v6 integration, Braintree-backed PayPal components, payment-method eligibility, or PayPal custom elements.

Apply the quick-reference guidance below first. Open the topic reference that matches the code being changed for the complete set of relevant details.

Reference index

Breaking changes and deprecations

Replace charge_pattern with usage_pattern

charge_pattern is deprecated. Use usage_pattern in Orders billing requests. Orders billing responses also return usage_pattern.

Use the renamed server eligibility helper

Import the plain async fetchEligibleMethods export from @paypal/react-paypal-js/sdk-v6/server.

import { fetchEligibleMethods } from "@paypal/react-paypal-js/sdk-v6/server";

const response = await fetchEligibleMethods({
  environment: "production", // or "sandbox"
  headers,
  payload,
});

The old useFetchEligibleMethods name is deprecated. The related type aliases are also replaced:

The environment option is required. Omitting it throws instead of silently querying sandbox.

Remove nullable message-content handling

PayPalMessagesSession.fetchContent() returns Promise<MessageContent> rather than Promise<MessageContent | null>.

API failures return an empty MessageContent sentinel with no messageItems. The <paypal-message> element then collapses, so null checks are dead code.

Do not pass disabled to the Apple Pay button

ApplePayOneTimePaymentButton no longer has a disabled prop because the <apple-pay-button> element ignored that attribute and manages availability through canMakePayments().

Control any additional presentation state separately.

Use the kebab-case Basic Card attribute

In JSX, pass buyer-country, not buyerCountry:

<paypal-basic-card-button buyer-country="US" />

React versions before 19 lowercase the camel-case form to an attribute that the custom element does not observe.

Load the Google Pay script before mounting

The React Google Pay component raises an error when it mounts without the Google Pay script loaded. It no longer continues without an explicit failure.

Eligibility and provider hydration

Server eligibility requests may include the merchant origin. Their response can hydrate the v6 PayPalProvider, allowing the client to skip a duplicate eligibility request.

Pay Later and Credit buttons require eligibility to be fetched first. Use useEligibleMethods on the client or fetchEligibleMethods on the server.

useBraintreeEligibleMethods fetches and caches funding-source eligibility. BraintreePayPalPayLaterButton uses that provider eligibility when rendering <paypal-pay-later-button>.

Braintree flow reminders

PayPal Messages

useBraintreePayPalMessages creates Braintree-backed <paypal-message> content and returns:

• error
• isReady
• isLoading
• handleFetchContent(options)

The fetched content exposes update({ amount }), which changes the displayed amount without another fetch.

Pay Later

useBraintreePayPalPayLaterSession manages the v6 Pay Later flow through error, isPending, and handleClick.

Session options

The one-time-payment, Pay Later, and checkout-with-vault session types accept:

• shippingCallbackUrl
• shippingAddressOverride
• contactPreference

shippingAddressOverride uses BraintreeShippingAddressOverride. BraintreeEligibilityResult.getDetails() is typed per funding source.

Orders API reminders

Requests

• Trustly payment sources require email_address.
• PUI payment-source requests accept a buyer-specific ID.
• Card payment sources support risk-related attributes.
• Orders supports a server-side shipping callback.
• Apple Pay and Google Pay payment sources support experience context.

Responses and objects

• Orders responses include stored_credentials.
• PayPal Wallet responses include business_name.
• The card object includes merchant_customer_id.

Enums, headers, and limits

• The Orders network enum includes EFTPOS.
• Confirm, Capture, and Authorize endpoints include a Content-Type header.
• An Orders item description supports up to 2,048 characters.
• A billing-agreement description supports up to 255 characters.

SDK v6 integration reminders

Non-React TypeScript users receive HTMLElementTagNameMap types for PayPal, Venmo, Pay Later, Credit, Basic Card, messages, and Apple Pay custom elements.

The @paypal/paypal-js ./sdk-v6 export has a default condition. Bundlers and tracers without a more specific matching condition can resolve the v6 entry rather than falling back to v5.

The v6 OnApproveData type includes vaultSetupToken. The createVaultSetupToken and onApprove contracts cover Venmo save-payment flows that do not make a purchase.