REST API reference

The official endpoint of Billy API is

https://billy.balancedpayments.com

When you found a bug, or you have any suggestion to this project, please create an issue in our GitHub repo.

All HTTP responses except errors will be in JSON format. Other format is not supported currently. To access the API, you need an API key, except the one for registering a company. The API key should be passed as the username for HTTP basic authentication, leave the password blank.

Company

A company is an user account for using the Billy system, you need to pass your Balanced API key to create one, so that Billy can process payments via Balanced for you. Company has a generated API key which is required for performing any further operations in Billy system.

Note

You MUST keep these API keys as secret, do not share them with anyone, do not post them on IRC. Also, currently, Billy API key cannot be Retrieved or reset easily, if you lost it, you can only contact administrator to ask them reset it for you.

Create

Create a company and return the entity. Only this method does not require an API key to access as you need it to generate one. Remember to save the API key in response.

Method

POST

Endpoint

/v1/companies

Parameters

processor_key - The API key for your Balanced account

Example:

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

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"
}

Retrieve

Retrieve a company record

Method: GET
Endpoint: /v1/companies/<Company GUID>

Example:

curl https://billy.balancedpayments.com/v1/companies/CP4MXZG4ThUdbLpiX8e9Yx3j \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC:

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"
}

Plan

A plan is setup to create recurring charges or for payouts. A plan contains the amount to charge or payout and the frequency which invoices are generated.

Create

Create a plan and return the entity.

Method

POST

Endpoint

/v1/plans

Parameters

plan_type - The type of this plan can be either debit for charging customer or credit for paying out.
frequency - The frequency to schedule charging or paying out to customer. Can be one of
- daily
- weekly
- monthly
- yearly
When it is monthly and the schedule started at the end of a month, the closest day to the started one in a month will be selected for following invoices. For example, the started date time is 2013-01-30, then following invoices will occur at 2013-02-28, 2013-03-30 and so on.
amount - The amount in USD cents to debit or credit to customer
interval - (optional) The interval of frequency period to multiply, the default value is 1. For example, to debit or credit a customer by two weeks frequency, you can set the frequency to weekly, and set the interval to 2, then the schedule will be in a biweekly manner.

Example:

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

Response:

{
    "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"
}

Retrieve

Retrieve a plan entity

Method: GET
Endpoint: /v1/plans/<Plan GUID>

Example:

curl https://billy.balancedpayments.com/v1/plans/PL4RHCKW7GsGMjpcozHveQuw \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC:

Response:

{
    "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"
}

Delete

Delete a plan and return entity.

Method: DELETE
Endpoint: /v1/plans/<Plan GUID>

Example:

curl https://billy.balancedpayments.com/v1/plans/PL4RHCKW7GsGMjpcozHveQuw \
    -X DELETE \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC:

Response:

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

List

List all plans

Method

GET

Endpoint

/v1/plans

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

Example:

curl https://billy.balancedpayments.com/v1/plans \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC:

Response:

{
    "items": [
        {
            "amount": 500,
            "company_guid": "CP4MXZG4ThUdbLpiX8e9Yx3j",
            "created_at": "2014-02-08T08:22:11.508000+00:00",
            "deleted": true,
            "frequency": "monthly",
            "guid": "PL4RHCKW7GsGMjpcozHveQuw",
            "interval": 1,
            "plan_type": "debit",
            "updated_at": "2014-02-08T08:22:11.508000+00:00"
        }
    ],
    "limit": 20,
    "offset": 0
}

List customers

List all customers who subscripted to the plan

Method

GET

Endpoint

/v1/plans/<Plan GUID/customers

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

List subscriptions

List all subscriptions owned by the plan

Method

GET

Endpoint

/v1/plans/<Plan GUID/subscriptions

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

List invoices

List all invoices generated by subscriptions owned by the plan

Method

GET

Endpoint

/v1/plans/<Plan GUID/invoices

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

List transactions

List all transactions generated by subscriptions owned by the plan

Method

GET

Endpoint

/v1/plans/<Plan GUID/transactions

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

Customer

An entity for customer to your service. Before the first time of debiting or crediting, a corresponding customer record in Balanced system will be created. If you want to map an existing customer in Balanced, you can set the processor_uri to the URI of customer in balanced.

Create

Create a customer and return the record.

Method

POST

Endpoint

/v1/customers

Parameters

processor_uri - (optional) The URI to an existing customer record in Balanced server

Example:

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

Response:

{
    "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"
}

Retrieve

Retrieve a customer entity

Method: GET
Endpoint: /v1/customers/<Customer GUID>

Example:

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

Response:

{
    "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"
}

Delete

Delete a customer and return entity.

Method: DELETE
Endpoint: /v1/customers/<Customer GUID>

Example:

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

Response:

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

List

List all customers

Method

