Save bank details for later use (JavaScript SDK integration)

You can use PayPal’s JavaScript SDK v6 to save Automated Clearing House (ACH) Direct Debit as a payment method for future purchases without an initial transaction, with fully integrated instant bank account verification.

Prerequisites

Ensure you have a PayPal business account approved for Expanded Checkout.
Ensure to set up developer, sandbox, and production environment accounts.
Ensure to complete the account provisioning process to enable ACH payments.

Load PayPal JavaScript SDK

PayPal’s JavaScript SDK provides the necessary pre-built tools to render the Pay with Bank (ACH) button on your webpage and handle payment authorization. Include the JavaScript SDK as a <script> tag in the HTML file that renders your webpage.

<script src="https://www.paypal.com/web-sdk/v6/core"></script>

<script src="https://www.sandbox.paypal.com/web-sdk/v6/core"></script>

Create browser-safe client token

The browser-safe token is a client-side access token that authorizes an app to use the JavaScript SDK resources.

A browser-safe token is not the same as a server-side access token. The server-side access token helps PayPal authenticate an app when the app accesses PayPal REST API resources.

To get the browser-safe client token from your server-side code, make a POST call to the /v1/oauth2/token endpoint and include the following:

Encoded app credentials Client ID : Secret in Base64 format, in the Authorization header.
Data parameters:

Parameter	Action
`grant_type`	Set the parameter value to `client_credentials` to specify that the app is requesting to exchange client ID and secret for an access token.
`response_type`	Set the parameter value to `client_token` to request a client-side access token.

Response: Contains the browser-safe client token in the access_token response parameter.

// Get OAuth token using client credentials
async function getClientToken() {
  try {
    const response = await fetch("/your-server/api/paypal/browser-safe-client-token");
    const data = await response.json();

    if (!response.ok) {
      throw new Error(data.error || "Failed to fetch client token");
    }

    return data.access_token;
  } catch (error) {
    console.error("Client token error:", error);
    throw error;
  }
}

// Sample config object
const config = {
  clientID: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  apiBaseUrl: process.env.PAYPAL_API_BASE_URL
}
// Helper function to get OAuth token
async function getAuthToken(formBody) {
  const encodedClientCredentials = Buffer.from(
    `${config.clientID}:${config.clientSecret}`,
  ).toString("base64");

  const response = await fetch(`${config.apiBaseUrl}/v1/oauth2/token`, {
    body: formBody,
    headers: {
      Accept: "application/json",
      "Accept-Language": "en_US",
      Authorization: `Basic ${encodedClientCredentials}`,
      "Content-Type": "application/x-www-form-urlencoded",
    },
    method: "POST",
  });

  const data = await response.json();

  if (response.status !== 200 && response.status !== 201) {
    throw new Error(data.error_description || "Failed to generate OAuth token");
  }

  return data;
}

// Function to get browser-safe client token
function getBrowserSafeClientToken() {
  return getAuthToken(
    "grant_type=client_credentials&response_type=client_token"
  );
}

// Route handler for browser-safe client token endpoint
router.get(
  "/your-server/api/paypal/browser-safe-client-token",
  async (request, response, next) => {
    try {
      const clientTokenResponse = await getBrowserSafeClientToken();
      return response.send({
        access_token: clientTokenResponse.access_token,
      });
    } catch (error) {
      next(error);
    }
  },
);

curl -v -X POST 'https://api-m.sandbox.paypal.com/v1/oauth2/token' \
  -u 'CLIENT-ID:CLIENT-SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H 'Accept-Language: en_US' \
  -d 'grant_type=client_credentials' \
  -d 'response_type=client_token'

Initialize JavaScript SDK and create SDK instance

In your client-side code, use the window.paypal.createInstance() method with the following parameters to create a PayPal SDK instance:

Parameter	Action
`clientToken`	Pass the browser-safe client token.
`components`	Set to `["bank-ach-payments"]` to load and render ACH components.

Response: Contains an SDK instance object with the createBankAchSavePaymentSession() method for creating ACH payment sessions and the findEligibleMethods() method for checking payment method availability.

const clientToken = await getClientToken();

const sdkInstance = await window.paypal.createInstance({
  clientToken,
  components: ["bank-ach-payments"],
});
window.sdkInstance = sdkInstance;

Verify eligibility

In your client-side code, use the following methods to determine if you are eligible to offer ACH as a payment method:

