Event Handling
Subscribe to Field Events
This function is used to subscribe to events emitted by a Paysafe.js field or fields.
The function signature is as follows:
instance.fields(fieldname).on(events, function(instance, event) {
...
})
The function signature contains the following parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
events | true | string | An event name or a list of event names separated by spaces to which the listener applies:
This parameter is case insensitive. |
| fieldname | true | string | The field—or fields separated by spaces—producing events to which to subscribe:
This parameter is case insensitive |
| callback | true | function | Callback function invoked when an event occurs. |
| {return} | true | object | The fields handler from which the method was invoked. |
An example is shown below:
<html>
...
<body>
<div id="cardNumber" paysafe="card-number"></div>
<div id="cvv" paysafe="cvv"></div>
<div id="expiryDate" paysafe="expiry-date"></div>
<script>
let hostedFieldInstance;
paysafe.fields.setup("my Base64 encoded single-use-token API key", options)
.then(instance => {
hostedFieldInstance = instance;
return hostedFieldInstance.show();
}).then(paymentMethods => {
if (paymentMethods.card && !paymentMethods.card.error) {
hostedFieldInstance.fields("cvv cardNumber expiryDate").on("Focus Blur", function(instance, event) {
this.style.borderColor = event.type === "Focus" ? "green" : initialcolor;
});
}
}).catch(error => {
console.log(error);
});
</script>
</body>
</html>
Async Await Example
<html>
...
<body>
<div id="cardNumber" paysafe="card-number"></div>
<div id="cvv" paysafe="cvv"></div>
<div id="expiryDate" paysafe="expiry-date"></div>
<script>
initializeJs();
async function initializeJs() {
try {
const hostedFieldInstance = await paysafe.fields.setup("my Base64 encoded single-use-token API key", options);
const paymentMethods = await hostedFieldInstance.show();
if (paymentMethods.card && !paymentMethods.card.error) {
hostedFieldInstance.fields("cvv cardNumber expiryDate").on("Focus Blur", function (instance, event) {
this.style.borderColor = event.type === "Focus" ? "green" : initialcolor;
});
}
} catch (error) {
console.log(error);
}
}
</script>
</body>
</html>
The supported events are listed below:
| Event | Description |
|---|---|
Focus | A field has been selected and is ready to receive input. |
| Blur | A field has been deselected. |
| Valid | A field now contains a valid value. |
| Invalid | A field does not contain a valid value. |
| FieldValueChange | The customer has changed a field's value. |
| InvalidCharacter | The customer has attempted to input a character that is not accepted by this field (for example an alphabetic character) |
Alternative Method of Subscribing to Events
You can also subscribe to events using the alternative syntax shown in the function signature below:
instance.fields.<fieldname>.on(events, function(instance, event) {
...
})
Replace <fieldname> with a single value from the list below:
- cardNumber
- cvv
- expiryDate
- expiryMonth
- expiryYear
The names above are case-sensitive.
The rest of the function has the same as the standard syntax; for example:
<html>
...
<body>
<div id="cardNumber" paysafe="card-number"></div>
<div id="cvv" paysafe="cvv"></div>
<div id="expiryDate" paysafe="expiry-date"></div>
<script>
let hostedFieldInstance;
paysafe.fields.setup("my Base64 encoded single-use-token API key", options)
.then(instance => {
hostedFieldInstance = instance;
return hostedFieldInstance.show();
}).then(paymentMethods => {
if (paymentMethods.card && !paymentMethods.card.error) {
hostedFieldInstance.fields.cvv.on("Focus Blur", function(instance, event) {
this.style.borderColor = event.type === "Focus" ? "green" : initialcolor;
});
}
}).catch(error => {
console.log(error);
});
</script>
</body>
</html>
The rest of the function has the same as the standard syntax; for example:
<html>
...
<body>
<div id="cardNumber" paysafe="card-number"></div>
<div id="cvv" paysafe="cvv"></div>
<div id="expiryDate" paysafe="expiry-date"></div>
<script>
let hostedFieldInstance;
paysafe.fields.setup("my Base64 encoded single-use-token API key", options)
.then(instance => {
hostedFieldInstance = instance;
return hostedFieldInstance.show();
}).then(paymentMethods => {
if (paymentMethods.card && !paymentMethods.card.error) {
hostedFieldInstance.fields.cvv.on("Focus Blur", function(instance, event) {
this.style.borderColor = event.type === "Focus" ? "green" : initialcolor;
});
}
}).catch(error => {
console.log(error);
});
</script>
</body>
</html>
Async Await example
<html>
...
<body>
<div id="cardNumber" paysafe="card-number"></div>
<div id="cvv" paysafe="cvv"></div>
<div id="expiryDate" paysafe="expiry-date"></div>
<script>
initializeJs();
async function initializeJs() {
try {
const hostedFieldInstance = await paysafe.fields.setup("my Base64 encoded single-use-token API key", options);
const paymentMethods = await hostedFieldInstance.show();
if (paymentMethods.card && !paymentMethods.card.error) {
hostedFieldInstance.fields("cvv cardNumber expiryDate").on("Focus Blur", function (instance, event) {
this.style.borderColor = event.type === "Focus" ? "green" : 'red';
});
}
} catch (error) {
console.log(error);
}
}
</script>
</body>
</html>
Subscribe to Instance Events
This function is used to subscribe to events emitted by the Paysafe.js instance. It has the following signature:
instance.on(events, function(instance, event) {
...
})
The function signature contains the following parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
events | true | string | An event name—or a list of event names separated by spaces—to which the listener applies; either:
This parameter is case insensitive |
| callback | true | function | Callback function invoked when the event occurs. |
| {return} | true | object | The instance from which the method was invoked. |
An example is shown below:
<html>
...
<body>
<div id="cardNumber" paysafe="card-number"></div>
<div id="cvv" paysafe="cvv"></div>
<div id="expiryDate" paysafe="expiry-date"></div>
<script>
let hostedFieldInstance;
paysafe.fields.setup("my Base64 encoded single-use-token API key", options)
.then(instance => {
hostedFieldInstance = instance;
return hostedFieldInstance.show();
}).then(paymentMethods => {
if (paymentMethods.card && !paymentMethods.card.error) {
hostedFieldInstance.on("Submit", function(instance, event) {
document.getElementById("pay-button").disabled = instance.areAllFieldsValid();
});
}
}).catch(error => {
console.log(error);
});
</script>
</body>
</html>
Async Await Example
<html>
...
<body>
<div id="cardNumber" paysafe="card-number"></div>
<div id="cvv" paysafe="cvv"></div>
<div id="expiryDate" paysafe="expiry-date"></div>
<script>
initializeJs();
async function initializeJs() {
try {
const hostedFieldInstance = await paysafe.fields.setup("my Base64 encoded single-use-token API key", options);
const paymentMethods = await hostedFieldInstance.show();
if (paymentMethods.card && !paymentMethods.card.error) {
hostedFieldInstance.on("Submit", function(instance, event) {
document.getElementById("pay-button").disabled = instance.areAllFieldsValid();
});
}
} catch (error) {
console.log(error);
}
}
</script>
</body>
</html>
The supported instance events are listed below:
| Event | Description |
|---|---|
CardBrandRecognition | The card brand is recognized from the card number entered. |
| Submit | The customer pressed "Enter" while one of the fields is focused. |
| BadBin | The card brand is enabled for transaction salvage and there is a chance that the transaction will be declined |
| UnsupportedCardBrand | The card brand is not configured for the merchant's account |
Callback
The callback function has the following signature
function callback(instance, event) {
...
}
The function signature contains the following parameters:
| Parameter | Required | Type | Description |
|---|---|---|---|
instance | true | object | Paysafe.js instance in which the event occurred. |
| event | true | object | Information about the event. |
| event | |||
| type | true | string | Type/name of the event. |
| target | true | object | The Paysafe.js field element that caused the event. |
| data | true | object | Information about the field state. |
| target | |||
| fieldName | true | string | Field name of the Paysafe.js field element. |
| containerElement | true | HTMLElement | HTML container of the iframe. |
| data | |||
| isEmpty | true | boolean | true if the field value is empty. |
| cardBrand | true | string | Type of the card if recognized, or undefined if not Supported card types:
|
| declineRate | true | number | The chance of bank decline of this particular brand in percentage |
| salvageFlow | true | boolean | whether the salvage flow is above the configured threshold for the merchant |
| {return} | false | any | No specific behavior associated with the return value. |
| {context} | true | HTMLElement | The iframe container of the field in which the event occurred. |
List of errors thrown on registering for events:
| Code | Display Message | Detailed Message | Description |
|---|---|---|---|
9005 | There was an error (9005), please contact our support. | Events should be string. | The supplied events parameter is not a string. |
| 9008 | There was an error (9008), please contact our support. | Missing events configuration. | No events are specified, or events are an empty string or contain only spaces. |
| 9009 | There was an error (9009), please contact our support. | Event with name ${eventName} is not supported. | |
| 9102 | There was an error (9102), please contact our support. | Failed to perform a BIN lookup request. |