swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Callbacks API
  description: This service is provided on behalf of the Mastercard Remote Payment and Presentment (RPPS) Bill Payment Processing Network, which supports consumer to business "push" bill payments (i.e. those which are not funded by debit/credit card transactions) in the U.S.
  version: '1.0'
  x-artifactId: billpay-api
  contact:
    name: Bill Pay Development Support
    email: Bill_Pay_Development_Support@mastercard.com
host: sandbox.api.mastercard.com
basePath: /billpayAPI/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Callbacks
  description: This API is to be used by the payment provider to notify payment status to relevant Mastercard Applications in case the payment was initiated by the Mastercard Application.
paths:
  /callbacks:
    post:
      tags:
      - Callbacks
      summary: Mastercard Callbacks Api
      description: This API is to be used by the payment provider to notify payment status to relevant Mastercard Applications in case the payment was initiated by the Mastercard Application.
      operationId: Callback
      requestBody:
        $ref: '#/components/requestBodies/CallbackRequest'
      responses:
        '200':
          $ref: '#/components/responses/CallbackSuccess'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/InvalidAuthHeaderError'
        '403':
          $ref: '#/components/responses/InvalidKeyError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Errors:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
      description: Errors list
      example:
        $ref: '#/components/examples/BadRequestExample'
    Callback:
      type: object
      properties:
        appId:
          type: string
          description: Application identifier for client.
          enum:
          - MFN
          - KUPAA
          example: MFN
          minLength: 3
          maxLength: 15
        partnerAccountId:
          type: string
          description: An id provided by the payment provider to identify the source account.
          example: '12345678'
          minLength: 5
          maxLength: 30
        transactionReference:
          type: string
          description: Transaction reference generated by client as mentioned in enum.
          example: b808add0-5b1b-447c-9341-83e32a83856e
          minLength: 5
          maxLength: 50
        providerReference:
          type: string
          description: Provider reference generated by provider.
          example: pro-1233763
          minLength: 5
          maxLength: 50
        status:
          type: string
          minLength: 1
          maxLength: 50
          description: 'Status can be between the values mentioned in enum '
          enum:
          - PROCESSING
          - OK
          - ERROR
          - UNKNOWN
          - INDETERMINATE
          - INSUFFICIENT_FUNDS
          example: PROCESSING
        confirmationUrl:
          type: string
          minLength: 1
          maxLength: 500
          description: Confirmation url sent from payment provider
          example: https://yo/confirmation-url
        responseCode:
          type: string
          minLength: 1
          maxLength: 50
          example: '100'
          description: Response Code
        responseMessage:
          type: string
          minLength: 1
          maxLength: 500
          example: Successful
          description: Response Message
        correlationId:
          type: string
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          description: correlationId for request
        apiAction:
          type: string
          minLength: 1
          maxLength: 50
          description: Type of Action/Transaction to be taken for the particular request.Value should be from.
          enum:
          - B2C
          - C2B
          - MIN
          - BAL
          - BB2C
          - BTRQ
          example: B2C
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
          example:
          - clientId: '88784744'
            transactionId: '7253653653'
            accountName: Test Account
            accountNumber: '1234567890'
            transactionAmount: 150
            currency: UGX
            countryCode: UG
            responseCode: '100'
            responseMessage: Successful
      title: Callback
      description: Callback Request
    ErrorWrapper:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          properties:
            Error:
              $ref: '#/components/schemas/Errors'
          description: Error object
          example:
            $ref: '#/components/examples/BadRequestExample'
    Error:
      type: object
      properties:
        Source:
          type: string
          minLength: 1
          maxLength: 50
          description: An element used to indicate the source of the issue causing this error.
          example: PAYMENT_SERVICE
        ReasonCode:
          type: string
          minLength: 1
          maxLength: 50
          description: A reason code for the error that has occurred.
          example: BAD_REQUEST
        Description:
          type: string
          minLength: 1
          maxLength: 500
          description: Description of the reason the operation failed.
          example: We couldn't handle your request
        Recoverable:
          type: boolean
          description: Generated by the gateway to indicate if the request could presented again for processing. Either "true" or "false".
          example: true
        Details:
          type: string
          minLength: 1
          maxLength: 500
          description: Identifies the description of the error.
          example: appId should be either MFN or Kupaa
      description: Error Object
    Recipient:
      type: object
      properties:
        clientId:
          type: string
          description: Client id generated for each beneficiary transaction by client application.
          enum:
          - MFN
          - KUPAA
          example: '8387484747'
          minLength: 5
          maxLength: 30
        transactionId:
          type: string
          description: Transcation id generated for each beneficiary transaction by payment provider.
          example: '7253653653'
          minLength: 5
          maxLength: 50
        accountName:
          type: string
          minLength: 1
          maxLength: 60
          example: Test User
          description: Account Name
        accountNumber:
          type: string
          minLength: 1
          maxLength: 30
          example: '1234567890'
          description: Account Number
        transactionAmount:
          type: number
          format: double
          example: 1500
          description: Transaction Amount
        currency:
          type: string
          example: USD
          minLength: 3
          maxLength: 3
          description: Alphabetic code of currency as per ISO4217 standard.
        countryCode:
          type: string
          minLength: 3
          maxLength: 3
          example: USA
          description: ISO 3-alpha country code format.
        responseCode:
          type: string
          minLength: 3
          maxLength: 3
          example: '200'
          description: Reason code
        responseMessage:
          type: string
          minLength: 3
          maxLength: 3
          example: XYZ
          description: Response Message
      title: Recipient
      description: Recipient Request
  responses:
    InvalidKeyError:
      description: Forbidden-You do not have necessary permission to access this resource on this server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            InvalidKeyExample:
              $ref: '#/components/examples/InvalidKeyExample'
    CallbackSuccess:
      description: Payment callback request executed successfully.
    BadRequestError:
      description: Bad Request-The server cannot not process the request due to invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequestExample'
    InvalidAuthHeaderError:
      description: Bad Request - No Authorization header set
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            InvalidAuthHeaderExample:
              $ref: '#/components/examples/InvalidAuthHeaderExample'
    NotFoundError:
      description: Not Found-The requested resource was not found on this server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample'
  examples:
    BadRequestExample:
      value:
        Errors:
          Error:
          - Source: PAYMENT_SERVICE
            ReasonCode: BAD_REQUEST
            Description: We couldn't handle your request
            Recoverable: false
            Details: appId should be either MFN or Kupaa
    NotFoundExample:
      value:
        Errors:
          Error:
          - Source: PAYMENT_SERVICE
            ReasonCode: NOT_FOUND
            Description: You requested something we don't have
            Recoverable: false
            Details: Requested resource doesn't exist
    InvalidAuthHeaderExample:
      value:
        Errors:
          Error:
          - Source: PAYMENT_SERVICE
            ReasonCode: INVALID_AUTH_HEADER
            Description: Bad Request - No Authorization header set
            Recoverable: false
            Details: check if key is passed to call the API
    InvalidKeyExample:
      value:
        Errors:
          Error:
          - Source: PAYMENT_SERVIC
            ReasonCode: INVALID_KEY
            Description: Signing certificate must be valid
            Recoverable: false
            Details: 'null'
  requestBodies:
    CallbackRequest:
      description: Callback Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Callback'