Get embedded component

Use the MPC Open‑Loop Prepaid Card Widget to display, activate, and manage an open‑loop prepaid card directly inside your application. This embeddable web component allows you to present the full prepaid card experience—including balance details, activation, and card management—without redirecting users outside your app. To implement the widget, embed the MPC Open‑Loop Card view as a web component and authenticate it using the token and tenant key retrieved from Tango’s API.

Open-Loop embedded component flows

The table below explains the two high‑level flows for using Tango’s embedded components with an Open-Loop Prepaid Card:

Prerequisites

The following requirements are needed before you can load the MPC Open-Loop Prepaid Card Widget inside your application:

• Have a valid Open-Loop Prepaid Card order: Place an order for an Open-Loop Prepaid Card and obtain a valid referenceLineItemID.
• Be able to call Tango REST APIs from your backend: Your backend must be able to call Tango API endpoints such as: POST /orders and GET /lineItems/{referenceLineItemID}/embeddedComponents.
• Have your domain added to the BHN allowlist: Contact your Customer Success Manger (CSM) or [email protected] to have your domain name added to the BHN allowlist to access the widget in both Sandbox and Production Tango environments.

Embedded component integration steps

The embedded component integration steps describes the complete process required to display the MPC Open-Loop Prepaid Card Widget inside your application using Tango’s API. By following these steps, your application can securely authenticate, load, and display the prepaid card experience without redirecting users to an external site.

Follow the implementation steps below:

1. Place the order

Create an Open-Loop Prepaid Card order using deliveryMethod=EMBEDDED_COMPONENT. The order response contains the credentials your widget needs. To place the order, call the following endpoint:

POST {URI}/orders

The request body below defines the prepaid card parameters. Setting deliveryMethod to EMBEDDED_COMPONENT tells Tango to generate a card intended for in‑app embedding rather than email delivery.

{
  "deliveryMethod": "EMBEDDED_COMPONENT",
  "externalRefID": "string",
  "customerIdentifier": "string",
  "accountIdentifier": "string",
  "utid": "string",
  "amount": 0.00
}

The response payload example below returns the metadata associated with the order, including the card details, status, and—most importantly—the credential list. You can find the following values for configuring and loading the embedded component in your application:

• tenantKey: Identifies the tenant context for the MPC widget
• token: A short‑lived access token required to authenticate the widget for the first view

