Mastercard Accounts API

openapi: 3.2.0
info:
  title: User Management Accounts API
  description: API for user management.
  contact:
    name: API Support
    url: https://developer.mastercard.com/support
    email: apisupport@mastercard.com
  version: 1.3.10
servers:
- url: https://sandbox.api.mastercard.com/loyalty/mrs
  description: Sandbox server
- url: https://api.mastercard.com/loyalty/mrs
  description: Production server
tags:
- name: Accounts
  description: Operations related to Accounts.
paths:
  /accounts:
    put:
      tags:
      - Accounts
      summary: Updates details for an enrolled account.
      description: Updates a currently enrolled account. An account is a unique card, as compared to a user which is a unique cardholder.
      operationId: updateAccount
      requestBody:
        $ref: '#/components/requestBodies/AccountUpdateRequest'
      responses:
        '200':
          $ref: '#/components/responses/AccountUpdateResponse'
        '400':
          $ref: '#/components/responses/ErrorsResponse'
    post:
      tags:
      - Accounts
      summary: 'Enrolls a new account for an existing User. An Account is a unique card, as compared to a User which is a unique cardholder. Use this operation only for subsequent account enrollments of an existing user.

        '
      description: Returns Account enrollment details.
      operationId: enrollAccount
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/AccountEnrollRequest'
      responses:
        '201':
          $ref: '#/components/responses/AccountEnrollResponse'
        '400':
          $ref: '#/components/responses/ErrorsResponse'
  /accounts/{id}:
    get:
      tags:
      - Accounts
      summary: Retrieves Account details using the Account Id, including the Account standing, enrollment date, and more.
      description: Retrieves Account details using the Account Id, including the Account standing, enrollment date, and more. An Account is a unique card, as compared to a User which is a unique cardholder.
      operationId: getAccount
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/AccountIdType'
      - $ref: '#/components/parameters/UserIdType'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/AccountSearchDetailsResponse'
        '400':
          $ref: '#/components/responses/ErrorsResponse'
