Page tree

 

Frameworx Specification

Prepay Balance Management REST Specification

 

 

 

 

 

 

 

TMFXYZ

Release 16.5

October 2016

 

Latest Update: Frameworx Release 16.5

Member Evaluation

Version 0.4.0

IPR Mode: RAND

 

 

NOTICE

 

Copyright © TM Forum 201 6 . All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to TM FORUM, except as needed for the purpose of developing any document or deliverable produced by a TM FORUM Collaboration Project Team (in which case the rules applicable to copyrights, as set forth in the TM FORUM IPR Policy , must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by TM FORUM or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and TM FORUM DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

 

TM FORUM invites any TM FORUM Member or any other party that believes it has patent claims that would necessarily be infringed by implementations of this TM Forum Standards Final Deliverable, to notify the TM FORUM Team Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the TM FORUM Collaboration Project Team that produced this deliverable.

 

The TM FORUM invites any party to contact the TM FORUM Team Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this TM FORUM Standards Final Deliverable by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the TM FORUM Collaboration Project Team that produced this TM FORUM Standards Final Deliverable. TM FORUM may include such claims on its website, but disclaims any obligation to do so.

 

TM FORUM takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this TM FORUM Standards Final Deliverable or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on TM FORUM's procedures with respect to rights in any document or deliverable produced by a TM FORUM Collaboration Project Team can be found on the TM FORUM website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this TM FORUM Standards Final Deliverable, can be obtained from the TM FORUM Team Administrator. TM FORUM makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

 

 

Direct inquiries to the TM Forum office:

 

240 Headquarters Plaza,

East Tower – 10 th Floor,

Morristown, NJ   07960 USA

Tel No.   +1 973 944 5100

Fax No.   +1 973 944 5110

TM Forum Web Page: www.tmforum.org

Table of Contents

NOTICE

Table of Contents

List of Tables

Introduction

SAMPLE USE CASES

Use Case 1: Customer top-ups a given amount to an account

Description

Main Actors

Use Case Steps

Example of API Usage in the Context of the Use Case

Success Outcome

Use Case 2: Customer transfers credit to another account

Description

Main Actors

Use Case Steps

Example of API Usage in the Context of the Use Case

Success Outcome

RESOURCE MODEL

BALANCE RESOURCE

Field Descriptions

BALANCETOPUP RESOURCE

Field Descriptions

BALANCETRANSFER RESOURCE

Balance Transfer Field Descriptions

BALANCEADJUSTMENT RESOURCE

Field Descriptions

API OPERATION TEMPLATES

BALANCE RESOURCE

BALANCETOPUP RESOURCE

BALANCETOPUP/STATUS RESOURCE

BALANCETRANSFER RESOURCE

BALANCETRANSFER/STATUS RESOURCE

BALANCEADJUSTMENT RESOURCE

Release History

List of Tables

 

N/A

 

Introduction

The following document is the specification of the REST API for Balance Management. It includes the model definition as well as all available operations for prepay balance management.

 

Prepaid subscribers pay fees before using services. Therefore, the subscribers must have sufficient balances. Operators can provide multiple recharge channels for subscribers. Subscribers can pass credit between different subscriptions, therefore transferring balance from one account to another.

 

Credit for a specific subscription for a type of service can be monetary or non-monetary. Allowed credit information is kept in an entity called bucket defined by an unit (currency, individual usage event, time) and an associated credited quantity of that unit.

 

The entity that owns a prepay balance is typically a subscription that is part of an account (e.g.: an msisdn subscription in a mobile operator environment) but in some environments the concepts of subscription and account are managed together as a single entity. In this API the term subscription and the reference to subscriptionId can be considered as accountId if the operation has a 1-to-1 relationship between subscriptions and accounts.

 

Prepay API manages the balance, recharge (top-up) and transfer resources

Prepay API performs the following operations

-           On a balance resource

  • Retrieve the balance information for a given subscription.

-           On a topUps collection resource

  • Retrieve information about all the top-up operations stored in the server filtered by some criteria.
  • Perform a new top up operation (recharge)

-           On a topUp individual resource

  • Retrieve detailed information about a top-up operation previously processed by the server.

-           On a topUp status resource

  • Retrieve the current and historic status information about a top-up operation previously processed by the server.
  • Modify the current status information about a top-up.

-           On a transfers collection resource

  • Perform a new transfer operation
  • Retrieve information about all the transfer operations stored in the server filtered by some criteria

-           On a transfer individual resource

  • Retrieve detailed information about a transfer operation previously processed by the server

-           On a transfer status resource

  • Retrieve the current and historic status information about a transfer operation previously processed by the server.
  • Modify the current status information about a transfer.

-           On a Balance adjustments collection resource

  • Retrieve information about all the adjustments stored in the server filtered by some criteria.
  • Perform a new adjustment operation

-           On a Balance adjustment  individual resource

  • Retrieve detailed information about a balance adjustment operation previously processed by the server.

 

SAMPLE USE CASES

This section includes a set of main use cases that can be performed with this API. Additional use cases can be generated using the operations and resources defined in this specification.

Use Case 1: Customer top-ups a given amount to an account

Description

The main purpose of this use case is the modification of the remaining balance for a given subscription, identified by a subscription Id such as an msisdn or by a customer account.

Main Actors

  • The top-up requestor
  • The affected subscription (identified by a subscription identifier such as an msisdn or customer account)

 

Use Case Steps

  1. The requestor makes use of any of the available channels in order to initiate a new top-up  operation
  2. The Operator receives a top-up creation request with indication of the following minimum information
    1. Channel used
    2. Requestor identifier
    3. Recharged subscriber identifier
    4. Type of bucket to be recharged (in case there are multiple independents balance storage, buckets or wallets, per subscriber)
    5. Amount to be recharged
  3. The operator confirms that the requestor is authorized to perform the recharge action over the specific affected subscriber. This could be based on just the requestor identifier or via a more sophisticated token-based authorization mechanisms
  4. The top-up operation is processed and the balance resource for the bucket is augmented accordingly with the amount indicated. The new amount will be valid for the time defined in the request or by a default value defined in the system
  5. The requestor is informed of the sucessful outcome

 

Example of API Usage in the Context of the Use Case

The following API interactions support the use case:

  • The requestor, via a user interface appropriate for the corresponding channel, consumes the service offered by the server over Topup resource to perform a new top-up.

 

 

Success Outcome

After completion of these API interactions, the corresponding balance resource for the impacted bucket and the affected subscription will be added the amount indicated in the request, to be used for prepay services.

 

Use Case 2: Customer transfers credit to another account

Description

The main purpose of this use case is the transfer of part of the amount from one subscription, identified by a subscription Id such as an msisdn or by a customer account, to a different subscription.

Main Actors

  • The transfer requestor
  • The transferring subscription  (identified by a subscription identifier such as an msisdn or customer account)
  • The receiving subscription (identified by a subscription identifier such as an msisdn or customer account)

 

Use Case Steps

  1. The requestor makes use of any of the available channels in order to initiate a new transfer operation
  2. The Operator receives a transfer request with indication of the following minimum information
    1. Channel used
    2. Requestor identifier
    3. Transferring subscriber identifier
    4. Receiving subscriber identifier
    5. Type of bucket to be recharged (in case there are multiple independents balance storage, buckets or wallets, per subscriber)
    6. Amount to be transferred
  3. The operator confirms that the requestor is authorized to perform the recharge action over the specific transferring subscriber. This could be based on just the requestor identifier or via a more sophisticated token-based authorization mechanisms
  4. The transfer operation is processed, then the balance resource for the receiving bucket is augmented and the balance resource for the transferring bucket is reduced accordingly with the amount indicated. The new amount will be valid for the time defined in the request or by a default value defined in the system
  5. The requestor is informed of the sucessful outcome

 

Example of API Usage in the Context of the Use Case

The following API interactions support the use case:

  • The requestor, via a user interface appropriate for the corresponding channel, consumes the service offered by the Tranfer resource to perform a new transfer operation.

 

 

Success Outcome

After completion of these API interactions, the corresponding balance resources for the impacted buckets will be modified, adding the amount indicated in the request to the receiving bucket and removing it from the transferring bucket, to be used for prepay services.

 

 

RESOURCE MODEL

BALANCE RESOURCE

The Balance resource represents and tracks the amount remained or owed in certain account which is owned by certain customer. The balance is associated to an specific subscription or account owned by a customer . This resource covers the main attributes defined in class CustomerAccountBalance defined in SID (validFor, remainedAmount).

{
"id": "SubscrAcc1",

"href":" /balancemanagement/v1/{subscriptionId}/balance ",

"totalBalance": {
"amount": 10,

"units": "EUR"
},
"bucketBalance": [{

"bucketType": "promotion sms",

"remainedAmount": {

"amount": 5,

"units": "EUR"

},

"validFor": {

"startDateTime": "10-02-2016",

"endDateTime": "10-12-2016"

},

"status": "active"

},{

"bucketType": "data",

"remainedAmount ": {

"amount": 5,

"units": "EUR"

},

"validFor": {

"startDateTime": "19-02-2016",

"endDateTime": "19-12-2016"

},

"status": "suspended"

}],

"relatedParty": [{

"id": "acc1",

"href": " http://server:port/AccountManagement/accounts/acc1 ",

"role": "customer",

"name": "John Doe"

}

}

Field Descriptions

Element

Type

Mandatory in API messages

Description

id

String

Yes in response

Unique Identifier within the server for the ticket reported.

href

anyURI

Yes in response

A resource URI pointing to the resource in the OB that stores the detailed information. This is typically the resource url to retrieve individual balance details for the specific subscription/account

totalBalance

QuantityType

Yes

Current balance for a subscription (aggregated for all prepaid balance buckets associated to the subscription)

bucketBalance

CustomerAccountBalance [1..unbounded]

Yes

Detailed information for each prepaid balance bucket associated to the subscription

relatedParty

Array of RelatedParty

No

Used to provide information about customer hierarchy for the balance (e.g.: customerId, accountId)

 

CustomerAccountBalance : Detailed information for a prepaid balancebucket

Field

Description

bucketType

Type of prepaid balance bucket (e.g.: promotion, deposit, bonus, data, voice,  …)

remainedAmount

Current value for the referenced prepaid balance

validFor

The period for which the balance is valid

status

Status for the balance (active, expired, suspended)

 

Figure 1 Balance resource model

 

BALANCETOPUP RESOURCE

The BalanceTopUp resource is a detailed description of a recharge operation requested over a subscription

{
"id": "top1",

"href":" /balancemanagement/v1/{subscriptionId}/balanceTopups/top1 ",

"type": "voice",

"description": "description",

"channel": {

"id": "channel1",

"href": " http://server:port/channels/channel1 ",

"name": " retail "

},

"place": {

"id": "desk123_abc",

"href": " http://server:port/places/desk123_abc ",

"name": " desk X in department store A "

},

"requestor": {

"id": "osidfuosid",

"href": " http://server:port/partyManagement/users/osidfuosid ",

"role": "user",

"name": "John Recharger"

},

"amount": {

"units": "EUR",

"amount": 10

},

"paymentMean": {

"id": "5",

"href": " http://server:port/accountManagement/paymentMeans/5 ",

"name": "cash"

},

"validFor": {

"startDateTime": "10-02-2016",

"endDateTime": "10-12-2016"

},

"requestedDate": "10-02-2016",

"confirmationDate": "10-02-2016",

"status": "confirmed",

"relatedParty": [{

"id": "c1",

"href": " http://server:port/partyManagement/customers/c1 ",

"role": "customer",

"name": "John Doe"

},

{

"id": "s1",

"href": " http://server:port/partyManagement/subscriptions/s1 ",

"role": "subscription"

}]

}

 

Field Descriptions

Element

Type

Mandatory in API messages

Description

id

string

Yes in response

Unique Identifier within the server for the ticket reported

href

anyURI

Yes in response

A resource URI pointing to the resource in the OB that stores the detailed information. This is typically the resource url to retrieve individual top-up operation details

type

string

Yes in request and response

A preconfigured value that describes a TopUp type which determines the prepaid balance bucket in which the top-up is done

description

string

No

Description of the recharge operation

channel

ChannelRef

(id, href, name)

Yes in request and response

Indicator for the channel used to request the top-up operation.

Structure including at least attribute “name”

place

PlaceRef

(id, href, name)

No

Indicator for the specific entity within

a channel used to request the top-up operation. This can be used to define the location where the top-up was requested (e.g.: counter X in department store A)

 

Structure including at least attribute

“name”

requestor

RelatedParty

(id, href, role, name)

No

Identifier for the user/customer/entity

that performs the top-up action when it is required to indicate additional customer hierarchy information regarding the subscription triggering the request.

 

This can be used to indicate the

identifier of an agent that performs the operation on behalf of a user via

a customer service channel

Structure including at least attributes “role” and  “name”

amount

QuantityType

Yes in request and response

Amount (can be monetary or non-monetary) to be recharged in the bucket

paymentMean

PaymentMeanRefType

(id, href, name)

No

Payment method used for the recharge operation (e.g.: cash, credit)

Structure including at least attribute

“name”

voucher

string

No

Identifier for the voucher when the topup can be perfomed by this means (referenced by a voucher based payment mean)

 

validFor

TimePeriodType

Yes in response

The period defined for the recharged amount to be part of the prepaid balance. This could be used to define expiration times to remove balance not consumed.

requestedDate

dateTime

Yes in response

Date when the top-up request was received in the server

confirmationDate

dateTime

Yes in response

Date when the top-up was confirmed in the server

status

string

Yes in response

Status of the top-up operation

Supported values are:

-           confirmed

-           cancelled

relatedParty

Array of RelatedParty

No

Used to provide information about additional parties with relationship with the operation

 

 

Figure 2 BalanceTopUp resource model

 

BALANCETRANSFER RESOURCE

The BalanceTransfer resource is a detailed description of credit transfer operation requested between two subscriptions.

{

"id": "01",
"href": " /balancemanagement/v1/{subscriptionId}/balanceTransfers/01 ",               "type": "sdfsiudfyisud",

"description": "type",

"channel": {

"id": "channel1",

"href": " http://server:port/channels/channel1 ",

"name": " retail "

},

"place": {

"id": "desk123_abc",

"href": " http://server:port/places/desk123_abc ",

"name": " desk X in department store A "

},

"requestor": {

"id": "osidfuosid",

"href": " http://server:port/partyManagement/users/osidfuosid ",

"role": "user",

"name": "John Recharger"

},

"targetSubscriptionId": "+1456789",

"receiver": {

"id": "sdfsd",

"href": "http://srvr:port/AccountManagement/acciunts/sdfsd",

"role": "billing account",

"name": "account sdfsd"

},

"amount": {

"units": "EUR",

"amount": 10

},

"transferCost": {

"units": "EUR",

"amount": 11

},

"costOwner": "originator",

"requestedDate": "10-02-2016",

"confirmationDate": "10-02-2016",

"status": "confirmed",

"relatedParty": [{

"id": "c1",

"href": " http://server:port/partyManagement/customers/c1 ",

"role": "customer",

"name": "John Doe"

},

{

"id": "s1",

"href": " http://server:port/partyManagement/subscriptions/s1 ",

"role": "subscription"

}]

}

Balance Transfer Field Descriptions

Element

Type

Mandatory

Description

id

string

Yes in response

Unique Identifier within the server for the ticket reported.

href

anyURI

Yes in response

A resource URI pointing to the resource in the OB that stores the detailed information. This is typically the resource url to retrieve individual transfer operation details

type

string

Yes in request and response

A preconfigured value that describes a Transfer type which determines the prepaid balance bucket in which the transfer  is done

description

string

No

Description of the transfer operation

channel

ChannelRef

(id, href, name)

Yes in request and response

Indicator for the channel used to request the transfer operation.

Structure including at least attribute “name”

place

PlaceRef

(id, href, name)

No

Indicator for the specific entity within a channel used to request the transfer operation

Structure including at least attribute “name”

requestor

RelatedParty

(id, href, role, name)

No

Identifier for the user/customer/entity that performs the transfer action when it is required to indicate additional customer hierarchy information regarding the subscription triggering the balance transfer .

This can be used to indicate the identifier of an agent that performs the operation on behalf of a user via a customer service channel

Structure including at least attributes “role” and  “name”

targetSubscriptionId

string

Yes in request and response

Identifier for the entity that receives the transfer (i.e.: receiving subscriptionId)

receiver

RelatedParty

(id, href, role, name)

No

Identifier for the user/customer/entity that receives the transfer action when it is required to indicate additional customer hierarchy information regarding the subscription receiving the balance transfer .

Structure including at least attributes “role” and  “name”

amount

QuantityType

Yes in request and response

Amount (can be monetary or non-monetary) to be transferred

transferCost

QuantityType

No

Associated cost to be charged for the transfer operation (can be monetary or non-monetary)

costOwner

string

No

Indicates the entity responsible to assume the cost of the transfer operation

Supported values are:

-           originator

-           receiver

requestedDate

dateTime

Yes in response

Date when the transfer request was received in the server

confirmationDate

dateTime

Yes in response

Date when the transfer was confirmed in the server

status

string

Yes in response

Status of the top-up.

Supported values are:

-           confirmed

-           cancelled

 

relatedParty

Array of RelatedParty

No

Used to provide information about additional parties with relationship with the operation

 

Figure 3 BalanceTransfer resource model

 

BALANCEADJUSTMENT RESOURCE

The BalanceAdjustment resource is a detailed description of credit adjustment operation performed on a given subscriptions.

{
"id": "A1",

"href":"/balancemanagement/v1/{subscriptionId}/balanceAdjustments/A1",

"type": "voice",

"description": "description text",

"reason": "text for reason of adjustment",

"requestor": {

"id": "AGENT1",

"href": "http://server:port/partyManagement/agents/AGENT1",

"role": "agent",

"name": "Agent Adjuster "

},

"amount": {

"units": "EUR",

"amount": 10

},

"validFor": {

"startDateTime": "10-02-2016",

"endDateTime": "10-12-2016"

},

"requestedDate": "10-02-2016"

}

 

Field Descriptions

Element

Type

Mandatory in API messages

Description

id

string

Yes in response

Unique Identifier within the server for the ticket reported

href

anyURI

Yes in response

A resource URI pointing to the resource in the OB that stores the detailed information. This is typically the resource url to retrieve individual top-up operation details

type

string

Yes in request and response

A preconfigured value that describes a TopUp type which determines the prepaid balance bucket in which the top-up is done

description

string

No

Description of the recharge operation

reason

string

Yes in request and response

Text describing the reason for the adjustment

requestor

RelatedParty

(id, href, role, name)

No

Identifier for the user/customer/entity

that performs the adjustment action when it is required to indicate additional customer hierarchy information regarding the subscription triggering the adjustment.

 

This can be used to indicate the

identifier of an agent that performs the operation on behalf of a user via

a customer service channel

Structure including at least attributes “role” and  “name”

amount

QuantityType

Yes in request and response

Amount (can be monetary or non-monetary) to be recharged in the bucket. It could refer to positive (increment) or negative (decrement) values

validFor

TimePeriodType

No

 

The period defined for the adjusted amount to be part of the prepaid balance. This could be used to define expiration times to remove balance not consumed.

requestedDate

dateTime

Yes in response

Date when the top-up request was received in the server

 

Figure 4 BalanceAdjustment resource model

API OPERATION TEMPLATES

For every single of operation on the entities use the following templates and provide sample REST requests and responses.

Remember that the following Uniform Contract rules must be used:

Operation on Entities

Uniform API Operation

Description

Query Entities

GET Resource

GET must be used to retrieve a representation of a resource.

 

Create Entity

POST Resource

POST must be used to create a new resource

Partial Update of an Entity

PATCH Resource

PATCH must be used to partially update a resource

For reconciliation processes

Complete Update of an Entity

PUT Resource

PUT must be used to completely update a resource identified by its resource URI

Remove an Entity

DELETE Resource

DELETE must be used to remove a resource

 

Filtering and attribute selection rules are described in the TMF REST Design Guidelines.

BALANCE RESOURCE

GET /balancemanagement/v1/{subscriptionId}/balance

Description:

The Application invokes this operation to retrieve balance information (total and split per prepaid balance type) stored in the server for an specific subscription.

 

The subscription refers to the actual customer asset where the top-up operation applies, this could be a mobile number (i.e.: msisdn), or a subscription identifier to refer to an individual asset (e.g.: license id for a TV service).

Behavior:

Status Code

Description

200

Balance information was returned successfully

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

The example below includes the attributes within the Balance resource model that are mandatory to be included in the query response

REQUEST

GET https://{serverRoot}/balancemanagement/v1/123456/balance 

Content-type: application/json

RESPONSE

200

Content-Type: application/json

 

{

"id": "SubscrAcc123456",

"href":" /balancemanagement/v1/123456/balance ",

"totalBalance": {

"units": "EUR",

"amount": 10

},

"bucketBalance": [{

"bucketType": "promotion voice",

"remainedAmount": {

"units": "EUR",

"amount": 5

},

"validFor": {

"startDateTime": "10-02-2016",

"endDateTime": "10-12-2016"

},

"status": "active"

},{

"bucketType": "voice",

"remainedAmount": {

"units": "EUR",

"amount": 5

},

"validFor": {

"startDateTime": "19-02-2016",

"endDateTime": "19-12-2016"

},

"status": "suspended"

}]

}

 

The example below shows the case where the balance for an specific credit record (bucket or wallet) is requested

REQUEST

GET https://{serverRoot}/balancemanagement/v1/123456/balance?bucketType=voice 

Content-type: application/json

RESPONSE

200

Content-Type: application/json

 

{

"id": "SubscrAcc123456",

"href":" /balancemanagement/v1/123456/balance ",

"totalBalance": {

"units": "EUR",

"amount": 10

},

"bucketBalance": [{

"bucketType": "voice",

"remainedAmount": {

"units": "EUR",

"amount": 5

},

"validFor": {

"startDateTime": "19-02-2016",

"endDateTime": "19-12-2016"

},

"status": "active"

}]

}

 

The example below shows the case where only the total balance for an account is requested

REQUEST

GET https://{serverRoot}/balancemanagement/v1/123456/balance?fields=totalBalance

Content-type: application/json

RESPONSE

200

Content-Type: application/json

 

{

"id": "SubscrAcc123456",

"href":" /balancemanagement/v1/123456/balance ",

"totalBalance": {

"units": "EUR",

"amount": 10

}

}

 

BALANCETOPUP RESOURCE

POST /balancemanagement/v1/{subscriptionId}/ balanceT opups

Description:

The Application invokes this operation to request a new top-up operation for a given subscription.

 

The subscription refers to the actual customer asset where the top-up operation applies, this could be a mobile number (i.e.: msisdn), or a subscription identifier to refer to an individual asset (e.g.: license id for a TV service).

 

Behavior:

Status Code

Description

201

Successful top-up operation (resource created)

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

The example below includes the attributes within the TopUp Operation entity resource model that are mandatory to be included in the request when creating a new resource in the server

REQUEST

POST https://{serverRoot}/balanceManagement/v1/123456/balanceTopups

Content-type: application/json

 

{

"type": "buckettype",

"channel": {

"name": " retail "

},

"amount": {

"units": "EUR",

"amount": 10

}

}

RESPONSE

201

Content-Type: application/json

Location: https://{serverRoot}/balanceManagement/v1/123456/topUps/TUPxxx01

 

Response is not required to include a BODY with the contents of the Balance resource created, but if included it must be filled with at least the mandatory parameters.

 

GET /balancemanagement/v1/{subscriptionId}/ balanceT opUps

Description:

The Application invokes this operation to retrieve the list of top-up operations processed for a given subscription, filtered by given criteria. The response includes the details of all top-ups and/or cancellations, as well as status changes associated to the operations reported.

Behavior:

Status Code

Description

200

TopUp information was returned successfully

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

The example below includes the attributes within the TopUp Operation entity resource model that may be included in the query response

REQUEST

GET https://{serverRoot}/balanceManagement/v1/123456/ balance Topups 

Content-type: application/json

RESPONSE

200

Content-Type: application/json

 

[{

"id": "TUPxxx01",

"href": " /balancemanagement/v1/123456/balanceTopups/TUPxxx01 ", "type": "voice",

"description": "description",

"channel": {

"id": "channel1",

"href": " http://server:port/channels/channel1 ",

"name": " retail "

},

"place": {

"id": "desk123_abc",

"href": " http://server:port/places/desk123_abc ",

"name": " desk X in department store A "

},

"requestor": {

"id": "osidfuod",

"href": " http://server:port/partyManagement/users/osidfuod ",

"role": "user",

"name": "John Recharger"

},

"amount": {

"units": "EUR",

"amount": 10

},

"paymentMean": {

"id": "5",

"href": " http://srvr:port/accountManagement/paymentMeans/5 ",

"name": "cash"

},

"validFor": {

"startDateTime": "10-02-2016",

"endDateTime": "10-12-2016"

},

"requestedDate": "10-02-2016",

"confirmationDate": "10-02-2016",

"status": "confirmed"

},

{

"id": "2ab",

"href": " srv:port/balancemanagement/v1/123456/balanceTopups/2ab ", "type": "voice",

"description": "description",

"channel": {

"id": "channel1",

"href": " http://server:port/channels/channel1 ",

"name": " bank teller "

},

"place": {

"id": "bankteller123_abc",

"href": " http://server:port/places/desk123_abc ",

"name": " desk X in department store A "

},

"amount": {

"units": "EUR",

"amount": 10

},

"paymentMean": {

"id": "5",

"href": " http://srvr:port/accountManagement/paymentMeans/5 ",

"name": "cash"

},

"validFor": {

"startDateTime": "10-03-2016",

"endDateTime": "10-12-2016"

},

"requestedDate": "10-03-2016",

"confirmationDate": "10-03-2016",

"status": "confirmed"

}]

 

The example below shows the case where the top-up operation involves an specific channel subscription

REQUEST

GET https://{serverRoot}/balanceManagement/v1/123456/ balanceT opups?channel=CHNL01 

Content-type: application/json

RESPONSE

200

Content-Type: application/json

 

[{

"id": "xxx001",

"href": " srv:port/balancemanagement/v1/123456/balanceTopups/xxx001 ",               "type": "sms",

"description": "description",

"channel": {

"id": "channel1",

"href": " http://server:port/channels/channel1 ",

"name": " CHNL01 "

},

"amount": {

"units": "EUR",

"amount": 10

},

"paymentMean": {

"id": "5",

"href": " http://srvr:port/accountManagement/paymentMeans/5 ",

"name": "cash"

},

"validFor": {

"startDateTime": "10-02-2016",

"endDateTime": "10-12-2016"

},

"requestedDate": "10-02-2016",

"confirmationDate": "10-02-2016",

"status": "confirmed",

},

{

...

}]

 

GET /balancemanagement/v1/{subscriptionId}/ balanceT opups/{topUpId}

Description:

The Application invokes this operation to retrieve detailed information about a single top-up operation previously processed by the server.

Behavior:

Status Code

Description

200

Successful top-up update operation (resource modified)

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

The example below includes the attributes within the TopUp Operation entity resource model that may be included in the query response

REQUEST

GET https://{serverRoot}/balanceManagement/v1/123456/ balanceT opups/TOPxxx001 

Content-type: application/json

RESPONSE

200

Content-Type: application/json

 

{

"id": "TOPxxx001",

"href": " /balancemanagement/v1/123456/balanceTopups/TOPxxx001 ", "type": "voice",

"channel": {

"id": "channel1",

"href": " http://server:port/channels/channel1 ",

"name": " CHNL01 "

},

"amount": {

"units": "EUR",

"amount": 10

},

"validFor": {

"startDateTime": "10-02-2016",

"endDateTime": "10-12-2016"

},

"requestedDate": "10-02-2016",

"confirmationDate": "10-02-2016",

"status": "confirmed"

}

 

PATCH /balancemanagement/v1/{subscriptionId}/balanceTopups/{topUpId}

This operation is optional to be supported in this API

Description:

The Application invokes this operation to partially update the information about a single top-up operation previously processed by the server.

 

The only element that are expected to be modified in the TopUp Operation resource are the status in order to allow cancellation of a previously processed top-up operation or the validity to modify the expiration type of the credit given to a subscription.

Behavior:

To Be Defined.

PUT /balancemanagement/v1/{subscriptionId}/balanceTopups/{topUpId}

This operation is optional to be supported in this API

Description:

The Application invokes this operation to completely update the information about a single top-up operation previously processed by the server.

 

Notice that the PUT method is intended to modify completely the resource impacted, meaning that optional values that are not included in the request may be erased in the server after updating, and will not keep the previous value stored. Behaviour of teh server on optional values not included is undefined.

Behavior:

To Be Defined.

 

BALANCETOPUP/STATUS RESOURCE

PUT /balancemanagement/v1/{subscriptionId}/balanceTopups/{topUpId}/status

This operation is optional to be supported in this API

Description:

The Application invokes this operation to modify the status a top-up operation previously processed by the server. This could be used to cancel an existing top up operation.

 

Behavior:

Status Code

Description

204

Successful status modification

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

The example below includes the attributes within the TopUp Operation entity resource model that are required to perfomr a status modification

REQUEST

PUT https://{serverRoot}/balanceManagement/v1/123456/balanceTopups /TUPxxx01/status

Content-type: application/json

 

{

"status": "cancelled"

}

RESPONSE

204

Content-Type: application/json

 

BALANCETRANSFER RESOURCE

POST /balancemanagement/v1/{subscriptionId}/balanceTransfers

Description:

The Application invokes this operation to request a new transfer operation for a given subscription.

 

The subscription refers to the actual customer asset where the transfer operation applies, this could be a mobile number (i.e.: msisdn), or a subscription identifier to refer to an individual asset (e.g.: license id for a TV service).

 

Behavior:

Status Code

Description

201

Transfer operation successful (resource created)

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

The example below includes the attributes within the Transfer Operation entity resource model that are mandatory to be included in the request when creating a new resource in the server

REQUEST

POST https://{serverRoot}/balancemanagement/v1/123456/balanceTransfers 

Content-type: application/json

{

"type": "data",

"channel": {

"id": "channel1",

"href": " http://server:port/channels/channel1 ",

"name": " retail "

},

"targetSubscriptionId": "+1456789",

"amount": {

"units": "EUR",

"amount": 10

}

}

RESPONSE

201

Content-Type: application/json

Location: https://{serverRoot}/balancemanagement/v1/123456/balanceTransfers/TRNSF01

 

Response is not required to include a BODY with the contents of the Balance resource created, but if included it must be filled with at least the mandatory parameters.

 

 

GET /balancemanagement/v1/{subscriptionId}/balanceTransfers

Description:

The Application invokes this operation to retrieve the list of transfer operations processed for a given subscription, filtered by given criteria. The response includes the details of all top-ups and/or cancellations, as well as status changes associated to the operations reported.

Behavior:

Status Code

Description

200

Transfer information was returned successfully

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

The example below includes the attributes within the Transfer Operation entity resource model that may be included in the query response

REQUEST

GET https://{serverRoot}/ balancemanagement /v1/123456/balanceTransfers 

Content-type: application/json

RESPONSE

200

Content-Type: application/json

 

[{

"id": "TRNSF1",
"href": " balancemanagement/v1/123456/balanceTransfers/TRNSF1 " ,

"type": "voice",

"channel": {

"id": "channel1",

"href": " http://server:port/channels/channel1 ",

"name": " retail "

},

"targetSubscriptionId": "+1456789",

"amount": {

"units": "EUR",

"amount": 10

},

"requestedDate": "10-02-2016",

"confirmationDate": "10-02-2016",

"status": "confirmed"

},

{

...

}]

 

The example below shows the case where the transfer operation involves an specific receiving subscription

REQUEST

GET https://{serverRoot}/ balancemanagement /v1/123456/balanceTransfers?receiver=RCVR01 

Content-type: application/json

RESPONSE

200

Content-Type: application/json

 

[{

"id": "TRNSF1",
"href": "/ balancemanagement/v1/123456/balanceTransfers/TRNSF1 " ,

"type": "data",

"channel": {

"id": "channel1",

"href": " http://server:port/channels/channel1 ",

"name": " retail "

},

"targetSubscriptionId": "+1456789",

"amount": {

"units": "EUR",

"amount": 10

},

"requestedDate": "10-02-2016",

"confirmationDate": "10-02-2016",

"status": "confirmed"

},

{

...

}]

 

GET /balancemanagement/v1/{subscriptionId}/balanceTransfers/{transferId}

Description:

The Application invokes this operation to retrieve detailed information about a single transfer operation previously processed by the server..

Behavior:

Status Code

Description

200

Transfer information was returned successfully

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

The example below includes the attributes within the Transfer Operation entity resource model that may be included in the query response

REQUEST

GET https://{serverRoot}/ balancemanagement /v1/123456/transfers/TRNSF01

Content-type: application/json

RESPONSE

200

Content-Type: application/json

 

{

"id": "TRNSFxxx01",
"href": " balancemanagement/v1/123456/balanceTransfers/TRNSF01 " ,

"type": "sms",

"channel": {

"id": "channel1",

"href": " http://server:port/channels/channel1 ",

"name": " retail "

},

"targetSubscriptionId": "+1456789",

"amount": {

"units": "EUR",

"amount": 10

},

"requestedDate": "10-02-2016",

"confirmationDate": "10-02-2016",

"status": "confirmed"

}

 

 

PATCH /balancemanagement/v1/{subscriptionId}/balanceTransfers/{transferId}

This operation is optional to be supported in this API

Description:

The Application invokes this operation to partially update the information about a single transfer operation previously processed by the server.

 

The only element that is expected to be modified in the Transfer resource is the status in order to allow cancellatiopn of a previously processed transfer operation

Behavior:

To Be Defined.

PUT /balancemanagement/v1/{subscriptionId}/balanceTransfers/{transferId}

This operation is optional to be supported in this API

Description:

The Application invokes this operation to completely update the information about a single balance transfer operation previously processed by the server.

 

Notice that the PUT method is intended to modify completely the resource impacted, meaning that optional values that are not included in the request may be erased in the server after updating, and will not keep the previous value stored. Behaviour of teh server on optional values not included is undefined.

Behavior:

To Be Defined.

 

BALANCETRANSFER/STATUS RESOURCE

PUT /balancemanagement/v1/{subscriptionId}/balanceTransfers/{transferId}/status

This operation is optional to be supported in this API

Description:

The Application invokes this operation to modify the status of a balance transfer operation previously processed by the server. This could be used to cancel an existing transfer operation.

Behavior:

Status Code

Description

204

Successful status modification

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

The example below includes the attributes within the Transfer Operation entity resource model that are mandatory to perform a status modifcation

REQUEST

PUT https://{serverRoot}/balanceManagement/v1/123456/balanceTransfers/ TRNSF01 /status

Content-type: application/json

 

{

"status": "cancelled"

}

RESPONSE

204

Content-Type: application/json

 

BALANCEADJUSTMENT RESOURCE

POST /balancemanagement/v1/{subscriptionId}/balanceAdjustments

Description:

The Application invokes this operation to perform a balance adjustment for a given subscription.

 

The subscription refers to the actual customer asset where the adjustment operation applies, this could be a mobile number (i.e.: msisdn), or a subscription identifier to refer to an individual asset (e.g.: license id for a TV service).

 

Behavior:

Status Code

Description

201

Successful adjustment operation (resource created)

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

The example below includes the attributes within the Adjustment Operation entity resource model that are mandatory to be included in the request when the adjustment is to add an amount to any of the buckets of the subscription

REQUEST

POST https://{serverRoot}/balanceManagement/v1/123456/balanceAdjustments

Content-type: application/json

 

{

"type": "buckettype",

"reason": "this is why the adjustment was performed",

"amount": {

"units": "EUR",

"amount": 10.5

}

}

RESPONSE

201

Content-Type: application/json

Location: https://{serverRoot}/balanceManagement/v1/123456/balanceAdjustments/ADJ01

 

Response is not required to include a BODY with the contents of the Balance resource created, but if included it must be filled with at least the mandatory parameters.

 

The example below includes the attributes within the Adjustment Operation entity resource model that are mandatory to be included in the request when the adjustment is to remove some amount to any of the buckets of the subscription

REQUEST

POST https://{serverRoot}/balanceManagement/v1/123456/balanceAdjustments

Content-type: application/json

 

{

"type": "buckettype",

"reason": "this is why the adjustment was performed",

"amount": {

"units": "EUR",

"amount": -3.5

}

}

RESPONSE

201

Content-Type: application/json

Location: https://{serverRoot}/balanceManagement/v1/123456/balanceAdjustments/TUP01

 

Response is not required to include a BODY with the contents of the Balance resource created, but if included it must be filled with at least the mandatory parameters.

 

 

GET /balancemanagement/v1/{subscriptionId}/balanceAdjustments

Description:

The Application invokes this operation to retrieve the list of adjustment operations processed for a given subscription, filtered by given criteria.

Behavior:

Status Code

Description

200

TopUp information was returned successfully

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

The example below includes the attributes within the TopUp Operation entity resource model that may be included in the query response

REQUEST

GET https://{serverRoot}/balanceManagement/v1/123456/balanceAdjustments 

Content-type: application/json

RESPONSE

200

Content-Type: application/json

 

[{

"id": "ADJ01",

"href": " /balancemanagement/v1/123456/balanceAdjustmentss/ADJ01 ", "type": "voice",

"reason": "this is why the adjustment was performed",

"description": "description",

"amount": {

"units": "EUR",

"amount": 10

},

"requestedDate": "10-02-2016"

},

}]

 

GET /balancemanagement/v1/{subscriptionId}/balanceAdjustments/{adjustmentId}

Description:

The Application invokes this operation to retrieve detailed information about a single top-up operation previously processed by the server.

Behavior:

Status Code

Description

200

Successful top-up update operation (resource modified)

400

Request Error

500

The server encountered an unexpected condition which prevented it from fulfilling the request

Other

The server may use other HTTP error status codes to reflect the error, the client must be processed in accordance with the error messages in other HTTP specification.

 

The example below includes the attributes within the TopUp Operation entity resource model that are may be included in the query response

REQUEST

GET https://{serverRoot}/balanceManagement/v1/123456/balanceAdjustments/ADJ001 

Content-type: application/json

RESPONSE

200

Content-Type: application/json

 

{

"id": "ADJ001",

"href": " /balancemanagement/v1/123456/balanceAdjustments/ADJ001 ", "type": "voice",

"reason": "this is why the adjustment was performed",

"description": "description",

"amount": {

"units": "EUR",

"amount": 10

},

"requestedDate": "10-02-2016"

}

 


Release History

Release Number

Date

Release led by:

Description

Release 0.1

16/0 9 /2016

 

First Release of Draft Version of the Document.

Release 0.2

10/11/2016

 

Updated after comments from TMForum team review.

Release 0.3

11/11/2016

 

Updated to include “Balance Adjustment” operation.

Release 0.4

16/11/2016

 

Updated after comments from TMForum team review (URL names changed in operation example templates) and additional attributes added to balance resource (status in bucket and relatedParty to link subscription to account).