swagger: '2.0'
info:
description: This is a sample representation of the Prepay Balance Management TMForum API. It is important to bear in mind that swagger 2.0 does not properly support polymorphism, so the link between the payment method details and its data types should be looked up in the API specification pdf file.
title: Prepay Balance Management
version: 2.0.4
host: "api.mtn.com"
basePath: /tmf-api/prepaybalancemanagement/v1/
schemes:
- https
consumes:
- application/json
produces:
- application/json
securityDefinitions:
ApiKeyAuth:
type: "apiKey"
name: "X-API-Key"
in: "header"
OAuth2:
type: oauth2
flow: application
tokenUrl: https://api.mtn.com/v1/oauth/access_token
security:
- ApiKeyAuth: []
- OAuth2: []
paths:
/bucket:
get:
operationId: retrieveBuckets
produces:
- application/json
parameters:
- name: relatedParty.id
required: true
in: query
description: customer identification ID eg MSISDN
type: string
responses:
'200':
description: Balance information was returned successfully
schema:
type: array
items:
$ref: '#/definitions/BucketBalance'
headers:
X-Total-Count:
description: Total results
type: integer
'400':
description: Request Error
'401':
description: Unauthorized
'403':
description: Forbidden
'405':
description: Method not Allowed
'500':
description: The server encountered an unexpected condition which prevented it from fulfilling the request
summary: Retrieve balance information stored in the server that can be filtered for specific criteria.
tags:
- Balance Buckets Methods
/balanceTransfer:
post:
operationId: createTransfer
produces:
- application/json
parameters:
- name: transactionId
type: string
in: header
required: true
description: unique identifier f the transaction generated by Apigee
- name: UsageType
in: query
description: type of the balance to be transferred
required: true
type: string
enum:
- Main balance
- Bonus
- SMS
- Data
- Voice
- name: TransferBody
in: body
description: The Transfer to be modify.
schema:
$ref: '#/definitions/BalanceTransferBody'
responses:
'201':
description: Transfer operation successful (resource created
schema:
$ref: '#/definitions/TransferBalance'
summary: request a new transfer operation for a given product (or commercial id reference to a product instance consuming the credit held in a bucket for a specific service).
tags:
- BalanceTransfer
definitions:
BucketBalance:
description: Represents and tracks the amount remained or owed for a certain type of service by certain customer
properties:
id:
type: string
description: Unique Identifier within the server for the bucket
href:
type: string
description: A resource URI pointing to the resource in the OB that stores the detailed information for the bucket
name:
type: string
description: Friendly name to identify the bucket
description:
type: string
description: Text describing the contents of the balance managed by the bucket
bucketType:
type: string
description: 'Type of prepay balance bucket (e.g.: promotion, deposit, bonus, data, voice, or any other service type)'
remainedAmount:
$ref: '#/definitions/QuantityType'
description: Amount remained in the bucket
reservedAmount:
$ref: '#/definitions/QuantityType'
description: Indicate the reserved amount on the bucket
validFor:
$ref: '#/definitions/TimePeriodType'
description: The period for which the balance in the bucket is valid
status:
type: string
description: Status for the balance (active, expired, suspended)
product:
type: array
items:
$ref: '#/definitions/ProductRefType'
description: A reference to the product whose consumption is managed by the bucket. This is an array to allow scenarios where a given bucket is shared between different products.
partyAccount:
$ref: '#/definitions/PartyAccountRefType'
description: A reference to the account that owns the bucket
realizingResource:
type: array
items:
$ref: '#/definitions/RealizingResourceRefType'
description: A reference to the resource that realizes a product. This is an array to allow scenarios where a given bucket is shared between different resources.
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedPartyRefType'
description: 'Used to provide information about any other entity with relation to the balance, for instance to define customer hierarchy for the balance (e.g.: customerId, userId, )'
required:
- id
- href
- bucketType
- validFor
- status
- product
AccumulatedBalance:
description: Represents and tracks the aggregated amount remained or owed in certain account which is owned by certain customer for a set of buckets.
properties:
name:
type: string
description: Friendly name to identify the aggregated balance
description:
type: string
description: Text describing the contents of the aggregated balance
totalBalance:
$ref: '#/definitions/QuantityType'
description: Aggregated for a set of prepay balance buckets associated to the product
bucket:
type: array
items:
$ref: '#/definitions/BucketBalanceRefType'
description: A reference to the buckets involved in the aggregation
product:
type: array
items:
$ref: '#/definitions/ProductRefType'
description: A reference to the product whose consumption is managed by the bucket . This is an array to allow scenarios where a buckets are shared between different products
partyAccount:
type: array
items:
$ref: '#/definitions/PartyAccountRefType'
description: A reference to the account that owns the buckets aggregated
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedPartyRefType'
description: 'Used to provide information about any other entity with relation to the balance, for instance to define customer hierarchy for the balance (e.g.: customerId, userId, )'
required:
- name
- totalBalance
- bucket
- product
BalanceTopupBody:
properties:
type:
type: string
description: A preconfigured value that describes a TopUp type which determines the prepay balance bucket in which the top-up is done (national-voice, roaming-voice, promotional-voice, data, ....)
channel:
$ref: '#/definitions/ChannelRefType'
description: Indicator for the channel used to request the top-up operation. Structure including at least attribute �name�
amount:
$ref: '#/definitions/QuantityType'
description: Amount (can be monetary or non-monetary) to be recharged in the bucket
product:
$ref: '#/definitions/ProductRefType'
description: A reference to the product related to the bucket that is impacted by the balance related operation
required:
- type
- channel
- amount
BalanceTopupRequest:
allOf:
- $ref: '#/definitions/BalanceTopupBody'
description: 'Represents a detailed description of a recharge operation requested over a bucket (defined by a specific product or reference to a product (i.e.: a commercial id such as an msisidn) and a service type)'
properties:
id:
type: string
description: Unique Identifier within the server for the recharge operation request
href:
type: string
description: 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
description:
type: string
description: Description of the recharge operation
requestor:
$ref: '#/definitions/RelatedPartyRefType'
description: Identifier for the user/customer/entity that performs the top-up action. 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�.
isAutoTopup:
type: boolean
description: Indicates if the topup requested is an autotopup (to be processed periodically)
recurringPeriod:
type: string
description: For autotopup indicates the periodicity for the recharge operation (monthly, weekly, )
nrOfPeriods:
type: integer
description: For autotopup indicates the number of occurrences of the period the recharge operation must be executed. If not included then no limit is set to stop the executionof the topup every period
paymentMethod:
$ref: '#/definitions/PaymentMethodRefOrValueType'
description: 'Payment method used for the recharge operation (e.g.: cash, credit card, �). Structure including at least attribute �name�. Notice that the use of a voucher can be managed as a specific methodtype, where he voucher code can be passed as value.'
voucher:
type: string
description: Identifier for the voucher when the topup can be perfomed by this means (referenced by a voucher based payment mean). This attribute is left in this release to keep compatibility with previous version and for implementations that do not relay on paymentMethods. A voucher can be managed as a specific methodtype, where he voucher code can be passed as value.
validFor:
$ref: '#/definitions/TimePeriodType'
description: The period defined for the recharged amount to be part of the prepay balance. This could be used to define expiration times to remove balance not consumed.
requestedDate:
type: string
description: Date when the top-up request was received in the server
confirmationDate:
type: string
description: Date when the top-up was confirmed in the server
status:
type: string
enum:
- confirmed
- cancelled
- in progress
description: 'Status of the top-up operation Supported values are: - confirmed - cancelled - in progress'
bucket:
$ref: '#/definitions/BucketBalanceRefType'
description: A reference to the bucket impacted by the request. This is used in scenarios where the requestor knows beforehand the bucket that is going to be impacted instead of just referring to the commercial identifier of the impacted product and the type of bucket created under that product
partyAccount:
$ref: '#/definitions/PartyAccountRefType'
description: A reference to the account that owns the bucket impacted by the balance related operation
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedPartyRefType'
description: Used to provide information about any other entity with relation to the operation
required:
- id
- href
- validFor
- requestedDate
- confirmationDate
- status
BalanceTransferBody:
properties:
direction:
type: string
description: 0-from outside system to OCS,1- from OCS to external system, 3- from OCS to OCS
channel:
$ref: '#/definitions/ChannelRefType'
description: Indicator for the channel used to request the top-up operation. Structure including at least attribute �name�
amount:
$ref: '#/definitions/QuantityType'
description: Amount (can be monetary or non-monetary) to be transferred
partyAccount:
$ref: '#/definitions/RelatedParty'
description: A reference to the product related to the bucket that is impacted by the balance related operation
receiver:
$ref: '#/definitions/RelatedParty'
description: A reference to the product related
transferCost:
$ref: '#/definitions/Money'
description: A reference to the product related
required:
- channel
- amount
- type
BalanceTransferRequest:
allOf:
- $ref: '#/definitions/BalanceTransferBody'
description: The BalanceTransfer resource is a detailed description of credit transfer operation requested between two buckets (reference to products owned by customers and consuming credit when using a service).
properties:
id:
type: string
description: Unique Identifier within the server for the balance transfer operation request.
href:
type: string
description: 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
description:
type: string
description: Description of the transfer operation
reason:
type: string
description: Text describing the reason for the adjustment
requestor:
$ref: '#/definitions/RelatedPartyRefType'
description: Identifier for the user/customer/entity that performs the top-up action. 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�.
targetType:
type: string
description: Intended for scenarios where the transfer is done from one bucket type to another (from voice to data). A preconfigured value that describes a Transfer type which determines the prepay balance bucket in which the transfer is done
receiver:
$ref: '#/definitions/RelatedPartyRefType'
description: Identifier for the user/customer/entity that receives the transfer action when it is required to indicate additional customer hierarchy information regarding the entity receiving the balance transfer
transferCost:
$ref: '#/definitions/QuantityType'
description: Associated cost to be charged for the transfer operation (can be monetary or non-monetary)
costOwner:
type: string
enum:
- originator
- receiver
description: Indicates the entity responsible to assume the cost of the transfer operation
requestedDate:
type: string
description: Date when the transfer request was received in the server
confirmationDate:
type: string
description: Date when the transfer was confirmed in the server
status:
type: string
enum:
- confirmed
- cancelled
- in progress
description: Status of the top-up.
bucket:
$ref: '#/definitions/BucketBalanceRefType'
description: A reference to the bucket impacted by the request. This is used in scenarios where the requestor knows beforehand the bucket that is going to be impacted instead of just referring to the commercial identifier of the impacted product and the type of bucket created under that product
partyAccount:
$ref: '#/definitions/PartyAccountRefType'
description: A reference to the account that owns the bucket impacted by the balance related operation
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedPartyRefType'
description: Used to provide information about any other entity with relation to the operation
required:
- id
- href
- reason
- requestedDate
- confirmationDate
- product
TransferBalance:
type: object
description: >-
The TransferBalance resource is a detailed description of credit transfer operation requested between two buckets (reference to products owned by customers and consuming credit when using a service).
required:
- referenceNumber
- channel
- status
properties:
id:
type: string
description: Unique Identifier for the resource
type:
type: string
description: Type of the identifier
referenceNumber:
type: string
description: Reference number generated by provider system
externalTransactionId:
type: string
description: Transaction id generated by MADapi.
direction:
type: string
description: "A direction"
example: "inbound"
confirmationDate:
type: string
format: date-time
description: Date when the deduction was confirmed in the server
status:
type: string
description: Status of the operation
description:
type: string
description: Description of the recharge operation
reason:
type: string
description: Text describing the reason for the action/task
href:
type: string
description: An href
requestedDate:
type: string
format: date-time
description: Date when the deduction request was received in the server
amount:
$ref: '#/definitions/Money'
description: Indicate the amount on the bucket
channel:
$ref: '#/definitions/ChannelRef'
description: >-
Indicator for the channel used to request the transfer operation.
partyAccount:
$ref: '#/definitions/RelatedParty'
description: >-
Reference to the sender used to request the transfer operation.
Structure including at least attribute name
contact:
type: array
items:
$ref: "#/definitions/ContactItem"
product:
type: array
items:
$ref: '#/definitions/ProductRef'
receiver:
$ref: '#/definitions/RelatedParty'
description: >-
Identifier for the user/customer/entity that receives the transfer
when it is required to indicate additional customer hierarchy
information regarding the entity receiving the balance transfer
Structure including at least attributes “role” and “name”
receiverLogicalResource:
$ref: '#/definitions/LogicalResourceRef'
description: A reference to the logical resource that can be used to identify the bucket balance for example where product ids are not unique.
receiverBucket:
$ref: '#/definitions/BucketRef'
logicalResource:
type: array
items:
$ref: '#/definitions/LogicalResourceRef'
transferFee:
$ref: '#/definitions/Money'
description: >-
Associated cost to be charged for the transfer operation (can be
monetary or non-monetary)
validFor:
$ref: '#/definitions/TimePeriod'
description: The period for which the balance in the bucket is valid
'@baseType':
example: ResourceSpecification
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
example: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
example: LogicalResourceSpecification
type: string
description: When sub-classing, this defines the sub-class Extensible name
recurring:
type: boolean
description: "Whether the activity should be a recurring event"
example: true
recurringCount:
type: number
description: "Number of times the recurring event should happen"
example: 2
ContactItem:
type: object
properties:
contactType:
type: string
description: The contact type
example: "EmailAddress, PhoneNumber etc"
contactMedium:
type: array
items:
$ref: "#/definitions/ContactMedium"
ContactMedium:
type: object
properties:
preferred:
type: boolean
example: false
description: "Whether this should be the preferred contact or not"
isEnabled:
type: boolean
example: false
mediumType:
type: string
description: "Medium type"
example: "example@email.com"
characteristic:
$ref: "#/definitions/ContactMediumCharacteristic"
ContactMediumCharacteristic:
type: object
properties:
emailAddress:
type: string
example: "exampl@example.com"
description: "Contact email address"
ProductRef:
type: object
properties:
id:
type: string
description: unique identifier
href:
type: string
description: Hyperlink reference
name:
type: string
description: Name of the related entity.
amount:
type: object
properties:
value:
type: number
example: 90
taxAmount:
type: object
properties:
value:
type: number
example: 20
'@baseType':
example: ResourceSpecification
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
example: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
example: LogicalResourceSpecification
type: string
description: When sub-classing, this defines the sub-class Extensible name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
LogicalResourceRef:
type: object
description: reference to the LogicalResource eg MSISDN
properties:
id:
type: string
description: unique identifier
href:
type: string
description: Hyperlink reference
name:
type: string
description: Name of the related entity.
'@baseType':
example: ResourceSpecification
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
example: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
example: LogicalResourceSpecification
type: string
description: When sub-classing, this defines the sub-class Extensible name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
TimePeriod:
type: object
description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both
properties:
endDateTime:
example: '1985-04-12T23:20:50.52Z'
type: string
format: date-time
description: End of the time period, using IETC-RFC-3339 format
startDateTime:
example: '1985-04-12T23:20:50.52Z'
type: string
format: date-time
description: Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
Money:
type: object
description: A base / value business entity used to represent money
properties:
units:
type: string
description: Currency (ISO4217 norm uses 3 letters to define the currency)
amount:
type: number
format: float
description: A positive floating point number
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
ChannelRef:
type: object
description: >-
The channel to which the resource reference to. e.g. channel for selling product offerings, channel for opening a trouble ticket etc..
properties:
id:
type: string
description: Unique identifier. This can be channel id , reference id etc
name:
type: string
description: Name of the channel. This can be channel short code or shrot name etc.
href:
type: string
description: channel url.
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
required:
- name
RelatedParty:
type: object
description: >-
Related Entity reference. A related party defines party or party role
linked to a specific entity.
properties:
id:
type: string
description: Unique identifier
name:
type: string
description: Name or ID of the related entity.
role:
type: string
description: Role played by the related party.
status:
type: string
description: Status of the related party.
href:
type: string
description: "Link"
example: "link://something-here.send"
description:
type: string
description: "Description of the related party"
bucket:
type: array
items:
$ref: "#/definitions/BucketRef"
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
BucketRef:
type: object
required:
- id
description: link to the resource that holds bucket information
properties:
id:
type: string
description: Unique identifier. This can be bucket id or wallet id etc.
name:
type: string
description: Name of the related entity.
role:
type: string
description: "Role of the activity"
href:
type: string
description: "Link"
usageType:
$ref: "#/definitions/UsageType"
description: Defines the type of the underlying balance e.g. data,voice, monetary etc.
balance:
$ref: "#/definitions/Quantity"
activationDate:
type: string
format: date-time
description: Activation date of the bucket.
expiryDate:
type: string
format: date-time
description: Expiry date of the bucket.
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
'@type':
example: LogicalResourceSpecification
type: string
description: When sub-classing, this defines the sub-class Extensible name
UsageType:
type: string
description: Valid values for the usage type are
enum:
- monetary
- voice
- data
- sms
Quantity:
type: object
description: An amount in a given unit
properties:
amount:
default: 1
type: number
format: float
description: Numeric value in a given unit
units:
type: string
description: Unit
BalanceAdjustmentBody:
properties:
type:
type: string
description: A preconfigured value that describes a TopUp type which determines the prepay balance bucket in which the top-up is done (national-voice, roaming-voice, promotional-voice, data, ....)
reason:
type: string
description: Text describing the reason for the adjustment
amount:
$ref: '#/definitions/QuantityType'
description: Amount (can be monetary or non-monetary) to be recharged in the bucket. It could refer to positive (increment) or negative (decrement) values
product:
$ref: '#/definitions/ProductRefType'
description: A reference to the product related to the bucket that is impacted by the balance related operation
required:
- type
- reason
- amount
BalanceAdjustmentRequest:
allOf:
- $ref: '#/definitions/BalanceAdjustmentBody'
description: 'the BalanceAdjustment resource is a detailed description of credit adjustment operation erformed on a given bucket (defined by a specific product or reference to a product (i.e.: a commercial id such as an msisidn) and a service type)'
properties:
id:
type: string
description: Unique Identifier within the server for the balance adjustment operation request
href:
type: string
description: 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
description:
type: string
description: Description of the recharge operation
PartyAccount:
$ref: '#/definitions/RelatedPartyRefType'
description: Identifier for the user/customer/entity that performs the top-up action. 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�.
validFor:
$ref: '#/definitions/TimePeriodType'
description: The period defined for the adjusted amount to be part of the prepay balance. This could be used to define expiration times to remove balance not consumed.
requestedDate:
type: string
description: Date when the top-up request was received in the server
bucket:
$ref: '#/definitions/BucketBalanceRefType'
description: A reference to the bucket impacted by the request. This is used in scenarios where the requestor knows beforehand the bucket that is going to be impacted instead of just referring to the commercial identifier of the impacted product and the type of bucket created under that product
partyAccount:
$ref: '#/definitions/PartyAccountRefType'
description: A reference to the account that owns the bucket impacted by the balance related operation
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedPartyRefType'
description: Used to provide information about any other entity with relation to the operation
required:
- id
- href
- requestedDate
- product
BalanceActivity:
description: The BalanceActivity resource is a detailed description of a specific balance-related action that has happened over a given bucket balance. Typically a recharge/transfer/adjustment request creates one activity, but a request for an auto-topup operation actually triggers multiple periodic balance-related activities.
properties:
type:
type: string
description: A preconfigured value that describes a type of balance-related performed (topup, t
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-tmf-prepay-balance-management-tmf654.yml