GET

Endpoint

/v1/customers

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

Example:

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

Response:

{
    "items": [
        {
            "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"
        }
    ],
    "limit": 20,
    "offset": 0
}

List subscriptions

List all subscriptions owned by the customer

Method

GET

Endpoint

/v1/customers/<Customer GUID/subscriptions

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

List invoices

List all invoices owned by the customer

Method

GET

Endpoint

/v1/customers/<Customer GUID/invoices

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

List transactions

List all transactions owned by the customer

Method

GET

Endpoint

/v1/customers/<Customer GUID/transactions

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

Subscription

An entity of subscription relationship between customer and plan. Invoices will be generated for the customer automatically and periodically according to the configuration of plan.

Create

Create a subscription and return the entity. If the funding_instrument_uri is given, it will be used to charge or payout to customer, however, if it is omitted, an invoice without funding_instrument_uri will be generated. You can update the funding_instrument_uri of invoice later. This allows you to generate invoice without knowing funding_instrument_uri at first, defer the fee collection later. If started_at is given, the subscription will be scheduled at that date time, otherwise, current time will be the started time, also, an invoice will be filed immediately.

Method

POST

Endpoint

/v1/subscriptions

Parameters

plan_guid - The GUID of plan to subscribe
customer_guid - The GUID of customer to subscribe
funding_instrument_uri - (optional) The URI to funding source in Balanced, could be a tokenlized credit card or bank account URI
amount - (optional) The amount in USD cents of this subscription for overwriting the one from plan, useful for giving a discount to customer
started_at - (optional) The date time of this subscription to started at, should be in ISO 8601 format.
appears_on_statement_as - (optional) The statement to appears on customer's credit card or bank account transaction record

Example:

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"

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"
}

Retrieve

Retrieve a subscription entity

Method: GET
Endpoint: /v1/subscriptions/<Subscription GUID>

Example:

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

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"
}

Cancel

Cancel the subscription.

Method: POST
Endpoint: /v1/subscriptions/<Subscription GUID>/cancel

Example:

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

Response:

{
    "amount": null,
    "appears_on_statement_as": null,
    "canceled": true,
    "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"
}

List

List all subscriptions

Method

GET

Endpoint

/v1/subscriptions

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

Example:

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

Response:

{
    "items": [
        {
            "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"
        }
    ],
    "limit": 20,
    "offset": 0
}

List invoices

List all invoices owned by the subscription

Method

GET

Endpoint

/v1/subscriptions/<Subscription GUID/invoices

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

List transactions

List all transactions generated from invoices owned by the subscription

Method

GET

Endpoint

/v1/subscriptions/<Subscription GUID/transactions

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

Invoice

An invoice is an entity generated from a subscription periodically, or generated for a customer direcly. You should notice that when the plan of subscription is a payout plan, invoice will also be generated.

Create

Create an invoice for a customer and return the entity.

Method

POST

Endpoint

/v1/invoices

Parameters

customer_guid - The guid of customer
amount - The amount to charge customer
title - (optional) The title of this invoice
appears_on_statement_as - (optional) The statement to appears on customer's credit card or bank account transaction record
funding_instrument_uri - (optional) The URI to Balanced funding instrument to charge
items - (optional) The items which indicate service or goods to charge. Fields of an item:
- name - The name of item
- amount - The amount of item (will not affect invoice amount)
- type - (optional) The type of item (a short string), e.g. Bandwidth
- quanity - (optional) The quantity of item
- volume - (optional) The volume of item
- unit - (optional) The unit of item
The parameter key format is item_<field name><number>. For example, you have two items, hosting service A and hosting service B, then you can pass these two items with following key/value pairs of parameters
- item_name1=Hosting Service A
- item_amount1=1000
- item_name2=Hosting Service B
- item_amount2=3000
adjustments - (optional) The adjustments to be applied on this invoice. You should notice that adjustments will affect the effective amount of an invoice. It is useful for discounts or extra fee. There are only two fields for an adjustment:
- amount - The adjustment amount (will affect invoice effective amount)
- reason - (optional) The reason of adjustment, e.g. discount
Similiar to items, the URL encoding rule is adjustments_<field name><number>. For example, to give two discount adjustments, you can pass parameters like this
- adjustments_amount1=-1000
- adjustments_reason1=Coupon discount
- adjustments_amount2=200
- adjustments_reason2=Setup fee

Example:

curl https://billy.balancedpayments.com/v1/invoices \
    -X POST \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC: \
    -d "customer_guid=CU4NheTMcQqXgmAtg1aGTJPK" \
    -d "amount=1000" \
    -d "appears_on_statement_as=FooBar Hosting" \
    -d "item_name1=Hosting Service A" \
    -d "item_amount1=1000" \
    -d "adjustments_amount1=-100" \
    -d "adjustments_reason1=Coupon discount"

