Skip to main content

SDKs Overview

Cards are available on card rails

Card acceptance switches on when a card acquirer is enabled for your account — ask your account manager; no rail enabled today takes cards. Build on this page once they confirm one.

The card shape does not change when it does. The only card shape the API accepts is an opaque token minted by the processor's own PCI-compliant secure fields, and a raw card number is refused in every mode, sandbox included, with ERR_2029 — by design, no card number reaches TensorRail.

Meanwhile the rails you already have take payments through Payment links, Hosted checkout or the Direct API. Your dashboard shows the methods enabled on your account.

TensorRail ships three kinds of SDK. They do different jobs and run in different places. Pick by where the code runs and what you need it to do:

SDKRuns inPackage / URLUse it to…
TensorRail.js (browser payment SDK)Customer's browserhttps://js.tensorrail.com/v1/TensorRail.js (script tag)Render the payment methods enabled on your account in a TensorRail-hosted iframe, and confirm the payment from the browser. Where cards are enabled, the card data is tokenized inside that iframe and never touches your server.
@tensorrail/sdk (npm loader)Browser bundlers (React, Vue, Vite, webpack…)@tensorrail/sdk on npmLoad TensorRail.js from your own JS bundle instead of hand-writing a <script> tag. It's a thin loader around the same runtime.
Server SDKs (@tensorrail/node-sdk, tensorrail)Your backendnpm / PyPICreate/confirm payments, issue refunds, manage customers, and verify webhooks with your secret key.

Why the browser payment SDK exists​

TensorRail.js renders whichever payment methods are enabled on your account — the fields, the wallet buttons and the redirect handoffs all live in iframes served from the TensorRail CDN, so your page never has to implement a method itself.

Where cards are enabled, that boundary is also what keeps a raw card number (PAN) out of your systems: the PAN is captured inside TensorRail's own secure context and never reaches your frontend code, your backend, or your logs. You only ever handle an opaque token.

Loading the card-collecting runtime from the TensorRail CDN is not optional for card acceptance: it is the mechanism that keeps card entry inside TensorRail's context instead of your page's. Do not self-host or bundle the card-collecting runtime.

1. TensorRail.js: the browser payment SDK​

The CDN-served runtime that renders secure payment fields. It exposes window.TensorRail and is loaded from the CDN with a script tag:

<script src="https://js.tensorrail.com/v1/TensorRail.js"></script>

Test mode: pass a rail_open_test_ publishable key. The key selects test or live behaviour — there is no separate test script to load.

One bundle, one host: js.tensorrail.com/v1/TensorRail.js serves both modes, and the runtime's own assets and the payment iframe are fetched from js.tensorrail.com. A Content-Security-Policy needs to allow that one host.

// Initialize with your PUBLISHABLE key (rail_open_<mode>_)
const tensorrail = window.TensorRail("rail_open_test_xxx");

// Mount secure fields with the client_secret your server got from POST /payments
const elements = tensorrail.elements({ clientSecret: "<client_secret>" });
elements.create("payment").mount("#payment-form");

// Confirm: the card is tokenized in the iframe; no PAN leaves the browser
const result = await tensorrail.confirmPayment({
  elements,
  confirmParams: { return_url: "https://yoursite.com/complete" },
  redirect: "if_required",
});

Full method and element reference: SDK Reference.

2. @tensorrail/sdk: the npm loader​

Published on npm as @tensorrail/sdk. It is a thin loader: it injects the TensorRail.js script above (idempotently) and returns an initialized, typed SDK instance. Use it when you build your frontend with a bundler and would rather import than manage a <script> tag. It does not bundle the card runtime; the secure iframes still load from the TensorRail CDN, so the card number is captured inside TensorRail's context and never enters your bundle.

npm install @tensorrail/sdk
import { loadTensorRail } from "@tensorrail/sdk";

// The loader always injects js.tensorrail.com/v1/TensorRail.js — one bundle
// serves both modes, and the key's mode (rail_open_test_… / rail_open_live_…)
// is what selects test or live behaviour.
const tensorrail = await loadTensorRail("rail_open_test_xxx");

const elements = tensorrail.elements({ clientSecret: "<client_secret>" });
elements.create("payment").mount("#payment-form");

const result = await tensorrail.confirmPayment({
  elements,
  confirmParams: { return_url: "https://yoursite.com/complete" },
  redirect: "if_required",
});

loadTensorRail(publishableKey, options?) returns Promise<TensorRail>; the instance exposes the same methods as window.TensorRail — see the SDK Reference for the full list. Options: customBackendUrl, profileId (forwarded into the key object, which is where the runtime reads it), and scriptSrc (advanced).

Which one for the browser?

Both give you the identical SDK. Use @tensorrail/sdk in a bundled app (React/Vue/Vite/webpack); use the script tag for plain HTML or a quick prototype. You never need both.

3. Server SDKs: @tensorrail/node-sdk & tensorrail (Python)​

Typed, server-side clients that wrap the REST API with idempotency, retries, and typed errors. They use your secret key (rail_full_*) and never touch card data. This is where you create payments, confirm with a token, refund, and verify webhook signatures.

npm install @tensorrail/node-sdk   # Node.js 18+
pip install tensorrail             # Python 3.9+

Full install, quickstart, and webhook-verification examples: Server SDKs.

How they fit together in one payment​

How the two SDKs work together:

  1. Server SDK (@tensorrail/node-sdk / tensorrail) creates the payment with your secret key and gets back a client_secret.
  2. Your page passes the client_secret to TensorRail.js (loaded via the npm loader or the script tag).
  3. The customer pays in the TensorRail-hosted iframe; TensorRail.js confirms the payment. Where the method is a card, it is tokenized there and no PAN leaves the browser.
  4. Server SDK verifies the webhook that carries the authoritative result.

Prefer not to write any frontend payment code at all? Skip TensorRail.js and use the Hosted Checkout: you redirect to a checkout TensorRail hosts.

Next Steps​