--- swagger: "2.0" info: description: |- API will enable MTN customers to transfer part of their active airtime or data to another MTN customer. **14-July-21: ChangeID: c835ca3** - Removed nodeId and made transferamount, productCode optional version: "1.1" title: Customer Transfer API for (Airtime or Data) host: api.mtn.com basePath: "/v1/transfer" schemes: - https consumes: - application/json produces: - application/json securityDefinitions: ApiKeyAuth: type: "apiKey" name: "X-API-Key" in: "header" security: - ApiKeyAuth: [] tags: - name: Customer description: "Customers will be able to transfer bundle via traditional and digital channel" externalDocs: url: https://mtngroup.atlassian.net/wiki/spaces/MSA/pages/976224274/Data+Transfer+API paths: /customers/{senderMsisdn}: post: tags: - Customer summary: Transfer (Data or Airtime) description: "Provides the ability to transfer Airtime or Data from one customer to another. The following validation will be checked once MTN received the transfer request:Appropriate notification message shall be sent to the customer in case of any failed validation step" parameters: - name: "senderMsisdn" in: path description: Source Msisdn. The format must be E.123 required: true type: string - name: channelId type: string in: header description: ID of the requesting body required: false - in: body name: body description: Request body required: true schema: $ref: '#/definitions/RequestBundle' responses: "200": description: Success schema: $ref: '#/definitions/BundleTransferResponse' "400": description: Bad Request schema: $ref: '#/definitions/Error' "401": description: Unauthorized schema: $ref: '#/definitions/Error' "403": description: Forbidden schema: $ref: '#/definitions/Error' "404": description: Not Found schema: $ref: '#/definitions/Error' "405": description: Method No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' definitions: RequestBundle: type: object required: - receiverMsisdn - type properties: receiverMsisdn: type: string example: "2349062058463" description: The Beneficiary subscriber msisdn. The format must be E.123 type: type: string example: airtime description: "Specify the type of bundle to shared" enum: - airtime - data - SME_DATA targetSystem: type: string example: CIS description: "Specify the backend system meant to fulfil the service" enum: - CIS agentId: type: string example: "JOLLYBAN" description: The unique identification for the agent (Mandatory only if the "type" passed is "airtime") pin: type: string example: "1234" description: This is unique per user’s MSISDN as required by the backend (CIS) to be able to successfully debit the senders’MSISDN (Mandatory only if the "type" passed is "airtime") productCode: type: string example: "ME2U_NG_Data2Share_711" description: The product code, which already has a predefined data volume and chargeable amount in the Charging system. (Mandatory only if the "type" passed is "data") transferAmount: type: string example: 100 description: The amount of the airtime to be transferred (Mandatory only if the "type" passed is "airtime") callbackUrl: type: string example: 'https://#' description: >- Airtime transfer request type requires consent validation, Hence, the need for a callback url where the response can be posted to. transactionId: type: string example: 1232412421412 description: Unique ID identifying the transaction currency: type: string example: GHC description: Currency of country BundleTransferResponseData: type: object description: "The impacted system success response" properties: valueCharged: type: integer example: 90 description: "Value Charged" unit: type: string example: NGN description: "Unit of the charged value" enum: - NGN - MB - GB productName: type: string description: "Name of the product" example: "Share 100MB" productId: type: integer description: "Product Identifier" example: "5" productType: type: string description: "Product Type" example: "Data2Share" notification: type: string example: "You have successfully transferred 100MB Data to 2349062058463." BundleTransferResponse: type: object properties: statusCode: type: string description: "This is the MADAPI Canonical response Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system response are mapped to specific canonical response codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'" statusMessage: type: string example: "Success" transactionId: type: string description: "API generated Id to include for tracing requests" data: $ref: '#/definitions/BundleTransferResponseData' _link: type: object properties: self: type: object properties: href: type: string example: "https://api.mtn.com/v1/transfer/customers/2348064816493" Error: type: object required: - "statusCode" - "statusMessage" properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '1000' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client supportMessage: type: string description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful) transactionId: type: string description: API generated Id to include for tracing requests timestamp: type: string format: date-time description: Timestamp of the error example: "2019-08-23T07:29:25.593+0000" _links: type: object properties: self: type: object properties: href: type: string example: "https://api.mtn.com/v1/"