Balanced currently doesn't return the results of the Address Verification Service (AVS). The API makes a risk based regardless if AVS passes or not, but it can be helpful for the marketplace to understand why a transaction was rejected.

Here's a comprehensive list of possible AVS results:
https://github.com/Shopify/active_merchant/blob/master/lib/active_merchant/billing/avs_result.rb

Note that only US and UK banks support AVS, so it would only be returned for any non-US/UK cards.

Currently, the minimum amount for a credit is 50cents.

This needs to be removed for credits to owner accounts as The marketplace owner may make less than this per transaction. If they have to wait until there is >= 50 cents in their escrow account before transferring then it requires the marketplace to do accounting on their side.

We are building a transaction history feature into Copious, and we'd like to show all transactions for an account except holds (which are meaningless to our users). The existing transaction endpoint allows to specify that we want only credits or debits or refunds, but it does not allow us to ask for all three types or to filter out holds. Retrieving all transactions and then filtering out holds on our side is wasteful and anyway is not really practical when "one page at a time" paging (as opposed to the infinite paging strategy that we don't use).

I'd like the transaction endpoint to accept1) a list of transaction types to include and/or 2) a list of transaction types to exclude.

Thoughts?

Creating an authorization hold on a card is a synchronous operation. Capturing an authorization to charge a card is not a synchronous operation, but the capture is guaranteed given a valid hold. That lends itself well to a REST API.

ACH credits are neither synchronous or guaranteed. Balanced treats credits optimistically (assume it will be successful). It notifies the marketplace if there's a rejection and retries every time the bank account information is updated. The ACH can make bank deposits next business day, but it takes four business days to let the originator know if it was successful or rejected.

There's two ways to treat ACH debits (UPDATE: going to use pessimistic approach. Read comments below for reasoning.):

Optimistic

Just like charging a card, the marketplace will receive the money in their escrow balance immediately and can credit the money out to a merchant. Since the operation is not guaranteed, the money may get pulled back. If there's a rejection, Balanced can pull the money back just a chargeback on a card, but ACH debit rejection are much more likely than a chargeback. This will complicate the marketplaces ledger since they'll have funds that may get pulled back, and they won't know for four business days.

Pessimistic

Don't give the money to the marketplace until after the debit is reported to be successful by the bank. Debits are next business day, but this depends on the originating bank, which can take four business days. That complicates the API. The debit isn't technically created, so Balanced can't return a 201. Balanced can notify the marketplace after the fact, but what does that actually look like in the API?

UPDATE: Isolating the conversation to just ACH debits and revisting how it work in the Balanced API. Take a look at the ach branch

from @gvenkataraman:

we have 2 different use models (1) debiting exising and (2) debiting new/uncreated, should we allow (2) at all? When you post to create a resource, you should ideally be returning a uri for the created resource. In (2), you are creating two resources which to me seems confusing. so, what uri should we be returning on (2), debit_uri? then should the client be parsing the response payload to construct account uri? making it a requirement to create a bank account before creating debits/credits keeps it quite consistent. It also defines a good hierarchical uri. the fact that debits/credits can never be performed without a bank account suggests to be me that's it's ok to impose the condition to create a bank account before performing debit

I'm moving part of the conversation that started in #1 here.

Here are the goals that I want to achieve:

• Make the reasoning behind API design decisions public. Even if the community doesn't comment, there's still value in discussing openly
• Give stakeholders outside of the Balanced team to comment and challenge decisions, ask for clarifications in the docs and spec, or suggest enhancements in the API
• Keep Balanced honest by ensuring the API is consistent with publicly published specifications. Balanced has a relatively small team, and it allows us to self police without requiring a manual process to guarantee consistency across the spec and docs

/cc @whit537 @mahmoudimus

At approximately 9:40AM PDT, Balanced's centralized logging machines experienced slowness as their free disk space started approaching dangerous levels. We are currently investigating why our alerting systems did not notify us at a lower threshold. Balanced's servers were operating normally at starting 11:15AM PDT.

Internally, we centralize our logs through the industry standard rsyslog, which is supposed to spool logs locally and asynchronously deliver them to our centralized logging server. However, a misconfiguration in our rsyslog configuration caused log messages to synchronously deliver instead of asynchronously, consequently impacting the responsiveness of our API applications.

Yesterday, we added two new machines to help with the current load we've been experiencing on Balanced, but we did not anticipate the surge in logs generated.

We're going to write sanity checks for our rsyslog configurations and install a redundant alerting system to allow us to respond faster to these issues before they arise. We're also now correlating the increase of log messages to a particular server, to monitor exactly how much disk space usage accrues per new API machine.

We understand that this is unacceptable and we're working tirelessly to ensure Balanced is operating efficiently and smoothly.

Balanced currently charges 2.9% + 30¢.

The 30¢ can't change since the card networks and acquiring banks charge this amount to Balanced. The 30¢ is a direct passthrough.

The pricing would work in the following way (per month). This is the standard model for tiered pricing:

1. up to tier 1 amount: 2.9%
2. for transactions that exceed tier 1 amount in that month: x%
3. for transactions that exceed tier 2 amount in that month: y%

