> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://ixopay.ferndocs.com/developer-hub/documentation/reference/integration/hosted-fields-payment-js/method-reference/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://ixopay.ferndocs.com/_mcp/server.

# Method reference

Methods for initializing and using `PaymentJs`.

## Methods

### init

```js
PaymentJs.init(publicIntegrationKey, numberDivId, cvvDivId, completeCallback);
```

Initializes the `PaymentJs` object for PAN and CVV entry. Pass `null` for `cvvDivId` to collect only the card number (PAN-only mode, no CVV field).

#### Parameters

* `publicIntegrationKey` — the connector's public integration key (provided to you with your credentials).
* `numberDivId` — the `id` of the `<div>` which will contain the primary account number (PAN).
* `cvvDivId` — the `id` of the `<div>` which will contain the CVV code, or `null` for PAN-only mode.
* `completeCallback(PaymentJs)` — a callback function that will receive the initialized `PaymentJs` as first argument.

### initCvvRefresh

```js
PaymentJs.initCvvRefresh(publicIntegrationKey, referenceTransactionId, cvvDivId, completeCallback);
PaymentJs.initCvvRefresh(publicIntegrationKey, paymentToken, cvvDivId, completeCallback);
```

Initializes the `PaymentJs` object for [CVV refreshing](https://documentation.ixopay.com/docs/reference/integration/payment.js/advanced-guides/cvv-refreshing).

#### Parameters

* `publicIntegrationKey` (string): the connector's public integration key (provided to you with your credentials).

> **Info**
>
> The selected connector, identified by the `publicIntegrationKey`,
>
> * must use the same [customer profile container](https://documentation.ixopay.com/docs/reference/features/customer-profiles#customer-profile-containers) as the used `paymentToken`, or
> * must belong to the same merchant as the connector identified by the `referenceTransactionId`.

* Reference to a [register or debit with register transaction](https://documentation.ixopay.com/docs/reference/concepts/transactions/types) for which the CVV will be refreshed:
  * `referenceTransactionId` (string): the referenced transaction ID. - `paymentToken` (string): the [customer profile](https://documentation.ixopay.com/docs/reference/features/customer-profiles#creating-a-customer-profile) payment token.
* `cvvDivId` (string): the `id` of the `<div>` which will contain the CVV code.
* `completeCallback` (function: `(PaymentJs) => void`): a callback function that will receive the initialized `PaymentJs` as first argument.

### tokenize

```js
PaymentJs.tokenize(additionalData, successCallback, errorCallback);
```

Submit the sensitive card information to the vaulting server for [tokenization](https://documentation.ixopay.com/docs/guides/features/tokenization).

#### Parameters

* `additionalData` (object): an object, may contain the following keys: `first_name`, `last_name`, `month`, `year`, `email`, `phone_number`, `company`, `address1`, `zip`, `city`, `state`, `country`.
* `successCallback` (function: `(token, cardData) => void`): will be called upon completion, receiving the `token` (as string) as first argument, and additional `cardData` as second argument , for example:

```json
{
  "card_type": "visa",
  "full_name": "Alex Smith",
  "bin_digits": "41111111",
  "first_six_digits": "411111",
  "last_four_digits": "1111",
  "month": "9",
  "year": "2031",
  "fingerprint": "46f7adfeb0a123fb8fcbfasdf6171asd6b3dfas44834c"
}
```

Possible `cardType` values are: `amex`, `dinacard`, `diners`, `discover`, `elo`, `jcb`, `mada`, `maestro`, `mastercard`, `meeza`, `uatp`, `unionpay`, `visa_electron`, and `visa`.

> **Forward compatibility**
>
> Please note that the enumerated list provided above is subject to change or expansion over time. As such, be ready to accommodate and appropriately handle unfamiliar card brands.

* `errorCallback` (function: `(errors) => void`): called if an error occurs, containing error information. For more details see [Error codes](https://documentation.ixopay.com/docs/reference/integration/payment.js/error-codes).

### refreshCvv

```js
PaymentJs.refreshCvv(successCallback, errorCallback);
```

Submit the CVC/CVV code to the vaulting server.

#### Parameters

* `successCallback` (function: `() => void`): will be called upon successful completion.
* `errorCallback` (function: `(errors) => void`): called if an error occurs, containing error information. For more details see [Error codes](https://documentation.ixopay.com/docs/reference/integration/payment.js/error-codes).

### initRiskScript

```js
PaymentJs.initRiskScript(options, completeCallback);
```

Initialize [Risk Scripts](https://documentation.ixopay.com/docs/reference/features/risk-checks). Required for certain types of risk checks, see [External risk checks](https://documentation.ixopay.com/docs/reference/features/risk-checks) for more details.

#### Parameters

* `options` (object): An object including the type, e.g. `{ type: 'forter' }`. `type` can be `forter` or `riskified`.
* `completeCallback` (function `(...) => void`): will be called upon successful completion, parameters depend on `type` from `options`.

### setNumberStyle

```js
PaymentJs.setNumberStyle(styleObject);
```

Sets the style of the number field.

#### Parameters

* `styleObject` (object): an [object with CSS properties](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style), for example:

```json
{
  "border-color": "red",
  "font-size": "10px"
}
```

Additionally, it is possible to style the placeholder of the number field by providing a nested object with CSS properties in the field `::placeholder`, e.g.

```json
{
  "border-color": "red",
  "font-size": "10px",
  "::placeholder": {
    "color": "#a00"
  }
}
```

> **PCI compliance: no external resource loading**
>
> In order to comply with Payment Card Industry (PCI) security standards, we are unable to permit the loading of external resources such as typefaces or background images.

### setCvvStyle

```js
PaymentJs.setCvvStyle(styleObject);
```

Sets the style of the CVV field.

#### Parameters

* `styleObject` (object): an [object with CSS properties](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style), for example:

```json
{
  "border-color": "red",
  "font-size": "10px"
}
```

Additionally, it is possible to style the placeholder of the CVV field by providing a nested object with CSS properties in the field `::placeholder`, e.g.

```json
{
  "border-color": "red",
  "font-size": "10px",
  "::placeholder": {
    "color": "#a00"
  }
}
```

> **PCI compliance: no external resource loading**
>
> In order to comply with Payment Card Industry (PCI) security standards, we are unable to permit the loading of external resources such as typefaces or background images.

### setNumberPlaceholder

```js
PaymentJs.setNumberPlaceholder(placeholderText);
```

Sets the placeholder text for the number input field.

#### Parameters

* `placeholderText` (string): text for the placeholder of the number input field.

### setCvvPlaceholder

```js
PaymentJs.setCvvPlaceholder(placeholderText);
```

Sets the placeholder text for the CVV input field.

#### Parameters

* `placeholderText` (string): text for the placeholder of the CVV input field.

### setNumberInputType

```js
PaymentJs.setNumberInputType(inputType);
```

Sets the type attribute on the number input field.

#### Parameters

* `inputType` (string): type value (i.e. 'text', 'password').

### setCvvInputType

```js
PaymentJs.setCvvInputType(inputType);
```

Sets the type attribute on the CVV input field.

#### Parameters

* `inputType` (string): type value (i.e. 'text', 'password').

### setNumberAttribute

```js
PaymentJs.setNumberAttribute(attribute, value);
```

Sets an attribute on the number input field.

#### Parameters

* `attribute` (string): attribute to set (allowed: 'aria-describedby', 'aria-description', 'aria-disabled', 'aria-errormessage', 'aria-invalid', 'aria-label', 'aria-labelledby', 'aria-placeholder', 'aria-required').
* `value` (string): value of the attribute.

### setCvvAttribute

```js
PaymentJs.setCvvAttribute(attribute, value);
```

Sets an attribute on the CVV input field.

#### Parameters

* `attribute` (string): attribute to set (allowed: 'aria-describedby', 'aria-description', 'aria-disabled', 'aria-errormessage', 'aria-invalid', 'aria-label', 'aria-labelledby', 'aria-placeholder', 'aria-required').
* `value` (string): value of the attribute.

### numberOn

```js
PaymentJs.numberOn(event, callbackFunction, { getBinData: boolean });
```

Attach an event listener for the number input field.

For more details see [Event listening](https://documentation.ixopay.com/docs/reference/integration/payment.js/event-listening).

If `getBinData` is set to `true`, the result will be asynchronous (adding a backend call) and the BIN data will be attached as the `binData` key to the response data.

```text
{
  "binData": {
    "cardBrand": "VISA",
    "fundingSource": "CREDIT",
    "issuer": "VISA Bank 1",
    "normalizedCardBrand": "visa",
    "subBrand": null
  },
  ...
}
```

`cardBrand` is the brand as reported by the BIN data source. `normalizedCardBrand` is the same brand normalized to the card type identifiers also used by `cardType` (see the list below), or `null` if the brand cannot be resolved to one of them. `binData` is `null` while fewer than six digits have been entered or when no BIN data is found.

#### Parameters

* `event` (string): the number input event to attach the `callbackFunction` to. One of `input`, `focus`, `blur`, `mouseover`, `mouseout`, `enter`, `esc`, `tab`, or `shift-tab`.
* `callbackFunction` (function: `(event) => void`): a callback that receives data about the `event`, for example:

```json
{
  "cardType": "visa",
  "cvvLength": 3,
  "numberLength": 12,
  "validCvv": true,
  "validNumber": true
}
```

Possible `cardType` values are: `amex`, `dinacard`, `diners`, `discover`, `elo`, `jcb`, `mada`, `maestro`, `mastercard`, `meeza`, `uatp`, `unionpay`, `visa_electron`, and `visa`.

> **Forward compatibility**
>
> Please note that the enumerated list provided above is subject to change or expansion over time. As such, be ready to accommodate and appropriately handle unfamiliar card brands.

### cvvOn

```js
PaymentJs.cvvOn(event, callbackFunction);
```

Attach an event listener for the CVV input field.

For more details see [Event listening](https://documentation.ixopay.com/docs/reference/integration/payment.js/event-listening).

#### Parameters

* `event` (string): the CVV input event to attach the `callbackFunction` to. One of `input`, `focus`, `blur`, `mouseover`, `mouseout`, `enter`, `esc`, `tab`, or `shift-tab`.
* `callbackFunction` (function: `(event) => void`): a callback that receives data about the `event`, for example:

```json
{
  "cardType": "visa",
  "cvvLength": 3,
  "numberLength": 12,
  "validCvv": true,
  "validNumber": true
}
```

Possible `cardType` values are: `amex`, `dinacard`, `diners`, `discover`, `elo`, `jcb`, `mada`, `maestro`, `mastercard`, `meeza`, `uatp`, `unionpay`, `visa_electron`, and `visa`.

> **Forward compatibility**
>
> Please note that the enumerated list provided above is subject to change or expansion over time. As such, be ready to accommodate and appropriately handle unfamiliar card brands.

### setRequireCardHolder

```js
PaymentJs.setRequireCardHolder(requireCardHolder);
```

Disable the requirement of passing a card-holder name in the `additionalData` object of the tokenize method.

#### Parameters

* `requireCardHolder` (boolean): a boolean whether a card-holder name is required when calling tokenize.

### enableAutofill

```js
PaymentJs.enableAutofill();
```

Enables autofill handling.

For details see [Auto-fill card data](https://documentation.ixopay.com/docs/reference/integration/payment.js/advanced-guides/auto-fill-card-data).

### onAutofill

```js
PaymentJs.onAutofill(autofillCallback);
```

Registers an event handler to receive auto filled data.

For details, see [Auto-fill card data](https://documentation.ixopay.com/docs/reference/integration/payment.js/advanced-guides/auto-fill-card-data).

#### Parameters

* `autofillCallback` (function: `(data) => void`): a callback that is called when card-data autofill is triggered and receives `data` about the event, for example:

```json
{
  card_holder: "Alex Smith",
  month: 09,
  year:  2031,
}
```

## Deprecated methods

### onNumberInput

```js
PaymentJs.onNumberInput(callbackFunction);
```

This function is deprecated in favor of `numberOn('input', callbackFunction)`.

### onCvvInput

```js
PaymentJs.onCvvInput(callbackFunction);
```

This function is deprecated in favor of `cvvOn('input', callbackFunction)`.