Recipes

Linking an Account

Register an external bank account as a source of funds for your Capital Account.

A linked account is an external bank account you register with Penny as a source of incoming funds. When Penny receives funds from a registered linked account, it routes them to your Capital Account, where they appear as an inbound transaction with a bank channel. See Transactions for how that transaction looks.

Details of where to send funds are coming soon.

This recipe walks through creating a linked account, reading it back, listing your linked accounts, and deleting one. All requests go to Penny Banking (https://sandbox.api.thepennyinc.com in sandbox).

1. Create the linked account

POST /accounts/linked/ registers an external bank account as a source of incoming funds. country and currency are required; US and USD are the supported values.

account_details is selected by its type: pass a us_account object (account_number, routing_number, us_account_type) or an iban object (iban), depending on how the external account is identified.

curl -X POST https://sandbox.api.thepennyinc.com/accounts/linked/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "currency": "USD",
    "account_details": {
      "type": "us_account",
      "account_number": "000123456789",
      "routing_number": "021000021",
      "us_account_type": "checking"
    }
  }'

The response is the new linked account, with account_number and routing_number (or iban) masked. In responses, the US account type is reported as account_details.account_type:

201 Created
{
  "account_id": "account_01937c9e-5b2f-7c41-9a70-5b2f7c419a70",
  "type": "linked",
  "version": 1,
  "version_time": "2026-01-15T18:32:00Z",
  "status": "pending_approval",
  "currency": "USD",
  "country": "US",
  "account_details": {
    "type": "us_account",
    "account_number": "**********",
    "routing_number": "**********",
    "account_type": "checking"
  }
}

alias and description are null on a new linked account, so they’re omitted. A new linked account may start in pending_approval while Penny reviews it. Penny routes funds from a linked account to your Capital Account once its status is approved.

2. Get a linked account

curl https://sandbox.api.thepennyinc.com/accounts/linked/$ACCOUNT_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Pass ?version= to look up a specific past version of the record. It defaults to 0, which selects the latest version.

The account/routing number or IBAN comes back masked by default here too. Pass ?reveal_sensitive=true if you need the real value:

cURL
curl "https://sandbox.api.thepennyinc.com/accounts/linked/$ACCOUNT_ID?reveal_sensitive=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

3. List linked accounts

curl "https://sandbox.api.thepennyinc.com/accounts/linked/?status=approved" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

status is optional and filters to one of created, pending_approval, approved, rejected, suspended, or deleted. Omit it to get every linked account regardless of status. Results are paginated like any other list endpoint. Account and routing numbers and IBANs are always masked in list results, and there’s no reveal_sensitive option here; fetch the individual account (step 2) if you need the real value.

4. Delete a linked account

Deleting a linked account marks it deleted rather than removing the record. Penny stops accepting it as a source of funds, and its history is preserved. The response is the linked account with status: "deleted".

curl -X DELETE https://sandbox.api.thepennyinc.com/accounts/linked/$ACCOUNT_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Deleting an already-deleted linked account is rejected. Check the status first if you’re not sure.

Staying in sync

Subscribe to linked_account.created and linked_account.updated (see the Event Catalog) instead of polling. linked_account.updated fires whenever a linked account’s status or details change, including approval. See Subscribing to Webhooks for how to set up a subscription.

Next steps