swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Initiate 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: Initiate
paths:
  /initiate-authentications:
    post:
      tags:
      - Initiate
      responses:
        '200':
          $ref: '#/components/responses/InitiateAuthenticationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      description: "Initialize authentication based on the information provided in PDS.   \n**This API is mandatory.**\n"
      summary: 'Authenticate a user using Liveness Assurance, this is a more performant, but less stringent form of authentication, which will enable the user to access, but not change certain details of their identity.

        '
      operationId: initializeAuthentication
      parameters:
      - $ref: '#/components/parameters/XEncryptedPayload'
      requestBody:
        $ref: '#/components/requestBodies/InitializeAuthenticationsRequest'
  /initiate-premium-authentications:
    post:
      tags:
      - Initiate
      responses:
        '200':
          $ref: '#/components/responses/InitiateAuthenticationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      description: "This API returns a token for initiating the premium authentication process\nusing SDK.   \n**This API is mandatory.**\n"
      summary: Authenticate a user using Genuine Presence Assurance, this is a less performant, but more stringent form of authentication, which will enable the user to manage all aspects of their identity.
      operationId: initiateStrongerAuthentication
      parameters:
      - $ref: '#/components/parameters/XEncryptedPayload'
      requestBody:
        $ref: '#/components/requestBodies/InitializePremiumAuthenticationsRequest'