findEligibleMethods(): Returns all the eligible payment methods.
isEligible(): Indicates if ACH is an eligible payment method.

Call findEligibleMethods() with an input options object containing the following parameters:

Parameter	Action
`currencyCode`	Set to the three-letter currency code. Example: `USD`.
`paymentFlow`	Set to `VAULT_WITHOUT_PAYMENT` to vault without an initial payment.

Response: Contains an object with the isEligible() method. Use the method to verify if the eligible payment methods include ACH.

// Check if ACH is available for vaulting without payment
const options = {
  currencyCode: "USD",
  paymentFlow: "VAULT_WITHOUT_PAYMENT"
};

// Query for available payment methods
const paymentMethods = await sdkInstance.findEligibleMethods(options);

// Check ACH eligibility
const isAchEligible = paymentMethods.isEligible("ach");

Render Pay with Bank button

After confirming eligibility, render the Pay with Bank - ACH button on your webpage:

Define the container for the ACH button: In the HTML file corresponding to the webpage where you want to render the button, include a container element.

<section class="payment-method-container" id="bank-ach-section">
  <h2>Pay with Bank</h2>
  <!-- BankAchButton web component launches the popup flow -->
  <bank-ach-button id="paypal-bank-ach-button" hidden></bank-ach-button>
</section>

Create vault setup token: Call createVaultSetupToken() to get the vault setup token. A vault setup token is a temporary token that is later exchanged for a payment method token.
Create payment session: Use sdkInstance.createBankAchSavePaymentSession() to create a payment session and register the onApprove(), onCancel(), onComplete(), and onError() event handlers.
Attach the onClick event handler and display the button: Use addEventListener() to attach the onClick event handler that triggers the onClick function when customers select the Pay with Bank - ACH button.

// isAchEligible returns true if ACH payments are eligible for your account.

if (isAchEligible) {
  // Step 2: Create vault setup token
  const { vaultSetupToken } = await createVaultSetupToken();

  // Step 3: Create payment session
  const bankAchSession = sdkInstance.createBankAchSavePaymentSession({
    onApprove,
    onCancel,
    onComplete,
    onError,
    vaultSetupToken,
  });

  // Step 4: Attach the onClick event handler and display the button
  const bankButton = document.querySelector("#paypal-bank-ach-button");
  bankButton.addEventListener("click", onClick);
  bankButton.removeAttribute("hidden");
} else {
  console.log("ACH is not eligible");
}

Define createVaultSetupToken function

The createVaultSetupToken() function creates a vault setup token for saving payment methods without an initial payment. In your client-side code, include the createVaultSetupToken() function that calls the server-side code to create a vault setup token. In your server-side code, include the code to make a POST call to the /v3/vault/setup-tokens endpoint:

Use a Bearer token with full-scope access token in the Authorization header.
Include the following parameters:

Parameter	Action
`payment_source.bank.ach_debit.billing_address.country_code`	Set to the two-letter country code. Example: `US`.
`payment_source.bank.ach_debit.experience_context.cancel_url`	Set to the URL where customers are redirected if they cancel. Example: `https://example.com/cancel`.
`payment_source.bank.ach_debit.experience_context.locale`	Set to the locale code. Example: `en-US`.
`payment_source.bank.ach_debit.experience_context.return_url`	Set to the URL where customers are redirected after completion. Example: `https://example.com/return`.
`payment_source.bank.ach_debit.verification.paypal.method`	Set to `INSTANT_ACCOUNT_VERIFICATION` for the verification method.

Response: Contains the vault setup token in the id response parameter.

async function createVaultSetupToken() {
  console.log("Creating vault setup token");

  const defaultHeaders = {
    "Content-Type": "application/json",
  };

  try {
    const response = await fetch(
      "/your-server/api/paypal/vault/setup-token",
      {
        headers: {
          ...defaultHeaders,
        },
        method: "POST",
      },
    );

    const data = await response.json();

    if (!response.ok) {
      throw new Error(data.message || "Failed to create setup token");
    }

    return data;
  } catch (error) {
    throw new Error(error);
  }
}

// Function to get full scope access token for vault operations
function getFullScopeAccessToken() {
  return getAuthToken(
    "grant_type=client_credentials&response_type=token"
  );
}