{
    "referenceOrderID": "string",
    "referenceLineItemID": "string",
    "externalRefID": "string",
    "customerIdentifier": "string",
    "accountIdentifier": "string",
    "accountNumber": "string",
    "amountCharged": {
        "value": 0.00,
        "currencyCode": "USD",
        "total": 0.0
    },
    "denomination": {
        "value": 0,
        "currencyCode": "USD"
    },
    "utid": "string",
    "rewardName": "Hawk Open Loop Embedded Component Reward",
    "sender": {
        "firstName": "",
        "lastName": "",
        "email": ""
    },
    "recipient": {
        "firstName": "",
        "lastName": "",
        "email": "",
        "mobileNumber": null,
        "address": null
    },
    "sendEmail": false,
    "deliveryMethod": "EMBEDDED_COMPONENT",
    "status": "COMPLETE",
    "orderStatus": "COMPLETE",
    "lineItemStatus": "COMPLETE",
    "createdAt": "date",
    "reward": {
        "credentialList": [
            {
                "label": "tenantKey",
                "value": "tango",
                "type": "text",
                "credentialType": "secretCode"
            },
            {
                "label": "token",
                "value": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI2RG13VXBxTV96ejB6SHZwakV6MUljWmlycjJLakpxNE9fOWdvZGRpOVhRIn0.eyJleHAiOjE3NzIxNDI5MDQsImlhdCI6MTc3MjE0MjAwNCwianRpIjoib25ydGNjOmM1MmQ5MTlkLWE5MTYtYjBmOC02YjFiLWViNTg5YjViNWU0ZiIsImlzcyI6Imh0dHBzOi8vYXV0aC1wcC5ibGFja2hhd2tuZXR3b3JrLmNvbS9yZWFsbXMvY29yZS1hcHBzIiwiYXVkIjpbInJlYWxtLW1hbmFnZW1lbnQiLCJhY2NvdW50Il0sInN1YiI6ImMxZWRlMjI2LTU2ZTAtNDdhOC1iMTM4LWM4MTE3MjE3NzFkZiIsInR5cCI6IkJlYXJlciIsImF6cCI6InJleC10YW5nby1jbGllbnQiLCJzaWQiOiIzaUIyUWxzbTB3SmxoTkhSaHFsbEVFcjMiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbIi8qIl0sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJkZWZhdWx0LXJvbGVzLWNvcmUtYXBwcyIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJhdXRoel9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7InJlYWxtLW1hbmFnZW1lbnQiOnsicm9sZXMiOlsiaW1wZXJzb25hdGlvbiJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJwcm9maWxlIHVyeC1yci1jdXN0b20tY2xhaW1zIHRlbmFudF9zY29wZSB0ZW5hbnRpZCBjdXN0b20tdXNlci1hdHRyaWJ1dGUtbWFwcGVyIGVtYWlsIiwiY2xpZW50SG9zdCI6IjEwLjE4Ni41OS4xMjkiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsIlgtRUlEIjoiUzhHQzRINDBSMlI2TjJMNkM2MlRKV1ZOM0MiLCJYLVRJRCI6IjY1N1EwUkdWVEpUWktDNTBBVzJQOFNUWVFDIiwiWC1UUkFOU0FDVElPTi1JRCI6ImZiMTk2NmFhLTZhYTctNGQwMi1iMDgwLTI1M2IyODFmNWEyMiIsInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2UtYWNjb3VudC1yZXgtdGFuZ28tY2xpZW50IiwiY2xpZW50QWRkcmVzcyI6IjEwLjE4Ni41OS4xMjkiLCJjbGllbnRfaWQiOiJyZXgtdGFuZ28tY2xpZW50In0.LueF7C1dGlOzcxbq0SUVHMGkepc7JblQAjwKBxnjIsK5XxKrfil1ppfC1nHQifrl3Blmm4FcqVwmxQH9mmFo3H1kqAi4uJYpcu1GjFgQ-3kapMakLUHaH45BYRMWUyccdS6Ivj2e6zk_D3jE1LArhqPs0q-W5N3HUW1DSAzAIymGxsPRLt3RL37tnb2G9mb0uW6V6jLeD3d0T_SZugncDSXCcDrnJb2spp2_cX_XrKMZ1z8z4IkhNN6SzqjuSAcFQc3BI6Asq1UmIU2rys1PVfQ8Bn97ms4Qz1LKzXlWey4A191lLD9fE_i8anY_u7ha4eHcU1--l_0AM9xNtyOnYQ",
                "type": "text",
                "credentialType": "accessToken"
            }
        ],
        "redemptionInstructions": "<p><span style=\"color: rgb(0, 0, 0); font-family: Helvetica, Arial, sans-serif; font-size: 14px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; white-space: normal; text-decoration-thickness: initial; text-decoration-style: initial; text-decoration-color: initial; display: inline !important; float: none;\">Redeem your Hawk card</span></p>"
    }
}

📘

Note:

• For the first view, use the token and tenantKey from the order response to configure the web component.
• The token is short-lived and valid for 10 minutes. Retrieve a new token each time you need to display the embedded component after the original token expires.

2. Retrieve the Open-Loop widget token (Tango API)

Your application must request a fresh token each time the user returns to view the card. This step ensures that your application continues to display the embedded MPC Open‑Loop Prepaid Card widget after the initial token from the order response expires. The token included in the order response is short‑lived (about 10 minutes).

