This document will walk through how an invoice is created inside the RoadSync application, and how that process correlates with how you create an invoice using the Checkout API. We will walk through each step and provide helpful tips & recommendations on how to build your API solution.
This particular document does not get into some of the more detailed, technical specifications, but is meant to provide a walkthrough of how associates create invoices today while including some specific notes about how this impacts API implementation.
Please send us feedback!
If you notice that something doesn't quite line up with your expectations, or you have some suggestions for us to add, please don't hesitate to reach out or suggest an edit.
In the RoadSync application, the user would typically navigate to the "Invoices" tab. On this page, there is a button to create a new invoice ("+ New Invoice").
When that button is clicked, we open the first step of our Invoice Builder. In this step, the associate is asked to provide the driver's carrier and the driver's phone number or email. This is requested so that the associate will be able to text or email the Remote Checkout link to the driver.
The Remote Checkout link refers to the link that allows the driver to complete their payment from their own device instead of the associate having to type in any numbers themselves. This is beneficial for staying safe amidst the pandemic, but also to avoid any sensitive data being shared.
API Implementation Note
It is highly recommended to include a driver carrier and either the driver's phone number (for SMS) or email upon creating an invoice as this will assist the associates in locating the invoice once it has been created via the API.
A potential scenario is that an invoice has been created via the API, but now the associate may not understand how to find that API later on. If they can search via the driver's carrier or the driver's phone number, that will help them find the right invoice quickly.
An alternative to creating the invoice with the driver's carrier and or driver's contact information is creating the invoice with custom field values. Read more on that below.
The next step contains custom fields & corresponding values that are completely optional, and your organization may not have these configured in RoadSync.
Most organizations using RoadSync do utilize custom field values. When configuring these fields in the application, you can choose from a few different data types.
- Email (checks for email formatting)
- Phone number (checks for phone number formatting)
- Dropdown menu (string values)
There is also the configuration option to decide whether the custom field is required for invoice creation, or is optional.
API Implementation Note
If a location has custom fields that are required for invoice creation, you will want to ensure you are sending the appropriate values when creating the invoice via the API.
Sending incorrect information may result in a failure for creating an invoice, and the correct information will need to be resubmitted.
The custom field values may also serve as a way for associates to identify invoices that have been created. Many organizations will use PO numbers, appointment numbers, or other unique data values for this.
The next step is typically where the associate selects the payment method that the driver will be using. This is an important step when it comes to the Checkout API because the Checkout API only supports the Remote Checkout payment method.
The Checkout API allows the associate to trigger the Remote Checkout link to be sent to the driver to the associated phone number or email. So, it is important that this is the only payment method attempted via the Checkout API.
The following step is where the specific products or items are added to the invoice. The products and items available to add via the API will depend on the configuration for each location.
This means that if one of your RoadSync locations has a product called "Late Fee" but the other locations do not have that same product, the invoice creation will likely fail. You will need to ensure the proper products are configured inside of your RoadSync locations. Please feel free to contact our support team for assistance with this.
API Implementation Note
It is recommended for the associates to have simple access to what products they are able to add when creating a particular invoice, but only if they are given the option to adjust the products. If products are automatically added and calculated based on other data provided, then the associate may not need visibility into that.
Based on the current usage of our different product types, many associates take advantage of the "Other" product type where the associate can designate a name for the product and a price for the product. This particular product type would allow you to get around having all the different potential charges configured inside of RoadSync.
This means you could tell the API you need to add a charge using the "Other" product type and provide the name and price. This name and price you provide could be different for every single invoice versus sticking to the same set of products each time. If you use the configured product types, such as "Item" or "Service", then you would not have the same customization flexibility.
With this next step, the associate would typically double-check the driver's contact information (phone number or email) and invoice amounts. Once confirmed, the associate would click "Send to Recipient" and this is what triggers the Remote Checkout link to be sent to the driver.
At this stage, the Remote Checkout link has been sent to the driver for payment. When implementing the Checkout API, you will want to be checking at your desired cadence to determine if the payment has been completed.
You do also have the ability to pull a list of invoices that have not been paid but have been sent for payment. This will allow visibility into which invoices the associate may still be waiting to have completed. This could also be used for managers or accounting to monitor how many invoices are getting missed.
Updated 12 months ago