Token Response | Finix.js Reference

Token Response

The response object passed to onSubmit callback or form.submit() method on successful tokenization. Access the token via response.data.

Tokens expire 30 minutes after creation and should be used immediately to create a Payment Instrument.

Card Token

Card token shape

On success, response.data contains:

{
  "id": "TKeD6uad8xZc52Rqg1VhvSBw",
  "created_at": "2025-06-10T00:31:53.54Z",
  "updated_at": "2025-06-10T00:31:53.54Z",
  "currency": "USD",
  "expires_at": "2025-06-11T00:31:53.54Z",
  "fingerprint": "FPRrcobjtdU98gr4sjiqYR1Qg",
  "instrument_type": "PAYMENT_CARD"
}

Field	Description
`id`	Token ID (prefixed `TK`) — use this to create a Payment Instrument
`currency`	`USD` for most countries; `CAD` for Canadian bank accounts
`expires_at`	Token expires 30 minutes after creation
`fingerprint`	Unique fingerprint for the payment instrument (prefixed `FP`)
`instrument_type`	`PAYMENT_CARD`, `BANK_ACCOUNT`, or `THIRD_PARTY_TOKEN`

Using the token

Pass tokenData.id to your backend, then use it to create a Payment Instrument via the Finix API.

Bank Account Token

Bank token shape

Bank account tokens have the same shape as card tokens, with instrument_type: "BANK_ACCOUNT".

Using the token

Pass tokenData.id to your backend, then use it to create a Payment Instrument via the Finix API.

Error Response

Error handling

When tokenization fails, error is non-null and response is null.

Parameter	Type	Description
`error`	`object`	Error details if submission failed
`response`	`null`	Always `null` when error is present

Example JavaScript Code

// Card token — accessed via response.data in the onSubmit callback:
const tokenData = response.data || {};
// tokenData shape:
// {
//   "id": "TKeD6uad8xZc52Rqg1VhvSBw",
//   "created_at": "2025-06-10T00:31:53.54Z",
//   "updated_at": "2025-06-10T00:31:53.54Z",
//   "currency": "USD",
//   "expires_at": "2025-06-11T00:31:53.54Z",
//   "fingerprint": "FPRrcobjtdU98gr4sjiqYR1Qg",
//   "instrument_type": "PAYMENT_CARD"
// }

Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
  onSubmit: function (error, response) {
    if (error) {
      console.error("Tokenization failed:", error);
      return;
    }

const tokenData = response.data || {};
    const token = tokenData.id; // e.g. "TKeD6uad8xZc52Rqg1VhvSBw"

// Send the token to your backend to create a Payment Instrument
    fetch("/your/backend", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ token: token }),
    });
  },
});

// Bank token — same shape, instrument_type differs:
const tokenData = response.data || {};
// tokenData shape:
// {
//   "id": "TKbFq4r8G5pN2mXvYhL9jW1c",
//   "created_at": "2025-06-10T00:31:53.54Z",
//   "updated_at": "2025-06-10T00:31:53.54Z",
//   "currency": "USD",
//   "expires_at": "2025-06-11T00:31:53.54Z",
//   "fingerprint": "FPaBC123def456ghi789",
//   "instrument_type": "BANK_ACCOUNT"
// }

const tokenData = response.data || {};
    const token = tokenData.id; // e.g. "TKbFq4r8G5pN2mXvYhL9jW1c"

Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
  onSubmit: function (error, response) {
    if (error) {
      console.error("Tokenization failed:", error);
      return;
    }
    // response is null when error is non-null
  },
});