TMF666 Account Management API with MTN extensions to retrieve financial account transactions, transaction details, outstanding balances, account balances.
openapi: 3.0.0
info:
title: TMF666 Account Management API
version: "1.0.0"
description: >
TMF666 Account Management API with MTN extensions
to retrieve financial account transactions, transaction details,
outstanding balances, account balances.
servers:
- url: https://api.mtn.com/tmf-api/financialProfile/v1
security:
- bearerAuth: []
paths:
/financialAccount/{id}/transaction:
get:
summary: List Financial Account Transactions
operationId: listFinancialAccountTransactions
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Financial Account identifier
- name: debitCredit
in: query
required: false
schema:
type: string
enum: [D, C]
- name: offset
in: query
schema:
type: string
example: "1"
- name: limit
in: query
required: false
schema:
type: number
example: 50
- name: searchBasedOn
in: query
required: false
schema:
type: string
enum: [S]
- name: serviced
in: query
required: false
schema:
type: string
responses:
"200":
description: Successful transaction list response
content:
application/json:
schema:
$ref: "#/components/schemas/FinancialTransactionList"
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financialAccount/{id}/transaction/{tid}:
get:
summary: Retrieve Financial Account Transaction
operationId: getFinancialAccountTransaction
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Financial Account identifier
- name: tid
in: path
required: true
schema:
type: string
description: Transaction identifier
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/FinancialTransaction"
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financialAccount/{id}/outstandingBalance:
get:
summary: Retrieve Financial Account Outstanding Balance
operationId: getFinancialAccountOutstandingBalance
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: outStandingBasedOn
in: query
required: true
schema:
type: string
enum: [E]
responses:
"200":
description: Outstanding balance response
content:
application/json:
schema:
$ref: "#/components/schemas/OutstandingAmount"
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/financialAccount/{id}/balance:
get:
summary: Retrieve Financial Account Balance
operationId: getFinancialAccountBalance
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: balanceLevel
in: query
required: true
schema:
type: number
enum: [2]
- name: outStandingBasedOn
in: query
required: true
schema:
type: string
enum: [E]
responses:
"200":
description: Successful balance response
content:
application/json:
schema:
$ref: "#/components/schemas/OutstandingAmount"
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
description: Method Not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
Error:
description: Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)
type: object
required:
- code
- reason
properties:
code:
type: string
description: Application relevant detail, defined in the API or a common list.
reason:
type: string
description: Explanation of the reason for the error which can be shown to a client user.
message:
type: string
description: More details and corrective actions related to the error which can be shown to a client user.
status:
type: string
description: HTTP Error code extension
referenceError:
type: string
format: uri
description: URI of documentation describing the error.
'@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.
FinancialTransactionList:
type: object
properties:
transactions:
type: array
items:
$ref: "#/components/schemas/FinancialTransaction"
FinancialTransaction:
type: object
properties:
transactionNumber: { type: string }
transactionDate: { type: string }
debitCredit: { type: string }
amount: { type: string }
remarks: { type: string }
channel: { type: string }
currency: { type: string }
accessedBy: { type: string }
adjustedAmount: { type: string }
autoAdjustFlag: { type: string }
correlationID: { type: string }
financialPostingReference: { type: string }
financialPostingStatus: { type: string }
hierarchyEntityCode: { type: string }
hierarchyParent: { type: string }
isBulkTransaction: { type: string }
invoiceMetaData: { type: object }
userAdditionalInfo: { type: object }
uraadjustmentdetails: { type: object }
paymentDetails:
type: array
items:
type: object
isCleared: { type: string }
status: { type: string }
statusChangeDate:
type: object
properties:
invrecinsertdate: { type: string }
taxAmount: { type: string }
approvalOperationType: { type: string }
excessAmount: { type: string }
runningTotal: { type: string }
cashBoxNumber: { type: string }
disputeAmount: { type: string }
externalReference: { type: string }
paymentId: { type: string }
reasons: { type: string }
transactionOwner: { type: string }
hierarchyRunningTotal: { type: string }
parentHierarchyRunningTotal: { type: string }
OutstandingAmount:
type: object
properties:
totalDebitAmount: { type: number }
totalCreditAmount: { type: number }
totalUnbilledAmount: { type: number }
billedOutstandingAmount: { type: number }
totalOustandingAmount: { type: number }
responses:
BadRequest:
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
timestamp: "2026-01-16T12:33:59.197Z"
status: "400"
error: "Bad Request"
message: "Invalid request parameters"
path: "/financialAccount/123/transaction"
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
timestamp: "2026-01-16T12:33:59.197Z"
status: "401"
error: "Unauthorized"
message: "Missing or invalid authentication token"
path: "/financialAccount/123/transaction"
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
timestamp: "2026-01-16T12:33:59.197Z"
status: "403"
error: "Forbidden"
message: "Access to this resource is denied"
path: "/financialAccount/123/transaction"
NotFound:
description: Customer not found
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
timestamp: "2026-01-16T12:33:59.197Z"
status: "404"
error: "Not Found"
message: "Customer not found"
path: "/financialAccount/123/transaction"
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
timestamp: "2026-01-16T12:33:59.197Z"
status: "500"
error: "Internal Server Error"
message: "Unexpected system error occurred"
path: "/financialAccount/123/transaction"