1. Use Cases
  2. Use Case 7: Manage Bank Accounts

Manage bank accounts associated with taxpayers or firms. Create, list, and delete bank accounts using your system’s bank account ID with the externalId field. Each bank account belongs to exactly one owner: an existing taxpayer or an existing firm.

Use Case 7: Manage Bank Accounts

​
Understanding Bank Accounts

Bank accounts represent the funding sources used to pay tax obligations for a taxpayer. Once created, a bank account can be associated with tax payments so Remitian can process them on the scheduled date.

Bank accounts are polymorphic and keyed on the paymentNetwork field:

Available Payment Networks:

  • Ach - US ACH transfer. Requires routingNumber.
  • Eft - Canadian EFT transfer. Requires institutionNumber and transitNumber.

Bank Account Object Structure:

FieldTypeDescription
idguidUnique identifier for the bank account
Example: 079bc3f4-d65e-73f7-8133-f5800e825515
externalIdstringYour system’s unique identifier (optional)
Example: my_bank_account_123
taxpayerIdguidAssociated taxpayer identifier
Example: 029bc3f4-d65e-73f7-8133-f5800e825510
bankAccountNamestringName of the bank account
Example: Business Checking
accountNumberstringBank account number
Example: 000123456789
paymentNetworkstringPayment network
Example: Ach, Eft
routingNumberstringRouting number (ACH only)
Example: 021000021
institutionNumberstringInstitution number (EFT only)
Example: 001
transitNumberstringTransit number (EFT only)
Example: 12345
isPlaidConnectedbooleanWhether the bank account was connected through Plaid
Example: true
institutionNamestringName of the bank returned by Plaid (optional). Not returned for bank accounts entered manually, for Plaid bank accounts connected before this field was available, or when Plaid did not return the bank’s name
Example: Chase

​
Create a Bank Account

Sequence of Events:

  1. Your system sends a request to create a bank account using an external ID and associates it with an existing taxpayer
  2. The request body varies by paymentNetwork — provide routingNumber for Ach, or institutionNumber and transitNumber for Eft
  3. Remitian responds with the created bank account’s details
  4. Your system can then use this id for subsequent operations

HTTP Request (ACH):

POST https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/bank-accounts
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

{
  "externalId": "my_ach_account_123",
  "paymentNetwork": "Ach",
  "bankAccountName": "Business Checking",
  "accountNumber": "000123456789",
  "routingNumber": "021000021"
}

HTTP Request (EFT):

POST https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/bank-accounts
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

{
  "externalId": "my_eft_account_456",
  "paymentNetwork": "Eft",
  "bankAccountName": "Operating Account",
  "accountNumber": "1234567",
  "institutionNumber": "001",
  "transitNumber": "12345"
}

HTTP Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "079bc3f4-d65e-73f7-8133-f5800e825515",
  "externalId": "my_ach_account_123"
}

​
List Bank Accounts

Sequence of Events:

  1. Your system sends a request to list all bank accounts associated with a specific taxpayer
  2. You can filter bank accounts by externalId and page the results with pageNumber and pageSize
  3. Remitian responds with a paginated list of bank accounts

HTTP Request:

GET https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/bank-accounts?externalId=my_ach_account_123&pageNumber=1&pageSize=50
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

HTTP Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "id": "079bc3f4-d65e-73f7-8133-f5800e825515",
      "externalId": "my_ach_account_123",
      "taxpayerId": "029bc3f4-d65e-73f7-8133-f5800e825510",
      "bankAccountName": "Business Checking",
      "accountNumber": "000123456789",
      "paymentNetwork": "Ach",
      "routingNumber": "021000021",
      "isPlaidConnected": true,
      "institutionName": "Chase"
    },
    {
      "id": "089bc3f4-d65e-73f7-8133-f5800e825516",
      "externalId": "my_eft_account_456",
      "taxpayerId": "029bc3f4-d65e-73f7-8133-f5800e825510",
      "bankAccountName": "Operating Account",
      "accountNumber": "1234567",
      "paymentNetwork": "Eft",
      "institutionNumber": "001",
      "transitNumber": "12345",
      "isPlaidConnected": false
    }
  ],
  "currentPage": 1,
  "pageSize": 50,
  "totalCount": 2,
  "totalPages": 1
}

​
Delete a Bank Account

Sequence of Events:

  1. Your system sends a request to delete a specific bank account associated with a taxpayer
  2. Remitian removes the bank account and responds with no content
  3. If the bank account does not exist for the taxpayer, Remitian responds with 404 Not Found

HTTP Request:

DELETE https://public-api.remitian.com/v1/taxpayers/{taxpayerId}/bank-accounts/{bankAccountId}
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

HTTP Response:

HTTP/1.1 204 No Content

​
Firm Bank Accounts

A firm can register its own bank account, separate from the bank accounts of its taxpayers. Firm bank accounts are ACH only, and are identified on incoming credits by the optional fundingCompanyId.

Firm Bank Account Object Structure:

FieldTypeDescription
idguidUnique identifier for the bank account
Example: 079bc3f4-d65e-73f7-8133-f5800e825517
externalIdstringYour system’s unique identifier (optional)
Example: my_firm_account_789
firmIdguidAssociated firm identifier
Example: 019bc3f4-d65e-73f7-8133-f5800e825501
bankAccountNamestringName of the bank account
Example: Firm Operating Account
accountNumberstringBank account number
Example: 000987654321
paymentNetworkstringPayment network, always Ach
routingNumberstring9-digit routing number
Example: 021000021
fundingCompanyIdstringACH Company ID the firm originates its credits from (optional, up to 50 characters). Unique across all bank accounts
Example: 1234567890

​
Create a Firm Bank Account

Sequence of Events:

  1. Your system sends a request to create a bank account for an existing firm
  2. Remitian responds with the created bank account’s details
  3. If the firm already has a bank account with the same routing and account number, or the fundingCompanyId is already registered to another bank account, Remitian responds with 409 Conflict
  4. If the firm does not exist, Remitian responds with 404 Not Found

HTTP Request:

POST https://public-api.remitian.com/v1/firms/{firmId}/bank-accounts
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

{
  "externalId": "my_firm_account_789",
  "bankAccountName": "Firm Operating Account",
  "accountNumber": "000987654321",
  "routingNumber": "021000021",
  "fundingCompanyId": "1234567890"
}

HTTP Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "079bc3f4-d65e-73f7-8133-f5800e825517",
  "externalId": "my_firm_account_789"
}

​
List Firm Bank Accounts

Sequence of Events:

  1. Your system sends a request to list the bank accounts of a specific firm
  2. You can page the results with pageNumber and pageSize
  3. Remitian responds with a paginated list of the firm’s bank accounts. Bank accounts of the firm’s taxpayers are not included

HTTP Request:

GET https://public-api.remitian.com/v1/firms/{firmId}/bank-accounts?pageNumber=1&pageSize=50
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY

HTTP Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    {
      "id": "079bc3f4-d65e-73f7-8133-f5800e825517",
      "externalId": "my_firm_account_789",
      "firmId": "019bc3f4-d65e-73f7-8133-f5800e825501",
      "bankAccountName": "Firm Operating Account",
      "accountNumber": "000987654321",
      "paymentNetwork": "Ach",
      "routingNumber": "021000021",
      "fundingCompanyId": "1234567890"
    }
  ],
  "currentPage": 1,
  "pageSize": 50,
  "totalCount": 1,
  "totalPages": 1
}