Get embedded component

You are now ready to embed the URL you have retrieved in the previous step in your application (iFrame or WebView) so users redeem their gift cards without leaving your application. See Get embedded URL to learn how to retrieve the URL.

The instructions on this page help you embed the MPC Open-Loop Card view via a web component and authenticate it using a token and tenant key retrieved from Tango’s AP. A My Prepaid Center (MPC) Open-Loop Prepaid Card Widget is an embeddable user interface component that allows Tango to display, activate, and manage Open-Loop Prepaid Card directly inside your own application.

Requirements

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

• A valid Open-Loop Prepaid Card order: You must have already placed an order for an Open-Loop Prepaid Card and obtained a valid: referenceLineItemID.
• Ability 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.
• Your domain must be on 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.

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:

Embedded component integration workflow

The embedded component integration workflow outlines the complete sequence required to display the MPC Open-Loop Prepaid Card Widget inside your application using Tango’s API.

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 will need:

POST/orders

Request body (body params)

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

Response payload

{
    "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)

The initial token from the order response expires quickly (in about 10 minutes). The widget cannot be displayed without a valid, unexpired token and a matching tenantKey. For subsequent views, you must request a new token from Tango’s API. Use the following endpoint to retrieve and store the access token for a specific line item:

Endpoint

GET /lineItems/{referenceLineItemID}/embeddedComponents

Body parameter

Response

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

📘

Note:

Use token and tenantKey when configuring the web component.

3. Load the widget script

Add the MPC embeddable script for either Sandbox or Production. Include the script on the page (typically in the head), where the widget will render.

Production

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

Sandbox

<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

Place the MPC widget exactly where it will render in your software.

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

Retrieve the Open-Loop widget token

5. Configure the Widget

Pass the token, tenantKey, and widgetConfig.locale to the component once your backend retrieves the access token and tenant key from Tango’s embedded widget endpoint. The configuration script will also be placed in the head section of the page.

<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 uses window.postMessage for lifecycle and error events, and supports a language update from the parent.

Widget → Parent

Listen for initialization and error messages.

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

Parent → Widget (Language Update)

<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