processing-sdk

Use new Processing(options: ProcessingOptions) to create an instance of the Processing object. The Processing object is your entrypoint to the processing SDK.

interface ProcessingOptions {
  apiUrl: string;
  fingerprintVisitorId: string;
  sessionId: string;
  isSecure?: boolean; // default false
  retryOptions?: RetryOptions; // default {}
}

const processing = new Processing({
  apiUrl: 'api-url',
  fingerprintVisitorId: 'fingerprint-visitor-id',
  sessionId: 'session-id',
});

The constructor validates its options and throws a TypeError when they are not an object, when they contain an unknown key (for example a misspelled issecure), when apiUrl, fingerprintVisitorId or sessionId is missing, empty or not a string, when isSecure is not a boolean, or when retryOptions is malformed (see Retries and error diagnostics).

Retries and error diagnostics

Failed HTTP requests are retried automatically with exponential backoff (100ms → 200ms → 500ms → 1000ms → 2000ms; every retry after the fifth waits 2000ms). Retries can be configured via the optional retryOptions constructor option:

interface RetryOptions {
  retryCount?: number; // number of retries after the initial attempt, default 5; 0 disables retries
  retryStatusCode?: (statusCode: number) => boolean; // default: statusCode < 200 || statusCode === 408 || statusCode >= 500
}

const processing = new Processing({
  apiUrl: 'api-url',
  fingerprintVisitorId: 'fingerprint-visitor-id',
  sessionId: 'session-id',
  retryOptions: { retryCount: 3 },
});

To disable retries entirely, pass retryCount: 0 — every request is then sent exactly once, as in 0.11.0. Error diagnostics (RequestError, the console.error dump) are still collected:

const processing = new Processing({
  apiUrl: 'api-url',
  fingerprintVisitorId: 'fingerprint-visitor-id',
  sessionId: 'session-id',
  retryOptions: { retryCount: 0 },
});

The constructor throws a TypeError when retryOptions is not an object, retryCount is not a non-negative integer, or retryStatusCode is not a function.

Network errors (the browser could not reach the server at all, e.g. TypeError: Failed to fetch, or the connection dropped while the response body was being read) are always retried too.

Every retry attempt is reported with console.warn. When a request finally fails, the SDK logs console.error (sdk-js: request failed: <message>) with a full diagnostic dump and rejects with a RequestError whose diagnostics field carries the same payload — include it in your error reporting. diagnostics.kind tells the failure class apart:

• "network" — the browser never got a complete response (e.g. TypeError: Failed to fetch, or the body could not be read); diagnostics.error describes the thrown error, diagnostics.response.status is present when headers had arrived before the failure, message is request to <url> failed after N attempt(s): ...;
• "http_error" — an error response (non-200 status, or an error field in the body); message is the error text from the response body (or unexpected response status <code> when the body has none), diagnostics.response.status carries the HTTP status and diagnostics.response.error the error text from the body;
• "invalid_json" — the response body is not valid JSON; both diagnostics.error (the parse error; its message follows the same policy as the body — sanitized for non-200, omitted for 200 responses) and diagnostics.response are set.

Every diagnostics payload also includes:

• sdkVersion;
• request: url, method, x-request-id, session id, and per-attempt log attempts: [{ durationMs, status?, error? }] — attempt durations help tell an instant failure (DNS/connection refused) from a hang (timeout/handshake);
• response.body for non-200 responses — truncated to 500 chars with long digit runs masked (***); the body of a 200 response is never included since it may carry session credentials; the request body is never included anywhere;
• response.error — the error field of the response body, for any status (including a 200 response with an error field); it is a business error text, so it is neither truncated nor masked;
• environment: navigator.onLine, document.visibilityState, navigator.connection (effectiveType/rtt/downlink, Chromium only), timestamp.

Diagnostics are collected regardless of whether retries are enabled.

SDK identification header

Every request the SDK makes carries an extra header:

x-pgw-sdk: sdk-js/<version>

The value contains the SDK name and version (kept in sync with package.json by a test) — for example sdk-js/0.11.0. The backend uses this header to identify traffic coming from the official SDK integration — for example to notify affected merchants when a security fix is released. It does not affect authentication or request routing.

The header is added automatically to every request and cannot be disabled.

API

processing.getSession()

Use processing.getSession to get session information (payment methods, credential fields, operation amount and currency, init credentials) for rendering the form. It is optional: submitForm does not depend on it and can be called right after constructing the instance.

processing
  .getSession()
  .then(result => console.log(result))
  .catch(error => console.warn(error));

processing.submitForm(data)

Use processing.submitForm to submit transaction. When called, processing.submitForm will attempt to complete any required actions to process the transaction. This method returns promise which resolves with response ({ "type": "redirect", "redirectUrl": string}) or error that describes the failure.

processing
  .submitForm(data)
  .then(result => console.log(result))
  .catch(error => console.warn(error));

Usage

Submit only

The minimal flow is to construct the instance and call submitForm — no other request is needed before it. Use it when your own UI already knows what to collect from the customer (for example, the payment method and its credential fields are fixed on your side):

import { Processing } from "@finteqhub/sdk-js";
import FingerprintJS from "@fingerprintjs/fingerprintjs";

const fp = await FingerprintJS.load();
const result = await fp.get();

const processing = new Processing({ apiUrl, fingerprintVisitorId: result.visitorId, sessionId });

const data = {/** collect data from form **/}

processing
  .submitForm(data)
  .then(result => console.log(result))
  .catch(error => console.warn(error));

Render the form from session data

Call getSession first when the form itself is built from the session: available payment methods, their credential fields, the operation amount and currency. submitForm does not use the result — it only drives your UI:

const processing = new Processing({ apiUrl, fingerprintVisitorId: result.visitorId, sessionId });

const session = await processing.getSession();

const data = {/** collect data from form rendered from session **/}

processing
  .submitForm(data)
  .then(result => console.log(result))
  .catch(error => console.warn(error));

Releasing

On every version bump update both package.json version and SDK_VERSION in src/version.ts — they must stay in sync so the x-pgw-sdk header reports the right version. src/version.test.ts fails CI if they drift (node scripts/sync-version.js updates src/version.ts from package.json). Describe the release in CHANGELOG.md, including migration notes for breaking changes.

Beta releases

To try changes before bumping the version, run the publish-beta workflow (GitHub → Actions → publish-beta → Run workflow, pick your branch). It publishes <current version>-beta.<run number> to npm under the beta dist-tag — latest and the version in the repo stay untouched. Install it with:

npm i @finteqhub/sdk-js@beta

or pin the exact version printed in the workflow summary.