Skip to main content
This guide shows how to:
  • Load the JavaScript SDK v6 core script
  • Initialize an SDK instance using a browser-safe client token
  • Render Card Fields (number, CVV, expiry)
  • Create and submit an order
  • Capture the order and handle 3-D Secure (3DS) outcomes
You’ll wire up three backend routes:
  • GET /paypal-api/auth/browser-safe-client-token: returns a browser-safe token
  • POST /paypal-api/checkout/orders/create-with-sample-data: returns a new orderId
  • POST /paypal-api/checkout/orders/{orderId}/capture captures the order

Prerequisites

You’ll need the following:
  • A PayPal sandbox business account and REST app with permissions to create client tokens.
  • A server capable of calling PayPal APIs securely. Node and Express examples included below.
  • PCI Compliance. PCI DSS SAQ A-EP considerations: Card fields are hosted or iframes from PayPal. Your page must follow security best practices.

Add the JavaScript SDK script

Include the core script and call the onPayPalWebSdkLoaded() handler when it’s ready.
Keep async to avoid blocking the render.

Build an HTML container

Provide containers for each card field and a pay button. The provided containers must have a defined height and width. The card field fills the entire space of the parent container. The button id in the sample is pay-button. Make sure your JavaScript uses the same selector.

Initialize the SDK and render card fields

Create an SDK instance with your browser‑safe client token, then create a one‑time payment session for credit and debit card fields and mount the components. To pass billing fields, use the submit(orderId, { billingAddress: { ... } }) options object. Include at least the fields you require for your risk and SCA strategy, for example, postalCode.

Create, submit, and capture the order

  1. Create the order on your server, then receive the orderId.
  2. Call cardSession.submit(orderId, options) to handle validations and 3D Secure.
  3. If state === "succeeded", capture the order on your server.

Client helpers

Server examples

The following is a minimal example to support three routes. It uses the PayPal Orders v2 API. Replace placeholders and secure secrets appropriately.

Style card fields

Use the style option to control input styling such as font size and color. Keep contrast AA or better. Avoid setting styles that imply validation, such as red and green, unless synchronized with real validation states. Allowed CSS selectors:
  • appearance
  • background
  • border
  • borderRadius
  • boxShadow
  • color
  • direction
  • font
  • fontFamily
  • fontSize
  • fontSizeAdjust
  • fontStretch
  • fontStyle
  • fontVariant
  • fontVariantAlternates
  • fontVariantCaps
  • fontVariantEastAsian
  • fontVariantLigatures
  • fontVariantNumeric
  • fontWeight
  • height
  • letterSpacing
  • lineHeight
  • opacity
  • outline
  • padding
  • paddingBottom
  • paddingLeft
  • paddingRight
  • paddingTop
  • textShadow
  • transition

Handle outcomes and errors

There are 3 possible outcomes from checkout:
  • state === "succeeded": Proceed to capture on server and show success.
  • state === "canceled": Buyer closed 3DS modal. Allow retry.
  • state === "failed": Inspect data.message and field errors if provided. Keep logs server‑side with correlation IDs from API responses.
Common troubleshooting issues:
  • Button id mismatch: Ensure your JS listens to #pay-button and not #save-payment-method-button.
  • OrderId shape: Pass the string orderId to submit(). Do not pass an object such as { orderId }.
  • Missing breaks in switch: Include break; in each case to avoid fall‑through.

Test

  • Test in the PayPal sandbox environment and use test credit cards.
  • Test the following scenarios:
    • Valid payment
    • Card validation error
    • 3DS succeeded
    • 3DS canceled
    • Network or server error on capture

Production readiness checklist

  • Use production script at https://www.paypal.com/web-sdk/v6/core.
  • Generate client tokens server‑side per session
  • Use CSRF protection on your backend routes
  • Ensure your integration has robust error handling and user‑friendly retry states
  • Ensure your integration logs PayPal API correlation IDs for support
  • Check your site for accessibility by keyboard and screen reader
  • Ensure your Content Security Policy is updated for PayPal domains

Full working example

The following example shows a JavaScript and HTML page that renders card fields for one-time checkout. You can localize placeholder strings when creating each component. When available, use sdk.findEligibleMethods({ currencyCode: "USD" }) and gate Card Fields rendering accordingly. The card may not appear in the eligibility response yet. Integrate defensively.