To register services and activate services content tokens.
swagger: '2.0'
info:
description: To register services and activate services content tokens
version: "v1.0"
title: Customer Billing Token API
schemes:
- https
host: "api.mtn.com"
basePath: "/v1/customer"
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:
/bill/registerToken:
post:
tags:
- Registration
summary: Register Token Service
description: Billing Recurring Service Token Registration
operationId: Register
parameters:
- name: "targetSystem"
in: header
required: false
type: string
default: Pantheon
enum:
- Pantheon
- SOA
- name: "allowPoll"
in: header
required: true
type: boolean
enum:
- TRUE
- FALSE
- name: body
in: body
required: true
schema:
$ref: "#/definitions/RegisterTokenRequest"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/CreateOrderResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorBadReq"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
"452":
description: "Invalid API Version"
schema:
$ref: "#/definitions/ErrorInvAPIVersion"
"454":
description: "MSISDN Not Provided"
schema:
$ref: "#/definitions/ErrorMsisdnNotProvided"
"463":
description: "Subscription Channel Not Found"
schema:
$ref: "#/definitions/ErrorSubChanNotFound"
"464":
description: "Subscription Not Found"
schema:
$ref: "#/definitions/ErrorSubNotFound"
"466":
description: "Service Not Found"
schema:
$ref: "#/definitions/ErrorSvcNotFound"
"467":
description: "Active Subscription Exists"
schema:
$ref: "#/definitions/ErrorActSubsEx"
"470":
description: "Service Not Linked To Billing Channel"
schema:
$ref: "#/definitions/ErrorSvcNotLinked"
"473":
description: "Service ID or Service Ref Not Found"
schema:
$ref: "#/definitions/ErrorSvcIdSvcRefNotFound"
"478":
description: "Invalid MSISDN"
schema:
$ref: "#/definitions/ErrorInvMsisdn"
"480":
description: "Invalid Billing Rate"
schema:
$ref: "#/definitions/ErrorInvBillRate"
"485":
description: "Pending Subscription Exists"
schema:
$ref: "#/definitions/ErrorPendingSubEx"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
"515":
description: "Subscription Not Active"
schema:
$ref: "#/definitions/ErrorSubNotActive"
/bill/activateToken:
post:
tags:
- Activation
summary: Activate Token Service
description: Billing Recurring Service Token Activation
parameters:
- name: "targetSystem"
in: header
required: false
type: string
enum:
- Pantheon
- name: "allowPoll"
in: header
required: true
type: boolean
enum:
- TRUE
- FALSE
- name: body
in: body
required: true
schema:
$ref: "#/definitions/ActivateTokenRequest"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/CreateOrderResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorBadReq"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
"452":
description: "Invalid API Version"
schema:
$ref: "#/definitions/ErrorInvAPIVersion"
"454":
description: "MSISDN Not Provided"
schema:
$ref: "#/definitions/ErrorMsisdnNotProvided"
"463":
description: "Subscription Channel Not Found"
schema:
$ref: "#/definitions/ErrorSubChanNotFound"
"464":
description: "Subscription Not Found"
schema:
$ref: "#/definitions/ErrorSubNotFound"
"466":
description: "Service Not Found"
schema:
$ref: "#/definitions/ErrorSvcNotFound"
"467":
description: "Active Subscription Exists"
schema:
$ref: "#/definitions/ErrorActSubsEx"
"470":
description: "Service Not Linked To Billing Channel"
schema:
$ref: "#/definitions/ErrorSvcNotLinked"
"473":
description: "Service ID or Service Ref Not Found"
schema:
$ref: "#/definitions/ErrorSvcIdSvcRefNotFound"
"478":
description: "Invalid MSISDN"
schema:
$ref: "#/definitions/ErrorInvMsisdn"
"480":
description: "Invalid Billing Rate"
schema:
$ref: "#/definitions/ErrorInvBillRate"
"485":
description: "Pending Subscription Exists"
schema:
$ref: "#/definitions/ErrorPendingSubEx"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
"515":
description: "Subscription Not Active"
schema:
$ref: "#/definitions/ErrorSubNotActive"
/bill/deactivateToken:
put:
tags:
- Deactivation
summary: Deactivate Token Service
parameters:
- name: "targetSystem"
in: header
required: false
type: string
enum:
- Pantheon
- name: isComposite
type: boolean
required: false
in: query
- name: body
in: body
required: true
schema:
$ref: "#/definitions/DeactivateTokenRequest"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/CreateOrderResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorBadReq"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
"452":
description: "Invalid API Version"
schema:
$ref: "#/definitions/ErrorInvAPIVersion"
"454":
description: "MSISDN Not Provided"
schema:
$ref: "#/definitions/ErrorMsisdnNotProvided"
"463":
description: "Subscription Channel Not Found"
schema:
$ref: "#/definitions/ErrorSubChanNotFound"
"464":
description: "Subscription Not Found"
schema:
$ref: "#/definitions/ErrorSubNotFound"
"466":
description: "Service Not Found"
schema:
$ref: "#/definitions/ErrorSvcNotFound"
"467":
description: "Active Subscription Exists"
schema:
$ref: "#/definitions/ErrorActSubsEx"
"470":
description: "Service Not Linked To Billing Channel"
schema:
$ref: "#/definitions/ErrorSvcNotLinked"
"473":
description: "Service ID or Service Ref Not Found"
schema:
$ref: "#/definitions/ErrorSvcIdSvcRefNotFound"
"478":
description: "Invalid MSISDN"
schema:
$ref: "#/definitions/ErrorInvMsisdn"
"480":
description: "Invalid Billing Rate"
schema:
$ref: "#/definitions/ErrorInvBillRate"
"485":
description: "Pending Subscription Exists"
schema:
$ref: "#/definitions/ErrorPendingSubEx"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
"515":
description: "Subscription Not Active"
schema:
$ref: "#/definitions/ErrorSubNotActive"
/bill/urlCreate:
post:
tags:
- urlCreate
summary: Create URL
parameters:
- name: targetSystem
in: query
required: true
type: string
enum:
- Pantheon
- name: body
in: body
required: true
schema:
$ref: "#/definitions/createUrlRequest"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/createUrlResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/bill/debit:
post:
tags:
- Debit
summary: Debit Token Service
description: Debit token request is used to initiate billing for DCB active tokens with VATDetails. This version also accept optional parameter offerDetails and these offeDetails are fowarded to COM for pbundle provisioning.
parameters:
- name: targetSystem
in: query
required: true
type: string
enum:
- Pantheon
- name: body
in: body
required: true
schema:
$ref: "#/definitions/debitRequest"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/debitResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/bill/refund:
post:
tags:
- Refund
summary: Refund Token Service
description: Refund token request is used to refund subscribers which were succesfully billed for DCB and Adhoc tokens. A debitNotidication with billed subscriber account balance details is required for a refund to be processed.
parameters:
- name: targetSystem
in: query
required: true
type: string
enum:
- Pantheon
- name: body
in: body
required: true
schema:
$ref: "#/definitions/refundRequest"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/refundResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/bill/transactionStatus:
get:
tags:
- Status
summary: Query transaction status
description: Query the transaction status for refunds, order and debit transactions.
parameters:
- name: targetSystem
in: query
required: true
type: string
enum:
- Pantheon
- name: type
in: query
required: false
type: string
- name: transactionId
in: query
required: false
type: string
- name: contractingPartnerId
in: query
required: false
type: string
- name: originTransactionID
in: query
required: false
type: string
- name: paymentRef
in: query
required: false
type: string
- name: orderRef
in: query
required: false
type: string
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/transStatResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
/bill/tokenStatus:
get:
tags:
- Status
summary: Query token status
description: Query the status of registered token
parameters:
- name: targetSystem
in: query
required: true
type: string
enum:
- Pantheon
- name: transactionId
in: query
required: false
type: string
- name: contractingPartnerId
in: query
required: false
type: string
- name: platformPartnerId
in: query
required: false
type: string
- name: contentToken
in: query
required: false
type: string
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/tokenStatResponse"
'400':
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
'401':
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
'403':
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
'404':
description: "Customer not found"
schema:
$ref: "#/definitions/Error"
'405':
description: "Method Not allowed"
schema:
$ref: "#/definitions/Error"
'500':
description: "Internal Server Error"
schema:
$ref: "#/definitions/Error"
definitions:
RegisterTokenRequest:
type: object
properties:
billingToken:
type: object
required:
- transactionId
- contractingPartnerId
- platformPartnerId
- msisdn
- billingType
- subscriberType
properties:
transactionId:
type: string
minLength: 9
maxLength: 36
description: Unique transaction identifier. It is advised that the client system use the methods defined in [RFC4122](https://tools.ietf.org/html/rfc4122) to generate this value.
example: '123456768'
contractingPartnerId:
type: string
minLength: 9
maxLength: 9
description: Contracting Partner Identifier as supplied by MTN Digital Department.
example: '911844857'
platformPartnerId:
type: string
minLength: 9
maxLength: 9
description: Platform Partner Identifier.
example: '911844857'
customerId:
type: string
minLength: 10
maxLength: 12
description: MSISDN of the subscriber.
example: '27832001000'
customerIdType:
type: string
description: Type of customer id
example: "msisdn"
billingType:
type: string
description: Token billing attempt will be for the full amount
sourceReferenceNumber:
type: string
description: The payment reference number generated for the payment at the source channel – for MTNPay card payments
returnUrl:
type: string
description: This field will be the self-service channel web page URL where the user is supposed to be once the payment is done on payportal – for MTNPay card payments
contentTypeId:
type: string
minLength: 3
maxLength: 3
description: Content type identifier. Default to 100 for DCB Google.
example: '100'
contentDescription:
type: string
minLength: 1
maxLength: 100
description: Description of content charged for.
example: Games
contentId:
type: string
minLength: 1
maxLength: 35
description: Content identifier.
example: '001'
partnerDisplayName:
type: string
minLength: 1
maxLength: 25
description: Content provider name.
example: Google
serviceInterval:
type: integer
minLength: 1
maxLength: 999
description: This field represents the service interval for a subscription/adhoc service in days. For adhoc the service interval should be 0.
example: 1
serviceIntervalMaxBillAmount:
type: integer
minimum: 0
maximum: 999999
description: This field represents the maximum billable amount(in cents) per service interval.
example: 100
fallBackInitialStepDownServiceExtension:
type: integer
minLength: 1
maxLength: 999
description: >-
If Billing type is FALL-BACK this field is the duration
for which the service will be initially extended for in days.
example: 1
fallBackInitialStepDownCharge:
type: integer
minLength: 0
maxLength: 999999
description: This is the amount(in cents) that should be charged for the period above.
example: 100
fallBackFinalStepDownServiceExtension:
type: integer
minLength: 1
maxLength: 999
description: >-
If Billing type is FALL-BACK this field is the duration in days for which the service will be
extended for in the event that the initial stepdown attempt was unsuccessful, otherwise empty.
example: 1
fallBackFinalStepDownCharge:
type: integer
minLength: 0
maxLength: 999999
description: >-
This field is only applicable if the fallBack final step down service interval is present,
and it is the amount in cents.
example: 100
initialCharge:
type: integer
minLength: 0
maxLength: 999999
description: >-
table: This field represents the service initial charge in cents
example: 100
tokenExpiry:
type: string
minLength: 10
maxLength: 10
description: This field represents the expiry date of a Content-Token in the format 'yyyy-mm-dd'.
example: '2020-02-18'
freeDays:
type: integer
description: This field represents the number of free service days a subscriber will be entitled to when authorizing a Content-Token.
example: 2
contentLimit:
type: string
minLength: 4
maxLength: 35
description: This field is used to indicate which limit counter to step.
example: 'MTN-ENTERTAINMENT'
allowedRecoveryIntervals:
type : integer
minimum: 0
maximum: 31
description : This field indicates the number of intervals that can be back billed for a service.
example: 2
billingMethod:
type: string
description: >-
The payment method for the service: Card Payment and Momo are only compatible with billingType value FULL. If billingMethod = "MTN Airtime" then only subscriberMNO = "Onnet" is allowed. If billingMethod is not defined, Pantheon shall set default to "MTN Airtime".
enum : [MTN Airtime,Card Payment,Momo,Offnet Airtime]
budgetPeriod:
type: integer
description: Credit Card Budget period in months. If budgetPeriod is not defined, Pantheon shall set default to 0 months.
example : 1
userAlias:
type: string
minimum: 5
maxLength: 50
description: Additional alias to identify a user i.e like an email address.
example : pantheon@mtn.com
secureDTxId:
type: string
minimum: 5
maxLength: 30
description: ID returned from the Secure-D check as part of DOI process.
revenueCategory:
type: string
minimum: 1
maxLength: 30
description: Revenue category.
revenueSubCategory:
type: string
minimum: 1
maxLength: 30
description: Revenue sub-category.
smeIntContractingPartnerId:
type: string
minimum: 9
maxLength: 9
description: The Subscription Management Engine internal partner identifier.
contractingPartnerType:
type: string
description: >-
table: This is the allowed content types. If contractingPartnerType is not defined, Pantheon shall set default to "Not Specified".
|Type |Description |
|-------------------|---------------------------|
| CP | Content Partner |
| WASP | External WASP Partner |
enum: [CP, WASP]
subscriberMNO:
type: string
description: Mobile Network Operator. If billingMethod = "MTN Airtime" then only subscriberMNO = "Onnet" is allowed. If subscriberMNO is not defined, Pantheon shall set default to "Onnet".
enum: [ Onnet, Offnet]
revenueTreatment:
type: string
description: Revenue treatment.
enum: [ Principle, Agent]
integratorPartnerId:
type: string
minLength: 9
maxLength: 9
description: A party that acts as an aggregator of the transaction.
example: '911844857'
contentProviderId:
type: string
minLength: 9
maxLength: 9
description: A party that has no contract with MTN but in the contract with the contracting party, it states that MTN needs to pay a portion of the revenue to them.
example: '911844857'
acquisitionChannel:
type: string
minLength: 1
maxLength: 30
description: This field is used to indicate the request channel.
example: 'USSD'
selectedDebitOrderDate:
type : integer
minimum: 1
maximum: 31
description : The token anniversary date as selected by the subscriber. Note that if the selected date does not exist in any month (e.g., 29, 30, or 31), then billing will happen on the last day of the month. This field is only used for a monthly subscription - use serviceInterval for daily/weekly subscriptions.
example: 25
billCycles:
type: integer
description: This field indicates the number of cycles/intervals that can be billed for a service. This field is only used for billingType = “FULL”
subscription:
type: object
properties:
externalId:
type: string
description: ID given by the consumer and only understandable by him (to facilitate his searches afterwards)
example: 67328fhhfdfh39u956
status:
type: string
example: Captured
description: Status of the product
reason:
type: string
example: 001
description:
type: string
example: purchase VAS product
channel:
type: array
items:
$ref: '#/definitions/RelatedChannel'
productOrderItem:
type: array
items:
$ref: '#/definitions/ProductOrderItem'
minItems: 1
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedParty'
ActivateTokenRequest:
type: object
properties:
billingToken:
required:
- transactionId
- contractingPartnerId
- platformPartnerId
- contentToken
properties:
transactionId:
type: string
minLength: 9
maxLength: 36
description: Unique transaction identifier. It is advised that the client system use the methods defined in [RFC4122](https://tools.ietf.org/html/rfc4122) to generate this value.
example: '123456768'
contractingPartnerId:
type: string
minLength: 9
maxLength: 9
description: Contracting Partner Identifier as supplied by MTN Digital Department.
example: '911844857'
platformPartnerId:
type: string
minLength: 9
maxLength: 9
description: Platform Partner Identifier.
example: '911844857'
contentToken:
type: string
minLength: 16
maxLength: 96
description: Token generated to be used for identifying the service for activation, billing, cancellation and refund.
example: '81B27C92607C6D47274C2859CF51B954A4EE99DFCC7DD89066F6CD41D74A10CE23CCD7C8A32B73DEDC0F2470B703F058'
limitConsent:
type : string
description : Y - Indicates consent was given by the subscriber, either the digital limit, spend limit or both will be updated. N - no limit will be updated.
enum: [ Y, N]
subscription:
type: object
properties:
# productOrderItem:
# type: object
# properties:
# product:
# type: object
# properties:
# productCharacteristic:
# type: array
# items:
# $ref: '#/definitions/productCharacteristicName'
id:
type: string
productOrderItem:
type: array
items:
$ref: '#/definitions/ProductOrderItem2'
minItems: 1
channel:
type: array
items:
$ref: '#/definitions/RelatedChannel'
DeactivateTokenRequest:
type: object
required:
- transactionId
- contractingPartnerId
- platformPartnerId
- contentToken
properties:
transactionId:
type: string
minLength: 9
maxLength: 36
description: Unique transaction identifier. It is advised that the client system use the methods defined in [RFC4122](https://tools.ietf.org/html/rfc4122) to generate this value.
example: '123456768'
contractingPartnerId:
type: string
minLength: 9
maxLength: 9
description: Contracting Partner Identifier as supplied by MTN Digital Department.
example: '911844857'
platformPartnerId:
type: string
minLength: 9
maxLength: 9
description: Platform Partner Identifier.
example: '911844857'
contentToken:
type: string
minLength: 16
maxLength: 96
description: Token generated to be used for identifying the service for activation, billing, cancellation and refund.
example: '81B27C92607C6D47274C2859CF51B954A4EE99DFCC7DD89066F6CD41D74A10CE23CCD7C8A32B73DEDC0F2470B703F058'
tokenAlias:
description: This is the authotization Identifier(AuthID) linked to the token. MSISDN is mandatory when cancelling a token using the token alias.
minLength: 16
maxLength: 96
type: string
example: '9237232085744947941'
customerId:
type: string
minLength: 10
maxLength: 12
description: MSISDN of the subscriber.
example: '27832001000'
cancellationReason:
type : integer
enum: [1,2,3,4]
description: >-
table:
|cancellationReason|Description|
|------------------|----------|
| 1 |Cancelled by subscriber - self|
| 2 |Cancelled by subscriber - assisted|
| 3 |Cancelled by partner|
| 4 |Cancelled due to TCF|
originator:
type: string
minLength: 1
maxLength: 32
description: Origin of the cancellation request.
example: Self Service
subscriptionId:
type: string
description: Id of Subscription
bc_id:
type: integer
description: billing channel identifier
example: 334
DeactivateTokenResponse:
type: object
properties:
statusCode:
type: string
statusMessage:
type: string
timestamp:
type: string
format: date-time
suppo
# --- truncated at 32 KB (127 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-customer-billing-token-v1.yml