swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Issuing 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: Issuing
paths:
  /source-verifications/{issuing_country}/medicare-cards:
    post:
      x-mastercard-api-encrypted: true
      summary: Verifies the details of a medicare card document with an identity verification provider
      tags:
      - Issuing
      responses:
        '200':
          $ref: '#/components/responses/MedicareCardSourceVerificationResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      description: Returns the status of the Medicare Card source verification as it's being processed by the vendor. Biometrics are not used with this API, which means document scanning is not required for the users to verify their identity. This will be a one-time verification with no data being stored.
      operationId: verifyMedicareCard
      parameters:
      - $ref: '#/components/parameters/IssuingCountryParameter'
      - $ref: '#/components/parameters/EncryptedPayloadParameter'
      requestBody:
        $ref: '#/components/requestBodies/MedicareCardSourceVerificationRequest'
  /source-verifications/{issuing_country}/passports:
    post:
      x-mastercard-api-encrypted: true
      summary: Verifies the details of a passport document with an identity verification provider
      tags:
      - Issuing
      responses:
        '200':
          $ref: '#/components/responses/PassportSourceVerificationResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      description: Returns the Status of the Source Verification that has been processed by a trusted IVP.
      operationId: verifyPassport
      parameters:
      - $ref: '#/components/parameters/IssuingCountryParameter'
      - $ref: '#/components/parameters/EncryptedPayloadParameter'
      requestBody:
        $ref: '#/components/requestBodies/PassportSourceVerificationRequest'
  /source-verifications/{issuing_country}/driving-licenses:
    post:
      x-mastercard-api-encrypted: true
      summary: Verifies the details of a driving license document with an identity verification provider
      tags:
      - Issuing
      responses:
        '200':
          $ref: '#/components/responses/DriversLicenseSourceVerificationResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      description: Returns the Status of the Source Verification that has been processed by a trusted IVP.
      operationId: verifyDriversLicense
      parameters:
      - $ref: '#/components/parameters/IssuingCountryParameter'
      - $ref: '#/components/parameters/EncryptedPayloadParameter'
      requestBody:
        $ref: '#/components/requestBodies/DriversLicenseSourceVerificationRequest'
