Support Services

BillPayIt Integration Guide

Overview

BillPayIt enables billers to collect bill payments from their customers electronically by uploading a bill definition file that describes the relevant bill information. The biller then directs customers to their BillPayIt portal website where customers can locate and pay their bills. As customers pay these bills, Forte provides a nightly bill payment file showing this payment activity. Billers can then update the bill payment status by uploading a new bill definition file.

Forte uses a secure FTP or web interface to transfer the bill definition and bill payment files.

Billing Lifecycle Dates

The BillPayIt lifecycle includes the following key dates:

  • Presentation Date 
    Billers can upload bills before the bills become available for customer payment. Bills only become visible to the customer on or after the presentation date.
  • Due Date 
    BillPayIt applies late fees when the biller passes this required field.
  • Expiration Date 
    The customer can no longer pay or view bills after the expiration date. Billers can request that their expired bills remain visible on the site for a period of time.
  • Paid in Full Date 
    If a biller wants to indicate that a bill has been paid in full, the biller can send an update to the bill that notes the date it was paid. Once a bill has been paid in full, BillPayIt no longer allows payments against the bill.
  • Last Payment Date 
    The last payment date allows billers to reflect the payment status information from their own bill systems. This field is required if you want to accept partial payments towards bill balances. When a customer makes a payment through the portal, it is considered a pending payment until the biller indicates acceptance of the payment. To indicate acceptance, the biller updates the next bill upload file with a modified paid amount and sets the last payment date by adding one day to the date when the customer made the payment on the portal. If the biller does not provide a last payment date, BillPayIt uses the date the bill was last modified.

Ordered Bill Payment

If a biller wants to require the customer to pay a series of bills in sequence, Forte can relate these bills by setting a shared Grouping ID. These bills must then be fully paid in the order of their due dates. For example, a property tax agency can relate quarterly tax payments on a parcel by placing the parcel number into this grouping field. The parcel owner must then pay each quarter in sequence by their due date.

When adding a grouped bill, BillPayIt ensures that all previous bills in the group have been paid in full. If not, it prompts customers to add these previous items to their carts and pay them in full.

Bill Amounts

Use the following bill amounts when collecting payments:

  • Due Amount 
    The total amount of the bill. This field should not be modified unless the biller is reducing the bill.
  • Paid Amount 
    The dollar amount that the biller reflects as "paid" against the bill. This field starts at $0 and increases as the customer makes partial payments through either the bill portal or via outside channels.
  • Minimum Amount 
    If the biller allows for partial payments against a bill, this amount is the minimum amount allowed. When set to 0, no partial payment is allowed.
  • Late Fee Amount 
    After the due date passes, BillPayIt adds this amount to the due amount as a separate line item that must now be paid against the bill.

BillPayIt Portal

Search

To make bills easy to find on their bill portal, billers can configure elements of the bill to be searchable through an exact or similar character match.

For example, a utility company can require that an invoice number be entered exactly as shown on a bill or it can use a name-based search that allows the search query "John Public" to be a match for "John Q. Public." Billers should work with their integration coordinator to determine how to configure this feature for their organization.

Billers can configure the following elements to be searchable:

  1. Customer Name
  2. Customer ID
  3. Bill Number
  4. Unique Bill ID
  5. Street Address
  6. Any of the four biller-defined fields

Labels

To assist customers in finding and understanding their bill, billers can rename fields through the portal. For example, a biller may want the "Bill Number" to be displayed in the portal as "Invoice Number."

All of searchable fields listed in the sections above can be relabeled, including "Late Fee" and "Invoice Date."

Bill Definition File

Billers use the bill definition file to create and update bills in their portal. This file is keyed on the Unique Bill ID (UBID). All bills are unique to the biller based on this alphanumeric ID field. When BillPayIt receives a bill with a new UBID, it creates a new bill. If the biller uses an existing UBID, BillPayIt updates that bill with all of the information contained in the new record. 

File Naming

Use the following naming scheme for your file:

<B><Format><Revision><TransmitterID>.<Ready Indicator><File Count>

