Getting started

Billy has a set of simple REST API. It means that you can use your favorite programming language to call the API. By the time I am writing this, there is a Python API for Billy is under development. If you are using Python, you can use it instead of writing REST API calling by yourself.

We will show you how to use Billy to process recurring payments for you in this section. If you want to know how to setup a Billy server, unfortunately, this document doesn’t cover that part yet.

Register a company

Before you can use the Billy API, you need to register a company first. A company here is basically an user entity in the Billy system, there will be a corresponding API key generated and associated with the company entity. You will need to pass your API key in order to access any other API of the Billy server. As Billy’s default payment processor is Balanced Payments, you will need to have an account and get a Balanced API key for registerion.

Okay, let’s say your Balanced API key is ef13dce2093b11e388de026ba7d31e6f. To register a company, here you call

curl https://billy.balancedpayments.com/v1/companies \
    -X POST \
    -d "processor_key=ef13dce2093b11e388de026ba7d31e6f"

and you should see the response

{
    "api_key": "5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC",
    "created_at": "2014-02-08T08:22:10.629000+00:00",
    "guid": "CP4MXZG4ThUdbLpiX8e9Yx3j",
    "updated_at": "2014-02-08T08:22:10.629000+00:00"
}

Currently, there is no easy way to Retrieve or reset the API key, so please do not lost it. If you lost it, you can only contact the administrator to get it back.

Create a plan

A plan is a configuration for recurring payment processing, it contains the amount to debit or credit and the frequency of payment processing. For instance, you are running a hosting business, you have three hosting service types:

• Small plan - 100GB storage, $5 USD/ mo
• Middle plan - 200GB storage, $10 USD / mo
• Large plan - 300GB storage, $15 USD / mo

To debit your customer montly, you can create three plan entities in Billy system correspond to your three hosting service types. Here we demonstrate how to create a Billy plan for your first hosting type:

curl https://billy.balancedpayments.com/v1/plans \
    -X POST \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC: \
    -d "plan_type=debit" \
    -d "amount=500" \
    -d "frequency=monthly"

As we mentioned above, to call any API other than the one for registering a company, you need to pass your API key, it’s easy, all you need to do is set it as the username for HTTP authentication. As you want to charge your hosting service customers rather than paying them out, the plan_type is debit here. The price for the plan is 5 USD dollars, but as the money unit in Billy system are all in cents, so here you set the amount to 500. And finally, it is a monthly debit, so you set the frequency to monthly.

Here we are, you should see the response looks like this one:

{
    "amount": 500,
    "company_guid": "CP4MXZG4ThUdbLpiX8e9Yx3j",
    "created_at": "2014-02-08T08:22:11.508000+00:00",
    "deleted": false,
    "frequency": "monthly",
    "guid": "PL4RHCKW7GsGMjpcozHveQuw",
    "interval": 1,
    "plan_type": "debit",
    "updated_at": "2014-02-08T08:22:11.508000+00:00"
}

Create a customer

When you have a new customer who wants to subscribe your hosting service, you need to create a customer entity in Billy system for him. To create a customer, you can call the API like this:

curl https://billy.balancedpayments.com/v1/customers \
    -X POST \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC:

and the response would be

{
    "company_guid": "CP4MXZG4ThUdbLpiX8e9Yx3j",
    "created_at": "2014-02-08T08:22:10.904000+00:00",
    "deleted": false,
    "guid": "CU4NheTMcQqXgmAtg1aGTJPK",
    "processor_uri": "/v1/customers/CUCChwFzuMRlBGgoBwjRgqr",
    "updated_at": "2014-02-08T08:22:10.904000+00:00"
}

Before Billy system charging or paying out to the customer, a corresponding customer entity will be created in Balanced. Sometimes, you want to map the customer in Billy system to an existing customer in Balanced system, you can set the processor_uri parameter as the URI of customer in Balanced.

curl https://billy.balancedpayments.com/v1/customers \
    -X POST \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC: \
    -d "processor_uri=/v1/customers/CU1jqOF9TocQXGIXjuMVrpMu"

Note

As the name processor_uri implies, it MUST be the URI to a Balanced customer rahter than its GUID.

Subscribe to a plan

