Skip to content

Commit

Permalink
Update getting started document page
Browse files Browse the repository at this point in the history
  • Loading branch information
@fangpenlin
fangpenlin committed Jan 9, 2014
1 parent fe2719e commit b4d5225
Showing 1 changed file with 119 additions and 77 deletions.
196 changes: 119 additions & 77 deletions docs/source/getting_started.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ Python, you can use it instead of writing REST API calling by yourself.
.. _`Python API for Billy`: https://github.com/victorlin/billy-client

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, the
document is not available yet, but we will cover it later.
section. If you want to know how to setup a Billy server, unfortunately, this
document doesn't cover that part yet.

Register a company
------------------
Expand Down Expand Up @@ -46,21 +46,23 @@ and you should see the response

Currently, there is no easy way to retrive 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. With the API key you get here, you can then call other API then.
back.

Create a plan
-------------

A plan is a setup for recurring payment processing, it has the amount to
charge or payout and the frequency of transaction. For instance, you are
running a hosting service, you have three hosting plans
A plan is a configuration for recurring payment processing, it contains the
amount to charge or payout 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

Then you can create three corresponding plans in Billy system. Let's say, we
want to create a Billy plan for the first hosting plan, then here we call
To charge 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:

::

Expand All @@ -72,15 +74,15 @@ want to create a Billy plan for the first hosting plan, then here we call
-d "frequency=monthly"


