Invoice Upload File Specifications

Upload File Specifications

When creating the billing presentment invoice upload file, the file must contain a header and must be in a tab-delimited format.

The header must be formatted in this fashion:

!BATCH[tab]email[tab]invoice_no[tab]enter_date[tab]expire_date[tab]account_no[tab]amount[tab]status[tab]item1[tab]cost1[tab]qty1[tab]descr1

Please Note:

  • The header line must be the first line in the file.

  • The “!” characters is required to the first character in the header line.

  • All fields are case sensitive in the header line.
Variable Required Max Size Value Notes
BATCH Mandatory 15 billpay_invoice The value for the ‘!BATCH’ column must be set to ‘billpay_invoice’
email Mandatory 80 person@place.com Set a single email address of the customer. When this email address matches the one the customer used to sign-up with, the bill will be presented to the customer.
clientid Optional 250 This may be used instead of supplying the customer’s email address. When ’email’ isn’t specified and this field is defined, we’ll use the email address from the corresponding contact listed within your Billing Presentment admin area. This value must exactly match the unique Client ID you specified for that customer within the Manage Contacts section of your Billing Presentment admin area.
invoice_no Optional 24 This is a unique invoice number for the customer’s bill. This is similar to our orderID field, but is for tracking all payment attempts against this invoice. If not defined, a unique value will be defined for you.
account_no Optional 24 This is the account number in your system. This is to help you track which account in your system the invoice belongs to. [see Special Note #5]
enter_date Optional 8 YYYYMMDD format This is the date you entered the invoice into the system. If left blank, the system will use the date you uploaded the invoice on. (This date is based on GMT)
expire_date Optional 8 YYYYMMDD format This is the date the invoice expires after. A customer may pay this bill up to the date indicated. Once this date has passed, they will be unable to pay the invoice online. If left blank, the system will set the date 1 month from the date you uploaded the invoice on. (This date is based on GMT)
amount Mandatory 10 1234.56 format This is the total dollar amount the invoice is for.
tax Optional 10 1234.56 format This is the total tax applied to the invoice.
shipping Optional 10 1234.56 format This is the total shipping fee applied to the invoice.
handling Optional 10 1234.56 format This is the total handling fee applied to the invoice.
discount Optional 10 1234.56 format This is the total discount applied to the invoice.
status Mandatory 20 open/closed/hidden/merged/paid The value of this field, will represent the type of invoice that has been uploaded. open - represents invoices which are open/unpaid. closed - represents invoices which were revoked, but can still be seen. hidden - represents invoices which the client cannot see. merged - represents invoices which were merged into another invoice. paid - represents invoices which have been paid. expired - represents open invoices which have passed its expire date.
billcycle Optional 10 number of months The value of this field will represent the number of months between each installment payment. Used in conjunction with the ‘monthly’ field.
monthly Optional 10 1234.56 format The value of this field will represent the amount charged each billing cycle. Used in conjunction with the ‘billcycle’ field.
balance Optional 10 1234.56 format This is the total amount left to be paid on the invoice. Used in conjunction with the ‘billcycle’ and ‘monthly’ fields. When omitted, will assume the total amount of the invoice. When the balance is less then the monthly amount, the system will charge only the remaining balance on the last installment payment.
datalink_url Optional 255 absolute URL to file or script Used to specify a URL to externally hosted script or file, which is related to the given invoice. [see Special Note #6] i.e. http://www.somedomain.com/somefolder/filename
datalink_pairs Optional 255 query string of name/value pairs Query string of name/value pairs to pass to the datalink URL, when the datalink URL is a script. [see Special Note #6] i.e. name=value&anothername=anothervalue&…
public_notes Optional NA Use this field to include comments/notes you want the customer to see, when they view the invoice online.
private_notes Optional NA Use this field to include comments/notes you want to privately keep on file with the invoice. (These comments/notes are not viewable by customers.)
itemX Optional 10 SKU of product Is the SKU of a product purchased. [see Special Note #2]
costX Optional 10 1234.56 format Is the per unit cost of the product. [see Special Note #2]
qtyX Optional 24 Is the number of units purchased of the product. [see Special Note #2]
descrX Optional 200 Is a short 1 line description of the product. [see Special Note #2]
weightX Optional 10 Is the per unit weight of the product in pounds.
descraX Optional 200 Is a description of second product attribute. [see Special Notes #2 & #3]
descrbX Optional 200 Is a description of third product attribute. [see Special Notes #2 & #3]
descrcX Optional 200 Is a short 1 line description of first product attribute. [see Special Notes #2 & #3]
clientname Optional 40 Customer’s name, to appear on invoice. [see Special Note #1]
clientcompany Optional 40 Customer’s company name, to appear on invoice. [see Special Note #1]
clientaddr1 Optional 40 Customer’s address line #1, to appear on invoice. [see Special Note #1]
clientaddr2 Optional 40 Customer’s address line #2, to appear on invoice. [see Special Note #1]
clientcity Optional 40 Customer’s city, to appear on invoice. [see Special Note #1]
clientstate Optional 2 Customer’s state , to appear on invoice – in 2 letter format. [see Special Note #1]
clientzip Optional 12 Customer’s zip/postal code, to appear on invoice. [see Special Note #1]
clientcountry Optional 2 Customer’s country, to appear on invoice – in 2 letter format. [see Special Note #1]
clientphone Optional 15 Customer’s phone number, to appear on invoice.
clientfax Optional 15 Customer’s fax number, to appear on invoice.
clientid Optional 250 Used for QuickBooks Customer Account # or Unique Customer ID [see Special Note #4]
consolidate Optional 3 yes When set to ‘yes’, grants client permission to consolidate ANY of their open/unpaid invoices.
alias Optional 20 Holds an alias code, ID or value, that is used under certain configurations to validate the client at time of their Billing Presentment sign-up/registration. [see Special Note #5]
shipsame Optional 3 yes When set to ‘yes’, customer’s address provided will be used for shipping address.
shipname Optional 40 Shipping name as it should appear in invoices.
shipcompany Optional 40 Shipping Company as it should appear in invoices.
shipaddr1 Optional 40 Shipping Address Line 1 as it should appear in invoices.
shipaddr2 Optional 40 Shipping Address Line 2 as it should appear in invoices.
shipcity Optional 40 Shipping City as it should appear in invoices.
shipstate Optional 2 Shipping State as it should appear in invoices. 2 Char. State Code - see Appendix for details.
shipzip Optional 14 Shipping Zip Code as it should appear in invoices.
shipcountry Optional 2 Shipping Country as it should appear in invoices. 2 Char. Country Code - see Appendix for details.
shipphone Optional 15 Shipping phone number, as it should appear in invoices.
shipfax Optional 15 Shipping fax number, as it should appear in invoices.

Notes:

Example File: Should be Tab Delimited

!BATCH email invoice_no enter_date expire_date account_no amount status item1 cost1 qty1 descr1

billpay_invoice trash@plugnpay.com 1234567898 20060614 20060714 111222333 123.00 open sku1 123.00 1 Product Description
billpay_invoice trash@plugnpay.com 1234567897 20060512 20060612 111222333 23.00 closed sku2 23.00 1 Product Description
billpay_invoice trash@plugnpay.com 1234567896 20060528 20060628 111222333 12.00 paid sku3 12.00 1 Product Description

The above example, is a simple 4 line example, which show the 3 different types of invoices. One open/unpaid invoice, one invoice which was closed and another which was paid.

If this sample was uploaded, it would create a new invoice for each invoice number which did not exist within the database. If give permission, a new invoice of the name invoice number would overwrite the record of the existing invoice.

SPECIAL NOTES:

  1. You should only need to define this, if customer is not listed within the Manage Contacts section of your Billing Presentment admin area, or if you want to update the contact information you already have on file for that email address.

    All client contact address fields MUST be present (i.e. clientname, clientcompany, clientaddr1, clientaddr2, clientcity, clientstate, clientzip, clientcountry), as we will automatically overwrite ALL of those noted fields with the contact info you have provided. If you do not define a particular field, it will simply be replaced with nothing (blanking out that particular field).

  2. To include a list of the items purchased in the invoice, four name/value pairs are required for EACH item purchased.

  3. You must contact us to enable this field, if you wish to display/edit it within your invoices.

  4. Must be specified when importing invoices generated from within QuickBooks. Please refer to QA number ‘QA20080618155941’ in the online FAQ for complete details of how to use this special ability.

  5. When merchant’s Billing Presentment service is configured to permit creation of invoices without a customer’s email address, the ‘account_no’ and ‘alias’ fields become mandatory, and the ’email’ field becomes optional. Merchant should include ’email’ field whenever possible. When ’email’ is unavailable, merchant must include ‘account_no’ and ‘alias’, so it may be used to later validate the legitimacy of the customer, when the customer attempts to register online for access to the customer side of Billing Presentment. Please contact tech support directly, if you need additional information or assistance with this special ability.

  6. You may use [query_xxxxxx], [invoice_xxxxxx] and [client_xxxxxx] substations to dynamically populate data within the datalink. [query_xxxxxx] inserts xxxxxx field value what passed into the page. [invoice_xxxxxx] inserts xxxxxx field value from invoice data. [client_xxxxxx] inserts xxxxxx field value from client contact data.