To enable merchants to manage purchases of subscribers.
swagger: '2.0'
info:
description: To enable merchants to manage purchases of subscribers
version: "v1.0"
title: MTN Merchant Provisioning API
schemes:
- https
host: "api.mtn.com"
basePath: "/v1/merchant"
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:
/validate/{customerId}:
post:
tags:
- Validate Customer
summary: Validate the given Customer ID.
description: Used by the merchant to validate the Customer ID.
operationId: validateMsisdn
parameters:
- name: "targetSystem"
in: header
required: true
type: string
default: SAAE
enum:
- SAAE
- name: "customerId"
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: "#/definitions/ValidateCustomerRequest"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/ValidateCustomerResponse"
'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"
/purchase/{customerId}:
post:
tags:
- Purchase
summary: Used to purchase airtime/bundles.
description: Used to purchase airtime/bundles. In addition an Auto Top Up (isAutoTopUp) field has been introduced for Bundle or Airtime Recharges. When isAutoTopUp=true, paymentId must be set.
operationId: purchase
parameters:
- name: "targetSystem"
in: header
required: true
type: string
default: SAAE
enum:
- SAAE
- name: "customerId"
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: "#/definitions/PurchaseCustomerRequest"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/ValidateCustomerResponse"
'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"
/adviceReconcile/{merchantId}:
post:
tags:
- Advice Reconcile
summary: Used to purchase airtime/bundles.
description: Used to purchase airtime/bundles. In addition an Auto Top Up (isAutoTopUp) field has been introduced for Bundle or Airtime Recharges. When isAutoTopUp=true, paymentId must be set.
operationId: adviceReconcile
parameters:
- name: "targetSystem"
in: header
required: true
type: string
default: SAAE
enum:
- SAAE
- name: "merchantId"
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: "#/definitions/ReconRequest"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/ReconResponse"
'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"
/usageLimitAdjust/{merchantId}:
post:
tags:
- Usage Limit Adjust
summary: Used to Reserve, Commit or Abort merchant limit.
description: This implementation has been done for the auto top up service where a Merchant's Limit can be reserved (Holds the Limit), Committed (Committed as Success) and Aborted (Limit Rolled Back). If we don't receive a commit or abort within a transaction keep alive period, the request will be aborted which will result in the external party needing to repeat the reserve.
operationId: usageLimitAdjust
parameters:
- name: "targetSystem"
in: header
required: true
type: string
default: SAAE
enum:
- SAAE
- name: "merchantId"
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
$ref: "#/definitions/usageLimitRequest"
responses:
'200':
description: 'Success'
schema:
$ref: "#/definitions/usageLimitResponse"
'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:
ValidateCustomerRequest:
type: object
properties:
merchantId:
type: string
minLength: 1
maxLength: 50
description: This field represents the merchant responsible for initiating the request.
example: '99999'
transactionId:
maxLength: 50
type: string
description: RSN is a unique request sequence number that can be used to tie up the request and response.
example: "4837617387438085"
timestamp:
description: The field denotes the date at which the request is done.
type: string
example: '20101126023515'
posType:
description: This field represents the point of sale identifier of the external application submitting the request.
enum:
- ATM
- CPP
- IVR
- SMS
- TestXML
- USSD
- WAP
- WEB
- WIG
- APP
- AgentAPP
- AgentUSSD
- AgentWEB
type: string
example: 'ATM'
merchantLocation:
description: This field represents the merchant’s location.
type: string
example: '14th avenue, Roodepoort'
purchaseType:
description: Allowed Purchase types. This can either be Recharge, Voucher or Dynamic
type: string
enum:
- Recharge
- Voucher
- Dynamic
bundleID:
description: The virtual alias (Part number) from ERP.
type: string
example: 'DATA100MB'
isAdvanced:
description: For XtraTime.
type: boolean
example: true
ValidateCustomerResponse:
type: object
properties:
statusCode:
type: string
example: "0000"
statusMessage:
type: string
example: "Success"
transactionId:
type: string
description: Unique identifier of the transaction
data:
type: object
properties:
msn:
type: string
description: This field represents the message sequence number generated by the ASAP to track the submitted request at a later point in time.
merchantId:
type: string
minLength: 1
maxLength: 50
description: This field represents the merchant responsible for initiating the request.
example: '99999'
customerId:
type: string
description: Customer Identifier eg. MSISDN
PurchaseCustomerRequest:
type: object
properties:
merchantId:
type: string
minLength: 1
maxLength: 50
description: This field represents the merchant responsible for initiating the request.
example: '99999'
transactionId:
maxLength: 50
type: string
description: RSN is a unique request sequence number that can be used to tie up the request and response.
example: "4837617387438085"
timestamp:
description: The field denotes the date at which the request is done.
type: string
example: '20101126023515'
posType:
description: This field represents the point of sale identifier of the external application submitting the request.
enum:
- ATM
- CPP
- IVR
- SMS
- TestXML
- USSD
- WAP
- WEB
- WIG
- APP
- AgentAPP
- AgentUSSD
- AgentWEB
type: string
example: 'ATM'
merchantLocation:
description: This field represents the merchant’s location.
type: string
example: '14th avenue, Roodepoort'
purchaseType:
description: Allowed Purchase types. This can either be Recharge, Voucher or Dynamic
type: string
enum:
- Recharge
- Voucher
- Dynamic
bundleID:
description: The virtual alias (Part number) from ERP.
type: string
example: 'DATA100MB'
isAdvanced:
description: For XtraTime.
type: boolean
example: true
amount:
description: 'This field denotes the amount that should be credited to the subscribers MSISDN. Note: The amount specified must be in cents.'
type: integer
transactionDescription:
description: This field represents information about the transaction type.
enum:
- AIRTIMELOAN
- AUTOAIRTIMELOAN
- VARIABLEVALUEVOUCHER
type: string
example: 'VARIABLEVALUEVOUCHER'
catalogueVersion:
type: integer
description: Version of the active catalogue on SAAE.
example: 1590739473
varOfferID:
description: This field represents the identifier of the product in the channel catalogue
type: string
example: '9257'
varOfferVal:
description: Used in conjunction with varOfferValUOM to calculate “period” of a service benefit.
type: string
example: '1'
varOfferValUOM:
enum:
- Seconds
- Hours
- Days
- Weeks
- Months
type: string
example: 'Days'
offerType:
type: string
description: This field represents the type of the product in the channel catalogue
offerCategory:
description: This field represents the category of the offer.
type: string
offerSubCategory:
description: This field represents the sub category of the offer.
type: string
offerFreq:
description: This field represents the frequecny at which the bundle is provisioned.
type: string
offerRecCycle:
description: TThis field represents the cycles at which the bundle is provisioned.
type: string
isAutoTopUp:
description: This is a conditional field and is only applicable for purchaseType Recharge . This field will enable customers to automatically purchase frequency-based Bundles or Airtime
type: boolean
example: true
paymentId:
description: Mandatory when Auto Top up is true. The portal (online recharges) generates the product payment ID (PPID), which will be shared via SOA to SAAE to IBF.
type: string
example: '5454DERFD'
varServices:
type: array
items:
$ref: "#/definitions/value"
value:
type: object
properties:
serviceType:
description: Auto Top Up
type: boolean
example: true
uom:
type: string
description: Unit of measure
enum:
- MB/GB
- UNITS
- MINUTES
- SECONDS
- RANDS/CENTS
example: 'RANDS/CENTS'
value:
description: The value of the product
type: string
example: 'R16'
effectiveRate:
description: The effective rate of the product. If value of “0” sent in, then default effective rates configured against “product” apply.
type: string
example: '0'
validity:
description: Used in conjunction with VALIDITY_UOM to calculate “period” of a service benefit.
type: string
example: '1'
validityUOM:
description: Unit of measure
enum:
- Seconds
- Hours
- Days
- Weeks
- Months
type: string
example: 'Days'
ReconRequest:
type: object
properties:
transactionId:
maxLength: 50
type: string
description: RSN is a unique request sequence number that can be used to tie up the request and response.
example: "4837617387438085"
timestamp:
description: The field denotes the date at which the request is done.
type: string
example: '20101126023515'
reconDate:
description: This field represents the date for which reconciliation advice (usage) should be retrieved for the merchant ID specified.
type: string
ReconResponse:
type: object
properties:
statusCode:
type: string
example: "0000"
statusMessage:
type: string
example: "Success"
transactionId:
type: string
description: Unique identifier of the transaction
data:
type: object
properties:
msn:
type: string
description: This field represents the message sequence number generated by the ASAP to track the submitted request at a later point in time.
merchantId:
type: string
minLength: 1
maxLength: 50
description: This field represents the merchant responsible for initiating the request.
example: '99999'
reconDate:
description: This field represents the date for which reconciliation advice (usage) should be retrieved for the merchant ID specified.
type: string
reconDateTotal:
description: This field represents the total usage for the merchant on the particular date specified.
type: string
usageLimitRequest:
type: object
properties:
transactionId:
maxLength: 50
type: string
description: RSN is a unique request sequence number that can be used to tie up the request and response.
example: "4837617387438085"
timestamp:
description: The field denotes the date at which the request is done.
type: string
example: '20101126023515'
customerId:
type: string
description: Customer Identifier eg. MSISDN
amount:
description: 'This field denotes the amount that should be credited to the subscribers MSISDN. Note: The amount specified must be in cents.'
type: integer
bundleID:
description: Identifier for the bundle.
type: string
example: 'DATA1G'
usageAdjust:
description: mode of adjustment
type: string
enum:
- Reserve
- Commit
- Abort
paymentId:
description: Mandatory when Auto Top up is true. The portal (online recharges) generates the product payment ID (PPID), which will be shared via SOA to SAAE to IBF.
type: string
example: '5454DERFD'
usageLimitResponse:
type: object
properties:
statusCode:
type: string
example: "0000"
statusMessage:
type: string
example: "Success"
transactionId:
type: string
description: Unique identifier of the transaction
data:
type: object
properties:
reserveRefId:
type: string
description: This field represents the message sequence number generated by the ASAP to track the submitted request at a later point in time. SAAE considers this the same as MSN.
Error:
type: "object"
title: "Error"
required:
- "status"
- "message"
properties:
statusCode:
type: "string"
description: "Status code returned by provider system"
statusMessage:
type: "string"
description: "Status description"
supportMessage:
type: "string"
description: "More error details and corrective measures"
path:
type: "string"
description: "The path that caused the error"
timestamp:
type: "string"
format: "date-time"
description: "Time stamp of the error"
transactionId:
type: "string"
description: "Transaction id returned by the provider system."