swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Donors 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: Donors
  description: Donors
paths:
  /donors:
    post:
      tags:
      - Donors
      summary: Create (Register) Donor API
      description: This API will be used for creating (registering) new users on platform as a Registerd Donor.A card will be added once. Second time, the initial card Id will be returned.Entire request body should be encrypted.
      operationId: addUserUsingPOST
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/CorrelationId'
      - $ref: '#/components/parameters/ProgramId'
      requestBody:
        $ref: '#/components/requestBodies/AddUser'
      responses:
        '200':
          $ref: '#/components/responses/DonateUser'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error-AddUser'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '415':
          $ref: '#/components/responses/Unsupported'
        '500':
          $ref: '#/components/responses/InternalServerError'
      deprecated: false
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-403'
    DonateUser:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DonateUser'
    Unauthorized:
      description: Unauthorised
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-401'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-500'
    Unsupported:
      description: Unsupported Content Type
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-415'
  schemas:
    Error-415:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          description: Contains all errors caused
          properties:
            Error:
              type: array
              description: Only returned in the event of an authorization is failed.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: DONATE_SERVICE
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: UNSUPPORTED_CONTENT_TYPE
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: The request Content-Type (<request content-type value>) is not supported for this service
                    description: Short description of the ReasonCode field
                  Recoverable:
                    type: boolean
                    example: false
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
                  Details:
                    type: string
                    example: 'null'
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing.
    UserName:
      type: object
      required:
      - firstName
      - lastName
      properties:
        firstName:
          type: string
          example: John
          minLength: 3
          maxLength: 30
          description: First Name
        lastName:
          type: string
          example: Doe
          minLength: 3
          maxLength: 30
          description: Last Name
        honorificPrefix:
          type: string
          example: Mr
          minLength: 2
          maxLength: 30
          description: Honorific Prefix
        honorificSuffix:
          type: string
          example: Jr.
          minLength: 2
          maxLength: 30
          description: Honorific Suffix
      title: UserName
    DonateUser:
      type: object
      properties:
        donorId:
          type: string
          minLength: 36
          maxLength: 36
          example: 652ce9ff-fa5f-4e9f-8151-c73fa20088f7
          format: uuid
          description: Valid UUID.
        userName:
          type: string
          example: John.Doe@mail.com
          minLength: 5
          maxLength: 30
          description: User Name
      title: DonateUserResponse
    Error-401:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          description: Contains all errors caused due to authorization failure
          properties:
            Error:
              type: array
              description: Only returned in the event of an authorization is failed.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: Gateway
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: AUTHENTICATION_FAILED
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: OAuth signatures did not match.
                    description: Short description of the ReasonCode field
                  Recoverable:
                    type: boolean
                    example: false
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
                  Details:
                    type: string
                    example: 'null'
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing.
    Error-403:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          description: Contains all errors caused due to forbidden requests
          properties:
            Error:
              type: array
              description: Only returned in the event of forbidden request.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: Gateway
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: INVALID_KEY
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: The signing certificate is not valid.
                    description: Short description of the ReasonCode field
                  Recoverable:
                    type: boolean
                    example: false
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
                  Details:
                    type: string
                    example: 'null'
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing.
    Error-AddUser:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          description: Contains all errors caused
          properties:
            Error:
              type: array
              description: Only returned in the event of an error condition.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: DONATE_SERVICE
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: USER_ALREADY_PRESENT
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: Username already exists.
                    description: Short description of the ReasonCode field
                  Recoverable:
                    type: boolean
                    example: false
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
                  Details:
                    type: array
                    items:
                      type: string
                      example: 'DonorId: ac9208b9-65cc-4d64-85c1-63ea703e3252'
    Identification:
      type: object
      properties:
        country:
          type: string
          example: MX
          minLength: 2
          maxLength: 3
          description: Country
        type:
          type: string
          example: GovtId
          minLength: 3
          maxLength: 20
          description: Type
        value:
          type: string
          example: '16367222222'
          minLength: 11
          maxLength: 20
          description: Value
      title: Identification
    PersonalInformation:
      title: PersonalInformation
      type: object
      properties:
        identifications:
          type: array
          description: identifications
          items:
            $ref: '#/components/schemas/Identification'
    AcceptedConsent:
      type: object
      required:
      - marketingEmailSubscribed
      - privacyNoticeVersion
      - tncVersion
      properties:
        marketingEmailSubscribed:
          type: string
          example: Y
          minLength: 1
          maxLength: 1
          description: Marketing Email Subscribed
        privacyNoticeVersion:
          type: string
          example: PN.2-#-xr.en-us.99.01
          minLength: 21
          maxLength: 21
          description: Privacy Notice Version
        tncVersion:
          type: string
          example: TC.##r#12.EN-Us.99.99
          minLength: 21
          maxLength: 21
          description: Tnc Version
      title: AcceptedConsent
    DonateUserAddress:
      required:
      - type
      - country
      - streetAddress
      type: object
      properties:
        country:
          type: string
          example: USA
          minLength: 3
          maxLength: 3
          description: Country
        formatted:
          type: string
          minLength: 3
          maxLength: 150
          example: 7832 West Elm Street Huntington Station, NY 11746
          description: Address
        locality:
          type: string
          minLength: 3
          maxLength: 30
          example: Rly Station
          description: Locality
        postalCode:
          type: string
          example: 11746
          minLength: 5
          maxLength: 5
          description: Postal Code
        region:
          type: string
          example: Huntington
          minLength: 3
          maxLength: 20
          description: Region
        streetAddress:
          type: string
          example: 7832 West Elm Street
          minLength: 3
          maxLength: 30
          description: Street Address
        type:
          type: string
          example: work
          minLength: 3
          maxLength: 20
          description: Type
      title: DonateUserAddress
    ConsumerEmail:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          example: home
          description: The type must be "home" for at least one email address.
          minLength: 4
          maxLength: 20
        value:
          type: string
          example: John.Doe@mail.com
          description: Email Id
          minLength: 10
          maxLength: 30
      title: ConsumerEmail
    DonorPhoneNumber:
      type: object
      properties:
        type:
          type: string
          example: home
          minLength: 3
          maxLength: 20
          description: Type
        value:
          type: string
          example: '+16367222222'
          minLength: 11
          maxLength: 20
          description: Phone number with country code.
      title: DonorPhoneNumber
    Error-500:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          description: Contains all errors caused due to server error
          properties:
            Error:
              type: array
              description: Only returned in the event of an server issue.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: DONATE_SERVICE
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: PROGRAM_ID_NOT_FOUND
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: Program id is required as this client is mapped to multiple programs.
                    description: Short description of the ReasonCode field
                  Recoverable:
                    type: boolean
                    example: false
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
                  Details:
                    type: string
                    example: 'null'
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing.
    AddUser:
      type: object
      required:
      - acceptedConsents
      - userName
      - userType
      - name
      - emails
      - locale
      properties:
        acceptedConsents:
          $ref: '#/components/schemas/AcceptedConsent'
        addresses:
          type: array
          description: Address is Optional. but if passed, type, streetAddress and country are required.
          items:
            $ref: '#/components/schemas/DonateUserAddress'
        emails:
          type: array
          description: Emails
          items:
            $ref: '#/components/schemas/ConsumerEmail'
        locale:
          type: string
          example: en-us
          minLength: 5
          maxLength: 5
          description: Locale
        name:
          $ref: '#/components/schemas/UserName'
        personalInformation:
          $ref: '#/components/schemas/PersonalInformation'
        phoneNumbers:
          type: array
          description: Phone Numbers
          items:
            $ref: '#/components/schemas/DonorPhoneNumber'
        timezone:
          type: string
          example: UTC-06:00
          minLength: 9
          maxLength: 20
          description: Timezone
        title:
          type: string
          example: Mr
          minLength: 2
          maxLength: 20
          description: Title
        userName:
          type: string
          example: John.Doe@mail.com
          minLength: 6
          maxLength: 30
          description: Name
        userType:
          type: string
          example: API
          minLength: 6
          maxLength: 20
          description: User Type
      title: AddUserRequest
  parameters:
    ClientId:
      name: x-openapi-clientid
      in: header
      description: ClientId is a unique and a mandatory ID shared while creating a project on Mastercard Developers Portal.
      required: true
      schema:
        type: string
        example: 0a7e433a-63fc-4557-8cf4
    ProgramId:
      name: ProgramId
      in: header
      description: ProgramId is an optional field, but if a client has more than one program associated to it, then this field becomes mandatory.
      required: false
      schema:
        type: string
        example: 80380ef2-5037-4e57-86bf-1bdd1efb0ae2
    CorrelationId:
      name: x-correlation-id
      in: header
      description: CorrelationId is a unique donation request ID. It is recommended to pass the x-correlation-id by the customer and to use the format "bankname_UUID" (bank name can be indicated using the first 4 digits). Maximum length of this field should be 100 alphanumeric characters. If not passed, Mastercard will generate it.
      required: false
      schema:
        type: string
        example: 03f8c4e8-8bdc-4a30-a2b4-b6f989e96ca3
  requestBodies:
    AddUser:
      description: addUserRequest
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AddUser'
      required: false