Tuesday, June 9, 2015

PHP and JavaScript SDKs Now Available

Bill & Pay is now making available SDKs for PHP and JavaScript. The SDK consists of a helper class that makes calling our API really easy along with an example of how to use it.

Download the Bill & Pay SDK


Let Us Write the Code for You


The "Try It" feature in the Bill & Pay API Documentation has been expanded to include the ability show the exact source code you would use to make a request through the SDK.

Here is how you use it:
The "Try It" form in the
Bill & Pay Documentation.


  1. Go to the Bill & Pay API Documentation.
     
  2. Go to the class and method you are interested in using.
     
  3. Expand the "Try It" section and fill out the form to specify the parameters you want to pass to the API method.
     
  4. Click "Generate XML Request". This will create the XML request that needs to be sent to the Bill & Pay API.
     
  5. Try out your method call by clicking the "Execute Request" button. The results will be shown below the generated XML.
     
  6. Once you have the XML request that works the way you want it to you can translate the XML request into the source code for your chosen SDK programming language. Just click the "Select an SDK language." drop-down list. Select your programming language that Bill & Pay provides an SDK for.
     
  7. The source code for the chosen programming language will appear below the XML request. You can copy the source code and paste it into your programming environment to use it immediately.
The Try It feature generates
the request XML.

A simple generated sample source code for
making an API method call using the
PHP version of the SDK.

Here is an example of the PHP SDK source code generated for a complex API method call:


$BPBiller = new BPBillerAPI();
$BPBiller.billerid = "99999";
$BPBiller.password = "xxxxxxxxx";
$customerinfo = $BPBiller->sendRequest(array('customerinfo' => array('limit' => array('rows' => '50', 'page' => '1'), 'field' => array('internalid', 'id', 'active', 'login', 'companyname', 'firstname', 'middlename', 'lastname', 'phone', 'billingaddress'), 'where' => array('active' => '1', 'enrolled' => '1'))));
if ($customerinfo !== false) {
    //Process response here using $customerinfo variable.
} else {
    //Handle errors here.
}


And the same API method call using source code generated for the JavaScript SDK:

var BPBiller = BPBillerAPI();
BPBiller.billerid = "99999";
BPBiller.password = "xxxxxxxxx";
BPBiller.sendRequest(customerinfo_response, {"customerinfo":{"limit":{"rows":"50","page":"1"},"field":["internalid","id","active","login","companyname","firstname","middlename","lastname","phone","billingaddress"],"where":{"active":"1","enrolled":"1"}}});
function customerinfo_response(customerinfo) {
    if (BPBiller.errorNumber == 0) {
        //Process response here using customerinfo variable.
    } else {
        //Handle errors here.
    }
}


Wednesday, May 27, 2015

Google Group for Developers

Today we are launching a Google Group for developers that are interested in integrating with Bill & Pay. This public forum will allow developers to talk with each other and the developers of Bill & Pay to get help, ask questions, and make suggestions.

Join Our Google Group



Wednesday, April 15, 2015

Payer Site Embedding with Server Side Programming

The payer site your customers use to make payments and view their account history is usually a separate web site hosted from www.billandpay.com.

If your business has a web site and you would like the payer site to appear to be a part of your web site you can use the "Embed Payer Site" feature.

How it Works


This part is a little bit technical. You will have to create a scripted page on your web site that can dynamically create a web page that embeds the payer site in it. If you are not familiar with server scripting for web sites we recommend you forward this page to a web developer that can do this work for you.

The Technical Details


You will need to create a scripted page on your web site that accepts a parameter called "url" and then generates a web page that includes an <iframe> element with the "src" property set to the value passed in the "url" parameter.

Here is a minimal example in PHP:

<?php
echo "<html>
    <head>
        <title>Payer Site Embedding Example</title>
    </head>
    <body>
        <iframe src='{$_GET['url']}' style='width: 800px; height: 600px; border: none;'></iframe>
    </body>
