JavaScript SDK
The payment terminal page is a standalone web app that is placed either inside an iframe or in a new tab, so it’s not connected directly to the host page, which serves as the entry point for the payment process within the terminal. This is sometimes causing the inconvenience of the host page reflecting the outdated state during the payment process in the terminal
The JavaScript SDK is a way for the host page to communicate with the terminal in a form of notifications to reflect the
current state or the choices made by the customer while progressing through the payment process.
This communication includes the visual instructions, such as the document size change which is important for the iframe terminal layout,
as well as the functional instructions - payment method chosen, payment attempt status, etc.
On a technical level the JavaScript SDK operates using the postMessage()
cross-domain message sharing feature.
Which is why the SDK requires the domain whitelist to be enabled and properly configured to preserve the security for this communication.
{danger.fa-exclamation} Please note: The main objective for the Cashier is to assure the seamless customer journey from the transaction attempt to the payment method of customer's choice, which is commonly a web-based flow. With that, the cashier is web-based as well, at the moment the mobile and desktop SDKs are not offered for your integration. Instead, you can always use the in-app browser in order to use all the convenience of the integration between the cashier and all the available payment solutions.
<!DOCTYPE html>
<html>
<head>
<title>Cashier</title>
<!-- SANDBOX -->
<!-- <script src="https://cdn.cashier-test.com/sdk/js/praxis_cashier.v1_3.js"></script> -->
<!-- LIVE -->
<script src="https://cdn-gateway.praxispay.com/sdk/js/praxis_cashier.v1_3.js"></script>
</head>
<body>
<div id="cashier-block">
<!-- Cashier will be rendered here -->
</div>
<script>
const AUTH_TOKEN = '8a7sd87a8sd778ac961062c6bedddb8';
const CONTAINER = document.getElementById('cashier-block');
const AUTOCLOSE = false;
const MODE = 'iframe';
const LOCALE = 'en-GB';
let cashier = PraxisCashier({
auth_token: AUTH_TOKEN, // auth_token received in response to API call
container: CONTAINER, // block where the cashier iframe or cashier window controls will be added
autoclose: AUTOCLOSE, // whether to close the cashier window upon transaction attempt
mode: MODE, // supported values: 'iframe', 'tab', 'window'
locale: LOCALE // optional, locale for Praxis login button, browser locale is default
});
// if you override this method, please make sure to adjust the iframe size
cashier.on('resize', function(data) {
if (MODE === 'iframe') {
let iframe = cashier.getCashierIframe();
if (iframe) {
iframe.style.height = data.height + 'px';
}
}
});
cashier.on('payment_method_selected', function(data) {
console.log(data.payment_method);
});
// if set, this callback will override the autoclose setting
cashier.on('transaction_attempted', function(data) {
console.log(data.transaction.amount);
console.log(data.transaction.currency);
console.log(data.transaction.transaction_status);
});
cashier.render();
</script>
</body>
</html>
The Cashier Events function allows you to listen for specific events that occur within the Cashier SDK, and execute custom code when those events happen. To invoke the cashier events function, you must use the cashier.on
method with two parameters:
EVENT_TYPE
- a string that specifies the event to listen for. Available event types are listed below.function(data){}
- a callback function that executes when the specified event occurs. The data parameter is an object that contains information about the event. The specific properties of the data object depend on the event type.
cashier.on(EVENT_TYPE, function(data) {
console.log(data);
});
You can find more comprehensive information about the available event types in the sections below, along with examples of the payload that comes with each event. This payload contains relevant information about the event, which you can use to customize your payment integrations and create better user experiences.
This event will be triggered whenever there is a change in the height of the Cashier iframe. The event context will contain the window height size in pixels.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - resize |
height | int(4) | ✓ | Window height size in pixels |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "resize",
"height": 348,
"cid": "2083",
"order_id": "order_68877",
}
This event will be triggered when the client selects a payment method in Cashier. The event context will contain the selected payment method.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - payment_method_selected |
payment_method | varchar(50) | ✓ | Selected payment method by the client |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "payment_method_selected",
"payment_method": "Credit Card",
"cid": "2083",
"order_id": "order_68877",
}
This event will be triggered when our system is ready to send the payment details to the PSP right after a successful submit by the customer. The event context will contain the transaction attempt details.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - transaction_attempted |
transaction | <Object> | ✓ | Transaction object with attempted details |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "transaction_attempted",
"transaction": {
"amount": "20",
"card_number": "454101******6764",
"charge_amount": 20,
"charge_currency": "USD",
"currency": "USD",
"payment_method": "Credit Card",
"payment_processor": "Test Card Processor",
"trace_id": 1070412852,
},
"cid": "2083",
"order_id": "order_68877",
}
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
amount | decimal | ✓ | Transaction amount |
currency | varchar(10) | ✓ | Transaction currency |
charge_currency | varchar(10) | ✓ | Transaction currency selected for processing |
charge_amount | decimal | ✓ | Transaction amount selected for processing |
card_number | varchar(20) | ? | Masked card number |
payment_method | varchar(50) | ✓ | Payment method |
payment_processor | varchar(50) | ✓ | Payment processor |
trace_id | varchar(50) | ✓ | Transaction indentifier |
This event will be sent when the Cashier is loaded successfully. The event context will contain information about the available payment methods and the session information.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - cashier_loaded |
amount | decimal | ? | Predefined amount in Cashier |
currency | varchar(10) | ✓ | Transaction currency |
payment_methods | array | ✓ | List of available payment methods for selection in Cashier |
message | varchar(100) | ✓ | Results of the operation |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "cashier_loaded",
"amount": null,
"currency": "USD",
"payment_methods": [
"Credit Card",
"Default APM",
"skrill"
],
"message": "Cashier loaded successfully",
"cid": "2083",
"order_id": "order_68877",
}
This event will be sent when the Cashier is not loaded successfully for any reason. The event context will contain a description of the issue.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - cashier_loading_failed |
amount | decimal | ? | Predefined amount in Cashier |
currency | varchar(10) | ? | Transaction currency |
message | varchar(100) | ✓ | Results of the operation |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "cashier_loading_failed",
"amount": 200,
"currency": "USD",
"message": "Something went wrong.",
"cid": "2083",
"order_id": "order_68877",
}
This event will be sent when a transaction failure occurs. The event context will contain a description of the issue (invalid token, session expired, etc).
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - transcation_failed |
cid | varchar(50) | ? | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
amount | decimal | ? | Predefined amount in Cashier |
currency | varchar(10) | ? | Transaction currency |
order_id | varchar(50) | ? | Transaction identifier in your system |
message | varchar(100) | ✓ | Results of the operation |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
message
propertyPossible Messages |
---|
Payment method not available. Please contact your site administrator. |
Token is invalid |
Not available gateways found |
Not supported yet |
Apologies, it appears that you don't have any payment details registered to use for withdrawal request |
Unknown session |
Session expired |
Something went wrong. Please contact your system administrator (Code: 101) |
For the combination of card number, amount and currency there are no available payment gateways. Please try another credit card or select an alternative payment method. |
{
"event_type": "transcation_failed",
"amount": 200,
"currency": "USD",
"message": "Token is invalid",
"cid": "2083",
"order_id": "order_68877",
}
This event will be sent when the Credit Card method is selected, and the Hosted Payment Fields form is rendered.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - hosted_payment_fields_loaded |
{
"event_type": "hosted_payment_fields_loaded",
"cid": "2083",
"order_id": "order_68877",
}
This event will be sent when the apm method is selected, and the APM Fields form is rendered.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - apm_fields_loaded |
fields | array | ✓ | List with the name of the fields |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "apm_fields_loaded",
"fields": ["country","email"],
"cid": "2083",
"order_id": "order_68877",
}
This event will be triggered when all required fields in the HPF form have been completed with valid values.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - hpf_form_valid |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "hpf_form_valid",
"cid": "2083",
"order_id": "order_68877",
}
This event will be triggered when all required fields in the HPF form have been filled in, but at least one of them contains an invalid value.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - hpf_form_invalid |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "hpf_form_invalid",
"cid": "2083",
"order_id": "order_68877",
}
This event will be triggered when all required fields in the APM form have been completed with valid values.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - apm_form_valid |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "apm_form_valid",
"cid": "2083",
"order_id": "order_68877",
}
This event will be triggered when all required fields in the HPF form have been filled in, but at least one of them contains an invalid value.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - apm_form_invalid |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "apm_form_invalid",
"cid": "2083",
"order_id": "order_68877",
}
This event will be sent when the client entered the data in a valid format and the validation action was successful. The event context will contain the filed name and the value that was entered by the client. This event will be triggered after each observed delay in the input field. Please note the actual value will not be available for credit card fields.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - validation_failed |
field | varchar(100) | ✓ | The field filled by the client |
value | varchar | ? | The value that was entered by the client |
message | varchar(100) | ✓ | The result of the validation operation |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "validation_success",
"field": "amount",
"value": "1",
"message": "Validation Success",
"cid": "2083",
"order_id": "order_68877",
}
This event will be sent when the client entered data in an invalid format and the validation failed. The event context will contain the filed name, the value that was entered by the client, and the message that indicates the reason for failure. This event will be triggered after each observed delay in the input field. Please note the actual value will not be available for credit card fields.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - validation_failed |
field | varchar(100) | ✓ | The field filled by the client |
value | varchar | ? | The value that was entered by the client |
message | varchar(100) | ✓ | The result of the validation operation |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "validation_failed",
"field": "amount",
"value": "0",
"message": "Minimum value is 1.",
"cid": "2083",
"order_id": "order_68877",
}
This event will be sent when the client enters all the required data and clicks on the Deposit/Withdrawal button in Cashier. The event context will contain the selected payment method, amount and currency.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - cashier_submit |
payment_method | varchar(50) | ✓ | Selected payment method |
currency | varchar(10) | ✓ | Selected currency |
amount | decimal | ✓ | Attempted amount |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "cashier_submit",
"payment_method": "Credit Card",
"currency": "USD",
"amount": 200,
"cid": "2083",
"order_id": "order_68877",
}
This event will be sent when the transaction will be created. The event context will contain the transaction attempt details, including payment method, amount, currency and results of the transaction.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - transaction |
amount | decimal | ✓ | Attempted amount |
card_number | varchar(20) | ? | Masked card number (only for CC transactions) |
charge_amount | decimal | ✓ | Transaction amount selected for processing |
charge_currency | varchar(10) | ✓ | Transaction currency selected for processing |
currency | varchar(10) | ✓ | Attempted currency |
error_message | varchar(255) | ✓ | PSP error message (if have one) |
message | varchar(255) | ✓ | Message to be displayed for the client |
payment_method | varchar(50) | ✓ | Selected payment method |
payment_processor | varchar(50) | ✓ | Payment processor |
status | varchar(16) | ✓ | Transaction status will change along with the processing |
trace_id | int(11) | ✓ | Transaction identifier |
transaction_id | string(255) | ✓ | Transaction identifier from PSP |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "transaction",
"amount": "10",
"card_number": "411111******1111",
"charge_amount": 10,
"charge_currency": "USD",
"currency": "USD",
"error_message": null,
"message": "Transaction approved",
"payment_method": "Credit Card",
"payment_processor": "Test Card Processor",
"status": "approved",
"trace_id": 17780,
"transaction_id": "345518",
"cid": "1046",
"order_id": "order_20717"
}
This event will be sent when the client will be redirected to the 3DS/APM page. The event context will contain the transaction attempt details and the redirection details (URL) on 3DS/APM page.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | ||
---|---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - redirection |
|
payment_method | varchar(50) | ✓ | Selected payment method | |
currency | varchar(10) | ✓ | Selected currency | |
amount | decimal | ✓ | Attempted amount | |
transaction_status | varchar(16) | ✓ | Transaction status will change along with the processing | |
tid | int(11) | ✓ | Transaction identifier | |
redirect_url | varchar | ✓ | URL for the client redirection on 3DS/APM page | |
message | varchar(255) | ✓ | Message to be displayed for the client | \ |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
|
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "redirection",
"payment_method": "Credit Card",
"amount": 100,
"currency": "USD",
"transaction_status": "pending_async",
"tid": 1070407751,
"redirect_url": "https://gw.praxisgate.com/site/process/T005anFWVmNaSVJtK1pUZG5OTFlYZz09",
"message": "[TEST] Transaction status: pending_async. Reason: 3DS authentication required",
"cid": "2083",
"order_id": "order_68877",
}
This event will be sent when the payment methods are succesfully loaded.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - payment_methods_loaded |
payment_methods | array | ✓ | List of available payment methods for selection in Cashier |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "payment_methods_loaded",
"payment_methods": [
"Credit Card",
"Default APM",
"skrill"
],
"cid": "2083",
"order_id": "order_68877",
}
This event will be sent when the client clicks on some elements on the page. The event context will contain the element that was clicked and the page on which the click was made.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - client_click |
element | varchar(50) | ✓ | The element that was clicked |
page | varchar(10) | ✓ | The page on which the click was made |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "client_click",
"element": "currency_field",
"page": "payment-method",
"cid": "2083",
"order_id": "order_68877",
}
element
propertypage
propertyThis event will be triggered when Thank you page is loaded.
✓ - required value
? - optional, value or null
✕ - always appears as null
Variable | Type | Description | |
---|---|---|---|
event_type | varchar(100) | ✓ | Type of the triggered event - thank_you_page_loaded |
cid | varchar(50) | ✓ | Unique customer id in your system. Note: Personally Identifiable Information such as an e-mail address are strictly forbidden; if your user identifier contains such PII you must hash/encrypt it before sending it to Praxis. |
order_id | varchar(50) | ✓ | Transaction identifier in your system |
{
"event_type": "thank_you_page_loaded",
"cid": "2083",
"order_id": "order_68877",
}