ParityVend Testing Mode

Average read time: 6 minutes.

ParityVend’s Testing Mode is a special mode designed for secure integration testing within non-live environments. Testing Mode is available for both ParityVend No-Code and ParityVend API. It disables certain security checks, allowing you to test your integration on domains that don’t match your live website, such as localhost, 127.0.0.1, or a development server. Read this guide to understand how to use the ParityVend Testing Mode and its security considerations.

Why do I need Testing Mode?

ParityVend incorporates a security feature called “Origin Checking” to safeguard the integrity of your integration. This mechanism plays a crucial role in preventing unauthorized access and exploitation. When a request is made to ParityVend API, your web browser automatically includes an Origin header. ParityVend examines this header to confirm that the request genuinely originates from your authorized website. This verification process helps to block any potentially malicious attempts to exploit your integration.

During the development and testing phases of your integration, you’ll often need to test it on a local development environment, such as localhost, 127.0.0.1 or a staging server. These environments typically have different domain names than your live website, which triggers Origin Checking restrictions and rejects these requests.

To facilitate testing in these non-live environments, Testing Mode is essential. It temporarily disables Origin Checking, allowing you to test your integration seamlessly on domains that don’t match your live website’s domain, letting you easily test your integration without restrictions.

How to use the Testing Mode (ParityVend No-Code)

ParityVend No-Code enables the Testing Mode when you add a key "testingSecret" containing your unique testing_secret to the integration code. There are two ways to enable the Testing Mode in ParityVend No-Code:

  • Dashboard

    1. Open the Dashboard

    2. Click on your project

    3. Click “code” in the navigation menu

    4. Select “demo” and click “copy code”.

    5. This will copy the ParityVend No-Code integration code, which will enable the Testing Mode automatically.

    6. Replace your website’s integration code with the new one, that has Testing Mode enabled.

  • Modify integration code

    1. Locate your ParityVend No-Code integration code.

    2. Add a new key “testingSecret” which equals to a string with your testing_secret. See the highlighted line in the example below:

      <script id="parityvend-no-code">
   var parityvendScript = document.createElement("script");
   parityvendScript.onload = function () {
      parityvendUpdateConfig({
         design: "solid/diamond",
         apiKey: "........",
         testingSecret: "....................................",
      });
      parityvendLoad();
   };
   parityvendScript.src = "https://api.parityvend.cloud/no-code-latest.js";
   document.head.appendChild(parityvendScript);
</script>

    3. Replace your website’s integration code with the new one, that has Testing Mode enabled.

After completing these changes, ParityVend No-Code will enable the Testing Mode. You will see a message in the Console of your browser’s devtools, confirming that the Testing Mode has been enabled.

How to use the Testing Mode (ParityVend API)

You can enable the Testing Mode for all ParityVend API “frontend” endpoints, which are /frontend/get-country/, /frontend/get-discount/, /frontend/get-banner/, and /frontend/get-discount-with-html/. To do this, follow the steps below:

  1. Modify endpoint URL:

    To activate Testing Mode for an endpoint, modify the endpoint URLs by adding the prefix “testing-mode-” before the original endpoint name. For instance, to enable Testing Mode for the “get-banner” endpoint, you would adjust the URL from /frontend/get-banner/ to /frontend/testing-mode-get-banner/. This prefix signals to ParityVend that Testing Mode should be used for this specific request.

  2. Add the testing-secret argument:

    As Testing Mode holds a high security significance, a secure way to authorize requests is needed, to ensure that this is actually who wants to enable the testing mode - not some attacker. For this, the “testing_secret” parameter plays a crucial role in authenticating and enabling Testing Mode. To proceed, add this query argument to your request, ensuring you provide your unique testing secret value. This value acts as a secure key that grants you permission to enable the Testing Mode. Continuing with the previous example, add the query argument to the URL to enable the Testing Mode: ?testing-secret=<YOUR TESTING SECRET>.

Warning

Exercise caution and never expose your testing_secret in production environments. It’s intended solely for testing purposes and should be removed before deploying your integration to a live website. Read the security section for more information about the dangers of testing mode.

For your convenience, find a list of prepared endpoints, already changed to the Testing Mode. Make sure to replace the <YOUR TESTING SECRET> and <YOUR PUBLIC KEY> with your actual testing_secret and public_key:

https://api.parityvend.cloud/frontend/testing-mode-get-banner/<YOUR PUBLIC KEY>/?testing-secret=<YOUR TESTING SECRET>

https://api.parityvend.cloud/frontend/testing-mode-get-country/<YOUR PUBLIC KEY>/?testing-secret=<YOUR TESTING SECRET>

https://api.parityvend.cloud/frontend/testing-mode-get-discount/<YOUR PUBLIC KEY>/?testing-secret=<YOUR TESTING SECRET>

https://api.parityvend.cloud/frontend/testing-mode-get-discount-with-html/<YOUR PUBLIC KEY>/?testing-secret=<YOUR TESTING SECRET>

Emulating Countries

Testing Mode empowers you to effortlessly test your integration’s behavior across various countries without physically changing your location. This is achieved through the testing-country parameter. This is useful for testing integration from different countries and ensures seamless integration testing.

