swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Changes 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: Changes
paths:
  /alerts/merchants/{member_id}/sub-merchants/{sub_merchant_id}/status-changes:
    put:
      tags:
      - Changes
      summary: Mastercard Change Sub-merchant Status.
      description: Returns sub-merchant details with updated status.
      operationId: updateAlertsSubMerchantStatus
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      - $ref: '#/components/parameters/SubmitterFirstNameParam'
      - $ref: '#/components/parameters/SubmitterLastNameParam'
      - $ref: '#/components/parameters/MemberIdParam'
      - $ref: '#/components/parameters/SubMerchantIdParam'
      requestBody:
        $ref: '#/components/requestBodies/AlertsSubMerchantStatusUpdateRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/AlertsSubMerchantSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/PermissionDenied'
        '403':
          $ref: '#/components/responses/ForbiddenOperation'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/Default'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  examples:
    ForbiddenOperation:
      summary: Member does not have permission to add/update/delete a resource
      description: If the merchant tries operate on a resource that is not related to them or if they are not allowed perform a specific operation on their resource, then ForbiddenOperation error response is returned to the caller with HTTP Status code 403.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: operation.not.allowed
            Description: Member is not allowed to perform a specific operation on a particular resource
            Recoverable: false
            Details: ''
    AlertsEntityNotFound:
      summary: Entity Not Found Error Response For Alerts
      description: If a requested entity(e.g. Sub-Merchant or Card Acceptor ID or Card Acceptor Name) doesn't exist in the system, then EntityNotFound error response is returned to the caller with HTTP Status code 404.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: subMerchantId'
            Description: Sub-Merchant 99ca4b15-72a6-41dd-8127-573d4b07669c not found
            Recoverable: false
            Details: ''
    MissingRequiredHeader:
      summary: Missing Required Header Error Response
      description: If a required request header is missing or null, then MissingRequiredHeader error response is returned to the caller with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: missing required header
            Description: Submitter-First-Name
            Recoverable: false
            Details: ''
    ResourceNotFound:
      summary: Resource Not Found Error Response
      description: If request URI doesn't match with any available endpoints, then ResourceNotFound error response is returned the caller with HTTP Status code 404.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: resource.not.found
            Description: Not Found
            Recoverable: false
            Details: /merchant-self-services/sub-merchantTs/
    AlertsSubMerchantDeactivated:
      summary: Alerts Merchant - Deactivated
      value:
        subMerchantId: 99ca4b15-72a6-41dd-8127-573d4b07669c
        name: Merchant 1
        merchantType: SUBMERCHANT
        status: DEACTIVATED
        parentMemberId: 99ca4b15-72a6-41dd-8127-573d4b07669c
        merchantCategoryCode: '3002'
        createdBy:
          timestamp: '2023-04-28T10:30:00.000Z'
          user: princess.diana
        modifiedBy:
          timestamp: '2023-04-30T10:30:00.000Z'
          user: princess.diana
        statusUpdateTs: '2023-04-30T10:30:00.000Z'
    ServerError:
      summary: Server Error Response
      description: If an unexpected internal server error occurs, then ServerError response is returned to the caller with HTTP Status code 500.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: server.error
            Description: Internal Server Error
            Recoverable: false
            Details: ''
    FormatInvalid:
      summary: Format Invalid Error Response For Consumer Clarity
      description: If a field is not correctly formatted (e.g. a String value is sent in an Integer type field), then FormatInvalid response is returned to the caller with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: format.invalid
            Description: orderHistoryMonths
            Recoverable: false
            Details: ''
    AlertsSubMerchantStatusUpdate:
      summary: Alert Merchant Status Update
      value:
        status: DEACTIVATED
    AlertsFormatInvalid:
      summary: Format Invalid Error Response For Alerts
      description: If a field is not correctly formatted (e.g. a String value is sent in an Integer type field), then FormatInvalid response is returned to the caller with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: merchantCategoryCode'
            Description: must match \"^[0-9]*$\"
            Recoverable: false
            Details: ''
    EntityNotFound:
      summary: Entity Not Found Error Response For Consumer Clarity
      description: If a requested entity(e.g. Merchant or Logo) doesn't exist in the system, then EntityNotFound error response is returned to the caller with HTTP Status code 404.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: GUID'
            Description: Merchant 1E37M8VSX1D28QYX not found
            Recoverable: false
            Details: ''
    PermissionDenied:
      summary: Permission Denied Error Response
      description: If the client id in the request doesn't correspond to any member in the system, then PermissionDenied error response is returned to the caller with HTTP Status code 401.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: permission.denied
            Description: Member does not have permission to perform any operation
            Recoverable: false
            Details: ''
    AlertsSubMerchantActivated:
      summary: Alerts Merchant - Activated
      value:
        subMerchantId: 99ca4b15-72a6-41dd-8127-573d4b07669c
        name: Merchant 1
        merchantType: SUBMERCHANT
        status: ACTIVATED
        parentMemberId: 99ca4b15-72a6-41dd-8127-573d4b07669c
        merchantCategoryCode: '3002'
        createdBy:
          timestamp: '2023-04-28T10:30:00.000Z'
          user: princess.diana
        modifiedBy:
          timestamp: '2023-04-28T10:30:00.000Z'
          user: princess.diana
        statusUpdateTs: '2023-04-28T10:30:00.000Z'
    InvalidParameterSet:
      summary: Invalid Parameter Set Error Response
      description: If request body is malformed or missing, then InvalidParameterSet error response is returned to the caller with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: invalid.parameter.set
            Description: request body is malformed
            Recoverable: false
            Details: ''
    InvalidData:
      summary: Invalid Data Error Response For Consumer Clarity
      description: If a field or set of fields fails a validation (eg. NotNull, Length, Pattern etc.), then InvalidData response will be returned to the caller for each invalid field with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: merchantType'
            Description: must not be blank
            Recoverable: false
            Details: ''
    ValidationFailed:
      summary: Validation of the request failed
      description: If the fields in the request did not pass the validation, a ValidationFailed error response is returned to the caller with HTTP Status code 422.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: validation.failed
            Description: Validation of the request fields failed
            Recoverable: false
            Details: ''
    AlertsInvalidData:
      summary: Invalid Data Field Error Response For Alerts
      description: If a field or set of fields fails a validation (eg. NotNull, Length, Pattern etc.), then InvalidData response will be returned to the caller for each invalid field with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: name'
            Description: size must be between 3 and 200
            Recoverable: false
            Details: ''
  responses:
    Default:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ServerError:
              $ref: '#/components/examples/ServerError'
    ValidationFailed:
      description: Validation Failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ValidationFailed:
              $ref: '#/components/examples/ValidationFailed'
    ForbiddenOperation:
      description: Forbidden Operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ForbiddenOperation:
              $ref: '#/components/examples/ForbiddenOperation'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ResourceNotFound:
              $ref: '#/components/examples/ResourceNotFound'
            EntityNotFound:
              $ref: '#/components/examples/EntityNotFound'
            AlertsEntityNotFound:
              $ref: '#/components/examples/AlertsEntityNotFound'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            InvalidData:
              $ref: '#/components/examples/InvalidData'
            AlertsInvalidData:
              $ref: '#/components/examples/AlertsInvalidData'
            InvalidParameterSet:
              $ref: '#/components/examples/InvalidParameterSet'
            FormatInvalid:
              $ref: '#/components/examples/FormatInvalid'
            AlertsFormatInvalid:
              $ref: '#/components/examples/AlertsFormatInvalid'
            MissingRequiredHeader:
              $ref: '#/components/examples/MissingRequiredHeader'
    AlertsSubMerchantSuccess:
      description: Sub-merchant with all details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlertsSubMerchantResource'
          examples:
            AlertsSubMerchantActivated:
              $ref: '#/components/examples/AlertsSubMerchantActivated'
            AlertsSubMerchantDeactivated:
              $ref: '#/components/examples/AlertsSubMerchantDeactivated'
    PermissionDenied:
      description: Permission Denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            PermissionDenied:
              $ref: '#/components/examples/PermissionDenied'
  schemas:
    CreatedOrModifiedBy:
      description: Timestamp and user responsible for creation or modification of the resource
      type: object
      properties:
        timestamp:
          $ref: '#/components/schemas/Timestamp'
        user:
          $ref: '#/components/schemas/User'
    User:
      description: Username for the user creating or modifying a resource
      type: string
      minLength: 0
      maxLength: 200
      example: John Doe
    UserId:
      title: User Id
      maxLength: 300
      minLength: 1
      type: string
      description: The user id of the submitter/technical contact.
      example: princess.diana
    AlertsSubMerchantResource:
      description: Response containing a specific sub-merchant with details
      type: object
      properties:
        subMerchantId:
          $ref: '#/components/schemas/AlertsMerchantMemberId'
        name:
          $ref: '#/components/schemas/MerchantName'
        merchantType:
          $ref: '#/components/schemas/MerchantType'
        status:
          $ref: '#/components/schemas/MerchantStatus'
        parentMemberId:
          $ref: '#/components/schemas/AlertsMerchantMemberId'
        merchantCategoryCode:
          $ref: '#/components/schemas/MerchantCategoryCode'
        createdBy:
          $ref: '#/components/schemas/CreatedOrModifiedBy'
        modifiedBy:
          $ref: '#/components/schemas/CreatedOrModifiedBy'
        statusUpdateTs:
          $ref: '#/components/schemas/Timestamp'
    AlertsMerchantMemberId:
      title: Unique identifier for merchants
      description: Internal Universally Unique Identifier (UUID) which uniquely identifies the merchants
      type: string
      format: uuid
      example: 99ca4b15-72a6-41dd-8127-573d4b07669c
    AlertsSubMerchantStatusUpdate:
      description: Request used to update sub-merchant status
      type: object
      properties:
        status:
          $ref: '#/components/schemas/MerchantStatus'
      required:
      - status
    ErrorResponse:
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
      description: Error Response object
    FirstName:
      title: First Name
      maxLength: 30
      minLength: 1
      type: string
      description: The individual's first name
      example: Michael
      nullable: true
    MerchantStatus:
      title: Merchant's Status
      type: string
      description: Merchant Status must be one of - ACTIVATED, DEACTIVATED
      minLength: 1
      maxLength: 50
      example: ACTIVATED
    MerchantCategoryCode:
      title: Merchant Category Code
      description: A four-digit number listed in ISO 18245 for retail financial services. MCC is used to classify the business by the type of goods or services it provides.
      type: string
      maxLength: 4
      minLength: 0
      pattern: ^[0-9]*$
      example: '3002'
    MerchantType:
      title: Merchant's Type
      description: Merchant Type must be one of - PARTNER, ACQUIRER, SUBMERCHANT
      type: string
      minLength: 1
      maxLength: 50
      example: SUBMERCHANT
    Errors:
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          description: List of error objects
          items:
            $ref: '#/components/schemas/Error'
          example: []
      description: Errors object
    Timestamp:
      description: Timestamp of the creation or modification of the resource
      type: string
      minLength: 0
      maxLength: 50
      format: date-time
      example: '2023-04-28T10:30:00.000Z'
    LastName:
      title: Last Name
      maxLength: 30
      minLength: 1
      type: string
      description: The individual's last name
      example: Fox
      nullable: true
    MerchantName:
      title: Merchant's Name
      maxLength: 200
      minLength: 3
      type: string
      description: Merchant's partial or full name.
      example: Merchant 1
    Error:
      type: object
      properties:
        Source:
          maxLength: 100
          minLength: 0
          type: string
          description: Source of the error
          example: Service
          nullable: true
        ReasonCode:
          maxLength: 100
          minLength: 0
          type: string
          description: A unique constant identifying the error
          example: format.invalid
          nullable: true
        Description:
          maxLength: 1000
          minLength: 0
          type: string
          description: Short description of the error
          example: Short description of the error
          nullable: true
        Recoverable:
          type: boolean
          description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
          example: false
          default: false
          nullable: true
        Details:
          maxLength: 1000
          minLength: 0
          type: string
          description: Optional detailed description of the issue
          example: Detailed description of the error
          nullable: true
      description: Error object
  parameters:
    SubmitterFirstNameParam:
      name: Submitter-First-Name
      in: header
      required: true
      example: Diana
      description: The first name of the submitter/technical contact.
      schema:
        $ref: '#/components/schemas/FirstName'
    SubmitterLastNameParam:
      name: Submitter-Last-Name
      in: header
      required: true
      example: Princess
      description: The last name of the submitter/technical contact.
      schema:
        $ref: '#/components/schemas/LastName'
    MemberIdParam:
      name: member_id
      in: path
      required: true
      description: Merchant member ID (parent of the sub-merchant)
      example: 99ca4b15-72a6-41dd-8127-573d4b07669c
      schema:
        $ref: '#/components/schemas/AlertsMerchantMemberId'
    UserIdParam:
      name: User-Id
      in: header
      required: true
      example: princess.diana
      description: The user id of the submitter/technical contact.
      schema:
        $ref: '#/components/schemas/UserId'
    SubMerchantIdParam:
      name: sub_merchant_id
      in: path
      required: true
      description: Sub-merchant member ID
      example: cc2cac41-d127-4c06-9646-c0f2ad76c444
      schema:
        $ref: '#/components/schemas/AlertsMerchantMemberId'
  requestBodies:
    AlertsSubMerchantStatusUpdateRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlertsSubMerchantStatusUpdate'
          examples:
            AlertsSubMerchantStatusUpdateRequestBody:
              $ref: '#/components/examples/AlertsSubMerchantStatusUpdate'