Navigation

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 a setup for recurring charing or paying out, it contains the amount to charge or payout and the frequency of generating invoices.

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.

_images/transaction_state_diagram.png

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
}

Table Of Contents

Related Topics

This Page

© Copyright 2013, Balanced Payments. Created using Sphinx 1.2.