Wolfe Card Linking UI

Introduction

Flow Diagram

Environments

Session Creation

Partner Gift Page Assets

Instantiate

UI Configuration Options

Test Data

Events

Exposed Methods

Full Example

Introduction

Wolfe provides partners with a prebuilt Card-Linking UI component for gift recipients to manage all necessary operations related to linking a gift to a payment card.

The general integration flow works is:

  1. Set-Up

    1. Place script tag on all pages that will render the Card Linking UI

    2. Add DIV component to page

  2. Runtime

    1. Upon page request, partner create session with server-to-server call on partner server via Wolfe API. See details below.

    2. After page load, call window.wolfe.link.instantiate() to ready the UI for user interaction

Back to Top

What are you getting?

Below depicts a simple gift being linked to a redemption account.

Activate doc image
Link success doc image
Gift details doc image

Back to Top

Environments

Wolfe provides two environments to integrate the Link UI components.

Sandbox

The sandbox URL is: https://card-link-sandbox.wolfe.com

Production

The production URL is: https://card-link.wolfe.com

Contact Wolfe to create sandbox and/or production environment credentials.

Back to Top

Session Creation

A session connects you with the Wolfe API and the gift. These sessions expire after 15 minutes. Session create API calls must be made server-to-server to protect the secret partner key and company ID.

POST https://card-link-sandbox.wolfe.com/partner/{companyId}/card-link-session Headers: { 'accept': 'application/json', 'partner-key': 'Your partner id', 'tenant-id': 'Your tenant id', }, body: { gift_id: "your gift ID" }

Once a session expires, the partner determines how a new session is generated. An event is emitted from the UI (noted below) so the partner can listen and offer a message to the user indicating the session has expired and prompt the user to refresh the page.

Back to Top

Partner Gift Page Assets

To include the UI components on your site, you must include 2 assets:

  1. Our script

    • Sandbox URL: https://card-link-sandbox.wolfe.com/script.js

    • Production URL: https://card-link.wolfe.com/script.js

  2. A DIV with data attribute<div data-wolfe-link="" />

Depending on your options, the UI will be displayed inside the DIV or as a dialog.

Back to Top

Instantiate

  1. Upon page ready, call window.wolfe.link.instantiate()

  2. Include a settings parameter. All settings are listed below.

  3. If you are using variant: "dialog":

    • you will need to listen for componentReady event. Once this fires, the partner parent webpage will enable a button which when clicked, will open the dialog.

    • Upon button click, call window.wolfe.link.open()

Instantiate Example

window.wolfe.link.instantiate({ giftId: '*****************', companyId: '*****************', sessionId: '*****************', variant: 'dialog', cardInputVariant: 'Select', includeGiftDetails: true, excludeSuccessScreens: [], successButtonLabel: 'Gift Details', udf: { email: 'admin@website.com', labelPlacement: 'Inside', primaryColor: '000000', privacyPolicyUrl: 'https://www.website.com/privacy-policy', termsOfServiceUrl: 'https://www.website.com/terms-of-service', bodyFontFamily: 'Roboto', headingFontFamily: 'Roboto', legalFontFamily: 'Roboto', partner: { company: { name: 'My Company Name, LLC', }, }, }, css: {}, })

Back to Top

UI Configuration Options (* indicates required option)

* Required

The gift ID

Property name: giftId

* Required

The company ID provided from Wolfe

Property name: companyId

* Required

The session ID generated connecting the partner, API, and gift

Property name: sessionId

Describes the appearance/interaction with the UI Link components.

Property name: variant

Valid values: dialog

Default: dialog

Choose the option for the credit card input whether its a selection dropdown or radio buttons.

Property name: cardInputVariant

Valid values: Select Radio

Default: Select

Option to include the Merchant Name, Original Gift Balance and Remaining Gift Balance

Property name: includeGiftDetails

Default: true

Option to exclude certain Success Screens

Property name: excludeSuccessScreens

Valid values: activateCard deactivateCard deleteCard

Default: []

Option to change the button text on the success screen after linking a gift.

Property name: successButtonLabel

Default: Gift Details

This will determine the scope of the Link component.

Property name: scope

Valid values: full

Default: full

* Required

The partner support email provided to recipients in the card-linking disclaimer text.

Property name: udf.email

User Defined Field: The option to include field input labels inside the field border, or outside and above the field border.

Property name: udf.labelPlacement

Default: Inside

Valid values: Inside Outside

User Defined Field: The color used throughout the UI Link components as the primary color.

Property name: udf.primaryColor

Valid values: any 6 character hex code

Example: ff0000

* Required

The privacy policy URL used for legal disclaimers' text

Property name: udf.privacyPolicyUrl

* Required

The terms of service URL used for legal disclaimers' text

Property name: udf.termsOfServiceUrl

The font family used for body text throughout

Property name: udf.bodyFontFamily

Default: Roboto

Valid values: Roboto Open_Sans Montserrat Roboto_Condensed Noto_Serif Dosis

The font family used for headings throughout

Property name: udf.headingFontFamily

Default: Roboto

Valid values: Roboto Open_Sans Montserrat Roboto_Condensed Noto_Serif Dosis