So far so good, you have a customer and a plan in the Billy system, however, before you can subscribe the customer to the plan, you will need a funding source in Balanced system to charge. In most cases, the funding source is a tokenlized credit card number or a bank account. In this example, we use a tokenlized credit card number looks like this:

/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/cards/CCBXYdbpYDwX68hv69UH1eS

For how to generate a tokenlized credit card number, you can reference to the Balanced documents here.

With that funding source, to subscribe the customer to our plan, here we call

curl https://billy.balancedpayments.com/v1/subscriptions \
    -X POST \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC: \
    -d "customer_guid=CU4NheTMcQqXgmAtg1aGTJPK" \
    -d "plan_guid=PL4RHCKW7GsGMjpcozHveQuw" \
    -d "funding_instrument_uri=/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/cards/CCBXYdbpYDwX68hv69UH1eS"

Then, here comes the subscription response:

{
    "amount": null,
    "appears_on_statement_as": null,
    "canceled": false,
    "canceled_at": null,
    "created_at": "2014-02-08T08:22:11.782000+00:00",
    "customer_guid": "CU4NheTMcQqXgmAtg1aGTJPK",
    "effective_amount": 500,
    "funding_instrument_uri": "/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/cards/CCBXYdbpYDwX68hv69UH1eS",
    "guid": "SU4ST39srWVLGbiTg174QyfF",
    "invoice_count": 1,
    "next_invoice_at": "2014-03-08T08:22:11.782000+00:00",
    "plan_guid": "PL4RHCKW7GsGMjpcozHveQuw",
    "started_at": "2014-02-08T08:22:11.782000+00:00",
    "updated_at": "2014-02-08T08:22:11.782000+00:00"
}

Congratulations! The Billy system just generated an invoice and charged the credit card for you, and it will generate invoices and try to debit that credit card monthly afterward. To view your invoices, you can visit

/v1/subscriptions/<Subscription GUID/invoices

with your API key like this

curl https://billy.balancedpayments.com/v1/subscriptions/SU4ST39srWVLGbiTg174QyfF/invoices \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC:

and here is the response

{
    "items": [
        {
            "adjustments": [],
            "amount": 500,
            "appears_on_statement_as": null,
            "created_at": "2014-02-08T08:22:15.073000+00:00",
            "customer_guid": "CU4NheTMcQqXgmAtg1aGTJPK",
            "effective_amount": 500,
            "external_id": null,
            "funding_instrument_uri": null,
            "guid": "IV4gVtDyP3CD9zQyv8AtPwx5",
            "invoice_type": "customer",
            "items": [],
            "status": "staged",
            "title": null,
            "total_adjustment_amount": 0,
            "transaction_type": "debit",
            "updated_at": "2014-02-08T08:22:15.073000+00:00"
        }
    ],
    "limit": 20,
    "offset": 0
}

Subscribe with an overwritten amount

In some cases, you may want to subscribe a customer to a plan with a different amount from the plan. For example, you want to give a discount to one of your old customers. In this case, you can pass an optional parameter amount to overwrite the amount from plan.

In the context of our hosting business story, you want to give a 30% discount to the old customer, the original price is $5 USD, then discounted amount would be 350 cents, so here you can call

curl https://billy.balancedpayments.com/v1/subscriptions \
    -X POST \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC: \
    -d "customer_guid=CU4NheTMcQqXgmAtg1aGTJPK" \
    -d "plan_guid=PL4RHCKW7GsGMjpcozHveQuw" \
    -d "funding_instrument_uri=/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/cards/CCBXYdbpYDwX68hv69UH1eS"
    -d "amount=350"

Schedule your subscription at a specific time

By default, when you subscribe to a plan, the first invoice will be filed and processed immediately. Then all following invoices will appear in the same time of following days. For instance, if the frequency is daily, and you call the API at 2013-01-01 7:10 AM, then the schedule will look like this

• Invoice 1, at 2013-01-01 07:10 AM
• Invoice 2, at 2013-01-02 07:10 AM
• Invoice 3, at 2013-01-03 07:10 AM
• ...

If the frequency is monthly, and the begin date is the last day of a month, then Billy will pick the closest day in following months, for example, we call the API at 2013-01-30 7:00 AM, then the schedule for invoices will be

• Invoice 1, at 2013-01-30 07:10 AM
• Invoice 2, at 2013-02-28 07:10 AM
• Invoice 3, at 2013-03-30 07:10 AM
• ...

