swagger: '2.0'
info:
  description: |-
    To facilitate the capability for consumers to make a payment or refund to service providers.
  version: v1.0
  title: Payments V1
  contact:
    name: MADAPI Development Team
    url: 'https://developers.mtn.com/contact'
    email: developer-support@mtn.com
schemes:
  - https
host: api.mtn.com
basePath: /v1
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: 'https://api.mtn.com/v1/oauth/access_token'
security:
  - OAuth2: []
tags:
  - name: Retrieve Payment Status
  - name: Submit Payment or Refund Request
paths:
  /payments:
    post:
      tags:
        - Submit Payment or Refund Request
      summary: Provides the ability for a consumer to make a payment or refund to service providers.
      description: Provides the ability for a consumer to make a payment or refund to service providers.
      operationId: createPayment
      parameters:
        - name: paymentRequest
          in: body
          description: Payment that is created.
          required: true
          schema:
            $ref: '#/definitions/PaymentRequest'
        - name: X-Authorization
          in: header
          description: Encrypted ECW credentials
          required: false
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/PaymentResponse'
          headers:
            transactionId:
              type: string
              description: Payment TransactionId as generated by MADAPI
          x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        '201':
          description: Successful payment generated.
          schema:
            $ref: '#/definitions/PaymentResponse'
          headers:
            Location:
              type: string
              description: Location header will include the link to the newly created payment.
        '204':
          description: Success
          schema:
            $ref: '#/definitions/PaymentResponse'
        '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'
  '/payments/{correlatorId}/transactionStatus':
    get:
      tags:
        - Retrieve Payment Status
      summary: Provides the status of a Payment Transaction to service providers.
      description: Provides the status of a Payment Transaction to service providers.
      operationId: getPaymentTransactionStatus
      parameters:
        - name: correlatorId
          in: path
          description: Unique identifier in the client for the payment in case it is needed to correlate.
          type: string
          x-example: c5f80cb8-dc8b-11ea-87d0-0242ac130003
          required: true
        - name: transactionId
          in: header
          description: Client generated Id to include for tracing requests.
          type: string
          x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        - name: X-Authorization
          in: header
          description: Encrypted ECW credentials
          required: false
          type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/PaymentTransactionStatusResponse'
        '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:
  PaymentRequest:
    description: Payment Request details.
    type: object
    properties:
      correlatorId:
        type: string
        description: Unique identifier in the client for the payment in case it is needed to correlate.
        example: c5f80cb8-dc8b-11ea-87d0-0242ac130003
      paymentDate:
        type: string
        format: date-time
        description: Date when the payment was performed.
        example: '2020-08-12T11:04:53.668Z'
      name:
        type: string
        description: Screen name of the payment.
        example: Manual Boost for RWC
      callingSystem:
        $ref: '#/definitions/CallingSystemEnum'
      transactionType:
        $ref: '#/definitions/TransactionTypeEnum'
      targetSystem:
        $ref: '#/definitions/TargetSystemEnum'
      callbackURL:
        type: string
        description: The callback URL.
        example: 'https://myCallBack/url'
      quoteId:
        type: string
        description: The ID of the quote used.
        example: '9223372036854775807'
      channel:
        type: string
        description: The channel used to perform the payment operation or just the channel itself with just its name.
        example: AYO
      description:
        type: string
        description: Text describing the contents of the payment.
        example: Manual Boost for RW
      authorizationCode:
        type: string
        description: Authorization code retrieved from an external payment gateway that could be used for conciliation.
        example: xxxxxxxxxxxxxxxxx
      amount:
        $ref: '#/definitions/MoneyType'
      taxAmount:
        $ref: '#/definitions/MoneyType'
      totalAmount:
        $ref: '#/definitions/MoneyType'
      payer:
        $ref: '#/definitions/Payer'
      payee:
        type: array
        items:
          $ref: '#/definitions/Payee'
      paymentMethod:
        $ref: '#/definitions/PaymentMethod'
      status:
        type: string
        description: Status of the payment method.
        example: Pending
      statusDate:
        type: string
        format: date-time
        description: Time the status of the payment method changed.
        example: '2020-08-12T11:04:53.668Z'
      additionalInformation:
        type: array
        items:
          $ref: '#/definitions/AdditionalInformation'
    required:
      - totalAmount
      - paymentMethod
      - correlatorId
      - transactionType
      - countryCode
      - callbackURL
  MoneyType:
    description: Representation of monetary value.
    type: object
    properties:
      amount:
        format: decimal
        type: number
        description: Amount of money
        example: 50
      units:
        type: string
        description: Currency
        example: XOF
    required:
      - amount
      - units
  Payer:
    description: The individual that performs the payment.
    type: object    
    properties:
      payerIdType:
        type: string
        description: Identifier Type of the Payer.
        example: MSISDN
      payerId:
        type: string
        description: The Payer identifier.
        example: '233364654737'
      payerNote:
        type: string
        description: A descriptive note for sender transaction history.
        example: Manual Boost for RWC
    required:
      - payerId
  Payee:
    description: 'A payment can be made in the context of an order, a recharge, for ongoing bills, for administrative fee (e.g. re-sending a paper copy of a bill), damaged device penalty, and more.'
    type: object      
    properties:
      amount:
        $ref: '#/definitions/MoneyType'
      taxAmount:
        $ref: '#/definitions/MoneyType'
      totalAmount:
        $ref: '#/definitions/MoneyType'
      payeeIdType:
        type: string
        description: Identifier Type of the Payee.
        example: USER
      payeeId:
        type: string
        description: The Payee identifier.
        example: AYO.DEPOSIT
      payeeNote:
        type: string
        description: A descriptive note for receiver transaction history.
        example: Manual Boost for RWC
    required:
      - totalAmount
      - payerIdType
      - payerId
  AdditionalInformation:
    description: Additional information relating to the payment transaction.
    type: object      
    properties:
      name:
        type: string
        description: Name of additional information item.
        example: BundleName
      description:
        type: string
        description: Description of additional information item.
        example: Voice_1111
    required:
      - name
      - description
  PaymentMethod:
    description: Reference or value of the method used to process the payment.
    type: object      
    properties:
      name:
        type: string
        description: Friendly name assigned to the payment method.
        example: Manual Boost for RWC
      description:
        type: string
        description: Description of the associated payment method.
        example: Manual Boost for RWC
      validFrom:
        type: string
        format: date-time
        description: Period the payment method is valid.
        example: '2021-07-21T17:32:28Z'
      validTo:
        type: string
        format: date-time
        description: Period the payment method is valid.
        example: '2021-07-21T17:32:28Z'
      type:
        $ref: '#/definitions/PaymentMethodTypeEnum'
      details:
        $ref: '#/definitions/PaymentMethodTypeDetails'
    required:
      - type
  PaymentMethodTypeEnum:
    type: string
    title: PaymentMethodTypeEnum
    enum:
      - BankCard
      - TokenizedCard
      - BankAccountDebit
      - BankAccountTransfer
      - Account
      - LoyaltyAccount
      - Bucket
      - Voucher
      - DigitalWallet
      - Airtime
      - Mobile Money
    x-enum-elements:
      - name: BankCard
        description: Use a Bank Card to pay.
      - name: TokenizedCard
        description: Use a Tokenized Card to pay.
      - name: BankAccountDebit
        description: Use a Bank Account Debit to pay.
      - name: BankAccountTransfer
        description: Use a Bank Account Transfer to pay.
      - name: Account
        description: Use a Telco Account to pay.
      - name: LoyaltyAccount
        description: Use a Loyalty Account to pay.
      - name: Bucket
        description: Use a Bucket to pay. Especially used in the Pre-Paid environment.
      - name: Voucher
        description: Use a Vouher to pay.
      - name: DigitalWallet
        description: Use a Digital Wallet to pay.
  TransactionTypeEnum:
    type: string
    title: TransactionTypeEnum
    description: The transaction type that is associated with the payment transaction.
    enum:
      - Payment
      - Debit
      - Transfer
      - Refund
    default: Payment
    example: Debit
  CallingSystemEnum:
    type: string
    title: CallingSystemEnum
    description: The name of the calling system.
    enum:
      - ECW
      - AYO
      - POS
  TargetSystemEnum:
    type: string
    title: TargetSystemEnum
    description: The name of the target system.
    enum:
      - ECW
      - AYO
      - EWP
      - OCC
      - CPG
  LoyaltyBalances:
    type: object
    description: Contains all the loyalty balances associated with a customer.
    properties:
      generatedAmount:
        $ref: '#/definitions/MoneyType'
      consumedAmount:
        $ref: '#/definitions/MoneyType'
      newBalance:
        $ref: '#/definitions/MoneyType'
  PaymentMethodTypeDetails:
    description: Definition of the payment method. Its content depends on the type field.
    type: object      
    properties:
      bankCard:
        $ref: '#/definitions/BankCard'
      tokenizedCard:
        $ref: '#/definitions/TokenizedCard'
      bankAccountDebit:
        $ref: '#/definitions/BankAccountDebit'
      bankAccountTransfer:
        $ref: '#/definitions/BankAccountTransfer'
      account:
        $ref: '#/definitions/Account'
      loyaltyAccount:
        $ref: '#/definitions/LoyaltyAccount'
      bucket:
        $ref: '#/definitions/Bucket'
      voucher:
        $ref: '#/definitions/Voucher'
      digitalWallet:
        $ref: '#/definitions/DigitalWallet'
  BankCard:
    description: Detailed information for a bank card.
    type: object      
    properties:
      brand:
        type: string
        description: 'Card brand. e.g. Visa, MasterCard, AmericanExpress.'
        example: Visa
      type:
        type: string
        description: 'Type of card. e.g. Credit, Debit.'
        example: Credit
      cardNumber:
        type: string
        description: Credit card number.
        example: xxxx xxxx xxx xxx
      expirationDate:
        type: string
        format: date-time
        description: Expiration date of the card.
        example: '2021-07-21T17:32:28Z'
      cvv:
        type: string
        description: 'Security Code of the card. e.g. CCV, CCV2.'
        example: '123'
      lastFourDigits:
        type: string
        description: Last four digits of the credit card.
        example: '1234'
      nameOnCard:
        type: string
        description: Name on the card.
        example: Bruce Wayne
      bank:
        type: string
        description: Bank that issued the card.
        example: Bank of Gotham
      pin:
        type: string
        description: Customer pin created when tokenizing the card
        example: '123'
  TokenizedCard:
    description: Detailed information for a stored tokenized card.
    type: object      
    properties:
      brand:
        type: string
        description: Card brand. Might be used for display purposes.
      type:
        type: string
        description: Card type. Might be used for display purposes.
      lastFourDigits:
        type: string
        description: Last four digits of the credit card. Might be used for display purposes.
      tokenType:
        type: string
        description: Token type. e.g emv.
      token:
        type: string
        description: The token itself.
      issuer:
        type: string
        description: Whoever issued the token.
  BankAccountDebit:
    description: Detailed information for a bank account debit.
    type: object      
    properties:
      accountNumber:
        type: string
        description: Bank Account Number (this could refer to the IBAN or SWIFT number).
      accountNumberType:
        type: string
        description: 'Type of account number. e.g. IBAN, SWIFT.'
      BIC:
        type: string
        description: Business Identifier Code/Swift code of the financial institution where the account is located.
      owner:
        type: string
        description: Owner of the bank account.
      bank:
        type: string
        description: Display nam of the bank.
  BankAccountTransfer:
    description: Detailed information for a bank account transfer.
    type: object      
    properties:
      accountNumber:
        type: string
        description: Bank Account Number (this could refer to the IBAN or SWIFT number).
      accountNumberType:
        type: string
        description: 'Type of account number. e.g. IBAN, SWIFT.'
      BIC:
        type: string
        description: Business Identifier Code/Swift code of the financial institution where the account is located.
      owner:
        type: string
        description: Owner of the bank account.
      bank:
        type: string
        description: Display nam of the bank.
  Account:
    description: Detailed information for a Telco Account.
    type: object      
    properties:
      id:
        type: string
        description: Unique identifier of the account.
      name:
        type: string
        description: Entity name.
      description:
        type: string
        description: Description of the associated account.
  LoyaltyAccount:
    description: Detailed information for a loyalty system that could be used to perform the payment..
    type: object      
    properties:
      id:
        type: string
        description: Unique identifier of the loyalty account.
      name:
        type: string
        description: Entity name.
      description:
        type: string
        description: Description of the associated loyalty account.
  Bucket:
    description: 'Detailed information for a bucket that could be used to perform the payment, especially in the pre-paid environment.'
    type: object      
    properties:
      id:
        type: string
        description: Unique identifier of the bucket.
      name:
        type: string
        description: Entity name.
      description:
        type: string
        description: Description of the associated bucket.
  Voucher:
    description: Detailed information for a voucher.
    type: object      
    properties:
      code:
        type: string
        description: Code that identifies the voucher.
      description:
        type: string
        description: 'Description of the voucher. i,e, Get one and receive one free.'
      value:
        type: string
        description: Discount that the voucher applies when its a discount voucher.
      expirationDate:
        type: string
        format: date-time
        description: The vouchers expiration date.
      campaign:
        type: string
        description: Campaign this voucher belongs to.
  DigitalWallet:
    description: Detailed information for a Digital Wallet.
    type: object      
    properties:
      service:
        type: string
        description: 'Organization, platform or currency backing the wallet. e.g. MoMo, PayPal, Yandex, BitCoin.'
        example: MoMo
      walletId:
        type: string
        description: Account identifier in that service.
        example: '233364654737'
      walletUri:
        type: string
        description: URI pointing at the digital wallet.
        example: 'https://paypal.me/johndoe'
  PaymentResponse:
    type: object
    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. 0000 is for a success. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
        example: '0000'
      providerTransactionId:
        type: string
        example: FT172145YB21
        description: 'ID of the payment, generated by back-end system. This can be blank if the payment has previously been pre-approved.'
      data:
        $ref: '#/definitions/Data'
      _links:
        $ref: '#/definitions/PaymentResponse__Links'
  PaymentResponse__Links_Self:
    type: object
    properties:
      href:
        type: string
        example: 'https://host:port/payments/v1/12345'
        description: Hyperlink to access the financial payment.
  PaymentResponse__Links:
    type: object
    properties:
      self:
        $ref: '#/definitions/PaymentResponse__Links_Self'
    description: Relevant links to the financial payment.
  Data:
    type: object
    properties:
      approvalId:
        type: string
        description: Unique identifier in the client for the payment in case it is needed to correlate. Generated by back-end system. This can be blank if the payment has previously been pre-approved.
      transactionFee:
        $ref: '#/definitions/MoneyType'
      discount:
        $ref: '#/definitions/MoneyType'
      newBalance:
        $ref: '#/definitions/MoneyType'
      payerNote:
        type: string
        description: A descriptive note for sender transaction history.
        example: Manual Boost for RWC
      status:
        type: string
        description: Status of the payment method.
        example: Approved
      statusDate:
        type: string
        description: Time the status of the payment changed.
        example: '2020-08-12T11:04:53.668Z'
      additionalInformation:
        $ref: '#/definitions/AdditionalInformation'
      loyaltyInformation:
        $ref: '#/definitions/LoyaltyBalances'
  PaymentTransactionStatusData:
    type: object
    properties:
      financialTransactionId:
        type: string
        description: The financial transaction ID. Generated by the back-end system.
      status:
        type: string
        description: Payment Status.
        example: Approved
  PaymentTransactionStatusResponse:
    type: object
    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. 0000 is for a success. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'
        example: '0000'
      providerTransactionId:
        type: string
        example: FT172145YB21
        description: 'ID of the payment, generated by back-end system. This can be blank if the payment has previously been pre-approved.'
      data:
        $ref: '#/definitions/PaymentTransactionStatusData'
      _links:
        $ref: '#/definitions/PaymentTransactionStatusResponse__Links'
  PaymentTransactionStatusResponse__Links_Self:
    type: object
    properties:
      href:
        type: string
        example: 'https://host:port/payments/v1/12345'
        description: Hyperlink to access the financial payment transaction status.
  PaymentTransactionStatusResponse__Links:
    type: object
    properties:
      self:
        $ref: '#/definitions/PaymentTransactionStatusResponse__Links_Self'
    description: Relevant links to the financial payment transaction status.
  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: This is the same transactionId that is sent in the request
        example: cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4
      timestamp:
        type: string
        format: date-time
        description: Timestamp that the error occurred
        example: '2021-07-21T17:32:28Z'
      path:
        type: string
        description: The path that caused the error
        example: /subscribers/27831234567
      method:
        type: string
        description: The HTTP method type that was used
        example: GET