</html>";
?>

You would add HTML to this minimal example to surround the <iframe> tag with the appearance from your web site that you want. Once you have created the necessary script on your web site you need to let customer service know that you want to enable payer site embedding and let us know the URL of the embedding script on your server.

Why a URL Parameter?


Bill & Pay sends unique URLs in each of the emails sent to your customers. These URLs are customized for each customer and for the invoice the email pertains to so that when they click on the URL in the email they are taken to the correct payment page. That is why you must accept the 'url' parameter and make it the 'src' of the <iframe> tag.

Site Encryption


Even when the payer site is embedded inside your web site, all payment and account information will be secured using encryption between the payer's computer and Bill & Pay's web server. It is the same level of security as is used when the payer site is not embedded.

However, the appearance of the security indicators in the payer's browser will be different. First, let's look at what the generic login page on the payer site looks like when the it is not embedded:

Generic login page on the payer site when not embedded.

You will notice the green area in the address bar that has a lock icon and says "SkyHill Software Incorporated (US)". SkyHill Software, Inc. is the company that created and operates the Bill & Pay service. This green area informs visitors to the site that the site is secure and tells them who they are communicating with. They can click the green area and verify the identity of the web site they are communicating with:



When you embed your web site, these security indicators enabled by the Bill & Pay server will no longer be displayed in the payer's web browser. Here is an example of a web site that embeds the payer site and has no encryption enabled:


To the payer it appears there is no encryption used for logging in to Bill & Pay because the web page that is embedding the payer site does not employ encryption. In fact, the Bill & Pay session on this page is completely secure and encrypted.

Embedded payer site on web site with no encryption.

Because of this situation, it is recommended that you have a security certificate installed on your web site's server so that the page that embeds the payer site is also secure. This will not add any additional security to the payer site but it will visually reassure your customers that their payments are secure.


Monday, April 13, 2015

Payment Surcharges

Surcharges make it easy for your business to charge an additional fee for certain types of payment transactions.

Surcharge Calculation


Surcharges are calculated for each transaction based on the following four settings:

  • Base fee. This is a fixed fee amount that will be applied.
  • Percentage. A fee calculated as a percentage of the total payment amount and added to the base fee.
  • Minimum surcharge. An amount that is the minimum surcharge that will be charged after adding the base fee and percentage.
  • Maximum surcharge. An amount that limit the maximum amount of surcharge that will be charged.
You can mix these four settings in any way you want and set any of them to zero to not use that setting. Here are some example surcharge scenarios:
  • Charge a $1.00 base fee along with a 2% fee with no minimum or maximum. On a $100.00 payment the customer will be charged an additional $3.00 surcharge.
  • Charge a 1% surcharge with a minimum fee of $1.00. On a $50.00 payment the customer will be charged an additional $1.00 surcharge because the minimum surcharge will be enforced. On a $200.00 payment the customer will be charged an additional $2.00.

