# Support
source: https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/support/index.md

## FAQ {#faq}

### General {#general}

A **segment** is an issuer-defined group that determines which benefits a cardholder receives. A **bundle** is one or more benefits that can be assigned directly to a card or included in a segment's configured benefits. A **card value proposition** is the set of benefits and services offered to a cardholder. The Benefit Allocation Service lets issuers manage these assignments through segments and bundles. See the [segment use cases](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/index.md) and [bundle use cases](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/index.md) for details. Yes. Freeze/Unfreeze Card temporarily suspends or restores benefit eligibility. The card's segment and bundle assignments remain unchanged. Use cancellation operations when benefits should be removed. Benefit Allocation Service is typically used when traditional BIN and product-level benefit assignment is not flexible enough. For example:

* Different cardholders on the same card product need different benefits.

* Benefits need to be provided to a targeted customer segment program.

* Individual cardholders need custom benefit packages.

* Benefits need to be added, changed, or removed during the card lifecycle.

Benefit Allocation Service gives customers additional granular control over segment and/or benefit eligibility at the cardholder level.

Example 1: VIP Travel Program

* Cardholder promoted to VIP tier
* Assign VIP Segment
* Travel benefits become active

<br />

Example 2: Airport Lounge Promotion

* Assign promotional Bundle
* Benefit active for 90 days
* Bundle expires
1. Create or configure segments and bundles during onboarding.
2. Call Assign Segment or Assign Bundle.
3. Update eligibility using Replace Segment or Bundle APIs.
4. Temporarily suspend access using Freeze.
5. Reinstate access using Unfreeze.
6. Move benefits to a new card using Replace Card.
7. Remove benefits using Cancel Segment or Bundle APIs.
A **segment** is a group defined by the customer that determines which benefits a cardholder receives. Each segment is linked to a specific set of benefits configured during Benefit Allocation Service setup. As part of pre-configuration at Mastercard, each segment can be linked to more than one bundle. A cardholder cannot be linked to more than one segment.

A **bundle** is one or more benefits. A bundle of benefit(s) is defined by the customer and determines which benefits a cardholder receives. Each bundle is linked to a specific set of benefits configured during Benefit Allocation Service setup.

|        Question         |                Segment                |                Bundle                 |
|-------------------------|---------------------------------------|---------------------------------------|
| What is it?             | Group of cardholders                  | Collection of benefits                |
| Purpose                 | Defines eligibility group             | Defines benefits package              |
| Assigned to cardholder? | Yes Assigned by issuer business rules | Yes Assigned directly to a cardholder |
| Contains benefits?      | References benefits                   | Contains benefits                     |
| Typical use             | Premium tiers                         | Promotional offerings                 |
| How many benefits?      | Can contain one or more benefits      | Can contain one or more benefits      |

**Can I use segments, bundles, or both?**

Yes, depending on your implementation, you may:

* Use only Segments

* Use only Bundles

* Use both Segments and Bundles

The appropriate approach depends on the Customer's objectives, how rules will be managed, and benefits allocated for cardholders. See the [segment use cases](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/index.md) and [bundle use cases](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/index.md) for operation details.
The main use cases for these services include:

* [Assign segments to a card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/assign_segment/index.md)

* [Replace segments on a card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/replace_segment/index.md)

* [Cancel segments from a card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/cancel_segment/index.md)

* [Replace a card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/card-operations/card_replacement/index.md)

* [Freeze/unfreeze a card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/card-operations/freeze_unfreeze/index.md)

* [Assign bundles to a card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/assign_bundles/index.md)

* [Replace bundles on a card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/replace_bundles/index.md)

* [Cancel bundles from a card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/cancel_bundles/index.md)

* [Update bundles on a card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/update_bundles/index.md)

<br />

Sample Scenarios

