swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Scopes 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: Scopes
paths:
  /scopes/{arid}:
    get:
      summary: To retrieve the scopes and RP details associated with the arid. The ARID must be in PENDING status.
      tags:
      - Scopes
      responses:
        '200':
          $ref: '#/components/responses/RPScopesSuccessResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      description: "To retrieve the requested scopes and RP details associated with the ARID.   \n**This API is mandatory.**\n"
      operationId: retrieveRPScopes
      parameters:
      - $ref: '#/components/parameters/AridParameter'
  /scope-fulfillments/{arid}:
    put:
      parameters:
      - $ref: '#/components/parameters/AridParameter'
      - $ref: '#/components/parameters/XEncryptedPayload'
      tags:
      - Scopes
      responses:
        '200':
          $ref: '#/components/responses/ScopeFulfillmentResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      description: "Process claims data  provided by the IDP for the corresponding RP authentication.   \nRequest scopes and update the authentication request.   \n **This API is mandatory.**\n"
      summary: To process the IDP claims and update the authentication request with the claims data. The Relying party can get these claims data via RP claim sharing endpoint.
      operationId: ProcessClaimsRequestedScopes
      requestBody:
        $ref: '#/components/requestBodies/ScopeFulfillmentRequest'
  /claims/scopes/{arid}:
    get:
      summary: Share an Identity with an External RP - Retrieve details of the scope request being made by an RP.
      tags:
      - Scopes
      responses:
        '200':
          $ref: '#/components/responses/RPScopesSuccessResponse_2'
        '400':
          $ref: '#/components/responses/BadRequestError_2'
        '401':
          $ref: '#/components/responses/UnauthorizedError_2'
        '404':
          $ref: '#/components/responses/NotFoundError_2'
      description: "Used to retrieve the scopes and RP details associated with the ARID. Does not require a minimum authentication standard.   \n**This API is mandatory.**\n"
      operationId: retrieveCSScopes
      parameters:
      - $ref: '#/components/parameters/AridParameter_2'