components:
  schemas:
    TpAuditMetadata:
      required:
      - sessionId
      - transactionGroupId
      type: object
      description: Object containing metadata related to the request.
      properties:
        sessionId:
          type: string
          description: UUID which uniquely identifies a set of transactions being executed within the same authentication session.
          pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
          minLength: 36
          maxLength: 36
          example: be3ad617-04ad-43e1-a438-79425b6511b6
        transactionGroupId:
          type: string
          description: UUID which uniquely identifies a set of transactions being executed within a single use-case.
          pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
          minLength: 36
          maxLength: 36
          example: be3ad617-04ad-43e1-a438-79425b6511b6
    Locale:
      type: string
      description: IETF BCP 47 code which identifies the language to be used in any dialogs being shown to the user during the flow.  The default value is "en-US".
      pattern: ^[a-z]{2}-[a-zA-Z]{2}$
      example: en-US
    PDS:
      type: string
      description: Encrypted Personal Device Storage (PDS) which hosts the users identity attributes. The PDS can be retrieved from the MIDS Core SDK, please refer to the SDK guide for details on how to retrieve this.
      pattern: ^(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?$
      minLength: 1
      example: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    ErrorResponse:
      required:
      - Errors
      type: object
      description: The error response model used by all the API endpoints.
      properties:
        Errors:
          required:
          - Error
          type: object
          description: The error response model used by all the API endpoints.
          properties:
            Error:
              type: array
              description: A list of Error objects.
              minItems: 1
              items:
                type: object
                properties:
                  Source:
                    type: string
                    description: The source of the problem. That is where the error occurred.
                    example: mids
                  ReasonCode:
                    type: string
                    description: A code defining the error, as defined in documentation.
                    example: USER_PROFILE_ID_NOT_FOUND
                  Description:
                    type: string
                    description: A description of this specific occurrence of the Reason code.
                    example: The provided user profile ID does not exist.
                  Recoverable:
                    type: boolean
                    description: Whether or not retrying this request could result in a successful response.
                    example: false
                  Details:
                    type: string
                    description: More details of this specific error. This is an optional field and is sometimes used to give a more comprehensive description of the error that has occurred, when required.
                    example: User X was not found
                  redirectUri:
                    type: string
                    description: TP will use this URI to redirect to RP.
                    pattern: ^(https?:\/\/(?:www\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\.[^\s]{2,}|www\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\.[^\s]{2,}|https?:\/\/(?:www\.|(?!www))[a-zA-Z0-9]+\.[^\s]{2,}|www\.[a-zA-Z0-9]+\.[^\s]{2,})$
                    example: https://sample-rp-redirect-uri.com/?error=invalid_scope&state=AJahbadinvjbdvdnvljkdnvdfhsrbghrtiu4w&ARID=1234&error_description=claim_not_satisfied
    AuditEventsItem:
      type: object
      properties:
        dateTime:
          type: string
          description: Date and time at which the event is created.
          minLength: 1
          maxLength: 29
          example: '2020-01-28T13:16:01.714-05:00'
        softwareVersion:
          type: string
          description: Software version.
          minLength: 1
          maxLength: 30
          example: 1.0.0
        userProfileId:
          type: string
          description: UUID identifying the user, which the TP App generates using the MIDS Core SDK.
          pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
          example: df52649e-4096-456a-bca0-751ee470009f
        sessionId:
          type: string
          description: UUID which uniquely identifies a set of transactions being executed within the same authentication session.
          pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
          minLength: 36
          maxLength: 36
          example: 123ae1aa-6744-433e-879d-7da48d631234
        transactionGroupId:
          type: string
          description: UUID which uniquely identifies a set of transactions being executed within a single use-case.
          pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
          minLength: 36
          maxLength: 36
          example: 28eae1aa-6744-433e-879d-7da48d63e89a
        logRequestFlow:
          type: string
          description: Log Request Flow.
          minLength: 1
          maxLength: 255
          example: CoreSDK-TP
        logEvent:
          type: string
          description: Log Event.
          minLength: 0
          maxLength: 255
          example: ID Enrollment
        logEventType:
          type: string
          description: Log Event Type.
          minLength: 1
          maxLength: 255
          example: User Profile Creation
        osVersion:
          type: string
          description: OS version.
          minLength: 1
          maxLength: 255
          example: Android 5.0
        deviceMake:
          type: string
          description: Device make.
          minLength: 1
          maxLength: 255
          example: Samsung S10
        type:
          type: string
          description: Type of the event.
          minLength: 1
          maxLength: 255
          example: audit
        audit:
          type: object
          description: Represents the audit event.
          properties:
            privacyPolicy:
              type: string
              description: Version user confirmed.
              minLength: 1
              maxLength: 20
              example: 1.0.0
            userBiometricConsent:
              type: string
              description: User consent to capture details.
              enum:
              - 'TRUE'
              - 'FALSE'
              - NA
              minLength: 4
              maxLength: 5
              example: 'TRUE'
            event:
              type: string
              description: Event.
              minLength: 1
              maxLength: 255
              example: Document Scan
            eventType:
              type: string
              description: EventType.
              minLength: 1
              maxLength: 255
              example: Enrollment
            result:
              type: string
              description: API Call result.
              enum:
              - 'TRUE'
              - 'FALSE'
              - FAIL
              minLength: 4
              maxLength: 5
              example: 'TRUE'
            eventGeneratedSource:
              type: string
              description: Event generated source.
              minLength: 1
              maxLength: 50
              example: CoreSDK
            owner:
              type: string
              description: Owner.
              minLength: 2
              maxLength: 4
              example: TP
            requestDetails:
              type: object
              description: Request Details.
              example: Request URL
            responseDetails:
              type: object
              description: Response Details.
              example: Response Data
    SdkVersion:
      type: string
      description: Mastercard SDK version integrated with TP App, it is a constant extracted from MIDS SDK Configurations (generated while bundling SDK artifacts). If the TP app supports split PDS, this attribute MUST be specified.
      pattern: ^[0-9]{1,5}\.[0-9]{1,5}\.[0-9]{1,5}$
      minLength: 5
      maxLength: 255
      example: 2.3.0
    UserConsent:
      enum:
      - ACCEPT
      - DECLINE
      - REVOKE
      - EXPIRE
      type: string
      description: Confirmation provided by the TP that the user has consented that the ID-Network can have access to their identity for the purposes of the API call. Should be ACCEPT, a forbidden exception will be thrown if it is any other value.
      pattern: ^(ACCEPT|DECLINE|REVOKE|EXPIRE)$
      minLength: 6
      maxLength: 7
      example: ACCEPT
    InitializeAuthentications:
      required:
      - countryCode
      - sdkVersion
      - userProfileId
      - userConsent
      - channelType
      - pds
      - locale
      type: object
      properties:
        deviceInfo:
          $ref: '#/components/schemas/DeviceInfo'
        isNewDeviceAppId:
          type: boolean
          description: A flag indicating that this is the first time the identity is being accessed on a new device, usually as a result of a backup and restore.
          example: false
        countryCode:
          $ref: '#/components/schemas/CountryCode'
        sdkVersion:
          $ref: '#/components/schemas/SdkVersion'
        userProfileId:
          type: string
          description: UUID identifying the user, which the TP App generates using the MIDS Core SDK.
          pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
          example: df52649e-4096-456a-bca0-751ee470009f
        pds:
          $ref: '#/components/schemas/PDS'
        userConsent:
          $ref: '#/components/schemas/UserConsent'
        locale:
          $ref: '#/components/schemas/Locale'
        channelType:
          type: string
          description: The platform from where the request is originating Web/SDK.
          enum:
          - WEB
          - SDK
          minLength: 3
          maxLength: 3
          example: WEB
        sdkAuditEvents:
          type: array
          description: Array of objects containing a record of any auditable steps occurring between the App and the SDK. A call must be made by the TP App from the MIDS Audit SDK prior to all API calls, with any audit events included in the subsequent call.
          items:
            $ref: '#/components/schemas/AuditEventsItem'
        tpAuditMetadata:
          $ref: '#/components/schemas/TpAuditMetadata'
        arid:
          $ref: '#/components/schemas/ARID'
    InitPremiumAuthentications:
      required:
      - countryCode
      - sdkVersion
      - userProfileId
      - userConsent
      - channelType
      - pds
      - locale
      allOf:
      - $ref: '#/components/schemas/InitializeAuthentications'
    ARID:
      type: string
      description: A unique identifier for any activity being executed arising out of a Claim Share request. This value is passed as a parameter in the URL redirecting a User to the TP Flow during a Claim Share.
      format: uuid
      pattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$
      minLength: 36
      maxLength: 36
      example: a15fa6de-b199-11eb-8529-0242ac130003
    Authentications:
      required:
      - transactionId
      - apiDataCenter
      - sdkToken
      type: object
      properties:
        transactionId:
          type: string
          description: A random 128-bit UUID represents the MIDS transaction.
          minLength: 36
          maxLength: 36
          example: 1ec14310-e85c-11ea-adc1-0242ac120002
        apiDataCenter:
          type: string
          description: Identity verification vendor SDK datacenter to be used by API. Possible values.
          example: SG
          minLength: 1
          maxLength: 2
        sdkToken:
          type: string
          description: Passed into the MIDS verification SDK for authentication.
          minLength: 1
          maxLength: 400
          example: eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAAAB3NQQpCMQwE0Lt0baBJ0yZ159KtN0jTBgTBjYgg3t3__3KGN8w3rc_llc4JG6KUhrmoYjolc7_OvWfPKJ2hUzNgagE2hcC5hsYIUeOdH7gStVr6AtElwNUcrBNDFppYMjqxb9hvKzb9fNzfa4_HVkORomdoggsYp8HgPqAWF43VtsOcfn_stx4UsAAAAA.tDRVowYYcpQ03Vlt7D3MiovleiyRFQMv4qzXb7Lf_6CarphRrlWXan8-jE-YesNiAiT8tk0b-i8TKHGrcgT1VQ
        privacyPolicyVersion:
          type: string
          description: The version of the privacy policy which the API call is being conducted under, this can be retrieved from the MIDS Core SDK.
          minLength: 1
          maxLength: 20
          example: 1.0.0
        privacyPolicyUrl:
          type: string
          description: Privacy policy static URL.
          minLength: 1
          maxLength: 255
          example: https://www.mastercard.us/en-us/vision/corp-responsibility/commitment-to-privacy/privacy.html
        privacyPolicyVersionUpdated:
          type: boolean
          description: Flag indicating if the privacy policy has been updated.
          example: true
        rotatedPds:
          type: string
          description: A rotated PDS is created and returned when the encryption key expires and a new key is generated.
          pattern: ^(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?$
          minLength: 1
          example: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    DeviceInfo:
      description: Object containing the details of the device from which the enrollment is being conducted.
      required:
      - deviceAppId
      - make
      - model
      type: object
      properties:
        deviceAppId:
          type: string
          description: The device application ID is retrieved from the mobile SDK.
          minLength: 1
          maxLength: 255
          example: 599F9C00-92DC-4B5C-9464-7971F01F8370
        make:
          type: string
          description: The make of the mobile device.
          minLength: 1
          maxLength: 255
          example: Samsung
        model:
          type: string
          description: The model of the mobile device.
          minLength: 1
          maxLength: 255
          example: S8
    CountryCode:
      type: string
      description: The country code of the country where the transaction originates from.
      pattern: ^[a-zA-Z]{2}$
      example: US
  examples:
    EncryptedPayloadWithRotatedPDSExample:
      value:
        encryptedData: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IoxNTE2MjM5MDIyf
        rotatedPds: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    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
    AuthenticationsExample:
      value:
        transactionId: 1ec14310-e85c-11ea-adc1-0242ac120002
        apiDataCenter: SG
        sdkToken: eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAAAB3NQQpCMQwE0Lt0baBJ0yZ159KtN0jTBgTBjYgg3t3__3KGN8w3rc_llc4JG6KUhrmoYjolc7_OvWfPKJ2hUzNgagE2hcC5hsYIUeOdH7gStVr6AtElwNUcrBNDFppYMjqxb9hvKzb9fNzfa4_HVkORomdoggsYp8HgPqAWF43VtsOcfn_stx4UsAAAAA.tDRVowYYcpQ03Vlt7D3MiovleiyRFQMv4qzXb7Lf_6CarphRrlWXan8-jE-YesNiAiT8tk0b-i8TKHGrcgT1VQ
        privacyPolicyVersion: 1.0.0
        privacyPolicyUrl: https://www.mastercard.us/en-us/vision/corp-responsibility/commitment-to-privacy/privacy.html
        privacyPolicyVersionUpdated: true
        rotatedPds: ZGZnZGVmZ2RnZGVnZXJnZXJncmRnZXJ5aGdld3J0eWJld3J5dHdleXd5d3l3cmFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh
    UserProfileDeletedErrorExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: USER_PROFILE_DELETED
            Description: 'USER_PROFILE_DELETED: ID of the deleted profile.'
            Recoverable: false
            redirectUri: https://sample-rp-redirect-uri.com?error=server_error&state=AJahbadinvjbdvdnvljkdnvdfhsrbghrtiu4w
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: CONSENT_NOT_GIVEN
            Description: User Consent Not Given.
            Recoverable: false
  requestBodies:
    InitializePremiumAuthenticationsRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InitPremiumAuthentications'
      required: true
    InitializeAuthenticationsRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InitializeAuthentications'
      required: true
  responses:
    InitiateAuthenticationsResponse:
      description: Success.
      headers:
        X-Transaction-ID:
          schema:
            type: string
          description: A random 128-bit UUID represents the transaction.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Authentications'
          examples:
            InitiateAuthenticationsUnencryptedResponse:
              $ref: '#/components/examples/AuthenticationsExample'
            InitiateAuthenticationsEncryptedResponse:
              $ref: '#/components/examples/EncryptedPayloadWithRotatedPDSExample'
    ForbiddenError:
      description: Consent not given.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ForbiddenExample:
              $ref: '#/components/examples/ForbiddenExample'
            ForbiddenExampleUnauthorizedScopedFields:
              $ref: '#/components/examples/ForbiddenExampleUnauthorizedScopedFields'
    BadRequestError:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            UserProfileDeletedErrorExample:
              $ref: '#/components/examples/UserProfileDeletedErrorExample'
  parameters:
    XEncryptedPayload:
      in: header
      name: X-Encrypted-Payload
      type: boolean
      description: 'An indicator that the request is encrypted or indicates that the client is able to receive an encrypted response. If not set, the payload will be treated as plaintext.

        '
      example: true
      schema: null