components:
  schemas:
    AccountUpdate:
      required:
      - accountId
      - accountIdType
      type: object
      properties:
        accountId:
          maxLength: 30
          minLength: 0
          type: string
          description: The unique identifier for the account.
          example: '103580149704735875487800510667'
        accountIdType:
          type: string
          description: Identifier type for the account. The static value of RANAC should be used for this field.
          example: RANAC
        status:
          type: string
          description: "Status of the user's account. Valid values are NEW, GOOD_STANDING, REDEEM_ONLY, CANCELLED, ON_HOLD, INACTIVE.\n - NEW  Used for auto and self-enrollment. Can earn, but not redeem.\n - GOOD_STANDING  Can earn and redeem. This is the typical good status for an account.\n - REDEEM_ONLY  Cannot earn but can redeem.\n - CANCELLED  Cannot earn or redeem. This is the typical final state for an account that is no longer active in a program.\n - ON_HOLD  Can earn, but not redeem. This status is for temporarily derogative accounts.\n - INACTIVE"
          example: CANCELLED
          enum:
          - NEW
          - GOOD_STANDING
          - REDEEM_ONLY
          - CANCELLED
          - ON_HOLD
          - INACTIVE
        accruePoints:
          type: boolean
          description: "Suggested status and accruePoints settings are as follows:\n - status = NEW, accruePoints = true\n - status = GOOD_STANDING, accruePoints = true\n - status = REDEEM_ONLY, accruePoints = false\n - status = CANCELLED, accruePoints = false\n - status = ON_HOLD, accruePoints = true"
          example: true
        primaryAccount:
          type: boolean
          description: Identifies if the account is primary for the user. A user may only have one primary account. In situations where householding is used, there may only be one primary account in the household, regardless of how many user accounts make up that household. A value of true indicates that the account is primary for the user or the household.
          example: false
        receiveStatements:
          type: boolean
          description: Specifies if the account should be included in the outbound statement file that the rewards system can send a customer, for the purpose of producing paper Rewards Statements. A value of true indicates that the user will receive a paper statement.
          example: true
        externalAccountId:
          maxLength: 10
          minLength: 0
          type: string
          description: Used for On-Soil customers when optional fields are turned on in the rewards system.
          example: '2222332322'
        cycleId:
          type: integer
          description: Bank cycle number that the cardholder/primary cardholder is assigned to. This field is typically not used unless the customer is receiving a Statement batch file from the rewards system.
          format: int64
          example: 1
        cycleRun:
          type: boolean
          description: Flag to indicate whether a Rewards account has been cycled for the current period.
          example: false
        pcloAccountStatusCode:
          type: string
          description: "Status of the user's account. This field is only for PCLO customers. Valid values are NEW, GOOD_STANDING, REDEEM_ONLY, CANCELLED, ON_HOLD.\n - NEW  Used for auto and self-enrollment. Can earn, but not redeem.\n - GOOD_STANDING  Can earn and redeem. This is the typical good status for an account.\n - REDEEM_ONLY  Cannot earn but can redeem.\n - CANCELLED  Cannot earn or redeem. This is the typical final state for an account that is no longer active in a program.\n - ON_HOLD  Can earn, but not redeem. This status is for temporarily derogative accounts."
          example: NEW
          enum:
          - NEW
          - GOOD_STANDING
          - REDEEM_ONLY
          - CANCELLED
          - ON_HOLD
        userDefined1:
          maxLength: 40
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 1 Example
        userDefined2:
          maxLength: 40
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 2 Example
        userDefined3:
          maxLength: 40
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 3 Example
        userDefined4:
          maxLength: 40
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 4 Example
        userDefined5:
          maxLength: 20
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 5 Example
        userDefined6:
          maxLength: 20
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 6 Example
        userDefined7:
          maxLength: 20
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 7 Example
        userDefined8:
          maxLength: 20
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 8 Example
        productTransfer:
          type: boolean
          description: Determines whether the Bank Product needs to be updated. When productTransfer is true, then only bank product for the given account will be updated ignoring other fields in the request payload.
          example: true
        bankProductCode:
          maxLength: 30
          type: string
          description: Bank Product Code associated with the new card.
          example: VISACD
    Errors:
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          description: Error Details
          items:
            $ref: '#/components/schemas/ErrorItem'
    AccountSearchDetails:
      required:
      - accounts
      type: object
      properties:
        offset:
          type: integer
          description: Indicates the number of items you asked the start of the list to be offset from.
          example: 1
        limit:
          type: integer
          description: Indicates the number of items you asked the list to be limited to.
          example: 1
        total:
          type: integer
          format: int64
          description: Indicates the total number of items in the collection.
          example: 1
        count:
          type: integer
          description: Indicates the number of items in this batch (the size of the item array).
          example: 1
        accounts:
          type: array
          description: accounts
          items:
            $ref: '#/components/schemas/Account'
    ErrorsWrapper:
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    EnrolledAccount:
      type: object
      properties:
        accountIdType:
          type: string
          description: Account identifier type such as RANAC.
          example: RANAC
        accountId:
          type: string
          description: The unique identifier for the given account.
          example: '136821076497727922312391057516'
    AccountEnroll:
      required:
      - accountId
      - accountIdType
      - companyIca
      - productCode
      - programIdentifier
      - status
      - userId
      - userIdType
      type: object
      properties:
        accountId:
          maxLength: 30
          minLength: 0
          type: string
          description: The unique identifier for a given account. This is typically referred to as the Bank Account Number (BAN). When enrolling a card account, the physical card number should be followed by 3 trailing zeros.
          example: '5330333671236516000'
        accountIdType:
          type: string
          description: Identifier type for the given account. Supported identifier is BAN.
          example: BAN
        status:
          type: string
          description: "Status of the user's account. Valid values are GOOD_STANDING and NEW.\n - NEW  Used for auto and self-enrollment.  Can earn, but not redeem.\n - GOOD_STANDING  Can earn and redeem. This is the typical good status for an account."
          example: NEW
          enum:
          - NEW
          - GOOD_STANDING
        productCode:
          maxLength: 20
          minLength: 0
          type: string
          description: The account's associated reward product identifier as defined by the client and configured during the implementation of the program.
          example: FIDOCASHBACK
        programIdentifier:
          maxLength: 40
          minLength: 0
          type: string
          description: Program identifier for the program in which the account is enrolled. Program identifier is assigned during the implementation of the program.
          example: PGM42051
        openDate:
          maxLength: 10
          minLength: 0
          pattern: ^\d{4}\-(0[1-9]|1[012])\-(0[1-9]|[12][0-9]|3[01])$
          type: string
          description: The date of account opening as defined by the client. This date is typically when the banking account was opened.
          example: '2014-12-31'
          format: date
        enrollmentDate:
          maxLength: 10
          minLength: 0
          pattern: ^\d{4}\-(0[1-9]|1[012])\-(0[1-9]|[12][0-9]|3[01])$
          type: string
          description: The date when the account becomes eligible for rewards program. If undefined, enrollment date is defaulted to the date that Mastercard processes the enrollment.
          example: '2018-03-10'
          format: date
        accruePoints:
          type: boolean
          description: "Suggested status and accruePoints settings are as follows:\n - status = NEW, accruePoints = true\n - status = GOOD_STANDING, accruePoints = true\n - status = REDEEM_ONLY, accruePoints = false\n - status = CANCELLED, accruePoints = false\n - status = ON_HOLD, accruePoints = true"
          example: false
        householdToken:
          type: string
          description: This field ties together multiple User accounts into one household. This value is typically assigned by the customer. To use this field, a rewards program must be configured to support the Token or Token then Bank Customer Number householding scheme.
          example: '254235'
        primaryAccount:
          type: boolean
          description: Identifies if the account is primary for the User. A User may only have 1 primary account. In situations where householding is used, there may only be 1 primary account in the household, regardless of how many User accounts make up that household. A value of true indicates that the account is primary for the User or the household.
          example: false
        userDefined1:
          maxLength: 40
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 1 Example
        userDefined2:
          maxLength: 40
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 2 Example
        userDefined3:
          maxLength: 40
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 3 Example
        userDefined4:
          maxLength: 40
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 4 Example
        userDefined5:
          maxLength: 20
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 5 Example
        userDefined6:
          maxLength: 20
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 6 Example
        userDefined7:
          maxLength: 20
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 7 Example
        userDefined8:
          maxLength: 20
          minLength: 0
          type: string
          description: User Defined Fields can be used to store partner-specific data that can be used for promotions and other business rules.
          example: UDF 8 Example
        externalAccountId:
          maxLength: 10
          minLength: 0
          type: string
          description: Used for On-Soil customers when optional fields are turned on in the rewards system.
          example: '2222332322'
        cycleId:
          type: integer
          description: Bank cycle number that the cardholder/primary cardholder is assigned to. This field is typically not used unless the customer is receiving a statement batch file from the rewards system.
          format: int64
          example: 1
        cycled:
          type: boolean
          description: Flag to indicate whether a Rewards account has been cycled for the current period.
          example: false
        pcloAccountStatusCode:
          type: string
          description: "Status of the user's account. Valid values are NEW, GOOD_STANDING, REDEEM_ONLY, CANCELLED, ON_HOLD.\n - NEW  Used for auto and self-enrollment. Can earn, but not redeem.\n - GOOD_STANDING  Can earn and redeem. This is the typical good status for an account.\n - REDEEM_ONLY  Cannot earn but can redeem.\n - CANCELLED  Cannot earn or redeem. This is the typical final state for an account that is no longer active in a program.\n - ON_HOLD  Can earn, but not redeem. This status is for temporarily derogative accounts."
          example: NEW
          enum:
          - NEW
          - GOOD_STANDING
          - REDEEM_ONLY
          - CANCELLED
          - ON_HOLD
        accountReferenceCode:
          maxLength: 50
          minLength: 0
          type: string
          description: Unique identifier the membership uses to identify an account.
          example: 123456abcdef123456abcdef123456abcdef0
        companyIca:
          type: integer
          description: Interbank Card Association number assigned by Mastercard to the financial institution.
          format: int64
          example: 9989
        userId:
          maxLength: 50
          minLength: 0
          type: string
          description: The unique identifier of the User.
          example: '5600000000000003000'
        userIdType:
          type: string
          description: Identifier type of the User. Supported identifiers are BCN or RANCU.
          example: BCN
    Account:
      required:
      - accountId
      - accountIdType
      - productCode
      - programIdentifier
      - status
      type: object
      properties:
        accountId:
          maxLength: 30
          minLength: 0
          type: string
          description: The unique identifier for the given account.
          example: '5330333671236516'
        accountIdType:
          type: string
          description: Identifier type for the given account.
          example: BAN
        status:
          type: string
          description: Status of the user's account. Valid values are GOOD_STANDING, REDEEM_ONLY, NEW, ON_HOLD, CANCELLED, INACTIVE.
          example: NEW
        productCode:
          maxLength: 20
          minLength: 0
          type: string
          description: The account's associated reward product identifier as defined by the client and configured during the implementation of the program.
          example: FIDOCASHBACK
        programIdentifier:
          maxLength: 40
          minLength: 0
          type: string
          description: Program identifier for the program in which the cardholder is enrolled. The program ID is created by Mastercard Rewards System.
          example: PGM42051
        openDate:
          maxLength: 10
          minLength: 0
          pattern: ^\d{4}\-(0[1-9]|1[012])\-(0[1-9]|[12][0-9]|3[01])$
          type: string
          description: The date of account opening as defined by the client.
          example: '2014-12-31'
          format: date
        enrollmentDate:
          maxLength: 10
          minLength: 0
          pattern: ^\d{4}\-(0[1-9]|1[012])\-(0[1-9]|[12][0-9]|3[01])$
          type: string
          description: The date when the account becomes eligible for rewards program. If undefined, enrollment date is defaulted to the date when Mastercard processes the enrollment.
          example: '2018-03-10'
          format: date
        accruePoints:
          type: boolean
          description: This specifies if the account can accrue points. It is used in conjunction with Account Status to define earn and burn behavior for the account.
          example: false
        householdToken:
          type: string
          description: This field ties together multiple user accounts into one household. This value is typically assigned by the Client. To use this field, a rewards program must be configured to support the Token or Bank Customer Number householding scheme.
          example: '254235'
        primaryAccount:
          type: boolean
          description: Identifies if the account is primary for the User. A User may only have 1 primary account. In situations where householding is used, there may only be 1 primary account in the household, regardless of how many User accounts make up that household. A value of true indicates that the account is primary for the User or the household.
          example: false
        userDefined1:
          maxLength: 40
          minLength: 0
          type: string
          description: User Defined Field 1
          example: UDF 1 Example
        userDefined2:
          maxLength: 40
          minLength: 0
          type: string
          description: User Defined Field 2
          example: UDF 2 Example
        userDefined3:
          maxLength: 40
          minLength: 0
          type: string
          description: User Defined Field 3
          example: UDF 3 Example
        userDefined4:
          maxLength: 40
          minLength: 0
          type: string
          description: User Defined Field 4
          example: UDF 4 Example
        userDefined5:
          maxLength: 20
          minLength: 0
          type: string
          description: User Defined Field 5
          example: UDF 5 Example
        userDefined6:
          maxLength: 20
          minLength: 0
          type: string
          description: User Defined Field 6
          example: UDF 6 Example
        userDefined7:
          maxLength: 20
          minLength: 0
          type: string
          description: User Defined Field 7
          example: UDF 7 Example
        userDefined8:
          maxLength: 20
          minLength: 0
          type: string
          description: User Defined Field 8
          example: UDF 8 Example
        externalAccountId:
          maxLength: 10
          minLength: 0
          type: string
          description: Used for On-Soil customers when optional fields are turned on in the rewards system.
          example: '2222332322'
        cycleId:
          type: integer
          description: Bank cycle number that the cardholder/primary cardholder is assigned to.
          format: int64
          example: 1
        cycled:
          type: boolean
          description: Flag to indicate whether a Rewards account has been cycled.
          example: false
        pcloAccountStatusCode:
          type: string
          description: Status of the user's account. Valid values are GOOD_STANDING, REDEEM_ONLY, NEW, ON_HOLD, CANCELLED, INACTIVE.
          example: NEW
        accountReferenceCode:
          maxLength: 50
          minLength: 0
          type: string
          description: Unique identifier the membership uses to identify an account.
          example: 123456abcdef123456abcdef123456abcdef0
        companyIca:
          type: integer
          description: Interbank Card Association number assigned by Mastercard to the financial institution.
          format: int64
          example: 611532
        accountFirstFour:
          type: string
          description: The first 4 digits of the account number.
          example: '5114'
        accountLastFour:
          type: string
          description: The last 4 digits of the account number.
          example: '5678'
        userId:
          type: string
          description: Value of the user or account identification.
          example: '5330333671236516'
        userIdType:
          type: string
          description: Type of the user or account identification. Supported identifier is RANCU.
          example: RANCU
        autoEnrolled:
          type: boolean
          description: Indicates whether this card was auto-enrolled.
          example: false
        enrollmentTypeId:
          type: integer
          description: Indicates how the customer is enrolled.
          format: int64
          example: 12
        enrollmentType:
          type: string
          description: Indicates the description of how the customer is enrolled.
          example: B2B Service
        previousAccountLostStolen:
          type: boolean
          description: Indicates whether this card number has been reported lost or stolen.
          example: false
        receiveStatements:
          type: boolean
          description: Used on programs receiving statements from Mastercard to determine which cardholders should receive a statement.
          example: false
        previousAccountFirstFour:
          type: string
          description: Indicates the first four digits of customer's previous bank account number.
          example: '1234'
        previousAccountLastFour:
          type: string
          description: Indicates the last four digits of customer's previous bank account number.
          example: '5678'
        programName:
          type: string
          description: Program name is the reference for a program associated to an account.
          example: SURPREENDA
        householdId:
          type: integer
          description: Unique ID for a Household in the rewards system. This is an internal value assigned to the household, when a customer is enrolled.
          format: int64
          example: 1234
      description: accounts
    ErrorItem:
      type: object
      properties:
        Source:
          type: string
          description: Source of the error
          example: user-management
        ReasonCode:
          type: string
          description: A unique constant identifying the error case encountered during API request processing.
          example: INVALID_FIELD_FORMAT
        Description:
          type: string
          description: Short description of the ReasonCode field.
          example: Email Address must be in the valid format.
        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: Where appropriate, indicates detailed information about the data received.
          example: Invalid Details
      description: Error Details
  parameters:
    AccountIdType:
      name: account_id_type
      in: query
      description: Determines the type of account identification. Supported identifier is RANAC.
      required: false
      schema:
        type: string
      example: RANAC
    Limit:
      name: limit
      in: query
      description: The number of items you ask the list to be limited to. Must be greater than 0 and less than or equal to 25, default value is 25.
      required: false
      schema:
        type: integer
      example: 2
    UserIdType:
      name: user_id_type
      in: query
      description: Determines the type of user identification. Supported identifier is RANCU.
      required: false
      schema:
        type: string
      example: RANCU
    Offset:
      name: offset
      in: query
      description: The number of items you ask the start of the list to be offset from. Zero-based offset index, must NOT be negative, default value is 0.
      required: false
      schema:
        type: integer
      example: 0
    AccountId:
      name: id
      in: path
      description: The unique identifier for the given account. Account Id is always RANAC.
      required: true
      schema:
        type: string
      example: '268810378058708149455458707247'
  responses:
    AccountUpdateResponse:
      description: Ok
    ErrorsResponse:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsWrapper'
    AccountSearchDetailsResponse:
      description: Successfully retrieved account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountSearchDetails'
    AccountEnrollResponse:
      description: Successfully enrolled account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnrolledAccount'
  requestBodies:
    AccountEnrollRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountEnroll'
    AccountUpdateRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountUpdate'