# Testing source: https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/testing/index.md Use this page to plan and execute Sandbox and MTF validation for the Benefit Allocation Service API. It covers the recommended workflow, positive and negative coverage, and the reference guides you need for endpoint-level execution. Tip: Start all validation in Sandbox before moving to MTF and Production.
### Sandbox Behaviour {#sandbox-behaviour} The Sandbox environment validates that your mTLS authentication and JWE encryption configuration are correct. Its responses reflect values in the request, but it does not process real card or benefit data. Use Sandbox to confirm your integration setup before moving to MTF, where requests are processed against real pre-production data. | **Environment** | **What it validates** | **Response type** | |-----------------|-------------------------------------------------------------------------|-------------------------------------------------------| | Sandbox | mTLS authentication, JWE encryption, connectivity, certificate validity | Mock response reflects values supplied in the request | | MTF | Full integration with real pre-production data | Real API response based on input | | Production | Live production data | Real API response based on input | ### Choose a testing method {#choose-a-testing-method} Choose a testing method that best matches how you want to validate requests: * [Reference Application](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/dev-tools/reference-app/index.md) * [Insomnia Collection](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/dev-tools/insomnia/index.md) * Custom API client generated as per guidance in [API Basics](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-basics/index.md). ### Recommended testing workflow {#recommended-testing-workflow} Use these separate sequences to validate segment and bundle endpoints with realistic end-to-end flows. #### Segment testing workflow {#segment-testing-workflow} 1. Assign a segment to a card (`POST /card-segments`) 2. Replace the segment with another segment (`PUT /card-segments-replacements`) 3. Replace a PAN number with another PAN number (`POST /cards`) 4. Freeze a card (`PUT /cards` with `isFrozen: true`) 5. Unfreeze a card (`PUT /cards` with `isFrozen: false`) 6. Cancel the segment replaced in step 2 (`PUT /card-segments-cancellations`) This flow gives coverage across segment and card management. #### Bundle testing workflow {#bundle-testing-workflow} 1. Assign bundle(s) to a card (`POST /card-bundles`) 2. Replace assigned bundle(s) (`PUT /card-bundles-replacements`) 3. Update bundle effective and/or expiry dates (`PUT /card-bundles-updates`) 4. Cancel bundle(s) (`PUT /card-bundles-cancellations`) This flow gives coverage across bundle management. Warning: The Benefit Allocation Service API validates card numbers using the Luhn algorithm. ## Positive testing {#positive-testing} Positive testing confirms that valid requests succeed and return the expected data. * Encrypted endpoints accept correctly signed and encrypted payloads. * Valid request bodies return success codes such as 200 OK, or 204 No Content. ### Segment Management {#segment-management} ### Assign Segment {#assign-segment} `POST /card-segments` **Purpose:** Assign a segment to a card through the API. **Required Fields** * cardNumber * segmentCode * effectiveDate **Rules** * API key must be authorized for the card ICA. * Segment must be valid for the ICA and account range. * Effective date must fall within segment eligibility dates. * Only one active segment is allowed. * Reassigning the same active segment returns existing information, with no changes to what was originally received. * Future bundle effective and expiration dates are preserved. * Effective date of the first set of assignments should be coordinated with Mastercard in order to properly set up the configuration. * The segment bundles assigned generally do not have an expiration date. But they could if the Customer asked for the bundle on the segment to have a specific expiration date.
**Common Errors** * Unauthorized API key. * Missing card number. * Missing segment code. * Missing effective date. * Invalid date format. * Invalid segment. * Card not associated to ICA. ```json { "cardNumber": 5291070000000000, "segments": [ { "code": "DART", "effectiveDate": "YYYY-MM-DD" } ] } ``` Expected response: `200 OK` status and body containing ```json { "bundles": [ { "code": "080815", "effectiveDate": "2023-08-08", "expiryDate": "2024-07-24" }, { "code": "087950", "effectiveDate": "2023-09-08", "expiryDate": "2024-08-18" } ] } ``` Customer sends a request with the above parameters as input to Assign Benefits to a card then the Benefit Allocation Service API returns an array of benefit bundles that are assigned to the card. ### Replace Segment {#replace-segment} `PUT /card-segments-replacements` **Purpose:** Replace one active segment with another segment. **Required Fields** * cardNumber * oldSegmentCode * newSegmentCode * effectiveDate
**Rules** * The new segment replacement cannot have an effective date before the old segment effective date. * New segment becomes active on replacement date. * New segment must be valid for ICA. * Effective date must be within segment eligibility dates. * Future bundle dates are preserved. * Replacing a canceled or expired segment is not allowed. * In the response, the segment bundles assigned generally do not have an expiration date. Although, the bundles could if the Customer asked for the bundle on the segment to have a specific expiration date in the segment's configuration.
**Common Errors** * Missing card number. * Missing old segment. * Missing new segment. * Missing effective date. * Invalid date format. * Invalid segment. * PAN does not exist. * Unauthorized API key. ```json { "cardNumber": 5291070000000000, "oldSegmentCode": "DART", "newSegmentCode": "PRT", "effectiveDate": "YYYY-MM-DD" } ``` Expected response: `200 OK` status and body containing ```json { "bundles": [ { "code": "087452", "effectiveDate": "2023-08-08", "expiryDate": "2024-07-24" }, { "code": "263560", "effectiveDate": "2023-09-08", "expiryDate": "2024-08-18" } ] } ``` Customer sends a request with the above parameters as input to Replace Segment to replace the segmented benefits on the card, then the Benefit Allocation Service API returns an array with the new segmented benefit bundles assigned to the card ### Cancel Segment {#cancel-segment} `PUT /card-segments-cancellations` **Purpose:** Expire a segment and all associated bundles within the segment. **Required Fields** * cardNumber * segmentCode * expiryDate
**Rules** * Segment must already be assigned. * The requested expiration date for the segment being cancelled cannot be before the assigned segment effective date. * The requested expiration date for the segment being cancelled can be the same day as the Assigned segment effective date, but the segment would be active for one day. * Expiry date will be used to expire after segment expiration. * All associated bundles are expired.
**Common Errors** * Missing card number. * Missing segment code. * Missing expiry date. * Invalid date format. * Invalid segment. * Unauthorized API key. * Expiry date before effective date. ```json { "cardNumber": 5291070000000000, "segments": [ { "code": "DART", "expiryDate": "YYYY-MM-DD" } ] } ``` Expected response: `200 OK` status and body containing ```json { "bundles": [ { "code": "58780", "effectiveDate": "2023-08-08", "expiryDate": "2024-07-24" }, { "code": "587462", "effectiveDate": "2023-09-08", "expiryDate": "2024-08-18" } ] } ``` Customer sends a request with the above parameters as input then the Benefit Allocation Service API Cancels the benefits associated to the card for the input segment. The response is an array of benefit bundles that are cancelled on the card. ### Card Management {#card-management} ### Card Replacement for a cardholder {#card-replacement-for-a-cardholder} `POST /cards` **Purpose:** Replace one card with another card through the API. **Required Fields** * oldCardNumber * newCardNumber * effectiveDate
**Rules** * Old PAN must exist. * New PAN must not already be in use. * New PAN must be eligible for the ICA/account range. * Segment and bundles move to the new PAN. * Existing PAN is expired.
**Common Errors** * Missing old card number. * Missing new card number. * Invalid PAN format. * Invalid effective date. * New PAN already in use. * Old PAN not found. * Unauthorized API key. ```json { "oldCardNumber": 5291070000000000, "newCardNumber": 5291070000000898, "effectiveDate": "YYYY-MM-DD" } ``` Expected response: `200 OK` status and body containing ```json { "bundles": [ { "code": "080815", "effectiveDate": "2023-08-08", "expiryDate": "2024-07-24" }, { "code": "087452", "effectiveDate": "2023-09-08", "expiryDate": "2024-08-18" } ] } ``` Customer sends a request with the above parameters as input then the Benefit Allocation Service API replaces the card associated with the user. The benefits on the old Card are expired, and the same set of benefits are applied to new Card. The response is an array of bundles that are assigned to the existing card. ### Freeze a card for a cardholder {#freeze--a-card-for-a-cardholder} `PUT /cards` **Purpose:** Temporarily prevent benefits access without canceling assignments. **Required Fields** * cardNumber * isFrozen (true)
**Rules** * Card status is set to Frozen. * Expired cards cannot be frozen. * Card must exist. * API key must be authorized.
**Common Errors** * Missing card number. * Missing isFrozen field. * Invalid card format. * Card not found. * Unauthorized API key. ```json { "cardNumber": 5291070000000000, "isFrozen": true } ``` Expected response: `204 OK` status Customer sends a request with the above parameters as input then the Benefit Allocation Service API freezes the card if isFrozen (boolean) is set to true, Unfreezes the card if the isFrozen (boolean) is set to false. ### Unfreeze a card for a cardholder {#unfreeze-a-card-for-a-cardholder} `PUT /cards` **Purpose:** Unfreezes the card so that the benefits can be used again **Required Fields** * cardNumber * isFrozen (false)
**Rules** * Frozen status is removed. * Expired cards cannot be unfrozen. * Card must exist. * API key must be authorized.
**Common Errors** * Missing card number. * Missing isFrozen field. * Invalid card format. * Card not found. * Unauthorized API key. ```json { "cardNumber": 5291070000000000, "isFrozen": false } ``` Expected response: `204 OK` status Customer sends a request with the above parameters as input then the Benefit Allocation Service API freezes the card if isFrozen (boolean) is set to true, Unfreezes the card if the isFrozen (boolean) is set to false. ### Bundle Management {#bundle-management} ### Assign Bundle(s) to a card {#assign-bundles-to-a-card} `POST /card-bundles` **Purpose:** Assign one or more benefit bundles to a card. **Required fields** * Card Number (PAN) * Bundle Code * Effective Date
**Rules** * A valid API key must be authorized for the ICA that owns the card * One or multiple bundles can be assigned in a single request. * Effective dates may be: * Today * A future date * A past date (if valid for the ICA-to-bundle relationship) * Expiration dates is optional and can be supplied based on use case. * A bundle cannot be assigned if the same bundle is already active on the card. * Bundle effective dates must fall within the active ICA-to-bundle association dates * A previously expired bundle can be reassigned after expiration. * A new assign bundle to extend the cardholder's benefit would need to be sent after the expiration. The effective date needs to be the day after the expiration. 
**Common Errors** * Missing card number. * Missing bundle code. * Missing effective date. * Invalid card number format or length. * Invalid bundle code. * Bundle not authorized for the ICA. * Bundle already active. * Unauthorized API key. * Expiration date before effective date. ```json { "cardNumber": 5291070000000000, "bundles": [ { "code": "080815", "effectiveDate": "YYYY-MM-DD", "expiryDate": "YYYY-MM-DD" } ] } ``` Expected response: `200 OK` status and body containing ```json { "bundles": [ { "code": "080815", "effectiveDate": "2023-08-08", "expiryDate": "2024-07-24" }, { "code": "087524", "effectiveDate": "2023-08-08", "expiryDate": "2024-07-24" } ] } ``` Customer sends a request with the above parameters as input to assign bundle(s) to a card. The Benefit Allocation Service API returns an array of benefit bundles that are assigned to the card. ### Replace Bundle(s) on a card {#replace-bundles-on-a-card} `PUT /card-bundles-replacements` **Purpose:** Replace one bundle with another bundle on the same card. **Required fields** * Card Number * Old Bundle Code * New Bundle Code * Effective Date
**Rules** * A valid API key authorized for the ICA is required. * The old bundle must already be assigned to the card. * The new bundle must be authorized for the ICA. * On the effective date: * The old bundle is expired -1 day from the effective date. * The new bundle is assigned on the effective date. * Replacements can be scheduled for today or a future date. * Past effective dates are not allowed. * Multiple replacements can be submitted in one request. * If any replacement pair is invalid, the request fails. * If a bundle was assigned with an expiration date, the bundle cannot be replaced. * A new assign bundle to extend the cardholder's benefit would need to be sent after the expiration. The effective date needs to be the day after the expiration. 
**Common Errors** * Old bundle not assigned. * New bundle not authorized for the ICA. * Missing effective date. * Past effective date. * Invalid bundle code. * Unauthorized API key. * Invalid card number. ```json { "cardNumber": 5291070000000000, "bundles": [ { "oldBundleCode": "080815", "newBundleCode": "084315", "effectiveDate": "YYYY-MM-DD" } ] } ``` Expected response: `200 OK` status and body containing ```json { "bundles": [ { "code": "084315", "effectiveDate": "2023-08-08", "expiryDate": "2024-07-24" }, { "code": "830475", "effectiveDate": "2023-08-08", "expiryDate": "2024-07-24" } ] } ``` Customer sends a request with the above parameters as input to replace existing bundle(s) on a card. The existing bundle(s) are expired the day before the new bundle effective date and the new bundle(s) are effective on the provided date. The response is an array of benefit bundles that are newly assigned to the card. ### Cancel Bundle(s) from a card {#cancel-bundles-from-a-card} `PUT /card-bundles-cancellations` **Purpose:** Expire an active bundle assignment on a card. **Required fields** * Card Number (PAN) * Bundle Code * Expiration Date
**Rules** * A valid API key authorized for the ICA is required. * A bundle can only be cancelled if it is currently assigned to the card. * Cancellation can be performed: * Effective today * Effective on a future date * Multiple bundles can be cancelled in a single request. * If any bundle in a multi-bundle request is invalid, the request fails. * If a bundle is already expired, the API returns the existing expiration information rather than cancelling again.
**Common Errors** * Bundle not assigned to the card. * Expiration date in the past. * Missing card number. * Missing bundle code. * Invalid card number. * Invalid bundle code. * Unauthorized API key. ```json { "cardNumber": 5291070000000000, "bundles": [ { "code": "080815" } ] } ``` Expected response: `400 Bad Request` status because body is missing "expiryDate" field for the bundle which is required to cancel a bundle from a card. ### Update Bundle(s) on a card {#update-bundles-on-a-card} `PUT /card-bundles-updates` **Purpose:** Change the effective date of an existing future-dated bundle assignment. **Required fields** * Card Number * Bundle Code * New Effective Date
**Rules** * A valid API key authorized for the ICA is required. * Future-dated assignments can be moved: * To today * To a different future date * Active assignments with today's date can be moved to a future date. * Historical (past) effective dates cannot be changed. * The bundle must already be assigned to the card.
**Common Errors** * Attempting to modify a past effective date. * Missing card number. * Missing bundle code. * Invalid effective date format. * Invalid bundle code. * Unauthorized API key. * Invalid card number. ```json { "bundles": [ { "code": "080815", "effectiveDate": "YYYY-MM-DD", "expiryDate": "YYYY-MM-DD" } ] } ``` Expected response: `400 Bad Request` status because body is missing "cardNumber" field which is required to update bundle(s) on a card. ## Negative testing {#negative-testing} Negative testing confirms that invalid requests fail cleanly and return useful error details. For error and reason code definitions and additional troubleshooting guidance, see [Codes and Formats](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/code-and-formats/index.md). ### Validate these behaviors {#validate-these-behaviors} * Missing required fields return 400 Bad Request. * Invalid field values return validation errors with a clear ReasonCode and description. * Requests for unknown resources return 404 Not Found. * Incorrect or missing authentication data is rejected. * Encrypted endpoints reject malformed or unencrypted payloads when encryption is required. ### Segment Management {#segment-management-1} ### Assign Segment {#assign-segment} `POST /card-segments` ```json { "cardNumber": 5291070000000000, "segments": [ { "code": "DART" } ] } ``` Expected response: `400 Bad Request` status because body is missing "effectiveDate" field for the segment. ### Replace Segment {#replace-segment} `PUT /card-segments-replacements` ```json { "cardNumber": 5291070000000000, "oldSegmentCode": "DART", "effectiveDate": "YYYY-MM-DD" } ``` Expected response: `400 Bad Request` status because body is missing "newSegmentCode" field for the segment replacement. ### Cancel Segment {#cancel-segment} `PUT /card-segments-cancellations` ```json { "segments": [ { "code": "DART", "expiryDate": "YYYY-MM-DD" } ] } ``` Expected response: `400 Bad Request` status because body is missing "cardNumber" field which is required to cancel a segment. ### Card Management {#card-management-1} ### Card Replacement for a cardholder {#card-replacement-for-a-cardholder} `POST /cards` ```json { "oldCardNumber": 5291070000000000, "newCardNumber": 5291070000000898, "effectiveDate": "MM-DD-YYYY" } ``` Expected response: `400 Bad Request` status because "effectiveDate" field has invalid format. The expected format is "YYYY-MM-DD". ### Freeze or Unfreeze a card for a cardholder {#freeze-or-unfreeze-a-card-for-a-cardholder} `PUT /cards` ```json { "cardNumber": 52910, "isFrozen": true/false } ``` Expected response: `400 Bad Request` status because "cardNumber" field has invalid format. The expected format is a 16 or 19 digit number. ### Bundle Management {#bundle-management-1} ### Assign Bundle(s) to a card {#assign-bundles-to-a-card} `POST /card-bundles` ```json { "cardNumber": 5291070000000000, } ``` Expected response: `400 Bad Request` status because body is missing "bundles" field which is required to assign bundle(s) to a card. ### Replace Bundle(s) on a card {#replace-bundles-on-a-card} `PUT /card-bundles-replacements` ```json { "bundles": [ { "oldBundleCode": "080815", "newBundleCode": "080817", "effectiveDate": "YYYY-MM-DD" } ] } ``` Expected response: `400 Bad Request` status because body is missing "cardNumber" field which is required to replace bundle(s) on a card. ### Cancel Bundle(s) from a card {#cancel-bundles-from-a-card} `PUT /card-bundles-cancellations` ```json { "cardNumber": 5291070000000000, "bundles": [ { "code": "080815" } ] } ``` Expected response: `400 Bad Request` status because body is missing "expiryDate" field for the bundle which is required to cancel a bundle from a card. ### Update Bundle(s) on a card {#update-bundles-on-a-card} `PUT /card-bundles-updates` ```json { "bundles": [ { "code": "080815", "effectiveDate": "YYYY-MM-DD", "expiryDate": "YYYY-MM-DD" } ] } ``` Expected response: `400 Bad Request` status because body is missing "cardNumber" field which is required to update bundle(s) on a card. ### Next steps {#next-steps} * Check the [API Reference](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-reference/index.md) for complete endpoint specifications, request and response schemas, and environment URLs. * If you run into issues, visit [Support](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/support/index.md) for FAQs and troubleshooting guidance.