JavaScript SDK JavaScript SDK

• Example

SDK parameters and customization

General

1. PAYLOAD_SRC - URL to JS SDK

2. SESSION_TOKEN session token returned from the open-hpf-session S2S call
3. containers property - specify containers that the SDK will use for each field (CVV container can be skipped if the CVV field is not needed)

UI customization (CSS and Labels)

Use these to customize the look & feel of the user interface:

{danger.fa-exclamation-triangle} NOTE: By default, the SDK will retreive the CSS for the Hosted Payment Fields from the HPF CSS configuration set in the Praxis backoffice (Atlas), where CSS can be customized and persisted. Praxis recommends to use the CSS properties of the SDK only if you need to override the stored CSS for specific sessions or apply in-session changes.

1. css property - an example how CSS can be initialized within SDK object
2. sendCSS function - an example how CSS can be modified after object initiation
3. labels property - customize labels and/or placeholders, if window.PG_INPUT_SHOW_LABELS is passed - custom input labels will be shown, if window.PG_INPUT_SHOW_PLACEHOLDERS is passed - custom input placeholders will be shown

Events

Use the events to run your own code to handle different application statuses as well as for tracking of user activity with the hosted payment fields:

1. onLoad function - this callback will be invoked when the SDK is ready and all fields are rendered
2. onValid function - this callback will be invoked when card data is valid, you can implement code for this event if card data is required for any purpose
3. onInvalid function - this callback will be triggered when card data is invalid
4. onFocus function - this callback will be triggered when any of the fields (card_number or card_holder or exp or cvv) is in user focus
5. onBlur function - this callback will be triggered when any of the fields (card_number or card_holder or exp or cvv) lost the user focus
6. onClick function - this callback will be triggered when any of the fields (card_number or card_holder or exp or cvv) were clicked
7. onValidationSuccess function - this callback will be triggered when any of the fields (card_number or card_holder or exp or cvv) returned validation success
8. onValidationError function - this callback will be triggered when any of the fields (card_number or card_holder or exp or cvv) returned validation error
9. onCardBrandNotSupported function - this callback will be triggered if if the brand of the currently provided card is not supported by the current session configuration (can be used as a part of validation process)
10. onCardBinInput function - this callback will be triggered when there are changes in the BIN (Bank Identification Number) segment of the card number input. It allows tracking of user interactions with the card number field in real-time and helps determine the eligibility of the entered card for Open Banking Transfer (OBT) methods.

API functions

Use these to implement rendering & selecting from a list of already stored cards, capturing a new card or saving the token for the current session:

1. getPaymentCardDetails function - retrieve an object with card data: returns an object {card_number: string, card_exp: string, card_type: string, card_token: string|undefined} (where card_token - a token of recently saved card)
2. getCustomerCards function - get customer cards list, returns a Promise object containing an array for list of cards
3. getAvailableGateways function - fetch all available gateways for the customer, returns a Promise object containing an array for gateways list, takes object as a parameter that contains list of fields (see request parameters for more details):
   1. gateway_type
   2. gateway
   3. country
   4. currency
   5. locale
   6. payment_method
   7. amount
   8. card_token
   9. include_payment_information
4. pickCustomerCard(card_token) function - Use this for the following cases:
   1. When the customer picks a card from the list received from the getCustomerCards, specifying the 'card_token' that was selected.
   2. When you want the customer to add a new card, The card_token parameter must be empty.
5. tokenizeCard function - save card data into current session, returns a Promise object as a result: in case of success it will return the token of current session, or null in case of request error
6. getAvailableOBTMethods function - this function queries available OBT gateways for a given card BIN or template and returns a Promise object. It takes one parameter: currency. In case of success, it returns the gateway details along with PSP bank information, or null if no gateways are found or an error occurs.

{danger.fa-exclamation-triangle} NOTE #1: It is important to understand that before proceeding with the Direct API server to server processing request, tokenizeCard function must be called, otherwise the transaction will fail because card data will not be associated with the token for this session.

NOTE #2: Once tokenizeCard is called, the token is available for processing for 15 minutes. if the Direct API request does not arrive on time, the call will fail.

JS SDK Implementation Example

Please find below few important considerations to be taken during the HPF integration:

1. Clean Up on Form Restart: Whenever restarting the credit card form, it is essential to remove all leftover components of the previous form. This includes any event listeners or bindings left from the old instance.
2. Avoid Re-Initialization on the Same Page: If you would like to use the re-initialization method, they should not attempt this on the same page where the previous form was initialized. This can prevent leftover events from interfering with the new form.
3. Handling for SPAs: In case if you are using SPA (Single-Page Application) please make sure to find a way to clean up all events and bindings from any previously initialized instances before starting a new one.

<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',
                            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>