We find examples are often the easiest way to explain. Feel free to head over to the next section though if you'd rather dive straight in!

Today, we are going to build a basic payment workflow consisting of a wire, a book transfer, and an ACH credit. We will be working within our sandbox environment, which lets you test out an application end-to-end before you go-live in production. In this guide, we will perform the following steps to build our workflow:

1. Create an entity
2. Create a bank account for the entity
3. Simulate an incoming wire transfer of $1,000 to the account
4. Link an external account we can transfer to/from by creating a counterparty
5. Send an ACH Credit of $400 from our bank account to this counterparty

First, you'll need to navigate to the dashboard and copy your api-key. A sandbox key is prefixed with test- and a live key is prefixed with live-.

Create entity

Once you have a valid key, you'll create an entity. An entity is the legal owner of the account. In this example I'll use myself - an individual owner.

curl https://api.column.com/entities/person
  -XPOST -u :{test_api-key}
  -d first_name=Andrew
  -d last_name=Jackson
  -d ssn=123456789
  -d date_of_birth="1987-03-15"
  -d email="andrew@column.com"
  -d "address[line1]"="123 Federal Reserve Way"
  -d "address[city]"="San Francisco"
  -d "address[state]"="CA"
  -d "address[postal_code]"="94123"
  -d "address[country_code]"="USA"

Create account

Next, you are going to create an account that will be attached to the entity. You'll receive an entity_id from the create entity response that will be used to create accounts.

curl https://api.column.com/bank-accounts
  -XPOST
  -u :{test_api-key}
  -d entity_id={enti_example}
  -d description="Andrew road-trip account"

Now, you have a bank account that you can move (well fake, since you're using your test api key) money in an out of! In the response to create account you'll receive a default_account_number and routing_number. These will be used to externally identify your account for transfers.

Every account is created with a default_account_number, however you can create multiple account numbers that are associated with this account. You can view them as pointers to that bank account - however, they are all valid account numbers that you can send ACH and Wires from. You can create and remove them without interfering with the underlying bank account.

Simulate an incoming wire transfer

Now that we have a bank account, let's send some MONEY to it! Our sandbox environment has several endpoints you can use to simulate an incoming ACH or Wire transfer. For now, let's receive an incoming wire of $1,000 (or 100,000 cents). The behavior is identical to what would happen if an account at another bank sent a wire to your account and routing number.

curl https://api.column.com/simulate/receive-wire
  -u :{test_api-key}
  -d destination_account_number_id={acno_example}
  -d amount=100000
  -d currency_code=USD

Any endpoint in the /simulate/* routes are used for simulating production behaviors and will NOT be available in production.

You should now have a balance on your account. To confirm the balance on your account, feel free to send a GET request using your bank_account_id as shown below.

curl https://api.column.com/bank-accounts/{bank_account_id}
  -u :{test_api-key}

Create counterparty

A counterparty is an external account that you can transfer money to and from. All ACH and Wire transfers originated by Column take in a counterparty_id to identify the destination. Let's create a counterparty we can transfer to.

curl https://api.column.com/counterparties
  -u :{test_api-key}
  -d account_number=87654321
  -d routing_number=121044055

Now that you created a counterparty - you can send money to it (or pull from it)! A counterparty stores an external bank account and can also store additional transaction detail, as desired or required. For example, an IAT (International ACH Transfer) and a wire transfer legally require information about the receiving party. You'll add this to the counterparty request. Note: for a domestic ACH transaction you only need to put in a valid account and routing number.

Create ACH credit transfer

Let's send $400 to our counterparty through an ACH Credit request. An ACH credit, is when you push money from your account to an external account. Insert the counterparty_id from the last request and the bank_account_id of your account. Money will move from your account to the counterparty account.

curl https://api.column.com/transfers/ach
  -XPOST
  -u :{test_api-key}
  -d counterparty_id={cpty_example}
  -d bank_account_id={bacc_example}
  -d type=CREDIT
  -d amount=40000
  -d currency_code=USD
  -d description="payment"

Congrats on your first outgoing transfer! You'll receive a webhook to remain updated as the ACH transfer goes through every step of the process and finally settles in the destination account. Note that ACH's usually take two business days to settle. If you want to speed up the settlement process for you own testing, take a look at our Settle ACH Transfer endpoint in our sandbox.