swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Token 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: Token
  description: Operations to manage tokens for virtual cards
paths:
  /users/{user_guid}/virtual-card-accounts/{account_guid}/tokens:
    post:
      parameters:
      - $ref: '#/components/parameters/userGUID'
      - $ref: '#/components/parameters/accountGUID'
      tags:
      - Token
      summary: Register a token linked to a user and a virtual card
      description: This endpoint allows users to register a token linked to a user and a virtual card
      operationId: TokenCreate
      requestBody:
        $ref: '#/components/requestBodies/NewToken'
      responses:
        '201':
          $ref: '#/components/responses/ResourceCreated'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
  /users/{user_guid}/virtual-card-accounts/{account_guid}/tokens/{token_guid}:
    get:
      parameters:
      - $ref: '#/components/parameters/userGUID'
      - $ref: '#/components/parameters/accountGUID'
      - $ref: '#/components/parameters/tokenGUID'
      tags:
      - Token
      summary: Retrieve token details linked to a user and a virtual card
      description: This endpoint allows users to retrieve token details linked to a user and a virtual card
      operationId: getTokenById
      responses:
        '200':
          $ref: '#/components/responses/Token'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
    put:
      tags:
      - Token
      parameters:
      - $ref: '#/components/parameters/userGUID'
      - $ref: '#/components/parameters/accountGUID'
      - $ref: '#/components/parameters/tokenGUID'
      summary: Update a token linked to a user and a virtual card
      description: This endpoint allows users to update a token linked to a user and a virtual card
      operationId: updateTokenById
      requestBody:
        $ref: '#/components/requestBodies/UpdatedToken'
      responses:
        '200':
          $ref: '#/components/responses/OKResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
    delete:
      tags:
      - Token
      parameters:
      - $ref: '#/components/parameters/userGUID'
      - $ref: '#/components/parameters/accountGUID'
      - $ref: '#/components/parameters/tokenGUID'
      summary: Delete a token linked to a user and a virtual card
      description: This endpoint allows users to delete a token linked to a user and a virtual card
      operationId: deleteTokenById
      responses:
        '204':
          $ref: '#/components/responses/NOContentResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/ResourceNotFoundError'
