JavaScript SDK JavaScript SDK

• SDK Parameters and Customization
• Example

SDK Parameters and Customization

General

1. PAYLOAD_SRC - URL to the JavaScript SDK.

   Name	URL
   Sandbox	https://cdn-pci.cashier-test.com/PraxisGate.js
   Live	https://cdn.praxisgate.com/PraxisGate.js

2. SESSION_TOKEN - session token returned from the open-hpf-session S2S call.

3. containers - A property to specify the containers used by the SDK for each field. The CVV container can be omitted if the CVV field is not required.

UI customization (CSS and Labels)

Use the options below to style the user interface and customize labels:

{danger.fa-exclamation-triangle} IMPORTANT: By default, the SDK retrieves its CSS from the HPF configuration in the Praxis Backoffice (Atlas). This CSS can be customized and persisted there. Praxis recommends overriding this via the SDK only if you need to apply session-specific changes.

1. css – Property to initialize custom CSS directly within the SDK configuration object.

2. sendCSS – Function to dynamically modify the CSS after the SDK object has been initialized.

3. labels – Property to define custom labels and/or placeholders.
   If window.PG_INPUT_SHOW_LABELS is passed, custom labels will be shown.
   If window.PG_INPUT_SHOW_PLACEHOLDERS is passed, placeholders will be shown.

Events

These event callbacks let you respond to user interactions and state changes:

1. onLoad – Triggered when the SDK is ready and all fields have rendered.

2. onValid – Triggered when card data is valid. Useful if card data is needed for any logic.

3. onInvalid – Triggered when card data is invalid.

4. onFocus – Triggered when any of the fields (card_number, card_holder, exp, or cvv) gain user focus.

5. onBlur – Triggered when any of the fields (card_number, card_holder, exp, or cvv) lose user focus.

6. onClick – Triggered when any of the fields (card_number, card_holder, exp, or cvv) are clicked.

7. onValidationSuccess – Triggered when a field (card_number, card_holder, exp, or cvv) passes validation.

8. onValidationError – Triggered when a field (card_number, card_holder, exp, or cvv) fails validation.

9. onCardBrandNotSupported – Triggered if the card brand is not supported by the current session configuration.
   Can be used as part of your validation process.

10. onCardBinInput – Triggered when the BIN (Bank Identification Number) section of the card number is changed.
    Helps with real-time validation and checking for eligibility with OBT (Open Banking Transfer) methods.

API functions

These functions allow programmatic control over card rendering, tokenization, and session handling:

1. getPaymentCardDetails – Retrieves an object with current card data:
   {card_number: string, card_exp: string, card_type: string, card_token: string | undefined}
   Note: card_token is available if a saved card was selected.

2. getCustomerCards – Returns a Promise with an array of stored cards. See list of cards.

3. getAvailableGateways – Returns a Promise with available gateways for the customer.
   Requires an object with the following fields (see request parameters):

   gateway_type
gateway
country
currency
locale
payment_method
amount
card_token
include_payment_information

4. pickCustomerCard(card_token) – Use this in two cases:
   When selecting a saved card (pass the card_token from getCustomerCards).
   To add a new card (pass an empty card_token).

5. tokenizeCard – Saves card data for the current session and returns a Promise.
   On success: returns the token.
   On failure(error): returns null.

6. getAvailableOBTMethods(currency) – Checks for available OBT gateways based on card BIN or template.
   Returns a Promise with gateway and PSP bank info on success, or null on failure(error) or if no matches are found.

{danger.fa-exclamation-triangle} IMPORTANT 1: Before proceeding with the Direct API processing request, the tokenizeCard function must be called.
Otherwise, the transaction will fail due to missing token association.

{danger.fa-exclamation-triangle} IMPORTANT 2: Once tokenizeCard is called, the resulting token is valid for 15 minutes.
If the Direct API request doesn't arrive within that time, the call will fail.

JS SDK Implementation Example

Please review these key considerations during HPF integration:

1. Clean Up on Form Restart
   Whenever restarting the credit card form, ensure you remove all leftover components from the previous instance including event listeners and bindings.

2. Avoid Re-Initialization on the Same Page
   If you plan to reinitialize the method, do not do it on the same page where the previous form was initialized. Residual bindings could interfere with the new form.

