swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Benefit-Allocations-Segment-Management 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: Benefit-Allocations-Segment-Management
  description: Endpoints to assign, cancel or replace a segment to a card.
paths:
  /card-segments:
    post:
      tags:
      - Benefit-Allocations-Segment-Management
      summary: Mastercard Assign Segment to a Card
      description: Assigns segment to a card by sending a card number, segment code and effective date in the input. The response is an array of bundles that are assigned to the card. At this time this endpoint supports exactly one segment code in the input. It is defined as an array for future support.
      operationId: assignSegment
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/AssignBenefitAllocationsRequest'
      responses:
        '200':
          description: Contains bundles associated details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bundles'
              examples:
                AllocateBundlesExample:
                  $ref: '#/components/examples/AllocateBundlesExample'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /card-segments-replacements:
    put:
      tags:
      - Benefit-Allocations-Segment-Management
      summary: Mastercard Replaces Segment on a Card
      description: Replaces the segment and the existing benefits with the new set of benefits that are on the new Segment Code. The existing benefits are expired, and new benefits are assigned. The response is an array of bundles that are newly assigned to the card.
      operationId: replaceSegment
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/ReplaceBenefitAllocationsRequest'
      responses:
        '200':
          description: Contains bundles associated details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bundles'
              examples:
                AllocateBundlesExample:
                  $ref: '#/components/examples/AllocateBundlesExample'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /card-segments-cancellations:
    put:
      tags:
      - Benefit-Allocations-Segment-Management
      summary: Mastercard Cancels Segment From a Card
      description: Cancels a segment and the benefits associated to the card for the input segment. The response is an array of bundles that are cancelled on the card. Exactly one input segment is supported at this time. It is defined as an array for future support.
      operationId: cancelSegment
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/CancelBenefitAllocationsRequest'
      responses:
        '200':
          description: Contains bundles associated details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bundles'
              examples:
                CancelBundlesExample:
                  $ref: '#/components/examples/CancelBundlesExample'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Bundles:
      type: object
      properties:
        bundles:
          type: array
          description: List of eligible benefit bundles after a segment has been assigned to a card number.
          items:
            $ref: '#/components/schemas/BundleDetails'
          example: []
    BundleDetails:
      type: object
      properties:
        code:
          maxLength: 6
          minLength: 0
          type: string
          description: Unique identifier of a benefit bundle that represents a group of benefit instances available.
          example: PC4657
        effectiveDate:
          type: string
          description: Effective date associated to the benefits in the benefit bundle. Date will be in YYYY-MM-DD format.
          format: date
          example: '2023-08-08'
        expiryDate:
          type: string
          description: Expiry date associated to the benefits in the benefit bundle. Date will be in YYYY-MM-DD format.
          format: date
          example: '2024-07-18'
    errors:
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          description: Object that contains the list of errors
          items:
            $ref: '#/components/schemas/Error'
          example: []
    SegmentToCancel:
      required:
      - code
      - expiryDate
      type: object
      properties:
        code:
          maxLength: 250
          minLength: 0
          type: string
          description: Identifier that represents a group of benefit bundles to be cancelled.
          example: DART
        expiryDate:
          type: string
          description: Date at which the benefit bundles associated to the segment code will be cancelled. Date should be in YYYY-MM-DD format.
          format: date
          example: '2024-07-24'
    CancelBenefitAllocation:
      required:
      - cardNumber
      - segments
      type: object
      properties:
        cardNumber:
          type: integer
          format: int64
          description: 16 or 19 digit PAN number that will have it's segment expired/cancelled.
          example: 5291070000000000
          pattern: ^(\d{16}|\d{19})$
        segments:
          type: array
          description: List of segments assigned to the card number that will be cancelled. Only accepts arrays containing one segment.
          items:
            $ref: '#/components/schemas/SegmentToCancel'
          example: []
    ErrorWrapper:
      description: A top level object for errors
      type: object
      required:
      - errors
      properties:
        Errors:
          $ref: '#/components/schemas/errors'
    ReplaceBenefitAllocation:
      required:
      - cardNumber
      - oldSegmentCode
      - newSegmentCode
      - effectiveDate
      type: object
      properties:
        cardNumber:
          type: integer
          format: int64
          description: 16 or 19 digit PAN number that will have its segment replaced.
          example: 5291070000000000
          pattern: ^(\d{16}|\d{19})$
        oldSegmentCode:
          maxLength: 250
          minLength: 0
          type: string
          description: Unique identifier representing a group of benefit bundles that will be expired and replaced.
          example: DART
        newSegmentCode:
          maxLength: 250
          minLength: 0
          type: string
          description: Unique identifier representing the new group of benefit bundles that will be assigned.
          example: PRT
        effectiveDate:
          type: string
          description: Date at which the new segment will go in effect. Date should be in YYYY-MM-DD format.
          format: date
          example: '2023-08-08'
    AssignBenefitAllocation:
      required:
      - cardNumber
      - segments
      type: object
      properties:
        cardNumber:
          type: integer
          format: int64
          description: 16 or 19 digit PAN number that will have a segment assigned to it.
          example: 5291070000000000
          pattern: ^(\d{16}|\d{19})$
        segments:
          type: array
          description: List of segments that will be assigned to the pan number. Only accepts arrays containing one segment.
          items:
            $ref: '#/components/schemas/Segment'
          example: []
    Segment:
      required:
      - code
      - effectiveDate
      type: object
      properties:
        code:
          maxLength: 250
          minLength: 0
          type: string
          description: Unique identifier representing a group of benefit bundles to be assigned.
          example: DART
        effectiveDate:
          type: string
          description: Date at which the benefit bundles associated to the segment code will be active and available for use. Date should be in YYYY-MM-DD format.
          format: date
          example: '2023-08-08'
    Error:
      type: object
      properties:
        Source:
          type: string
          minLength: 0
          maxLength: 200
          description: Information about where the error happened
          example: benefits allocation api
        ReasonCode:
          type: string
          minLength: 0
          maxLength: 200
          description: An error code
          example: Bad request
        Description:
          type: string
          minLength: 0
          maxLength: 10000
          description: A description of the error
          example: string
        Recoverable:
          type: boolean
          description: Indicates if the request can be presented again for processing
          example: string
        Details:
          type: string
          minLength: 0
          maxLength: 100000
          description: More details about the error
          example: Invalid JSON payload
  requestBodies:
    CancelBenefitAllocationsRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CancelBenefitAllocation'
    ReplaceBenefitAllocationsRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReplaceBenefitAllocation'
    AssignBenefitAllocationsRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AssignBenefitAllocation'
  examples:
    BadRequestExample:
      value:
        Errors:
          Error:
          - Source: Benefit Allocation Service
            ReasonCode: 50
            Description: invalid card number, segment code, date
            Recoverable: false
            Details: invalid card number format
    AllocateBundlesExample:
      value:
        bundles:
        - code: PC4657
          effectiveDate: '2023-08-08'
          expiryDate: null
        - code: PC6323
          effectiveDate: '2023-08-08'
          expiryDate: null
    CancelBundlesExample:
      value:
        bundles:
        - code: PC4657
          effectiveDate: '2023-08-08'
          expiryDate: '2024-07-18'
        - code: PC6323
          effectiveDate: '2023-08-08'
          expiryDate: '2024-07-18'
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: Benefit Allocation Service
            ReasonCode: PERMISSION_DENIED
            Description: You don't seem authorized to do that
            Recoverable: false
            Details: cardNumber not mapped to requester
  responses:
    BadRequestErrorResponse:
      description: Something was wrong with the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequestExample'
    ForbiddenErrorResponse:
      description: Insufficient permissions for interacting with the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            ForbiddenExample:
              $ref: '#/components/examples/ForbiddenExample'