components:
  responses:
    UnauthorizedError:
      description: Authentication Required
      headers:
        WWW-Authenticate:
          description: Method of authentication
          schema:
            type: string
      content:
        application/json:
          examples:
            Unauthorized:
              $ref: '#/components/examples/AuthorizationError'
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
    OKResponse:
      description: OK
    ResourceNotFoundError:
      description: Resource Not Found
      content:
        application/json:
          examples:
            ResourceNotFound:
              $ref: '#/components/examples/NotFoundError'
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
    ResourceCreated:
      description: Resource Created
      headers:
        Location:
          description: location of the resource
          schema:
            type: string
    Token:
      description: Token detail
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Token'
          examples:
            Token:
              $ref: '#/components/examples/Token'
    NOContentResponse:
      description: No Content
    ForbiddenError:
      description: Not Authorized
      content:
        application/json:
          examples:
            Forbidden:
              $ref: '#/components/examples/ForbiddenError'
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
    BadRequestError:
      description: Invalid Request
      content:
        application/json:
          examples:
            BadRequest:
              $ref: '#/components/examples/BadRequestError'
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
  examples:
    Token:
      value:
        accountNumber: '1234567891234567'
        expiry: 2021-11
        accountGuid: 123e4567-e89b-12d3-a456-426614174000
        tokenUniqueRef: DE9JOVYK6FVSO8I32DLDPHGTC9NZ7SLKPVLMDQ0RRGK3WYD2
        paymentAppInstanceId: '128652974320250630'
        status: ACTIVE
    AuthorizationError:
      value:
        Errors:
          Error:
          - Source: token-management-service
            ReasonCode: authorization.missing
            Description: Error description
            Recoverable: true
            Details: Detail information
    NotFoundError:
      value:
        Errors:
          Error:
          - Source: token-management-service
            ReasonCode: not.found
            Description: Error description
            Recoverable: true
            Details: Detail information
    ForbiddenError:
      value:
        Errors:
          Error:
          - Source: token-management-service
            ReasonCode: authorization.forbidden
            Description: Error description
            Recoverable: true
            Details: Detail information
    BadRequestError:
      value:
        Errors:
          Error:
          - Source: token-management-service
            ReasonCode: invalid.parameter
            Description: Error description
            Recoverable: true
            Details: Detail information
    TokenUpdate:
      value:
        accountNumber: '1234567891234567'
        expiry: 2021-11
        status: ACTIVE
  parameters:
    tokenGUID:
      name: token_guid
      in: path
      description: The globally unique identifier of the token being queried
      required: true
      schema:
        $ref: '#/components/schemas/ResourceIdentifier'
      example: 8f242496-b71a-11eb-8529-0242ac130003
    accountGUID:
      name: account_guid
      in: path
      description: The globally unique identifier of the card being queried
      required: true
      schema:
        $ref: '#/components/schemas/ResourceIdentifier'
      example: 8f242496-b71a-11eb-8529-0242ac130003
    userGUID:
      name: user_guid
      in: path
      description: The globally unique identifier of the user being queried
      required: true
      schema:
        $ref: '#/components/schemas/ResourceIdentifier'
      example: 8f242496-b71a-11eb-8529-0242ac130003
  schemas:
    Token:
      allOf:
      - $ref: '#/components/schemas/Card'
      properties:
        accountGuid:
          type: string
          format: uuid
          description: The globally unique identifier of the token
          example: 123e4567-e89b-12d3-a456-426614174000
        tokenUniqueRef:
          type: string
          maxLength: 64
          description: The unique reference identifier of the token
          example: DE9JOVYK6FVSO8I32DLDPHGTC9NZ7SLKPVLMDQ0RRGK3WYD2
        paymentAppInstanceId:
          type: string
          maxLength: 64
          description: The unique app device identifier
          example: '128652974320250630'
        status:
          type: string
          pattern: ^(ACTIVE|SUSPENDED)$
          description: Token Status. Valid values are ACTIVE and SUSPENDED
          example: ACTIVE
    ResourceIdentifier:
      description: A UUID which uniquely identifies a resource
      type: string
      format: uuid
      example: c63de020-a446-11eb-bcbc-0242ac130002
    ErrorWrapper:
      type: object
      required:
      - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    Card:
      type: object
      required:
      - accountNumber
      - expiry
      properties:
        accountNumber:
          type: string
          minLength: 12
          maxLength: 19
          pattern: ^[0-9]+
          example: '1234567891234567'
          description: Card Account Number
        expiry:
          minLength: 7
          maxLength: 7
          type: string
          pattern: ^20[2-9][0-9]-(0[1-9]|1[012])$
          description: Card expiry date in yyyy-MM format
          example: 2021-11
    TokenUpdate:
      allOf:
      - $ref: '#/components/schemas/Card'
      properties:
        status:
          type: string
          pattern: ^(ACTIVE|SUSPENDED)$
          description: Token Status. Valid values are ACTIVE and SUSPENDED
          example: ACTIVE
    Errors:
      type: object
      required:
      - Error
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    ErrorList:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    Error:
      type: object
      properties:
        Source:
          type: string
          example: source
          description: Source of error
        ReasonCode:
          type: string
          description: A unique constant identifying the error
          example: '123'
        Description:
          type: string
          example: Error desc
          description: Short description of the error
        Recoverable:
          type: boolean
          example: true
          description: Is recoverable error
        Details:
          type: string
          example: Detail information
          description: Optional detailed description of the issue
  requestBodies:
    NewToken:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Token'
          examples:
            Token:
              $ref: '#/components/examples/Token'
    UpdatedToken:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TokenUpdate'
          examples:
            TokenUpdate:
              $ref: '#/components/examples/TokenUpdate'