Virtual Accounts

The OpenTransact API is able to connect to financial instutions that enable Virtual Bank Accounts, sometimes referred to as a virtual DDA account. This guide will walk through integrating with the OpenTransact API for the purposes of connectiong to one of the integrated partners that supports processing payments and managing a virtual account structure.

Intro to Virtual Accounts

For all intents and purposes, OpenTransact treats Virtual Accounts like any other Bank Account in the system. The Virtual Account is stored in the OpenTransact API in the same way as any other standard bank account (See docs for BankAccount). When creating the account, your financial institution may have specific requirements regarding a specific sequence or range of account numbers which you can create for use with their system. Your application should choose a valid account number and create the account as normal.

If your application needs to manage other standard external Bank Accounts, you can use the Rules Engine to only trigger Virtual Account creation for accounts matching a specified range (standard), or optionally use a value in the Account’s metadata object as a trigger.

If a Transaction is reported by the financial institution to OpenTransact, and it does not match any existing Virtual Account within the OpenTransact API, one will be created automatically.

ACH and other ledger transactions that occur against the Virtual Account will typically be reported by the financial institution to OpenTransact via a direct API or file transfer integration on a daily schedule, typically with multiple batch files per day.

You may also wish to originate ACH transactions on behalf of your customers using the Virtual Account. See the ACH Transactions guide for more details on how to do this.

Integration Basics

1: Monitor the Activity Stream for New Accounts & Transactions

Create a process that will run on a regular basis to check for new accounts and transactions using the List Activities endpoint. You or your system must monitor this endpoint for any new transactions that are reported by your financial institution in case there is a need to return a particular transaction since there is a limited time window for most ACH returns to be processed.

# Fetch the Account to check the status
curl --request GET \
  --url 'https://api.opentransact.com/v1/activities?filter%5Bapplication-id%5D={APPLICATION_ID}' \
  --header 'Authorization: Basic {AUTH_TOKEN}'

2: Creating an ACH Return

If you want to ‘decline’ or return a transaction, please Create an ACH Return object for the appropriate return type and ensure youve created it within the timeline specified by your institution. It will be delivered to the financial institution and processed with the next scheduled batch.

# Return a transaction
curl --request POST \
  --url https://api.opentransact.com/v1/ach-returns \
  --header 'Authorization: Basic {AUTH_TOKEN}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
	"data": {
		"type": "ach-returns",
      "attributes": {
        "code": "R01",
        "metadata": {
          "program": "virtual-account"
        }
      },
      "relationships": {
        "transaction": {
          "data": {
            "type": "transactions",
            "id": "{TRANSACTION_ID}"
          }
        }
      }
   }
}'

Risk Management Reporting

Connected financial institutions will often require additional information to be reported to them in order to manage risk. OpenTransact will provide the data fields that are required and they will typically need to be set on the metadata object of the Account, Profile, or Transaction objects as appropriate.