Web Component Token Examples

Overview of Web Component tokens

Due to the inherent risk of front end authorization, we have a fine-grained access token pattern for our web components. The following table describes which roles can be used to render a web component. To generate a web component token use the web component token API or generate it in the JustiFi Portal (in the user menu click Developer https://portal.justifi.tech/developer/credentials). An API key is required for any API request. It can be generated in the JustiFi Portal on the same page.

Roles needed for each component

Component	Pre-Requisite	Role
BusinessDetails	Existing Business	read:business:`business_id` or write:business:`business_id`
PaymentProvisioning	Existing Business	write:business:`business_id`
GrossPaymentChart	Existing Sub Account	read:account:`account_id` or write:account:`account_id`
PaymentDetails	Existing Sub Account	read:account:`account_id` or write:account:`account_id`
PaymentsList	Existing Sub Account	read:account:`account_id` or write:account:`account_id`
PaymentTransactionsList	Existing Sub Account	read:account:`account_id` or write:account:`account_id`
PayoutDetails	Existing Sub Account	read:account:`account_id` or write:account:`account_id`
PayoutsList	Existing Sub Account	read:account:`account_id` or write:account:`account_id`
PayoutTransactionsList	Existing Sub Account	read:account:`account_id` or write:account:`account_id`
CheckoutsList	Existing Sub Account	read:account:`account_id` or write:account:`account_id`
TerminalsList	Existing Sub Account	read:account:`account_id` or write:account:`account_id`
TerminalOrdersList	Existing Sub Account	read:account:`account_id` or write:account:`account_id`
OrderTerminals	Existing Sub Account	read:business:`business_id` and write:account:`account_id`
Modular and Unified Checkout	Existing Checkout	write:checkout:`checkout_id` and write:tokenize:`account_id`
TokenizePaymentMethod	Existing Sub Account	write:tokenize:`account_id`
DisputeManagement	Existing Dispute	read:dispute:`dispute_id`, write:dispute:`dispute_id`, read:account:`account_id` or write:account:`account_id`
RefundPayment	Existing Payment	write:account:`account_id`

See the Web Components documentation for details on each web component.

General Usage

The pattern for using a web component starts in a backend request. Your backend should have an access token generated. Then, you need to find or create the resource the component needs to function, for example create a business before rendering the PaymentProvisioning component. Next, you generate a web component token, which is valid for 60 minutes, using the id(s) of the resources you will render. You then use this as the auth-token attribute to render the component in your front end.

Example: Retrieve a payment and render the Payment Details web component

The following steps show how to get the latest payment, generate a web component token, and render the PaymentDetails web component (copy and paste each block of code in a terminal to test using your credentials):

We use curl to make the API calls in the terminal, and jq to parse the JSON response. You can install them using Homebrew on a Mac or Chocolatey on Windows.

Generate Access Token via API

ACCESS_TOKEN_RESPONSE=$(curl -sS --request POST \
  --url https://api.justifi.ai/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id":"test_abc1234",
    "client_secret":"test_xyz9876"
  }'
)

Get the access_token and print to the console

ACCESS_TOKEN=$(echo $ACCESS_TOKEN_RESPONSE | jq -r '.access_token')
echo "Access Token: ${ACCESS_TOKEN}"

List Payments API using the access_token generated above and a test account:

ACCOUNT_ID="acc_abc1234"

PAYMENT_LIST=$(curl -sS --request GET \
  --url https://api.justifi.ai/v1/payments \
  --header 'Authorization: Bearer '${ACCESS_TOKEN}'' \
  --header 'Sub-Account: '${ACCOUNT_ID}''
)

Get the first payment_id from the payment list (= latest payment) and print to the console

PAYMENT_ID=$(echo ${PAYMENT_LIST} | jq -r '.data[0].id')
echo "Payment ID: ${PAYMENT_ID}"

Generate Web Component Token API (Note: replace acc_abc1234 with the account id from step 3)

WC_TOKEN_RESPONSE=$(curl -sS --request POST \
  --url https://api.justifi.ai/v1/web_component_tokens \
  --header 'Authorization: Bearer '${ACCESS_TOKEN}'' \
  --header 'Content-Type: application/json' \
  --data '{ "resources": [ "read:account:acc_abc1234" ] }'
)

Get the web_component_token and print to the console (Note: this token is valid for 60 minutes)

WEB_COMPONENT_TOKEN=$(echo $WC_TOKEN_RESPONSE | jq -r '.access_token')
echo "Web Component Token: ${WEB_COMPONENT_TOKEN}"

Front end code: payment_details.html

Note: replace WEB_COMPONENT_TOKEN and PAYMENT_ID with the values from the terminal script above

