swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Field Mapping 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: Field Mapping
paths:
  /fieldmappings:
    get:
      summary: Retrieving fieldmappings
      description: Retrieve field information for notification message content, which can be used to set up subscription filter specifications for those notifications.
      tags:
      - Field Mapping
      operationId: getFieldMapping
      responses:
        '200':
          $ref: '#/components/responses/FieldMappingSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  examples:
    FieldMappingBPCAuthorizationResponse:
      value:
      - id: 141747A087EADC9DE06368459E0AC116
        name: fundingSource.fundingSourceGuid
        displayName: Funding Source Guid
        subjectType: BPC_PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 141747A087B1DC9DE06368459E0AC116
        name: messageTypeIndicator
        displayName: MessageTypeIndicator
        subjectType: BPC_PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 141747A087B4DC9DE06368459E0AC116
        name: issuerGuid
        displayName: IssuerGuid
        subjectType: BPC_PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 141747A087B5DC9DE06368459E0AC116
        name: corpGuid
        displayName: CorpGuid
        subjectType: BPC_PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 141747A087B8DC9DE06368459E0AC116
        name: processor.responseCode
        displayName: Processor ResponseCode
        subjectType: BPC_PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 141747A087BBDC9DE06368459E0AC116
        name: processor.onBehalfResult
        displayName: Processor OnBehalfResult
        subjectType: BPC_PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 141747A087BFDC9DE06368459E0AC116
        name: realPaymentCard.accountGuid
        displayName: RealPaymentCard AccountGuid
        subjectType: BPC_PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 141747A087C0DC9DE06368459E0AC116
        name: virtualPaymentCard.number
        displayName: VirtualPaymentCard Number
        subjectType: BPC_PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 141747A087C2DC9DE06368459E0AC116
        name: virtualPaymentCard.accountGuid
        displayName: VirtualPaymentCard AccountGuid
        subjectType: BPC_PAYMENT_AUTHORIZATION
        contentType: TEXT
    FieldMappingICMPProvisioningResponse:
      value:
      - id: 1AD42C3FCAE62726E06368459E0A9487
        name: vcnInfo.accountNumber
        displayName: VCN Account Number
        subjectType: TOKEN_PROVISIONING_EVENT
        contentType: TEXT
      - id: 1AD42C3FCAE92726E06368459E0A9487
        name: vcnInfo.ownerInfo.issuerGuid
        displayName: VCN Issuer Guid
        subjectType: TOKEN_PROVISIONING_EVENT
        contentType: TEXT
      - id: 1AD42C3FCAF12726E06368459E0A9487
        name: purchaseRequest.rcnAlias
        displayName: Purchase Request RCN Alias
        subjectType: TOKEN_PROVISIONING_EVENT
        contentType: TEXT
      - id: 1AD42C3FCAF22726E06368459E0A9487
        name: purchaseRequest.companyId
        displayName: Purchase Request Company Id
        subjectType: TOKEN_PROVISIONING_EVENT
        contentType: INTEGER
    FieldMappingICMPLifecycleResponse:
      value:
      - id: 1AD42C3FCAE62726E06368459E0A9487
        name: vcnInfo.accountNumber
        displayName: VCN Account Number
        subjectType: TOKEN_LIFECYCLE_EVENT
        contentType: TEXT
      - id: 1AD42C3FCAE92726E06368459E0A9487
        name: vcnInfo.ownerInfo.issuerGuid
        displayName: VCN Issuer Guid
        subjectType: TOKEN_LIFECYCLE_EVENT
        contentType: TEXT
      - id: 1AD42C3FCAF12726E06368459E0A9487
        name: purchaseRequest.rcnAlias
        displayName: Purchase Request RCN Alias
        subjectType: TOKEN_LIFECYCLE_EVENT
        contentType: TEXT
      - id: 1AD42C3FCAF22726E06368459E0A9487
        name: purchaseRequest.companyId
        displayName: Purchase Request Company Id
        subjectType: TOKEN_LIFECYCLE_EVENT
        contentType: INTEGER
    FieldMappingICCPAuthorizationResponse:
      value:
      - id: 0CNS2cfa3d3977d6d991b7cd723570ba96bf6830ef4c4f897f4d00df0038e288f34c1556724071
        name: virtualPaymentCard.number
        displayName: Virtual card number
        subjectType: PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 0CNSa6d4a329d377bb296957df43e9f2f1ab5b35c997f88bcbc34939bc1525990be51556724071
        name: messageTypeIndicator
        displayName: Message type indicator
        subjectType: PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 0CNS05bb6badecddacf50a3c4c94184c6214f38e0980883b13bf7205165c7a74a8231556724071
        name: responseCode
        displayName: Response code
        subjectType: PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 0CNSddd4612f680dd452c61b945436e06f73e80786d7ebd6683d8cc0c7950bdd01211556724071
        name: inControlOnBehalfServiceResult.vcnServiceResultCode
        displayName: In Control VCN service result code
        subjectType: PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 0CNS14802eafac9cfe04d25da2a5944074eaa89bee5ca2136329e493399a27a39ccd1556724071
        name: purchaseRequest.rcnAlias
        displayName: Purchase request RCN alias
        subjectType: PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 0CNS0e2d81ac7109e23ee63d818f575d43e465ca193771eb510a4156d772fd98eb5a1556724071
        name: purchaseRequest.companyId
        displayName: Purchase request company id
        subjectType: PAYMENT_AUTHORIZATION
        contentType: INTEGER
      - id: 0CNS1fe7275144b16a3ef1cec8f8261598d7491491c2894015d549ec00e13ba961a31556724071
        name: purchaseRequest.companyGuid
        displayName: Purchase request company GUID
        subjectType: PAYMENT_AUTHORIZATION
        contentType: TEXT
      - id: 0CNSa91bf379b48a593fd17f07f431bad8fb296796498f4e9982ea134394c1fa4f071556724071
        name: purchaseRequest.issuerGuid
        displayName: Purchase request issuer GUID
        subjectType: PAYMENT_AUTHORIZATION
        contentType: TEXT
    FieldMappingICCPClearingResponse:
      value:
      - id: 135E59332C14BF9AE06368459E0ACEF0
        name: virtualPaymentCard.number
        displayName: virtual Card number
        subjectType: CLEARING
        contentType: TEXT
      - id: 16E733C760225235E06368459E0AD1EA
        name: purchaseRequest.rcnAlias
        displayName: purchaseRequest rcnAlias
        subjectType: CLEARING
        contentType: TEXT
      - id: 16E733C760235235E06368459E0AD1EA
        name: purchaseRequest.companyId
        displayName: purchaseRequest company Id
        subjectType: CLEARING
        contentType: INTEGER
      - id: 16E733C760245235E06368459E0AD1EA
        name: purchaseRequest.companyGuid
        displayName: purchaseRequest company Guid
        subjectType: CLEARING
        contentType: TEXT
      - id: 16E733C760255235E06368459E0AD1EA
        name: purchaseRequest.issuerGuid
        displayName: purchaseRequest issuer Guid
        subjectType: CLEARING
        contentType: TEXT
      - id: 16E733C75FE65235E06368459E0AD1EA
        name: acceptor.merchantCategoryCode
        displayName: acceptor merchantCategoryCode
        subjectType: CLEARING
        contentType: TEXT
      - id: 16E733C760065235E06368459E0AD1EA
        name: isMatched
        displayName: isMatched
        subjectType: CLEARING
        contentType: TEXT
      - id: 16E733C7600B5235E06368459E0AD1EA
        name: type
        displayName: type
        subjectType: CLEARING
        contentType: TEXT
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-403'
    FieldMappingSuccess:
      description: OK
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/FieldMapping'
          examples:
            BPC PAYMENT AUTHORIZATION:
              $ref: '#/components/examples/FieldMappingBPCAuthorizationResponse'
            ICCP CLEARING:
              $ref: '#/components/examples/FieldMappingICCPClearingResponse'
            ICCP PAYMENT AUTHORIZATION:
              $ref: '#/components/examples/FieldMappingICCPAuthorizationResponse'
            ICMP TOKEN LIFECYCLE:
              $ref: '#/components/examples/FieldMappingICMPLifecycleResponse'
            ICMP TOKEN PROVISIONING:
              $ref: '#/components/examples/FieldMappingICMPProvisioningResponse'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-400'
  schemas:
    Error-403:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          properties:
            Error:
              type: array
              description: An array of error objects giving information about relevant errors.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    description: The origin of the error
                    example: Commercial Event Notifications
                  ReasonCode:
                    type: string
                    description: A unique error code representing the error that occurred
                    example: subscriber.notAllowed
                  Description:
                    type: string
                    description: A developer-friendly description of the error that occurred
                    example: Access not allowed
                  Recoverable:
                    type: boolean
                    description: Can the error be recovered by retrying the same request later?
                    example: false
                  Details:
                    type: string
                    description: Additional details regarding the error that occurred
                    example: Subscriber with consumerKey 'INVALID_CONSUMER_KEY' doesn't have permissions to complete the request
    Error-400:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          properties:
            Error:
              type: array
              description: An array of error objects giving information about relevant errors.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    description: The origin of the error
                    example: Commercial Event Notifications
                  ReasonCode:
                    type: string
                    description: A unique error code representing the error that occurred
                    example: format.invalid
                  Description:
                    type: string
                    description: A developer-friendly description of the error that occurred
                    example: One or more fields contain invalid data
                  Recoverable:
                    type: boolean
                    description: Can the error be recovered by retrying the same request later?
                    example: false
                  Details:
                    type: string
                    description: Additional details regarding the error that occurred
                    example: Invalid content in request payload
    FieldMapping:
      description: A collection of field definitions any of which can be used to specify matching criteria when creating a subscription.
      type: object
      properties:
        id:
          description: Field mapping id
          type: string
          minLength: 1
          maxLength: 255
          readOnly: true
          example: CNSa91bf379b48a593fd17f07f431bad8fb296796498f4e9982ea134394c1fa4f071556724073
        name:
          description: The name used to refer to the field in the specification criteria.
          type: string
          minLength: 1
          maxLength: 255
          example: purchaseRequest.rcnAlias
        displayName:
          description: Descriptive name of the field
          type: string
          minLength: 1
          maxLength: 255
          example: Purchase request RCN alias
        subjectType:
          description: The type of subject to which the field refers. Currently allowed values are 'PAYMENT_AUTHORIZATION', 'PAYMENT_UPDATE', 'CLEARING', 'BPC_PAYMENT_AUTHORIZATION', 'TOKEN_PROVISIONING_EVENT' and 'TOKEN_LIFECYCLE_EVENT'.
          type: string
          minLength: 1
          maxLength: 50
          example: PAYMENT_AUTHORIZATION
        contentType:
          description: What type of information the field (and therefore the matching criteria for that field) will contain. Currently one of allowed values are 'INTEGER', 'number', 'TEXT', 'DATE', 'CURRENCY'.
          type: string
          default: TEXT
          example: TEXT