JavaScript SDK

The Synapto JS SDK securely collects card details in the browser. It renders card inputs inside an iframe so raw card data never touches your servers.

For complete integration walkthroughs, see Taking Payments and Saving Cards.

Installation

Add the script tag to your page. Use the URL matching your environment:

<script src="https://js.synaptopay.com/synapto.js"></script>

Initialization

const syn = Synapto("pk_YOUR_PUBLISHABLE_KEY");

The constructor accepts an optional second argument for configuration:

const syn = Synapto("pk_YOUR_PUBLISHABLE_KEY", { theme: "dark" });

Find your publishable key in the Dashboard under Settings > Developer. See Authentication for details.

Theming

The SDK supports theming to match your site's look and feel. Pass a theme when initializing the SDK — it applies to all elements (payment element, card tokenization, and 3D Secure modals).

Built-in presets

Use "light" (default) or "dark":

const syn = Synapto("pk_YOUR_PUBLISHABLE_KEY", { theme: "dark" });

Custom colors

Pass an object with any combination of these properties to customize individual colors:

All properties are optional — omitted values fall back to the light theme defaults.

const syn = Synapto("pk_YOUR_PUBLISHABLE_KEY", {
  theme: {
    background: "#1a1a2e",
    foreground: "#eaeaea",
    buttonBackground: "#16c784",
    buttonForeground: "#ffffff",
    inputBackground: "#262641",
    inputForeground: "#eaeaea",
    inputBorder: "#3a3f5c",
    accent: "#16c784",
  },
});

Google Pay

The Google Pay button can be rendered with either a black or white background.

The SDK picks one from the theme you pass:

The default value can be overwritten with the walletButtonTheme.googlePay option, which accepts either "black" or "white".

const syn = Synapto("pk_YOUR_PUBLISHABLE_KEY", {
  theme: { background: "#101828", foreground: "#F8FAFC" },
  walletButtonTheme: {
    googlePay: "white", // "black" | "white"
  },
});

How it works

1. Your server creates a payment intent or setup intent via the API, receiving a client_secret
2. Your server passes the client_secret to the frontend
3. The frontend creates a payment element with the client_secret and mounts it to a DOM element — this renders a card input form in a secure iframe
4. When the customer submits, the frontend calls confirmPayment() or confirmSetup() — the SDK tokenizes the card data and sends it to Synapto
5. The SDK returns the result (success or error) to your frontend

The client_secret authorizes the customer to view and confirm the specific intent. Your API key is never exposed to the browser.

Payment element

syn.paymentElement(clientSecret, options?)

Creates a payment element bound to a payment intent or setup intent.

const paymentElement = syn.paymentElement("pi_..._secret_...");

The optional second argument configures the fields the element collects:

If you already collect the cardholder name as part of your own billing details, pass it through and hide the input so the customer doesn't type it twice:

const paymentElement = syn.paymentElement("pi_..._secret_...", {
  fields: { billingDetails: { name: "never" } },
  defaultValues: { billingDetails: { name: "Ada Lovelace" } },
});

If you don't know the name until checkout completes, supply it at confirmation instead:

const paymentElement = syn.paymentElement("pi_..._secret_...", {
  fields: { billingDetails: { name: "never" } },
});

await paymentElement.confirmPayment({
  paymentMethodData: { billingDetails: { name: "Ada Lovelace" } },
});

A name given at confirmation wins over defaultValues. The name is sent as part of the card's billing details either way.

If you suppress the input and then supply no name by either route, the element re-displays the input at confirmation and asks the customer for it, rather than taking a payment with no cardholder name.

name is currently the only billing detail these options cover — the element doesn't collect email, phone or address.

paymentElement.mount(selector)

Renders the card input form inside the specified DOM element.

paymentElement.mount("#payment-container");

paymentElement.confirmPayment(options?)

Confirms a payment intent — tokenizes the card data, sends it to Synapto, and processes the payment. Returns a promise.

const { paymentIntent, error } = await paymentElement.confirmPayment();

Returns:

paymentElement.confirmSetup(options?)

Confirms a setup intent — tokenizes the card data and saves it as a payment method. Returns a promise.

const { setupIntent, error } = await paymentElement.confirmSetup();

Returns:

paymentElement.awaitReady()

Waits until the payment element iframe is loaded and ready. Call this if you need to ensure the element is initialized before confirming.

await paymentElement.awaitReady();

3D Secure

Both confirmPayment() and confirmSetup() handle 3D Secure automatically. If the card issuer requires authentication, the SDK displays a challenge modal and resolves the promise once the customer completes it.

You can customize the 3D Secure behavior with an options object:

const { paymentIntent, error } = await paymentElement.confirmPayment({
  modalSelector: "#my-3ds-modal",
  onModal: (visible) => {
    console.log("3DS modal visible:", visible);
  },
});