So, what if you want to schedule those transactions at a specific time rather than the API calling time? It’s simple, you can use the optional started_at parameter. For example, you have a violin course for beginners, to make things clear, you want to collect your fee only at the first day of all months. The invoice schedule would look like this

• Invoice 1, at 2013-01-01 00:00 AM
• Invoice 2, at 2013-02-01 00:00 AM
• Invoice 3, at 2013-03-01 00:00 AM
• ...

In this case, to subscribe a new student to your course plan, you can give it a started_at at the 1st of the next month. The started_at should be in ISO 8601 format. Here is our call:

curl https://billy.balancedpayments.com/v1/subscriptions \
    -X POST \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC: \
    -d "customer_guid=CU4NheTMcQqXgmAtg1aGTJPK" \
    -d "plan_guid=PL4RHCKW7GsGMjpcozHveQuw" \
    -d "funding_instrument_uri=/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/cards/CCBXYdbpYDwX68hv69UH1eS" \
    -d "started_at=2013-10-01T00:00:00"

Cancel a subscription

When a customer doesn’t want to continue a subscription anymore, you will need to cancel it. To cancel it, that’s easy. For example, you want to cancel a subscription SU4ST39srWVLGbiTg174QyfF, then just call

curl https://billy.balancedpayments.com/v1/subscriptions/SU4ST39srWVLGbiTg174QyfF/cancel \
    -X POST \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC:

Create an invoice for customer

Invoices can be generated from a subscription, however, it is not the only way to generate an invoice. You can also generate an invoice directly to your customer. For example, a customer purchased some goods from your online store, you can invoice them like this

curl https://billy.balancedpayments.com/v1/invoices \
    -X POST \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC: \
    -d "customer_guid=CU4NheTMcQqXgmAtg1aGTJPK" \
    -d "amount=4497" \
    -d "appears_on_statement_as=Cuty shop" \
    -d "item_name1=Lovely hat" \
    -d "item_amount1=999" \
    -d "item_name2=Cute shoes" \
    -d "item_amount2=1499" \
    -d "item_name3=Adorable clothes" \
    -d "item_amount3=1999" \
    -d "adjustments_amount1=-1000" \
    -d "adjustments_reason1=Coupon discount"

and the response will be

{
    "adjustments": [
        {
            "amount": -1000,
            "reason": "Coupon discount"
        }
    ],
    "amount": 4497,
    "appears_on_statement_as": "Cuty shop",
    "created_at": "2014-02-08T08:22:15.073000+00:00",
    "customer_guid": "CU4NheTMcQqXgmAtg1aGTJPK",
    "effective_amount": 3497,
    "external_id": null,
    "funding_instrument_uri": null,
    "guid": "IV4gVtDyP3CD9zQyv8AtPwx5",
    "invoice_type": "customer",
    "items": [
        {
            "amount": 999,
            "name": "Lovely hat",
            "quantity": null,
            "type": null,
            "unit": null,
            "volume": null
        },
        {
            "amount": 1499,
            "name": "Cute shoes",
            "quantity": null,
            "type": null,
            "unit": null,
            "volume": null
        },
        {
            "amount": 1999,
            "name": "Adorable clothes",
            "quantity": null,
            "type": null,
            "unit": null,
            "volume": null
        }
    ],
    "status": "staged",
    "title": null,
    "total_adjustment_amount": -1000,
    "transaction_type": "debit",
    "updated_at": "2014-02-08T08:22:15.073000+00:00"
}

The parameter funding_instrument_uri is optional for creating an invoice. You can create an invoice first, and let customer decide how to settle the invoice later. To settle an invoice, you can use PUT method to update the invoice’s funding_instrument_uri like this:

curl https://billy.balancedpayments.com/v1/invoices/IVS6Mo3mKLkUJKsJhtqkV7T7 \
    -X PUT \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC: \
    -d "funding_instrument_uri=/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/cards/CCBXYdbpYDwX68hv69UH1eS"

Refund an invoice

Sometimes, you may want to issue a refund to customer, here you can call:

curl https://billy.balancedpayments.com/v1/invoices/IVFRvtNxGvoWMehPG63Uyz1X/refund \
    -X POST \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC: \
    -d "amount=100"