Mastercard

Mastercard Benefit-Allocations-Card-Management API

Endpoints to freeze/unfreeze a card and replace a card for a cardholder.

Documentation GitHub OpenAPI

Operations 2

POST /cards Mastercard Replace Card Number for a Cardholder #

PUT /cards Mastercard Freeze/unfreeze a Card for Benefits #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/mastercard-benefit-allocations-card-management-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Mastercard Benefit Allocation Service Benefit Allocations Card Management API
  description: Benefits Allocation Service API facilitates the management of benefit segments to cards by enabling the assignment, replacement, or cancellation of benefits. It also provides the ability to freeze or unfreeze benefits associated with a card number and can replace a card  for a cardholder.
  contact:
    name: API Support
    url: https://developer.mastercard.com/support
    email: apisupport@mastercard.com
  version: 1.0.0
servers:
- url: https://sandbox.api.mastercard.com/loyalty/benefits
  description: Sandbox server
- url: https://api.mastercard.com/loyalty/benefits
  description: Production server
tags:
- name: Benefit-Allocations-Card-Management
  description: Endpoints to freeze/unfreeze a card and replace a card for a cardholder.
paths:
  /cards:
    post:
      tags:
      - Benefit-Allocations-Card-Management
      summary: Mastercard Replace Card Number for a Cardholder
      description: 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.
      operationId: cardReplacement
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/CardReplacementRequest'
      responses:
        '200':
          description: Contains bundles associated details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bundles'
              examples:
                ReplaceCardExample:
                  $ref: '#/components/examples/ReplaceCardExample'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Benefit-Allocations-Card-Management
      summary: Mastercard Freeze/unfreeze a Card for Benefits
      description: Freezes a card for benefits, or unfreezes the card for benefits. isFrozen set to true freezes the card, and isFrozen set to false unfreezes the card.
      operationId: freezeUnfreeze
      x-mastercard-api-encrypted: true
      requestBody:
        $ref: '#/components/requestBodies/FrozenCardRequest'
      responses:
        '204':
          $ref: '#/components/responses/BenefitAllocationEmptyResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  examples:
    ReplaceCardExample:
      value:
        bundles:
        - code: PC4657
          effectiveDate: '2022-01-18'
          expiryDate: '2024-07-18'
        - code: PC6323
          effectiveDate: '2022-01-18'
          expiryDate: '2024-07-18'
    BadRequestExample:
      value:
        Errors:
          Error:
          - Source: Benefit Allocation Service
            ReasonCode: 50
            Description: invalid card number, segment code, date
            Recoverable: false
            Details: invalid card number format
    ForbiddenExample:
      value:
        Errors:
          Error:
          - Source: Benefit Allocation Service
            ReasonCode: PERMISSION_DENIED
            Description: You don't seem authorized to do that
            Recoverable: false
            Details: cardNumber not mapped to requester
  schemas:
    Error:
      type: object
      properties:
        Source:
          type: string
          minLength: 0
          maxLength: 200
          description: Information about where the error happened
          example: benefits allocation api
        ReasonCode:
          type: string
          minLength: 0
          maxLength: 200
          description: An error code
          example: Bad request
        Description:
          type: string
          minLength: 0
          maxLength: 10000
          description: A description of the error
          example: string
        Recoverable:
          type: boolean
          description: Indicates if the request can be presented again for processing
          example: string
        Details:
          type: string
          minLength: 0
          maxLength: 100000
          description: More details about the error
          example: Invalid JSON payload
    FrozenCard:
      required:
      - cardNumber
      - date
      - isFrozen
      type: object
      properties:
        cardNumber:
          type: integer
          format: int64
          description: 16 or 19 digit PAN number that will be frozen/unfrozen.
          example: 5291070000000000
        date:
          type: string
          description: Date at which the freeze will be effective. Date should be in YYYY-MM-DD format.
          format: date
          example: '2023-08-08'
        isFrozen:
          type: boolean
          description: Variable to change whether or not the card number is frozen. True for freeze and false for unfreeze.
          example: true
    CardReplacement:
      required:
      - oldCardNumber
      - newCardNumber
      - effectiveDate
      type: object
      properties:
        oldCardNumber:
          type: integer
          format: int64
          description: 16 or 19 digit PAN number that will be expired and replaced along with its benefit bundles.
          example: 5291070000000000
        newCardNumber:
          type: integer
          format: int64
          description: New 16 or 19 digit PAN number that will have the same unexpired set of benefits as the old card number.
          example: 5291070000000898
        effectiveDate:
          type: string
          description: Date at which the replace will be effective. Date should be in YYYY-MM-DD format.
          format: date
          example: '2023-08-08'
    Bundles:
      type: object
      properties:
        bundles:
          type: array
          description: List of eligible benefit bundles after a segment has been assigned to a card number.
          items:
            $ref: '#/components/schemas/BundleDetails'
          example: []
    errors:
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          description: Object that contains the list of errors
          items:
            $ref: '#/components/schemas/Error'
          example: []
    ErrorWrapper:
      description: A top level object for errors
      type: object
      required:
      - errors
      properties:
        Errors:
          $ref: '#/components/schemas/errors'
    BundleDetails:
      type: object
      properties:
        code:
          maxLength: 6
          minLength: 0
          type: string
          description: Unique identifier of a benefit bundle that represents a group of benefit instances available.
          example: PC4657
        effectiveDate:
          type: string
          description: Effective date associated to the benefits in the benefit bundle. Date will be in YYYY-MM-DD format.
          format: date
          example: '2023-08-08'
        expiryDate:
          type: string
          description: Expiry date associated to the benefits in the benefit bundle. Date will be in YYYY-MM-DD format.
          format: date
          example: '2024-07-18'
  responses:
    BenefitAllocationEmptyResponse:
      description: No content.
    BadRequestErrorResponse:
      description: Something was wrong with the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadRequestExample'
    ForbiddenErrorResponse:
      description: Insufficient permissions for interacting with the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            ForbiddenExample:
              $ref: '#/components/examples/ForbiddenExample'
  requestBodies:
    CardReplacementRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CardReplacement'
    FrozenCardRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FrozenCard'

Mastercard Benefit-Allocations-Card-Management API

Operations 2

Documentation

Specifications

Code Examples

Other Resources