The response object passed to onSubmit callback or form.submit() method on successful tokenization. Access the token via response.data. When the ThreeDSecure option is set, the response carries a second key, threeDSecure.
Tokens expire 30 minutes after creation and should be used immediately to create a Payment Instrument.
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 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.
When the ThreeDSecure option is set on the form, response.threeDSecure holds the authentication result alongside the token.
threeDSecure.session.state still reads PENDING when status is succeeded. The API state only advances once Finix processes the authentication result from the vendor, which happens after your onSubmit runs. Decide whether to charge from threeDSecure.status, then submit the payment referencing threeDSecure.session.id.
threeDSecure shape
{
"data": {
"id": "TKnWxGqNKGkyhkEGkPfCrxLC",
"instrument_type": "PAYMENT_CARD"
},
"threeDSecure": {
"session": {
"id": "3d_secure_session_f3fG3Zj8K958MTP5vpXAXX",
"amount": 1000,
"currency": "USD",
"merchant_id": "MUmUNeW5N9Yw8RkLhLcGghy4",
"state": "PENDING"
},
"status": "succeeded"
}
}| Field | Description |
|---|---|
session | The full 3D Secure Session your backend created. null when createSession fails or returns an unusable session |
status | initialized, succeeded, or failed |
error | Present only when status is failed. Holds a code and a human-readable reason |
Finix.js uses camelCase for its own keys, but the session comes straight from the Finix API and keeps its snake_case field names.
For every status, every error code, and the full session object, see Finix.ThreeDSecure.
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 |
// 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"
// }
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. "TKbFq4r8G5pN2mXvYhL9jW1c"
// 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 }),
});
},
});
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
},
});
Finix.PaymentForm("payment-form", "sandbox", "APgPDQrLD52TYvqazjHJJchM", {
ThreeDSecure: {
createSession: async (token) => createSessionOnYourBackend(token),
},
onSubmit: function (error, response) {
if (error) {
console.error("Tokenization failed:", error);
return;
}
const tokenData = response.data || {};
const threeDSecure = response.threeDSecure || {};
// threeDSecure.session.state still reads "PENDING" here, even on success.
// Branch on threeDSecure.status instead.
if (threeDSecure.status === "succeeded") {
fetch("/your/backend", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
token: tokenData.id,
threeDSecureSessionId: threeDSecure.session.id,
}),
});
}
},
});