swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Activity 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: Activity
paths:
  /user-account-activity-searches:
    post:
      tags:
      - Activity
      responses:
        '200':
          $ref: '#/components/responses/UserAccountActivitySearchesResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      description: 'Retrieve decrypted user activities and present them to the user in the

        TP app. Does not require a minimum authentication standard.

        **This API is mandatory.**

        '
      summary: View identity lifecycle activities which have occurred in a time period.
      operationId: retrieveUserActivities
      parameters:
      - $ref: '#/components/parameters/XUserIdentityParameter'
      - $ref: '#/components/parameters/XEncryptedPayload'
      requestBody:
        $ref: '#/components/requestBodies/UserAccountActivitySearchRequest'
  /rp-activity-searches:
    post:
      tags:
      - Activity
      responses:
        '200':
          $ref: '#/components/responses/RPActivitySearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      description: 'Retrieve decrypted RP activities and present them to the user in the TP

        app. Does not require a minimum authentication standard.

        **This API is mandatory.**

        '
      summary: View identity claim sharing activities which have occurred in a time period.
      operationId: searchRpActivity
      parameters:
      - $ref: '#/components/parameters/XUserIdentityParameter'
      - $ref: '#/components/parameters/XEncryptedPayload'
      requestBody:
        $ref: '#/components/requestBodies/RPActivitySearchRequest'
