...
JSON based representation of the managed entities and tasks.
...
A BillingAccount is a detailed description of a customer's bill structure.
JSON representation of a BillingAccount
...
Hide If |
---|
|
Note |
---|
title | To access this API specification you wil need to be logged in |
---|
| To login with your TM Forum account please click on the Login button below Button Hyperlink |
---|
title | Login |
---|
type | primary |
---|
url | https://projects.tmforum.org/wiki/login.action?os_destination=%2Fdisplay%2FAPI%2FOpen%2BAPI%2BTable |
---|
|
Don't have an account? You can register by clicking here: Button Hyperlink |
---|
title | Register |
---|
type | primary |
---|
url | https://www.tmforum.org/user-registration/ |
---|
target | true |
---|
|
|
|
Show If |
---|
|
Managed Entity and Task Resource ModelsJSON based representation of the managed entities and tasks. BillingAccount ResourceA BillingAccount is a detailed description of a customer's bill structure. JSON representation of a BillingAccount |
...
...
...
...
...
...
...
...
"my personal Billing Account", "state": " |
|
...
...
...
...
...
2013-04-19T16:42:23.0Z" }, " |
|
...
...
...
...
...
...
...
...
"Customer Account xxx" }, " |
|
...
customerBillingCycleSpecification": { " |
|
...
...
...
...
...
...
Monthly billing on the 15" } |
|
...
...
...
...
...
...
...
...
...
Detailed invoice" }, "customerBillPresentationMedia": { "id": " |
|
...
...
...
...
...
...
...
...
...
...
...
billingAccountBalance": [ { "type" |
|
...
...
...
...
...
2013-04-19T16:42:23.0Z", " |
|
...
...
2013-06-19T00:00:00.0Z" }, " |
|
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
Field Descriptions :
BillingAccount: A detailed description of a customer's bill structure.
Field | Description |
id | Unique identifier of the billing account |
href | Reference of the billing account |
name | A short descriptive name |
ratingType | Rating type (prepaid, postpaid) of the billing account |
state | Used to track the lifecycle state |
validFor. | The period for which the billing account is valid |
...
Field | Description |
type | Type of the balance |
amount | Balance amount |
validFor | Balance validity period |
status | Balance status |
...
Customer billing cycle specification Resource Field Descriptions : BillingAccount: A detailed description of a customer's bill structure |
Field | Description |
id | Unique identifier of the customer account |
href | Reference of the customer account |
name | A short descriptive name |
CustomerBillingCycleSpecification: A detailed description of when to initiate a billing cycle and the various sub steps of a billing cycle
. Field | Description | id | Unique identifier of the |
|
...
...
...
billingDateShift
...
An offset of a billing date. The offset is expressed as number of days with regard to the start of the billing period.
...
frequency
...
Frequency of the billing cycle (monthly for instance)
href | Reference of the billing account |
|
...
href
...
| name | A short descriptive name |
|
...
| ratingType | Rating type (prepaid, postpaid) of the billing account | state | Used to track the lifecycle state | validFor. | The period for which the billing account is valid |
BillingAccountBalance: Balance of the Billing Account
|
CustomerBillFormat: A detailed description of the way in which a customer's bill is presented...
...
...
...
href
...
Reference of the customer bill format
...
name
...
A short descriptive name
amount | Balance amount | validFor | Balance validity period | status | Balance status |
CustomerAccount: An arrangement that a customer has with an enterprise that provides products to the customer (SID definition to be reviewed?)
|
CustomerBillPresentationMedia: A means of communicating a CustomerBill, supported by the associated bill format. For example, post mail, email, web page. Field | Description | id | Unique identifier of the customer |
|
...
account | href | Reference of the customer |
|
...
account | name | A short descriptive name |
|
Currency CustomerBillingCycleSpecification: A
|
base / value business entity used to represent currencydetailed description of when to initiate a billing cycle and the various sub steps of a billing cycle. |
...
currencyCode
...
A string used as a code for specifying the currency associated to the given amounts. The ISO4217 norm uses 3 letters to define the currency (for example USD for US dollar or EUR for Euro)
| id | Unique identifier of the customer billing cycle specification | billingDateShift | An offset of a billing date. The offset is expressed as number of days with regard to the start of the billing period. | frequency | Frequency of the billing cycle (monthly for instance) | href | Reference of the customer billing cycle specification | name | A short descriptive name |
CustomerBillFormat: A detailed description of the way in which a customer's bill is presented
|
PaymentMean: defines a specific mean of payment (e.g. direct debit with all details associated). Field | Description | id | Unique identifier of the |
|
...
customer bill format | href | Reference of the |
|
...
...
Name of the payment mean
CustomerBillPresentationMedia: A means of communicating a CustomerBill, supported by the associated bill format. For example, post mail, email, web page
|
RelatedParty: Defines party or partyRole linked to a specific entity. Field | Description | id | Unique identifier of |
|
...
the customer bill presentation media | href | Reference of the |
|
...
role
...
Role of the related party
...
customer bill presentation media | name | A short descriptive name |
Currency: A base / value business entity used to represent currency.
Field | Description | currencyCode | A string used as a code for specifying the currency associated to the given amounts. The ISO4217 norm uses 3 letters to define the currency (for example USD for US dollar or EUR for Euro) |
PaymentMean: defines a specific mean of payment (e.g. direct debit with all details associated).
Field | Description | id | Unique identifier of the payment mean | href | Reference of the payment mean | name | Name of the payment mean |
RelatedParty: Defines party or partyRole linked to a specific entity.
Field | Description | id | Unique identifier of related party | href | Reference of the relatedParty, could be a party reference or a partyRole reference | role | Role of the related party |
UML models: Image Added Figure 1 – BillingAccount resource model Image Added Figure 2 – CustomerBillPresentationMedia resource model Image Added Figure 3 CustomerBillingCycleSpecification resource model Image Added Figure 4 CustomerBillFormat resource model
applied customer billing charge Resource |
...
...
...
...
...
...
...
...
...
...
...
Field
...
Description
...
id
...
Unique identifier of the applied customer billing charge
...
href
...
Reference of the applied customer billing charge
"productSpecification": [ { "name": "Partner Premium", "productNumber": "P001" } ], "period": [ { "startPeriod": "2013-10-01T00:00:00.0Z", "endPeriod": "2013-10-31T00:00:00.0Z" } ] } |
Tax rate should be further defined by experts. Field Descriptions : AppliedCustomerBillingCharge: An amount, usually of money, for which a person or an organization is financially liable.
Field | Description | id | Unique identifier |
|
...
date
...
of the applied customer billing charge |
|
...
description
...
href | Reference of the applied customer billing charge | date | Creation date of the applied customer billing charge | description | Additional data to be displayed on the customer bill for this applied customer billing charge | type | Type of the applied customer billing charge (recurring, one time or usage) necessary to find the category of the invoice where the charge has to be displayed | currencyCode | A string used as a code for specifying the currency associated to the given amounts. The ISO4217 norm uses 3 letters to define the currency (for example USD for US dollar or EUR for Euro) | taxIncludedAmount | All taxes included amount to be charged on the customer bill (expressed in the given currency) | taxExcludedAmount | Tax excluded amount to be charged on the customer bill (expressed in the given currency) |
AppliedCustomerBillingTaxRate: An amount of money levied on the price of a product by a legislative body.
Field | Description | amount | Tax amount | taxCategory | A categorization of the tax rate |
Period: defines the period of a recurring charge
Field | Description | startPeriod | Start date of the period | endPeriod | End date of the period |
ProductSpecification: A detailed description of a tangible or intangible object made available externally in the form of a ProductOffering to Customers or other Parties playing a PartyRole.
Field | Description | productNumber | An identification number assigned to uniquely identity the specification | Name | The name of the product specification |
ServiceId: defines the identifier of the service
Field | Description | id | Identifier of the service | type | Type of the service identifier (e.g. mobile number) |
UML models: Image Modified Figure 5 AppliedCustomerBillingCharge (Bill Item) resource model
|
...
Settlement note ADVICE Resource{ "id": "26", "href": "http://serverlocation:port/BillingManagement/settlementNoteAdvice/26", "date": "2013-04-19T16:42:23.0Z", "description": "Settlement note â€" From 2013/10/01 to 2013/10/31", "paymentDueDate": "2013-04-19T16:42:23.0Z", "taxDate": "2013-04-19T16:42:23.0Z", "currencyCode": "EUR", "taxExcludedAmount": 89933.25, "taxIncludedAmount": 107560.16, "taxItem": [ { "taxCategory": "VAT", "taxRate": 19.6, "taxAmount": 17626.91 } ], "settlementMethod": { "code": "NET", "label": "Netting" }, "receiver": { "id": "63796", "href": "http://serverlocation:port/PartyManagement/partyRole/63796", "taxRegistration": { "number": "FR12345678912" } }, "issuer": { "id": "0800", "href": "http://serverlocation:port/PartyManagement/partyRole/0800", "taxRegistration": { "number": "FR98765432178" } }, "settlementNoteImage": { "imageFormat": "pdf", "imageSize": 130, "imageFileName": "BungiornoFrance-2013October-1234", "imageFileURL": "http://serverlocation:port/SettlementNoteImage/RQAAAABAAAAAAAAALryCQAbAAAAMAAxAF8ASQBuAHMAdABhAGwAb" }, "settlementNoteItem": [ { "itemNumber": "1", "itemId": "0815", "itemLabel": "Achats Gamifive", "quantity": 34873, "taxExcludedUnitPrice": 1.463, "taxExcludedAmount": 51019.2, "taxIncludedAmount": 61018.96, "taxItem": [ { "taxCategory": "VAT", "taxRate": 19.6, "taxAmount": 9999.76 } ], "period": { "startPeriod": "2013-10-01T00:00:00.0Z", "endPeriod": "2013-10-31T00:00:00.0Z" }, "productSpecification": { "name": "Gamifive", "productNumber": "17060" } }, { "itemNumber": "2", "itemId": "0816", "itemLabel": "Achats iGirls TV", "quantity": 19001, "taxExcludedUnitPrice": 2.048, "taxExcludedAmount": 38914.05, "taxIncludedAmount": 46541.2, "period": { "startPeriod": "2013-10-01T00:00:00.0Z", "endPeriod": "2013-10-31T00:00:00.0Z" }, "productSpecification": { "name": "iGirls TV", "productNumber": "17063" } } ] } |
Field Descriptions : SettlementNoteAdvice: The settlement is about transferring money receiving by a CSP to a partner. The settlement is notified to the partner with a settlement note advice containing details in settlement lines.
Field | Description | id | A unique identifier for the settlement note advice | date | Creation date of the settlement note advice | description | A free description text | href | Reference of the settlement note advice | paymentDueDate | Date at which the due amount should have been paid to the partner | taxDate | Date of the tax | currencyCode | A string used as a code for specifying the currency associated to the given amounts. The ISO4217 norm uses 3 letters to define the currency (for example USD for US dollar or EUR for Euro) | taxExcludedAmount | All taxes excluded amount (expressed in the given currency) | taxIncludedAmount | All taxes included amount (expressed in the given currency) |
TaxItem: A tax item is created for each tax rate and tax type used in the settlement note.
Field | Description | taxCategory | Tax category (for example VAT) | taxRate | Tax rate | taxAmount | Tax amount |
SettlementMethod: is the way in which the CSP provides the payment.
Field | Description | Code | Code of the settlement method | label | A word, term or phrase by which a settlement method is known and distinguished from other settlement method |
Receiver: PartyRole who will receive the settlement note.
Field | Description | id | Identifier of the receiver | href | Reference of the receiver |
Issuer: PartyRole who will issue the settlement note.
Field | Description | id | Identifier of the issuer | href | Reference of the issuer |
TaxRegistration: The CSP and the partner could be registered with a tax number in a tax registration system.
Field | Description | number | Tax registration number |
SettlementNoteImage: is the image of the settlement note.
Field | Description | imageFormat | The format of the settlement note image (Csv, pdf, xls, txt…) | imageSize | The size of the settlement note image (in bytes) | imageFileName | The name of the file in which the settlement note image is saved | imageFileURL | The URL of the settlement note image |
SettlementNoteItem: concerns a product identified by its catalogue reference. It could also follow a period delimited by a start and an end date.
Field | Description | itemNumber | Unique number assigned to the settlement note item | itemId | Unique identifier of the settlement note item | itemLabel | A free description text for the settlement note item | quantity | Quantity | taxExcludedUnitPrice | Tax excluded unit price to be applied on the given quantity | taxExcludedAmount | Tax excluded amount equal to quantity * taxExcludedUnitPrice | taxIncludedAmount | All taxes included amount equal to taxExcludedAmount + taxAmount |
Period: defines the period of a recurring charge
Field | Description | startPeriod | Start date of the period | endPeriod | End date of the period |
ProductSpecification: A detailed description of a tangible or intangible object made available externally in the form of a ProductOffering to Customers or other Parties playing a PartyRole.
Field | Description | productNumber | An identification number assigned to uniquely identity the specification | Name | The name of the product specification |
UML models Image Modified Figure 6 – SettlementNoteAdvice resource model
BillingAccount lifecycle: Image Modified Figure 7 : Billing Account States State definitions:
- Defined / created: billing account has been created but no related invoice can be produced
- Active: The billing account is active and related invoices are produced
- Pending update : billing account update is planned and will be effective for next billing cycle
- Suspended : billing account has been suspended on customer request or for other reasons (bad debts, etc.)
- Pending closed: the billing account will be closed when the last invoice will have been produced
- Closed : the billing account is closed and can not be changed to another state.
|
...
Two notification event types are defined:
- BillingAccountStateChangeNotification
- SettlementNoteAdviceNotification
...
{ "eventType": "BillingAccountStateChangeNotification", "eventTime": "2014-09-27T05:46:25.0Z", "eventId": "13048231", "event": { "billingAccount": { "id": "43", Following a whole representation of the BillingAccount with all its attributes See BillingAccount Resource. } } } |
...
© TM Forum 2015. All Rights Reserved.