Update home.md (cf80b678) · Commits · finance / Public Documentation

billing-service/home.md

+34 −18

Original line number	Diff line number	Diff line
		# Billing Service
		[[_TOC_]]
		## Overview
		Billing Service is a REST API which provides an interface for DoIT's Financial System, CBS.
		This service allows DoIT Service Providers to send bills for their users to CBS.

		@@ -12,6 +9,8 @@ Our initial clients are SEO Service Providers for infrastructure services includ
		We also intend the Billing Service to be used for reporting purposes and customer inquiries.
		Please see [Reporting Database](./docs/reporting-database.md) for more information.

		[[_TOC_]]

		### OpenAPI Specification

		Here is a link to our OpenAPI Specification: https://api.test.billing.doit.wisc.edu/api-docs/
		@@ -30,15 +29,18 @@ The Billing Service API has three resources, `Charge`, `FundingSource`, and `Ser
		#### Charge
		The `Charge` resource represents a bill for a customer.

		The Billing Service is responsible for submitting valid charges to CBS.
		`Charge` resource submission to CBS happens asynchronously from when a user creates the `Charge` resource in the Billing Service.
		This allows users of the Billing Service to create `Charge` resources without depending on the availability of CBS.
		The `Charge` resource can represent a "Showback" or a "Chargeback" bill. This is indicated by the `billable` property on the resource.

		The Billing Service is responsible for submitting valid "Chargeback" charges to CBS.

		The Billing Service considers a charge valid if it meets the following criteria:
		* The charge is billable (`billable` property is true)
		* The charge is billed to a valid `FundingSource` (contains `fundingSourceId` property of a valid `FundingSource`).
		* The charge is billable (`billable` property is true).
		* The charge is billed to an `active` and `chargeback` `FundingSource` resource (contains `fundingSourceId` property of an `active` and `chargeback` `FundingSource` resource).
		* The charge is for a valid `Service` (contains `serviceId` property of a valid `Service`)

		`Charge` resource submission to CBS happens asynchronously from when a user creates the `Charge` resource in the Billing Service.
		This allows users of the Billing Service to create `Charge` resources without depending on the availability of CBS.

		__Example__
		```
		{
		@@ -68,7 +70,7 @@ __Example__
		"errors": [
		{
		"code": 201,
		"message": "Funding Source is not valid."
		"message": "Funding Source is not active."
		"relatedResource": "http://api.test.billing.doit.wisc.edu/fundingSource/5678efgh-12ab-34cd-56ef-1234abcd90ij"
		}
		]
		@@ -100,8 +102,8 @@ The Billing Service is not responsible for submitting credits for customers.
		Please contact Financial Services for more information (projectbilling@doit.wisc.edu) regarding Customer Credits.

		#### FundingSource
		The `FundingSource` resource represents the funding string a bill is charged to.
		A `FundingSource` can be one of two types, Dnumber/UDDS type or Project/Task type.
		The `FundingSource` resource represents the funding string a bill is charged against.
		A `FundingSource` can be one of two types, Dnumber/UDDS type or Project/Task type. They will also indicate if they can be used for Showback and/or Chargeback purposes.

		__Example__

		@@ -110,10 +112,11 @@ A `FundingSource` resource with a Dnumber and UDDS.
		{
		"id": "5678efgh-12ab-34cd-56ef-1234abcd90ij",
		"name": "Division of Information technology:Enterprise Integrations",
		"billable": true,
		"chargeback": true,
		"showback": true,
		"dnumber": "D000101",
		"udds": "A001001",
		"valid": true,
		"active": true,
		"validationMessage": "Funding Source has been validated.",
		"createdDate": "2020-01-01T00:00:00.000Z"
		}
		@@ -125,10 +128,11 @@ A `FundingSource` resource with a Project and Task.
		{
		"id": "5678efgh-12ab-34cd-56ef-1234abcd90ij",
		"name": "CBS - Support",
		"billable": true,
		"chargeback": true,
		"showback": true,
		"project": "1001018",
		"task": "200",
		"valid": true,
		"active": true,
		"validationMessage": "Funding Source has been validated.",
		"createdDate": "2020-01-01T00:00:00.000Z"
		}
		@@ -138,7 +142,9 @@ The user submitting a charge is responsible for getting the correct funding stri
		If a `FundingSource` resource with the funding string exists in the Billing Service, its `id` property can be used in a `Charge` resource.

		The Billing Service validates `FundingSource` resources against CBS.
		If a `FundingSource` resource is not valid, `Charge` resources using it will fail the submission process.
		If a `FundingSource` resource is not `active` in CBS, `Charge` resources using it will fail the submission process.

		When creating Showback/Chargeback charges, they need to use the appropriate Showback/Chargeback `FundingSource`.

		#### Service
		The `Service` resource represents the service a bill is charged for.
		@@ -159,7 +165,17 @@ To further familiarize yourself with REST APIs please use the resources below:

		### Example

		DoIT Bucky Backup service needs to send charges to CBS
		* Physical Hosting/CCI usage data is added to CMDB
		* Charge amounts are calculated for customers based on their usage
		* Identify any charges that are missing required information to submit to API
		* Charges are submitted to the billing service API
		* The IDs for services are saved in CMDB
		* The IDs for customer's funding sources are looked up before submitting the charge
		* Showback charges are submitted with billable set to false
		* Chargeback charges are submitted with billable set to true
		* Chargeback charges are checked for updates to determine when they are submitted and processed by CBS
		* If a charge has an error and was unable to be submitted to CBS the error will be saved to a dashboard
		* Errors are reviewed on the dashboard and resolved which causes the charge to be submitted

		## Related Documentation