// Express route to create setup token for ACH
router.post(
  "/your-server/api/paypal/vault/setup-token",
  async (request, response, next) => {
    try {
      const { access_token: accessToken } = await getFullScopeAccessToken();

      const requestHeaders = {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json",
      };

      const apiResponse = await fetch(
        `${config.apiBaseUrl}/v3/vault/setup-tokens`,
        {
          body: JSON.stringify({
            payment_source: {
              bank: {
                ach_debit: {
                  billing_address: {
                    country_code: "US",
                  },
                  experience_context: {
                    cancel_url: "https://example.com/cancel",
                    locale: "en-US",
                    return_url: "https://example.com/return",
                  },
                  verification: {
                    paypal: {
                      method: "INSTANT_ACCOUNT_VERIFICATION",
                    },
                  },
                },
              },
            },
          }),
          headers: requestHeaders,
          method: "POST",
        },
      );

      const data = await apiResponse.json();

      if (apiResponse.ok) {
        return response.send({
          vaultSetupToken: data.id,
        });
      } else {
        return response.status(apiResponse.status).send(data);
      }
    } catch (error) {
      next(error);
    }
  },
);

curl -v -X POST 'https://api-m.sandbox.paypal.com/v3/vault/setup-tokens' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -d '{
    "payment_source": {
      "bank": {
        "ach_debit": {
          "billing_address": {
            "country_code": "US"
          },
          "experience_context": {
            "cancel_url": "https://example.com/cancel",
            "locale": "en-US",
            "return_url": "https://example.com/return"
          },
          "verification": {
            "paypal": {
              "method": "INSTANT_ACCOUNT_VERIFICATION"
            }
          }
        }
      }
    }
  }'

Define onClick event handler function

Create an onClick event-handler function that starts the authentication flow. In your client-side code, include an event-handler function that is triggered when the user clicks the Pay with Bank - ACH button and starts the authentication (account verification) flow.

async function onClick() {
  try {
    await bankAchSession.start({
      presentationMode: "popup",
    });
  } catch (error) {
    console.error("Error starting authentication flow:", error);
  }
}

Handle events

Event handlers manage the different outcomes when your customers attempt to save ACH payment methods. In your code, create event-handler functions that handle customer approval, payment cancellation, error scenarios, and completion.

a. Handle approval and create payment token

In your client-side code, include the onApprove() event-handler function that receives the vault setup token after the customer successfully verifies their bank account, calls the createPaymentToken() function, and passes the vault setup token.

async function onApprove(data) {
  try {
    console.log("Processing vault PaymentToken for ACH...");

    // Create payment token using the vault setup token
    const createPaymentTokenResponse = await createPaymentToken(
      data.vaultSetupToken,
    );

    console.log(
      "✅Payment Token created successfully: " + createPaymentTokenResponse.paymentToken,
    );

    console.log("Create payment token response: ", createPaymentTokenResponse);
  } catch (error) {
    console.error("❌Error creating payment token: " + error.message);
  }
}

In your server-side code, include the code to make a POST call to the /v3/vault/payment-tokens endpoint:

Use a valid full-scope Bearer access token and make a POST call to the /v3/vault/payment-tokens endpoint with the vault setup token received from client-side.
Receive the payment token details from the PayPal server and pass them to the client-side code.

async function createPaymentToken(setupToken) {
  console.log("Creating vault payment token");

  const defaultHeaders = {
    "Content-Type": "application/json",
  };

  try {
    const response = await fetch(
      "/your-server/api/paypal/vault/payment-token",
      {
        headers: {
          ...defaultHeaders,
        },
        method: "POST",
        body: JSON.stringify({ setupToken }),
      },
    );

    const data = await response.json();

    if (!response.ok) {
      throw new Error(data.message || "Failed to create payment token");
    }

    return data;
  } catch (error) {
    throw new Error(error);
  }
}

// Express route to create payment token for ACH
router.post(
  "/your-server/api/paypal/vault/payment-token",
  async (request, response, next) => {
    const setupToken = request.body.setupToken;

    try {
      const { access_token: accessToken } = await getFullScopeAccessToken();

      const requestHeaders = {
        Authorization: `Bearer ${accessToken}`,
        "Content-Type": "application/json",
      };

      const apiResponse = await fetch(
        `${config.apiBaseUrl}/v3/vault/payment-tokens`,
        {
          body: JSON.stringify({
            payment_source: {
              token: {
                id: setupToken,
                type: "SETUP_TOKEN",
              },
            },
          }),
          headers: requestHeaders,
          method: "POST",
        },
      );

      const data = await apiResponse.json();

      if (apiResponse.ok) {
        return response.send({
          paymentToken: data.id,
        });
      } else {
        return response.status(apiResponse.status).send(data);
      }
    } catch (error) {
      next(error);
    }
  },
);

