balanced / balanced-docs Goto Github PK
View Code? Open in Web Editor NEWBalanced's API Documentation
Home Page: https://docs.balancedpayments.com/
Balanced's API Documentation
Home Page: https://docs.balancedpayments.com/
I cannot seem to find any mention in the docs about how to do this.
Reading the documentation for creating a merchant, it's hard to understand exactly what to pass when creating a business. The person documentation is very concise but not so for a business.
Also:
For business merchants dob is optional, defaulting to null.
street_address
is not mandatory but posting to the API says otherwise.A working JSON payload would clear this up.
(migrated from balanced/balanced-api#164)
I was chatting with Mahmoud this evening about a trouble I had with the
Merchant Underwriting process with PHP. I have now resolved my issue, but
thought you may want to clarify the documentation. In the PHP example (seen
herehttps://www.balancedpayments.com/docs/overview?language=php#merchant-underwriting)
the '$account' variable uses CreateAccount without passing the merchant
data parameters, but rather uses promoteToMerchant. This function does not
seem to pick up the merchant_data array. The account would be created, but
all the details were blank when I viewed the new account in my portal.
Original:
$account = $marketplace->createAccount();
Here is my fix:
$account = $marketplace->createMerchant($email, $merchant_data);
There may be issues with my solution, but it seems to work.
Reported by Hank
From @travisp,
Hello,
Just wanted to tell you that there was an error in your documentation for
your client side validation helpers for bank accounts (it doesn't work)https://www.balancedpayments.com/docs/overview?language=bash#client-side-validation-helpers
Correct code:
https://gist.github.com/travisp/5320330
Also, it says it performs a sanity check on the account number and name
(somehow), but accepts "8887776665555sdfsdf" as a valid account number
how long does a bank account verification take? time between initiating a verification and the ability to use it?
Balanced requires marketplaces to include a snipper of the Balanced TOS in their own. The snippet is included in the marketplace agreement. Balanced should include the marketplace agreement in the docs, so developers can easily find it.
Paul Alexander reported that our merchant business underwriting docs are incorrectly displaying that tax_id
and person
is optional, when in fact it is required.
pilo
is doing the wrong thing here.
Also, clarify that the person is just a representative of the company underwriting the business on Balanced, not necessarily the business owner.
From balanced/balanced-api#137
"""Creating and/or updating merchant is not as simple as creating a buyer, and the docs don't seem to cover everything in the level of detail that I would have hoped. There seem to be numerous cases that need to be handled -- does the user have an account in the marketplace already, does the user have the merchant role already, do you need to update the merchant acount when the user changes his email or address, etc.
In lieu of a solid working example (preferably in Python/Django), some pseudo-code would suffice. I know it would have saved me a lot of time."""
And note Marshall’s gist: https://gist.github.com/3820242
I've heard from some YC founders that putting a TRUSTe badge on your checkout page leads to a 3-5% increase in conversions -- actually using your own badge that looks similar to a TRUSTe badge seems to do the trick as well. And two badges are better than 1.
I suggest Balanced build a trust badge in addition to our "powered by balanced" badge
Originally opened in the api repo (balanced/balanced-api#234)
From balanced-api #18
"Refunds typically take one business day to reflect on a card statement, but it's possible for the issuing bank to take five business days to process the refund. Balanced should document this constraint in the banking system as a reference for marketplaces."
Currently the docs explain the concept of errors but there is no comprehensive list of all the errors that exist. Well, there is a list of errors, but it's not linked to.
Migrated from balanced/balanced-api#209
from @mjallday:
It's probably best to just associate the account_uri with a local user ID. everything else can be derived from that account_uri. However, if you want to display transactions in real time then it will be slow so you may want to keep debit_uris locally as well.
and @bradfordb commented (balanced/balanced-api#209 (comment))
It seems that "hash" is a great source of confusion, and understandably so as it's not explained anywhere in the documentation.
I think it would be worthwhile to explain what it is, how it's composed and what purpose it serves.
For underwriting a merchant, the docs say that the tax_id is optional but its required.
Several people have asked recently how they can find an account. While this call can be deduced from other examples in the API documentation, it could be clearer.
Add an API documentation section with examples to make this clear since similar sections exist for retrieving credits, debits, verifications and so on.
18:16 < ajsharp> It says to create a merchant we have to pass in either a bank account uri or a bank account object. Is that correct? https://github.com/balanced/balanced-api/blob/master/resources/accounts.rst
18:19 < ajsharp> mjallday: ^^
18:19 < mjallday> hey mate, one second...
18:20 < ajsharp> np
18:21 < mjallday> ajsharp: looks like an inacuracy in the docs, i just tried it and it works fine without the bank account
From the documentation
Exactly one of
bank_account_uri
string. The URI of the bank account created via balanced.js. Ignored if not updated.
POSTing merchant data to the API without a bank account clearly works fine however:
curl -X POST https://api.balancedpayments.com/v1/marketplaces/TEST-MP6IEymJ6ynwnSoqJQnUTacN/accounts \
-u 7b7a51ccb10c11e19c0a026ba7e239a9: \
-d email_address="[email protected]" \
-d merchant[type]="person" \
-d merchant[name]="William James" \
-d merchant[street_address]="801 High St" \
-d merchant[postal_code]="94301" \
-d merchant[country]="USA" \
-d merchant[dob]="1842-01" \
-d merchant[phone_number]="+16505551234"
(migrated from balanced/balanced-api#162)
GET https://api.balancedpayments.com/v1/marketplaces/:marketplace_id/holds
is not correct for getting holds for account the Request i correct for the above
curl https://api.balancedpayments.com/v1/marketplaces/TEST-MP5cTJW1r4snN0IJaY9fyMov/accounts/AC5F0v74Q8Fwh344QWMdhV8Q/holds?limit=2
-u ab0d51063dab11e28e50026ba7cd33d0:
(migrated from balanced/balanced-api#211)
I've processed a couple of charges, and while my balance has gone up the credit card processing fees do not appear in my account.
There's really very sparse information on how to use meta
on the resources. We briefly address this here: https://balancedpayments.com/docs/overview?language=bash#using-meta-for-fraud and in some parts of the https://balancedpayments.com/docs/api reference.
We need to really document meta to demonstrate the capabilities of the meta
field.
ping @zealoushacker
From balanced-api #10
We need to explain what underwriting is and why it matters.
"Specifically the concept of underwriting a merchant is pretty foreign to most payments services.
Balanced underwrites sellers/recipients as merchants to comply with payment aggregation compliance policies. Otherwise, the marketplace would become an aggregator. There's a explanation of the ramifications on Gittip #67.
The API has to validate the identity of the seller to underwrite them as a merchant, which requires, at minimum, the legal name, home address, and DOB. This information is verified against external data sources, but Balanced doesn't currently explain this process well or return very useful messages in the API response."
In the balanced-ruby gem examples.rb, a merchant account is created this way:
merchant = marketplace.create_merchant(
:email_address => "[email protected]",
:merchant => {
:type => "person",
:name => "Billy Jones",
:street_address => "801 High St.",
:postal_code => "94301",
:country => "USA",
:dob => "1842-01",
:phone_number => "+16505551234",
},
:bank_account_uri => bank_account.uri,
:name => "Jack Q Merchant",
)
This appears to both create and underwrite the merchant simultaneously. The overview/tutorial documentation, however, explains how to create just an account with no extra credentials, and then "promote" the associated account to a merchant:
require 'balanced'
Balanced.configure('099e55e07f7311e2b923026ba7c1aba6')
marketplace = Balanced::Marketplace.my_marketplace
merchant_data = {
:phone_number => '+14089999999',
:name => 'Timmy Q. CopyPasta',
:dob => '1989-12',
:postal_code => '94110',
:type => 'person',
:street_address => '121 Skriptkid Row',
}
account = Balanced::Marketplace.my_marketplace.create_account
begin
account.promote_to_merchant(merchant_data)
rescue Balanced::MoreInformationRequired => error
# could not identify this account.
puts 'redirect merchant to: ' + error.redirect_uri
rescue Balanced::Error => error
# TODO: handle 400 and 409 exceptions as required
raise
end
It would be handy to see both explanations along with reasons why a developer would want to choose the different paths.
Balanced provides 1099s for merchants that sell through marketplaces.
As I was going through the docs, I noticed the How Does Balanced Take Its Cut? section under Pricing was empty.
/cc @mahmoudimus
Migrated from balanced-api/issues/17.
From Wikipedia:
Authorization hold (also card authorisation, preauthorization, or preauth) is the practice within the banking industry of authorizing electronic transactions done with a debit card or credit card and holding this balance as unavailable either until the merchant clears the transaction (also called settlement), or the hold "falls off." In the case of debit cards, authorization holds can fall off the account (thus rendering the balance available again) anywhere from 1–5 days after the transaction date depending on the bank's policy; in the case of credit cards, holds may last as long as 30 days, depending on the issuing bank.
There needs to be communication through the API and/or documentation about when a hold is likely to drop off. The most problematic are prepaid and debit cards where there's real money being held by the bank.
A minimal solution would be to add a brief explanation and link to Wikipedia.
The next step could be to return the card type (prepaid, debit, charge, etc.) in the cards
resource since the type is what generally determins the period required for the hold to fall off.
"Provide an HTML for in the documentation that follows best practices and integrates balanced.js to create a new bank account."
https://balancedpayments.com/docs/overview?language=bash#pricing
Does not cover the pricing of holds as .30C.
extending balanced/balanced-api#21
We really need basic documentation explaining how filtering/sorting works in the API, and how to use it from various client libraries.
Also: "Currently it's a game of trial and error to know which fields can be filtered on."
From balanced/balanced-api#218
Ideally, the documentation should be readable from phones, tablets, netbooks, etc.
/marketplaces/:marketplace/accounts/:account/cards
/marketplaces/:marketplace/accounts/:account/bank_accounts
These two API endpoints apparently don't have any documentation. I believe @mahmoudimus has the docs written in his fork, and they just need to be merged.
migrated from balanced/balanced-api#230
ping @josephwegner
The API documentation for holds incorrectly includes the appears_on_statement_as
field.
appears_on_statement_as
is only used when creating a debit.
(migrated from balanced/balanced-api#161)
The API spec has a fields section where all of the fields are listed. There should be a similar section with more detailed information.
Developers tend to get stuck on how to process batch orders (nightly). Write a simple application that demonstrates this.
Right now, it's not very clear re: the sections on what we have to do.
Can we move this link: https://www.balancedpayments.com/docs/dashboard to the overview page?
ping @jrus
All the contents of that page should be moved to the overview page.
The documentation isn't clear about how to associate/earmark a debit for a particular merchant.
Examples for the various client libraries as well as via the API would be good. Also, how are complex edge cases handled such as multiple merchants being associated with a single debit? If I create a single debit for $10 and there are 2 merchants associated, the first gets $4 and the second $5 ($1 goes to MP), how would I do this?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.