Open and fund an account

This walk-through creates a customer, gets them verified in the sandbox, opens a checking account, adds an account number, funds the account three ways and reads the result. It runs against the local sandbox, which Getting started sets up. $TOKEN is a service token, as in Authentication.

1. Create the customer

A business needs a legal_name, an email, a tax_id and an address. The answer carries the customer's id and a kyc_status of pending. Customers and KYC has every field, and what a person needs.

POST /customers

curl -X POST 'https://api.dev.bank.corgi.com/customers' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "business",
    "legal_name": "Acme Supply LLC",
    "email": "ops@acme.example",
    "tax_id": "12-3456789",
    "address": { "line1": "1 Market St", "city": "San Francisco",
      "state": "CA", "postal_code": "94105", "country": "US" }
  }'

2. Get KYC verified

Until a check verifies the customer, POST /accounts answers accounts.customer_not_eligible. In the sandbox the identity-verification provider is a simulator, and it verifies any legal name that carries none of its markers. The check answers with a decision of verified, and the customer's kyc_status follows.

POST /kyc-checks

curl -X POST 'https://api.dev.bank.corgi.com/kyc-checks' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm" }'

3. Open the checking account

The request names the owners and a product_code. The answer carries the account's id, its routing_number and a default_account_number. A consumer product such as consumer_checking also needs an acknowledgement of its opening documents, which Opening accounts covers.

POST /accounts

curl -X POST 'https://api.dev.bank.corgi.com/accounts' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "owners": ["cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm"],
    "product_code": "business_checking"
  }'

4. Add an account number

A second number lands on the same balance, so one payer can be given a number of its own. See Account numbers.

POST /accounts/{id}/account-numbers

curl -X POST 'https://api.dev.bank.corgi.com/accounts/acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm/account-numbers' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Payer: Bolt Fasteners" }'

5. Fund it

There are three ways in. The first is a deposit taken at a branch, which POST /accounts/{id}/credits records. With no availability kind the money is available at once.

A branch deposit

curl -X POST 'https://api.dev.bank.corgi.com/accounts/acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm/credits' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500000,
    "currency_code": "USD",
    "source_ref": "branch-0001",
    "description": "Opening deposit"
  }'

The second is a payment from another bank. No rail is connected, so the simulation endpoints play the other side and deliver to an account number through the bank's real inbound code. An ACH credit posts at once and becomes available the next business day. A wire and a FedNow or RTP credit post with no hold.

An incoming ACH credit

curl -X POST 'https://api.dev.bank.corgi.com/simulate/transfers/ach/receive' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "7304182657",
    "amount": 500000,
    "currency_code": "USD",
    "direction": "credit",
    "sec_code": "CCD",
    "originator_name": "BOLT FASTENERS INC",
    "originator_routing_number": "021000021",
    "individual_id": "INV-1002",
    "description": "PAYMENT"
  }'

The third is a book transfer from another account at the bank, addressed by to_account_id or to_account_number. It posts immediately.

A book transfer in

curl -X POST 'https://api.dev.bank.corgi.com/transfers/book' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "from_account_id": "acct_2tVh8nqLxq4GbDe0K1F6S9zRcWn",
    "to_account_number": "7304182657",
    "amount": 100000,
    "currency_code": "USD",
    "description": "Refund"
  }'

6. Read the balance

The account carries its balances. After the three credits the ledger_amount is 3,100,000 and the available_amount 2,600,000, because the ACH credit is still a pending_amount. Balances and holds explains each figure.

GET /accounts/{id}

curl 'https://api.dev.bank.corgi.com/accounts/acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm' \
  -H "Authorization: Bearer $TOKEN"

7. Read the statement

GET /accounts/{id}/transactions returns the account's activity straight from the ledger's entries, each line with its running balance. For one month, generate the draft with POST /accounts/{id}/statements/{period}/generations and read it at GET /accounts/{id}/statements/{period}, where period is YYYY-MM. Statements and tax documents covers issuing and delivery.

GET /accounts/{id}/transactions

curl 'https://api.dev.bank.corgi.com/accounts/acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm/transactions' \
  -H "Authorization: Bearer $TOKEN"