Configure your SMB customer in Codat

Create a company and its connection that form the structure required to execute the bill pay process

Overview

When implementing your Bill Pay solution, you need to create your SMB customer as a company in Codat before registering their accounting software as a connection. You can do that when the customer starts interacting with your application.

We have highlighted this sequence of steps in our detailed process diagram below.

Detailed process diagram

Authorize your API calls

Remember to authenticate when making calls to our API. Navigate to Developers > API keys in the Portal to pick up your authorization header.

Create a company

Within Bill Pay, a company represents your SMB customer that pays and manages their bills using your application. To create it, use our Create company (async) or Create company (sync) endpoints.

The endpoints return the company schema containing the ID that you will use to establish a connection to an accounting software.

TypeScript

const companyResponse = payablesClient.companies.create({
    name: companyName,
});

if(companyResponse.statusCode == 200){
  throw new Error("Could not create company")
}

const companyId = companyResponse.company.id
console.log(companyId)

Python

company_request = shared.CompanyRequestBody(
    name=company_name,
)

company_response = payables_client.companies.create(company_request)

if company_response.status_code != 200:
  raise Exception('Could not create company')

company_id = company_response.company.id
print(company_id)

C#

var companyResponse = await payablesClient.Companies.CreateAsync(new() {
    Name = companyName,
});

if(companyResponse.StatusCode != 200){
  throw new Exception("Could not create company");
}

var companyId = companyResponse.Company.Id;
console.log(companyId)

Go

ctx := context.Background()
companyResponse, err := payablesClient.Companies.Create(ctx, &shared.CompanyRequestBody{
  Name: companyName,
	})

if companyResponse.StatusCode == 200 {
  companyID := companyResponse.Company.ID
  fmt.Println("%s", companyID)
}

Create a connection

Next, use the Create connection (async) or Create connection (sync) endpoints to connect the company to an accounting data source via one of our integrations.

This will allow you to synchronize data with that source, fetching or creating suppliers, bills, and payment methods. In the request body, specify a platformKey of the accounting software you're looking to connect.

Async Bill Pay

Accounting software	platformKey
MYOB Business	pdvj
Oracle NetSuite	akxx
QuickBooks Online	qhyg
QuickBooks Desktop	pqsw
Sage Intacct	knfz
Xero	gbol

Sync Bill Pay

Accounting software	platformKey
FreeAgent	fbrh
Oracle NetSuite	akxx
QuickBooks Online	qhyg
Xero	gbol

As an example, let's create a QuickBooks Online (QBO) connection. In response, the endpoint returns a dataConnection object with a PendingAuth status and a linkUrl. Direct your customer to the linkUrl to initiate our Link auth flow and enable them to authorize this connection.

TypeScript

const connectionResponse = payablesClient.connections.create({
    requestBody: {
      platformKey: "qhyg",
    },
    companyId: companyResponse.company.id,
  });

console.log(connectionResponse.connection.linkUrl)

Python

connection_request = operations.CreateConnectionRequest(
    request_body=operations.CreateConnectionRequestBody(
        platform_key='qhyg',
    ),
    company_id=company_response.company.id,
)

connection_response = payables_client.connections.create(connection_request)

console.log(connection_response.connection.link_url)

C#

var connectionResponse = await payablesClient.Connections.CreateAsync(new() {
    RequestBody = new CreateConnectionRequestBody() {
        PlatformKey = "qhyg",
    },
    CompanyId = companyResponse.Company.Id,
});

Console.WriteLine(connectionResponse.Connection.LinkUrl)

Go

ctx := context.Background()
connectionResponse, err := payablesClient.Connections.Create(ctx, operations.CreateConnectionRequest{
    RequestBody: &operations.CreateConnectionRequestBody{
        PlatformKey: syncforpayables.String("qhyg"),
    },
    CompanyID: companyResponse.Company.ID,
})

fmt.Println(connectionResponse.Connection.LinkUrl)

Deauthorize a connection

If your customer wants to revoke their approval and sever the connection to their accounting software, use the Unlink connection (async) or Unlink connection (sync) endpoints.

You can learn more about connection management best practices and see how you can provide this functionality in your app's UI.

TypeScript

const unlinkResponse = payablesClient.connections.unlink({
    requestBody: {
      status: DataConnectionStatus.Unlinked
    },
    companyId: companyResponse.company.id,
    connectionId: connectionResponse.connection.id,
  });

Python

unlink_request = operations.UnlinkConnectionRequest(
    request_body=operations.UnlinkConnectionUpdateConnection(
      status=shared.DataConnectionStatus.UNLINKED
    ),
    company_id=company_response.company.id,
    connection_id=connection_response.connection.id,
)

unlink_response = payables_client.connections.unlink(unlink_request)

C#

var unlinkResponse = await payablesClient.Connections.UnlinkAsync(new() {
    RequestBody = new UnlinkConnectionUpdateConnection() {
      Status = DataConnectionStatus.Unlinked
    },
    CompanyId = companyResponse.Company.Id,
    ConnectionId = connectionResponse.Connection.Id,
});

Go

ctx := context.Background()
unlinkResponse, err := payablesClient.Connections.Unlink(ctx, operations.UnlinkConnectionRequest{
    RequestBody: &operations.UnlinkConnectionUpdateConnection{
      Status: shared.DataConnectionStatusUnlinked
    },
    CompanyID: companyResponse.Company.ID,
    ConnectionID: connectionResponse.Connection.ID,
})

Recap

You have created the structure of key objects required by Codat's Bill Pay solution: a company and its connection to an accounting data source.

Next, you can choose to manage your customer's suppliers, bills or payment methods prior to paying the bills.

---

Read next

• Manage your customer's suppliers asynchronously or synchronously
• Manage your customer's bills asynchronously or synchronously
• Pay your customer's bills asynchronously or synchronously