();
useEffect(() => {
fetchClientId().then(setClientId);
}, []);
return (
);
}
```
### Tracking Loading State
Use the `usePayPal` hook to access the SDK loading status:
```tsx
import {
usePayPal,
INSTANCE_LOADING_STATE,
} from "@paypal/react-paypal-js/sdk-v6";
function CheckoutPage() {
const { loadingStatus, error } = usePayPal();
if (loadingStatus === INSTANCE_LOADING_STATE.PENDING) {
return Loading PayPal...
;
}
if (loadingStatus === INSTANCE_LOADING_STATE.REJECTED) {
return (
Failed to load PayPal SDK: {error?.message}
);
}
return ;
}
```
## Button Components
### PayPalOneTimePaymentButton
Renders a PayPal button for one-time payments.
```tsx
import { PayPalOneTimePaymentButton } from "@paypal/react-paypal-js/sdk-v6";
{
const response = await fetch("/api/create-order", { method: "POST" });
const { orderId } = await response.json();
return { orderId };
}}
onApprove={async ({ orderId }: OnApproveDataOneTimePayments) => {
await fetch(`/api/capture/${orderId}`, { method: "POST" });
console.log("Payment approved!");
}}
onCancel={(data: OnCancelDataOneTimePayments) =>
console.log("Payment cancelled")
}
onError={(data: OnErrorData) => console.error("Payment error:", data)}
onComplete={(data: OnCompleteData) => console.log("Payment Flow Completed")}
/>;
```
**Props:**
| Prop | Type | Description |
| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------ |
| `orderId` | `string` | Static order ID (alternative to `createOrder`) |
| `createOrder` | `() => Promise<{ orderId: string }>` | Async function to create an order |
| `presentationMode` | `"auto" \| "popup" \| "modal" \| "redirect"` | How to present the payment session (default: `"auto"`) |
| `onApprove` | `(data) => void` | Called when payment is approved |
| `onCancel` | `() => void` | Called when buyer cancels |
| `onError` | `(error) => void` | Called on error |
| `onComplete` | `(data) => void` | Called when payment session completes |
| `type` | `"pay" \| "checkout" \| "buynow" \| "donate" \| "subscribe"` | Button label type |
| `disabled` | `boolean` | Disable the button |
### VenmoOneTimePaymentButton
Renders a Venmo button for one-time payments. Requires `"venmo-payments"` in the provider's `components` array.
```tsx
import { VenmoOneTimePaymentButton } from "@paypal/react-paypal-js/sdk-v6";
{
const { orderId } = await createOrder();
return { orderId };
}}
onApprove={(data: OnApproveDataOneTimePayments) =>
console.log("Venmo payment approved!", data)
}
onCancel={(data: OnCancelDataOneTimePayments) =>
console.log("Venmo payment cancelled", data)
}
onError={(data: OnErrorData) =>
console.error("Venmo payment error:", data)
}
onComplete={(data: OnCompleteData) =>
console.log("Venmo payment flow completed", data)
}
/>
;
```
### PayLaterOneTimePaymentButton
Renders a Pay Later button for financing options. Country code and product code are automatically populated from eligibility data.
```tsx
import { PayLaterOneTimePaymentButton } from "@paypal/react-paypal-js/sdk-v6";
{
const { orderId } = await createOrder();
return { orderId };
}}
onApprove={(data: OnApproveDataOneTimePayments) =>
console.log("Pay Later approved!", data)
}
onCancel={(data: OnCancelDataOneTimePayments) =>
console.log("Pay Later cancelled", data)
}
onError={(data: OnErrorData) => console.error("Pay Later error:", data)}
onComplete={(data: OnCompleteData) =>
console.log("Pay Later flow completed", data)
}
/>;
```
### PayPalGuestPaymentButton
Renders a guest checkout button for card payments without a PayPal account (Branded Card/Debit Card checkout). Requires `"paypal-guest-payments"` in the provider's `components` array.
```tsx
import { PayPalGuestPaymentButton } from "@paypal/react-paypal-js/sdk-v6";
{
const { orderId } = await createOrder();
return { orderId };
}}
onApprove={(data: OnApproveDataOneTimePayments) =>
console.log("Guest payment approved!", data)
}
onCancel={(data: OnCancelDataOneTimePayments) =>
console.log("Guest payment cancelled", data)
}
onError={(data: OnErrorData) =>
console.error("Guest payment error:", data)
}
onComplete={(data: OnCompleteData) =>
console.log("Guest payment flow completed", data)
}
/>
;
```
### PayPalSavePaymentButton
Renders a button for vaulting a payment method without making a purchase.
```tsx
import { PayPalSavePaymentButton } from "@paypal/react-paypal-js/sdk-v6";
{
const response = await fetch("/api/create-vault-token", {
method: "POST",
});
const { vaultSetupToken } = await response.json();
return { vaultSetupToken };
}}
onApprove={({ vaultSetupToken }: OnApproveDataSavePayments) => {
console.log("Payment method saved:", vaultSetupToken);
}}
onCancel={(data: OnCancelDataSavePayments) =>
console.log("Save payment cancelled", data)
}
onError={(data: OnErrorData) => console.error("Save payment error:", data)}
onComplete={(data: OnCompleteData) =>
console.log("Save payment flow completed", data)
}
/>;
```
### PayPalSubscriptionButton
Renders a PayPal button for subscription payments. Requires `"paypal-subscriptions"` in the provider's `components` array.
```tsx
import { PayPalSubscriptionButton } from "@paypal/react-paypal-js/sdk-v6";
{
const response = await fetch("/api/create-subscription", {
method: "POST",
});
const { subscriptionId } = await response.json();
return { subscriptionId };
}}
onApprove={(data: OnApproveDataOneTimePayments) =>
console.log("Subscription approved:", data)
}
onCancel={(data: OnCancelDataOneTimePayments) =>
console.log("Subscription cancelled", data)
}
onError={(data: OnErrorData) =>
console.error("Subscription error:", data)
}
onComplete={(data: OnCompleteData) =>
console.log("Subscription flow completed", data)
}
/>
;
```
### PayPalCreditOneTimePaymentButton
Renders a PayPal Credit button for one-time payments. The `countryCode` is automatically populated from eligibility data.
```tsx
import { PayPalCreditOneTimePaymentButton } from "@paypal/react-paypal-js/sdk-v6";
{
const response = await fetch("/api/create-order", { method: "POST" });
const { orderId } = await response.json();
return { orderId };
}}
onApprove={({ orderId }: OnApproveDataOneTimePayments) =>
console.log("Credit payment approved:", orderId)
}
onCancel={(data: OnCancelDataOneTimePayments) =>
console.log("Credit payment cancelled", data)
}
onError={(data: OnErrorData) =>
console.error("Credit payment error:", data)
}
onComplete={(data: OnCompleteData) =>
console.log("Credit payment flow completed", data)
}
/>;
```
### PayPalCreditSavePaymentButton
Renders a PayPal Credit button for saving a credit payment method (vaulting).
```tsx
import { PayPalCreditSavePaymentButton } from "@paypal/react-paypal-js/sdk-v6";
{
const response = await fetch("/api/create-vault-token", {
method: "POST",
});
const { vaultSetupToken } = await response.json();
return { vaultSetupToken };
}}
onApprove={(data: OnApproveDataSavePayments) =>
console.log("Credit saved:", data)
}
onCancel={(data: OnCancelDataSavePayments) =>
console.log("Credit save cancelled", data)
}
onError={(data: OnErrorData) => console.error("Credit save error:", data)}
onComplete={(data: OnCompleteData) =>
console.log("Credit save flow completed", data)
}
/>;
```
## Payment Flow
1. User clicks a payment button
2. `handleClick()` starts the payment session
3. `createOrder` callback creates an order via your backend API
4. PayPal opens the checkout experience (popup/modal/redirect)
5. On approval, `onApprove` callback captures the order via the backend
6. Success/error handling displays the result to the user
## Card Fields Components
Card Fields components provide customizable card input fields for collecting payment details directly on your page.
Requires `"card-fields"` in the provider's `components` array.
### PayPalCardFieldsProvider
Wraps card field components and manages the Card Fields session.
```tsx
import {
PayPalProvider,
PayPalCardFieldsProvider,
} from "@paypal/react-paypal-js/sdk-v6";
function App() {
return (
);
}
function CheckoutForm() {
return (
);
}
```
**Props:**
| Prop | Type | Required | Description |
| --------------------- | ----------------- | -------- | --------------------------------------------------------------------------------- |
| `amount` | `OrderAmount` | No | Amount for the card transaction (e.g., `{ value: "10.00", currencyCode: "USD" }`) |
| `isCobrandedEligible` | `boolean` | No | Enable co-branded card eligibility |
| `blur` | `(event) => void` | No | Callback when a field loses focus |
| `change` | `(event) => void` | No | Callback when field value changes |
| `focus` | `(event) => void` | No | Callback when field receives focus |
| `empty` | `(event) => void` | No | Callback when field becomes empty |
| `notempty` | `(event) => void` | No | Callback when field becomes non-empty |
| `validitychange` | `(event) => void` | No | Callback when field validity changes |
| `cardtypechange` | `(event) => void` | No | Callback when detected card type changes |
| `inputsubmit` | `(event) => void` | No | Callback when submit key is pressed in field |
### PayPalCardNumberField
Renders a card number input field. Must be used within a [PayPalCardFieldsProvider](#paypalcardfieldsprovider) component.
```tsx
import { PayPalCardNumberField } from "@paypal/react-paypal-js/sdk-v6";
;
```
### PayPalCardExpiryField
Renders a card expiry input field. Must be used within a [PayPalCardFieldsProvider](#paypalcardfieldsprovider) component.
```tsx
import { PayPalCardExpiryField } from "@paypal/react-paypal-js/sdk-v6";
;
```
### PayPalCardCvvField
Renders a CVV input field. Must be used within a [PayPalCardFieldsProvider](#paypalcardfieldsprovider) component.
```tsx
import { PayPalCardCvvField } from "@paypal/react-paypal-js/sdk-v6";
;
```
### Field Component Props
All field components ([`PayPalCardNumberField`](#paypalcardnumberfield), [`PayPalCardExpiryField`](#paypalcardexpiryfield), [`PayPalCardCvvField`](#paypalcardcvvfield)) accept the same set of props. They combine container styling properties with CardField-specific configuration options.
| Prop | Type | Required | Description |
| ------------------------- | --------------------- | -------- | ---------------------------------------------- |
| `placeholder` | `string` | No | Placeholder text for the field |
| `label` | `string` | No | Label text for the field |
| `style` | `MerchantStyleObject` | No | Style object for the field |
| `ariaLabel` | `string` | No | ARIA label for accessibility |
| `ariaDescription` | `string` | No | ARIA description for accessibility |
| `ariaInvalidErrorMessage` | `string` | No | ARIA error message when field is invalid |
| `containerStyles` | `React.CSSProperties` | No | CSS styles for the field container wrapper |
| `containerClassName` | `string` | No | CSS class name for the field container wrapper |
## Payment Flow: Card Fields
1. User enters card number, expiry, and CVV in the card fields
2. User clicks your submit button
3. `createOrder` creates an order via your backend API
4. `submit(orderId)` processes the card payment with the order ID
5. `submitResponse` object gets updated with the payment result
6. Handle submit response based on payment result
## Hooks API
### usePayPal
Returns the PayPal context including the SDK instance and loading status.
```tsx
import {
usePayPal,
INSTANCE_LOADING_STATE,
} from "@paypal/react-paypal-js/sdk-v6";
function MyComponent() {
const {
sdkInstance, // The PayPal SDK instance
eligiblePaymentMethods, // Eligible payment methods
loadingStatus, // PENDING | RESOLVED | REJECTED
error, // Any initialization error
isHydrated, // SSR hydration status
} = usePayPal();
const isPending = loadingStatus === INSTANCE_LOADING_STATE.PENDING;
const isReady = loadingStatus === INSTANCE_LOADING_STATE.RESOLVED;
// ...
}
```
### useEligibleMethods
Returns eligible payment methods and loading state. Use this to conditionally render payment buttons based on eligibility. This hook also updates the `PayPalProvider` reducer with Eligibility Output from the SDK, enabling built-in eligibility features in the UI Button components.
```tsx
import { useEligibleMethods } from "@paypal/react-paypal-js/sdk-v6";
function PaymentOptions() {
const { eligiblePaymentMethods, isLoading, error } = useEligibleMethods();
if (isLoading) return Checking eligibility...
;
const isPayPalEligible = eligiblePaymentMethods?.isEligible("paypal");
const isVenmoEligible = eligiblePaymentMethods?.isEligible("venmo");
const isPayLaterEligible = eligiblePaymentMethods?.isEligible("paylater");
return (
{isPayPalEligible &&
}
{isVenmoEligible &&
}
{isPayLaterEligible &&
}
