API will enable MTN customers to transfer part of their active airtime or data to another MTN customer. This service excludes special data plans.
openapi: 3.0.1
info:
title: 'Customer Transfer '
description: API will enable MTN customers to transfer part of their active airtime
or data to another MTN customer. This service excludes special data plans
license:
name: MADAPI
url: https://developers.mtn.com/
version: 3.0.0
servers:
- url: https://api.mtn.com/v1
description: Production Server
security:
- OAuth2: []
tags:
- name: CustomerTransferService
paths:
/customers/{senderMsisdn}:
post:
tags:
- CustomerTransferService
summary: Customers
description: Customers will be able to transfer airtime or data to other MTN
customers using both traditional and digital channel options available to
them.
operationId: CustomerTransferService_post_transfer_customerssenderMsisd
parameters:
- name: senderMsisdn
in: path
required: true
schema:
type: string
- name: network
in: query
required: false
schema:
type: string
- name: x-country-code
in: header
required: false
schema:
type: string
- name: transactionId
in: header
required: false
schema:
type: string
- name: x-origin-channelid
in: header
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
title: CustomerTransferRequest
required:
- receiverMsisdn
- targetSystem
- type
type: object
properties:
additionalInformation:
type: array
items:
title: AdditionalInformation
type: object
properties:
name:
type: string
description:
type: string
agentId:
type: string
productId:
type: integer
format: int32
dstAccountType:
type: integer
format: int32
transferAmount:
type: string
type:
type: string
targetSystem:
type: string
paysrc:
type: string
productCode:
type: string
pin:
type: string
srcAccountType:
type: integer
format: int32
callbackUrl:
type: string
receiverMsisdn:
type: string
required: true
responses:
"200":
description: Success
content:
application/json:
schema:
title: CustomerTransferResponse
type: object
properties:
downstreamStatusCode:
type: integer
format: int32
sequenceNo:
type: string
data:
title: CustomerTransferResponseData
type: object
properties:
agentId:
type: string
productId:
type: string
localTransactionId:
type: string
description:
type: string
productName:
type: string
notification:
type: string
unit:
type: string
productCode:
type: string
accountBalances:
type: array
items:
title: AccountBalance
type: object
properties:
amount:
title: Amount
type: object
properties:
value:
type: string
currencyCode:
type: string
balanceType:
type: string
valueCharged:
type: integer
format: int64
customerId:
type: string
receiverMsisdn:
type: string
transactionState:
type: string
productType:
type: string
links:
type: array
items:
title: Link
type: object
properties:
template:
title: UriTemplate
type: object
properties:
template:
type: string
variables:
title: TemplateVariables
type: object
properties:
variables:
type: array
items:
title: TemplateVariable
type: object
properties:
name:
type: string
limit:
type: integer
format: int32
description:
type: string
type:
title: VariableType
type: object
properties:
optional:
type: boolean
combiner:
type: string
key:
type: string
cardinality:
title: Cardinality
type: object
baseUri:
type: string
groups:
title: ExpandGroups
type: object
properties:
groupList:
type: array
items:
title: ExpandGroup
type: object
properties:
variables:
title: TemplateVariables
type: object
properties:
variables:
type: array
items:
title: TemplateVariable
type: object
properties:
name:
type: string
limit:
type: integer
format: int32
description:
type: string
type:
title: VariableType
type: object
properties:
optional:
type: boolean
combiner:
type: string
key:
type: string
cardinality:
title: Cardinality
type: object
type:
title: VariableType
type: object
properties:
optional:
type: boolean
combiner:
type: string
key:
type: string
affordances:
type: array
items:
title: Affordance
type: object
properties:
models:
type: object
additionalProperties:
title: AffordanceModel
type: object
properties:
output:
title: PayloadMetadata
type: object
input:
title: InputPayloadMetadata
type: object
queryMethodParameters:
type: array
items:
title: QueryParameter
type: object
properties:
name:
type: string
value:
type: string
required:
type: boolean
name:
type: string
link:
title: Link
type: object
httpMethod:
title: HttpMethod
type: object
properties:
name:
type: string
hreflang:
type: string
profile:
type: string
rel:
title: LinkRelation
type: object
name:
type: string
href:
type: string
media:
type: string
title:
type: string
type:
type: string
deprecation:
type: string
statusMessage:
type: string
transactionId:
type: string
statusCode:
type: string
supportMessage:
type: string
"400":
description: "Bad request. Invalid request parameters, missing required\
\ fields, or validation errors."
content:
application/json:
schema:
title: APIError
required:
- statusCode
- statusMessage
type: object
properties:
path:
type: string
description: API endpoint path where the error occurred
example: /api/v1/resource
downstreamStatusCode:
type: string
description: Downstream service error code if applicable
sequenceNo:
type: string
description: Sequence number for request tracking
example: "20250115120000001"
method:
type: string
description: HTTP method of the request that caused the error
example: POST
statusMessage:
type: string
description: Human-readable error message
example: Bad request. Invalid parameters provided.
transactionId:
type: string
description: Transaction identifier for tracking and correlation
example: "1234567890"
statusCode:
type: string
description: Error status code
example: "400"
supportMessage:
type: string
description: Technical support message or error code for troubleshooting
example: VALIDATION_ERROR
timestamp:
type: string
description: Error timestamp in ISO 8601 format
format: date-time
example: 2025-01-15T12:00:00Z
description: Generic MADAPI error response structure
example:
sequenceNo: "20250115120000001"
statusMessage: "Bad request. Invalid request parameters, missing\
\ required fields, or validation errors."
transactionId: "1234567890"
statusCode: "400"
supportMessage: API_ERROR
timestamp: 2025-01-15T12:00:00Z
"401":
description: "Unauthorized. Invalid or missing authorization credentials,\
\ insufficient permissions, or authentication failure."
content:
application/json:
schema:
title: APIError
required:
- statusCode
- statusMessage
type: object
properties:
path:
type: string
description: API endpoint path where the error occurred
example: /api/v1/resource
downstreamStatusCode:
type: string
description: Downstream service error code if applicable
sequenceNo:
type: string
description: Sequence number for request tracking
example: "20250115120000001"
method:
type: string
description: HTTP method of the request that caused the error
example: POST
statusMessage:
type: string
description: Human-readable error message
example: Bad request. Invalid parameters provided.
transactionId:
type: string
description: Transaction identifier for tracking and correlation
example: "1234567890"
statusCode:
type: string
description: Error status code
example: "400"
supportMessage:
type: string
description: Technical support message or error code for troubleshooting
example: VALIDATION_ERROR
timestamp:
type: string
description: Error timestamp in ISO 8601 format
format: date-time
example: 2025-01-15T12:00:00Z
description: Generic MADAPI error response structure
example:
sequenceNo: "20250115120000001"
statusMessage: "Unauthorized. Invalid or missing authorization credentials,\
\ insufficient permissions, or authentication failure."
transactionId: "1234567890"
statusCode: "401"
supportMessage: API_ERROR
timestamp: 2025-01-15T12:00:00Z
"403":
description: Forbidden. Access denied. The request is valid but the server
refuses to perform it.
content:
application/json:
schema:
title: APIError
required:
- statusCode
- statusMessage
type: object
properties:
path:
type: string
description: API endpoint path where the error occurred
example: /api/v1/resource
downstreamStatusCode:
type: string
description: Downstream service error code if applicable
sequenceNo:
type: string
description: Sequence number for request tracking
example: "20250115120000001"
method:
type: string
description: HTTP method of the request that caused the error
example: POST
statusMessage:
type: string
description: Human-readable error message
example: Bad request. Invalid parameters provided.
transactionId:
type: string
description: Transaction identifier for tracking and correlation
example: "1234567890"
statusCode:
type: string
description: Error status code
example: "400"
supportMessage:
type: string
description: Technical support message or error code for troubleshooting
example: VALIDATION_ERROR
timestamp:
type: string
description: Error timestamp in ISO 8601 format
format: date-time
example: 2025-01-15T12:00:00Z
description: Generic MADAPI error response structure
example:
sequenceNo: "20250115120000001"
statusMessage: Forbidden. Access denied. The request is valid but
the server refuses to perform it.
transactionId: "1234567890"
statusCode: "403"
supportMessage: API_ERROR
timestamp: 2025-01-15T12:00:00Z
"404":
description: Not found. The requested resource was not found or does not
exist.
content:
application/json:
schema:
title: APIError
required:
- statusCode
- statusMessage
type: object
properties:
path:
type: string
description: API endpoint path where the error occurred
example: /api/v1/resource
downstreamStatusCode:
type: string
description: Downstream service error code if applicable
sequenceNo:
type: string
description: Sequence number for request tracking
example: "20250115120000001"
method:
type: string
description: HTTP method of the request that caused the error
example: POST
statusMessage:
type: string
description: Human-readable error message
example: Bad request. Invalid parameters provided.
transactionId:
type: string
description: Transaction identifier for tracking and correlation
example: "1234567890"
statusCode:
type: string
description: Error status code
example: "400"
supportMessage:
type: string
description: Technical support message or error code for troubleshooting
example: VALIDATION_ERROR
timestamp:
type: string
description: Error timestamp in ISO 8601 format
format: date-time
example: 2025-01-15T12:00:00Z
description: Generic MADAPI error response structure
example:
sequenceNo: "20250115120000001"
statusMessage: Not found. The requested resource was not found or
does not exist.
transactionId: "1234567890"
statusCode: "404"
supportMessage: API_ERROR
timestamp: 2025-01-15T12:00:00Z
"500":
description: "Internal server error. Unexpected system failure, database\
\ connectivity issues, or external service integration problems."
content:
application/json:
schema:
title: APIError
required:
- statusCode
- statusMessage
type: object
properties:
path:
type: string
description: API endpoint path where the error occurred
example: /api/v1/resource
downstreamStatusCode:
type: string
description: Downstream service error code if applicable
sequenceNo:
type: string
description: Sequence number for request tracking
example: "20250115120000001"
method:
type: string
description: HTTP method of the request that caused the error
example: POST
statusMessage:
type: string
description: Human-readable error message
example: Bad request. Invalid parameters provided.
transactionId:
type: string
description: Transaction identifier for tracking and correlation
example: "1234567890"
statusCode:
type: string
description: Error status code
example: "400"
supportMessage:
type: string
description: Technical support message or error code for troubleshooting
example: VALIDATION_ERROR
timestamp:
type: string
description: Error timestamp in ISO 8601 format
format: date-time
example: 2025-01-15T12:00:00Z
description: Generic MADAPI error response structure
example:
sequenceNo: "20250115120000001"
statusMessage: "Internal server error. Unexpected system failure,\
\ database connectivity issues, or external service integration\
\ problems."
transactionId: "1234567890"
statusCode: "500"
supportMessage: API_ERROR
timestamp: 2025-01-15T12:00:00Z
"502":
description: Bad gateway. The server acting as a gateway received an invalid
response from an upstream server.
content:
application/json:
schema:
title: APIError
required:
- statusCode
- statusMessage
type: object
properties:
path:
type: string
description: API endpoint path where the error occurred
example: /api/v1/resource
downstreamStatusCode:
type: string
description: Downstream service error code if applicable
sequenceNo:
type: string
description: Sequence number for request tracking
example: "20250115120000001"
method:
type: string
description: HTTP method of the request that caused the error
example: POST
statusMessage:
type: string
description: Human-readable error message
example: Bad request. Invalid parameters provided.
transactionId:
type: string
description: Transaction identifier for tracking and correlation
example: "1234567890"
statusCode:
type: string
description: Error status code
example: "400"
supportMessage:
type: string
description: Technical support message or error code for troubleshooting
example: VALIDATION_ERROR
timestamp:
type: string
description: Error timestamp in ISO 8601 format
format: date-time
example: 2025-01-15T12:00:00Z
description: Generic MADAPI error response structure
example:
sequenceNo: "20250115120000001"
statusMessage: Bad gateway. The server acting as a gateway received
an invalid response from an upstream server.
transactionId: "1234567890"
statusCode: "502"
supportMessage: API_ERROR
timestamp: 2025-01-15T12:00:00Z
"503":
description: Service unavailable. The server is temporarily unable to handle
the request due to maintenance or overload.
content:
application/json:
schema:
title: APIError
required:
- statusCode
- statusMessage
type: object
properties:
path:
type: string
description: API endpoint path where the error occurred
example: /api/v1/resource
downstreamStatusCode:
type: string
description: Downstream service error code if applicable
sequenceNo:
type: string
description: Sequence number for request tracking
example: "20250115120000001"
method:
type: string
description: HTTP method of the request that caused the error
example: POST
statusMessage:
type: string
description: Human-readable error message
example: Bad request. Invalid parameters provided.
transactionId:
type: string
description: Transaction identifier for tracking and correlation
example: "1234567890"
statusCode:
type: string
description: Error status code
example: "400"
supportMessage:
type: string
description: Technical support message or error code for troubleshooting
example: VALIDATION_ERROR
timestamp:
type: string
description: Error timestamp in ISO 8601 format
format: date-time
example: 2025-01-15T12:00:00Z
description: Generic MADAPI error response structure
example:
sequenceNo: "20250115120000001"
statusMessage: Service unavailable. The server is temporarily unable
to handle the request due to maintenance or overload.
transactionId: "1234567890"
statusCode: "503"
supportMessage: API_ERROR
timestamp: 2025-01-15T12:00:00Z
deprecated: false
/customers/transactionStatus:
get:
tags:
- CustomerTransferService
summary: Customers
description: Provides the status of a Transaction and ensures that the state
of the transaction is communicated to service providers.
operationId: CustomerTransferService_get_transactionStatus_customerstransaction
parameters:
- name: transactionId
in: query
required: false
schema:
type: string
- name: operation
in: query
required: false
schema:
type: string
- name: network
in: query
required: false
schema:
type: string
- name: x-country-code
in: header
required: false
schema:
type: string
- name: targetSystem
in: header
required: false
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
title: CustomerTransferResponse
type: object
properties:
downstreamStatusCode:
type: integer
format: int32
sequenceNo:
type: string
data:
title: CustomerTransferResponseData
type: object
properties:
agentId:
type: string
productId:
type: string
localTransactionId:
type: string
description:
type: string
productName:
type: string
notification:
type: string
unit:
type: string
productCode:
type: string
accountBalances:
type: array
items:
title: AccountBalance
type: object
properties:
# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-mtn-customer-datatransfer.yml