SDK API Reference
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.
The SDK bundle is served from the CDN. Load it with a script tag:
<script src="https://js.tensorrail.com/v1/TensorRail.js"></script>
Or, in a bundled app, install the published npm loader
@tensorrail/sdk and call
loadTensorRail(publishableKey): it injects the same script and returns the
initialized instance. See the SDK Overview for the full
model.
This page documents the public surface of the TensorRail.js SDK.
TensorRail(publishableKey, options?)
Initialize the SDK. The factory is exposed as window.TensorRail.
const tensorrail = window.TensorRail(publishableKey, options);
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
publishableKey | string | object | Yes | Publishable key string, or { publishableKey, profileId? }. |
options | object | No | Loader and endpoint options. |
Init options
| Option | Type | Default | Description |
|---|---|---|---|
customBackendUrl | string | - | API base URL; forwarded to the loader (e.g. sandbox API). |
customSdkUrl | string | - | Override URL for SDK assets (app.js / app.css host). |
isPreloadEnabled | boolean | true | Prefetch SDK scripts, styles, and related assets. |
isTestMode | boolean | false | Non-transactional simulation; confirm calls are bypassed. |
isForceInit | boolean | false | Force re-initialization even if the SDK is already loaded. |
shouldUseTopRedirection | boolean | false | Legacy redirection flag; prefer redirectionFlags. |
redirectionFlags | object | - | { shouldUseTopRedirection?, shouldRemoveBeforeUnloadEvents? }. |
analytics | object | - | { metadata?: ... } merged into analytics. |
Instance methods
| Method | Signature | Description |
|---|---|---|
elements | (options) → Elements | Build payment Elements (iframes) for the given clientSecret. (The bundle also accepts an sdkAuthorization, but that value is engine-internal and is stripped from every merchant response, so clientSecret is the one you have.) |
widgets | (options) → Elements | Alias of elements. |
paymentMethodsManagementElements | (options) → Elements | Elements for saved payment methods (pmClientSecret, pmSessionId, etc.). |
confirmPayment | (payload) → Promise<JSON> | Submit payment; posts doSubmit to iframes and resolves with JSON from the iframe. |
confirmTokenization | (payload) → Promise<JSON> | Alias of confirmPayment. |
confirmOneClickPayment | (payload, result: boolean) → Promise<JSON> | One-click / wallet confirm path. |
confirmCardPayment | (clientSecret, data?, options?) → Promise<JSON> | Direct card confirm; uses return_url from data when redirecting. |
retrievePaymentIntent | (clientSecret) → Promise<JSON> | GET payment intent by client secret. |
paymentRequest | (options) → PaymentRequest | Browser Payment Request API wrapper (Apple Pay method data, totals, etc.). |
initPaymentSession | (options) → session | Payment session flow; returned object includes getCustomerSavedPaymentMethods. |
initAuthenticationSession | (options) → session | Authentication session (e.g. Click to Pay helpers on the session object). |
completeUpdateIntent | (clientSecret) → Promise<JSON> | Refresh session data and notify iframes. |
initiateUpdateIntent | () → Promise<JSON> | Signal iframes to start an update flow. |
elements(options)
Returns an Elements handle: create, getElement, update, fetchUpdates.
const elements = tensorrail.elements({
clientSecret: "<client_secret>",
appearance: { theme: "default", variables: { /* ... */ }, rules: {} },
locale: "auto",
loader: "auto",
fonts: [],
});
Common options
| Option | Type | Required | Description |
|---|---|---|---|
clientSecret | string | Yes* | Client secret from payment creation. |
sdkAuthorization | string | Yes* | Alternative token that embeds client secret / context (either this or clientSecret is used). |
appearance | object | No | Theme, variables, rules, labels; see Theming. |
locale | string | No | Default "auto" (uses navigator.language). |
fonts | array | No | Font descriptors (e.g. { cssSrc }) passed into the iframe. |
loader | string | No | "auto" | "always" | "never"; controls loading indicators. |
preloadSDKWithParams | object | No | Advanced preload payload for the embedded app. |
Elements methods
| Method | Signature | Description |
|---|---|---|
create | (type: string, options: object) → PaymentElement | Create a component of one of the element types below. |
getElement | (name: string) → PaymentElement | null | Retrieve an element already created for name. |
update | (options: object) → void | Push clientSecret, sdkAuthorization, locale, or appearance to iframes (ElementsUpdate). |
fetchUpdates | () → Promise<JSON> | Reserved / stub; returns a Promise (currently short delayed resolve in loader). |
Element types
The first argument to create(type, options). Anything else logs
Unknown Key: <type> type in create and creates nothing:
| Type | Renders |
|---|---|
payment | The unified payment element — every method enabled on your account. |
card | Single combined card field. |
cardNumber / cardExpiry / cardCvc | The card field split into three. |
paymentMethodCollect | Collect-a-method flow. |
paymentMethodsManagement | Manage a customer's saved methods. |
expressCheckout | Express/wallet button row. |
googlePay / applePay / payPal / samsungPay / paze / klarna | Individual wallet or BNPL buttons. |
Which of these actually render is decided by what is enabled on your account; an element for a method you are not enabled for renders nothing.
PaymentElement
| Method | Description |
|---|---|
mount(selector) | Mount into an id selector string, e.g. "#payment-form". The runtime keys the iframe it creates off that id, so a class or tag selector is not supported. |
unmount() | Remove from DOM; state may be preserved. |
destroy() | Tear down the element. |
on(event, handler?) | Subscribe to events; pass null/undefined handler to remove (see Events). |
focus() / blur() / clear() / collapse() | Focus and UI helpers. |
update(options) | Element-level option updates. |
onSDKHandleClick(handler?) | Optional async handler when the SDK drives confirm from a button. |
confirmPayment(payload)
const result = await tensorrail.confirmPayment({
elements,
confirmParams: {
return_url: "https://yoursite.com/payment/complete",
},
redirect: "if_required", // or "always"
});
| Field | Type | Description |
|---|---|---|
elements | object | The Elements instance (serialized as JSON for the loader). |
confirmParams | object | Must include return_url for redirect after 3DS / success when applicable. |
redirect | string | "if_required" (default) or "always"; controls when return_url is applied. |
Resolution depends on iframe submitSuccessful and redirect rules; on success the loader may resolve with payment data or trigger navigation to return_url.
Security
The SDK requires a secure (HTTPS) context (window.isSecureContext).
Initialize the SDK with a publishable key (prefix rail_open_<mode>_, e.g. rail_open_test_…). Keep your secret keys server-side and never expose them in client code. See the SDK Overview.