SecureFieldsClient

The client returned by initSecureFields.

Methods

on()

on<K>(event, callback): void;

Registers an event listener for the specified event.

Type Parameters

Type Parameter
K extends SecureFieldsEvents

Parameters

Parameter	Type
event	K
callback	(data) => void

Returns

void

Properties

destroy

destroy: () => void;

Destroys the SDK instance and removes all event listeners. This is terminal; the instance cannot be used after this call.

Returns

void

---

getCardInfo

getCardInfo: () => Promise<CardInfo | null>;

Gets card information such as BIN, detected brands, and last four digits.

Returns

Promise<CardInfo | null>

Card info or Null if the form is not complete enough.

Example

const info = await hostedFields.getCardInfo();
if (info) {
  console.log(info.bin);
  console.log(info.detected_brands);
  console.log(info.last_four_digit);
}

---

render

render: () => void;

Renders the fields in the targets specified in the config.

Returns

void

Throws

SecureFieldsErrors.FIELD_RENDER_FAILED If the target element for the field is not found.

Throws

SecureFieldsErrors.INSTANCE_DESTROYED If the instance has been destroyed.

See

SecureFieldsErrors

---

setSelectedBrand

setSelectedBrand: (brand) => void;

Tells the card fields which brand was chosen for a co-badged card.

Without this, the fields keep formatting against the brand the BIN lookup ranked first: the digit grouping of the card number and the accepted CVV length follow the detected brand rather than the chosen one. Call it as soon as the choice is made, not at submit.

When to call it:

• Hosted fields — whenever you run your own brand <select>. Not needed if you let the SDK render the in-field selector.
• Hosted form, hidden mode — the only way in; there is no selector on screen.
• Hosted form, explicit mode — done for you by the rendered <select>.

The chosen brand is also the one tokenized by SecureFieldsClient.submit, so passing selectedNetwork there as well is no longer required. A brand the BIN lookup did not match is ignored.

Parameters

Parameter	Type	Description
brand	Brand	The chosen brand, e.g. 'CARTE_BANCAIRE'.

Returns

void

Throws

SecureFieldsErrors.FIELDS_NOT_RENDERED If the fields have not been rendered yet.

Throws

SecureFieldsErrors.INSTANCE_DESTROYED If the instance has been destroyed.

Example

secureFields.on('brandDetected', ({ brands }) => renderMyBrandChoices(brands));
myBrandSelect.addEventListener('change', (e) => {
  secureFields.setSelectedBrand(e.target.value);
});

See

SecureFieldsErrors

---

submit

submit: (payload?) => Promise<SecureFieldsSubmitResult>;

Triggers validation and tokenization of the form.

Parameters

Parameter	Type	Description
payload?	SubmitOptions	SubmitOptions- This param is not passed when tokenizing a cvv, otherwise this payload contains the expiry month, expiry year, cardholder name, and selected network.

Returns

Promise<SecureFieldsSubmitResult>

Throws

SecureFieldsErrors.TOKENIZATION_FAILED If the form is invalid or if there is an error during the process.

Throws

SecureFieldsErrors.INVALID_FORM If the form is not valid.

Example

 const result = await hostedFields.submit({
     expiryMonth: 12;
     expiryYear: 25;
     cardHolderName: 'Joe Dawn';
     selectedNetwork: 'VISA';
     saveToken: false;
  });

  /**
  * result example
  * {
  *    vault_form_token: 'tok_xxx',
  *     card: {
  *       detected_brands: ['VISA'],
  *       bin: '41111111',
  *       last_four_digits: '1111',
  *     }
  *   }

With threeDS: { enabled: true } in the init config, the same call also runs the 3DS sequence after tokenization — versioning, then the 3DS Method in a hidden iframe when the card range has one — and the result carries the three_ds_server_trans_id your backend needs for the payment creation call, alongside the browser information you collect with getBrowserData(). The sequence is best-effort and never blocks the submit: a failed versioning call returns the token without three_ds_server_trans_id.

See

SecureFieldsErrors

Events

success Emitted when the form is successfully tokenized.

error Emitted when there is an error during the tokenization process.