Praxis Wiki

Cashier API `JavaScript SDK`

OVERVIEW
Example
Cashier Events

Overview

The payment terminal page is a standalone web application that is either embedded inside an iframe or opened in a new tab.
It is not directly connected to the host page, which merely serves as the entry point for initiating the payment process.

This separation may cause the host page to reflect an outdated state during the customer's interaction with the terminal.

The JavaScript SDK provides a way for the host page to communicate with the terminal by sending and receiving notifications. These notifications help synchronize the current state or user actions made within the terminal session.

This communication includes:

Visual instructions, such as documentation adjustments to iframe terminal layout
Functional instructions, such as:
- Payment method selection
- Payment attempt status

Technically, the JavaScript SDK operates using the postMessage() for cross-domain messaging. Because of this, domain whitelisting is required and must be properly configured to ensure secure communication.

{danger.fa-exclamation} IMPORTANT:
The primary goal of the Cashier is to offer a seamless customer journey from the transaction initiation to the selected payment method through a web-based experience. Currently, native mobile and desktop SDKs are not available. To achieve integration within mobile apps, use an
in-app browser. This enables full compatibility with the Cashier and all available payment solutions.

Example

<!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>

Cashier Events

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.

Resize

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.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "resize",
    "height": 348,
    "cid": "2083",
    "order_id": "order_68877",
}

Payment Method Selected

This event will be triggered when the client selects a payment method in Cashier. The event context will contain the selected payment method.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "payment_method_selected",
    "payment_method": "Credit Card",
    "cid": "2083",
    "order_id": "order_68877",
}

Transaction Attempted

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.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "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",
}

Transaction Object

✓ - 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

Cashier Loaded

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.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "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",
}

Cashier Loading Failed

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.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "cashier_loading_failed",
    "amount": 200,
    "currency": "USD",
    "message": "Something went wrong.",
    "cid": "2083",
    "order_id": "order_68877",
}

Transaction Failed

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).

Event context parameters

✓ - required value
? - optional, value or null
✕ - always appears as null

Variable	Type		Description
event_type	varchar(100)	✓	Type of the triggered event - `transaction_failed`
cid	varchar(50)	✓	Unique customer id in your system. Note: Personally Identifiable Information (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or 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.
order_id	varchar(50)	✓	Transaction identifier in your system.

Possible values for message property:

Possible 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 context example:

{
    "event_type": "transcation_failed",
    "amount": 200,
    "currency": "USD",
    "message": "Token is invalid",
    "cid": "2083",
    "order_id": "order_68877",
}

Hosted Payment Fields Loaded

This event will be sent when the Credit Card method is selected, and the Hosted Payment Fields form is rendered.

Event context parameters

✓ - 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 context example:

{
    "event_type": "hosted_payment_fields_loaded",
    "cid": "2083",
    "order_id": "order_68877",
}

APM Fields Loaded

This event will be sent when the apm method is selected, and the APM Fields form is rendered.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "apm_fields_loaded",
    "fields": ["country","email"],
    "cid": "2083",
    "order_id": "order_68877",
}

HPF Form Valid

This event will be triggered when all required fields in the HPF form have been completed with valid values.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "hpf_form_valid",
    "cid": "2083",
    "order_id": "order_68877",
}

HPF Form Invalid

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.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "hpf_form_invalid",
    "cid": "2083",
    "order_id": "order_68877",
}

APM Form Valid

This event will be triggered when all required fields in the APM form have been completed with valid values.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "apm_form_valid",
    "cid": "2083",
    "order_id": "order_68877",
}

APM Form Invalid

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.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "apm_form_invalid",
    "cid": "2083",
    "order_id": "order_68877",
}

Validation Success

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.
Note: Actual value will not be available for credit card fields.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "validation_success",
    "field": "amount",
    "value": "1",
    "message": "Validation Success",
    "cid": "2083",
    "order_id": "order_68877",
}

Validation Failed

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.
Note: Actual value will not be available for credit card fields.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "validation_failed",
    "field": "amount",
    "value": "0",
    "message": "Minimum value is 1.",
    "cid": "2083",
    "order_id": "order_68877",
}

Cashier Submit

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.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "cashier_submit",
    "payment_method": "Credit Card",
    "currency": "USD",
    "amount": 200,
    "cid": "2083",
    "order_id": "order_68877",
}

Transaction

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.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "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"
}

Redirection

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.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "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",
}

Payment Methods Loaded

This event will be sent when the payment methods are succesfully loaded.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "payment_methods_loaded",
     "payment_methods": [
        "Credit Card",
        "Default APM",
        "skrill"
    ],
    "cid": "2083",
    "order_id": "order_68877",
}

Client Click

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.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "client_click",
    "element": "currency_field",
    "page": "payment-method",
    "cid": "2083",
    "order_id": "order_68877",
}

Possible values for element property:

Quick Deposit button (quick_deposit)
Amount field (amount_field)
Currency field (currency_field)
Credit Card field (credit_card_field)
Next button (next_button)
Back button (back_button)
CVV "?" icon (cvv_info_icon)
Deposit button (deposit_button)
Back to website button (back_to_website_button)
Try Again button (try_again_button)
Phone icon (phone_icon)
Chat icon (chat_icon)
Modal Close ('name of the modal'_modal_close)
Bdcc Modal (bdcc_modal)
Declaration of Deposit (dod)
Promocode Modal Save/Open Button(promocode_modal_save/close/open)
Missing Information Modal (missing_information_modal_continue)
Transactions Modal open/close(transactions-modal_open/close)
Terms of conditions Open/Close (termsOfConditions_open/close)
Billing Info Modal Open/Close/Save (billing_info_modal_open/close/save)
Retry Insufficient Funds Confirm/Cancel Button (confirm_button/cancel_button)
Retry Insufficient Funds Pre Defined Option (predefined_option)

Possible values for page property:

Payment method page (payment-details)
Credit Card page (card-details)
Final page (result)
Quick deposit (quick-deposit)
E-Wallet (apm-details)
Manual Bank Wire (manual-bank-wire-details)
Custom (custom-details)
Retry Page (retry-page)

Thank You Page Loaded

This event will be triggered when Thank you page is loaded.

Event context parameters

✓ - 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 (PII), such as email addresses, is strictly forbidden. If your user identifier contains any PII, you must hash or encrypt it before sending it to Praxis.
order_id	varchar(50)	✓	Transaction identifier in your system.

Event context example:

{
    "event_type": "thank_you_page_loaded",
    "cid": "2083",
    "order_id": "order_68877",
}

Overview

Processing

Direct API

HPF API

Cashier API

Agent API

Subscription API

Objects

Webhooks

Demo

Migration to API 1.3

Cashier API JavaScript SDK

Event context parameters

Event context parameters

Event context parameters

Transaction Object

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Event context parameters

Cashier API `JavaScript SDK`