Skip to main content

Building a complete billpay solution

note

This guide is for those wanting to build a modular solution and already have bills/invoicing in their application.
If you just want to use a hosted or redirect solution, you do not need to implement anything in this guide.

While adding a billpay button to your application is quite simple if you follow the Add a pay bill button guide building a full comprehensive solution requires setting up more integration points.

A typical bill pay application needs the following:

  • Adding a schedule payment button next to unpaid bills in your system
  • Keeping bill status in sync with a payment's lifecycle
  • Adding a view payment button next to a scheduled/paid bill
  • Freezing changes to a bill that is scheduled
  • Updating melio when user changes role or is removed
  • Adding a link to the payments dashboard
  • Providing deep links to view a specific payment for use in emails

Depending on what capabilities are available for you product, you might also need to handle the following:

  • Support partial payments

Adding a schedule payment button next to unpaid bills in your system​

You need to identify which bills your users have area already paid/scheduled and only add a pay bill button to unpaid bills.
You can follow the guide in Add a pay bill button guide.

Keeping bill status in sync with a payment's lifecycle​

After a bill is scheduled and associated with a payment, that payment goes through several stages before completing.

This is exposed on the payment's status field, which is available both in the Get Payments Api and via the PaymentUpdated webhook event .

Applications typically do the following for payments in the following statues:

  • scheduled/in_progress/blocked - mark the bill as "scheduled" or "in-progress" and add a view payment link for additional details
  • completed - mark the bill as completed.
  • failed - mark the bill as failed and show a view payment link for fixing or canceling the payment
  • canceled - transition the bill back to unpaid and allow another payment to be scheduled

Adding a view payment button next to a scheduled/paid bill​

When a payment for a bill exists it is vital that the user be able to view the payment in Melio.
Melio includes a lot of functionality inside the view payment page - including the ability to resolve common risk and transaction failures, show more granular details about the payment and support actions such as approval workflows if enabled.

Freezing changes to a bill that is scheduled​

When a bill has a non-canceled associated payment, it should be frozen and not modifiable.
Once a payment is scheduled Melio does not accept any changes to the bill.
If a bill is modified at the partner and not in Melio discrepancies can arise that can cause unforseen errors.

Updating melio when user changes role or is removed​

When a user changes roles inside a company you need to call Update Account Api, and when it is no longer has access to a company - Remove Account Api

This is required to avoid situations where emails for a company are sent to users who are no longer part of the company or are in a role where those emails make no sense.

Support partial payments​