components:
  responses:
    UnauthorizedError:
      description: Unauthorized request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorWrapper'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    RPScopesSuccessResponse:
      description: Success response.
      headers:
        X-Transaction-ID:
          $ref: '#/components/headers/X-Transaction-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RPScopes'
    NotFoundError:
      description: The target resource has not been found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorWrapper'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample'
    ScopeFulfillmentResponse:
      description: Success response.
      headers:
        X-Transaction-ID:
          $ref: '#/components/headers/X-Transaction-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IDPScopesAuthorizationData'
          examples:
            ScopeFulfillmentResponseUnencryptedExample:
              $ref: '#/components/examples/IDPScopesAuthorizationDataResponseExample'
            ScopeFulfillmentResponseEncryptedExample:
              $ref: '#/components/examples/EncryptedPayloadNoPDSExample'
    BadRequestError:
      description: The server cannot process the request due to bad request. client should consider correcting the request before retrying again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorWrapper'
          examples:
            BadRequestClaimsEmptyExample:
              $ref: '#/components/examples/BadRequestClaimsEmptyExample'
            BadRequestInvalidFormatExample:
              $ref: '#/components/examples/BadRequestInvalidFormatExample'
            BadRequestInvalidClaimsExample:
              $ref: '#/components/examples/BadRequestInvalidClaimsExample'
    UnauthorizedError_2:
      description: Unauthorized request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    BadRequestError_2:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            UserProfileDeletedErrorExample:
              $ref: '#/components/examples/UserProfileDeletedErrorExample'
    RPScopesSuccessResponse_2:
      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/RPScopes_2'
    NotFoundError_2:
      description: The request didn't match an existing resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            NotFoundExample:
              $ref: '#/components/examples/NotFoundExample_2'
  schemas:
    RPScopes:
      required:
      - scopes
      - rpName
      - rpLogoUrl
      type: object
      properties:
        scopes:
          type: array
          items:
            type: string
            example: name:0:365
            description: The list of scopes that have been requested.
        rpName:
          type: string
          minLength: 1
          maxLength: 255
          example: THISRP
          description: RP Name
          pattern: ^[a-zA-Z\s ,.'-]{1,255}$
        rpLogoUrl:
          type: string
          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,})$
          description: The URL of the logo of the RP.
          example: https://www.rpsite.com/logo.jpg
    ApiError:
      type: object
      properties:
        Source:
          type: string
          description: Source of where the error occurred.
          minLength: 3
          maxLength: 50
          example: mids
        ReasonCode:
          type: string
          description: Code of the error.
          minLength: 5
          maxLength: 100
          example: BAD_REQUEST
        Description:
          type: string
          description: The cause of the error.
          minLength: 10
          maxLength: 250
          example: Claims in the request are empty
        Recoverable:
          type: boolean
          description: Indicates if the error can be recovered from.
          example: false
        Details:
          type: string
          description: Contains information about the error.
          minLength: 10
          maxLength: 1000
          example: IOException Occurred
    IDPClaim:
      required:
      - claim
      - values
      type: object
      properties:
        claim:
          maxLength: 255
          minLength: 1
          description: A unique claim name particular to a scope requested by the relying party.
          type: string
          example: address:0:250
        values:
          type: array
          items:
            $ref: '#/components/schemas/IDPIndividualClaim'
          description: List of values particular to a scope requested by the relying party.
          minItems: 1
    IDPIndividualClaim:
      required:
      - name
      - value
      type: object
      properties:
        name:
          maxLength: 255
          minLength: 1
          description: A single claim name.
          type: string
          example: address
        value:
          maxLength: 255
          minLength: 1
          description: The claim value.
          type: string
          example: 2102 North Square Blvd.
    ApiErrorWrapper:
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/ApiErrors'
    IDPScopesAuthorizationData:
      required:
      - redirectUri
      type: object
      properties:
        redirectUri:
          description: URL where IDP would redirect authorization response to be consumed by relying party
          type: string
          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: http://rp.com/auth?code=xcxxzaas3&state=xccx234
    ApiErrors:
      description: List of errors.
      example:
        $ref: '#/components/examples/NotFoundExample'
      required:
      - Error
      type: object
      properties:
        Error:
          $ref: '#/components/schemas/ApiErrorList'
    ApiErrorList:
      description: Error Details.
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/ApiError'
    IDPScopesAuthorization:
      required:
      - claims
      - userConsent
      type: object
      properties:
        claims:
          description: Claims for RP requested scopes.
          type: array
          items:
            $ref: '#/components/schemas/IDPClaim'
          example:
          - claim: address:0:250
            values:
            - name: address
              value: 2102 North Square Blvd
          - claim: govtId:0:100
            values:
            - name: firstName
              value: abc
            - name: lastName
              value: xyz
            - name: dateOfBirth
              value: '1990-12-12'
          minItems: 1
        userConsent:
          maxLength: 8
          minLength: 6
          enum:
          - ACCEPT
          - DECLINE
          - REVOKE
          - EXPIRE
          type: string
          example: ACCEPT
          description: Attribute used to signify the user consent. If consent is other than 'ACCEPT' redirect url will be provided with the error details.
        locale:
          type: string
          example: en-US
          pattern: ^[a-z]{2}-[a-zA-Z]{2}$
          description: 'IETF BCP 47 Format E.g. "en-GB" (English - United Kingdom), "es-MX" (Spanish - Mexico). More information: Locale ID (LCID) as defined by Microsoft. Not required. The default value is "en-US".'
        countryCode:
          description: ISO-3166 Alpha-2 standard.
          type: string
          example: US
          pattern: ^[a-zA-Z]{2}$
    RPScopes_2:
      required:
      - scopes
      - rpName
      - rpLogoUrl
      type: object
      properties:
        scopes:
          type: array
          items:
            type: string
            description: The list of scopes that have been requested.
            example: name:0:365
        rpName:
          type: string
          description: RP Name.
          minLength: 1
          maxLength: 255
          example: THISRP
        rpLogoUrl:
          type: string
          description: The URL of the logo of the RP.
          minLength: 1
          example: https://www.rpsite.com/logo.jpg
    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
  examples:
    BadRequestInvalidFormatExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: BAD_REQUEST
            Description: Claims in the request are empty.
            Recoverable: false
            Details: Invalid Date format. Valid format expected is 'YYYY-MM-DD'
    UnauthorizedExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: UNAUTHORIZED_REQUEST
            Description: Unauthorized request.
            Recoverable: false
    IDPScopesAuthorizationRequestExample:
      value:
        claims:
        - claim: address:0:250
          values:
          - name: address
            value: 2102 North Square Blvd
        - claim: govtId:0:100
          values:
          - name: firstName
            value: abc
          - name: lastName
            value: xyz
          - name: dateOfBirth
            value: '1990-12-12'
        userConsent: ACCEPT
        locale: en-US
        countryCode: US
    EncryptedPayloadNoPDSExample:
      value:
        encryptedData: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyf
    IDPScopesAuthorizationDataResponseExample:
      value:
        redirectUri: http://rp.com/auth?code=xcxxzaas3&state=xccx234
    NotFoundExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: CLAIM_SHARING_ARID_DOES_NOT_EXIST
            Description: ARID does not exist.
            Recoverable: false
    BadRequestClaimsEmptyExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: BAD_REQUEST
            Description: Claims in the request are empty.
            Recoverable: false
    BadRequestInvalidClaimsExample:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: INVALID_CLAIMS
            Description: Provided claims are invalid.
            Recoverable: false
            Details: Claims are invalid. System defined claims for a mandatory scope 'ageOver' can't be empty
    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
    NotFoundExample_2:
      value:
        Errors:
          Error:
          - Source: mids
            ReasonCode: USER_PROFILE_ID_NOT_FOUND
            Description: The provided user profile ID does not exist.
            Recoverable: false
  parameters:
    AridParameter:
      name: arid
      in: path
      description: UUID represents the ARID.
      example: df52649e-4096-456a-bca0-751ee470009f
      required: true
      schema:
        maxLength: 36
        minLength: 36
        type: string
        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}$
    XEncryptedPayload:
      in: header
      name: X-Encrypted-Payload
      example: true
      description: 'Indicator that request is encrypted or to indicate that client is able to receive a encrypted response. If not set, payload will treated as plaintext.

        '
      schema:
        type: boolean
    AridParameter_2:
      name: arid
      in: path
      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. .
      example: df52649e-4096-456a-bca0-751ee470009f
      required: true
      schema:
        type: string
        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}$
        maxLength: 36
        minLength: 36
  requestBodies:
    ScopeFulfillmentRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IDPScopesAuthorization'
          examples:
            ScopeFulfillmentRequestUnencryptedExample:
              $ref: '#/components/examples/IDPScopesAuthorizationRequestExample'
            ScopeFulfillmentRequestEncryptedExample:
              $ref: '#/components/examples/EncryptedPayloadNoPDSExample'
      required: true
  headers:
    X-Transaction-ID:
      schema:
        type: string
      description: A random 128-bit UUID represents the transaction.