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",
  },
});

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)

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

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

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);
  },
});