How the demo app works
A closer look at the functionality of the bill pay demo app
Now you're ready to explore the functionality of the bill pay demo app in more depth. The user flow diagrams describe the demo app's functionality at a high level, while the example API calls show the exchange of data with the Codat API.
Understand the authorization flow
The company creation feature and authorization flow were built using the Platform API and Hosted Link. For a seamless user experience, we customized the Hosted Link flow with the same branding and colors as the demo app UI - see Customize Link for more details.
The main features are:
- Creating a company to represent the user using the Create company endpoint. This returns a unique company ID and Link URL.
- Redirecting the user to their chosen accounting platform (in this case, QuickBooks Online) via the Link URL. This opens the OAuth login window for the accounting platform, where the user can authenticate and authorize access to their accounting data.
- Creating a data connection to the accounting platform using the Create connection endpoint.
- When the company is successfully connected, redirecting the user to the demo app's redirect URL, as defined in the Link settings.
View bills
The following diagram illustrates the user flow for viewing bills in the demo app UI.
Fetch Bills (API call: List bills)
When launched, the demo app retrieves a list of all bills from your sandbox QuickBooks Online company, in descending order of issue date.
Here is an example request:
GET https://api.codat.io/companies/<COMPANY_ID>/data/bills?page=1&pageSize=100&orderBy=-issueDate
{
"results": [
{
"id": "181",
"supplierRef": {
"id": "41",
"supplierName": "Mac's Supply Store"
},
"purchaseOrderRefs": [],
"issueDate": "2023-04-01T00:00:00",
"dueDate": "2023-04-01T00:00:00",
"currency": "GBP",
"currencyRate": 1,
"lineItems": [
{
#...
}
],
"withholdingTax": [],
"status": "Open",
"subTotal": 1250,
"taxAmount": 250,
"totalAmount": 1500,
"amountDue": 1500,
"modifiedDate": "2023-05-02T10:35:04Z",
"sourceModifiedDate": "2023-03-27T23:30:01Z",
"paymentAllocations": [],
"metadata": {
"isDeleted": false
}
},
# ...
],
"pageNumber": 1,
"pageSize": 100,
"totalResults": 8,
"_links": {
"current": {
"href": "/companies/0f655a48-f6c2-43b4-857b-f2d6793f90b8/data/bills?page=1&pageSize=100&orderBy=-issueDate"
},
"self": {
"href": "/companies/0f655a48-f6c2-43b4-857b-f2d6793f90b8/data/bills"
}
}
}
When the View unpaid bills only toggle is selected in the UI, the &query=status=Open query is appended to the request URL as a Codat query string. This returns only unpaid bills.
Fetch Accounts (API call: List accounts)
When launched, the demo app fetches the company's latest accounts. The account name is displayed against its respective bill in the Reference column of the bills table.
Here is an example request:
GET https://codat.io/companies/<COMPANY_ID>/data/accounts
{
"results": [
{
"id": "84",
"name": "Accounts Receivable (A/R)",
"fullyQualifiedCategory": "Asset.Accounts Receivable.AccountsReceivable",
"fullyQualifiedName": "Asset.Accounts Receivable.AccountsReceivable.Accounts Receivable (A/R)",
"currency": "USD",
"currentBalance": 5281.52,
"type": "Asset",
"status": "Active",
"isBankAccount": false,
"modifiedDate": "2023-05-11T09:46:07Z",
"sourceModifiedDate": "2023-03-12T20:16:17Z",
"validDatatypeLinks": [],
"metadata": {
"isDeleted": false
}
},
#...
],
"metadata": {
"isDeleted": false
}
}
],
"pageNumber": 1,
"pageSize": 100,
"totalResults": 90,
"_links": {
"current": {
"href": "/companies/3e67a1ea-a124-4a54-a241-698169eb19fb/data/accounts?page=1"
},
"self": {
"href": "/companies/3e67a1ea-a124-4a54-a241-698169eb19fb/data/accounts"
}
}
}
Pay a bill
The following diagram illustrates the user flow for selecting and paying a bill in the demo app UI.
The bill remains in a pending status during the polling process.
When selecting an account in the Bill Payment dialog, the Account name dropdown only displays banking accounts in the same currency as the bill. The account type is determined using a query parameter for isBankAccount=true.
The Bill payment will be assigned to the selected account in your sandbox QuickBooks Online company.
Pay a bill (API call: Create bill payments)
When you pay a bill, the demo app creates a Bill payment in QuickBooks Online for the total amount due. This process reconciles the payment against the outstanding bill.
Here is an example request:
POST https://api.codat.io/companies/<COMPANY_ID>/connections/<CONNECTION_ID>/push/billPayments
{
"supplierRef": {
"id": "<SUPPLIER_ID>" // ID of the supplier to reconcile payment against
},
"accountRef": {
"id" : "<ACCOUNT_ID>" // ID of the bank account for the payment
},
"totalAmount": 2400.00,
"date": "<ISO_TIMESTAMP>", // date and time of payment
"currency": "USD",
"lines": [
{
"amount": 2400.00, // total amount of bill
"links": [
{
"type": "Bill",
"id": "<BILL_ID>", // separate link for each bill the bill payment should be reconciled against
"amount": -2400.00
}
]
}
]
}
💪 Ready for more?
Try these suggestions to make the most of your experience with the demo app:
Access sandbox data for a different region
You can set up a sandbox QuickBooks Online company that contains data for a different region, then run through the demo app guide again. For more information, see Create and test with a sandbox company in the Intuit developer documentation.Expand the app's functionality
Go one step further and develop other features that make the Accounts Payable process simpler for your customers. For example, you could provide the ability to pay a bill using a credit note or create a new bill from within your application.Further reading
Explore accounting automation topics in the Codat Blog.
Find out more about Sync for Payables or explore our other use cases.