It's really frustrating how in 2014 almost everybody is still writing API definitions which are only human-readable. Two worthy exceptions:
- https://github.com/balanced/balanced-api
- https://helloreverb.com/developers/swagger
You can have self-describing messages without having to embed the schema in the instance. Instead you embed a reference to the schema in the message. We came up with an approach to this called self-describing JSONs: http://snowplowanalytics.com/blog/2014/05/15/introducing-sel... The Avro community do something similar.
In Transit – A format for conveying values between different languagesbalanced
balanced-api
Ruby2012–2014
balanced / balanced-api
balanced-api
Balanced API specification.
15Distinct people
50Mentions
0Explicit recommenders
220GitHub stars
What to know before exploring
What it is
Balanced API specification.
GitHub
Where it is used
No documented product use was verified in the last source check.
What people are saying
No recommendation phrase was found in the indexed comments.
No classified warning is attached to this page. Read the discussions before treating silence as approval.
Also in these discussions
No other repository is repeatedly linked in the same discussions.
This week on Hacker News
Nov 7–Nov 14 UTC · Direct repository links and separately labeled related project stories. Indexed through 11/14/2026, 12:54:37 PM UTC.
No direct repository links were found in the indexed HN discussions over the past seven days. Older discussions are available below.
Mentions over time
HN mentions by month50 dated mentions
Observed mentions: 2012-08-17 19:37:53 UTC to 2014-07-22 19:16:43 UTC.
Counts come from the repository’s dated source evidence. Index cutoff: 2026-11-02 08:16:59 UTC.
View mention counts and date ranges
| Period | Start (UTC) | End (exclusive, UTC) | Mentions | Submissions | Comments |
|---|---|---|---|---|---|
| Aug 2012 | 2012-08-01 00:00:00 UTC | 2012-09-01 00:00:00 UTC | 3 | 2 | 1 |
| Sep 2012 | 2012-09-01 00:00:00 UTC | 2012-10-01 00:00:00 UTC | 0 | 0 | 0 |
| Oct 2012 | 2012-10-01 00:00:00 UTC | 2012-11-01 00:00:00 UTC | 0 | 0 | 0 |
| Nov 2012 | 2012-11-01 00:00:00 UTC | 2012-12-01 00:00:00 UTC | 7 | 2 | 5 |
| Dec 2012 | 2012-12-01 00:00:00 UTC | 2013-01-01 00:00:00 UTC | 2 | 0 | 2 |
| Jan 2013 | 2013-01-01 00:00:00 UTC | 2013-02-01 00:00:00 UTC | 3 | 0 | 3 |
| Feb 2013 | 2013-02-01 00:00:00 UTC | 2013-03-01 00:00:00 UTC | 10 | 1 | 9 |
| Mar 2013 | 2013-03-01 00:00:00 UTC | 2013-04-01 00:00:00 UTC | 1 | 0 | 1 |
| Apr 2013 | 2013-04-01 00:00:00 UTC | 2013-05-01 00:00:00 UTC | 2 | 0 | 2 |
| May 2013 | 2013-05-01 00:00:00 UTC | 2013-06-01 00:00:00 UTC | 2 | 0 | 2 |
| Jun 2013 | 2013-06-01 00:00:00 UTC | 2013-07-01 00:00:00 UTC | 2 | 0 | 2 |
| Jul 2013 | 2013-07-01 00:00:00 UTC | 2013-08-01 00:00:00 UTC | 0 | 0 | 0 |
| Aug 2013 | 2013-08-01 00:00:00 UTC | 2013-09-01 00:00:00 UTC | 0 | 0 | 0 |
| Sep 2013 | 2013-09-01 00:00:00 UTC | 2013-10-01 00:00:00 UTC | 0 | 0 | 0 |
| Oct 2013 | 2013-10-01 00:00:00 UTC | 2013-11-01 00:00:00 UTC | 0 | 0 | 0 |
| Nov 2013 | 2013-11-01 00:00:00 UTC | 2013-12-01 00:00:00 UTC | 1 | 0 | 1 |
| Dec 2013 | 2013-12-01 00:00:00 UTC | 2014-01-01 00:00:00 UTC | 1 | 0 | 1 |
| Jan 2014 | 2014-01-01 00:00:00 UTC | 2014-02-01 00:00:00 UTC | 7 | 0 | 7 |
| Feb 2014 | 2014-02-01 00:00:00 UTC | 2014-03-01 00:00:00 UTC | 1 | 0 | 1 |
| Mar 2014 | 2014-03-01 00:00:00 UTC | 2014-04-01 00:00:00 UTC | 2 | 0 | 2 |
| Apr 2014 | 2014-04-01 00:00:00 UTC | 2014-05-01 00:00:00 UTC | 1 | 0 | 1 |
| May 2014 | 2014-05-01 00:00:00 UTC | 2014-06-01 00:00:00 UTC | 4 | 0 | 4 |
| Jun 2014 | 2014-06-01 00:00:00 UTC | 2014-07-01 00:00:00 UTC | 0 | 0 | 0 |
| Jul 2014 | 2014-07-01 00:00:00 UTC | 2014-08-01 00:00:00 UTC | 1 | 0 | 1 |
From the project README
An excerpt from the repository, fetched Nov 13, 2026.
Read the project’s introduction
Balanced API Specification
This repository contains an executable specification of the Balanced API. The
goal of this repository is two-fold. First, to ensure that the API is working
according to the spec. Second, to provide a place to have discussions around
the API as a product.
An Executable Specification
Specifications don't matter if they're not followed. Therefore, this
specification is executable, so we can ensure conformance to the spec. There are
more details in the README file inside the features directory, but to run these
tests yourself, simply:
$ git clone https://github.com/balanced/balanced-api.git
$ cd balanced-api
$ bundle
$ bin/rake cucumber
This requires Ruby. We run the changes with Ruby 2.0, but other versions will
probably work as well. Let us
know if you have any
problems running these specs, and we'd be happy to help.
If you're working on a new scenario, the 'focus' task is useful. Tag a scenario
with @focus, and then run bin/rake focus. It will only run that single scenario.
Discussions around changes
Speaking of issues, that's the second purpose of this repository. If you would
like to see a new feature implemented in the Balanced API, please open an
issue and we'll discuss
it.
For example, one of our biggest requests is to support non-USD currencies.
Here is the issue with
the discussion, and when we support this feature, we close the issue via a pull
request that implements the specification, and then everyone on the issue gets
notified.
Sometimes, Issues are great for collecting feedback, as well. For example,
all implementation of the current framework was done via
PR, and some issues need
more explanation around use cases by those who want the feature, like Bitcoin
support.
We try to do as much 'internal' discussion in these issues as well, it's not
just for public feedback. If you want to know what we're thinking, just search
for a relevant issue!
Edit field descriptions for scenarios
Field descriptions are from balanced.rev1.json, which are generated from
balanced-api. The "forms" used in balanced-docs are assembled from parameters
supplied in the scenarios in balanced-api. Those scenarios should be
updated to include the fields missing the specific scenario section and a
newly generated balanced.rev1.json be committed into the docs. To generate
balanced.rev1.json in balanced-api run:
bundle exec rake features:all
DO NOT run
bundle exec rake parallel:features
doing so causes the file to overwrite itself.
Read the full README on GitHubWhat Hacker News says
50 sources"I have sufficient funds in my marketplace" is defined here: https://github.com/balanced/balanced-api/blob/master/feature...
Given(/^I have sufficient funds in my marketplace$/) do
step 'I have tokenized a card'
@client.post("/cards/#{@card_id}/debits", {
amount: 500000
})
end
Here's another example from the scenario above:
Given(/^I have a tokenized debit card$/) do
@client.post('/cards',
{
name: "Johannes Bach",
number: "4342561111111118",
expiration_month: "05",
expiration_year: "2015"
}
)
@debit_card_id = @client['cards']['id']
@client.add_hydrate(:debit_card_id, @debit_card_id)
end
In TDD your APIHere's an example of how we do it:
The scenario: https://github.com/balanced/balanced-api/blob/master/feature...:
Scenario: Push money to an existing debit card
Given I have sufficient funds in my marketplace
And I have a tokenized debit card
When I POST to /cards/:debit_card_id/credits with the JSON API body:
"""
{
"credits": [{
"amount": 1234
}]
}
"""
Then I should get a 201 Created status code
And the response is valid according to the "credits" schema
And the fields on this credit match:
"""
{
"status": "succeeded"
}
"""
And the credit was successfully created
There's several things in there like "And I have a tokenized debit card" that setup the scenario to be able to do things like "/cards/:debit_card_id/credits", which r
Read the rest
efers to an actual card ID created in the test API.
It's really, really nice to see an API with all the validating JSON Schemas publically available[1]. I wish everybody did this.
We have been doing a lot of thinking at Snowplow [2] [3] about JSON Schema versioning and self-description. One of the key points as it relates to RESTful APIs is: it's not enough to version your API, you should be versioning the individual entities that your API returns; these entities should be able to individually evolve over time, with the focus on evolving the entities' schemas in additive (i.e. non-breaking ways) for existing clients.
There's quite a lot to learn from the Avro community in all this.
[1] https://github.com/balanced/balanced-api/tree/master/fixture...
[2] http://snowplowanalytics.com/blog/2014/05/13/introducing-sch...
[3] http://snowplowanalytics.com/blog/2014/05/15/introducing-sel...
In TDD your APINo daily limits.
Visa limits the transactions to $2,500 per transaction. Other networks don't have as well defined of a limit. We set the $2,500 limit in the API to set a reasonable expectation. We'll learn more about the limits over time and document it here: https://github.com/balanced/balanced-api/issues/603
In Send money to a customer’s checking account using their debit card numberHi theflyingkiwi42. I'm a co-founder of Balanced. Happy to answer whatever questions you have about our product and hear how we can make Balanced's ACH products better, but don't want to derail this thread. Would you mind commenting on one, or more, of our ACH related GitHub issues [1]? Or you can email support@balancedpayments.com to expand on your thoughts here. Cheers!
-jkw
[1] https://github.com/balanced/balanced-api/search?q=ach&ref=cm...
In How ACH works: A developer perspectiveTotally. Our experience around checks has been interesting: basically, there are some customers who absolutely do not want anything but a check. They've been using checks their entire life, and they don't want to change. Fair enough.
Some other people just simply don't understand how _quickly_ they can get money via ACH. It's a matter of venturing into the unknown vs. what's tried and true. So when we say "You'll get your money today, in your bank account, if you use Wells Fargo, and tomorrow otherwise," they say "really?" And decide ACH is good enough for the cost. Then again, that's on the payout side rather than the pay-in side, though I guess if your website accepted payment via check, it'd be much faster there, too.
There are also all kinds of other complications in dealing with paper checks that may make it worth the $5. Here's the
Read the rest
issue where we talk about Balanced and paper checks, and this comment in particular is very insightful: https://github.com/balanced/balanced-api/issues/69#issuecomm... Checks are also not reversible, which we feel is a significant drawback.
Anyway, no matter what you do, feel free to ping me if you have any questions payments related: I've really enjoyed learning this domain, there's so many details, and they're all so important...
Hey Jerome! I work at Balanced.
We won't be supporting wire transfers: https://github.com/balanced/balanced-api/issues/267
As our CEO says in that thread, given that we do same-day payouts to Wells Fargo and next-day payouts to all other banks, we think ACH debits are a better use-case than a wire transfer in this scenario.
To handle your case with ACH debits, you would debit the bank account, it would go into our escrow, and then when the seller ships, you would pay them out.
Now, for one or two other things:
We absolutely support the ability to do an authorization and then a capture: we call it a 'hold', since we provide both ACH and credit card processing. Holds are free, and you pay the same price when you capture as when you do a regular charge: https://www.balancedpayments.com/pricing
And we put a limit of seven days for a hold. As
Read the rest
you've asked, credit card companies don't like seeing lots of voided holds: you've basically frozen someone's funds for a period of time. Doing it often generally means something else is going wrong.
I just left a comment regarding this on GitHub: https://github.com/balanced/balanced-api/issues/204#issuecom...
(I work at Balanced and managed this partnership.)
In Balanced Partners With Coinbase and Adds Bitcoin Support(Balanced co-founder here)
Good suggestion. We'll work on adding that [1]. Right now, we have those interested +1 on a GitHub issue tread [2], so we can contact them later, but you're right something a bit cleaner would be easier for you and us.
[1] https://github.com/balanced/www.balancedpayments.com/issues/...
[2] https://github.com/balanced/balanced-api/issues/23
In Payments Startup Stripe (YC S10) Joins the Billion Dollar ClubSteve from Balanced here. I'm in charge of the API.
You can look at this comparison in a few ways. We share a lot of the same investors: Both YC, SV Angel, a16z, etc. They've gotten a lot more funding than we have, and so have a bigger team.
You get paid faster with Balanced: we have _same day_ payouts to Wells Fargo customers, and _next day_ payouts to any other bank. Stripe is seven days.
Feature wise, we provide a lot of the same things, but Balanced has more. We support ACH debits AND credits, for example, and Stripe only supports credits. We're soon adding push-to-card as well. We have escrow, and let you choose how long to hold funds in it.
Speaking of escrow, in general, we have lots of extra features for marketplaces, since that's our bread and butter. Stripe now has a marketplace product, Connect, but it basically requires all of
Read the rest
your sellers to sign up for Stripe. Our customers tell us that white label is important, and so Balanced is 100% white labeled. We individually underwrite all sellers, and we give you full control over your descriptor, on a per-transaction basis.
Our fee structure is 100% transparent, and the same for everyone. You can negotiate with Stripe on your rates, ours are just published publicly: https://www.balancedpayments.com/pricing
In general, Balanced is striving to be as open and transparent as possible: new feature discussion is done in the open, on GitHub. As I just mentioned, our pricing is transparent. We're working with Gittip and several other companies to start the Open Company Initiative[1] to help promote general open-ness. Loving that internal transparency from Stripe with their emails. [2]
To say some more good things about Stripe, they have launched in a few places internationally, and we are still US only. We can accept foreign credit cards, but merchants need to be in the US.[3] Hoping to fix that, regulations are hard.
Stripe has a loyal fanbase for a reason: they do a great job. I really appreciate the clarity of their docs, for example. Patrick, I know you're as much of an HN junkie as I am: congrats on the raise. Let's all keep dragging the payments industry kicking and screaming into the future. ;)
Here's some links from others, comparing the two of us:
* http://blog.localon.com/2013/11/21/why-we-switched-from-stri...
* http://blog.apixchange.com/2013/10/why-api-xchange-uses-bala...
* http://www.quora.com/Balanced/How-does-Balanced-compare-agai...
* http://stackoverflow.com/questions/14289347/stripe-vs-balanc...
As always, you can reach me here on at steve@balancedpayments.com to talk about any of this more.
1: http://opencompany.biz , though we just chipped in for .org: https://github.com/opencompany/www.opencompany.org/issues/59
2: https://stripe.com/blog/email-transparency
3: https://github.com/balanced/balanced-api/issues/23
Gotcha. Thanks, I thought you meant sending BTC to cards somehow.
Cryptocurrency exchange is currently against our terms, "Prohibited Transactions" -> "(18) currency exchanges or dealers" and "(49) virtual currency or credits that can be monetized, re-sold or converted to physical or digital goods or services or otherwise exit the virtual world," in https://www.balancedpayments.com/terms/selleragreement . This is due to our upstream providers.
We're interested in working with them to work around such things, but haven't been able to yet: https://github.com/balanced/balanced-api/issues/204
I've been heavily involved in Dogecoin, and I'd love to see BTC/LTC/DOGE payments, but there's a lot of unresolved questions.
In Balanced Will Release an API to Push Money to Debit CardsThis was opened 11 months ago:
https://github.com/balanced/balanced-api/issues/268
But it appears it was updated just yesterday by someone with WP experience, so maybe it will be done soon? Would love to test it out.
In Payments Startup Balanced (YC W11) Is Processing $370M a YearWe do! We haven't committed to a timeline, but you can track progress at these two links:
* https://github.com/balanced/balanced-api/issues/23
* https://github.com/balanced/balanced-api/issues/294
Also, we can accept credit card _payments_ from anywhere in the world. It's paying money out that's the hard part.
In Payments Startup Balanced (YC W11) Is Processing $370M a YearHi rbitton,
Balanced employee here.
>> I found the process of actually taking and charging a card to be a bit cumbersome with having to tokenize the card (wait for response), create the customer record (wait for response), associate the card token (wait for response), and finally create the debit (wait for response).
Couldn't agree more. Tracking this issue here: https://github.com/balanced/balanced-api/issues/472. We will have news very shortly on some changes that you might be interested in.
>> I also like Stripe's two-factor authentication support.
This is already done AFAIK. Email me directly -- m@balancedpayments.com
>> And, on another note, I was a bit disappointed with both Balanced and Stripe's iOS libraries. They only support tokenizing a card. Though this is likely going to be the bulk of use by many people it meant creating eve
Read the rest
rything else from scratch.
May I ask that you open a github issue on https://github.com/balanced/balanced-ios with exactly what you're looking for?
Thank you very much.
Showing the 15 most recent of 50 sources. Enable JavaScript to search and browse every indexed mention.