swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Benefit-Allocations-Card-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-Card-Management
  description: Endpoints to freeze/unfreeze a card and replace a card for a cardholder.
paths:
  /cards:
    post:
      tags:
      - Benefit-Allocations-Card-Management
      summary: Mastercard Replace Card Number for a Cardholder
      description: Replaces the card number associated with the user. The benefits on the old card number are expired, and the same set of benefits are applied to new card number.
      operationId: cardReplacement
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/CardReplacementRequest'
      responses:
        '200':
          description: Contains bundles associated details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bundles'
              examples:
                ReplaceCardExample:
                  $ref: '#/components/examples/ReplaceCardExample'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Benefit-Allocations-Card-Management
      summary: Mastercard Freeze/unfreeze a Card for Benefits
      description: Freezes a card for benefits, or unfreezes the card for benefits. isFrozen set to true freezes the card, and isFrozen set to false unfreezes the card.
      operationId: freezeUnfreeze
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/FrozenCardRequest'
      responses:
        '204':
          $ref: '#/components/responses/BenefitAllocationEmptyResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  examples:
    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
    BadRequestExample:
      value:
        Errors:
          Error:
          - Source: Benefit Allocation Service
            ReasonCode: 50
            Description: invalid card number, segment code, date
            Recoverable: false
            Details: invalid card number format
    ReplaceCardExample:
      value:
        bundles:
        - code: PC4657
          effectiveDate: '2022-01-18'
          expiryDate: '2024-07-18'
        - code: PC6323
          effectiveDate: '2022-01-18'
          expiryDate: '2024-07-18'
  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'
    ErrorWrapper:
      description: A top level object for errors
      type: object
      required:
      - errors
      properties:
        Errors:
          $ref: '#/components/schemas/errors'
    errors:
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          description: Object that contains the list of errors
          items:
            $ref: '#/components/schemas/Error'
          example: []
    CardReplacement:
      required:
      - oldCardNumber
      - newCardNumber
      - effectiveDate
      type: object
      properties:
        oldCardNumber:
          type: integer
          format: int64
          description: 16 or 19 digit PAN number that will be expired and replaced along with its benefit bundles.
          example: 5291070000000000
        newCardNumber:
          type: integer
          format: int64
          description: New 16 or 19 digit PAN number that will have the same unexpired set of benefits as the old card number.
          example: 5291070000000898
        effectiveDate:
          type: string
          description: Date at which the replace will be effective. Date should be in YYYY-MM-DD format.
          format: date
          example: '2023-08-08'
    FrozenCard:
      required:
      - cardNumber
      - date
      - isFrozen
      type: object
      properties:
        cardNumber:
          type: integer
          format: int64
          description: 16 or 19 digit PAN number that will be frozen/unfrozen.
          example: 5291070000000000
        date:
          type: string
          description: Date at which the freeze will be effective. Date should be in YYYY-MM-DD format.
          format: date
          example: '2023-08-08'
        isFrozen:
          type: boolean
          description: Variable to change whether or not the card number is frozen. True for freeze and false for unfreeze.
          example: true
    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
  responses:
    BenefitAllocationEmptyResponse:
      description: No content.
    ForbiddenErrorResponse:
      description: Insufficient permissions for interacting with the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            ForbiddenExample:
              $ref: '#/components/examples/ForbiddenExample'
    BadRequestErrorResponse:
      description: Something was wrong with the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequestExample'
  requestBodies:
    FrozenCardRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FrozenCard'
    CardReplacementRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CardReplacement'