<!doctype html>
<html dir="ltr" lang="en">
<head>
  <meta charset="utf-8" />
  <meta
    name="viewport"
    content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0"
  />
  <title>justifi-payment-details</title>
  <script
    type="module"
    src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@6.14.5/dist/webcomponents/webcomponents.esm.js"
  ></script>
</head>
<body>
  <justifi-payment-details
    auth-token="${WEB_COMPONENT_TOKEN}"
    payment-id="${PAYMENT_ID}"
  >
  </justifi-payment-details>
</body>
</html>

Open the file in your browser OR run a local web server (you may use any web server)

Note: if you have python3 installed, you can run the following command in the folder where the HTML file was created to start a local web server.

# example using Python
python3 -m http.server

Open the file OR go to http://localhost:8000/payment_details.html, you should see the Payment Details web component

Example: Render the Payments List web component

The following steps show how to generate a web component token, and render the Payments List web component (copy and paste each block of code below into a terminal to test using your API credentials):

Generate Access Token API

ACCESS_TOKEN_RESPONSE=$(curl -sS --request POST \
  --url https://api.justifi.ai/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id":"test_abc1234",
    "client_secret":"test_xyz9876"
  }'
)

Get the access_token and print to the console

ACCESS_TOKEN=$(echo $ACCESS_TOKEN_RESPONSE | jq -r '.access_token')
echo "Access Token: ${ACCESS_TOKEN}"

Generate Web Component Token via API (Note: replace acc_abc1234 with an account id listed in the Payments List in the JustiFi Portal)

WC_TOKEN_RESPONSE=$(curl -sS --request POST \
  --url https://api.justifi.ai/v1/web_component_tokens \
  --header 'Authorization: Bearer '${ACCESS_TOKEN}'' \
  --header 'Content-Type: application/json' \
  --data '{ "resources": [ "read:account:acc_abc1234" ] }'
)

Get the web_component_token and print to the console (Note: this token is valid for 60 minutes)

WEB_COMPONENT_TOKEN=$(echo $WC_TOKEN_RESPONSE | jq -r '.access_token')
echo "Web Component Token: ${WEB_COMPONENT_TOKEN}"

Front end code: payment_list.html

Note: replace WEB_COMPONENT_TOKEN and ACCOUNT_ID with the values from the terminal script above

<!doctype html>
<html dir="ltr" lang="en">
<head>
  <meta charset="utf-8" />
  <meta
    name="viewport"
    content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0"
  />
  <title>justifi-payments-list</title>
  <script
    type="module"
    src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@6.14.5/dist/webcomponents/webcomponents.esm.js"
  ></script>
</head>
<body>
  <justifi-payments-list
    auth-token="${WEB_COMPONENT_TOKEN}"
    account-id="${ACCOUNT_ID}"
  >
  </justifi-payments-list>
  <script>
    const paymentsList = document.querySelector('justifi-payments-list');
    paymentsList.addEventListener('click-event', (event) => {
      // event.detail.name is 'tableRow', 'nextPage' or 'previousPage'
      // event.detail.data holds the clicked row's payment when the name is 'tableRow'
      if (event.detail.name === 'tableRow') {
        console.log(`You clicked on ${event.detail.data.id}`);
      }
    });
  </script>
</body>
</html>

Open the file or go to http://localhost:8000/payment_list.html, you should see the Payments List web component

Example: Create a business and render the Payment Provisioning web component

See the integration guide for detailed step-by-step instructions.

Front end code: payment_provisioning.html

Note: replace WEB_COMPONENT_TOKEN and BUSINESS_ID with the values from the terminal script in the integration guide

<!doctype html>
<html dir="ltr" lang="en">
<head>
  <meta charset="utf-8" />
  <meta
    name="viewport"
    content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0"
  />
  <title>justifi-payment-provisioning</title>
  <script
    type="module"
    src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@6.14.5/dist/webcomponents/webcomponents.esm.js"
  ></script>
</head>
<body>
  <justifi-payment-provisioning
    business-id="${BUSINESS_ID}"
    auth-token="${WEB_COMPONENT_TOKEN}"
  >
  </justifi-payment-provisioning>
</body>
</html>

Open the file or go to http://localhost:8000/payment_provisioning.html, you should see the Payment Provisioning web component

Example: Create a checkout and render the Unified Checkout web component

See the integration guide for detailed step-by-step instructions.

Overview of Web Component tokens​

Roles needed for each component​

General Usage​

Example: Retrieve a payment and render the Payment Details web component​

Front end code: payment_details.html​

Example: Render the Payments List web component​

Front end code: payment_list.html​

Example: Create a business and render the Payment Provisioning web component​

Front end code: payment_provisioning.html​

Example: Create a checkout and render the Unified Checkout web component​