Types of Payments


    You can specify separate surcharge settings for each of the following types of transactions:
    • ACH one-time payments.
    • Credit Card one-time payments.
    • ACH auto pay payments.
    • Credit Card auto pay payments.
    You can set different surcharge rates for each of these payment methods or choose to charge a surcharge for some of them and not for others.

    A credit card surcharge will be displayed once "Credit Card" is chosen as the payment method.

    For the ACH and Credit Card one-time payment surcharge types the surcharge will not be displayed until the payer chooses a payment method. You can also specify an up front surcharge setting for one-time payments that will apply to both ACH and Credit Card payments and will be displayed on the invoice payment amounts page where the payer chooses which invoices to pay and how much to pay on them.

    An up front surcharge on the invoice payment amounts page.

    Other Surcharge Options


    When surcharges are enabled you also need to decide how you want to describe the surcharge to your customers. For example, it could be called a "Convenience Fee", "Surcharge", or whatever name best fits your business model.

    Surcharges are recorded as a Sales Receipt. The Sales Receipt has a line item for the surcharge. You must create a line item that will be used to record payments received for surcharges.

    The biller has the option to uncheck the surcharge on the "Accept Payment" screen in the Biller Control Panel when entering a customer's payment.

    Enabling Surcharges


    Enabling this option costs a one-time $50 activation fee and an additional $0.10 for each transaction that has the surcharge applied.

    Contact customer service to enable surcharges or ask any questions you have about this feature.

    Please note, the rules for adding surcharges to credit card transactions vary by state and is illegal in some states.  Please check your individual state laws before you begin to use the Bill & Pay surcharge feature.


    Monday, April 6, 2015

    Click Pay and Payer Logins

    There are two different ways that your customers, we refer to them as payers, can make payments:

    • Click Pay
    • Payer Login

    Click Pay


    Click Pay puts a payment link in your email messages sent to your customers. They click the link in your email and are immediately taken to the Make Payment page without having to create and account or remember a login user name and password.

    The benefits of Click Pay are obvious. You get paid quickly by your customers because they don't have to create an account and they don't have to remember an account login.

    Payer Login


    During Click Pay your customers are informed that they can create an account or login if they already have an account. The benefits of your customers logging in are:
    • Bill & Pay can remember their last payment account for them.
    • Pay more than one invoice with a single payment choosing how to split the payment.
    • See past invoices and payment history.
    • View invoice PDFs with full line item detail.
    • See and approve payment plans.
    • Approve automatic payments.
    • Choose up to three email addresses where Bill & Pay will send messages to.

    Add Features to Click Pay


    Some of the features that are not available to customers in Click Pay by default can be added. You can send a request to customer service to add any or all of the following features to Click Pay for your customers so they do not require a login to use them:
    • Allow Click Pay users to pay more than one invoice. They will be able to choose to pay any or all invoices with an open balance in a single transaction.
    • Allow Click Pay users to use "Invoices & Payments" page. This gives the customer access to past invoices and payment history. They will be able to view all invoice PDFs with full line item detail.
    • Allow Click Pay users to use "Auto Pay" page. The customer will be able to approve and modify auto pay approval for their account.
    • Allow Click Pay users to use "Payment Plans" page. The customer will be able to see and approve payment plans you have created.
    By default all of these features require your customers to create a user name and password and login to protect their privacy. However, your business may decide that these features are not a privacy concern for your customers and that enabling them is a benefit.

    Prevent Payer Logins


    If you want to prevent your customers from creating a login you can request that account creation not be offered to your customers when using Click Pay. Some possible reasons you may choose this are:
    • You do not want Bill & Pay to ever remember the customer's payment account information.
    • You only want the customer to pay their invoices. You do not want them to look at past invoices or payments.

    Disabling Click Pay


    Bill & Pay's default configuration is a good balance between maintaining customer privacy protections and making payments as easy as possible to make. However, if your business or customers demand a higher level of privacy you can also request that Click Pay be disabled for your account. Customers will have to create a payer login and use that login everytime they make a payment.

    If you choose to have Click Pay disabled, you can use the Invite Customers feature in Bill & Pay to invite your customers to create accounts. The new invoice notification email will also instruct them to create an account if they have not done so yet.

    Friday, April 3, 2015

    Developers: Making Your Life Easier

    Integrating with another system can often be an "ugh!" moment in any developers life. Learning the way a new system works. Figuring out how to call a new API. Dealing with all sorts of weird edge cases. Scratching your head when what was working all of a sudden stops working.

    Our API is Made to Make Developers' Lives Easier


    We have worked with great APIs from other companies and really bad APIs from other companies, so we understand the pain when an API is anything other than great. Because of that we work hard to make sure our API is really great.

    Easy to Understand Documentation


    Our API documentation is straightforward, easy to read, and easy to understand. You can find the documentation here. We recommend you start by reading the "Sending Requests" article and looking at the "biller" class.

    Helpful Tools


    Our documentation has a "Try It" feature on every method's page. Try It gives you a web form you can fill out to specify the parameters for an API method. Clicking the "Generate XML Request" will open a new browser window with the exact XML request you specified ready to try. You don't need to guess how to format the request. Let us generate a request template for you that you can copy and paste into your own code.

    Finally, you can click the "Execute Request" button to call the method live on our server. If a problem occurs processing your call our API returns sensible, informative error messages that make it easy to track down and resolve issues. You can manually edit the XML request on the Try It page and execute the call again to see what request works best for your use case.

    XML Requests


    All requests to our API are made using an easy to learn XML structure that you POST to our secure web server.

    Response Formats


    The API will return responses in XML format by default. You can also specify the following response formats if they are more convenient for your development purposes:
    • JSON - Receive responses in the JSON format for use in many development languages including JavaScript.
    • PHP - Receive responses in a format that you can pass to the PHP function unserialize() to retrieve a PHP array with the API response.

    Thursday, April 2, 2015

    Developers: Why Integrate with Bill & Pay

    Bill & Pay provides an open web-based API that offers several different ways you can integrate. We make great API documentation and tools a priority. So, to start off you can check out our developer documentation.

    Instant Accounts Receivables


    Developers creating a product that would benefit from a built-in Accounts Receivable system can integrate directly with Bill & Pay to manage customers, create and send invoices, and receive payments.

    Integration can be as simple as provisioning new Bill & Pay accounts for your customers and embedding that account into your product.

    You can also use the web-based API to perform automatic data synchronization between your product to:
    • Keep the customer list in Bill & Pay up-to-date with the customer list in your product.
    • Create new invoices and send them to customers for payment.
    • Record payments customers make through methods other than Bill & Pay.

    Why build your own customer and invoice management system when you can integrate Bill & Pay and make commissions off payments made through your integration?

    To try our API with a free trial account, sign up for Bill & Pay Easy Invoice today. We can extend your trial period beyond 30 days free of charge for development and testing purposes.

    See the "biller" class in the API documentation for more information.

    Custom Accounting System Synchronization


    Our API can also be used to integrate your vertical-market accounting system with Bill & Pay so that you can quickly start offering your customers an invoice delivery and payment acceptance solution. Our API provides everything needed to synchronize your customers, payments, and invoices to Bill & Pay and post payments made online back to your system.

    Web Notifications


    We also provide web notifications from our server to yours to inform your application when events such as a new payment being occur. You can use these notifications to automatically synchronize between your product and Bill & Pay in the most effecient, event-driven method possible.


    Single Integration Model


    You can integrate between your system and Bill & Pay using individual credentials for a specific business setup with Bill & Pay. This makes custom solutions for individual businesses easy to implement.

    App Integration Model


    If your integration will be targeted at a larger market then you can implement the app authentication model. You use a single set of credentials unique to your app to make API calls to any business that has authorized your app to access their data.

    Reseller API Structure


    Become a reseller and you can make commissions from the Bill & Pay usage of your customers. There is even a reseller API that makes provisioning of new Bill & Pay businesses automatic. Your reseller account can be configured to automatically authorize API access for your app to all business accounts created through your reseller account.

    See the "reseller" class in the API documentation for implementation information.

    Wednesday, April 1, 2015

    What is ACH?

    ACH stands for Automated Clearing House. Your business can use ACH to accept payments from your customers' checking our savings bank account at rates much lower than accepting credit card payments.

    How ACH Works


    When a customer uses Bill & Pay to make a payment to your business using ACH, the customer will enter the name on their account, their bank routing number, and the account number. All of this information can be found on a blank check as illustrated in the image below.


    At the end of the business day a request for funds is sent to the bank of each of your customers that made a payment to you that day using ACH. Those funds are then received and deposited to your bank account.


    Why ACH is Better than a Check


    ACH is a better way to receive payment from your customers because:
    • You don't have to endorse each payment check.
    • You don't have to manually record each payment check. The payment will be automatically recorded for you and properly credited to the invoices the customer wanted to pay.
    • You don't have to make a trip to the bank.
    • You get paid faster because your customer doesn't have to mail the check to you. This also saves your customers time and money on postage.

    ACH Saves You Money Compared to Credit Cards


    When you receive a payment through Bill & Pay by ACH you pay a single flat transaction fee and no "discount rate" on the first $5,000.00 of each payment transaction. Credit Cards cost a transaction fee plus a "discount rate" on the entire amount. A discount rate is a percentage you pay to the credit card companies to accept credit cards.

    Bill & Pay Also Works with Credit Cards


    We realize that the most important thing for your business is to get paid by any method your customer will use to pay you. That is why Bill & Pay also works with all the major credit card brands through many industry standard merchant gateways.

    Bill & Pay allows you to accept both ACH and Credit Card payments through a single product. Payments made using ACH will start saving your business money right away. The convenience and time savings Bill & Pay brings your business will save you money on every payment made, even by credit card.

    Tuesday, March 31, 2015

    Emails Sent Tracking

    Bill & Pay includes tools to track the delivery of all the emails sent for your business including new invoice notifications, payment due and over due reminders, and payment confirmations.


    Email Log


    Bill & Pay retains a one month log of all email messages sent to your customers on your behalf. What we log:
    • What customer an email was sent to
    • The customer's email address the email was sent to
    • The date and time and it was sent
    • The subject and content of the email message
    • The invoice file attachment included with the message
    Your business may have a need to retain sent email logs for a period of time longer than one month. Please contact customer service to inquire about increasing the duration of email log retention.

    View by Customer


    To view all of the emails sent to a specific customer go to that customer's page in Bill & Pay and click the "Emails Sent" button.

    The Customer Emails Sent page will list all of the emails in your sent email log with the status of the email, the date and time the email was sent, the email address the email was sent to, and the subject of the email.

    Click on any of the emails in the Customer Emails Sent list to view the email details. The details page will show you the email message the way it looked to your customer when they received it. If there was an attachment with the email, such as an invoice PDF, then you will also be able to view the file that was attached to the email.

    Reporting


    You can generate a report of all the emails you have sent in a date range that you specify. Go to Reports and click the "Emails Sent to Customers" report. You can choose the start and end dates for the report along with which email status types you want to include in the report. Possible statuses are sent, opened, and error.

    The report that is generated will list all of the emails sent in the selected date range with the email status, date and time sent, the email address it was sent to, the customer the email was sent to, and the email's subject.

    A great use for the emails sent report is to generate a report of all the emails you sent in the last month that have a status of "Error". This will give you a list of customers that have email addresses that you are unable to delivery messages to. You can use the report is a list of customers to contact to get an updated email from. Keeping your customer email list up-to-date and accurate will help improve your cash flow.

    Email Status


    There are three possible email statuses:
    1. Sent - Bill & Pay has sent the email for delivery. If the email can not be delivered it will move from the Sent status to the Error status.
    2. Opened - The customer opened the email. You can use this status to verify that your customer received the email and looked at it. Click on a sent email to view it in detail to see the date and time the customer first opened the email.
    3. Error - The email could not be delivered. Click on an email with an error to view a detailed explanation of why it could not be delivered. The most common reason for this is trying to send an email to an address that is not valid.

    How the Opened Status Works


    Bill & Pay includes images in the emails we send to your customers. When your customer looks at the email and the images in the email are loaded it notifies our server that they are reading the email message. This makes it possible for us to mark the email as opened and know the date and time when the customer first opened it.

    Many email readers, including most email readers on mobile devices, automatically load images when reading email messages. Customers that use one of these email readers will have emails you send them marked as 'Opened' when they read them. Some email readers, such as Outlook, do not load images by default as a privacy protection for the user. Emails to these customers will remain in a "Sent" status unless the customer adds your business email address you send emails from to their "Safe Sender" list or they tell their email reader to load images for the email message they are reading.

    This means that an email status of "Opened" indicates your customer has opened your email message. However, a status of "Sent" means it was sent to them and they may or may not have opened it.

    Longer Email Retention


    By default, email history is stored in Bill & Pay for the past 30 days. Some businesses may be required to keep a record of messages sent to customers for regulatory reasons. If this is the case for your business, contact customer service to increase the sent email log retention period for your business. We retain a record of what your email looked like at the time it was delivered. Even if an invoice is modified at some point after an email is sent, we retain a record of how that invoice appeared at the time the email was sent.

    Email Deliverability

    Bill & Pay uses email to deliver new invoice notifications, payment due and overdue reminders, and payment confirmations to your customers. Knowing your email has been delivered to your customers is key to getting paid on time. Bill & Pay helps improve the delivery success rate of your customer communications in several ways.

    Below are different options we provide to customize your email delivery experience.

    Getting Started

    When a business starts using Bill & Pay we deliver email to your customers on your behalf. You can customize the email address that these emails are sent from so that if your customer replies you will receive them.

    Bill & Pay will initially send all emails from an email address of "notify@billandpay.com" with a special heading on the email called "Reply-To" that instructs your customers email system to send reply emails directly to your email address. Most email programs will show the email as being sent from your email address. It may also show a small note on screen indicating the email was sent on behalf of your address from notify@billandpay.com.

    How to Change Your From Address In Bill & Pay

    To change what email address Bill & Pay uses as the “From Email Address” on your emails go to Advanced Options / Letter Templates and Advanced Options / Payment Reminders.

    Deliver Emails Through Your Own Email Server

    Sending emails from your own mail server will greatly improve the rate of successful delivery and reduce the likelihood of the emails being identified as spam. You can setup your mail server in Bill & Pay in Advanced Options / Email Delivery.

    Use Your Own Domain Name

    If you have a domain name for your business you should try to use it for your business email, if you aren't already. Using an email address at any of the free email services, such as @gmail.com or @yahoo.com, will hurt the delivery of your emails. If you have a website with your own address, known as a domain name, you can start receiving email at your domain. You will need to have your own email server for your domain name. Most web hosting companies offer this as part of your web hosting or as an optional add-on. Contact your web hosting company for more details about using your domain name for email.

    Approve Bill & Pay to Send Email for Your Domain

    This is only necessary if you are unable to get your own email server setup for delivering emails to your customers. In that case you will need to approve Bill & Pay as a sender of email for your domain name.

    In order to help combat spam, or unwanted email messages, many mail servers on the Internet will not accept delivery of an email from one domain name for another domain name unless specific approval has been given to do so.

    You can give approval for Bill & Pay to send email on behalf of your domain name by adding a few records to your domain's DNS settings. Please contact Bill & Pay Support for instructions on getting this set up. If you are not comfortable modifying the DNS settings for your domain our instructions will also include an offer to perform the necessary changes for you.

    For those curious as to what DNS settings we recommend adding, the instructions we send will tell you how to add SPF and DKIM records to your domain. These records in your domain's DNS settings will instruct other mail servers on the Internet to allow Bill & Pay's email server to send them new email as if it was coming from your own mail server.

    Report of Emails Sent to Customers

    There is a report in Bill & Pay that will show you which emails have been sent out to all customers. You can find this in the "Reports" section under "Emails Sent to Customers". You can also look up an individual customer in Bill & Pay and then click on the "Emails Sent" button to only see what has been sent to that specific customer.

    For more information about how emails to customers are tracked in Bill & Pay, please see our Emails Sent Tracking article.