About

Introduction

UltraCart's Javascript Checkout requires a Browser Key for authentication. This setup ensures secure and scoped access for checkout functionality via the REST API.

This guide walks you through the two-stage process to properly configure a browser-authenticated application using the setupBrowserKey SDK function. This method is commonly used by OAuth-based integrations such as the UltraCart WordPress plugin.

Prerequisites

Prerequisite: You must have access to an UltraCart merchant account with permissions to manage API credentials.

Note: The JavaScript Checkout does not support simple key authentication. Only Browser Key authentication is valid for REST checkout operations.

Step-by-step Instructions

Stage 1: Create a Simple Key Application

1. Log into your UltraCart account.

2. Navigate to:

note

Main Menu → Advanced → Developer Tools → REST APIs → Setup API Credentials

3. Click New Application.

   

4. In the configuration panel:
   * Enter a name for your application.
   * Select Simple Key as the Authentication Type.
   * Leave other settings default unless needed.

5. In the permissions section, select:
   * checkout_read
   * checkout_write

6. Click Save.

info

This application will serve as the parent for creating the Browser Key in the next stage.

Stage 2: Run the setupBrowserKey Script

Use the setupBrowserKey SDK function from your server or OAuth application (e.g., a WordPress plugin).

note

Do not call this from the browser, as it requires a non-browser authentication context.

Example Script (JavaScript SDK)

const ultracart = require('ultracart-rest-api');

// Configure the API client using your Simple Key
let defaultClient = ultracart.ApiClient.instance;
let simpleApiKey = defaultClient.authentications['simple_key'];
simpleApiKey.apiKey = 'YOUR_SIMPLE_KEY_HERE';

let api = new ultracart.CheckoutApi();

let browserKeyRequest = {
  application: {
    name: "JavaScript Checkout App",
    authenticationType: "BrowserKey",
    browserAllowedOrigins: ["https://www.yoursite.com"]
  }
};

api.setupBrowserKey(browserKeyRequest, (error, response, data) => {
  if (error) {
    console.error("Error setting up browser key: ", error);
  } else {
    console.log("Browser Key setup complete.");
    console.log(data);
  }
});

note

Warning: The browser key created will be linked to the parent application that made the request.
*If the parent application is deleted, the browser key will also be deleted.

Example of the generated Browser Key Application in the REST APIs Logs:

Stage 3: Use the Browser Key in Your Checkout Script

Once the browser key is generated, embed it in your JavaScript Checkout implementation as follows:

ultracart.checkout.configure({
  browserKey: 'YOUR_BROWSER_KEY_HERE'
});

info

Tip: Be sure to configure your referrer restrictions properly in the browser key to prevent misuse.

Conclusion

Setting up a Browser Key is essential for secure JavaScript Checkout integration. By following the two-stage setup process—first creating a simple key and then using it to call setupBrowserKey—you ensure that your checkout is both secure and properly authenticated.

Next Steps

• Review the REST Checkout API documentation

• Download the UltraCart JavaScript SDK

• Implement your checkout form using the new browser key