To simulate a request originating from a specific country, simply append the testing-country query argument to your request and set its value to the desired two-letter country code in the ISO 3166-1 alpha-2 standard. Make sure you enter the correct country code, and requests with incorrect codes will simply return a generic “error occurred” response.

To emulate a request coming from the United States, you would include testing-country=US in your request. ParityVend will then process your request as if it originated from the specified country, allowing you to observe and test how your integration functions in that particular context. This proves useful for ensuring seamless user experiences across different regions.

For your convenience, here is a list of prepared endpoints with testing-country appended, showing examples for US (United States), AU (Australia), DE (Germany), and GR (Greece). Make sure to replace the <YOUR TESTING SECRET> and <YOUR PUBLIC KEY> with your actual testing_secret and public_key:

https://api.parityvend.cloud/frontend/testing-mode-get-banner/<YOUR_PUBLIC_KEY>/?testing-secret=<YOUR_TESTING_SECRET>&testing-country=US

https://api.parityvend.cloud/frontend/testing-mode-get-country/<YOUR_PUBLIC_KEY>/?testing-secret=<YOUR_TESTING_SECRET>&testing-country=AU

https://api.parityvend.cloud/frontend/testing-mode-get-discount/<YOUR_PUBLIC_KEY>/?testing-secret=<YOUR_TESTING_SECRET>&testing-country=DE

https://api.parityvend.cloud/frontend/testing-mode-get-discount-with-html/<YOUR_PUBLIC_KEY>/?testing-secret=<YOUR_TESTING_SECRET>&testing-country=GR

Some Key Points:

  • Testing Mode Exclusive: The testing-country parameter is only available within Testing Mode and cannot be used in production environments.

  • Testing Versatility: It provides a convenient way to test country-specific features, content variations, or localization strategies without the need to physically change your location or device settings.

  • Enhanced Insights: By simulating requests from various countries, you can gain valuable insights into potential regional differences in your integration’s behavior, enabling you to make necessary adjustments or optimizations for a truly global user experience.

Production Usage: Prioritizing Security

Testing Mode, by design, disables certain security measures to facilitate testing and debugging. While it is useful during the development phase, it must be always disabled before publishing your website to live/production. Leaving Testing Mode enabled on a live website poses security risks and exposes your integration to potential exploitation by attackers.

Danger

Always ensure Testing Mode is disabled when making your website available to the public. Testing Mode simplifies your development process, but neglecting to disable it before your website goes live can have serious security consequences.

Testing Mode temporarily disables Origin Checking, a vital security feature that ensures only requests from your authorized website are accepted. With Testing Mode active in production, anyone could potentially send requests to your ParityVend integration without origin verification. If an attacker gains access to your testing_secret, they could potentially exploit your API key. This could involve:

  • Integrating ParityVend on their own website: They could use your API key to integrate ParityVend onto their website, exploiting or misusing your account and resources.

  • Sending unauthorized requests: They could send fraudulent or malicious requests through your integration, compromising your data or functionality, or even putting visitors in danger.

Danger

Even though Testing Mode simplifies development, security should always be your top priority. Leaving it enabled in production exposes your integration to significant risks. If you ever accidentally share or commit your testing_secret, we recommend that you immediately reissue your API keys.

How to Disable Testing Mode

To ensure a secure website launch, carefully follow these steps before going live:

  • For ParityVend No-Code users: If you use the ParityVend No-Code, remove the “testingSecret” key from the configuration.

  • Remove the “testing-mode-” prefix: From all endpoint URLs used by your integration, remove the “testing-mode-” prefix.

  • Delete the “testing_secret” parameter: Ensure all requests sent to ParityVend no longer include the “testing_secret” parameter.

  • Delete the “testing-country” parameter: Verify that you’re not using the “testing-country” parameter in any production requests.

By diligently following these steps, you can confidently launch your website with a secure ParityVend integration.

Advanced: Understanding Origin Checking

In the world of web development and APIs, trust is paramount. When you integrate a powerful tool like ParityVend into your website, you share sensitive data and functionalities. To safeguard this trust and prevent unauthorized access, ParityVend employs crucial security measures, one of which is “Origin Checking”.

What is Origin Checking?

Imagine your website as a fortress, and Origin Checking acts as a vigilant gatekeeper. This gatekeeper examines every incoming request sent to ParityVend from your website. It carefully inspects a special header called the Origin header, which essentially reveals the website where the request originated.

How does it work?

During setup, you configure ParityVend with your authorized website domain. This becomes the trusted origin. The Origin Checking compares the Origin header of each incoming request against your authorized domain. If the Origin header matches, the gatekeeper grants access, allowing the request to pass through to ParityVend and perform its intended function.

Why is Origin Checking important?

Without Origin Checking, any rogue website could copy your public_key and send requests to ParityVend while pretending to be you. This could lead to several alarming scenarios:

  • Unauthorized access to your ParityVend account and data.

  • Misuse of your API key for malicious purposes.

  • Compromised functionality of integrations.

Origin Checking ensures that only requests originating from your trusted website have access to your ParityVend integration, effectively preventing these security threats. Therefore, it’s important to disable the Testing Mode in production, as it disables Origin Checking.