|                   Scenario                    | How Benefit Allocation Service Helps |
|-----------------------------------------------|--------------------------------------|
| Premium customers receive additional benefits | Assign a premium segment or bundle   |
| Promotional benefit campaign                  | Add a temporary bundle               |
| Upgrade or change customer benefits           | Replace segment or bundle            |
| Account closure or suspend benefits           | Cancel segment or bundle             |
| Lost/stolen card or pause benefits            | Freeze benefits                      |
| Resume benefits                               | Unfreeze benefits                    |
| Card reissue and move benefits to a new card  | Replace card                         |
| Add custom benefits to a card                 | Assign Bundle                        |

Examples:

**Customer Upgrade**

1. Cardholder qualifies
2. Customer to Assign Segment
3. Benefits become available through Benefit Allocation Service

**Promotion Campaign**

1. Cardholder selected
2. Customer to Assign Bundle
3. Rule or Promotion expires
4. Customer to Cancel Bundle

**Lost Card**

1. Cardholder Lost Card
2. Customer to Freeze Card
3. Customer to Unfreeze Card
4. Customer to Replace Card
* **[Assign segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/assign_segment/index.md)** adds a segment to a card so the cardholder can receive the benefits linked to that segment.

* **[Replace segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/replace_segment/index.md)** changes the card from one segment to another segment. The existing segment benefits are expired the day before the effective date of the new segment, and the benefits linked to the new segment are assigned using the provided effective date.

* **[Cancel segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/cancel_segment/index.md)** removes the benefits linked to the current segment from the card.

* **[Assign bundle](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/assign_bundles/index.md)** adds a bundle to a card so the cardholder can receive the benefits.

* **[Replace bundle](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/replace_bundles/index.md)** changes the card bundle from one bundle to another bundle. The existing benefits are expired the day before the effective date of the new bundle, and the benefits linked to the new bundle are assigned using the provided effective date.

* **[Cancel bundle](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/cancel_bundles/index.md)** removes the benefits linked to the current bundle from the card.

<br />

Organization structure:

      Cardholder 
          ↓  
      Segment (Optional CH grouping like a program)
          ↓
      Bundles
          ↓
      Benefits

* **[Replacing a segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/replace_segment/index.md)** changes the benefits associated with the same card by moving the card from one segment to another segment.

* **[Replacing a card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/card-operations/card_replacement/index.md)** moves the benefits from an old card number to a new card number. The benefits on the old card are expired, and the same set of benefits and the original effective dates are applied to the new card number.

Use \[**freeze** \](/documentation/use-cases/card-operations/freeze_unfreeze/) when benefits should be temporarily unavailable, such as when a card is lost, stolen, or the account needs to block all benefits on the card (handling may vary by benefit provider).

Use [**cancel a 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) when assigned benefits should be removed from the card.

If a card is frozen and you want to cancel the segment but reinstate their standard card benefits, first [unfreeze the card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/card-operations/freeze_unfreeze/index.md) and then [cancel the segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/cancel_segment/index.md), so the cardholder can still receive their other benefits.
No. [Freezing a card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/card-operations/freeze_unfreeze/index.md) does not cancel or replace the segment. It temporarily prevents the cardholder from using benefits on that card until the card is unfrozen. When a card is [unfrozen](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/card-operations/freeze_unfreeze/index.md), the cardholder can use benefits on that card again, assuming the card and associated benefits are still valid. Issuers are all potential consumers of this API. Benefit Allocation Service is a global product and is available in all markets. For pricing information about Benefit Allocation Service, contact a Mastercard representative or account manager. Yes. Segments, bundles, and their associated benefits must be configured during Benefit Allocation Service setup before they can be used through the API. If all cardholders on a card product receive the same benefits, Benefit Allocation Service may not be required.

### Onboarding {#onboarding}

