balanced/balanced-docs

Balanced's API Documentation

balanced-docs's Issues

Allow previewing the generated spec

Balanced underwriting merchants doc error

For underwriting a merchant, the docs say that the tax_id is optional but its required.

Warn on bank account validation in javascript to not issue warning

Explain when fees are charged

• When is the chargeback fee invoiced?
• Does the chargeback fee get returned if the chargeback is successfully disputed?
• When is a failed credit fee invoiced?

add contributers file

document filtering/sorting, including which fields can be filtered/sorted

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

Explain "How Does Balanced Take Its Cut?"

As I was going through the docs, I noticed the How Does Balanced Take Its Cut? section under Pricing was empty.

/cc @mahmoudimus

Add marketplace agreement to the docs

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.

How can I simulate the merchant redirect flow in the test environment?

I cannot seem to find any mention in the docs about how to do this.

Outline the overview of each resource in the reference

The API spec has a fields section where all of the fields are listed. There should be a similar section with more detailed information.

Add Section for Retrieve An Account

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.

Add marketplace merchant dashboard link to the overview documentation

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.

Build sample ACH form

balanced/balanced-api#187

"Provide an HTML for in the documentation that follows best practices and integrates balanced.js to create a new bank account."

Firefox Rendering Issues

Processing fees are not appearing in my dashboard

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.

Explain Underwriting

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

Enumerate or link to all possible errors

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.

Docs: Hold create form includes appears_on_statement_as

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)

Document how to simulate a underwriting failure (300 redirect)

Our old docs show this (Ruby, Python, PHP), but not our new ones!

Also relevant: #39

bank account verifications

how long does a bank account verification take? time between initiating a verification and the ability to use it?

Allow for interlinking of overview and api reference for sphinx

Need create / update merchant example that handles all exceptions

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

Write step-by-step protocol for adding new clients into the documentation

Use responsive layout for documentation (make docs HTML/CSS work on mobile devices & small screens)

From balanced/balanced-api#218

Ideally, the documentation should be readable from phones, tablets, netbooks, etc.

account->cards/bank_accounts Documentation

/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

Document what the best practices are for URIs and fields to store in databases

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))

New API documentation incorrect to list Holds for accounts

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)

Show an example of how to batch process orders for developers

Developers tend to get stuck on how to process batch orders (nightly). Write a simple application that demonstrates this.

Document bank processes for voiding an authorization hold Edit

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.

client side validation helpers for bank accounts are incorrect

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

Clearly explain multiple ways to underwrite merchant

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 => "[phone]",
},
: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 => '[phone]',
   :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.

Docs: Business merchant create example unclear

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.

• Is email address required within the merchant payload too?
• Person says 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)

Balanced Merchant Underwriting for Business Optional/Required confusion

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.

Clarify what "hash" is in the docs

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.

Build screencasts for documentation / integration

http://www.techsmith.com/camtasia.html
http://www.araelium.com/screenflick#4
http://lifehacker.com/5878458/the-best-screencasting-app-for-mac-os-x

Amount formatting is weird for Creating A New Debit

https://www.balancedpayments.com/docs/api?language=ruby#create-a-new-debit

Issue with PHP's merchant underwriting example.

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

Add Holds pricing to tables

https://balancedpayments.com/docs/overview?language=bash#pricing

Does not cover the pricing of holds as .30C.

1099 Processing

Balanced provides 1099s for merchants that sell through marketplaces.

• How often are these generated
• How are marketplace fees calculated
• Are they sent straight to the merchants or does the marketplace have to distribute them

Charging best practices (in overview)

• Can I delete a card?
• How do I handle the scenario for deleting a card?
• How do I build an Amazon-like credit card picking scenario?
• How do card defaults work?

Scenarios need to be officially specced and implemented per client

Provide a Balanced trust badge

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

Here's the TRUSTe badge:

Originally opened in the api repo (balanced/balanced-api#234)

Better explain how to associate merchants with debits

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?

Document upper bounds on transaction sizes

Docs: Merchant inaccuracy

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]="[phone]"

(migrated from balanced/balanced-api#162)

Have a going live checklist in the documentation

• Read merchant underwriting/KYC requirements
• Verify the use of best practices
• Change API key to production API key
• Change application marketplace URI to production marketplace URI
• Include marketplace agreement in terms of service
• Use SSL
• Include a "Powered by Balanced" badge on the site footer or checkout page
• Include the credit card brand logos on the checkout page

document the typical period of time required for a refund

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

Need documentation for 300 response status code on merchant account create docs page

From @ajsharp

https://github.com/balanced/balanced-api/blob/master/resources/accounts.rst

Migrated From: balanced/balanced-api#145

Re-organize the overview for easier to structure and quickstart

Right now, it's not very clear re: the sections on what we have to do.

More information on how to use the meta field on resources.

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