The font family used for legal text throughout

Property name: udf.legalFontFamily

Default: Roboto

Valid values: Roboto Open_Sans Montserrat Roboto_Condensed Noto_Serif Dosis

The partner name used throughout the Link Component

Back to Top

Test Data

To test in sandbox environment, you can use this data:

Card number

4242-4242-4242-4242

Name on card

John Doe

Card expiration

12/26

Back to Top

Events

The Card-Linking UI emits various events so partners can direct user actions as desired.

Example:

DIV.addEventListener('componentReady', e => { /* Do something here with the event, such as enabling buttons */ })

componentReady

This event fires after window.wolfe.link.instantiate is called and the UI is ready.

sessionExpired

This event fires for any time a user request to API results in 401 Not Authorized. This can happen if the session has timed out after 15 minutes, or the user has taken certain actions which invalidate the session, having it marked as “used”. This event is useful for partners to handle this situation, where the partner needs to generate a new valid session and re-instantiate the UI.

dialogOpen

This event fires every time a dialog is requested to be opened.

dialogClose

This event fires every time a dialog is requested to be closed.

cardLinkStarted

This event fires every time a user attempts to link a card to a gift. This event does not guarantee the link is successful. This event happens for new and existing cards.

cardLinked

This event fires every time the card is successfully linked

cardLinkSuccessClose

This event fires every time the “Card Link Success” page is requested to be closed.

cardLinkErrorClose

This event fires every time the “Card Link Error” page is requested to be closed.

cardUnlinked

This event fires every time the card is successfully unlinked

cardEnrollStarted

This event fires every time a new card is attempted to be enrolled. This event does not guarantee a successful enrollment.

cardEnrolled

This event fires every time a card is successfully enrolled. This only happens for new cards.

cardUnenrolled

This event fires every time the card is successfully unenrolled/deleted

cardUnenrolledSuccessClose

This event fires every time the “Card Unenroll Success” dialog is requested to be closed.

error

This event fires as a general error event for API errors

deactivateCardSuccessClose

This event fires every time the “Deactivate Card Success” page is requested to be closed via button click.

Back to Top

Exposed methods

wolfe.link.instantiate()

This method will load the iframe inside any DIV with data attribute [data-wolfe-link]

wolfe.link.open()

This method will open the dialog if variant: "dialog" setting is set

wolfe.link.destroy()

This method will reset all iframes and event listeners for content inside the DIV [data-wolfe-link]

Back to Top

Full Example

import {useEffect, useRef, useState} from "react"; import Script from 'next/script' import axios from "axios"; const CardLinkedGiftingExample = ({ sessionId, companyId }) => { const containerRef = useRef(); const [linkReady, setLinkReady] = useState(false) useEffect(() => { setUpEventListeners(); }, []) const setUpEventListeners = () => { containerRef?.current?.addEventListener('linkReady', () => { /* Do something here with the event, such as enabling buttons */ setLinkReady(true); }) } const handleClick= () => { /* Upon user interaction, open the dialog */ window.wolfe.link.open() } const handleScriptLoad = () => { /* After script is loaded and ready, instantiate the UI components */ window.wolfe.link.instantiate({ giftId: '*****************', companyId: '*****************', sessionId: '*****************', variant: 'dialog', cardInputVariant: 'Select', includeGiftDetails: true, excludeSuccessScreens: [], successButtonLabel: 'Gift Details', udf: { email: 'admin@website.com', labelPlacement: 'Inside', primaryColor: '000000', privacyPolicyUrl: 'https://www.website.com/privacy-policy', termsOfServiceUrl: 'https://www.website.com/terms-of-service', bodyFontFamily: 'Roboto', headingFontFamily: 'Roboto', legalFontFamily: 'Roboto', partner: { company: { name: 'My Company Name, LLC', }, }, }, css: {}, }) } return ( <div> <Script onReady={handleScriptLoad} src={'https://card-link-sandbox.wolfe.com/script.js'} /> <button disabled={!linkReady} onClick={handleClick}>Link gift to card</button> <div data-wolfe-link={''} ref={containerRef} /> </div> ) } export default CardLinkedGiftingExample; export async function getServerSideProps(ctx) { } // tenantId, partnerId, and companyId shall be kept secret on server side const tenantId = '22841ad1-d84d-4f51-bcd3-4398b3e278c9'; const partnerId = '5443c42b2fb562c1468c3e4e016991971f94e666873e033b60c523626500776e'; const companyId = '41bf20de-e38c-4794-a86c-41b311f89c7f'; // giftId is determined from partner webpage URL const giftId = '578299b2-1572-43ab-a2a7-7f130122fd60'; let sessionId = ''; try { const client = axios.create({ baseURL: 'https://gift-sandbox.wolfe.com', headers: { accept: 'application/json', 'partner-key': partnerId, 'tenant-id': tenantId } }); /* Generate a session ID on partner server */ const response = await client.post(`/partner/${companyId}/card-link-session`, { gift_id: giftId }); sessionId = response.data.data.session } catch (e) { console.log('error', e) } return { props: { sessionId, companyId } } }

Back to Top