As we mentioned above, to call API other than the one for registering a
company, you need to pass your API key, it's simple, all you need to do is
set it as the username for HTTP authentication. You want to charge your hosting
service customer periodically, so the `plan_type` is `charge` here. The price
for the plan is 5 USD dollars, but all amounts of Billy are in cents, so here
you set the `amount` to `500`. And finally, it is a monthly plan, so you set the
`frequency` to `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 `charge`
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 charge, so you set the `frequency` to `monthly`.

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

::

Expand All @@ -99,55 +101,67 @@ Here we are, you should see the response
Create a customer
-----------------

A customer for Billy is the customer entity to your service, for example, a
customer who subscribed your hosting plan. To create a customer, you can call
the API like this
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://billing.balancedpayments.com/v1/customers \
-X POST \
-u 6w9KwCPCmCQJpEYgCCtjaPmbLNQSavv5sX4mCZ9Sf6pb:

the response would be
and the response would be

::

{
"guid": "CUR1omRKGYYhqNaK1SyZqSbZ",
"company_guid": "CPMM8C8Uhkt4pDeJ8oqJu8Nj",
"external_id": null,
"processor_uri": null,
"deleted": false,
"created_at": "2013-10-02T06:06:21.239505",
"updated_at": "2013-10-02T06:06:21.239505"
}

When the Billy system is charging or paying out to the customer, a corresponding
customer entity will be created in Balanced. Sometimes, you just want to map
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 `external_id` parameter as the URI of customer in Balanced.
can set the `processor_uri` parameter as the URI of customer in Balanced.

::

curl https://billing.balancedpayments.com/v1/customers \
-X POST \
-u 6w9KwCPCmCQJpEYgCCtjaPmbLNQSavv5sX4mCZ9Sf6pb: \
-d "external_id=/v1/customers/AC1jqOF9TocQXGIXjuMVrpMu"
-d "processor_uri=/v1/customers/AC1jqOF9TocQXGIXjuMVrpMu"


.. 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, you have a customer and a plan in the Billy system, however, at this
moment, Billy have no idea what the funding source is. To subscribe the
customer to the plan, you will need a `funding_instrument_uri` in Balanced system. In most
cases, the `funding_instrument_uri` is a tokenlized credit card number or bank account.
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-MP7hkE8rvpbtYu2dlO1jU2wg/cards/CC1dEUPMmL1ljk4hWqeJxGno

With that `funding_instrument_uri`, here we call
For how to generate a tokenlized credit card number, you can reference to the
`Balanced documents here`_.

.. _`Balanced documents here`: https://docs.balancedpayments.com/current/api.html?language=bash#tokenize-a-card

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

::

Expand All @@ -157,7 +171,7 @@ With that `funding_instrument_uri`, here we call
-d "plan_guid=PL97ZvyeA4wzM3WUyEG8xwps" \
-d "funding_instrument_uri=/v1/marketplaces/TEST-MP7hkE8rvpbtYu2dlO1jU2wg/cards/CC1dEUPMmL1ljk4hWqeJxGno"

Then, here comes our subscription response:
Then, here comes the subscription response:

::

Expand All @@ -166,7 +180,7 @@ Then, here comes our subscription response:
"plan_guid": "PL97ZvyeA4wzM3WUyEG8xwps",
"customer_guid": "CUR1omRKGYYhqNaK1SyZqSbZ",
"funding_instrument_uri": "/v1/marketplaces/TEST-MP7hkE8rvpbtYu2dlO1jU2wg/cards/CC1dEUPMmL1ljk4hWqeJxGno",
"period": 1,
"invoice_count": 1,
"amount": null,
"canceled": false,
"canceled_at": null,
Expand All @@ -176,8 +190,49 @@ Then, here comes our subscription response:
"updated_at": "2013-10-02T06:35:00.380234",
}

Great! The Billy system just charged the credit card for you, and it will
charge that credit card monthly afterward.
Congratulations! The Billy system just generated an invoice and charged the
credit card for you, and it will generate invoices and try to charge 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://billing.balancedpayments.com/v1/subscriptions/SUR6jKqqSyaFfGeeAsGaXFqZ/invoices \
-u 6w9KwCPCmCQJpEYgCCtjaPmbLNQSavv5sX4mCZ9Sf6pb:

and here is the response

::

{
"items": [
{
"adjustments": [],
"amount": 500,
"appears_on_statement_as": null,
"created_at": "2013-10-02T06:35:00.380234",
"effective_amount": 500,
"funding_instrument_uri": null,
"guid": "IVFRvtNxGvoWMehPG63Uyz1X",
"invoice_type": "subscription",
"items": [],
"scheduled_at": "2013-10-02T06:35:00.380234",
"status": "init",
"subscription_guid": "SUR6jKqqSyaFfGeeAsGaXFqZ",
"title": null,
"total_adjustment_amount": 0,
"transaction_type": "charge",
"updated_at": "2013-10-02T06:35:00.380234"
}
],
"limit": 20,
"offset": 0
}

Subscribe with an overwritten amount
------------------------------------
Expand All @@ -187,9 +242,9 @@ 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 plan story, you want to give a 30% discount to
an old customer, the original price is $5 USD, so the discounted amount would be
350 cents. Then here you can call
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

::

Expand All @@ -203,40 +258,39 @@ an old customer, the original price is $5 USD, so the discounted amount would be
Schedule your subscription at a specific time
---------------------------------------------

By default, when you subscribe to a plan, the first transaction will be filed
and processed immediately. And transactions will appear in the same time of
following days. For instance, if the `frequency` is `daily`, and you call the
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

* Transaction 1, at 2013-01-01 07:10 AM
* Transaction 2, at 2013-01-02 07:10 AM
* Transaction 3, at 2013-01-03 07:10 AM
* 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 date is end of the month, the
closes day in that month will be used, for example, call the API at
2013-01-30 7:00 AM, then the schedule will be
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

* Transaction 1, at 2013-01-30 07:10 AM
* Transaction 2, at 2013-02-28 07:10 AM
* Transaction 3, at 2013-03-30 07:10 AM
* 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 rahter
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 only want to collect your fee at 1st days of each month. The
transaction schedule would look like this
clear, you want to collect your fee only at the first day of all months. The
invoice schedule would look like this

* Transaction 1, at 2013-01-01 00:00 AM
* Transaction 2, at 2013-02-01 00:00 AM
* Transaction 3, at 2013-03-01 00:00 AM
* 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 student to your course plan, you can give it a
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 the call:

8601 format. Here is our call:

::

Expand All @@ -251,7 +305,7 @@ 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 simple. For example, you want to cancel a
to cancel it. To cancel it, that's easy. For example, you want to cancel a
subscription `SUR6jKqqSyaFfGeeAsGaXFqZ`, then just call

::
Expand All @@ -260,26 +314,14 @@ subscription `SUR6jKqqSyaFfGeeAsGaXFqZ`, then just call
-X POST \
-u 6w9KwCPCmCQJpEYgCCtjaPmbLNQSavv5sX4mCZ9Sf6pb:

sometimes, you also want to issue a prorated refund when canceling the
subscription. Let's say, there are 30 days from the latest transaction to
the next transaction. And 10 days has already elapsed, you want to do a
prorated refund to the customer for the rest 20 days. In this case,
you can use `prorated_refund` parameter to let Billy do the refunding for you.
Call it like this

::

curl https://billing.balancedpayments.com/v1/subscriptions/SUR6jKqqSyaFfGeeAsGaXFqZ/cancel \
-u 6w9KwCPCmCQJpEYgCCtjaPmbLNQSavv5sX4mCZ9Sf6pb: \
-d "prorated_refund=1"
Refund an invoice
-----------------

If you want to refund an arbitrarity amount to the customer, you can use the
`refund_amount` parameter. For instance, you want to refund $5 USD to the
customer, just call
Sometimes, you may want to issue a refund to customer, here you can call:

::

curl https://billing.balancedpayments.com/v1/subscriptions/SUR6jKqqSyaFfGeeAsGaXFqZ/cancel \
curl https://billing.balancedpayments.com/v1/invoices/IVFRvtNxGvoWMehPG63Uyz1X/refund \
-X POST \
-u 6w9KwCPCmCQJpEYgCCtjaPmbLNQSavv5sX4mCZ9Sf6pb: \
-d "refund_amount=500"

-d "amount=100"

0 comments on commit b4d5225

Please sign in to comment.