swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Email  O T P 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: Email  O T P
paths:
  /email-otps:
    post:
      x-mastercard-api-encrypted: true
      summary: Creates and Send a One-Time Passcode (OTP) via Email
      tags:
      - Email  O T P
      responses:
        '200':
          $ref: '#/components/responses/EmailOtpGenerationSuccessReponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      description: Create and Send a One-Time Passcode (OTP) via Email to the address provided.
      operationId: sendEmailOtp
      requestBody:
        $ref: '#/components/requestBodies/EmailOtpGenerationRequest'
      parameters:
      - $ref: '#/components/parameters/EncryptedPayloadParameter'
components:
  responses:
    UnauthorizedError:
      description: Unauthorized request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    EmailOtpGenerationSuccessReponse:
      description: Success.
      headers:
        X-Transaction-ID:
          $ref: '#/components/headers/X-Transaction-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Otp'
          examples:
            OtpExample:
              $ref: '#/components/examples/OtpExample'
            EncryptedPayloadExample:
              $ref: '#/components/examples/EncryptedPayloadExample'
    ForbiddenError:
      description: Consent not given.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          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/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'
  examples:
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: UNAUTHORIZED_REQUEST
            Description: Unauthorized request.
            Recoverable: false
    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
    BadRequestExampleCountryCode:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: VALIDATION_ERROR
            Description: Invalid value US4 for 'countryCode'.
            Recoverable: false
            Details: null
    OtpExample:
      value:
        otpId: 568def8e-d17b-11ea-87d0-0242ac12343
        transactionId: 689def8e-d17b-89ea-87d0-0242ac12343
    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
    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
    EmailOtpExample:
      value:
        countryCode: BR
        emailAddress: john.dunne@domain.com
        locale: en-GB
        userConsent: ACCEPT
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: CONSENT_NOT_GIVEN
            Description: User Consent Not Given.
            Recoverable: false
  schemas:
    ApiError:
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    EmailOtp:
      required:
      - countryCode
      - emailAddress
      type: object
      properties:
        countryCode:
          description: The ISO 3166-1 alpha2 code which corresponds to the country from where the request to ID is originating from.
          type: string
          example: BR
          pattern: ^[a-zA-Z]{2}$
          minLength: 2
          maxLength: 2
        emailAddress:
          description: The email address in which to send the OTP to.
          type: string
          pattern: ^[\w-\.\'\\]+@([\w-]+\.)+[\w-]{2,4}$
          example: john.dunne@domain.com
          minLength: 1
        locale:
          description: The IETF BCP 47 value which determines the language variant to be applied in the OTP messages.
          type: string
          default: en-US
          example: en-GB
          pattern: ^[a-z]{2}-[a-zA-Z]{2}$
        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
    Errors:
      description: List of Errors.
      example:
        $ref: '#/components/examples/NotFoundExample'
      required:
      - Error
      type: object
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    Otp:
      required:
      - otpId
      - transactionId
      type: object
      properties:
        otpId:
          description: A random 128-bit UUID representing otp request.
          type: string
          example: 471dddb6-7204-4ac6-a94a-fdeb7a094a85
          minLength: 36
          maxLength: 36
        transactionId:
          description: The transaction ID provided in the API response must be logged by the Relying Party. The Relying Party is required to provide the transaction ID when contacting the Mastercard customer support team.
          type: string
          example: bd400bde-8ae1-4d7b-a39e-ebebb94e6d08
          minLength: 36
          maxLength: 36
    ErrorList:
      description: Error Details.
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    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
  headers:
    X-Transaction-ID:
      schema:
        type: string
        example: 2d077b9c-3c06-44ac-b00e-d78fe8cce606
        description: A random 128-bit UUID representing the transaction.
  requestBodies:
    EmailOtpGenerationRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EmailOtp'
          examples:
            EmailOtpExemple:
              $ref: '#/components/examples/EmailOtpExample'
            EncryptedPayloadExample:
              $ref: '#/components/examples/EncryptedPayloadExample'
      required: true
  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