ACH-in documentation

ach-in

-----
# Deprecated

This documentation is now deprecated. Please see https://stripe.com/docs/guides/ach-beta 
for the latest documentation.
-----

ACH-in (private beta) documentation

# Creating a payment

To create an ACH payment, you send a request to /v1/payments like you would to
/v1/charges:

curl https://api.stripe.com/v1/payments \
   -u {API_KEY}: \
   -d customer={ID} \
   -d amount=1000 \
   -d currency=usd \
   -d payment_method=ach
   
(It's worth noting that we're eventually going to merge /v1/charges and /v1/
payments, so we may ask you to switch to another API endpoint nearing the end
of the beta.)

The payment object looks like:

{
  "id": "py_2jOYfo213EKxIk",
  "object": "payment",
  "created": 1381458902,
  "livemode": false,
  "amount": 100,
  "currency": "usd",
  "payment_method": "ach",
  "payment_source": {
    "object": "bank_account",
    "id": "ba_2gjqUkUwN31jI5",
    "bank_name": "STRIPE TEST BANK",
    "last4": "6789",
    "country": "US",
    "currency": "usd",
    "validated": false,
    "verified": true,
    "fingerprint": "glTJvPVnzCgyOwjh"
  },
  "balance_transaction": "txn_2jOYrlBKKNzCfl",
  "customer": "cus_2gjqT8FOFoESWu",
  "description": null,
  "statement_descriptor": null,
  "status": "pending"
}

# Attaching a bank account to a customer

Stripe currently only allows you to debit from a bank account that is attached
to a customer and has been verified via micro-deposit.

To add a bank account to a customer, POST to /v1/customers/{ID}/bank_accounts 
with the bank account details, either as a hash or by using a bank account 
token created by Stripe.js:

curl https://api.stripe.com/v1/customers/{ID}/bank_accounts \
  -u {API_KEY}: \
  -d bank_account[account_number]=000123456789 \
  -d bank_account[routing_number]=110000000 \
  -d bank_account[country]=US
  
You can list a customers' bank accounts:
  
curl https://api.stripe.com/v1/customers/{ID}/bank_accounts \
  -u {API_KEY}:
  
Or retrieve a specific one:
  
curl https://api.stripe.com/v1/customers/{ID}/bank_accounts/{ID} \
  -u {API_KEY}:
  
You can't currently update or delete bank accounts. We'll be adding that soon, 
though.

## Verifying bank accounts

Upon attaching a bank account to a customer, Stripe will send two small deposits
to the bank account (which should take 1-2 business days to appear in the account).
To verify the bank account, have your user confirm the amounts of the two deposits:

curl https://api.stripe.com/v1/customers/{ID}/bank_accounts/{ID}/verify \
  -u {API_KEY}: \
  -d amounts[]=14 \
  -d amounts[]=26
  
# Payout timeline

The payout timeline (along with the various webhooks that you'll get at each
stage) mirrors that of the /v1/transfers API:

https://stripe.com/docs/tutorials/sending-transfers#transfer-timeline

# Testing

To mimic success/failed payment behaviors, you can use the following bank account 
information in test mode:

Routing number: 110000000
Account number: 000123456789 (success), 000111111116 (failure)

To mimic success/failed verifications, you can use the amounts:

[32, 45] (success)
[any other number combinations] (failure)

# Pricing

The pricing for the beta is 25c/payment, and $1/failed payment.

# Coming up

- Refunding payments
- ACH payments for recurring billing
- Dashboard