DIM API

This page will showcase the various methods, events and errors you can expect with DIMs

Callbacks Overview

Here's a breakdown of the callbacks on each DIM:

MethodExplanation
onSuccessThis callback method is invoked when the drop-in experience has fulfilled its purpose, such as when a user has successfully authenticated their loan account in the Connect drop-in module. At this point, we pass the necessary data as a method parameter and proceed to close the drop-in module. *Please note that adding onSuccess to some modules that do not support the method can cause unintended user experiences, for modules such as interest-rate-monitoring please avoid leveraging the onSuccess method.
onLoadYou can provide a callback function on the configuration object that will be invoked when the drop-in module has finished loading. This function will serve as a notification that the module has successfully loaded.
onExitThe onExit callback function is triggered when you use the close navigation button located at the top right of the page to close the drop-in module. The close button is an optional feature that you can enable by setting the 'showExitNavigation' property to 1 in the dropinConfig object.
onEventThe onEvent callback function is used to notify you of important events that occur throughout the lifetime of the drop-in experience. This callback function includes a method parameter that contains useful information about each event, so that you can stay informed about the events that matter most to you.
onErroronError callback is called when dropin module throws an error. You can leverage this callback to do necessary handling on your side.
onResizeThe onResize callback function is triggered whenever the size of the drop-in module changes due to events such as page resizing. This function provides the height and width of the drop-in module document, which enables you to customize the experience for different devices. Currently, our drop-in modules will switch to a mobile experience when the screen width is 768 pixels or less.
onSettledThe onSettled callback function is triggered once the drop-in module has completed all of its API requests and has finished loading, indicating that it is ready for the user to begin interacting with it.
pageChangeThe onPageChange callback function is triggered whenever the user navigates from one page to another within the drop-in module.

The callbacks that present on each DIM are listed in this table:

ModuleonSuccessonLoadonExitonEventonErroronResizeonSettled
loan-servicers-login
precision-pay
loan-pal
loan-list
transaction-history
student-loan-refi
auto-refi
personal-refi
auto-debit
debt-connect
identity-connect
credit-card-update
prequal
interest-rate-monitoring
balance-transfer

Errors

Here are the error events you can expect to see when the onEvent callback is invoked:

ErrorExplanation
DROPIN_CONTAINER_NOT_PASSEDOccurs when an element id is not passed.
DROPIN_CONTAINER_UNAVAILOccurs when the dropin container element doesn't exist.
DROPIN_TOKEN_UNAVAILOccurs when a token isn't passed.
DROPIN_LOAD_FAILOccurs when a dropin module fails to load, due to invalid token or other config related values.
PAYMENT_FAILOccurs when a payment scheduling api fails.
SUBSCRIPTION_FAILOccurs when a subscription save api fails.
API_TIMEOUTOccurs when an api call exceeds 120 seconds.
OPEN_METHOD_DUPLICATE_CALLOccurs when there is a duplicate call to handler.open method.
EXIT_CALLBACK_UNAVAILOccurs when an exit callback function is not provided and the onExit callback is invoked by the dropin.
SUCCESS_CALLBACK_UNAVAILOccurs when a success callback function is not provided and the onSuccess is invoked by the dropin.
DIM_UNAVAILABLE_OUTAGEOccurs when a dropin module server is not available.
INVALID_MODULE_NAMEOccurs when an invalid module name is passed.
DIM_ERROROccurs when there is an unexpected error in the dropin.
INVALID_TOKENOccurs when an invalid token is passed.
EXPIRED_TOKENOccurs when a token is expired upon request sent or the expiry time has elapsed for that token.

Common methods

onLoad

onLoad(metadata){
    // your code
}

// metadata
{
    'eventName': 'DROPIN_LOAD',
    'message': `${dropin} dropin module loaded.`
}

onExit

onExit(metadata){
    // your code
}

{
    'eventName': 'DROPIN_EXIT',
    'message': 'Drop in Module Closed.'
}

onError

onError(metadata) {
	// your code
}

{
    'eventName': '{eventName}',
    'message': '{message}',
    'metadata': {
        // details related to error
    }
}

onResize

onResize(metadata){
    // your code
}

{
    'eventName': 'DROPIN_RESIZE',
    'message': 'Dropin window size changed.',
    'metadata': {
        'height': 'height of dropin document', // in pixels like 786
        'width':  'width of dropin document' // in pixels like 500
    }
}

onEvent - Common use cases

AUTH_EXPIRE

The onEvent method is commonly triggered when a user's credentials have expired or been updated, known as the AUTH_EXPIRE event. This method is used by all dropin modules except for the connect dropin module. In addition, the metadata includes the noValidLoan and reauthenticateAccounts attributes. The noValidLoan attribute indicates whether the user has any valid loan accounts, while the reauthenticateAccounts attribute provides an array of loan accounts that require re-authentication.

When a consumer subscribes to this event and it is triggered, we send a callback to the consumer and unmount the dropin module. This allows the partner to provide their own re-authentication experience. If the consumer does not subscribe to this event, our default screen is displayed and the user goes through the re-authentication flow to authenticate their account.

CONNECT_LOAN_TO_CONTINUE

The CONNECT_LOAN_TO_CONTINUE method is triggered when a user does not have any loans. This method is used by all dropin modules except for the connect dropin module. In addition, the metadata includes the userInfo object.

onEvent(metadata){
    // your code
}

{
    'eventName': 'AUTH_EXPIRE',
    'message': 'Credentials Expired/Updated.',
    'metadata': {
        'extUserId': '{extUserId}',
        'shouldReconnect':  true,
        'noValidLoan': false,
        'reauthenticateAccounts': "<array of accounts needing re-auth>"
    }
}

{
    'eventName': 'CONNECT_LOAN_TO_CONTINUE',
    'message': 'Connect loan to use this Dropin.',
    'metadata': {
        'extUserId': '{extUserId}',
        'userInfo': '<userInfo>'
        "dimExitInitiated": true
    }
}

onSettled

onSettled {
  triggerType: 'settled',
  instanceId: 'spinwheel-dim',
  messagedata: {
    eventName: 'DIM_SETTLED’,
    message: '{{module name}} Dropin Load complete’
  }
}

To learn more about our debt APIs and 1-click solutions, visit spinwheel.io.