swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Ids 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: Ids
paths:
  /alerts/merchants/{member_id}/sub-merchants/{sub_merchant_id}/card-acceptor-ids:
    post:
      tags:
      - Ids
      summary: Mastercard Create Sub-merchant Card Acceptor Id Config.
      description: Returns created sub-merchant card acceptor id config details.
      operationId: createAlertsCardAcceptorIdConfig
      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/AlertsCardAcceptorIdConfigRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/AlertsMerchantIdentifierSuccess'
        '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
    get:
      tags:
      - Ids
      summary: Mastercard Get Sub-merchant Card Acceptor Id Configs.
      description: Returns sub-merchant card acceptor id config details.
      operationId: getAlertsCardAcceptorIdConfigs
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      - $ref: '#/components/parameters/SubmitterFirstNameParam'
      - $ref: '#/components/parameters/SubmitterLastNameParam'
      - $ref: '#/components/parameters/MemberIdParam'
      - $ref: '#/components/parameters/SubMerchantIdParam'
      - $ref: '#/components/parameters/AcquirerReferenceIdParam'
      - $ref: '#/components/parameters/CardAcceptorIdParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/PageNumberParam'
      responses:
        '200':
          $ref: '#/components/responses/AlertsCardAcceptorIdConfigs'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/PermissionDenied'
        '403':
          $ref: '#/components/responses/ForbiddenOperation'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Default'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      tags:
      - Ids
      summary: Mastercard Delete Sub-merchant Card Acceptor Id Config.
      description: Returns 200 if sub-merchant card acceptor id configs gets deleted.
      operationId: deleteAlertsCardAcceptorIdConfig
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      - $ref: '#/components/parameters/SubmitterFirstNameParam'
      - $ref: '#/components/parameters/SubmitterLastNameParam'
      - $ref: '#/components/parameters/MemberIdParam'
      - $ref: '#/components/parameters/SubMerchantIdParam'
      - $ref: '#/components/parameters/MerchantIdentifierConfigIdParam'
      responses:
        '200':
          $ref: '#/components/responses/SuccessWithoutBody'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/PermissionDenied'
        '403':
          $ref: '#/components/responses/ForbiddenOperation'
        '404':
          $ref: '#/components/responses/NotFound'
        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: ''
    AlertsCardAcceptorIdConfig:
      summary: Alerts Card Acceptor ID Configuration
      value:
        acquirerReferenceId: '123456'
        cardAcceptorId: card_acceptorA
    AlertsMerchantIdentifierConfigIdOnly:
      summary: Alerts Merchant Identifier Configuration ID
      value:
        merchantIdentifierConfigId: 88ca4b15-72a6-41dd-8127-573d4b07875c
    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/
    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: ''
    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: ''
    AlertsCardAcceptorIdConfigs:
      summary: Alerts Card Acceptor ID Configurations
      value:
        responseHeader:
          totalRecords: 500
          totalPages: 10
          currentPage: 2
          responseTime: 300 ms
        configs:
        - merchantIdentifierConfigId: 11ca4b15-72a6-41dd-8127-573d4b07511c
          acquirerReferenceId: '123456'
          cardAcceptorId: card_acceptorA
        - merchantIdentifierConfigId: 22ca4b15-72a6-41dd-8127-573d4b07522c
          acquirerReferenceId: '876543'
          cardAcceptorId: card_acceptorB
    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: ''
    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'
    AlertsCardAcceptorIdConfigs:
      description: Sub-merchant card acceptor id configurations
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlertsCardAcceptorIdConfigs'
          examples:
            AlertsCardAcceptorIdConfigs:
              $ref: '#/components/examples/AlertsCardAcceptorIdConfigs'
    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'
    SuccessWithoutBody:
      description: Successful Operation
    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'
    PermissionDenied:
      description: Permission Denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            PermissionDenied:
              $ref: '#/components/examples/PermissionDenied'
    AlertsMerchantIdentifierSuccess:
      description: Sub-merchant identifiers for either card acceptor id or card acceptor name configuration
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlertsMerchantIdentifierConfigIdOnly'
          examples:
            AlertsMerchantIdentifierConfigIdOnly:
              $ref: '#/components/examples/AlertsMerchantIdentifierConfigIdOnly'
  requestBodies:
    AlertsCardAcceptorIdConfigRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlertsCardAcceptorIdConfig'
          examples:
            AlertsCardAcceptorIdConfig:
              $ref: '#/components/examples/AlertsCardAcceptorIdConfig'
  schemas:
    UserId:
      title: User Id
      maxLength: 300
      minLength: 1
      type: string
      description: The user id of the submitter/technical contact.
      example: princess.diana
    AcquirerReferenceId:
      title: Acquirer Reference ID (ARID)
      description: The acquirer BINs that a partner currently services under their portfolio. This is represented by Mastercard DE 31 - Subfield 2 (Clearing), DE 32 (Authorization), or Visa Field 32.
      type: string
      minLength: 6
      maxLength: 6
      pattern: ^[\d]+$
      example: '123456'
    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
    CardAcceptorId:
      title: Card Acceptor's ID (CAID)
      description: Identifies the card acceptor ID assigned by the acquirer. This ID must represent a unique identifier for each merchant name/location within the acquirer BIN. This is represented by Mastercard DE 42 and Visa Field 42.
      type: string
      minLength: 1
      maxLength: 15
      example: card_acceptor1
    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
    ResponseHeader:
      type: object
      properties:
        totalRecords:
          type: integer
          format: int64
          description: Total number of records found
          minimum: 0
          maximum: 999999999
          example: 500
        totalPages:
          type: integer
          description: Total number of pages based on limit
          minimum: 0
          maximum: 999999999
          example: 10
        currentPage:
          type: integer
          description: The current page number
          minimum: 1
          maximum: 999999999
          example: 2
        responseTime:
          $ref: '#/components/schemas/ResponseTime'
    AlertsMerchantIdentifierConfigIdOnly:
      description: Merchant identifier configuration Id (referring to card acceptor id or name configuration)
      type: object
      properties:
        merchantIdentifierConfigId:
          $ref: '#/components/schemas/AlertsMerchantConfigId'
    AlertsCardAcceptorIdConfigs:
      description: Card acceptor id configurations for a merchant
      type: object
      properties:
        responseHeader:
          $ref: '#/components/schemas/ResponseHeader'
        configs:
          type: array
          items:
            $ref: '#/components/schemas/AlertsCardAcceptorIdConfig'
          example: []
    AlertsCardAcceptorIdConfig:
      description: Map of acquirer reference id and the corresponding card acceptor id
      type: object
      properties:
        merchantIdentifierConfigId:
          $ref: '#/components/schemas/AlertsMerchantConfigId'
        acquirerReferenceId:
          $ref: '#/components/schemas/AcquirerReferenceId'
        cardAcceptorId:
          $ref: '#/components/schemas/CardAcceptorId'
      required:
      - acquirerReferenceId
      - cardAcceptorId
    Errors:
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          description: List of error objects
          items:
            $ref: '#/components/schemas/Error'
          example: []
      description: Errors object
    LastName:
      title: Last Name
      maxLength: 30
      minLength: 1
      type: string
      description: The individual's last name
      example: Fox
      nullable: true
    ResponseTime:
      type: string
      description: Total response time in ms
      minLength: 0
      maxLength: 10
      example: 300 ms
    AlertsMerchantConfigId:
      title: Unique identifier for merchants identifier (such as acquirer reference id, card acceptor id or name) configuration
      description: Internal Universally Unique Identifier (UUID) which uniquely identifies the merchants configuration
      type: string
      format: uuid
      example: 88ca4b15-72a6-41dd-8127-573d4b07558c
    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:
    OffsetParam:
      name: offset
      in: query
      required: false
      description: Number of items per page
      schema:
        type: integer
        default: 25
        maximum: 25
      example: 25
    MerchantIdentifierConfigIdParam:
      name: merchant_identifier_config_id
      in: query
      required: true
      description: The Configuration ID for acquirer reference ID or card acceptor ID or card acceptor name configurations.
      schema:
        $ref: '#/components/schemas/AlertsMerchantConfigId'
      example: 88ca4b15-72a6-41dd-8127-573d4b07875c
    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'
    AcquirerReferenceIdParam:
      name: acquirer_reference_id
      in: query
      required: false
      description: BIN that a partner currently services under their portfolio.
      schema:
        $ref: '#/components/schemas/AcquirerReferenceId'
      example: '123456'
    PageNumberParam:
      name: page_number
      in: query
      required: false
      description: Current page number
      schema:
        type: integer
        default: 1
        minimum: 1
      example: 1
    CardAcceptorIdParam:
      name: card_acceptor_id
      in: query
      required: false
      description: Identifies the card acceptor ID assigned by the acquirer. This ID must represent a unique identifier for each merchant name/location within the acquirer BIN.
      schema:
        $ref: '#/components/schemas/CardAcceptorId'
      example: card_acceptor1