components:
  responses:
    UnauthorizedError:
      description: Unauthorized request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    UserAccountActivitySearchesResponse:
      description: Success.
      headers:
        X-Transaction-ID:
          schema:
            type: string
          description: A random 128-bit UUID represents the transaction.
        X-User-Identity:
          schema:
            type: string
          description: JWT token for session validation in subsequent API calls.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserAccountActivities'
          examples:
            UserAccountActivitySearchesUnencryptedResponse:
              $ref: '#/components/examples/UserAccountActivitiesExample'
            UserAccountActivitySearchesEncryptedResponse:
              $ref: '#/components/examples/EncryptedPayloadWithRotatedPDSExample'
    NotFoundError:
      description: The request didn't match an existing resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample'
    RPActivitySearchResponse:
      description: Success.
      headers:
        X-Transaction-ID:
          schema:
            type: string
          description: A random 128-bit UUID represents the transaction.
        X-User-Identity:
          schema:
            type: string
          description: JWT token for session validation in subsequent API calls.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RPActivities'
          examples:
            UnencryptedResponseExample:
              $ref: '#/components/examples/RPActivitiesResponseExample'
            EncryptedResponseExample:
              $ref: '#/components/examples/EncryptedPayloadNoPDSExample'
    ForbiddenError:
      description: Consent not given.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ForbiddenExample:
              $ref: '#/components/examples/ForbiddenExample'
            ForbiddenExampleUnauthorizedScopedFields:
              $ref: '#/components/examples/ForbiddenExampleUnauthorizedScopedFields'
    BadRequestError:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            UserProfileDeletedErrorExample:
              $ref: '#/components/examples/UserProfileDeletedErrorExample'
  schemas:
    RPActivitySearch:
      required:
      - pds
      - startIndex
      - endIndex
      - userConsent
      type: object
      properties:
        pds:
          $ref: '#/components/schemas/PDS'
        startIndex:
          type: integer
          description: Start index of the RP activity.
          format: int32
          minimum: 1
          maximum: 999
          example: 3
        endIndex:
          type: integer
          description: End index of the RP activity.
          format: int32
          minimum: 1
          maximum: 999
          example: 10
        userConsent:
          $ref: '#/components/schemas/UserConsent'
        sdkVersion:
          $ref: '#/components/schemas/SdkVersion'
    UserAccountActivitySearch:
      required:
      - pds
      - startIndex
      - endIndex
      - userConsent
      type: object
      properties:
        pds:
          $ref: '#/components/schemas/PDS'
        startIndex:
          type: integer
          description: Start index of the user account activity.
          format: int32
          minimum: 1
          maximum: 999
          example: 3
        endIndex:
          type: integer
          description: End index of the user account activity.
          format: int32
          minimum: 1
          maximum: 999
          example: 10
        userConsent:
          $ref: '#/components/schemas/UserConsent'
        sdkVersion:
          $ref: '#/components/schemas/SdkVersion'
    RPActivityItems:
      required:
      - rpName
      - consentType
      - createdDate
      - attributesConsented
      type: object
      properties:
        rpName:
          type: string
          description: Relying Party name.
          minLength: 1
          maxLength: 255
          example: Toys inc
        consentType:
          type: string
          description: User consent type.
          minLength: 1
          maxLength: 10
          example: OneTime
        createdDate:
          type: string
          description: Date of the event.
          minLength: 1
          maxLength: 29
          example: '2020-01-28T13:16:01.714-05:00'
        attributesConsented:
          type: object
          description: This is the same data structure that is returned to Relying Party.
          additionalProperties: {}
          example:
            passport.firstName: John
            passport.lastName: Doe
    PDS:
      type: string
      description: Encrypted Personal Device Storage (PDS) which hosts the users identity attributes. The PDS can be retrieved from the MIDS Core SDK, please refer to the SDK guide for details on how to retrieve this.
      pattern: ^(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?$
      minLength: 1
      example: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    UserAccountActivities:
      required:
      - userAccountActivities
      properties:
        userAccountActivities:
          type: array
          description: User account activity items.
          items:
            $ref: '#/components/schemas/UserAccountActivityItems'
        rotatedPds:
          type: string
          description: A rotated PDS is created and returned when the encryption key expires and a new one is generated.
          pattern: ^(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?$
          minLength: 1
          example: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    UserAccountActivityItemContents:
      required:
      - value
      properties:
        attributeName:
          type: string
          description: Name of the updated attribute.
          minLength: 1
          maxLength: 255
          example: legalName
        previousValue:
          type: string
          description: Value before the update.
          minLength: 1
          maxLength: 255
          example: John Doe
        value:
          type: string
          description: Value after the update.
          minLength: 1
          maxLength: 255
          example: John Dow
        source:
          type: string
          description: The source document for the update.
          minLength: 1
          maxLength: 29
          example: passport
    UserAccountActivityItems:
      required:
      - action
      - createdDate
      properties:
        action:
          type: string
          description: Type of the activity, possible values - ["ID Created", "Details Updated", "Add Drivers License", "Add Passport", "Add Health Card", "ID Backup", "ID Restore", "Attribute Deleted"].
          minLength: 1
          maxLength: 24
          example: ID Created
        createdDate:
          type: string
          description: Date of the event.
          minLength: 1
          maxLength: 29
          example: '2020-01-28T13:16:01.714-05:00'
        values:
          type: array
          description: Details of the activity.
          items:
            $ref: '#/components/schemas/UserAccountActivityItemContents'
    RPActivities:
      required:
      - rpActivities
      properties:
        rpActivities:
          type: array
          description: Relying Party activity items.
          items:
            $ref: '#/components/schemas/RPActivityItems'
        rotatedPds:
          type: string
          description: A rotated PDS is created and returned when the encryption key expires and a new key is generated.
          pattern: ^(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?$
          minLength: 1
          example: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    ErrorResponse:
      required:
      - Errors
      type: object
      description: The error response model used by all the API endpoints.
      properties:
        Errors:
          required:
          - Error
          type: object
          description: The error response model used by all the API endpoints.
          properties:
            Error:
              type: array
              description: A list of Error objects.
              minItems: 1
              items:
                type: object
                properties:
                  Source:
                    type: string
                    description: The source of the problem. That is where the error occurred.
                    example: mids
                  ReasonCode:
                    type: string
                    description: A code defining the error, as defined in documentation.
                    example: USER_PROFILE_ID_NOT_FOUND
                  Description:
                    type: string
                    description: A description of this specific occurrence of the Reason code.
                    example: The provided user profile ID does not exist.
                  Recoverable:
                    type: boolean
                    description: Whether or not retrying this request could result in a successful response.
                    example: false
                  Details:
                    type: string
                    description: More details of this specific error. This is an optional field and is sometimes used to give a more comprehensive description of the error that has occurred, when required.
                    example: User X was not found
                  redirectUri:
                    type: string
                    description: TP will use this URI to redirect to RP.
                    pattern: ^(https?:\/\/(?:www\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\.[^\s]{2,}|www\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\.[^\s]{2,}|https?:\/\/(?:www\.|(?!www))[a-zA-Z0-9]+\.[^\s]{2,}|www\.[a-zA-Z0-9]+\.[^\s]{2,})$
                    example: https://sample-rp-redirect-uri.com/?error=invalid_scope&state=AJahbadinvjbdvdnvljkdnvdfhsrbghrtiu4w&ARID=1234&error_description=claim_not_satisfied
    SdkVersion:
      type: string
      description: Mastercard SDK version integrated with TP App, it is a constant extracted from MIDS SDK Configurations (generated while bundling SDK artifacts). If the TP app supports split PDS, this attribute MUST be specified.
      pattern: ^[0-9]{1,5}\.[0-9]{1,5}\.[0-9]{1,5}$
      minLength: 5
      maxLength: 255
      example: 2.3.0
    UserConsent:
      enum:
      - ACCEPT
      - DECLINE
      - REVOKE
      - EXPIRE
      type: string
      description: Confirmation provided by the TP that the user has consented that the ID-Network can have access to their identity for the purposes of the API call. Should be ACCEPT, a forbidden exception will be thrown if it is any other value.
      pattern: ^(ACCEPT|DECLINE|REVOKE|EXPIRE)$
      minLength: 6
      maxLength: 7
      example: ACCEPT
  examples:
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: UNAUTHORIZED_REQUEST
            Description: Unauthorized request.
            Recoverable: false
    UserAccountActivitiesExample:
      value:
        userAccountActivities:
        - action: ID Created
          createdDate: '2020-01-28T13:16:01.714-05:00'
          values:
          - attributeName: legalName
            previousValue: John Doe
            value: John Dow
            source: passport
        rotatedPds: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    EncryptedPayloadWithRotatedPDSExample:
      value:
        encryptedData: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IoxNTE2MjM5MDIyf
        rotatedPds: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    ForbiddenExampleUnauthorizedScopedFields:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: UNAUTHORIZED_SCOPED_FIELDS
            Description: 'UNAUTHORIZED_SCOPED_FIELDS: Requested scoped fields are not part of whitelisted fields.'
            Recoverable: false
    EncryptedPayloadNoPDSExample:
      value:
        encryptedData: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyf
    UserProfileDeletedErrorExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: USER_PROFILE_DELETED
            Description: 'USER_PROFILE_DELETED: ID of the deleted profile.'
            Recoverable: false
            redirectUri: https://sample-rp-redirect-uri.com?error=server_error&state=AJahbadinvjbdvdnvljkdnvdfhsrbghrtiu4w
    NotFoundExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: USER_PROFILE_ID_NOT_FOUND
            Description: The provided user profile ID does not exist.
            Recoverable: false
    RPActivitiesResponseExample:
      value:
        rpActivities:
        - rpName: Toys Inc
          consentType: OneTime
          createdDate: '2020-01-28T18:16:01.714Z'
          attributesConsented:
            passport.firstName: John
            passport.lastName: Doe
        rotatedPds: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: CONSENT_NOT_GIVEN
            Description: User Consent Not Given.
            Recoverable: false
  parameters:
    XEncryptedPayload:
      in: header
      name: X-Encrypted-Payload
      type: boolean
      description: 'An indicator that the request is encrypted or indicates that the client is able to receive an encrypted response. If not set, the payload will be treated as plaintext.

        '
      example: true
      schema: null
    XUserIdentityParameter:
      in: header
      name: X-User-Identity
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
      description: 'JWT token for session validation. Returned as response header in previous API calls with key X-User-Identity.

        '
      schema:
        type: string
  requestBodies:
    RPActivitySearchRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RPActivitySearch'
      required: true
    UserAccountActivitySearchRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserAccountActivitySearch'
      required: true