Opening a Master Account

In this tutorial we explore the account opening process. This tutorial assumes you have already completed the Onboarding Customers tutorial. Before starting this tutorial, please make sure you have the following:

API credentials
Partner ID
Customer ID
Product ID

Get an Access Token

Before calling the COS API you must first request an access token. Once the access token has been obtained it is recommended that it is cached for the lifetime of the token. If the API starts to return a 401 response code, it is likely that your token has expired and you need to obtain a new one. More details can be found here.

Register Webhooks

Webhooks allow us to receive notifications when certain events occur within COS. We will want to be informed once the account is opened. For that you will need to call the webhook registration endpoint and indicate you wish to receive Core.Account.Opened events. An example of the webhook registration call is provided below.

POST /webhooks/v1/registrations
{
  "partnerId": "00000000-0000-0000-0000-000000000000",
  "eventName": "Core.Account.Opened",
  "registrationType": "Push", 
  "callbackUrl": "https://cos.yourcompanysite.com/core-events"
}

To learn more about webhook registrations click here. For a full listing of available customer webhook events click here.

Open an Account

In this scenario, you'll be opening an account for a Bob Smith, a customer that you've successfully onboarded.

POST /core/v1/dda/accounts
{
  "customerId": "00000000-0000-0000-0000-000000000000",
  "productId": "00000000-0000-0000-0000-000000000000",
  "title": "Bob Smith",
  "statementAddress": {
    "street1": "123 Any Street",
    "city": "Anywhere",
    "state": "NY",
    "postalCode": "12345",
    "countryCode": "US"
  }
}

🚧
It is highly recommended that you include an idempotency key in your request header. This will provide duplicate protection in the event of a failure. Read more about idempotency keys here.

Here's a sample response body based on the above request:

{
  "accountNumber": "2348751955",
  "status": "Active",
  "accountType": "Deposit",
  "ledgerType": "Passthrough",
  "classification": "Personal",
  "productType": "Checking",
  "productId": "44015e68-1afb-40fc-9497-abc1014f52da",
  "title": "Bob Smith",
  "currentBalance": 0,
  "holdAmount": 0,
  "transactionCount": 0,
  "availableBalance": 0,
  "creditLimit": 0,
  "customerId": "59e3bc15-bbec-4990-88e9-a9a600d3296c",
  "statementAddress": {
    "street1": "123 Any Street,
    "city": "Anywhere",
    "state": "NY",
    "postalCode": "12345",
    "countryCode": "US"
  },
  "openedAt": "2021-01-26T09:46:10.0931461-05:00",
  "lastMaintenanceAt": "2021-01-26T09:46:10.0931461-05:00",
  "partnerId": "e6c3824a-377f-44d5-a2f6-a9a600c9b37e",
  "lastModifiedAt": "2021-01-26T09:46:10.1011462-05:00"
}

After an account is successfully opened, its status will automatically update to Active and becomes immediately available for use. This will also trigger the Core.Account.Opened event:

{
  "id": "259cdbca-6a89-4af8-a50e-ada3010fb13f",
  "eventName": "Core.Account.Opened",
  "status": "Pending",
  "partnerId": "e6c3824a-377f-44d5-a2f6-a9a600c9b37e",
  "createdAt": "2021-01-26T09:48:10.1011462-05:00",
  "resources": [
    "core/v1/dda/accounts/2235223803"
  ],
  "details": []
}