balanced / balanced-api Goto Github PK
View Code? Open in Web Editor NEWBalanced API specification.
Balanced API specification.
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:
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.
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.
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.
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.
To complete #2, Balanced has to determine an appropriate price for ACH debits.
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
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.
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.
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.
Marketplaces and merchants would like the ability to use Balanced dashboard to search for transactions by:
Balanced only allows for pulling money in from credit cards. ACH debits enable the following use cases:
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!
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.
Integration requests tend to focus around these areas:
Collecting information is still somewhat tricky as it needs to deal with:
When going live, the first thing that is encountered is:
TEST-MK...
out of their balanced.js
.How do we simplify the process?
A more generalized version of #22
Balanced should allow DELETE
operations on accounts, cards, bank_accounts, and marketplaces.
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.
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.
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:
There are two steps required for this task:
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.
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.
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.
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
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.
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.):
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.
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
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.
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.
I'm moving part of the conversation that started in #1 here.
Here are the goals that I want to achieve:
/cc @whit537 @mahmoudimus
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:
There are two steps required for this task:
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?
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:
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.
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?
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.
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?
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
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.
#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:
Add anything not included in this list, and I'll update this summary.
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.
Required steps:
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?
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.
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'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.
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:
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
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 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.