3. Handling for SPAs (Single-Page Applications)
   When using HPF in an SPA environment, always make sure to clean up all previous events and bindings before starting a new instance.

<html>
    <head>
        <script>
            let sdk = document.createElement('SCRIPT'),
                isSandboxHPF = true,
                src = isSandboxHPF
                    ? 'https://cdn-pci.cashier-test.com/PraxisGate.js'
                    : 'https://cdn.praxisgate.com/PraxisGate.js';
            sdk.src = src + '?t=' + (new Date()).getTime();
            document.querySelector('head').appendChild(sdk);
        </script>
    </head>
    <body>
        <div>
            <form action="<?= YOUR_PAYMENT_FORM_SUBMISSION_URL ?>" method="post">
                <div id="secure-card-number"></div>
                <div id="cards-list"></div>
                <div id="secure-card-holder"></div>
                <div id="secure-exp"></div>
                <div id="secure-cvv"></div>
                <button type="submit" id="submit" disabled="">Submit</button>
            </form>
        </div>
        <script>
            let PraxisGateInstance;
            const praxisGateInterval = setInterval(function () {
                if (typeof window.PraxisGate !== 'undefined') {
                    clearInterval(praxisGateInterval);
                    PraxisGateInstance = new PraxisGate({
                        sessionToken: 'SESSION_TOKEN',
                        containers: {
                            card_number: '#secure-card-number',
                            card_holder: '#secure-card-holder',
                            exp: '#secure-exp',
                            cvv: '#secure-cvv',
                        },
                        onValid: function() {
                            let tokenizePromise = PraxisGateInstance.tokenizeCard();
                            tokenizePromise.then(function(token) {
                                if (token === SESSION_TOKEN) {
                                    document.getElementById('submit').disabled = false;
                                } else {
                                    document.getElementById('submit').disabled = true;
                                }
                            })
                        },
                        onInvalid: function() {
                            document.getElementById('submit').disabled = true;
                        },
                        onFocus: function(fieldName) {},
                        onBlur: function(fieldName) {},
                        onClick: function(fieldName) {},
                        onValidationSuccess: function(fieldName) {},
                        onValidationError: function(fieldName) {},
                        onLoad: function() {
                            let customerListPromise = PraxisGateInstance.getCustomerCards(); // list of available templates also can be received by Agent API get_customer_cards request
                            customerListPromise.then(function (list) {
                                // merchants business logic to process customer cards list
                            })
                            let availableGatewaysListDataObject = {
                                "gateway_type": null, // insert here value if needed
                                "gateway": null, // insert here value if needed
                                "country": null, // insert here value if needed
                                "currency": null, // insert here value if needed
                                "locale": null, // insert here value if needed
                                "payment_method": null, // insert here value if needed
                                "amount": null, // insert here value if needed
                                "card_token": null, // insert here value if needed
                                "include_payment_information": null, // insert here value if needed
                            }
                            let availableGatewaysListPromise = PraxisGateInstance.getAvailableGateways(availableGatewaysListDataObject); // list of available gateways also can be received by Agent API get_available_gateways request
                            availableGatewaysListPromise.then(function (list) {
                                // merchants business logic to process gateways list
                            })
                            // ready to run merchants business logic
                        }
                        css: `
                            input {
                                border: none;
                                background: none;
                                outline: transparent;
                                font-size: 16px;
                                font-family: Courier;
                            },
                            .card-number {
                                width: '100%';
                            }
                        `,
                        labels: {
                            display: [window.PG_INPUT_SHOW_LABELS, window.PG_INPUT_SHOW_PLACEHOLDERS],
                            label_card_number: 'Credit Card',
                            label_card_holder: 'Card Holder',
                            label_exp: 'Expires',
                            label_cvv: 'CSC/CVV',
                            label_no_cards_saved: 'No Cards Saved',
                            label_new_card: 'New Card',
                            placeholder_card_number: '0000 0000 0000 0000',
                            placeholder_card_holder: 'Card Holder Name',
                            placeholder_exp: 'MM/YY',
                            placeholder_cvv: 'CVV'
                        }});
                    PraxisGateInstance.sendCSS({input: {color:'#555'}});
                }
            }, 150);
        </script>
    </body>
</html>