1. Include the SDK

Include the Cashier SDK script on your payment page's header section and be sure to use the correct URL for your environment.

https://cdn.cashier-test.com/sdk/js/praxis_cashier.v1_3.js (Sandbox environment)
https://cdn-gateway.praxispay.com/sdk/js/praxis_cashier.v1_3.js (LIVE environment)

📘
Custom Domain Implementations
If you are using a custom domain implementation for the Cashier, you must use your custom domain URL instead of praxispay.com when including the SDK script on your page.

📘
Domain Whitelisting Required
This Payment Page JavaScript SDK operates using postMessage() for cross-domain messaging. Because of this, domain whitelisting is required. You must ensure your domain is properly configured with Praxis to allow secure communication.

2. Initialize the SDK

Next, create an empty HTML element on your page. This will act as the container where the Cashier interface will be rendered.

Now initialize the PraxisCashier object. This step prepares the environment, handles authentication using your auth_token, and binds the Cashier to the HTML container you just created.

📘
Where do I get the auth_token ?
The auth_token is dynamically generated for each payment session. Your backend server must first initiate a Cashier Payment Request via the API. The Praxis response will contain the auth_token, which you must then pass to your frontend to initialize the SDK below.

Finally, after initializing the Cashier and setting up your event listeners, you must call the render() method to actually display the UI inside your designated HTML container.

Below is the example of the Payment Page SDK implementation.

<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>
    // Initialize the SDK
    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 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
    });


    // Invoking EVENTS Listener
    // 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);
    });

    // Render the Cashier UI
    cashier.render();
</script>
</body>
</html>

3. Invoke events listener

To activate the event listener, use the cashier.on() method. This method requires two arguments:

EVENT_TYPE: A string specifying which event you want to monitor (e.g., resize, close, etc.).
function(data){}: A callback function that executes when the specified event is triggered. The data parameter is an object containing relevant information about the event (the content of data varies based on the EVENT_TYPE).

Once your event listeners are defined, you must call the render() method to actually display the UI.

cashier.on(EVENT_TYPE, function(data) {
    // Custom code to execute when the event occurs
    console.log('Event triggered:', data); 
});

//Sample event format
cashier.on('payment_method_selected', function(data) {
      console.log(data.payment_method);
});

Events

The below are the list of available events in Cashier SDK.

These indicators are used in the parameters table to quickly identify the expected state of an attribute in the event context:

Symbol	Status	Description
✓	Required	The parameter must be present and contain a valid value.
?	Optional	The parameter may be sent with a valid value or explicitly set to `null`.
✕	Excluded	The parameter is reserved for internal processing or future use, and will always appear as `null`.

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"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 identifier in your system.
`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"
}

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"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 identifier in your system.
`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"
}

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"payment_method_selected"`.
`payment_method`	`varchar(50)`	✓	Selected payment method by the client.
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`order_id`	`varchar(50)`	✓	Transaction identifier in your system.

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

`payment_methods_loaded`

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"payment_methods_loaded"`.
`payment_methods`	`array`	✓	List of available payment methods for selection in Cashier.
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`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"
}

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"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 identifier in your system.
`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"
}

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"resize"`.
`height`	`int(4)`	✓	The required window height size in pixels (`px`).
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`order_id`	`varchar(50)`	✓	Transaction identifier in your system.

{
    "event_type": "resize",
    "height": 348,
    "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.

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"validation_success"`.
`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 identifier in your system.
`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"
}

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"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 identifier in your system.
`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"
}

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"cashier_submit"`.
`payment_method`	`varchar(50)`	✓	Selected payment method.
`currency`	`varchar(10)`	✓	Selected currency.
`amount`	`decimal`	✓	Attempted amount.
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`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"
}

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"transaction_attempted"`.
`transaction`	`<Object>`	✓	Transaction object with attempted details (see Schema below).
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`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"
}

`transaction`(success)

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.

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"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 one exists).
`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.
`trace_id`	`int(11)`	✓	Transaction identifier.
`transaction_id`	`string(255)`	✓	Transaction identifier from PSP.
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`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"
}

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"transaction_failed"`.
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`amount`	`decimal`	?	Predefined amount in Cashier.
`currency`	`varchar(10)`	?	Transaction currency.
`message`	`varchar(100)`	✓	Results of the operation.
`order_id`	`varchar(50)`	✓	Transaction identifier in your system.

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

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"redirection"`.
`payment_method`	`varchar(50)`	✓	Selected payment method.
`currency`	`varchar(10)`	✓	Selected currency.
`amount`	`decimal`	✓	Attempted amount.
`transaction_status`	`varchar(16)`	✓	Transaction status.
`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 identifier in your system.
`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.gate.com/site/process/T005anFWVmNaSVJtK1pUZG5OTFlYZz09](https://gw.gate.com/site/process/T005anFWVmNaSVJtK1pUZG5OTFlYZz09)",
    "message": "[TEST] Transaction status: pending_async. Reason: 3DS authentication required",
    "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.

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"hosted_payment_fields_loaded"`.
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`order_id`	`varchar(50)`	✓	Transaction identifier in your system.

{
    "event_type": "hosted_payment_fields_loaded",
    "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.

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"hpf_form_valid"`.
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`order_id`	`varchar(50)`	✓	Transaction identifier in your system.

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"hpf_form_invalid"`.
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`order_id`	`varchar(50)`	✓	Transaction identifier in your system.

{
    "event_type": "hpf_form_invalid",
    "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.

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"apm_fields_loaded"`.
`fields`	`array`	✓	List with the name of the fields.
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`order_id`	`varchar(50)`	✓	Transaction identifier in your system.

{
    "event_type": "apm_fields_loaded",
    "fields": ["country","email"],
    "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.

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"apm_form_valid"`.
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`order_id`	`varchar(50)`	✓	Transaction identifier in your system.

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"apm_form_invalid"`.
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`order_id`	`varchar(50)`	✓	Transaction identifier in your system.

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

`thank_you_page_loaded`

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

Variable	Type	Status	Description
`event_type`	`varchar(100)`	✓	Type of the triggered event. Always set to `"thank_you_page_loaded"`.
`cid`	`varchar(50)`	✓	Unique customer identifier in your system.
`order_id`	`varchar(50)`	✓	Transaction identifier in your system.

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

1. Include the SDK

Custom Domain Implementations

Domain Whitelisting Required

2. Initialize the SDK

Where do I get the auth_token ?

3. Invoke events listener

Events

cashier_loaded

cashier_loading_failed

payment_method_selected

payment_methods_loaded

client_click

resize

validation_success

validation_failed

cashier_submit

transaction_attempted

transaction(success)

transaction_failed

redirection

hosted_payment_fields_loaded

hpf_form_valid

hpf_form_invalid

apm_fields_loaded

apm_form_valid

apm_form_invalid

thank_you_page_loaded

`cashier_loaded`

`cashier_loading_failed`

`payment_method_selected`

`payment_methods_loaded`

`client_click`

`resize`

`validation_success`

`validation_failed`

`cashier_submit`

`transaction_attempted`

`transaction`(success)

`transaction_failed`

`redirection`

`hosted_payment_fields_loaded`

`hpf_form_valid`

`hpf_form_invalid`

`apm_fields_loaded`

`apm_form_valid`

`apm_form_invalid`

`thank_you_page_loaded`