curl -v -X POST 'https://api-m.sandbox.paypal.com/v3/vault/payment-tokens' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ACCESS-TOKEN' \
  -d '{
    "payment_source": {
      "token": {
        "id": "VAULT-SETUP-TOKEN",
        "type": "SETUP_TOKEN"
      }
    }
  }'

b. Handle cancellation

In your app code, include the onCancel() event-handler function that handles payment cancellation. Payment cancellation can occur when the customer cancels account verification or the saving process. JavaScript SDK passes the cancellation details to the function’s data parameter.

function onCancel(data) {
  console.log("ACH Save Cancelled!", data);
  console.log("Customer cancelled the bank account linking process");
}

c. Handle errors

In your app code, include the onError(data) event-handler function to process errors that occur during bank account verification or the saving process. JavaScript SDK passes error message and error details to the function’s data parameter.

function onError(data) {
  console.log("ACH Save Error:", data);
  console.error(`Error occurred during bank account linking: ${data.message || 'Unknown error'}`);
}

d. [Optional] Handle completion

In your app code, you can include the onComplete(data) event-handler function to perform necessary clean-up operations.

function onComplete(data) {
  console.log("ACH Save Complete:", data);
  console.log("Bank account authentication flow completed");
}

Test and go live

Test the end-to-end integration flow

Load your integration page and verify ACH eligibility checking works correctly.
Click the Pay with Bank button to start the bank account authentication process.
Verify the vault setup token is created successfully when the authentication flow begins as documented in the Define createVaultSetupToken function section.
Complete the authentication flow and verify the onApprove callback receives the vault setup token as documented in the Handle approval and create payment token section. When the bank selection popup appears, use the following sandbox test credentials:
- Bank selection: Select Demo Bank from the list of available banks.
- Username: pyplopenbankingubsb.site16441.2credential
- Password: site16441.2
Confirm your server successfully creates a payment method token using the vault setup token as documented in the Handle approval and create payment token section.
Verify the authentication flow starts correctly when clicking the button as documented in the Define onClick event handler function section.

Test error handling

Cancel the authentication process and verify the onCancel callback executes as documented in the Handle cancellation section.
Test error scenarios and verify the onError callback handles failures appropriately as documented in the Handle errors section.
Confirm the onComplete callback executes when the flow finishes as documented in the Handle completion section.

Go live

Switch from sandbox to production API endpoints:
- Change SDK URL from https://www.sandbox.paypal.com/web-sdk/v6/core to https://www.paypal.com/web-sdk/v6/core.
- Update API base URL from https://api-m.sandbox.paypal.com to https://api-m.paypal.com.
Replace sandbox credentials with production credentials:
- Use your production client ID and secret.
- Ensure your production PayPal business account is approved for Expanded Checkout and ACH payments.
Deploy and test your production integration to confirm everything works correctly.

Add ACH

Add Apple Pay

Save bank details for later use (JavaScript SDK integration)

Prerequisites

Load PayPal JavaScript SDK

Create browser-safe client token

Initialize JavaScript SDK and create SDK instance

Verify eligibility

Render Pay with Bank button

Define createVaultSetupToken function

Define onClick event handler function

Handle events

a. Handle approval and create payment token

b. Handle cancellation

c. Handle errors

d. [Optional] Handle completion

Test and go live

​Prerequisites

​Load PayPal JavaScript SDK

​Create browser-safe client token

​Initialize JavaScript SDK and create SDK instance

​Verify eligibility

​Render Pay with Bank button

​Define createVaultSetupToken function

​Define onClick event handler function

​Handle events

​a. Handle approval and create payment token

​b. Handle cancellation

​c. Handle errors

​d. [Optional] Handle completion

​Test and go live

Prerequisites

Load PayPal JavaScript SDK

Create browser-safe client token

Initialize JavaScript SDK and create SDK instance

Verify eligibility

Render Pay with Bank button

Define createVaultSetupToken function

Define onClick event handler function

Handle events

a. Handle approval and create payment token

b. Handle cancellation

c. Handle errors

d. [Optional] Handle completion

Test and go live