Events (Callbacks)

These event callbacks let you respond directly to user interactions and state changes within the card fields.

Event Callback	Trigger Condition	Primary Use Case
`onLoad`	Triggered when the SDK is ready and all fields have rendered.	Confirm the SDK is operational and start initialization logic.
`onValid`	Triggered when card data is valid.	Useful if card data is needed immediately for any subsequent logic.
`onInvalid`	Triggered when card data is invalid.	Provide real-time feedback to the user or disable submission buttons.
`onFocus`	Triggered when any field (`card_number`, `exp`, `cvv`, etc.) gains user focus.	Custom UI highlighting or tracking user flow.
`onBlur`	Triggered when any field loses user focus.	Trigger field-level validation checks.
`onClick`	Triggered when any field is clicked.	Debugging or specific interaction tracking.
`onValidationSuccess`	Triggered when a single field passes validation.	Granular feedback, confirming valid input for one field.
`onValidationError`	Triggered when a single field fails validation.	Show specific error message for the failed field.
`onCardBrandNotSupported`	Triggered if the card brand (e.g., Visa, Mastercard) is not supported by the current session.	Used in validation logic; notify the user immediately.
`onCardBinInput`	Triggered when the BIN (Bank Identification Number) section of the card is changed.	Helps with real-time eligibility checks (e.g., for OBT methods).

API Functions

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

Retrieval Functions

Function	Returns	Purpose
`getPaymentCardDetails`	Object: `{card_number: string, card_exp: string, card_type: string, card_token: string \| undefined}`	Retrieves the current card data. (`card_token` is only available if a saved card was selected).
`getCustomerCards`	`Promise<Array>`	Returns a Promise with an array of stored cards for the customer.
`getAvailableGateways`	`Promise<Object>`	Returns available gateways for the customer based on request parameters.
`getAvailableOBTMethods(currency)`	`Promise<Object \| null>`	Checks for available OBT (Open Banking Transfer) methods based on card BIN or template. Returns gateway and PSP bank info on success.

Control & Tokenization Functions

Function	Returns	Purpose
`pickCustomerCard(card_token)`	n/a	Selects a card to be used for the current session. Pass the `card_token` for a saved card or an empty token to add a new card.
`tokenizeCard`	`Promise<string \| null>`	Saves card data for the current session. Returns the unique token on success or `null` on failure.

🛑
CRITICAL IMPLEMENTATION NOTES
1. Tokenization Requirement
Before proceeding with the Direct API processing request, the tokenizeCard function MUST be called. Otherwise, the transaction will fail due to a missing token association in the final request.
2. Token Expiry
Once tokenizeCard is successfully called, the resulting token is valid for only 15 minutes. If the final Direct API processing request does not arrive within that time window, the call will fail.

SDK Implementation Best Practices

Please review these key considerations during HPF Integration.

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.
Avoid Re-Initialization on the Same Page: If you need 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 instance.
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() {
                            document.getElementById('submit').disabled = false;
                        },
                        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>