Skip to main content

Hosted Fields Checkout

Introduction​

Hosted Fields enables easy integration of a credit card payment method while maintaining control over the form UI.

Features
  • Light Integration: Minimal setup required.
  • Secure Payment: PCI-compliant.
  • Customizable: Configure styles and translations.

Prerequisites​

Ensure you have:

  • Basic JavaScript, HTML, and CSS knowledge.
  • An active credit card payment method.
  • A Purse API key.
  • A client session.

Limitations​

caution

Hosted fields are only supported with vault credit cards.

Quick Start Guide​

Step 1: Installation​

First, you need to add UpStreamPay to your frontend by including the appropriate script in your HTML.

<script src="https://cdn.purse-sandbox.com/dropin/v3-latest/purse.js"></script>

This script adds UpStreamPay to the window object, allowing you to use it throughout your project.

Replace WIDGET_VERSION with the version you want to use.

Widget Versioning
  • v3-current → Stable version (recommended for production).
  • v3-next → Release candidate (preview of the next version).

Step 2: Build The Form Markup​

Hosted Fields does not generate form labels. You must provide them using these IDs:

  • PAN field: usp-pan-input
  • CVV field: usp-cvv-input
  • Expiry field: usp-expiry-input
  • Holder field: usp-holder-input

Below is an example form structure of what you should have:

<form>
    <div class="form-group">
        <label for="usp-holder-input">Holder Name</label>
        <div id="holder-placeholder"></div>
    </div>
    <div class="form-group">
        <label for="usp-pan-input">Card Number</label>
        <div id="card-number-placeholder"></div>
    </div>
    <div class="form-group">
        <label for="usp-cvv-input">CVV</label>
        <div id="cvv-placeholder"></div>
    </div>
    <div class="form-group">
        <label for="usp-expiry-input">Expiry Date</label>
        <div id="expiry-placeholder"></div>
    </div>
    <button id="pay-button">Pay</button>
</form>

Step 3: Initialize the Checkout​

Initialize the Widget​

Start by building the widget manager using the widget.data field from your client session:

<script language="javascript">
    const CheckoutManager = await UpStreamPay
            .WidgetManager
            .buildForWidgetData(clientSession.widget.data);
    // build and mount widget interface using widget manager
</script> 
await manager.setPaymentSession(session);

const widget = manager.createWidget({
    name: "my-checkout-form",
    interface: "HOSTED_FIELDS",
    preSelectMethod: 'creditcard',
    payload: {
        hostedFields: {
            cvvTarget: "cvv-placeholder",
            panTarget: "card-number-placeholder",
            holderTarget: "holder-placeholder",
            expTarget: "expiry-placeholder"
        }
    }
});

widget.mount();

Step 4: Customize Field Appearance​

Use the stylesheet object to customize the checkout's appearance. Refer to the full style variables reference.

manager.createWidget({
    name: "hosted_fields",
    interface: "HOSTED_FIELDS",
    preSelectMethod: "creditcard",
    ui: {
        layout: {
            vaultBrandSelectionMode: "inPanInput"
        },
        stylesheet: {
            overrides: {
                'usp-input-text-color': '#616E7C',
                'usp-input-border-color': '#7B8794',
                'usp-input-height': '24px',
                'usp-input-border-radius': '8px',
                'usp-error-color': '#BA2525'
            }
        }
    },
    payload: {
        hostedFields: {
            "cvvTarget": "cvv-placeholder",
            "panTarget": "pan-placeholder",
            "holderTarget": "holder-placeholder",
            "expTarget": "expiry-placeholder"
        }
    }
});

Supported Brands​

For co-branded cards, users can choose their preferred brand. Define a container and pass its ID to the brandsTarget hosted fields option.

InPanInput​

Displays an inline list of brand icons.

manager.createWidget({
  name: "hosted_fields",
  interface: "HOSTED_FIELDS",
  preSelectMethod: "creditcard",
  ui: {
    layout: {
      vaultBrandSelectionMode: "inPanInput"
    },
    stylesheet: {
      overrides: {
        "usp-brand-button-border-width": "1px",
        "usp-brand-button-border-color": "#CCC",
        "usp-brand-button-bg-color": "#F5F5F5",
        "usp-brand-button-padding": "2px",
        "usp-brand-button-border-radius": "5px",
        "usp-brand-button-active-border-color": "green",
        "usp-icon-s-size": "24px",
        "usp-spacing-xs": "8px"
      }
    }
  },
  payload: {
    hostedFields: {
      "brandsTarget": "my-brand-container"
    }
  }
});

Other Modes​

Other supported brand selection modes:

  • Select Mode: Displays a dropdown.
  • Hypertext Mode: Displays text links.
  • None: No brand selection UI.

For custom brand icons, refer to the documentation.

Save Cards (Tokenization)​

Enable users to store card details for later:

await manager.createWidget({
  name: "hosted_fields",
  interface: "HOSTED_FIELDS",
  preSelectMethod: "creditcard",
  payload: {
    hostedFields: {
      saveTokenTarget: "save-token-placeholder"
    }
  }
});

Handling Validation Errors​

Subscribe to widget events to manage validation manually:

const handleDisplayErrors = (event) => {
  if (event.code === "HOSTED_FIELDS_CARD_NUMBER_ERROR") {
    // display error
  }
  if (event.code === "HOSTED_FIELDS_CARD_NUMBER_VALID") {
    // hide error
  }
};

manager.subscribe(handleDisplayErrors, ['widget_hosted_fields']);
warning

Omitting required fields will throw an error. Contact support for more information on methods.

Handle Widget Errors​

danger

Possible errors:

  • Expired session → SOURCE_IS_EXPIRED
  • Already validated session → CHECKOUT_API_INIT_FAILED
  • Method initialization failure → CHECKOUT_API_INIT_FAILED

Final Notes​

  • Ensure proper styling for better UX.
  • Test error cases before going live.