Response:

{
    "adjustments": [
        {
            "amount": -100,
            "reason": "Coupon discount"
        }
    ],
    "amount": 1000,
    "appears_on_statement_as": "FooBar Hosting",
    "created_at": "2014-02-08T08:22:15.073000+00:00",
    "customer_guid": "CU4NheTMcQqXgmAtg1aGTJPK",
    "effective_amount": 900,
    "external_id": null,
    "funding_instrument_uri": null,
    "guid": "IV4gVtDyP3CD9zQyv8AtPwx5",
    "invoice_type": "customer",
    "items": [
        {
            "amount": 1000,
            "name": "Hosting Service A",
            "quantity": null,
            "type": null,
            "unit": null,
            "volume": null
        }
    ],
    "status": "staged",
    "title": null,
    "total_adjustment_amount": -100,
    "transaction_type": "debit",
    "updated_at": "2014-02-08T08:22:15.073000+00:00"
}

Retrieve

Retrieve an invoice entity

Method: GET
Endpoint: /v1/invoices/<Invoice GUID>

Example:

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

Response:

{
    "adjustments": [
        {
            "amount": -100,
            "reason": "Coupon discount"
        }
    ],
    "amount": 1000,
    "appears_on_statement_as": "FooBar Hosting",
    "created_at": "2014-02-08T08:22:15.073000+00:00",
    "customer_guid": "CU4NheTMcQqXgmAtg1aGTJPK",
    "effective_amount": 900,
    "external_id": null,
    "funding_instrument_uri": null,
    "guid": "IV4gVtDyP3CD9zQyv8AtPwx5",
    "invoice_type": "customer",
    "items": [
        {
            "amount": 1000,
            "name": "Hosting Service A",
            "quantity": null,
            "type": null,
            "unit": null,
            "volume": null
        }
    ],
    "status": "staged",
    "title": null,
    "total_adjustment_amount": -100,
    "transaction_type": "debit",
    "updated_at": "2014-02-08T08:22:15.073000+00:00"
}

Update

An invoice can be created without a funding_instrument_uri. You can create an invoice first, send it to customer, and let them decide how to pay the bill. Once your customer decided to pay the bill, for example, with their credit card, you can then update the funding_instrument_uri of invoice to the tokenlized credit card number. Billy will then try to settle the invoice with given funding istrument. This could also be useful when previous funding_instrument_uri is incorrect, or something goes wrong while processing, such as there is no sufficient fund in the credit card. In that case, invoice will become failed eventually, and you can ask your customer for another method to pay the bill, and update the funding_instrument_uri again with the new instrument URI.

Method

PUT

Endpoint

/v1/invoices/<Invoice GUID>

Parameters

funding_instrument_uri - The funding instrument URI to update

Example:

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

Response:

{
    "adjustments": [
        {
            "amount": -100,
            "reason": "Coupon discount"
        }
    ],
    "amount": 1000,
    "appears_on_statement_as": "FooBar Hosting",
    "created_at": "2014-02-08T08:22:15.073000+00:00",
    "customer_guid": "CU4NheTMcQqXgmAtg1aGTJPK",
    "effective_amount": 900,
    "external_id": null,
    "funding_instrument_uri": "/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/cards/CCBXYdbpYDwX68hv69UH1eS",
    "guid": "IV4gVtDyP3CD9zQyv8AtPwx5",
    "invoice_type": "customer",
    "items": [
        {
            "amount": 1000,
            "name": "Hosting Service A",
            "quantity": null,
            "type": null,
            "unit": null,
            "volume": null
        }
    ],
    "status": "staged",
    "title": null,
    "total_adjustment_amount": -100,
    "transaction_type": "debit",
    "updated_at": "2014-02-08T08:22:15.073000+00:00"
}

Refund

Issue an refund to customer. Only settled invoices can be refunded.

Method

POST

Endpoint

/v1/invoices/<Invoice GUID>/refund

Parameters

amount - The amount to refund customer

Example:

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

Response:

{
    "adjustments": [
        {
            "amount": -100,
            "reason": "Coupon discount"
        }
    ],
    "amount": 1000,
    "appears_on_statement_as": "FooBar Hosting",
    "created_at": "2014-02-08T08:22:15.073000+00:00",
    "customer_guid": "CU4NheTMcQqXgmAtg1aGTJPK",
    "effective_amount": 900,
    "external_id": null,
    "funding_instrument_uri": "/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/cards/CCBXYdbpYDwX68hv69UH1eS",
    "guid": "IV4gVtDyP3CD9zQyv8AtPwx5",
    "invoice_type": "customer",
    "items": [
        {
            "amount": 1000,
            "name": "Hosting Service A",
            "quantity": null,
            "type": null,
            "unit": null,
            "volume": null
        }
    ],
    "status": "staged",
    "title": null,
    "total_adjustment_amount": -100,
    "transaction_type": "debit",
    "updated_at": "2014-02-08T08:22:15.073000+00:00"
}

