1 About
- 1.1 Introduction
- 1.2 Prerequisites
2 Step-by-step Instructions
- 2.1 Stage 1: Create a Simple Key Application
3 Stage 2: Run the setupBrowserKey Script
- - - 3.1.1.1 Example Script (JavaScript SDK)
  - 3.1.2 Stage 3: Use the Browser Key in Your Checkout Script
- 3.2 Conclusion
- 3.3 Next Steps

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

Log into your UltraCart account.
Navigate to:

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

screenshot image showing Setup API Credentials button

Developer Tools → REST APIs → Setup API Credentials.

Click New Application.
In the configuration panel:
* Enter a name for your application.
* Select Simple Key as the Authentication Type.
* Leave other settings default unless needed.
In the permissions section, select:
* checkout_read
* checkout_write
Click Save.

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).

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);
  }
});

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:

Example Browser Key Application after successfully running the generate browser key script.

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'
});

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

Creating a Browser Key for a JavaScript checkout