There are two steps required for this task:

1. determine the tiers (no more than what is listed above)
2. determine the pricing for each tier

Balanced doesn't return the result of a card security code check. The API makes a decision to process or reject a card based on risk even if the security code check fails. Passing through the results gives the marketplace insight into why a card transaction may have been rejected.

Here's a comprehensive list of possible results:
https://github.com/Shopify/active_merchant/blob/master/lib/active_merchant/billing/cvv_result.rb

#3 tries to address how Balanced should define a ACH debit interface, but it's important to first understand the constraints of ACH before moving forward on how the interface looks.

Specifically:

• how long until an ACH debit is confirmed to have happened?
• how long until the funds become availble from issuing the request?
• are the funds guaranteed after a successful response is returned from the ODFI?
• how long until the ACH debit is rejected?
• what rejection reasons are provided?

Add anything not included in this list, and I'll update this summary.

UPDATE: changed title to address volume pricing for debits as well

Per the discussion in #48, I am creating a new issue to determine if there should be volume pricing tiers for ACH credits, and if so, what those tiers will be.

Balanced currently charges 25¢ per ACH credit (i.e. each time we pay a merchant via next-business day ACH)

The pricing would work in the following way (per month). This is the standard model for tiered pricing:

1. up to X credits : 25¢
2. Y > # of credits > X: YY¢

3. of credits > Y: ZZ¢

There are two steps required for this task:

1. determine the tiers (no more than what is listed above)
2. determine the pricing for each tier

Currently payments must be made to a funding destination such as a bank account.

Customers have expressed interest in being able to create credits to accounts without the funds leaving the system. This would allow aggregation of credits to help reduce fees incurred.

It's higher friction to collect bank account information than a credit card number. It would be useful to be able to push money to a credit card to pay a merchant.

Create transparency around uptime and report issues to customers. We borrowed from Heroku's status page. Currently using Stashboard in a poor way

The messages would feed in from @balancedstatus.

This enhancement is currently scheduled for Fri, Aug 24.

This is the core problem from #13.

The transactions endpoint returns holds, debits, refunds, and debits. You can't filter out specific objects because there is no field to filter on. If balanced added something akin to "object": "debit" it would solve this problem.

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.

The topic has been brought up to me several times whether Balanced offers any introductory discounts on it's processing and payout fees.