List

List all invoices

Method

GET

Endpoint

/v1/invoices

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

Example:

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

Response:

{
    "items": [
        {
            "adjustments": [
                {
                    "amount": -100,
                    "reason": "Coupon discount"
                }
            ],
            "amount": 1000,
            "appears_on_statement_as": "FooBar Hosting",
            "created_at": "2014-02-08T08:22:15.073000+00:00",
            "customer_guid": "CU4NheTMcQqXgmAtg1aGTJPK",
            "effective_amount": 900,
            "external_id": null,
            "funding_instrument_uri": "/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/cards/CCBXYdbpYDwX68hv69UH1eS",
            "guid": "IV4gVtDyP3CD9zQyv8AtPwx5",
            "invoice_type": "customer",
            "items": [
                {
                    "amount": 1000,
                    "name": "Hosting Service A",
                    "quantity": null,
                    "type": null,
                    "unit": null,
                    "volume": null
                }
            ],
            "status": "staged",
            "title": null,
            "total_adjustment_amount": -100,
            "transaction_type": "debit",
            "updated_at": "2014-02-08T08:22:15.073000+00:00"
        }
    ],
    "limit": 20,
    "offset": 0
}

List transactions

List all transactions generated from the invoice

Method

GET

Endpoint

/v1/invoices/<Invoice GUID/transactions

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

Transaction

Transactions are entities generated from an invoice. It represents transactions we submited to underlying payment processor. A transaction has attributes like the current submit status, status of transaction in processor, type of transaction, amount, funding instrument URI and failures. The submit state transition of a transaction is shown in following diagram.

For all status:

STAGED - just created transaction

RETRYING - attempt to submit but failed, retrying

CANCELED - the invoice is canceled before the transaction is done or failed

FAILED - the transaction failure count exceeded limitation

DONE - the transaction is submitted successfully

Retrieve

Retrieve a transaction entity

Method: GET
Endpoint: /v1/transactions/<Transaction GUID>

Example:

curl https://billy.balancedpayments.com/v1/transactions/TX4SVWm156bBTSY17KJKW88y \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC:

Response:

{
    "amount": 500,
    "appears_on_statement_as": null,
    "created_at": "2014-02-08T08:22:11.792000+00:00",
    "failure_count": 0,
    "failures": [],
    "funding_instrument_uri": "/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/cards/CCBXYdbpYDwX68hv69UH1eS",
    "guid": "TX4SVWm156bBTSY17KJKW88y",
    "invoice_guid": "IV4SUGxQ3hu2ZB6FU5NXNj4u",
    "processor_uri": "/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/debits/WDFd93gSV8Sb27bUP5GREjt",
    "status": "succeeded",
    "submit_status": "done",
    "transaction_type": "debit",
    "updated_at": "2014-02-08T08:22:15.047000+00:00"
}

List

List all transactions

Method

GET

Endpoint

/v1/transactions

Parameters

offset - Offset for pagination, default value is 0
limit - Limit for pagination, default value is 20

Example:

curl https://billy.balancedpayments.com/v1/transactions \
    -u 5MyxREWaEymNWunpGseySVGBZkTWDW57FUXsyTo2WtGC:

Response:

{
    "items": [
        {
            "amount": 500,
            "appears_on_statement_as": null,
            "created_at": "2014-02-08T08:22:11.792000+00:00",
            "failure_count": 0,
            "failures": [],
            "funding_instrument_uri": "/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/cards/CCBXYdbpYDwX68hv69UH1eS",
            "guid": "TX4SVWm156bBTSY17KJKW88y",
            "invoice_guid": "IV4SUGxQ3hu2ZB6FU5NXNj4u",
            "processor_uri": "/v1/marketplaces/TEST-MP6lD3dBpta7OAXJsN766qA/debits/WDFd93gSV8Sb27bUP5GREjt",
            "status": "succeeded",
            "submit_status": "done",
            "transaction_type": "debit",
            "updated_at": "2014-02-08T08:22:15.047000+00:00"
        }
    ],
    "limit": 20,
    "offset": 0
}

FilesExpand file tree

api_reference.rst

Latest commit

History

api_reference.rst

File metadata and controls

REST API reference

Company

Create

Retrieve

Plan

Create

Retrieve

Delete

List

List customers

List subscriptions

List invoices

List transactions

Customer

Create

Retrieve

Delete

List

List subscriptions

List invoices

List transactions

Subscription

Create

Retrieve

Cancel

List

List invoices

List transactions

Invoice

Create

Retrieve

Update

Refund

List

List transactions

Transaction

Retrieve

List