raycmorgan/0. toc.md Secret

## 0. toc.md

      
    Raw
  

              0. toc.md
            
          
    You can find more up to date documentation here: https://stripe.com/docs/guides/ach-beta
This will continue to live and document /v1/payments but we now recommend using the stripe.com guide and implement against /v1/charges
ACH-in (private beta) documentation

Table of contents


Payments

Creating a payment
Attaching a bank account to a customer
Listing bank accounts
Retrieve a bank account
Delete a bank account
Edit a bank account
Verify a bank account
Payout timeline
Webhooks
Testing
Connect Support


Refunds

API calls

Create a refund
Listing refunds
Retrieving a refund


Subscriptions (supported, but needs to be documented)


Example Flow


Current Limitations


Read only dashboard support: Currently you must go through the API to create and refund payments.
No bindings support


## 1. payments.md

      
    Raw
  

              1. payments.md
            
          
    ACH Payments

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
If the customer has multiple bank accounts, you can specify which one to
use by supplying a bank_account param:
curl https://api.stripe.com/v1/payments \
   -u {API_KEY}: \
   -d customer={ID} \
   -d bank_account={BANK_ACCOUNT_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
Listing bank accounts

You can list a customers' bank accounts:
curl https://api.stripe.com/v1/customers/{ID}/bank_accounts \
  -u {API_KEY}:
Retrieve a bank account

curl https://api.stripe.com/v1/customers/{ID}/bank_accounts/{ID} \
  -u {API_KEY}:
Delete a bank account

curl https://api.stripe.com/v1/customers/{ID}/bank_accounts/{ID} \
  -u {API_KEY}:
  -XDELETE
Updating a bank account

The only thing that can be updated on a bank account is the metadata.
If you would like to change the account/routing information, you must
create a new bank account (and delete the old one if you'd like).
curl https://api.stripe.com/v1/customers/{ID}/bank_accounts/{ID} \
  -u {API_KEY}: \
  -d metadata[bar]=qux
Verify a bank account

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

ACH payments will clear into your Stripe available balance (or automatically
transferred) after 5 days. During that time, the payment might fail for various
reasons such as an invalid bank account or insufficient funds.
Your customer should expect to see the debit on their bank statement within
1-2 business days.
Webhooks

All payment webhooks contain the payment information as their payload.

payment.created - Right after a successful POST /v1/payments. Note that
the payment will be in the pending state, and can still fail.
payment.paid - This will happen when the payment transitions it's
status from pending to paid. This happens after 5 days.
payment.failed - Before 5 days, if the payment is returned
(insufficient funds, etc) you will receive this hook.

A payment.created webhook will always occur, and only one of payment.paid and
payment.failed will occur.
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)

Connect Support

Applications can create ACH payments on behalf of their connected
merchants. Just like /v1/charges you may specify an
application_fee to allow your application to take part of the
payment as a fee.
Customer sharing
The process to share a bank account across connected accounts is similar
to sharing cards. The main difference is that bank accounts must be
verified before sharing.

Attach a bank account to a customer in your account (using your secret key)
Verify the bank account using microdeposits
Create a token on the connected account using their access_token

curl https://api.stripe.com/v1/tokens \
  -u {ACCESS_TOKEN}: \
  -d customer={CUSTOMER_ID} \
  -d bank_account={BANK_ACCOUNT_ID}

Attach the bank account token to a customer on the connected account
using the access_token.

curl https://api.stripe.com/v1/customers/{OTHER_CUSTOMER_ID}/bank_accounts \
  -u {ACCESS_TOKEN}: \
  -d bank_account={BANK_ACCOUNT_TOKEN}

  
## 2. refunds.md

      
    Raw
  

              2. refunds.md
            
          
    Refunds

Refunds for ACH payments are handled via ACH transfers back into your customer's
account. As such, they take 1-2 business days to appear on your customer's bank
statement.
API calls

Create a refund

To create a full refund on a payment all you need to specify is the payment to
refund.
curl https://api.stripe.com/v1/refunds \
   -u {API_KEY}: \
   -d payment={PAYMENT_ID}
To create a partial refund of the payment simply add the amount field.
curl https://api.stripe.com/v1/refunds \
   -u {API_KEY}: \
   -d payment={PAYMENT_ID} \
   -d amount=500
If you are using Stripe Connect, you can also refund your application_fee by
specifying refund_application_fee. If the refund is a partial refund, the
amount of the application_fee that will be refunded is proportional to the
amount of the payment and the amount being refunded. For example, if 50% of
the original payment is being refunded, 50% of the application_fee will be
refunded.
However, if the refund fully refunds the payment (either a full refund, or a
partial that refunds the remainder of the payment) then the entire
application_fee will be refunded if refund_application_fee is set to true.
curl https://api.stripe.com/v1/refunds \
   -u {API_KEY}: \
   -d payment={PAYMENT_ID} \
   -d refund_application_fee=true
You can also specify metadata on a refund when creating it.
curl https://api.stripe.com/v1/refunds \
   -u {API_KEY}: \
   -d payment={PAYMENT_ID} \
   -d metadata[foo]=bar
Listing refunds

To list all payment refunds.
curl https://api.stripe.com/v1/refunds \
   -u {API_KEY}:
You can also filter by payment.
curl https://api.stripe.com/v1/refunds?payment={PAYMENT_ID} \
   -u {API_KEY}:
Retrieving a refund

curl https://api.stripe.com/v1/refunds/{REFUND_ID} \
   -u {API_KEY}:

  
## 3. flow.sh
# 1. Create a customer
$ curl https://api.stripe.com/v1/customers \
    -u {API_KEY}:
{
  "id": "cus_123123",
  ...
}

# 2. Create bank account via token or non-token flow
# 2a. Using the token flow
$ curl https://api.stripe.com/v1/tokens \
    -u {API_KEY}: \
    -d bank_account[country]=US \
    -d bank_account[routing_number]=110000000 \
    -d bank_account[account_number]=000123456789
{
  "id": "btok_123123",
  ...
}

$ curl https://api.stripe.com/v1/customers/cus_123123/bank_accounts \
    -u {API_KEY}: \
    -d bank_account=btok_123123
{
  "id": "ba_123123",
  ...
}

# 2b. Creating bank account without token
$ curl https://api.stripe.com/v1/customers/cus_123123/bank_accounts \
    -u {API_KEY}: \
    -d bank_account[country]=US \
    -d bank_account[routing_number]=110000000 \
    -d bank_account[account_number]=000123456789
{
  "id": "ba_123123",
  ...
}

# 3. Microdeposit verification
# The values from this are test amounts Stripe deposited into this customer's bank account.
# There will be 2 values between 1-99¢
$ curl https://api.stripe.com/v1/customers/cus_123123/bank_accounts/ba_123123/verify \
    -u {API_KEY}: \
    -d amounts[]=12 \
    -d amounts[]=54

# 4. Create payment
$ curl https://api.stripe.com/v1/payments \
    -u {API_KEY}: \
    -d customer=cus_123123 \
    -d amount=1000 \
    -d currency=usd \
    -d payment_method=ach
	# 1. Create a customer
	$ curl https://api.stripe.com/v1/customers \
	-u {API_KEY}:
	{
	"id": "cus_123123",
	...
	}

	# 2. Create bank account via token or non-token flow
	# 2a. Using the token flow
	$ curl https://api.stripe.com/v1/tokens \
	-u {API_KEY}: \
	-d bank_account[country]=US \
	-d bank_account[routing_number]=110000000 \
	-d bank_account[account_number]=000123456789
	{
	"id": "btok_123123",
	...
	}

	$ curl https://api.stripe.com/v1/customers/cus_123123/bank_accounts \
	-u {API_KEY}: \
	-d bank_account=btok_123123
	{
	"id": "ba_123123",
	...
	}

	# 2b. Creating bank account without token
	$ curl https://api.stripe.com/v1/customers/cus_123123/bank_accounts \
	-u {API_KEY}: \
	-d bank_account[country]=US \
	-d bank_account[routing_number]=110000000 \
	-d bank_account[account_number]=000123456789
	{
	"id": "ba_123123",
	...
	}

	# 3. Microdeposit verification
	# The values from this are test amounts Stripe deposited into this customer's bank account.
	# There will be 2 values between 1-99¢
	$ curl https://api.stripe.com/v1/customers/cus_123123/bank_accounts/ba_123123/verify \
	-u {API_KEY}: \
	-d amounts[]=12 \
	-d amounts[]=54

	# 4. Create payment
	$ curl https://api.stripe.com/v1/payments \
	-u {API_KEY}: \
	-d customer=cus_123123 \
	-d amount=1000 \
	-d currency=usd \
	-d payment_method=ach