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

## Overview {#overview}

The Benefit Allocation Service (BAS) allows issuers to efficiently manage cardholder value propositions in real-time. It enables the assignment and replacement of benefits, the freezing and unfreezing of cards, and the complete 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. BAS revolutionizes this process by offering instant, automated solutions on a single platform, enhancing operational efficiency and customer satisfaction. Its flexibility and responsiveness ensure issuers can meet the dynamic needs of their cardholders.

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

The Benefits Personalization Service API provides a set of services that simplify the management of cardholder's benefits based off the PAN's segment.

![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/Freeze/Unfreeze a benefit or a card.
3. Confirm activation of benefits.
4. New card or benefits active or card frozen / unfrozen.

## Summary of the Benefit Allocation Service API functions: {#summary-of-the-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.                                                                                                               |

## 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 -- Benefit Allocation Services also support a batch process. Often times, the batch process is used to support mass data loads when initially onboarding cardholders.
* Backwards-compatibility of the API version.

|        Roles         |                                                                               Description                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Issuer/Customer      | Establishes segments of benefits including core or optional benefits. This must be pre-configured in the Mastercard system during the Benefit Allocation Services 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 provision Benefits Allocation Service API benefit to the cardholders. Ensure that you have completed all the contractual steps with your Mastercard representative. You may need to get the 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 is securely exchanged through the rest of the provider network and services when applicable.

* Issuer decides on segments based on their portfolios and which benefits will apply.
* Issuer establishes which cardholders should be assigned a segment.
* Mastercard will configure the segments and benefits, 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 and configuration).
* Mastercard manages provider readiness and provides the flexibility globally.
* The issuer issues Mastercard cards with specified benefit to their cardholders.
* Issuer will then send requests to Global Benefits Platform (GBP) to receive the PAN association with the segment.
* After a successful PAN to segment allocation, GBP will respond with the bundle assignments.
* Once GBP has the PAN segments, when any of the vendors or issuer needs information on the benefits, the proper information based on the personalization will be provided through the Benefit Eligibility and Benefit Content Eligibility APIs to applicable stakeholders.
* The Issuer can request to change PAN information, cancel the segment, replace the segment, freeze or unfreeze the card or replace the card which are available to request changes through GBP Benefit Allocation Services.

## 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.

## 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/platform/documentation/getting-started-with-mastercard-apis/renewing-your-keys/) for more information on how to complete authentication requirements in order to be able to access any Mastercard API.