Mastercard Sources API

openapi: 3.2.0
info:
  title: Mastercard ID Verification Sources API
  description: In this digital world, user identity fraud is on the rise due to inadequate digital identity verification methods. The ID Networkopens in a new tab model provides users with greater control of their digital identityopens in a new tab and enables organizations to provide seamless digital interactions with reduced risk. The ID network protects personal data and privacy by allowing individuals to control when and with whom their identity data is shared.
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
  version: 1.0.2
servers:
- url: https://api.mastercard.com.au/idverify
  description: Production server (uses live data)
- url: https://sandbox.api.mastercard.com.au/idverify
  description: Sandbox server (testing environment)
tags:
- name: Sources
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:
      - Sources
      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:
      - Sources
      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:
      - Sources
      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:
  headers:
    X-Transaction-ID:
      schema:
        type: string
        example: 2d077b9c-3c06-44ac-b00e-d78fe8cce606
        description: A random 128-bit UUID representing the transaction.
  responses:
    PassportSourceVerificationResponse:
      description: Success.
      headers:
        X-Transaction-ID:
          $ref: '#/components/headers/X-Transaction-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SourceVerificationResult'
    NotFoundError:
      description: Request didn't match an existing resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample'
    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'
    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'
    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'
  requestBodies:
    MedicareCardSourceVerificationRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MedicareCardSourceVerificationRequestAttributes'
      required: true
    DriversLicenseSourceVerificationRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DriversLicenseSourceVerificationRequestAttributes'
          examples:
            SourceVerDrivingLicenceExample:
              $ref: '#/components/examples/SourceVerDrivingLicenceExample'
      required: true
    PassportSourceVerificationRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PassportSourceVerificationRequestAttributes'
          examples:
            SourceVerPassportExample:
              $ref: '#/components/examples/SourceVerPassportExample'
            EncryptedPayloadExample:
              $ref: '#/components/examples/EncryptedPayloadExample'
      required: true
  examples:
    SourceVerPassportExample:
      value:
        documentNumber: N1234567
        userConsent: ACCEPT
        dateOfBirth: '1990-01-01'
        firstName: John
        lastName: Smith
        gender: M
        visaMatched: true
        visaIssuingCountry: AUS
    BadRequestExampleMedicareCountryCode:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value for 'Country code'.
            Recoverable: false
            Details: null
    BadRequestExampleUserConsent:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Unexpected value 'Invalid' for enumerate field.
            Recoverable: false
            Details: null
    BadRequestExampleMedicareIndividualReferenceNo:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value for 'INDIVIDUAL_REFERENCE_NO'.
            Recoverable: false
            Details: null
    EncryptedPayloadExample:
      value:
        encryptedData: eyJraWQiOiIwMTQyNmRhY2JlMmRjYzA3NmQ1OWU1NDQ5N2NiNjBiMjdjZmQwMDE0ZjZmMGQyYTJiN2FmNjExNDg2NjYyMj...
    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
    MedicareSuccessExample:
      value:
        verificationResult: DOCUMENT_VERIFIED
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: CONSENT_NOT_GIVEN
            Description: User Consent Not Given.
            Recoverable: false
    BadRequestExampleMedicareExpireDate:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value for 'expiry date'.
            Recoverable: false
            Details: null
    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
    BadRequestExampleMedicareUserConsent:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: User consent not given.
            Recoverable: false
            Details: null
    BadRequestExamplePhoneNumber:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value ASD for 'phoneNumber'.
            Recoverable: false
            Details: null
    BadRequestExampleMedicareMedicareNumber:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value for 'Medicare card number'.
            Recoverable: false
            Details: null
    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
    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
    BadRequestExampleCountryCode:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value US4 for 'countryCode'.
            Recoverable: false
            Details: null
    SourceVerDrivingLicenceExample:
      value:
        documentNumber: AB001234567
        userConsent: ACCEPT
        dateOfBirth: '1990-01-01'
        firstName: John
        lastName: Smith
        stateCode: NSW
        cardNumber: '1867530950'
    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
    MedicareDocumentInvalidExample:
      value:
        verificationResult: DOCUMENT_INVALID
        reason: Provided data is invalid or not electronically captured
    MedicareDataNotMatchedExample:
      value:
        verificationResult: DOCUMENT_NOT_VERIFIED
    NotFoundExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: USER_PROFILE_ID_NOT_FOUND
            Description: The provided userProfileId does not exist.
            Recoverable: false
  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]
    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}$
    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
    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
    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'
    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
    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
  parameters:
    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
    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}