Access to Benefit Allocation Service requires completing onboarding and environment setup with Mastercard. Complete the Sandbox onboarding steps to validate authentication and integration. Finalize the required onboarding prerequisites to enable Production access. For detailed onboarding steps, follow our onboarding guide in the [Quick Start Guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/quick-start-guide/index.md) To test Benefit Allocation Service in the Sandbox environment, create a project, generate sandbox keys, and use the test data. Refer to the [Quick Start Guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/quick-start-guide/index.md) for details. Create a Mastercard Developers project for Benefit Allocation Service and generate Sandbox mTLS certificates and encryption keys. Follow the [Quick Start Guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/quick-start-guide/index.md) for the complete setup steps. Complete Sandbox testing and the Production access prerequisites in your Mastercard Developers project, then submit a Production access request. Follow the [Quick Start Guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/quick-start-guide/index.md) for the complete process. A Sandbox key is intended just for testing purposes. In the Sandbox environment, you can run requests to verify functionality during Sandbox or MTF testing. See [API Basics](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-basics/index.md) for environment details and the [Testing guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/testing/index.md) for the recommended validation workflow.

A Production key gives you access to the live production environment. Any requests you make in the production environment will affect cardholders and needs to be carefully considered.
**Business Setup**

* Contract signed

* Segments defined

* Bundles defined

**Technical Setup**

* Mastercard Developers access created and project created

* Keys issued

* Encryption and data configured

**Testing**

* Sandbox and MTF completed

**Production**

* Company verification approved

* Production access approved

Refer to the [Quick Start Guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/quick-start-guide/index.md) page.

### Integration {#integration}

The card number is the full 16-digit card number. The effectiveDate is the date when a segment or bundle assignment, replacement, or card replacement takes effect. The format is yyyy-mm-dd, and all dates use UTC. See the [segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/assign_segment/index.md) and [bundle](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/assign_bundles/index.md) assignment examples for date usage. The expiryDate ends the segment or benefit for the cardholder. If it is omitted or empty, the benefits remain active until they are canceled, replaced, or otherwise changed. The format is yyyy-mm-dd, and all dates use UTC. See the [bundle assignment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/assign_bundles/index.md) and [bundle cancellation](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/cancel_bundles/index.md) examples. Mastercard recommends for Issuers to send bundles with the Effective date \>= Today's date; Expiration dates (when applicable) to be \>= Today's date and \>= the Effective date. Back dating of either field may cause servicing issues with service providers. For operation-specific date rules, see [Assign Bundles](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/assign_bundles/index.md), [Replace Bundles](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/replace_bundles/index.md), and [Replace Segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/replace_segment/index.md). **[Canceling a segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/cancel_segment/index.md)** removes the segment and its associated benefits from the card. This is used when the cardholder should no longer receive the benefits assigned through that segment.

**[Canceling a bundle](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/cancel_bundles/index.md)** removes the bundle and its associated benefits from the card. This is used when the cardholder should no longer receive the benefits assigned for that bundle.

**[Freezing a card](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/card-operations/freeze_unfreeze/index.md)** temporarily stops the cardholder from using benefits on that card, usually when the card is lost, stolen, or the account needs to be blocked. Freezing does not remove the segment or bundle; it only pauses access to benefits until the card is unfrozen.
As part of Benefit Allocation Service requirements, Mastercard and the customer agree to the applicable segments, bundles, and benefits that will be used in the APIs.

Segments are defined during onboarding based on the issuer's business rules and customer programs. The issuer determines which cardholders qualify for each configured segment or bundle and uses the Benefit Allocation Service APIs to assign them. See the [segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/index.md) and [bundle](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/bundle-operations/index.md) use cases for available operations.
The APIs use JSON request and response bodies. See [API Basics](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-basics/index.md) and the [API Reference](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-reference/index.md) for integration details and endpoint schemas. See [API Basics](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-basics/index.md) for this API's mTLS requirements, then use the [Quick Start Guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/quick-start-guide/index.md) to generate and configure your project credentials. Do not retry failed requests until the issue described in the error response has been addressed. The exception is error code 40099909, where retrying the request is recommended. If not retrying automatically, please research and determine the cause of the issue before resending a new request.

|      Error Type      |        Retry?        |
|----------------------|----------------------|
| Validation Error     | No                   |
| Authentication Error | No                   |
| Business Rule Error  | No                   |
| System Error         | Depends on the error |
| 40099909             | Yes                  |

