Mastercard Community Pass Payment APIs

openapi: 3.0.3
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.
- name: Notifications
  description: >-
    This API is to be used by the payment provider to notify a payment status
    to relevant Mastercard Applications in case the payment was initiated from
    an Application external to Mastercard.
- name: Validations
  description: >-
    This API is to be used to validate customer information present within
    relevant Mastercard Applications.
info:
  description: >-
    A secure way to validate customer information and notify Community Pass
    applications on payment status
  version: 1.0.7
  title: Mastercard Community Pass Payment APIs
  contact:
    name: API Support
    email: [email protected]
    url: https://developer.mastercard.com/support
servers:
- url: https://api.mastercard.com/community-pass/payments
  description: Production Environment
- url: https://sandbox.api.mastercard.com/community-pass/payments
  description: Sandbox Environment
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
  /validations:
    post:
      tags:
      - Validations
      summary: Mastercard Validations Api
      description: >-
        This API is to be used to validate customer information present within
        relevant Mastercard Applications.
      operationId: Validation
      requestBody:
        $ref: '#/components/requestBodies/ValidationRequest'
      responses:
        '200':
          $ref: '#/components/responses/PaymentValidationStatus'
        '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
  /notifications:
    post:
      tags:
      - Notifications
      summary: Mastercard Notifications Api
      description: >-
        This API is to be used by the payment provider to notify a payment
        status to relevant Mastercard Applications in case the payment was
        initiated from an Application external to Mastercard.
      operationId: paymentNotification
      requestBody:
        $ref: '#/components/requestBodies/NotificationRequest'
      responses:
        '200':
          $ref: '#/components/responses/NotificationSuccess'
        '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:
  requestBodies:
    CallbackRequest:
      description: Callback Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Callback'
    NotificationRequest:
      description: Notification Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Notification'
    ValidationRequest:
      description: Validation Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Validation'
  schemas:
    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'
    Errors:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
      description: Errors list
      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
    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
    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
    Validation:
      type: object
      properties:
        appId:
          type: string
          description: Application identifier for client.
          enum:
          - MFN
          - KUPAA
          example: MFN
          minLength: 3
          maxLength: 15
        partnerId:
          type: string
          description: 'Code to identify partner. E,g: school on Kupaa.'
          example: '12345'
          minLength: 5
          maxLength: 30
        accountId:
          type: string
          minLength: 1
          maxLength: 60
          description: 'Account Number being validated. E.g: student id.'
          example: '25471234567'
        partnerType:
          type: string
          minLength: 1
          maxLength: 50
          description: Partner type can be one of values in enum.
          enum:
          - SCHOOL
          - BUYER
          - CHANNEL
          - SUPPLIER
          example: SCHOOL
        correlationId:
          type: string
          format: uuid
          description: Correlation Id for tracking request
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        transactionTime:
          type: string
          minLength: 0
          maxLength: 50
          example: '2020-07-16T19:20:30+01:00'
          description: Transaction time in the format 'YYYY-MM-DDThh:mm:ssTZD'
        paymentChannel:
          type: string
          minLength: 1
          maxLength: 50
          description: Depicts mode of payment as mentioned in enum.
          enum:
          - MOBILE
          - BANK
          example: MOBILE
      title: Validation
      description: Validation Request
    PaymentValidationStatus:
      type: object
      properties:
        accountId:
          type: string
          minLength: 1
          maxLength: 50
          example: '25471234567'
          description: Account Id
        accountName:
          type: string
          minLength: 1
          maxLength: 250
          example: Student Name
          description: Account Name
        additionalInfo:
          $ref: '#/components/schemas/AdditionalInfo'
      title: ValidationStatus
      description: Validation Response
    AdditionalInfo:
      type: object
      properties:
        balance:
          type: string
          minLength: 0
          maxLength: 50
          example: 1500
          description: Balance of requested account
        currency:
          type: string
          example: USA
          minLength: 3
          maxLength: 10
          description: Currency
      title: AdditionalInfo
      description: AdditionalInfo Response
      example:
        $ref: '#/components/examples/AdditionalInfoExample'
    Notification:
      type: object
      properties:
        appId:
          type: string
          description: Application identifier for client.
          enum:
          - MFN
          - KUPAA
          example: MFN
          minLength: 3
          maxLength: 15
        partnerId:
          type: string
          minLength: 0
          maxLength: 50
          description: 'Code to identify partner. Eg: school on Kupaa'
          example: '1234'
        providerReference:
          type: string
          description: Unique transaction ID from Payment Provider
          example: ABC123
          minLength: 5
          maxLength: 50
        srcAccount:
          type: string
          description: Payer mobile bank account number
          example: '25471234567'
          minLength: 5
          maxLength: 30
        paymentChannel:
          type: string
          minLength: 1
          maxLength: 30
          description: Depicts mode of payment as mentioned in enum.
          enum:
          - MOBILE
          - BANK
          example: MOBILE
        transactionAmount:
          type: number
          format: double
          description: Transaction amount
          example: 12567.89
        accountId:
          type: string
          minLength: 1
          maxLength: 30
          example: '1234'
          description: Payer's account id
        transactionDate:
          type: string
          minLength: 0
          maxLength: 30
          example: '2020-07-15'
          description: Transaction date in the format 'YYYY-MM-DD'
        narration:
          type: string
          minLength: 0
          maxLength: 500
          description: Description of payment
          example: Payment for XYZ
        accountName:
          type: string
          minLength: 0
          maxLength: 100
          example: Payer Name
          description: Payer Name
        accountNumber:
          type: string
          minLength: 1
          maxLength: 30
          example: '25471234589'
          description: Destination account number
        currency:
          type: string
          example: UGX
          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.
        signature:
          type: string
          minLength: 0
          maxLength: 500
          description: Signature for request
          example: Signature for request
        correlationId:
          type: string
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
          description: CorrelationId for request
      title: Notification
      description: notification request
  responses:
    PaymentValidationStatus:
      description: Payment validations request executed successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentValidationStatus'
          examples:
            PaymentValidationStatusExample:
              $ref: '#/components/examples/PaymentValidationStatusExample'
    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'
    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'
    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'
    InvalidAuthHeaderError:
      description: Bad Request - No Authorization header set
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            InvalidAuthHeaderExample:
              $ref: '#/components/examples/InvalidAuthHeaderExample'
    CallbackSuccess:
      description: Payment callback request executed successfully.
    NotificationSuccess:
      description: Payment notification request executed successfully.
  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
    InvalidKeyExample:
      value:
        Errors:
          Error:
          - Source: PAYMENT_SERVIC
            ReasonCode: INVALID_KEY
            Description: Signing certificate must be valid
            Recoverable: false
            Details: 'null'
    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
    PaymentValidationStatusExample:
      value:
        accountId: 25471234567
        accountName: Student Name
        additionalInfo:
          balance: 1500
          currency: UGX
    AdditionalInfoExample:
      value:
        balance: 1500
        currency: UGX
    RecipientExample:
      value:
        clientId: '8387484747'
        transactionId: '7253653653'
        accountName: Test User
        accountNumber: '1234567890'
        transactionAmount: 1500
        currency: USD
        countryCode: USA
        responseCode: '100'
        responseMessage: successful