Embeddable User Interface (Invoice Dashboard)

If you want to get up and running quickly with a proven invoicing, payment (credit card) processing, and reconciliation UX that matches your colors, fonts, and branding, then the Embeddable User Interface is your best bet.

1. Initializing the SDK

To initialize the Hurdlr SDK in your project, follow the instructions on Embedding Hurdlr's white-labelled UI.

2. Adding the Invoice Dashboard to your app

To render the Invoice Dashboard, you will need to provide the elementId parameter, which is the HTML id of the main <div> where you would like the Invoice Dashboard to render. When your user taps on your "Invoices" navigation CTA, you simply need to invoke the following line of javascript:

Hurdlr.renderScreen(elementId, 'invoiceDash');

3. Customizing the UI to match your branding

Hurdlr's API team can quickly customize the UI to match your branding. Please follow the instructions on Customizing the embedded UI to match your branding.

Some examples of customized experiences are shown below:

4. Handling key user interactions

While the Hurdlr SDK gives you a customized UI to match your branding, there are also certain parts of the user experience that we recommend your team owns as a best practice.

By registering a listener, the Hurdlr SDK will invoke the callback function you provide when users perform key actions, so that you can route the user to the proper place within your own UI.

To register the listener, simply add the following line of JS to be ran once after Hurdlr.init({...}):

Hurdlr.registerInvoiceListener(myInvoiceCallback);

The two key interactions that will invoke your callback function are:

a) the user presses a CTA to set up their payment processing
b) the user presses a CTA to refund an invoice that was already paid for through your payment processing

Continue reading below for instructions on how to handle the above two scenarios.

5. Allowing you user to set up payment processing

Now that you have registered the listener, you are ready to handle when a user wants to set up payment processing (e.g. to accept credit card payments). Whenever a user presses a CTA to set up payment processing, myInvoiceCallback will be invoked with a JSON object as the single argument.

When that CTA is clicked, we recommend you take the following actions:
a) route the user to your payment processing (or merchant account creation) flow, so they can complete their merchant setup
b) once complete, update the user's invoice setup record to set thirdPartyPaymentsEnabled to true

An example implementation of myInvoiceCallback is shown below:

var myInvoiceCallback = (data) => {
  switch (data.type) {
    case Hurdlr.SETUP_PAYMENT_PROCESSING:
      // route user to my existing payment processing setup flow
      // once complete, POST to /invoiceSetup to set { invoiceSetupComplete: true, thirdPartyPaymentsEnabled: true }
      break;
    case Hurdlr.REFUND_INVOICE:
      break;
  }
  // route back to my app's invoice dashboard screen
}

Hurdlr.registerInvoiceListener(myInvoiceCallback);

Don't hesitate to contact us directly at [email protected] should you need any help understanding how to use invoice listeners with the Hurdlr SDK.

6. Processing refunds on invoices paid via your payment processing

Now that you have registered the listener, you are ready to handle when a user wants to refund a paid invoice. Whenever a user presses a CTA to refund a paid invoice, myInvoiceCallback will be invoked with a JSON object as the single argument.

When that CTA is clicked, we recommend you take the following actions:
a) process the refund for the specific invoice (using data.invoiceId) via your payment processor
b) alert the Hurdlr API that the refund was processed, by marking the invoice as refunded

An example implementation of myInvoiceCallback is shown below:

var myInvoiceCallback = ({ type, invoiceId }) => {
  switch (type) {
    case Hurdlr.SETUP_PAYMENT_PROCESSING:
      // route user to my existing payment processing setup flow
      // once complete, POST to /invoiceSetup to set { invoiceSetupComplete: true, thirdPartyPaymentsEnabled: true }
      break;
    case Hurdlr.REFUND_INVOICE:
      // process the refund with my payment processor, for invoice with id===invoiceId
      // once complete, POST the refunded payment to /payment
      break;
  }
  // route back to my app's invoice dashboard screen
}

Hurdlr.registerInvoiceListener(myInvoiceCallback);

Don't hesitate to contact us directly at [email protected] should you need any help understanding how to use invoice listeners with the Hurdlr SDK.