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

## Overview {#overview}

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 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. 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 OAuth 1.0a request signing and JWE payload encryption. See [API Basics](https://developer.mastercard.com/benefit-allocations-service/documentation/api-basics/index.md) for authentication, encryption, and environment requirements.

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

The Benefit Allocation Service API provides a set of services that simplify the management of cardholders'
benefits based off the PAN's segment or bundle.

![Overview Image](https://static.developer.mastercard.com/content/benefit-allocations-service/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-allocations-service/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-allocations-service/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-allocations-service/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-allocations-service/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-allocations-service/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-allocations-service/documentation/use-cases/segment-operations/cancel_segment/index.md) or [Cancel Bundles](https://developer.mastercard.com/benefit-allocations-service/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-allocations-service/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-allocations-service/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 -- Benefit Allocation Service also supports batch processing, often used for mass 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 provision Benefit Allocation Service
for 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.

Benefit Allocation Service is the first step to initiate 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 a 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 a Luhn checked PANs for API integration testing/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 bundle allocation, Benefit Allocation Service will respond with the bundle assignments.
* Once Benefit Allocation Service has the PAN's segments or bundles, vendors and issuers can use the Benefit Eligibility APIs to retrieve information about the cardholder's configured benefits.
* The Issuer can request to change PAN information, cancel the segment or bundles, replace the segment or bundles, update the bundle dates, freeze or unfreeze the card or replace the card which are available to request changes through Benefit Allocation Service.
* Issuer should track all API activity on the Cardholders cards both success or failures and the sequence of activities for history, proper API usage and troubleshooting.

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

> * **Onboarding Information:** Onboarding starts by creating an account on [Mastercard Developers](https://developer.mastercard.com/) and generating Sandbox project credentials. Production access is requested later for the same project.
> * **Testing Information:** We have an [Open Sandbox](https://developer.mastercard.com/benefit-allocations-service/documentation/api-reference/index.md) that you can use to test Sandbox calls.
> * **Batch \& API Support:** Segment changes are available through both batch processing and Benefit Allocation Service APIs. Freezing/unfreezing and bundle assignment changes are available exclusively through Benefit Allocation Service APIs.
> * **Region Availability/Border Control:** Benefit Allocation Service is available globally.

## Next Steps {#next-steps}

* Review our [API Basics](https://developer.mastercard.com/benefit-allocations-service/documentation/api-basics/index.md) to learn about the Mastercard environments and authentication requirements.
* Review the [Use Cases](https://developer.mastercard.com/benefit-allocations-service/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-allocations-service/documentation/quick-start-guide/index.md) for more information on how to complete authentication requirements in order to access any Mastercard API.