components:
  schemas:
    MedicareCardSourceVerificationRequestAttributes:
      required:
      - userConsent
      - cardColor
      - nameLine1
      - medicareCardNo
      - individualReferenceNo
      - countryCode
      - expiryDate
      properties:
        userConsent:
          description: The value which best reflects the input of the User with regard to consent to use their data.
          enum:
          - ACCEPT
          - DECLINE
          - REVOKE
          - EXPIRE
          type: string
          example: ACCEPT
          minLength: 6
          maxLength: 7
        cardColor:
          description: Medicard Color can be GREEN, BLUE OR YELLOW.
          enum:
          - GREEN
          - BLUE
          - YELLOW
          type: string
          example: BLUE
          minLength: 4
          maxLength: 6
        nameLine1:
          description: Name Line 1.
          example: Smith
          type: string
          minLength: 1
          maxLength: 27
          pattern: ^[a-zA-Z\s ,.'-]{1,27}$
        medicareCardNo:
          description: Unique number for Medicare card.
          type: string
          maxLength: 10
          example: '1234567890'
          pattern: ^[0-9]{10}$
        individualReferenceNo:
          description: Individual Reference Number.
          type: string
          maxLength: 1
          example: '1'
          pattern: ^[0-9]{1}$
        countryCode:
          description: Country code (case insensitive) as described in the ISO 3166-1 alpha-3 international standard.
          type: string
          example: AUS
          pattern: ^[a-zA-Z]{3}
        expiryDate:
          example: '2000-12-31'
          description: The expiry date as it appears on the card, following the color and format. Green card YYYY-MM, Yellow or Blue card YYYY-MM-DD.
          type: string
          minLength: 7
          maxLength: 10
        nameLine2:
          description: Name Line 2.
          example: Steve
          type: string
          minLength: 1
          maxLength: 25
          pattern: ^[a-zA-Z\s ,.'-]{1,25}$
        nameLine3:
          description: Name Line 3.
          example: Baven
          type: string
          minLength: 1
          maxLength: 23
          pattern: ^[a-zA-Z\s ,.'-]{1,23}$
        nameLine4:
          description: Name Line 4.
          example: Mike
          type: string
          minLength: 1
          maxLength: 21
          pattern: ^[a-zA-Z\s ,.'-]{1,21}$
        birthDate:
          example: '2010-10-25'
          description: YYYY-MM-DD format.
          type: string
          format: date
          minLength: 10
          maxLength: 10
          pattern: ^[0-9]{4}-[0-1][0-9]-[0-3][0-9]
    MedicareCardSourceVerificationResult:
      required:
      - verificationResult
      type: object
      properties:
        verificationResult:
          type: string
          example: DOCUMENT_VERIFIED
          description: 'Verification Results, following : DOCUMENT_VERIFIED - Document matches with the IVP registered document, DOCUMENT_NOT_VERIFIED - Document does not match with any of the IVP registered document, DOCUMENT_INVALID - Document is invalid or not electronically captured.'
          minLength: 16
          maxLength: 21
    ApiError:
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    PassportSourceVerificationRequestAttributes:
      required:
      - documentNumber
      - userConsent
      - firstName
      - lastName
      - dateOfBirth
      type: object
      properties:
        documentNumber:
          description: Document Number.
          type: string
          example: N1234567
          pattern: ^[0-9a-zA-Z\-]{1,50}$
        userConsent:
          description: The value which best reflects the input of the User with regard to consent to use their data.
          enum:
          - ACCEPT
          - DECLINE
          - REVOKE
          - EXPIRE
          type: string
          example: ACCEPT
          minLength: 6
          maxLength: 7
        dateOfBirth:
          description: YYYY-MM-DD format.
          type: string
          format: date
          example: '1990-01-01'
          pattern: ^[0-9]{4}-[0-1][0-9]-[0-3][0-9]$
        firstName:
          description: Users First Name.
          type: string
          example: John
          pattern: ^[a-zA-Z\s ,.'-]{1,255}$
        lastName:
          description: Users Last Name.
          type: string
          example: Smith
          pattern: ^[a-zA-Z\s ,.'-]{1,255}$
        gender:
          description: Users Gender.
          type: string
          example: M
          pattern: ^[M|F|X]$
        visaMatched:
          type: boolean
          description: Whether visa verification is required.
          example: true
        visaIssuingCountry:
          description: Visa issuing country.
          type: string
          example: AUS
          pattern: ^[A-Z]{3}$
    DriversLicenseSourceVerificationRequestAttributes:
      required:
      - documentNumber
      - userConsent
      - firstName
      - lastName
      - dateOfBirth
      - stateCode
      - cardNumber
      type: object
      properties:
        documentNumber:
          description: Document Number.
          type: string
          example: AB001234567
          pattern: ^[0-9a-zA-Z\-]{1,50}$
        userConsent:
          description: The value which best reflects the input of the User with regard to consent to use their data.
          enum:
          - ACCEPT
          - DECLINE
          - REVOKE
          - EXPIRE
          type: string
          example: ACCEPT
          minLength: 6
          maxLength: 7
        dateOfBirth:
          description: YYYY-MM-DD format.
          type: string
          format: date
          example: '1990-01-01'
          pattern: ^[0-9]{4}-[0-1][0-9]-[0-3][0-9]$
        firstName:
          description: Users First Name.
          type: string
          example: John
          pattern: ^[a-zA-Z\s ,.'-]{1,255}$
        lastName:
          description: Users Last Name.
          type: string
          example: Smith
          pattern: ^[a-zA-Z\s ,.'-]{1,255}$
        stateCode:
          description: State code.
          type: string
          example: NSW
          pattern: ^[a-zA-Z]{2,3}$
        cardNumber:
          description: Users DVS Card Number.
          type: string
          example: AB45864
    Errors:
      description: List of Errors.
      example:
        $ref: '#/components/examples/NotFoundExample'
      required:
      - Error
      type: object
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    ErrorList:
      description: Error Details.
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    SourceVerificationResult:
      required:
      - verificationResult
      type: object
      properties:
        verificationResult:
          type: string
          description: 'Verification Results, following : DOCUMENT_VERIFIED - Document matches with the IVP registered document, DOCUMENT_NOT_VERIFIED - Document does not match with any of the IVP registered document, DOCUMENT_INVALID - Document is invalid or not electronically captured.'
          example: DOCUMENT_VERIFIED
          minLength: 16
          maxLength: 21
    Error:
      type: object
      properties:
        Source:
          type: string
          description: Source of where the error occured.
          example: mids
        ReasonCode:
          type: string
          description: Code of the error.
          example: USER_PROFILE_ID_NOT_FOUND
        Description:
          type: string
          description: The cause of the error
          example: The provided userProfileId does not exist
        Recoverable:
          type: boolean
          description: Indiciates if the error can be recovered from.
          example: false
        Details:
          type: string
          description: Contains information about the error.
          example: IOException Occured
  examples:
    SourceVerDrivingLicenceExample:
      value:
        documentNumber: AB001234567
        userConsent: ACCEPT
        dateOfBirth: '1990-01-01'
        firstName: John
        lastName: Smith
        stateCode: NSW
        cardNumber: '1867530950'
    MedicareDataNotMatchedExample:
      value:
        verificationResult: DOCUMENT_NOT_VERIFIED
    BadRequestExampleIVPConnectionTimeout:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: IVP_CONNECTION_TIMEOUT
            Description: Connection timeout when trying to connect with the Identity Verification Provider. Please look at 'details' for additional information.
            Recoverable: false
            Details: Received Connection TimeOut Exception
    MedicareDocumentInvalidExample:
      value:
        verificationResult: DOCUMENT_INVALID
        reason: Provided data is invalid or not electronically captured
    BadRequestExampleCountryCode:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value US4 for 'countryCode'.
            Recoverable: false
            Details: null
    BadRequestExampleIVPSystemError:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: IVP_SYSTEM_ERROR
            Description: Received system error from the Identity Verification Provider. Please look at 'details' for additional information.
            Recoverable: false
            Details: System Error Received
    BadRequestExampleMedicareName:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value for 'nameLine' field OR value exceeds allowed max characters.
            Recoverable: false
            Details: null
    BadRequestExampleUserConsent:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Unexpected value 'Invalid' for enumerate field.
            Recoverable: false
            Details: null
    BadRequestExampleMedicareCountryCode:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value for 'Country code'.
            Recoverable: false
            Details: null
    SourceVerPassportExample:
      value:
        documentNumber: N1234567
        userConsent: ACCEPT
        dateOfBirth: '1990-01-01'
        firstName: John
        lastName: Smith
        gender: M
        visaMatched: true
        visaIssuingCountry: AUS
    ForbiddenExampleUnauthorizedScopedFields:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: UNAUTHORIZED_SCOPED_FIELDS
            Description: 'UNAUTHORIZED_SCOPED_FIELDS: Requested scoped fields are not part of whitelisted fields.'
            Recoverable: false
            Details: null
    BadRequestExampleDocumentMismatch:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: BAD_REQUEST
            Description: The document uploaded by the User does not comply to the document type/country specified by the client in the originating access-token request.
            Recoverable: false
            Details: null
    EncryptedPayloadExample:
      value:
        encryptedData: eyJraWQiOiIwMTQyNmRhY2JlMmRjYzA3NmQ1OWU1NDQ5N2NiNjBiMjdjZmQwMDE0ZjZmMGQyYTJiN2FmNjExNDg2NjYyMj...
    BadRequestExampleMedicareIndividualReferenceNo:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value for 'INDIVIDUAL_REFERENCE_NO'.
            Recoverable: false
            Details: null
    BadRequestExampleMedicareExpireDate:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value for 'expiry date'.
            Recoverable: false
            Details: null
    BadRequestExampleMedicareUserConsent:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: User consent not given.
            Recoverable: false
            Details: null
    NotFoundExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: USER_PROFILE_ID_NOT_FOUND
            Description: The provided userProfileId does not exist.
            Recoverable: false
    BadRequestExampleMedicareMedicareNumber:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value for 'Medicare card number'.
            Recoverable: false
            Details: null
    BadRequestExamplePhoneNumber:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value ASD for 'phoneNumber'.
            Recoverable: false
            Details: null
    MedicareSuccessExample:
      value:
        verificationResult: DOCUMENT_VERIFIED
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: CONSENT_NOT_GIVEN
            Description: User Consent Not Given.
            Recoverable: false
  requestBodies:
    DriversLicenseSourceVerificationRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DriversLicenseSourceVerificationRequestAttributes'
          examples:
            SourceVerDrivingLicenceExample:
              $ref: '#/components/examples/SourceVerDrivingLicenceExample'
      required: true
    MedicareCardSourceVerificationRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MedicareCardSourceVerificationRequestAttributes'
      required: true
    PassportSourceVerificationRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PassportSourceVerificationRequestAttributes'
          examples:
            SourceVerPassportExample:
              $ref: '#/components/examples/SourceVerPassportExample'
            EncryptedPayloadExample:
              $ref: '#/components/examples/EncryptedPayloadExample'
      required: true
  responses:
    NotFoundError:
      description: Request didn't match an existing resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample'
    PassportSourceVerificationResponse:
      description: Success.
      headers:
        X-Transaction-ID:
          $ref: '#/components/headers/X-Transaction-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SourceVerificationResult'
    ForbiddenError:
      description: Consent not given.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            ForbiddenExample:
              $ref: '#/components/examples/ForbiddenExample'
            ForbiddenExampleUnauthorizedScopedFields:
              $ref: '#/components/examples/ForbiddenExampleUnauthorizedScopedFields'
    DriversLicenseSourceVerificationResponse:
      description: Success.
      headers:
        X-Transaction-ID:
          $ref: '#/components/headers/X-Transaction-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SourceVerificationResult'
    BadRequestError:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            BadRequestExampleUserConsent:
              $ref: '#/components/examples/BadRequestExampleUserConsent'
            BadRequestExampleCountryCode:
              $ref: '#/components/examples/BadRequestExampleCountryCode'
            BadRequestExamplePhoneNumber:
              $ref: '#/components/examples/BadRequestExamplePhoneNumber'
            BadRequestExampleIVPConnectionTimeout:
              $ref: '#/components/examples/BadRequestExampleIVPConnectionTimeout'
            BadRequestExampleIVPSystemError:
              $ref: '#/components/examples/BadRequestExampleIVPSystemError'
            BadRequestExampleMedicareExpireDate:
              $ref: '#/components/examples/BadRequestExampleMedicareExpireDate'
            BadRequestExampleMedicareName:
              $ref: '#/components/examples/BadRequestExampleMedicareName'
            BadRequestExampleMedicareIndividualReferenceNo:
              $ref: '#/components/examples/BadRequestExampleMedicareIndividualReferenceNo'
            BadRequestExampleMedicareMedicareNumber:
              $ref: '#/components/examples/BadRequestExampleMedicareMedicareNumber'
            BadRequestExampleMedicareCountryCode:
              $ref: '#/components/examples/BadRequestExampleMedicareCountryCode'
            BadRequestExampleMedicareUserConsent:
              $ref: '#/components/examples/BadRequestExampleMedicareUserConsent'
            BadRequestExampleDocumentMismatch:
              $ref: '#/components/examples/BadRequestExampleDocumentMismatch'
    MedicareCardSourceVerificationResponse:
      description: Success.
      headers:
        X-Transaction-ID:
          $ref: '#/components/headers/X-Transaction-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MedicareCardSourceVerificationResult'
          examples:
            MedicareSuccessExample:
              $ref: '#/components/examples/MedicareSuccessExample'
            MedicareDataNotMatchedExample:
              $ref: '#/components/examples/MedicareDataNotMatchedExample'
            MedicareDocumentInvalidExample:
              $ref: '#/components/examples/MedicareDocumentInvalidExample'
  headers:
    X-Transaction-ID:
      schema:
        type: string
        example: 2d077b9c-3c06-44ac-b00e-d78fe8cce606
        description: A random 128-bit UUID representing the transaction.
  parameters:
    IssuingCountryParameter:
      name: issuing_country
      in: path
      description: Country of issue for the document in the ISO 3166-1 alpha-3 format, only AUS is an acceptable value for this parameter.
      example: AUS
      required: true
      schema:
        type: string
        pattern: ^[A-Z]{3}
    EncryptedPayloadParameter:
      name: X-Encrypted-Payload
      in: header
      description: Whether the request payload is encrypted with the Encyption Key generated from the Developer Zone Portal.
      example: true
      required: false
      schema:
        type: boolean