# User Account Administration source: https://developer.mastercard.com/presentment/documentation/use-cases/user-account-administration/index.md The following use cases refer to users as cardholders and an account as a unique card. Each user can have multiple accounts, meaning cardholders can have multiple cards. Note: Customers should refer to different API documentation depending on their integration platform: * Offers Direct Integration Platform: Use the Offers for Publishers User Account Administration APIs to support key functionalities, including cardholder enrollment, account updates, card replacements, and user or account lookup using Publisher-provided identifiers. * Mastercard Loyalty Management Platform: Customers who have not migrated to the new Offers platform may continue using the Mastercard Loyalty Management User Account Management APIs. In this case, refer to the [User Account Management API documentation](https://developer.mastercard.com/user-account-management-service/documentation/) on Mastercard Developers. ## Evaluate PAN for enrollment {#evaluate-pan-for-enrollment} This use case is optional and can be leveraged by platforms that wish to validate card eligibility criteria enforced by the offers platform. It enables validation of a cardholder's Primary Account Number (PAN) against predefined eligibility criteria, ensuring that only qualified PANs are enrolled in the Offers program. This use case also applies to scenarios where customers wish to enroll cardholders in non-FAE programs where Publishers require the offers program to validate card eligibility rules. Note: Eligibility rules must be clearly defined during the publisher onboarding process, as they form the basis for PAN validation. ### Sequence diagram {#sequence-diagram} Diagram evaluate-pan-enrollment ### Execution steps {#execution-steps} 1. The cardholder enrolls into a Publisher's offers program. 2. The Publisher submits the PAN to check whether it is eligible for enrollment. The request includes these fields: | Field | Description | Required field? | |------------------------|-----------------------------------------------------------------------------------------------------|---------------------------------------------| | ban | Bank Account Number, which must be a valid Mastercard credit card or PAN. | Yes | | enrollmentType | The identifier for the type of enrollment, such as targeted enrollment. | Yes | | fiIds | An array of financial institution identifiers provided by Mastercard. | No, unless the enrollment type is targeted. | | includeEnrollmentExist | If this field is set to true, the response includes whether there is an existing enrollment record. | No | | includeProductDetails | If this field is set to true, the response includes product details. | No | 3. Offers for Publishers determines the validity of the PAN and checks eligibility rules based on the cardholder's data and enrollment type. 4. Offers for Publishers returns the response based on whether the PAN is eligible for enrollment. The response includes these fields: | Field | Description | |----------------------------|---------------------------------------------------------------------------------------------------------| | enrollmentEligible | Shows if the cardholder is eligible. | | enrollmentEligiblePlatform | Eligible platform code(s). | | bankProductCode | Bank product identifier. | | enrollmentRecordExists | Shows whether an enrollment record exists. | | directIntegrationOnboarded | Shows if the platform is onboarded through direct integration. | | programIdentifier | Identifies the program associated with the account and determines which program ID should be populated. | | includeProductDetails | Shows whether product details are included. | | mastercardProductDetails | Product details such as issuer ICA, name, product type, category, and more. | 5. If the enrollmentRecordExists field is set to true, then these fields are included in the response: | Field | Description | |---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | userId | A numerical string that uniquely identifies a user or cardholder. | | userIdType | Specifies the type of identifier used for the associated user with values such as: Bank Account Number (BAN), Bank Customer Number (BCN), Account Reference Key (ARK), or Customer Reference Key (CRK). | | accountId | A numerical string that uniquely identifies an account or unique card. | | accountIdType | Specifies the type of identifier used for the associated account with values such as: Bank Account Number (BAN), Bank Customer Number (BCN), Account Reference Key (ARK), or Customer Reference Key (CRK). | 6. If PAN authorization is successful, the user receives a successful response. 7. If PAN authorization fails, the user receives a failed response. ### API structure {#api-structure} API Reference: `GET /enrollments/eligibilities/searches` ## Enroll user {#enroll-user} This use case enables enrollment for an initial user and account record into an offers program. This operation is intended solely for new cardholders enrolling with their first account. ### Prerequisite {#prerequisite} This use case requires payload encryption to ensure secure data transmission. Refer to the Payload Encryption Prerequisite section on the [Use Cases](https://developer.mastercard.com/presentment/documentation/use-cases/index.md) page for details. ### Sequence diagram {#sequence-diagram-1} Diagram enroll-user ### Execution steps {#execution-steps-1} 1. The cardholder enrolls in an offers program with their first account. 2. The Publisher authenticates the cardholder. 3. The Publisher sends an encrypted request for enrollment. The enrollment request requires this input parameter: | Parameter | Description | |-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | X-FID | A 4--6 digit Interbank Card Association (ICA) number assigned by Mastercard to the financial institution or partner. This value is provided as an input parameter in the request header. | 4. Mastercard API Gateway validates the Publisher's information and sends the request to User Account Administration. 5. User Account Administration validates the encrypted request. 6. User Account Administration enrolls the user through POST /enrollments/users. 7. If the request is valid, User Account Administration sends a successful response. 8. If the request is invalid, User Account Administration sends a failed response. 9. In the event of an error response for an invalid request or missing request parameter, update the input and repeat step 3. ### API structure {#api-structure-1} API Reference: `GET /enrollments/users` ## Update user {#update-user} This use case applies when a user wants to update personal information for current cardholders, including their name and contact information. ### Sequence diagram {#sequence-diagram-2} Diagram update-user ### Execution steps {#execution-steps-2} 1. The cardholder signs in to the Publisher portal. 2. The Publisher authenticates the cardholder. 3. The Publisher sends an encrypted request for updating user details. The request requires these input parameters: | Parameter | Description | |------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | X-FID | A 4--6 digit Interbank Card Association (ICA) number assigned by Mastercard to the financial institution or partner. This value is provided as an input parameter in the request header. | | Customer Reference Key (CRK) | The unique identifier for the customer issued during enrollment on the offers platform. This value is provided as an input parameter in the request path. | 4. Mastercard API Gateway validates the Publisher's information and sends the request to User Account Administration. 5. User Account Administration validates the encrypted request. 6. User Account Administration updates the user details through PUT /enrollments/users/{crk}. 7. If the request is valid, User Account Administration sends a successful response. 8. If the request is invalid, User Account Administration sends a failed response. 9. In the event of an error response for an invalid request or missing request parameter, update the input and repeat step 3. ### API structure {#api-structure-2} API Reference: `GET /enrollments/users/{crk}` ## Enroll account {#enroll-account} This use case involves enrolling a new account, defined as a unique card, for an existing user, defined as a unique cardholder. ### Prerequisite {#prerequisite-1} Before enrolling an account, the associated user must first be enrolled. Refer to the Enroll User use case for details. This use case requires payload encryption to ensure secure data transmission. Refer to the Payload Encryption Prerequisite section on the [Use Cases](https://developer.mastercard.com/presentment/documentation/use-cases/index.md) page for details. ### Sequence diagram {#sequence-diagram-3} Diagram enroll-account ### Execution steps {#execution-steps-3} 1. The cardholder signs in to the Publisher portal. 2. The Publisher authenticates the cardholder. 3. The Publisher sends an encrypted request for enrollment. The enrollment request requires these input parameters: | Input parameter | Description | |------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | X-FID | A 4--6 digit Interbank Card Association (ICA) number assigned by Mastercard to the financial institution or partner. This value is provided as an input parameter in the request header. | | Customer Reference Key (CRK) | The unique identifier for the customer issued during enrollment on the offers platform. This value is provided as an input parameter in the request path. | 4. Mastercard API Gateway validates the Publisher's information and sends the request to User Account Administration. 5. User Account Administration validates the encrypted request. 6. User Account Administration enrolls the account through POST /enrollments/users/{crk}/accounts. 7. If the request is valid, User Account Administration sends a response with account details. 8. If the request is invalid, User Account Administration sends a failed response. 9. In the event of an error response for an invalid request or missing request parameter, update the input and repeat step 3. ### API structure {#api-structure-3} API Reference: `GET /enrollments/users/{crk}/accounts` ## Update account {#update-account} This use case applies when a user, defined as a cardholder, wants to update the currently enrolled account, defined as a unique card. ### Sequence diagram {#sequence-diagram-4} Diagram update-account ### Execution steps {#execution-steps-4} 1. The cardholder signs in to the Publisher portal. 2. The Publisher authenticates the cardholder. 3. The Publisher sends an encrypted request for updating account details. The request requires these input parameters: | Parameter | Description | |------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | X-FID | A 4--6 digit Interbank Card Association (ICA) number assigned by Mastercard to the financial institution or partner. This value is provided as an input parameter in the request header. | | Customer Reference Key (CRK) | The unique identifier for the customer issued during enrollment on the offers platform. This value is provided as an input parameter in the request path. | | Account Reference Key (ARK) | The unique identifier for the account issued during enrollment on the offers platform. This value is provided as an input parameter in the request path. | 4. Mastercard API Gateway validates the Publisher's information and sends the request to User Account Administration. 5. User Account Administration validates the encrypted request. 6. User Account Administration updates the user account through PUT /enrollments/users/{crk}/accounts/{ark}. 7. If the request is valid, User Account Administration sends a response with a successfully updated account message. 8. If the request is invalid, User Account Administration sends a failed response. 9. In the event of an error response for an invalid request or missing request parameter, update the input and repeat step 3. ### API structure {#api-structure-4} API Reference: `GET /enrollments/users/{crk}/accounts/{ark}` ## Retrieve user and account details {#retrieve-user-and-account-details} This use case supports the retrieval of both user information and the accounts linked to that user. It also supports scenarios where a single user may be associated with multiple accounts. ### Sequence diagram {#sequence-diagram-5} Diagram retrieve-account-user-details ### Execution steps {#execution-steps-5} 1. The cardholder signs in to the Publisher portal. 2. The Publisher authenticates the cardholder. 3. The Publisher sends a signed request for user details. The request requires these input parameters: | Parameter | Description | |------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | X-FID | A 4--6 digit Interbank Card Association (ICA) number assigned by Mastercard to the financial institution or partner. This value is provided as an input parameter in the request header. | | Customer Reference Key (CRK) | The unique identifier for the customer issued during enrollment on the offers platform. This value is provided as an input parameter in the request path. | | Account Reference Key (ARK) | The unique identifier for the account issued during enrollment on the offers platform. This value is provided as an input parameter in the request path. | 4. Mastercard API Gateway authenticates and authorizes the Publisher and sends the request to User Account Administration. 5. User Account Administration validates the request parameters. 6. User Account Administration retrieves the account and user details through GET /enrollments/users/{crk}/accounts/{ark}. 7. If the request is valid, User Account Administration sends a response with account and user details. 8. If the request is invalid, User Account Administration sends a failed response. 9. In the event of an error response for an invalid request or missing request parameter, update the input and repeat step 3. ### API structure {#api-structure-5} API Reference: `GET /enrollments/users/{crk}/accounts/{ark}` ## Card replacements {#card-replacements} This use case applies when a cardholder must replace a lost or stolen card with a new card. ### Prerequisite {#prerequisite-2} This use case requires payload encryption to ensure secure data transmission. Refer to the Payload Encryption Prerequisite section on the [Use Cases](https://developer.mastercard.com/presentment/documentation/use-cases/index.md) page for details. ### Sequence diagram {#sequence-diagram-6} Diagram lost-stolen-card ### Execution steps {#execution-steps-6} 1. The cardholder signs in to the Publisher portal. 2. The Publisher authenticates the cardholder. 3. The Publisher sends an encrypted request to report lost or stolen cards. The request requires these input parameters and fields: | Input parameter | Description | |------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | X-FID | A 4--6 digit Interbank Card Association (ICA) number assigned by Mastercard to the financial institution or partner. This value is provided as an input parameter in the request header. | | Customer Reference Key (CRK) | The unique identifier for the customer issued during enrollment on the offers platform. This value is provided as an input parameter in the request path. | | Field | Description | |-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | oldAccountId | The Account Reference Key (ARK) associated with the original account that is being replaced. | | newAccountNumber | Specifies the new account number, which is required when the action code value is A or B. | | newCustomerNumber | Specifies the new customer number, which is required when the action code value is C or B. | | accountStatus | A code indicating an account's eligibility for opt-in/opt-out. This is required when the action code value is A or B. | | actionCode | Specifies the type of action the request is intended to perform. Note: The supported action codes are: * A: Updates the Bank Account Number.  Required fields: oldAccountId, newAccountNumber, status * B: Updates both the Bank Account Number and the Bank Customer Number.  Required fields: oldAccountId, newAccountNumber, status * C: Updates the Bank Customer Number only.  Required fields: oldAccountId, newCustomerNumber * S: Moves the account from one Bank Customer Number to another.  Required fields: oldAccountId, newCustomerNumber | 4. Mastercard API Gateway validates the Publisher's information and sends the request to User Account Administration. 5. User Account Administration validates the encrypted request. 6. User Account Administration updates the lost or stolen account. 7. If the request is valid, User Account Administration sends the response with a successfully processed lost or stolen request message. 8. If the request is invalid, User Account Administration sends a failed response. 9. In the event of an error response for an invalid request or missing request parameter, update the input and repeat step 3. ### API structure {#api-structure-6} API Reference: `GET /enrollments/users/{crk}/replacements` ## Lookup identifiers {#lookup-identifiers} This use case applies when searching for a user through one of the following identifiers to retrieve user information with or without sensitive data: * Bank Account Number (BAN) * Bank Customer Number (BCN) * Account Reference Key (ARK) * Customer Reference Key (CRK)
These identifiers are established during the onboarding phase in collaboration with a Solution Engineer and are customized to meet the specific needs of each program. ### Prerequisite {#prerequisite-3} This use case requires payload encryption to ensure secure data transmission. Refer to the Payload Encryption Prerequisite section on the [Use Cases](https://developer.mastercard.com/presentment/documentation/use-cases/index.md) page for details. ### Sequence diagram {#sequence-diagram-7} Diagram lookup-identifiers ### Execution steps {#execution-steps-7} 1. The cardholder signs in to the Publisher portal. 2. The Publisher authenticates the cardholder. 3. The Publisher sends the signed or encrypted request for tokens and sensitive identifiers. The request requires these input parameters and fields: | Parameter | Description | |-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | X-FID | A 4--6 digit Interbank Card Association (ICA) number assigned by Mastercard to the financial institution or partner. This value is provided as an input parameter in the request header. | | Field | Description | |-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | userId | A numerical string that uniquely identifies a user or cardholder. | | userIdType | Specifies the type of identifier used for the associated user with values such as: Bank Account Number (BAN), Bank Customer Number (BCN), Account Reference Key (ARK), or Customer Reference Key (CRK). | | programIdentifier | Identifies the program associated with the account and determines which program ID should be populated. | 4. Mastercard API Gateway validates the Publisher's information and sends the request to User Account Administration. 5. User Account Administration validates the request. 6. User Account Administration retrieves the tokens and sensitive identifiers. 7. If the request is valid, User Account Administration responds based on the optional parameter provided: * If the includeSensitiveIdentifiers field is set to true, the response includes encrypted sensitive identifiers. 8. If the request is invalid, User Account Administration sends a failed response. 9. In the event of an error response for an invalid request or missing request parameter, update the input and repeat step 3. ### API structure {#api-structure-7} API Reference: `GET /enrollments/users/searches` ## Submit rebate transaction {#submit-rebate-transaction} This use case enables Publishers and Publisher partners to initiate Mastercard cashback rebates by submitting rebate details through a secure POST endpoint. The Rebate API supports cashback transaction creation and processing by accepting the rebate amount and currency details. This API can help: * Simplify partner integration * Enable consistent rebate issuance * Support timely delivery of cashback benefits to eligible Mastercard cardholders ### Prerequisite {#prerequisite-4} This use case requires payload encryption to ensure secure data transmission. Refer to the Payload Encryption Prerequisite section on the [Use Cases](https://developer.mastercard.com/presentment/documentation/use-cases/index.md) page for details. ### Sequence diagram {#sequence-diagram-8} Diagram submit-rebate-request ### Execution steps {#execution-steps-8} 1. The Publisher or Publisher partner sends the rebate request. The rebate request requires these input parameters: | Parameter | Description | |-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | X-FID | A 4--6 digit Interbank Card Association (ICA) number assigned by Mastercard to the financial institution or partner. This value is provided as an input parameter in the request header. | | accountIdentifier | A unique account identifier represented by either the Account Reference Key (ARK) or Primary Account Number (PAN). | | IdentifierType | ARK or PAN. | 2. Mastercard API Gateway validates the Publisher or Publisher partner's information and sends the request to User Account Administration. 3. User Account Administration validates the request 4. User Account Administration submits the rebate request through POST /rebates. 5. If the request is valid, User Account Administration sends a successful response with the rebate ID value. 6. If the request is invalid, User Account Administration sends a failed response. 7. In the event of an error response for an invalid request or missing request parameter, update the input and repeat step 1. ### API structure {#api-structure-8} API Reference: `GET /rebates` ## Retrieve rebates {#retrieve-rebates} This use case allows Publishers and Publisher partners to retrieve rebate information, either for a specific rebate or for a list of rebates within a specified financial institution identifier (FID) and date range. Rebates can be filtered using parameters such as rebate ID, date range, record limit, and record offset. If a date range is not provided, the response includes rebates from the last 30 days. ### Prerequisite {#prerequisite-5} This use case requires payload encryption to ensure secure data transmission. Refer to the Payload Encryption Prerequisite section on the [Use Cases](https://developer.mastercard.com/presentment/documentation/use-cases/index.md) page for details. ### Sequence diagram {#sequence-diagram-9} Diagram rebate-status ### Execution steps {#execution-steps-9} 1. The Publisher or Publisher partner sends a request to retrieve rebate status information, either for a specific rebate or for all rebates within a specified FID and date range. The request includes the following input parameters: | Parameter | Description | Required | |------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| | X-FID | A 4--6 digit Interbank Card Association (ICA) number assigned by Mastercard to the financial institution or partner. This value is provided as an input parameter in the request header. | Yes | | rebate_id | A unique identifier for an individual rebate. Use this field if the request is for a specific rebate. | No | | start_date | The starting date used to retrieve rebates. This parameter, together with end_date, defines the time window for which rebates are returned. | No | | end_date | The ending date used to retrieve rebates. This parameter, together with start_date, defines the time window for which rebates are returned. | No | | offset | Indicates how many records to skip before starting to collect the result set. | No | | limit | Specifies the maximum number of rebate records returned in a response. | No | 2. Mastercard API Gateway validates the Publisher or Publisher partner's information and sends the request to User Account Administration. 3. User Account Administration validates the encrypted request. 4. User Account Administration retrieves the rebate status through GET /rebates. 5. If the request is valid, User Account Administration sends a successful response with the rebate or list of rebates matching the criteria and their associated metadata such as creation date and status code. 6. If the request is invalid, User Account Administration sends a failed response. 7. In the event of an error response for an invalid request or missing request parameter, update the input and repeat step 1. ### API structure {#api-structure-9} API Reference: `GET /rebates`