Balanced does not currently offer pricing discounts aside from volume pricing (#48, #57), but I wanted to create an issue to collect thoughts on the matter.

The current explanation of the accounts resource in the docs and the api spec is pretty atrocious. 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.

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.

#29

At approximately 2012-09-10, 23:30 UTC, Balanced generated 500 errors on the accounts endpoint. The 500's lasted for less than 3 minutes and affect a small subset of requests. This was due to a failed deploy which left a server in an inconsistent state. We have put together steps to make sure such issues do not happen in future.

• Could Balanced support recurring payments?
• Is anyone interested in this feature?
• Would it be useful to have these for credits as well as debits?

Add the ability to change the merchant account type.

A merchant may change the way their company is organized and need to change from a personal to a business type of merchant account. It would be nice to have the ability to change it and add submit the remaining information to balanced. Currently you'd have to create a new account which results in the loss of their transaction history or an otherwise broken transaction trail.

Should the API specs for Balanced be written in GitHub Flavored Markdown or reStructuredText?

In creating this repo, we were having an internal debate around whether we should use Markdown or rst. Balanced is a Python shop, and it's considerably easier for us to generate rst. That means it's also easier to ensure validation and consistancy. However, the specs are being written for GitHub, and Markdown is the standard on GitHub.

Add a card signature to the cards resource. Right now, there's no way to see if two card objects refer to the same card. This is especially important if a marketplace wants to see if two buyers are using the same card.

PCI DSS doesn't allow for an externally computed hash, so the signature will be just that. It can only be checked by actually creating a new card token.

Prosed field name: signature

I don't have emails for my users. Right now we're constructing a fake email address to work with Balanced. It'd be cleaner if email weren't required.

What's the reason for requiring email?

A more generalized version of #22

Balanced should allow DELETE operations on accounts, cards, bank_accounts, and marketplaces.

balanced/balanced-ruby#26

Currently it's a game of trial and error to know which fields can be filtered on. Also, the documentation only makes the most passing comments about how to filter or sort.

It has been reported that Bank of America was issuing ACH credits with descriptor showing BALANCED rather than what was added to the appears_on_statement_as field on some credits.

What can be done to minimise how often this occurs?

UPDATE (12/19/12): Balanced has verified that the appears_on_statement_as does not show up properly for credits.

I have a button on my site that says "Delete my Credit Card - Your credit card details will immediately be completely purged from Gittip." However, I think this might be a lie. Am I right that cards in Balanced can only be invalidated, not deleted? I need them to be deleted. Is there a reason they can't be deleted?

There should one file per resources in the resource directory. All operations, along with an overview of the resource itself, should be merged into the same file.

Due to the down times today, I think it would be very beneficial for marketplaces to be notified with system status updates as opposed to finding out through their customers.

I am thinking something even along the lines of an email to the marketplace support address or something similar.

The debits resource has a field called appears_on_statement_as. Balanced displays the value of this field as the soft descriptor, which shows up on the card statement.

Amex displays the value correctly after the hold has been captured, but they display "PoundPay" for pending transactions. This is especially bad on Amex for two reasons:

1. Amex does not support voiding an authorization hold, so all "pending" transactions stay on the statement for 30 days. See #17
2. Amex does not support the verify operation, which means Balanced has to perform a $1 hold to verify a card is valid when tokenizing the card

This is typically not an issue since Amex collapses the Pending Transactions section when a user logins online, but it can be, understandably, confusing for a user.

Minimal solution: document this shortcoming in Amex's system and change DBA with Amex from PoundPay to Balanced to reflect rebranding

Optimal solution: work with Amex to find a better solution if possible

To complete #2, Balanced has to determine an appropriate price for ACH debits.

Use case: pull debit money from my marketplace owner account into my escrow balance. As far as I know, this cannot be done via the dashboard, only the API.

Balanced only allows for pulling money in from credit cards. ACH debits enable the following use cases:

• merchant initiated refund to a buyer after the merchant has already received their money
• debiting a merchant in the case of a chargeback by a buyer
• large transactions that can't support the variable fee associated to credit card payments

UPDATE

ACH Debits are now supported, visit https://docs.balancedpayments.com/current/?language=bash#debiting-bank-accounts for more information

Email us at [email protected] to get in the beta!

Pricing

It's possible to cancel an ACH transaction before it has cleared. This can be useful if the transaction was submitted accidentally, or if fraud has been detected.

See also #2 and #3

We had 3 periods today where we experienced slowness in Amazon's EBS volumes, causing an issue with rsyslog's logging channels, and consequently causing massive slowdowns on some of our API machines. We were alerted instantly and have reconfigured rsyslog to ensure this will not be a problem in the future.

Currently, when Balanced declines the creation of a hold or debit using a card the response is 402 status code.

No additional information is conveyed which can lead to support tickets being raised to enquire about the status of a declination.

Can Balanced return the declination reason? I propose the following reasons be exposed as a property on the exception returned:

• INSUFFICIENT_FUNDS
• FRAUD
• INVALID_CARD
• BANK_DECLINED

Required steps:

1. Get the spec for ACH to a workable point: https://github.com/balanced/balanced-api/tree/ach
2. Release a test API that follows the spec but does not process transactions
3. Release thin client libraries for the API in Ruby, Python, and PHP
4. Enable live transactions
5. Go back to 1, improve the spec, and go through the steps again until interface freezes
6. Incorporate back into production (/v1) API

Currently bank accounts are not verified until a transaction is processed to/from the account.

How could Balanced verify a bank account ahead of time?

I'd like to be able to export my marketplaces transaction history via CSV. Currently, there is no way to do so from the Balanced dashboard.

International card processing is quite hard, but it's easier to provide a system to transfer from to and from US and non-US bank accounts. The easiest method is IAT.

There are some limitations to IAT. ACH only requires the following fields:

• name
• account number
• routing number
• account type

IAT also requires the following fields for both the sender (originator) and recipient (receiver). See Bank of America's FAQ on IAT

• Physical address of the originator including city, state, province, country and postal code
• �Physical address of the receiver including city, state, province, country and postal code
• Correspondent bank name, identification number and branch country code if applicable
• Receiving bank name, identification number and branch country code
• Reason for the payment

This address part of the issue discussed in #23

Balanced verifies a card with the networks and issuing banks when a card is tokenized. The cards endpoint only supports a one-time POST.

There have been requests to allow a marketplace to validate the cvv2 on an existing card. The proposed use case is to request cvv2 on subsequent transactions (without asking for the card number again) to reduce risk.

Proposed interaction:
PUT on cards resource with the security_code reverifies the card

UPDATE (5/29/13): include AVS as part of the proposal.

Not all of our merchants have bank accounts / want to share that information. Could Balanced provide bill pay-style check issuing? If so how much would it cost?

Right now Balanced only supports merchant accounts for US entities. There's a whole world out there. Obviously a big undertaking, but definitely of huge value to Balanced customers.

It would be great if Balanced could push notifications when certain criteria are met. Foremost in my mind would be a notification when the state of a credit is updated.

Marketplaces and merchants would like the ability to use Balanced dashboard to search for transactions by:

• description
• meta field
• date
• amount
• buyer/merchant email address
• last four of card #

Integration requests tend to focus around these areas:

1. How do I get started (conceptual)
2. How do I find duplicate cards / bank accounts? Do you return the same URI for the same card/bank account?
3. How do I do the merchant signup (conceptual)
   • Something that helps is breaking it into 2 discrete steps
     1. collect merchant information securely
     2. collect bank account information

Collecting information is still somewhat tricky as it needs to deal with:

1. does the account exist?
2. does account already have merchant role?

When going live, the first thing that is encountered is:

1. People forget to take out the TEST-MK... out of their balanced.js.

How do we simplify the process?