For example, BSTD112345.u01 where

  • B indicates a bill definition file
  • STD indicates the format (max length: 3). STD is the standard format.
  • 1 indicates the format revision number (max length: 1)
  • 12345 is the biller-assigned Transmitter ID used for FTP login. Group multiple billers together with a shared Transmitter ID.
  • .u indicates upload files. After processing the file, the biller must rename the file and change this field to .b.
  • 01 - indicates the daily file counter. The value 01 indicates the first file upload of the day.

File Format

A Standard Revision 1 File Format is a single-line-per-record CSV format with support for the following quoted text qualifiers: 

FieldDescriptionRequired?
UniqueBillIDA unique value representing the bill in this recordRequired
MerchantIDThe billers's Forte-assigned merchant IDRequired
PresentationDateThe date the bill becomes available for customer viewingOptional
DueAmountThe total amount due based on due dateRequired
MinimumAmountMinimum amount a customer must payOptional
CurrencyCodeThe alpha code from 4217; this field must be "USD"Required
DueDateThe date the bill becomes overdueRequired
LateFeeThe late fee applied to the bill after the due dateOptional
ExpirationDateThe expiration date of the bill. This field defaults to 90 days if no value is passed in with the file.Optional
PaidAmountThe amount the customer has already paid against due amountOptional
LastPaymentDateThe date of the last payment accounted for in the PaidAmount field plus one day (e.g., if the customer submitted the payment via the portal on 8/21, the payment date would be 8/22 or greater in the next file upload). NOTE: This field is required for merchants who accept partial payments toward bill balances.Optional
PaidInFullDateThe date of the final payment on the bill's remaining balanceOptional
CustomerNameThe customer's nameRequired
ContactNameThe customer's contact name (if the customer is a company)Optional
StreetAddressThe first line of the customer's street addressOptional
StreetAddress2The second line of the customer's street addressOptional
CityThe customer's cityOptional
StateProvinceThe customer's state or provinceOptional
PostalCodeThe customer's zip/postal codeOptional
CountryThe customer's countryOptional
PhoneThe customer's phone numberOptional
EmailAddressThe customer's email addressOptional
CustomerIDThe biller's Customer ID or Account NumberRequired
BillNumberThe bill or invoice numberOptional
BillDateThe bill dateOptional
TermsThe terms of the billOptional
MemoAny memos associated with this billOptional
GroupingIDA field used for payment orderingOptional
MDF1Merchant-defined field #1Optional
MDF2Merchant-defined field #2Optional
MDF3Merchant-defined field #3Optional
MDF4Merchant-defined field #4Optional

Merchant-Defined Fields

The format options for the Merchant Data fields (MDF1MDF4) are String, Amount, Date, and URL. Billers who want to have a PDF invoice displayed need to put the URL of the invoice associated with the outstanding payment in one of the following merchant-defined fields: MDF1MDF2MDF3, or MDF4. If any of the merchant-defined fields contain a URL, a PDF icon displays in the right-most column. The user can then click on the PDF icon to see the contents of the invoice. 

Bill Payment File

The bill payment file communicates bill payment events to the biller. The standard file format echos back the same format above but appends two new fields at the end of the bill record to indicate payment status and payment amount.

Use one of the following values to populate the Payment Status field:

  • A - Authorized. The customer has attempted the payment, but funds may not yet have moved.
  • F - Funded. The payment funded into the biller account.
  • C - Chargedback. A customer has initiated a chargeback on a credit card payment.
  • U - Unchargedbacked. A chargeback has been reverted.
  • Z - Unfunded. An ACH transaction has been taken back from the biller account
  • R - Returned. An ACH transaction was rejected

The Payment Amount is a traditional money field indicating the amount of the bill paid.

Bill Overpayment

The BillPayIt system attempts to reconcile multiple sources of information in regard to the paid amount of the bill and to enforce a correct payment amount. It accomplishes this quickly and accurately in the vast majority of circumstances. However, complex scenarios involving out-of-portal payments, partial payments, chargebacks, returns and incorrect or out-of-date "Last Payment Date" information could incorrectly result in a scenario where the BillPayIt system reflects a bill as being fully paid and thus allows no further payments against it.

For concerns that a complex payment scenario may temporarily stop payments from being made on a bill for legal or regulatory reasons, the biller should contact their integration specialist to enable bill overpayment within a specified percentage of the bill's original due amount.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.