To retrieve the token, call the following Tango’s embedded components endpoint, passing the original referenceLineItemID. This line‑item identifier uniquely represents the specific prepaid card that was originally ordered.

GET /lineItems/{referenceLineItemID}/embeddedComponents

When embedding an Open-Loop Card for the API, send the following information in the request body to know which card it should generate:

When you send a valid request, the system responds with the token and tenantKey. Use both token and tenantKey when setting up or initializing the web component that displays the Open‑Loop Card.

{
  "token": "<string>",
  “tenantKey”: “<string>”
}

3. Load the widget script

You must now include the MPC embeddable widget script on your webpage (Sandbox or Production). Load the script before the widget can render. Include the script in the head of your HTML page, or anywhere before your own widget‑initialization code runs. Here's the examples for both environments:

For the Production environment:

<script
  src="https://cpp-content.bhn.cards/urx/urx-embeddable-card-view/{VERSION}/urx-embeddable-card-view.iife.js"
  defer>
</script>

For the Sandbox environment:

<script
  src="https://cpp-content.pp.bhn.cards/cpp/urx-embeddable-card-view/{VERSION}/urx-embeddable-card-view.iife.js"
  defer>
</script>

📘

Note:

• Replace VERSION with the latest available version (currently VERSION=1.0.0.)
• Load this script only once per page.

4. Add the widget element

Add a custom HTML element called embeddable-card-view to your page to show exactly where the Open‑Loop Card widget will show up. embeddable-card-view is the actual widget container provided by the MPC script.

<embeddable-card-view
  id="embeddable-card-view"
  on-error="handleError">
</embeddable-card-view>

After adding the widget element to the page, the next step is to retrieve the Open‑Loop widget token (which you get from the API). That token, along with your tenantKey, is used to initialize and render the widget inside this element.

5. Configure the Widget

Pass the token, tenantKey, and locale ( widgetConfig.locale) to the widget so it can authenticate and render properly. The configuration script must be placed in your page typically in the head or just before the closing /body tag.

<script>
  document.addEventListener('DOMContentLoaded', () => {
    const elem = document.getElementById('embeddable-card-view');

    elem.widgetConfig = {
      locale: 'en-US' // adjust as needed
    };

    // Use the access_token and tenant_key from GET /lineItems/{referenceLineItemID}/embeddedWidget
    elem.cardAuthContext = {
      token: '<token>',
      tenantKey: '<tenantKey>'
    };
  });

  function handleError(error) {
    console.error('Widget error:', error);
  }
</script>

6. Handle widget events and messaging

The widget and the parent page can now communicate using window.postMessage . Parent can receive widget events (like initialization or error messages) and send updates back, such as changing the widget’s language.

Here is a message example from Widget to Parent. Listen for these messages using a message event listener:

<script>
  window.addEventListener('message', (event) => {
    if (event.origin !== window.location.origin) return;
    const { type, payload, source } = event.data || {};
    if (source !== 'embeddable-card-widget') return;
    if (type === 'WIDGET_INITIALIZED') {
      console.log('Widget initialized:', payload);
    } else if (type === 'WIDGET_ERROR') {
      console.error('Widget error:', payload);
    }
  });
</script>

Here is a message example from Parent to Widget for language update. Your page can send instructions back to the widget, such as changing the widget’s language dynamically:

<script>
  function setWidgetLanguage(langCode, locale) {
    window.postMessage(
      {
        type: 'UPDATE_LANGUAGE',
        payload: { language: langCode, locale },
        source: 'parent-page'
      },
      window.location.origin
    );
  }
</script>

📘

Implementation Notes:

• Token source and tenant identifier: always use Tango’s embedded components endpoint rather than calling a separate auth server directly.
• Localization: set widgetConfig.locale to match your site’s language, and optionally update language at runtime via UPDATE_LANGUAGE.

Quick reference summary

This table is a fast, at‑a‑glance summary of the most important technical details you need when integrating the widget: