# Benefit Allocation Service
source: https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/index.md

## Overview {#overview}

The Benefit Allocation Service allows issuers to efficiently manage cardholder value propositions in real time. It enables the assignment, replacement and cancellation of benefits, the freezing and unfreezing of cards, and the replacement of cards. Historically, benefits were assigned using a one-size-fits-all approach, limited by batch processing, which delayed critical changes and fragmented card management. The Benefit Allocation Service streamlines this process with automated solutions on a single platform, enhancing operational efficiency and customer satisfaction. Its flexibility and responsiveness help issuers meet the changing needs of their cardholders.

The API uses mTLS client authentication and JWE payload encryption. See [API Basics](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-basics/index.md) for authentication, encryption, and environment requirements.

## How It Works {#how-it-works}

The Benefit Allocation Service API provides services that simplify the management of cardholder benefits based on the PAN's segment or bundle.

![Overview Image](https://static.developer.mastercard.com/content/benefit-allocation-service-mtls/uploads/bas-howitworks.png)

1. Request a new card, benefit, or freezing / unfreezing a card.
2. Assign/Replace/Cancel/Freeze/Unfreeze a benefit or a card.
3. Confirm activation of benefits.
4. New card or benefits active or card frozen / unfrozen.

## Summary of Benefit Allocation Service API functions: {#summary-of-benefit-allocation-service-api-functions}

|    Function     |                                                                           Description                                                                            |
|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Assign Segment  | Assigns segment to a card by sending a card number, segment code and effective date in the input.                                                                |
| Replace Segment | Replaces the segment and the existing benefits with the new set of benefits that are on the new Segment Code.                                                    |
| Cancel Segment  | Cancels a segment and the benefits associated to the card for the input segment.                                                                                 |
| Card Replace    | Replaces the card number associated with the user. The benefits on the old card number are expired, and the same set of benefits are applied to new card number. |
| Freeze/Unfreeze | Allows freezing or unfreezing a card for benefits.                                                                                                               |
| Assign Bundles  | Assigns bundle(s) to a card by sending a card number, bundle code(s) and effective date in the input.                                                            |
| Replace Bundles | Replaces the existing bundle(s) and assigns the new bundle(s).                                                                                                   |
| Cancel Bundles  | Cancels the bundle(s) sent in the request.                                                                                                                       |
| Update Bundle   | Updates existing bundle dates for a card based on the request input.                                                                                             |

#### Which operation should I use? {#which-operation-should-i-use}

|                       Issuer scenario                        |                                                                                                                                                   Operation                                                                                                                                                   |                                              Result                                              |
|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| Enroll a cardholder in a preconfigured benefits group        | [Assign Segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/assign_segment/index.md)                                                                                                                                                         | Assigns the segment and returns its associated benefit bundles.                                  |
| Change a cardholder's group and associated benefits          | [Replace Segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/replace_segment/index.md)                                                                                                                                                       | Expires the old segment's bundles and assigns the new segment's bundles from the effective date. |
| Add one or more individual benefit packages to a card        | [Assign Bundles](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/assign_bundles/index.md)                                                                                                                                                          | Assigns the requested bundles with their effective and expiry dates.                             |
| Change an assigned benefit package                           | [Replace Bundles](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/replace_bundles/index.md)                                                                                                                                                        | Expires the old bundle and assigns its replacement from the effective date.                      |
| Change the dates of an assigned bundle without changing it   | [Update Bundle](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/update_bundles/index.md)                                                                                                                                                           | Updates the bundle's effective and/or expiry date while keeping the same bundle code.            |
| Permanently remove a segment or selected bundles             | [Cancel Segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/cancel_segment/index.md) or [Cancel Bundles](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/cancel_bundles/index.md) | Expires the selected assignment(s); canceling a segment also expires its associated bundles.     |
| Temporarily suspend or restore benefit eligibility on a card | [Freeze/Unfreeze Card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/card-operations/freeze_unfreeze/index.md)                                                                                                                                                     | Suspends or reinstates benefit eligibility without changing segment or bundle assignments.       |
| Move existing benefit assignments to a replacement card      | [Replace Card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/card-operations/card_replacement/index.md)                                                                                                                                                            | Expires benefits on the old card and applies them to the replacement card.                       |

## Benefit Allocation Service Program Participants and Interactions {#benefit-allocation-service-program-participants-and-interactions}

Benefit Allocation Service participants, their roles, responsibilities, and how they interact with each other.

### Outlined below is what needs to be completed before developers can access this service. {#outlined-below-is-what-needs-to-be-completed-before-developers-can-access-this-service}

* Key mapping -- customers need to provide the Consumer IDs (keys) for Mastercard to link to the proper ICAs.
* Compatibility of the API -- The Benefit Allocation Service also supports batch processing, often used for large data loads when initially onboarding cardholders.
* Backwards-compatibility of the API version.

|        Roles         |                                                                        Description                                                                        |
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| Issuer/Customer      | Establishes benefits, including core or optional benefits. These must be pre-configured in the Mastercard system during Benefit Allocation Service setup. |
| Mastercard           | The Mastercard implementation team takes the catalog information and configures the platform via the proprietary tools.                                   |
| Issuer API Developer | Develops the backend API client, using the Mastercard API signer libraries for authentication, to invoke the various API functions.                       |

### Before You Start {#before-you-start}

A Mastercard representative will be assigned once the issuer has agreed to provide cardholder benefits through the Benefit Allocation Service API. Complete all contractual steps with your Mastercard representative. You may need to obtain documents from your representative and make them available to your cardholders.

The Benefit Allocation Service is the first step to initiate the differentiated cardholder benefits, which are securely exchanged through the rest of the provider network and services when applicable.

* Issuer decides on benefits based on their portfolios and which benefits will apply.
* Issuer establishes which cardholders should be assigned benefits.
* The ICA, segment and/or bundles must be agreed to and established by the Issuer and Mastercard before using in the APIs.
* Mastercard will configure the segments and / or bundles, which is required before the API can be used. This setup process can take up to 3 to 8 weeks (including issuer's definition of segments, bundles and configuration).
* Mastercard manages provider readiness and provides the flexibility globally.
* The issuer issues Mastercard cards with specified benefit to their cardholders.
* Issuer must use Luhn-checked PANs for API integration testing and production validations.
* Issuer will then send requests to Benefit Allocation Service to receive the PAN association with the segment or bundles.
* After a successful PAN-to-segment or PAN-to-bundle allocation, Benefit Allocation Service will respond with the bundle assignments.
* Once Benefit Allocation Service has the PAN segments or bundles, when any vendors or issuers need information on the benefits, the proper information based on the personalization will be provided through the Benefit Eligibility APIs to applicable stakeholders.
* The issuer can request changes to PAN information, cancel or replace segments or bundles, update bundle dates, freeze or unfreeze a card, or replace a card through the Benefit Allocation Service.
* Issuer should track all API activity on cardholder cards, whether successful or failed, using response codes and correlation IDs.

## Good to Know {#good-to-know}

Before testing with the API, the Client Key will need to be shared with the Mastercard Implementation team.
Go to the API basics section that will describe important concepts of your service. Click [API basics](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-basics/index.md) for documentation about what is expected.

* **Authentication and encryption:** All configured environments use mTLS client authentication and support JWE payload encryption. See [API Basics](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-basics/index.md) for certificate and encryption setup.
* **Testing environments:** Sandbox validates mTLS and JWE configuration and returns responses that reflect values in the request, but it does not process real card or benefit data. Use MTF for end-to-end testing with real pre-production data. See the [Testing guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/testing/index.md).
* **Batch and API support:** Batch processing is available for segment changes and card replacements. Use the APIs for bundle management and card freeze/unfreeze operations. See the [use cases](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/index.md) for operation details.
* **Availability:** The Benefit Allocation Service is available globally.

## Next Steps {#next-steps}

* Review our [API Basics](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-basics/index.md) to learn about the Mastercard environments and authentication requirements.
* Review the [Use Cases](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/index.md) to understand how the Benefit Allocation Service API facilitates the supported operations.
* See our [Quick Start Guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/quick-start-guide/index.md) for more information on how to complete authentication requirements in order to access any Mastercard API.