Mastercard Profiles API

openapi: 3.2.0
info:
  title: Mastercard Carbon Calculator Profiles API
  description: The Carbon Calculator API enables issuers to provide their consumers with visibility into the environmental impact based on their spending. This API allows the issuer to calculate the carbon footprint based on consumers' payment transactions using their Mastercard cards. This API can be used inside a banking application or website to provide meaningful and actionable insights.
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
  version: 1.2.0
servers:
- url: https://sandbox.api.mastercard.com/carbon
  description: Sandbox
- url: https://api.mastercard.com/carbon
  description: Production
tags:
- name: Profiles
paths:
  /profiles:
    put:
      operationId: updateUserProfile
      description: The Profile Service employs a sophisticated algorithm to compute a detailed climate profile, drawing upon the responses gathered through a survey obtained from the Surveys Service. This process involves a meticulous analysis of user-provided answers to generate a comprehensive and nuanced representation of their climate preferences and perspectives. See (https://surveyjs.io/survey-creator)
      summary: Calculates a climate profile based on the answers from a survey obtained from the Surveys Service.
      tags:
      - Profiles
      requestBody:
        $ref: '#/components/requestBodies/ProfileRequest'
      responses:
        '200':
          $ref: '#/components/responses/Profile'
        '400':
          $ref: '#/components/responses/ProfilePayloadBadRequestError'
        '404':
          $ref: '#/components/responses/ServiceProviderNotFoundError'
components:
  schemas:
    Error:
      title: Error
      type: object
      description: Error object which contains details about the error.
      required:
      - Source
      - ReasonCode
      - Description
      - Recoverable
      properties:
        Source:
          type: string
          description: The application name that generated this error. Every error message that is generated and returned by the gateway will have this field equal to Gateway. Other possible values are 'Carbon-Calculator' and 'Service-Provider'.
          minLength: 1
          maxLength: 100
          example: Service-Provider-Mgmt
        ReasonCode:
          type: string
          description: A unique constant identifying the error case encountered during request processing.
          minLength: 1
          maxLength: 100
          example: INVALID_REQUEST_PARAMETER
        Description:
          type: string
          description: Short description of the ReasonCode field.
          minLength: 10
          maxLength: 1000
          example: One of the request parameters is invalid, try again with correct request.
        Recoverable:
          type: boolean
          description: Indicates whether this error will always be returned for this request, or retrying could change the outcome.
          example: false
        Details:
          type: string
          description: (Optional) Where appropriate, indicates detailed information about data received and calculated during the request processing, to help the user with diagnosing errors.
          minLength: 0
          maxLength: 5000
          example: paymentCardId size must be between 36 and 36
    Errors:
      title: Errors
      type: object
      description: Error object which returns a list of Error objects.
      required:
      - Error
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    ErrorList:
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    ClimateProfile:
      description: Represents a Climate Profile for a User. Always use updated profile present in the response, which might include benchmarks, comparisons, insights and surveys.
      properties:
        userAttributes:
          description: Attributes defining this profile
          properties:
            country:
              type: string
              description: country of issuer
              example: IN
              minLength: 2
              maxLength: 3
            demo:
              type: number
              description: demo of user / score for user demo
              example: 65
            diet:
              type: number
              description: diet type of user
              example: 512
            energy:
              type: number
              description: energy consumption type of user
              example: 12288
            lifestyle:
              type: number
              description: lifestyle type of user
              example: 1
            transport:
              type: number
              description: transport type of user
              example: 12357
          required:
          - country
          - demo
          - diet
          - energy
          - lifestyle
          - transport
          type: object
        benchmarks:
          description: Tracks benchmarks data. This value is sourced from benchmarks API.
          type: object
          additionalProperties: true
          example:
            key1:
              key2: 1
              key3: 2
        comparisons:
          description: Tracks comparison data. This value is sourced from comparisons by id API.
          type: object
          additionalProperties: true
          example:
            key1:
              key2: 1
              key3: 2
        insights:
          description: Tracks which insights have been displayed. This value is sourced from insights by id API.
          type: object
          additionalProperties: true
          example:
            key1:
              key2: 1
              key3: 2
        created:
          description: represents creation date of user profile
          type: string
          format: date-time
          example: '2023-08-07T12:39:35.087Z'
        persona:
          description: Representation of user persona type
          type: string
          example: '5'
          minLength: 1
          maxLength: 1
        surveys:
          description: Tracks surveys data. This value is sourced from /surveys API.
          type: object
          additionalProperties: true
          example:
            key1:
              key2: 1
              key3: 2
        traits:
          description: Scores for knowledge, lifestyle, and motivation
          properties:
            knowledge:
              type: number
              example: 0.575
              description: score for user knowledge
              minLength: 1
            lifestyle:
              type: number
              example: 0.324
              description: score for user lifestyle
              minLength: 1
            motivated:
              type: number
              example: 0.617
              description: score for user motivation
              minLength: 1
          required:
          - knowledge
          - lifestyle
          - motivated
          type: object
        version:
          description: Version for this profile
          type: string
          example: 1
      required:
      - userAttributes
      - created
      - persona
      - traits
      - version
      type: object
    Profile:
      type: object
      properties:
        profile:
          $ref: '#/components/schemas/ClimateProfile'
      required:
      - profileResponsePayload
    Profiles:
      title: profiles
      type: object
      description: Climate Profile of the user.
      properties:
        profilesPayload:
          properties:
            id:
              type: string
              description: id of survey
              example: onboarding
            surveyioResults:
              type: object
              properties:
                sex:
                  type: string
                  description: '''demo.m'' stands for Male, ''demo.f'' stands for Female, ''demo.other'' stands for other'
                  example: demo.m
                age:
                  type: string
                  description: '''demo.lt10'' for age in range 0-9, ''demo.lt20'' for age in the range 10-19, ''demo.lt30'' for age in the range 20-29, ''demo.lt40'' for age in the range 30-39, ''demo.lt50'' for age in the range 40-49, ''demo.lt60'' for age in the range 50-59, ''demo.lt70'' for age in the range 60-69, ''demo.lt80'' for age in the range 70-79, ''demo.lt90'' for age in the range 80-89, ''demo.gt90'' for age greater than 90'
                  example: demo.lt30
                country:
                  type: string
                  description: 2 letter country code of country of residence. For example, 'IN' stands for India, 'US' stands for United States of America, 'BH' stands for Bahrain
                  example: IN
                interest:
                  type: string
                  description: '''stronglyAgree'' stands for ''Strongly Agree'', ''somewhatAgree'' stands for ''Somewhat Agree'', ''Neutral'' stands for ''Neutral'', ''somewhatDisagree'' stands for ''Somewhat Disagree'' and ''stronglyDisagree'' stands for ''Strongly Disagree'''
                  example: Neutral
                knowledge:
                  type: string
                  description: '''stronglyAgree'' stands for ''Strongly Agree'', ''somewhatAgree'' stands for ''Somewhat Agree'', ''Neutral'' stands for ''Neutral'', ''somewhatDisagree'' stands for ''Somewhat Disagree'' and ''stronglyDisagree'' stands for ''Strongly Disagree'''
                  example: Neutral
                diet:
                  type: string
                  description: '''diet.all'' stands for "I eat everything", ''diet.meatlessDay'' stands for "One meatless day a week", ''diet.avoidRed'' stands for "I try to avoid eating red meat", ''diet.noRed'' stands for "I don''t eat red meat", ''diet.pescetarian'' stands for "Pescetarian(I don''t eat meat except fish)", ''diet.vegetarian'' stands for "Vegetarian", ''diet.vegan'' stands for "Vegan"'
                  example: diet.noRed
                renewableElectricity:
                  type: string
                  description: '''energy.renewable'' stands for "Yes, we use a supplier of renewable electricity", ''energy.selfProduced'' stands for "Yes, we produce our own renewable electricity", ''energy.not'' stands for "No", ''energy.idk'' stands for "I don''t know"'
                  example: energy.renewable
                haveCar:
                  type: string
                  description: '''transport.hasCar'' stands for "Yes" and ''transport.noCar'' stands for "No"'
                  example: transport.hasCar
                carFuel:
                  type: string
                  description: '''transport.petrol'' stands for "Petrol", ''transport.diesel'' stands for "Diesel", ''transport.bio'' stands for "Bio-fuel or bio-gas", ''transport.hybrid'' stands for "Hybrid", ''transport.phev'' stands for "Plug-in hybrid", ''transport.electric'' stands for "Electric", ''transport.idk'' stands for "I don''t know"'
                  example: transport.petrol
                flyFrequency:
                  type: string
                  description: '''transport.everyMonth'' stands for "Every month or more", ''transport.secondMonth'' stands for "Every second month", ''transport.twice'' stands for "A couple of times a year", ''transport.once'' stands for "Once a year or less", ''transport.Never'' stands for "Never"'
                  example: transport.twice
                shopFrequency:
                  type: string
                  description: '''lifestyle.shopVeryOften'' stands for "Every week or more often", ''lifestyle.shopOften'' stands for "2-3 times every month", ''lifestyle.shopSometimes'' stands for "Once a month", ''lifestyle.shopSeldom'' stands for "1-2 times every 3 months", ''lifestyle.shopRarely'' stands for "Less often or not at all"'
                  example: once a month
                difference:
                  type: string
                  description: '''stronglyAgree'' stands for ''Strongly Agree'', ''somewhatAgree'' stands for ''Somewhat Agree'', ''Neutral'' stands for ''Neutral'', ''somewhatDisagree'' stands for ''Somewhat Disagree'' and ''stronglyDisagree'' stands for ''Strongly Disagree'''
                  example: somewhatAgree
                consciousPurchasingDecision:
                  type: string
                  description: '''stronglyAgree'' stands for ''Strongly Agree'', ''somewhatAgree'' stands for ''Somewhat Agree'', ''Neutral'' stands for ''Neutral'', ''somewhatDisagree'' stands for ''Somewhat Disagree'' and ''stronglyDisagree'' stands for ''Strongly Disagree'''
                  example: Neutral
                explainCarbonFootprint:
                  type: string
                  description: '''stronglyAgree'' stands for ''Strongly Agree'', ''somewhatAgree'' stands for ''Somewhat Agree'', ''Neutral'' stands for ''Neutral'', ''somewhatDisagree'' stands for ''Somewhat Disagree'' and ''stronglyDisagree'' stands for ''Strongly Disagree'''
                  example: stronglyDisagree
              required:
              - sex
              - age
              - country
              - interest
              - knowledge
              - diet
              - renewableElectricity
              - haveCar
              - flyFrequency
              - shopFrequency
              - difference
              - consciousPurchasingDecision
              - explainCarbonFootprint
              additionalProperties: false
            version:
              type: string
              example: '1'
              description: version of survey
          required:
          - id
          - surveyioResults
          - version
          type: object
        profile:
          $ref: '#/components/schemas/ClimateProfile'
      required:
      - profilesPayload
    ErrorWrapper:
      title: ErrorWrapper
      type: object
      description: The error response object gets returned in case of any error.
      required:
      - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
  requestBodies:
    ProfileRequest:
      description: List of payment transactions which needs to be scored.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Profiles'
          examples:
            ProfileRequest:
              $ref: '#/components/examples/ProfileRequest'
      required: true
  responses:
    ServiceProviderNotFoundError:
      description: This response code is returned when the server cannot find the account which has been used to call this API.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            ServiceProviderNotFoundError:
              $ref: '#/components/examples/ServiceProviderNotFoundError'
    ProfilePayloadBadRequestError:
      description: This response code is returned when one or more request parameters is either missing or is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestError:
              $ref: '#/components/examples/ProfilePayloadBadRequestError'
    Profile:
      description: The resulting profile.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Profile'
          examples:
            ProfileResponse:
              $ref: '#/components/examples/ProfileResponseData'
  examples:
    ProfilePayloadBadRequestError:
      value:
        Errors:
          Error:
          - Source: Carbon-Calculator
            ReasonCode: INVALID_REQUEST_PARAMETER
            Description: One of the request parameters is invalid, try again with correct request.
            Recoverable: false
            Details: payload.id must not be null
          - Source: Carbon-Calculator
            ReasonCode: INVALID_REQUEST_PARAMETER
            Description: One of the request parameters is invalid, try again with correct request.
            Recoverable: false
            Details: payload.version must not be null
    ProfileRequest:
      value:
        profilesPayload:
          id: onboarding
          version: '1.1'
          surveyioResults:
            sex: demo.f
            age: demo.lt20
            country: AX
            interest: stronglyDisagree
            knowledge: stronglyDisagree
            diet: diet.vegan
            renewableElectricity: energy.idk
            haveCar: transport.noCar
            flyFrequency: transport.never
            shopFrequency: lifestyle.shopRarely
            difference: stronglyDisagree
            consciousPurchasingDecisions: stronglyDisagree
            explainCarbonFootprint: stronglyDisagree
        profile:
          traits:
            knowledge: 0.65
            lifestyle: 0.445
            motivated: 0.683
          userAttributes:
            demo: 66
            diet: 256
            lifestyle: 4
            energy: 12288
            transport: 36933
            country: AX
          created: '2024-01-31T10:57:36.161Z'
          surveys:
            key1:
              key2: 1
              key3: 2
          persona: '3'
          benchmarks:
            key1:
              key2: 1
              key3: 2
          comparisons:
            key1:
              key2: 1
              key3: 2
          insights:
            key1:
              key2: 1
              key3: 2
          version: '1.0'
    ServiceProviderNotFoundError:
      value:
        Errors:
          Error:
          - Source: Service-Provider-Mgmt
            ReasonCode: ACCOUNT_NOT_FOUND
            Description: We cannot find the account which you are using to access this service. Kindly register your account or contact your Mastercard associate if you have already registered with us earlier.
            Recoverable: false
            Details: ''
    ProfileResponseData:
      value:
      - profile:
          traits:
            knowledge: 0
            lifestyle: 0.683
            motivated: 0.3
          userAttributes:
            demo: 34
            diet: 16399
            lifestyle: 16
            energy: 0
            transport: 0
            country: AF
          created: '2024-01-19T09:31:08.065Z'
          surveys:
            key1:
              key2: 1
              key3: 2
          persona: '5'
          benchmarks:
            key1:
              key2: 1
              key3: 2
          comparisons:
            key1:
              key2: 1
              key3: 2
          insights:
            key1:
              key2: 1
              key3: 2
          version: '1.0'
externalDocs:
  description: ISO 4217 - Currency Code
  url: https://en.wikipedia.org/wiki/ISO_4217