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
        - name: amount
          type: number
          in: query
        - name: targetSystem
          type: string
          in: query
          description: target system expected to fulful the service
          enum: [EWP, ECW, CELD]
        - name: paymentType
          type: string
          in: query
          description: Type of the transaction
          enum: [Airtime]
        - name: customerId
          type: string
          in: query
          description: This is the payer mobile number
        - name: description
          in: query
          type: string
          description: Payer note
      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'

  /payments/payment-link:
    post:
      tags:
        - Generate a payment link for account payment
      summary: Provides the ability for a consumer to generate a payment link for account payment
      description: Provides the ability for a consumer to get the payment link for the requesting MSISDN so as to enable the customer to make payment to the service providers.
      operationId: generatePaymentLink
      parameters:
        - name: orderRequest
          in: body
          description: Order details for the payment link that is to be created.
          required: true
          schema:
            $ref: '#/definitions/OrderRequest'
        - name: transactionId
          in: header
          description: Client generated Id to include for tracing requests.
          type: string
          x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
          required: false

      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/OrderResponse'
        '201':
          description: Success
          schema:
            $ref: '#/definitions/OrderResponse'
        '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/payment-agreement:
    post:
      tags:
        - Generate a payment agreement
      summary: Provides the ability for a consumer to generate a payment agreement (Promise to Pay)
      description: Provides the ability for a consumer to generate a payment agreement (Promise to Pay) so as to enable the customer to make payment to the service providers.
      operationId: generatePaymentAgreement
      parameters:
        - name: promiseToPayRequest
          in: body
          description: Agreement details for the payment promise that is to be created.
          required: true
          schema:
            $ref: '#/definitions/promiseToPayRequest'
        - name: transactionId
          in: header
          description: Client generated Id to include for tracing requests.
          type: string
          x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
          required: false

      responses:
        '201':
          description: Success
          schema:
            $ref: '#/definitions/promiseToPayResponse'
        '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

  OrderRequest:
    description: Order Request details.
    allOf:
      - required:
          - channel
          - quoteId
          - description
          - authenticationType
          - deliveryMethod
          - payer
          - totalAmount
          - itemDetails
    type: object
    properties:
      channel:
        type: "string"
        description: "Source system (Channel) identifier"
        example: 'Facebook'
      quoteId:
        type: string
        description: The ID of the quote used.
        example: '9223372036854775807'
      description:
        type: string
        description: Text describing the contents of the payment.
        example: Manual Boost for RW
      authenticationType :
        type : string
        description : This field will have the authentication type that the channel prefers to have for making a payment. Pass it as "Query Payment" incase if you don't need any back update notification about payment. Possible values are [Query Payment, Inline Auth, Notification]
        example: 'Query Payment'
      deliveryMethod :
        type : string
        description : Method through which link need to be shared. In case of "SMS" URL is sent via SMS. In case of "Paylink" URL will be sent part of response. Possible values are [SMS, Payweb, Email, Paylink]
        example : 'Paylink'
      payer:
        $ref: '#/definitions/Payer'
      totalAmount:
        $ref: '#/definitions/MoneyType'
      itemDetails :
        type : array
        description : ''
        items :
          type : object
          allOf:
            - required:
                - itemName
                - itemDescription
                - itemValue
                - currency
                - quantity
          properties:
            itemName :
              type : string
              description : Name of the item placed by the customer. Possible values are [ITEM_PURCHASE, ACCOUNT_PAYMENT]
              example: 'ACCOUNT_PAYMENT'
            itemDescription :
              type : string
              description : Description of the item placed by the customer
            itemValue :
              type : string
              description : This field will have the amount of the item
              example: 200
            currency :
              type : string
              description : This field will have the uom for the itemValue
              example: ZAR
            quantity :
              type : integer
              description : This field will have number of items placed by the customer
              example: '1'

  OrderResponse:
    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'
      statusMessage:
        type: string
        description: Message of the transaction. Either Success or Failure.
      transactionId:
        type: string
        description: Unique identifier for every request to the backend. Mapped from input request.
        example: 5345345
      data:
        $ref: '#/definitions/DataOrder'
      _links:
        $ref: '#/definitions/OrderResponse__Links'

  OrderResponse__Links:
    type: object
    properties:
      self:
        $ref: '#/definitions/OrderResponse__Links_Self'

  OrderResponse__Links_Self:
    type: object
    properties:
      href:
        type: string
        example: 'https://host:port/payments/payment-link/'
        description: Hyperlink to access the payment link generation endpoint.

  DataOrder:
    type: object
    properties:
      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.'
      orderRedirectUrl:
        type: string
        description: This will have the encrypted url that will be route to pay portal on click.

  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
      payerName:
        type: string
        description: Name of the payer
      payerRef:
        type: string
        description: A reference to the payer
        example: "233364654737"
      payerSurname:
        type: string
        description: Surname of the payer
        example: "Orimoloye"
    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
      payeeName:
        type: string
        description: Name of the payee
    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
      - Invoice
    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.
      - name: Invoice
        description: Create an invoice or pay to an already scheduled invoice
  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
      - CELD
  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'
      invoice:
        $ref: '#/definitions/InvoiceMethod'

  InvoiceMethod:
    description: Detailed information for an invoice
    type: object
    properties:
      id:
        type: string
        description: This is the Id of the invoice
        example: 86rer4478878t991
      type:
        type: string
        description: Type of the invoice being paid for
        example: trigger
      frequency:
        type: string
        description: This is the frequency of a reccuring transaction
        enum:
          - 'on_call'
          - 'once'
          - 'hourly'
          - 'daily'
          - 'weekly'
          - 'every_[1-366]d'
      startDate:
        type: string
        description: This is the start date of a reccuring transaction
        example: '2021-03-20'
      endDate:
        type: string
        description: This is the end date of a reccuring transaction
        example: '2021-09-20'
      retryOnFail:
        type: boolean
        description: A boolean to showing if the transaction should be retried on fail or not.
        example: true
      deactivateOnFail:
        type: string
        description: A boolean to showing if the transaction should be deactivated on fail or not.
        example: true
      callbackUrl:
        type: string
        description: The url to be invoked for callbacks
        example: 'https://merchant-application-url/webhook-endpoint'
      retryRun:
        type: string
        description: This is the retry run
        example: 1-5
      retryFrequency:
        type: string
        description: The retry frequencies
        enum:
          - 'once'
          - 'hourly'
          - 'daily'



  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.'
      statusMessage:
        type: string
        description: 'A description of the transaction status.'
      supportMessage:
        type: string
        description: 'A description used for error handling'
      fulfillmentStatus:
        type: string
        description: 'A description of the transaction fulfillment status.'
        enum:
          - 'Succesful'
          - 'Failed'
          - 'Null'

      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
      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
      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'
      externalCode:
        type: string
        description: This is the external reference code. This can be the bank institution code for the NIMBS payments usecases

  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
      requestType:
        type: string
        description: Request Type.
      fulfillmentStatus:
        type: string
        description: The financial transaction fullfilment status.
      transactionRefParent:
        type: string
        description: The financial transaction reference parent.
      transactionDescription:
        type: string
        description: The financial transaction description.
      amount:
        type: number
        description: The financial transactional amount.
        example: 3453.45
      customer:
        $ref: '#/definitions/CustomerObject'

  CustomerObject:
    type: object
    properties:
      firstname:
        type: string
        description: Customer First Name.
        example: John
      surname:
        type: string
        description: Customer surname.
        example: Doe
      email:
        type: string
        description: Customer email.
        example: johndoe@email.com
      msisdn:
        type: string
        description: Customer Mobile number.
        example: '263897646890'

  AdditionalInfoObject:
    type: object
    properties:
      name:
        type: string
        description: Product Name.
        example: Product A
      description:
        type: string
        description: Product Identifier.
        example: Prod_2349

  DetailsObject:
    type: object
    properties:
      brand:
        type: string
        description: Telco Code.
        example: AB233
      fulfillmentMsisdn:
        type: string
        description: Fulfillment Msisdn.
        example: '263897646890'
      issuer:
        type: string
        description: Source of funds scheme.
        example: 'VISA'

  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'
      statusMessage:
        type: string
        description: 'This is a description of the status'
      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'
      additionalInformation:
        $ref: '#/definitions/AdditionalInfoObject'
      details:
        $ref: '#/definitions/DetailsObject'
      _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.

  promiseToPayRequest:
    description: Payment Request details.
    type: object
    properties:
      billingAccountNo:
        type: string
        description: Unique Billing Account number of the customer
        example: 903442299RC
      serviceName:
        type: string
        description: Service name of the payment.
        example: Outstanding Dues
      promiseOpenDate:
        type: string
        format: date-time
        description: Start Date of the Promise.
        example: '2020-08-12T11:04:53.668Z'
      promiseAmount:
        type: number
        format: double
        description: Amount promised to be paid.
        example: 1290.00
      numberOfInstallments:
        type: string
        description: Number of the EMI.
        example: 3
      durationUOM:
        type: string
        description: Unit of Measure for the EMI (can be Month, Week and Year).
        example: 'Month'
      promiseThreshold:
        type: string
        description: The Promise Threshold
        example: 100

  promiseToPayResponse:
    description: Promise details response
    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'
      statusMessage:
        type: string
        description: Message of the transaction. Either Success or Failure.
      transactionId:
        type: string
        description: Unique identifier for every request to the backend. Mapped from input request. 
        example: 5345345
      data:
        type: object
        properties:
          PromiseDetails:
            type: array
            items:
              $ref: '#/definitions/PromiseDetail'
      _links:
        $ref: '#/definitions/Response_Links'
        
  Response_Links:
    type: object
    properties:
      self:
        $ref: '#/definitions/Response_Links_Self'
  
  Response_Links_Self:   
    type: object
    properties:
      href:
        type: string
        example: 'https://host:port/payments/payment-agreement/'
        description: Hyperlink to access the payment agreement generation endpoint.
        
  PromiseDetail:
    type: object
    properties:
      installmentDueAmount:
        type: string
        example: 266.67
        description: Installment Amount Due to be paid
      installmentEndDate:
        type: string
        format: date-time
        description: End date of Installment
        example: '2020-08-12T11:04:53.668Z'
      queryNumber:
        type: string
        example: FT172145YB21
        description: Query Number in SV
      installmentStartDate:
        type: string
        format: date-time
        description: Start Date of Installment
        example: '2020-08-12T11:04:53.668Z'

  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