@open-border/js

The framework-agnostic, brand-themed Open Border checkout drop-in. Load one <script> and mount a branded card element into any storefront. The element collects the card in the browser and sends it directly to the payment processor (PCI SAQ A), returning a payment method token — it never charges and never holds a secret key.

New here? Start with the step-by-step Custom API setup guide, which covers mounting this element alongside the server-side charge and the CSP origins a storefront must allow. This README is the per-option reference.

Usage

<div id="ob-checkout"></div>
<script src="https://unpkg.com/@open-border/js"></script>
<script>
  OpenBorder('pk_test_OB_your_publishable_key').mount('#ob-checkout', {
    currency: 'USD',
    amount: 4200, // integer minor units — display only (labels the pay button)
    onSuccess: async ({ paymentMethodId }) => {
      // Send paymentMethodId to YOUR backend, which creates the charge with your
      // SECRET key: POST /v1/payment_intents { payment_method: paymentMethodId, ... }
      await fetch('/checkout/charge', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ paymentMethodId }),
      });
    },
    onError: (message) => console.error(message),
  });
</script>

API reference

• OpenBorder(publishableKey, clientOptions?) — creates a client bound to your publishable key.
  • publishableKey (string, required) — your pk_… key. It is public by design; it authenticates only a read-only config fetch and can never move money.
  • clientOptions.apiBaseUrl (string, optional) — override the Open Border API base URL. Defaults to the host matching the key's rail (see Sandbox & test mode below); override for local development.
• .mount(target, options) — renders the element and returns { unmount() }.
  • target (string or HTMLElement, required) — a CSS selector or the element itself; throws if the selector matches nothing.
  • options.currency (required) — one of 'USD' | 'GBP' | 'EUR' | 'CAD' | 'AUD'; the charge/product currency, which resolves the acquiring entity. Changing it re-fetches config and re-initialises the card fields (re-collect the card).
  • options.amount (number, optional) — order total in integer minor units. Display-only — it labels the pay button (e.g. "Pay $42.00"); omit for a plain label. The actual charge is created by your backend.
  • options.billingDetails (object, optional) — buyer identity attached to the payment method's billing details (AVS): { name?, email?, address? }, where address is { line1?, line2?, city?, state?, postal_code?, country? } (country is ISO 3166-1 alpha-2).
  • options.onSuccess (function, required) — called with { paymentMethodId, entity } on successful tokenization. Send paymentMethodId to YOUR backend as payment_method on POST /v1/payment_intents.
  • options.onError (function, optional) — called with a safe, human-readable message on failure.
  • options.submitLabel (string, optional) — overrides the pay button label (otherwise the merchant's branding label, then the formatted amount, then "Pay").
• unmount() (on the object returned by mount) — removes the element and releases its React root.
• Branding (logo, colors, font, radius, button label) is configured by the merchant in their Open Border dashboard and applied automatically.

Sandbox & test mode

A pk_test_… key hits the sandbox (https://api-sandbox.openborderpayments.com); a pk_live_… key hits production (https://api.openborderpayments.com). Pass apiBaseUrl to override either (e.g. local development). Use a pk_test_… key here — with your backend on the matching sk_test_… key — while integrating; test and live rails never mix.

Security model

The card is tokenized directly by the payment processor in the buyer's browser and never touches your servers. The resulting payment method is charged server-side by your own backend using your Open Border secret key (sk_…) — the embed only produces the token.