For more information, please visit the [Code and Formats](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/code-and-formats/index.md) page.
All Benefit Allocation Service API responses include a Correlation ID (correlation-id) header value, which is a unique ID for each API call in Mastercard systems. We recommend you log this ID for tracking purposes. When seeking support, providing the relevant Correlation ID may help resolve your inquiry more quickly. The Benefit Allocation Service is available through APIs using mTLS, batch files, or a combination of both. All capabilities are available through the Benefit Allocation Service APIs. Batch files are limited to segment updates and card replacements for benefits managed by the Benefit Allocation Service.

Bundle management through Benefit Allocation Service is only available through the API.
If the customer is using segments, then the APIs for assigning or cancelling the segment, and to replace the card are required. If the Customer allows a cardholder to swap between segments, then replace segment API is required.

If the customer is using bundles, then the API to assign bundle is required. The APIs to cancel the bundle or to replace the card are conditionally required based on use cases. The API to replace the bundle is optional.

The APIs to freeze or unfreeze the card, are optional.
A successful API request will return an HTTP 200 response, indicating that Mastercard successfully received and processed the request.

As a best practice, Customers should also:

* Verify the response code returned by the API.

* Log the Correlation ID provided in the response headers for troubleshooting and support purposes.

* Review any response messages or error details returned by the API.

* Monitor application logs and integration monitoring tools to confirm the request completed successfully.

* Contact Mastercard Support and provide the Correlation ID if there are questions about the processing of a request.

A successful response confirms that the request was accepted and processed according to Benefit Allocation Service business rules. If the API returns an error response, review the error code and message before retrying the request. Error code **40099909** is the exception where retrying the request is recommended. See the [Testing guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/testing/index.md) for end-to-end validation and [Codes and Formats](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/code-and-formats/index.md) for error details.
**Initiation/Sandbox**

* Complete onboarding

* Obtain Mastercard Developers access and credentials

* Obtain encryption certificates

* Final agreements on segments and bundles

**MTF**

* Configure segments

* Configure bundles

* Validate authentication

* Complete Company Verification step

* Execute test calls

* Monitor APIs and track correlation IDs

* Validate Benefit Allocation Service test cases are successful for MTF testing

**Production**

* Configure segments

* Configure bundles

* Complete production access and certificates

* Generate production keys

* Go live

* Monitor APIs and track correlation IDs

Refer to the [Quick Start Guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/quick-start-guide/index.md) page.

### Policy {#policy}

The request payload must be encrypted as it has PCI data, the response is not encrypted as there is no sensitive data in the response. Please find more details [here](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/). The PEM certificate for encryption can be downloaded from the project page under Client Encryption Keys -\> Actions -\> Download encryption key. Yes, all our APIs are PCI compliant.

### Performance {#performance}

The observed average response time per endpoint is 0.468 seconds. Actual response times may vary depending on endpoint, request volume, and environment. The Transactions per Second (TPS)/Throughput is around 25. Actual throughput may vary depending on endpoint, request volume, and environment. The API gateway allows up to 500 requests per second by default. If you send more than that, some requests may not go through. Mastercard may adjust this limit to keep the service reliable for everyone.

### Support {#support}

When you contact Mastercard and request access to this service, you are typically connected with a regional Mastercard representative who can provide further information about Benefit Allocation Service and guide you through onboarding for access, registration and eligibility requirements. When you are ready for program implementation, you will be assigned a Mastercard Delivery Manager who will guide you through implementation.   
If you have not been connected with a Mastercard representative, please contact us to request a regional representative, identifying your company name, region, and the Benefit Allocation Service products and services that interest you. The [API Status page](https://developer.mastercard.com/api-status) informs Mastercard Developers users of the status of each API. On the site you can toggle between Sandbox and Production environments and find the status of the Benefit Allocation Service using the search bar. Please refer to the credential management guide [here](https://developer.mastercard.com/platform/documentation/credential-management/)

## Get Help {#get-help}

### Contact us for technical support. {#contact-us-for-technical-support}