Praxis Wiki logo

Cashier API JavaScript SDK


Overview

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.

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:

  1. EVENT_TYPE - a string that specifies the event to listen for. Available event types are listed below.
  2. 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 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 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 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 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 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 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 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 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 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 context example
{
    "event_type": "cashier_loading_failed",
    "amount": 200,
    "currency": "USD",
    "message": "Something went wrong.",
    "cid": "2083",
    "order_id": "order_68877",
}

Transcation 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 - 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
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 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 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 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 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 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 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 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 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 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 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. Please note the 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 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 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. Please note the 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 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 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 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 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 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 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 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 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 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 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 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 context example
{
    "event_type": "client_click",
    "element": "currency_field",
    "page": "payment-method",
    "cid": "2083",
    "order_id": "order_68877",
}
Possible values for element property
  1. Quick Deposit button (quick_deposit)
  2. Amount field (amount_field)
  3. Currency field (currency_field)
  4. Credit Card field (credit_card_field)
  5. Next button (next_button)
  6. Back button (back_button)
  7. CVV "?" icon (cvv_info_icon)
  8. Deposit button (deposit_button)
  9. Back to website button (back_to_webstite_button)
  10. Try Again button (try_again_button)
  11. Phone icon (phone_icon)
  12. Chat icon (chat_icon)
  13. Modal Close ('name of the modal'_modal_close)
  14. Bdcc Modal (bdcc_modal)
  15. Declaration of Deposit (dod)
  16. Promocode Modal Save/Open Button(promocode_modal_save/close/open)
  17. Missing Information Modal (missing_information_modal_continue)
  18. Transactions Modal open/close(transactions-modal_open/close)
  19. Terms of conditions Open/Close (termsOfConditions_open/close)
  20. Billing Info Modal Open/Close/Save (billing_info_modal_open/close/save)
  21. Retry Insufficient Funds Confirm/Cancel Button (confirm_button/cancel_button)
  22. Retry Insufficient Funds Pre Defined Option (predefined_option)
Possible values for page property
  1. Payment method page (payment-details)
  2. Credit Card page (card-details)
  3. Final page (result)
  4. Quick deposit (quick-deposit)
  5. E-Wallet (apm-details)
  6. Manual Bank Wire (manual-bank-wire-details)
  7. Custom (custom-details)
  8. 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 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 context example
{
    "event_type": "thank_you_page_loaded",
    "cid": "2083",
    "order_id": "order_68877",
}