Embeddable User Interface (Client-facing Invoice)

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.

While the Invoice Dashboard provides your users with what they need to create and manage invoices, the Client-facing Invoice allows your users' clients to view and pay their invoices.

1. How it works

When your user sends out an invoice, their client will receive an email with a link to view/pay the invoice. When the client presses that link, they will be redirected to a URL of your choosing, with a clientInvoiceKey appended. When the client lands on that URL, you can follow the steps below to render the Client-facing Invoice.

2. Adding the Client Invoice to your app

Contact us directly at [email protected] to let us know your desired URL structure for the Client Invoice. For example, you might use something like:
Development Environment: https://dev.myproduct.com/invoices/{clientInvoiceKey}
Production Environment: https://app.myproduct.com/invoices/{clientInvoiceKey}

When the client lands on https://app.myproduct.com/invoices/{clientInvoiceKey}, you should:
a) parse out the clientInvoiceKey from the URL
b) render the Client Invoice, as described below

To render the Client Invoice, you will also need to provide the elementId parameter, which is the HTML id of the main <div> where you would like the Client Invoice to render. Then, you simply need to invoke the following line of javascript:

Hurdlr.renderClientInvoice(elementId, { 
  clientId: $(client_id),
  environment: "SANDBOX",
  clientInvoiceKey,
  paymentCallbackFunction: myClientInvoiceCallback
});

3. Allowing the user's client to pay an invoice (payment processing)

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 passing in a paymentCallbackFunction into the Hurdlr.renderClientInvoice() function, the Hurdlr SDK will invoke the callback function you provide when the user's client performs key actions, such as pressing a CTA to pay the invoice, so that you can route the user to the proper place within your own UI.

When the "pay invoice" CTA is clicked, we recommend you take the following actions:
a) route the user to your payment capture flow
b) process the payment for the specific invoice (using data.invoiceId) via your payment processor
c) alert the Hurdlr API that the payment was processed

An example implementation of myClientInvoiceCallback is shown below:

var myClientInvoiceCallback = ({ type, invoiceId, invoiceName, invoiceBalance }) => {
  switch (type) {
    case Hurdlr.PAY_INVOICE:
      // route user to my existing payment capture flow
      // process the payment with my payment processor, for invoice with id===invoiceId
      // once complete, POST the payment to /payment
      break;
  }
}

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.