# Account Management
source: https://developer.mastercard.com/user-account-management-service/documentation/use-cases/account-management/index.md

## Enroll Account {#enroll-account}

This use case enrolls a new account for an existing user. This use case uses payload encryption.

### Pre-requisites {#pre-requisites}

The pre-requisite for the customer to use this endpoint is: Successful user enrollment

Refer to payload encryption in [Use Cases](https://developer.mastercard.com/user-account-management-service/documentation/use-cases/index.md).

### Sequence Diagram {#sequence-diagram}

Diagram account-enrollment

##### Following are the execution steps: {#following-are-the-execution-steps}

1. The cardholder signs into the customer application.
2. The customer authenticates the cardholder.
3. The customer sends an encrypted request to the User Account Management for enrollment.
   * The enrollment request requires the following mandatory input parameters:
     * accountId - The unique identifier for a given account. This is typically referred to as the Bank Account Number (BAN).
     * accountIdType - Identifier type for the given account. The supported identifier is BAN.
     * status - Status of the user's account. Valid values are GOOD_STANDING and NEW.
     * productCode - The account's associated reward product identifier.
     * programIdentifier - Program identifier for the program in which the account is enrolled.
4. The Mastercard API Gateway validates the customer's information and routes the request to the User Account Management in the case of a valid customer.
5. The User Account Management Service validates the encrypted request received through the `/accounts` endpoint.
6. The User Account Management Service enrolls the account.
7. The User Account Management Service sends a response with account details (200).
8. The User Account Management Service sends a response with a status code of 4xx/5xx in case of an invalid request.

You will receive an error response for an invalid request or any missing request parameter. In that case, you need to update the input and perform step 3 again.

### Endpoint {#endpoint}


API Reference: `POST /accounts`

## Update Account {#update-account}

This use case is used when a user wants to update the currently enrolled accounts.

### Sequence Diagram {#sequence-diagram-1}

Diagram update-account

##### Following are the execution steps: {#following-are-the-execution-steps-1}

1. The cardholder signs into the customer application.
2. The customer authenticates the cardholder.
3. The customer sends an encrypted request to the User Account Management for account details.
   * The request for updating the account requires the following mandatory input parameters:
     * accountId - The unique identifier for the account.
     * accountIdType - Identifier type for the account.
4. The Mastercard API Gateway validates the customer's information and routes the request to the User Account Management in the case of a valid customer.
5. The User Account Management Service validates the encrypted request received through the `/accounts` endpoint.
6. The User Account Management Service updates the user account.
7. The User Account Management Service sends a response with a successfully updated account message (200).
8. The User Account Management Service sends a response with a status code of 4xx/5xx in case of an invalid request.

You will receive an error response for an invalid request or any missing request parameter. In that case, you need to update the input and perform step 3 again.

### Endpoint {#endpoint-1}


API Reference: `PUT /accounts`

## Retrieve Account {#retrieve-account}

This use case is used when a user wants to retrieve account details using the account ID, including the account status, enrollment date, and more.

### Sequence Diagram {#sequence-diagram-2}

Diagram get-account

##### Following are the execution steps: {#following-are-the-execution-steps-2}

1. The cardholder signs into the customer application.
2. The customer authenticates the cardholder.
3. The customer sends a signed request to the User Account Management for account details.
   * The request for account details requires the following mandatory request parameters:
     * accountId - The unique identifier for the given account.
4. The Mastercard Network API Gateway authenticates and authorizes the customer and routes the request to the User Account Management in the case of a valid customer.
5. The User Account Management Service validates the request parameters received through the `/accounts/{id}` endpoint.
6. The User Account Management Service retrieves the account details.
7. The User Account Management Service sends a response with account details (200).
8. The User Account Management Service sends a response with a status code of 4xx/5xx in case of an invalid request.

You will receive an error response for an invalid request or any missing request parameter. In that case, you need to update the input and perform step 3 again.
Note: The response can return single or multiple accounts depending on the account_id_type or user_id_type in the request. If the account_id_type is RANAC (account-level identifier), the response has only one account. If the user_id_type is RANCU (customer level identifier) then the response can have multiple accounts.

### Endpoint {#endpoint-2}


API Reference: `GET /accounts/{id}`

## Group Accounts {#group-accounts}

This use case is used when a user wants to move or remove an account from a group of accounts in a household. Depending upon the action code provided, will move an account or accounts to another existing account group and/or remove an
account or accounts from its current account group. Account Group is also known as householding in the rewards system.

### Sequence Diagram {#sequence-diagram-3}

Diagram account-groups

##### Following are the execution steps: {#following-are-the-execution-steps-3}

1. The cardholder signs into the customer application.
2. The customer authenticates the cardholder.
3. The customer sends a request to the User Account Management to update account group information.
   * The request for updating the account group requires a path param along with the following mandatory request parameter:
     * actionCode - Indicates the type of householding action that is to be performed by the request.
4. The Mastercard API Gateway validates the customer's information and routes the request to the User Account Management in the case of a valid customer.
5. The User Account Management Service validates the request received through the `/account-groups` endpoint.
6. The User Account Management Service updates the user account with the given account group ID.
7. The User Account Management Service sends a response with a successfully updated account message (200).
8. The User Account Management Service sends a response with a status code of 4xx/5xx in case of an invalid request.

You will receive an error response for an invalid request or any missing request parameter. In that case, you need to update the input and perform step 3 again.

### Endpoint {#endpoint-3}


API Reference: `PUT /account-groups`

Note: For more information about the error codes, refer to the [Code and Formats](https://developer.mastercard.com/user-account-management-service/documentation/code-and-formats/index.md) section.

#### Additional Details {#additional-details}

This section documents the various scenarios for account grouping or householding. Depending on the action code provided, this call will move an account to another existing account group or remove an account from its current account group. The information documents things to consider when using the group account function.

If you are looking to update the primary switches, refer to the PUT/accounts section instead (for primary and redeemer account status).

**Before getting started, a few things to be noted:**

* A cardholder never joins the household as a primary because there is already a primary. You can change the redeemer status for the account.
* The removal of a user from a single account household is not permitted. This is because there is only one card associated with the household. If you need to remove (or delete) an account, this is allowed.
* The various user roles are as follows:
  * **Redeemer** -- can redeem points in the assigned accounts in the 'account group' (must have the redeemer status to be able to do so).
  * **Primary Redeemer** - can redeem points in all accounts in the 'account group'
  * **Non-redeemer** - cannot redeem points in the account.
* The household token is used by the issuer to identify the household; the household ID is the internal database ID belonging to Mastercard.  

**Scenario #1: Moving a single account to another existing household:**

* The account joins the household as non-primary and is no longer associated with the original household.
* The household token changes to the value of the household that the household is joining (if token householding is used).
* The account joining the household is set as a redeemer to allow for point usage on the account.  

**Scenario #2: Moving a non-primary account in a multi-card household to another existing household:**

* The account joins the household as non-primary and is no longer associated with the original household.
* The household token changes to the value of the household that the household is joining (if token householding is used).
* The account joining the household is set as a redeemer to allow for point usage on the account.  

**Scenario #3: Moving the primary account in a multi-card household to another existing household:**

* The account joins the household as non-primary and is no longer associated with the original household.
* The household token changes to the value of the household that the household is joining (if token householding is used).
* The account joining the household is set as a redeemer to allow for point usage on the account.
* In the original household, the API automatically changes the oldest remaining non-primary account to primary. This account is made the primary redeemer in the household.   

**Scenario #4: Removing a non-primary account from a multi-card household**

* The account that is being removed is made primary in a new household.
* The new household contains that account only.
* A new household token is assigned to the household (if token householding is used)
* The account is set as the primary redeemer in the new household.  

**Scenario #5: Removing a primary account from a multi-card household**

* The account that is being removed is made primary in a new household.
* The new household contains that account only.
* A new household token is assigned to the household (if token householding is used).
* The account is set as the primary redeemer in the new household.
* In the original household, the API automatically changes the oldest remaining non-primary account to primary. This account is made the primary redeemer in the household.   

Note: If there are further unanswered questions, contact your Mastercard account manager.