Seamless Checkout Integration

A seamless checkout integration allows you to embed a Novalnet payment gateway directly into your website, providing a user-friendly checkout with lot more customization. This guide included with necessary API endpoints, handle methods with request and response parameters

Integration

The seamless checkout integration entirely on the use of iframe technology for embedding and, the URL for the payment form is generated by the Novalnet API system.

The sequential steps of the iframe integration process are described below

  • Obtain the payment form URL
  • Render and handle the payment form in Iframe

Obtain the Payment form URL

Header Authentication

  1. Each header request is built using the Payment access key. To get your Payment Access Key, login to your Novalnet Admin Portal and navigate to the path Projects -> [Select Desired Project] -> API credentials -> Payment access key
  2. The Payment Access Key should be encoded using a variant of Base64.
  3. The resultant base64_encoded value should be passed in the Novalnet's custom header key X-NN-Access-Key.
    The custom header field is formulated in the format: X-NN-Access-Key: base64_encoded_value.

All payment requests must be carried out through an HTTPS connection along with the header values, otherwise, the request will fail with authorization error messages.

Your Payment Access Key carry many privileges, so be sure to keep them secure! Do not share your secret Payment Access Key in publicly accessible areas such as GitHub, client-side code, and so forth.

Preparation of the Payment Form request

Endpoint: https://payport.novalnet.de/v2/seamless/payment

Sample Request Header:

Sample Request Header:
[
"Content-Type:application/json",
"Charset:utf-8",
"Accept:application/json",
"X-NN-Access-Key: base64_encoded(<YOUR_PAYMENT_ACCESS_KEY>)",
];

Render and handle the payment form in Iframe

Once the iframe URL is created successfully, you can prepare the client-side page (where the payment form has to be displayed) through the following steps,

Step 1: Include the Novalnet's checkout JS libirary https://cdn.novalnet.de/js/pv13/v1.0.0/checkout-lib.js.

Step 2: Create an iframe HTML tag, the area you want to show the seamless checkout in your shop/integration-environment.

src="result.redirect_url"

Set the generated iframe URL as the value of the 'src' attribute

allow="payment"

This attribute specifies a feature policy that allows the iframe to process payments. It is essential for embedding a secure checkout processing.

referrerPolicy="origin"

This attribute controls the referrer information sent when navigating to the iframe's URL. The value origin ensures that only the origin (e.g., https://example.com) of the document is sent as the referrer, enhancing privacy and security.

iframe
<iframe id="novalnetPaymentIFrame" src="$response->result->redirect_url" allow="payment"
referrerPolicy="origin"></iframe>

Step 3: Create the Payment Intent and synchronize with the shop/integration-environment, The initialization process should be implemented during the DOMContentLoaded event. Refer to the sample script below:

Step 3.1: Create payment form instance

Creating instance for the seamless checkout form

const paymentForm = new NovalnetPaymentForm();

Step 3.2: Synchronize with shop or integration environment

To sync the payment form with the shop or integration environment, use the initiate method. This step involves providing necessary data for synchronization, ensuring the payment form is aware of the current state of the shopping cart, user information, and other relevant details.

  • The function call initializes the payment form with the necessary data.
  • The postMessageData object contains all the required information to synchronize the payment form with the current state of your shopping environment
Payment Form Sync
/** Sync the payment form with the shop or integration environment
*
* @param (Object)
* @return
*/
paymentForm.initiate(postMessageData)
Synchronization
document.addEventListener('DOMContentLoaded', (event) => {
    let paymentForm = new NovalnetPaymentForm();

    let paymentFormRequestObj = {
        iframe: '#novalnetPaymentIFrame',
        initForm: {
            creditCard: { // Optional
                text: {
                    error: "Your credit card details are invalid",
                    card_holder: {
                        label: "Card holder name",
                        place_holder: "Name on Card",
                        error: "Please enter the valid card holder name"
                    },
                    card_number: {
                        label: "Card number",
                        place_holder: "XXXX XXXX XXXX XXXX",
                        error: "Please enter the valid card number"
                    },
                    expiry_date: {
                        label: "Expiry date",
                        error: "Please enter the valid expiry month / year in the given format"
                    },
                    cvc: {
                        label: "CVC/CVV/CID",
                        place_holder: "XXX",
                        error: "Please enter the valid CVC/CVV/CID"
                    }
                }
            },
            uncheckPayments: true, // Optional
            showButton: false      // Optional
        }
    };

    // Initiate payment form
    paymentForm.initiate(paymentFormRequestObj);
});

Step 4: Attach `Pay` or `Checkout submit` functionality for the checkout page
Add an event listener to the checkout button to handle the click event and retrieve payment details. Refer to the sample script below.

Sample Script
document.querySelector('#CHECKOUT-BUTTON').addEventListener('click', function () {
    /**
     * Get the current selected payment details,
     * And this functionality works based on callback handling at a single place
     */
    paymentForm.getPayment((paymentDetails) => {
        $.post('###SHOP_API_ENDPOINT###', paymentDetails, function (response) {
            // Handle payment detail as per the Novalnet payment API
        });
    });
});

Additional functionalities

If you need any additional modifications to your payment form, you can use these methods based on your requirement.

Get the current selected payment information

To get the current selected payment information,

Payment Information
novalnetInstance.selectedPayment((data) => {
    // Sample data
    {
        nnpf_postMsg: "SELECTED_PAYMENT",
        payment_details: {
            key: 6,
            name: "Credit/Debit Cards",
            type: "CREDITCARD"
        }
    };
});

Update the customer address and checkout amount dynamically

Add an event listener to handle the cart change event and update the address and amount in your JavaScript code:

By integrate this functionality, you can to update the cart address and amount when a specific event (e.g., button click) occurs, ensuring a dynamic and responsive checkout process

JAVASCRIPT
/ To update the address or amount of the checkout
document.querySelector('#ON_CART_CHANGE').addEventListener('click', function ()
{
    // Updated billing address
    let updatedAddress = {
        billing_address: {
            street: "###STREET_NO###",
            city: "###CITY###",
            zip: "###ZIP###",
            country_code: "###COUNTRY_CODE###"
        },
        shipping_address: {
            street: "###STREET_NO###",
            city: "###CITY###",
            zip: "###ZIP###",
            country_code: "###COUNTRY_CODE###"
        },
        same_as_billing: 1,
        amount: '###NEW_CART_AMOUNT###' // Updating final amount
    };

    /** Custom function for callback handling
     *
     * @param (Object) response
     * @return (Null)
     */
    function updateCallback(response) {
        Sample response
        {
            "result": {
                "status": "SUCCESS",
                "message": "Update successful"
            }
        }
    }

    /** To update the address and amount of the checkout
     *
     * @param (Object) updatedAddress
     * @param (Function) updateCallback
     * @return (Boolean)
     */
    paymentForm.updateForm(updatedAddress, updateCallback);
});

Select the particular payment in the payment form

To receive the payment booking details by asynchronously

/** To select the payment in the form.
* @param (String) PAYMENT_NAME > EX: CREDITCARD, INVOICE, PREPAYMENT
* @return (Boolean)
*/
paymentForm.checkPayment('PAYMENT_NAME');

Deselecting the chosen payments methods from the payment form

To deselect all the payments from the payment form.

/** To deselect the payments in the form.
*
* @return (Boolean)
*/
paymentForm.uncheckPayment();

Process Payment

Processing payment through API

After receiving the payment configuration and other required parameters, you can process the payment using the Novalnet Direct API.

You can refer to the below mentioned link to know more about the Novalnet Direct API parameters, sample codes and results for retrieving the transaction API,

Refer to this link to know more more about parameter references

Technical Support Through Novalnet

For any questions or further enquiries please contact one of the following departments as per your requirement. Our in-house experts are ready to assist you in case of queries or issues.

For installation assistance contact technic@novalnet.de or call +49 89 9230683-19

For a merchant account, new payment plugin or additional payment methods, please contact sales@novalnet.de or call +49 89 9230683-20.

If you have any recommendations or suggestions for improvement kindly share your thoughts with us to develop our payment plugins further technic@novalnet.de or call us at +49 89 9230683-19.

For our License details see for Freeware License Agreement

Related Topics