Mastercard

Mastercard Alerts Merchants API

The Alerts Merchants API from Mastercard — 1 operation(s) for alerts merchants.

Documentation GitHub OpenAPI

Operations 4

POST /alerts/merchants/{member_id}/acquirer-reference-ids Mastercard Create Acquirer Reference Id Config. #

PUT /alerts/merchants/{member_id}/acquirer-reference-ids Mastercard Update Acquirer Reference Id Config. #

GET /alerts/merchants/{member_id}/acquirer-reference-ids Mastercard Get Acquirer Reference Id Configs. #

DELETE /alerts/merchants/{member_id}/acquirer-reference-ids Mastercard Delete Acquirer Reference Id Config. #

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-alerts-merchants-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 Ethoca Merchant Self Services Alerts  Merchants API
  description: The Ethoca Merchant Self Services API lets you enter your merchant details for your organization, including for all of your submerchants. Using the Merchant Self Services API helps you onboard and integrate your company and all of your submerchants as quickly as possible.
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
  version: 1.6.0
servers:
- url: https://api.ethocaweb.com/ethoca/merchant-self-services
  description: Production server (uses live data)
- url: https://sandbox.api.ethocaweb.com/ethoca/merchant-self-services
  description: Sandbox server (testing environment)
tags:
- name: Alerts  Merchants
paths:
  /alerts/merchants/{member_id}/acquirer-reference-ids:
    post:
      tags:
      - Alerts  Merchants
      summary: Mastercard Create Acquirer Reference Id Config.
      description: Create an acquirer reference id configuration.
      operationId: createAlertsAcquirerReferenceIdConfig
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      - $ref: '#/components/parameters/SubmitterFirstNameParam'
      - $ref: '#/components/parameters/SubmitterLastNameParam'
      - $ref: '#/components/parameters/MemberIdParam'
      requestBody:
        $ref: '#/components/requestBodies/AlertsAcquirerReferenceIdConfigRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/AlertsMerchantIdentifierSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/PermissionDenied'
        '403':
          $ref: '#/components/responses/ForbiddenOperation'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/Default'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Alerts  Merchants
      summary: Mastercard Update Acquirer Reference Id Config.
      description: Update an acquirer reference id configuration.
      operationId: updateAlertsAcquirerReferenceIdConfig
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      - $ref: '#/components/parameters/SubmitterFirstNameParam'
      - $ref: '#/components/parameters/SubmitterLastNameParam'
      - $ref: '#/components/parameters/MemberIdParam'
      - $ref: '#/components/parameters/MerchantIdentifierConfigIdParam'
      requestBody:
        $ref: '#/components/requestBodies/AlertsAcquirerReferenceIdConfigUpdateRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/AlertsMerchantIdentifierSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/PermissionDenied'
        '403':
          $ref: '#/components/responses/ForbiddenOperation'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        default:
          $ref: '#/components/responses/Default'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      tags:
      - Alerts  Merchants
      summary: Mastercard Get Acquirer Reference Id Configs.
      description: Get the acquirer reference id configs filtered by acquirer reference id and card scheme.
      operationId: getAlertsAcquirerReferenceIdConfigs
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      - $ref: '#/components/parameters/SubmitterFirstNameParam'
      - $ref: '#/components/parameters/SubmitterLastNameParam'
      - $ref: '#/components/parameters/MemberIdParam'
      - $ref: '#/components/parameters/AcquirerReferenceIdParam'
      - $ref: '#/components/parameters/CardSchemeParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/PageNumberParam'
      responses:
        '200':
          $ref: '#/components/responses/AlertsPageableAcquirerReferenceIdConfigs'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/PermissionDenied'
        '403':
          $ref: '#/components/responses/ForbiddenOperation'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Default'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      tags:
      - Alerts  Merchants
      summary: Mastercard Delete Acquirer Reference Id Config.
      description: Delete an acquirer reference id configuration.
      operationId: deleteAlertsAcquirerReferenceIdConfig
      parameters:
      - $ref: '#/components/parameters/UserIdParam'
      - $ref: '#/components/parameters/SubmitterFirstNameParam'
      - $ref: '#/components/parameters/SubmitterLastNameParam'
      - $ref: '#/components/parameters/MemberIdParam'
      - $ref: '#/components/parameters/MerchantIdentifierConfigIdParam'
      responses:
        '200':
          $ref: '#/components/responses/SuccessWithoutBody'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/PermissionDenied'
        '403':
          $ref: '#/components/responses/ForbiddenOperation'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Default'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    AcquirerReferenceIdParam:
      name: acquirer_reference_id
      in: query
      required: false
      description: BIN that a partner currently services under their portfolio.
      schema:
        $ref: '#/components/schemas/AcquirerReferenceId'
      example: '123456'
    CardSchemeParam:
      name: card_scheme
      description: Name of card scheme may be one of - MASTERCARD, VISA or any other supported schemes
      in: query
      schema:
        $ref: '#/components/schemas/CardScheme'
      example: MASTERCARD
    MemberIdParam:
      name: member_id
      in: path
      required: true
      description: Merchant member ID (parent of the sub-merchant)
      example: 99ca4b15-72a6-41dd-8127-573d4b07669c
      schema:
        $ref: '#/components/schemas/AlertsMerchantMemberId'
    PageNumberParam:
      name: page_number
      in: query
      required: false
      description: Current page number
      schema:
        type: integer
        default: 1
        minimum: 1
      example: 1
    SubmitterFirstNameParam:
      name: Submitter-First-Name
      in: header
      required: true
      example: Diana
      description: The first name of the submitter/technical contact.
      schema:
        $ref: '#/components/schemas/FirstName'
    UserIdParam:
      name: User-Id
      in: header
      required: true
      example: princess.diana
      description: The user id of the submitter/technical contact.
      schema:
        $ref: '#/components/schemas/UserId'
    SubmitterLastNameParam:
      name: Submitter-Last-Name
      in: header
      required: true
      example: Princess
      description: The last name of the submitter/technical contact.
      schema:
        $ref: '#/components/schemas/LastName'
    MerchantIdentifierConfigIdParam:
      name: merchant_identifier_config_id
      in: query
      required: true
      description: The Configuration ID for acquirer reference ID or card acceptor ID or card acceptor name configurations.
      schema:
        $ref: '#/components/schemas/AlertsMerchantConfigId'
      example: 88ca4b15-72a6-41dd-8127-573d4b07875c
    OffsetParam:
      name: offset
      in: query
      required: false
      description: Number of items per page
      schema:
        type: integer
        default: 25
        maximum: 25
      example: 25
  examples:
    AlertsInvalidData:
      summary: Invalid Data Field Error Response For Alerts
      description: If a field or set of fields fails a validation (eg. NotNull, Length, Pattern etc.), then InvalidData response will be returned to the caller for each invalid field with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: name'
            Description: size must be between 3 and 200
            Recoverable: false
            Details: ''
    AlertsAcquirerReferenceIdConfigUpdate:
      summary: Alerts Acquirer Reference Id Configuration for Update
      value:
        binOnlyMatch: true
    InvalidParameterSet:
      summary: Invalid Parameter Set Error Response
      description: If request body is malformed or missing, then InvalidParameterSet error response is returned to the caller with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: invalid.parameter.set
            Description: request body is malformed
            Recoverable: false
            Details: ''
    AlertsAcquirerReferenceIdConfig:
      summary: Alerts Acquirer Reference Id Configuration
      value:
        cardScheme: MASTERCARD
        acquirerReferenceId: '123456'
        binOnlyMatch: true
    AlertsMerchantIdentifierConfigIdOnly:
      summary: Alerts Merchant Identifier Configuration ID
      value:
        merchantIdentifierConfigId: 88ca4b15-72a6-41dd-8127-573d4b07875c
    AlertsEntityNotFound:
      summary: Entity Not Found Error Response For Alerts
      description: If a requested entity(e.g. Sub-Merchant or Card Acceptor ID or Card Acceptor Name) doesn't exist in the system, then EntityNotFound error response is returned to the caller with HTTP Status code 404.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: subMerchantId'
            Description: Sub-Merchant 99ca4b15-72a6-41dd-8127-573d4b07669c not found
            Recoverable: false
            Details: ''
    EntityNotFound:
      summary: Entity Not Found Error Response For Consumer Clarity
      description: If a requested entity(e.g. Merchant or Logo) doesn't exist in the system, then EntityNotFound error response is returned to the caller with HTTP Status code 404.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: GUID'
            Description: Merchant 1E37M8VSX1D28QYX not found
            Recoverable: false
            Details: ''
    FormatInvalid:
      summary: Format Invalid Error Response For Consumer Clarity
      description: If a field is not correctly formatted (e.g. a String value is sent in an Integer type field), then FormatInvalid response is returned to the caller with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: format.invalid
            Description: orderHistoryMonths
            Recoverable: false
            Details: ''
    ValidationFailed:
      summary: Validation of the request failed
      description: If the fields in the request did not pass the validation, a ValidationFailed error response is returned to the caller with HTTP Status code 422.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: validation.failed
            Description: Validation of the request fields failed
            Recoverable: false
            Details: ''
    AlertsFormatInvalid:
      summary: Format Invalid Error Response For Alerts
      description: If a field is not correctly formatted (e.g. a String value is sent in an Integer type field), then FormatInvalid response is returned to the caller with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: merchantCategoryCode'
            Description: must match \"^[0-9]*$\"
            Recoverable: false
            Details: ''
    MissingRequiredHeader:
      summary: Missing Required Header Error Response
      description: If a required request header is missing or null, then MissingRequiredHeader error response is returned to the caller with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: missing required header
            Description: Submitter-First-Name
            Recoverable: false
            Details: ''
    ForbiddenOperation:
      summary: Member does not have permission to add/update/delete a resource
      description: If the merchant tries operate on a resource that is not related to them or if they are not allowed perform a specific operation on their resource, then ForbiddenOperation error response is returned to the caller with HTTP Status code 403.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: operation.not.allowed
            Description: Member is not allowed to perform a specific operation on a particular resource
            Recoverable: false
            Details: ''
    ResourceNotFound:
      summary: Resource Not Found Error Response
      description: If request URI doesn't match with any available endpoints, then ResourceNotFound error response is returned the caller with HTTP Status code 404.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: resource.not.found
            Description: Not Found
            Recoverable: false
            Details: /merchant-self-services/sub-merchantTs/
    InvalidData:
      summary: Invalid Data Error Response For Consumer Clarity
      description: If a field or set of fields fails a validation (eg. NotNull, Length, Pattern etc.), then InvalidData response will be returned to the caller for each invalid field with HTTP Status code 400.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: 'invalid data: merchantType'
            Description: must not be blank
            Recoverable: false
            Details: ''
    PermissionDenied:
      summary: Permission Denied Error Response
      description: If the client id in the request doesn't correspond to any member in the system, then PermissionDenied error response is returned to the caller with HTTP Status code 401.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: permission.denied
            Description: Member does not have permission to perform any operation
            Recoverable: false
            Details: ''
    ServerError:
      summary: Server Error Response
      description: If an unexpected internal server error occurs, then ServerError response is returned to the caller with HTTP Status code 500.
      value:
        Errors:
          Error:
          - Source: service
            ReasonCode: server.error
            Description: Internal Server Error
            Recoverable: false
            Details: ''
  schemas:
    ErrorResponse:
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
      description: Error Response object
    CardScheme:
      description: Name of card scheme may be one of - MASTERCARD, VISA or any other supported schemes
      type: string
      minLength: 1
      maxLength: 20
      example: MASTERCARD
    FirstName:
      title: First Name
      maxLength: 30
      minLength: 1
      type:
      - string
      - 'null'
      description: The individual's first name
      example: Michael
    AlertsAcquirerReferenceIdConfig:
      description: Acquirer reference id configuration
      type: object
      properties:
        merchantIdentifierConfigId:
          $ref: '#/components/schemas/AlertsMerchantConfigId'
        acquirerReferenceId:
          $ref: '#/components/schemas/AcquirerReferenceId'
        cardScheme:
          $ref: '#/components/schemas/CardScheme'
        binOnlyMatch:
          $ref: '#/components/schemas/BinOnlyMatch'
      required:
      - acquirerReferenceId
      - cardScheme
    ResponseHeader:
      type: object
      properties:
        totalRecords:
          type: integer
          format: int64
          description: Total number of records found
          minimum: 0
          maximum: 999999999
          example: 500
        totalPages:
          type: integer
          description: Total number of pages based on limit
          minimum: 0
          maximum: 999999999
          example: 10
        currentPage:
          type: integer
          description: The current page number
          minimum: 1
          maximum: 999999999
          example: 2
        responseTime:
          $ref: '#/components/schemas/ResponseTime'
    Error:
      type: object
      properties:
        Source:
          maxLength: 100
          minLength: 0
          type:
          - string
          - 'null'
          description: Source of the error
          example: Service
        ReasonCode:
          maxLength: 100
          minLength: 0
          type:
          - string
          - 'null'
          description: A unique constant identifying the error
          example: format.invalid
        Description:
          maxLength: 1000
          minLength: 0
          type:
          - string
          - 'null'
          description: Short description of the error
          example: Short description of the error
        Recoverable:
          type:
          - boolean
          - 'null'
          description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
          example: false
          default: false
        Details:
          maxLength: 1000
          minLength: 0
          type:
          - string
          - 'null'
          description: Optional detailed description of the issue
          example: Detailed description of the error
      description: Error object
    Errors:
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          description: List of error objects
          items:
            $ref: '#/components/schemas/Error'
          example: []
      description: Errors object
    AlertsAcquirerReferenceIdConfigUpdate:
      description: Acquirer reference id configuration for update
      type: object
      properties:
        binOnlyMatch:
          $ref: '#/components/schemas/BinOnlyMatch'
      required:
      - binOnlyMatch
    AlertsMerchantIdentifierConfigIdOnly:
      description: Merchant identifier configuration Id (referring to card acceptor id or name configuration)
      type: object
      properties:
        merchantIdentifierConfigId:
          $ref: '#/components/schemas/AlertsMerchantConfigId'
    AlertsPageableAcquirerReferenceIdConfigs:
      description: Pageable response containing acquirer reference id configurations
      type: object
      properties:
        responseHeader:
          $ref: '#/components/schemas/ResponseHeader'
        configs:
          $ref: '#/components/schemas/AlertsAcquirerReferenceIdConfigs'
    AlertsMerchantMemberId:
      title: Unique identifier for merchants
      description: Internal Universally Unique Identifier (UUID) which uniquely identifies the merchants
      type: string
      format: uuid
      example: 99ca4b15-72a6-41dd-8127-573d4b07669c
    AlertsAcquirerReferenceIdConfigs:
      description: Acquirer reference id configurations
      type: array
      items:
        $ref: '#/components/schemas/AlertsAcquirerReferenceIdConfig'
    LastName:
      title: Last Name
      maxLength: 30
      minLength: 1
      type:
      - string
      - 'null'
      description: The individual's last name
      example: Fox
    ResponseTime:
      type: string
      description: Total response time in ms
      minLength: 0
      maxLength: 10
      example: 300 ms
    AlertsMerchantConfigId:
      title: Unique identifier for merchants identifier (such as acquirer reference id, card acceptor id or name) configuration
      description: Internal Universally Unique Identifier (UUID) which uniquely identifies the merchants configuration
      type: string
      format: uuid
      example: 88ca4b15-72a6-41dd-8127-573d4b07558c
    AcquirerReferenceId:
      title: Acquirer Reference ID (ARID)
      description: The acquirer BINs that a partner currently services under their portfolio. This is represented by Mastercard DE 31 - Subfield 2 (Clearing), DE 32 (Authorization), or Visa Field 32.
      type: string
      minLength: 6
      maxLength: 6
      pattern: ^[\d]+$
      example: '123456'
    UserId:
      title: User Id
      maxLength: 300
      minLength: 1
      type: string
      description: The user id of the submitter/technical contact.
      example: princess.diana
    BinOnlyMatch:
      description: Indicates whether to use only acquirer reference ID (Acquirer BIN) for merchant matching
      type: boolean
      default: false
      example: true
  responses:
    PermissionDenied:
      description: Permission Denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            PermissionDenied:
              $ref: '#/components/examples/PermissionDenied'
    Default:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ServerError:
              $ref: '#/components/examples/ServerError'
    AlertsPageableAcquirerReferenceIdConfigs:
      description: Pageable list of acquirer reference id configurations
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlertsPageableAcquirerReferenceIdConfigs'
    SuccessWithoutBody:
      description: Successful Operation
    AlertsMerchantIdentifierSuccess:
      description: Sub-merchant identifiers for either card acceptor id or card acceptor name configuration
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlertsMerchantIdentifierConfigIdOnly'
          examples:
            AlertsMerchantIdentifierConfigIdOnly:
              $ref: '#/components/examples/AlertsMerchantIdentifierConfigIdOnly'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ResourceNotFound:
              $ref: '#/components/examples/ResourceNotFound'
            EntityNotFound:
              $ref: '#/components/examples/EntityNotFound'
            AlertsEntityNotFound:
              $ref: '#/components/examples/AlertsEntityNotFound'
    ValidationFailed:
      description: Validation Failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ValidationFailed:
              $ref: '#/components/examples/ValidationFailed'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            InvalidData:
              $ref: '#/components/examples/InvalidData'
            AlertsInvalidData:
              $ref: '#/components/examples/AlertsInvalidData'
            InvalidParameterSet:
              $ref: '#/components/examples/InvalidParameterSet'
            FormatInvalid:
              $ref: '#/components/examples/FormatInvalid'
            AlertsFormatInvalid:
              $ref: '#/components/examples/AlertsFormatInvalid'
            MissingRequiredHeader:
              $ref: '#/components/examples/MissingRequiredHeader'
    ForbiddenOperation:
      description: Forbidden Operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ForbiddenOperation:
              $ref: '#/components/examples/ForbiddenOperation'
  requestBodies:
    AlertsAcquirerReferenceIdConfigUpdateRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlertsAcquirerReferenceIdConfigUpdate'
          examples:
            AlertsAcquirerReferenceIdConfigUpdate:
              $ref: '#/components/examples/AlertsAcquirerReferenceIdConfigUpdate'
    AlertsAcquirerReferenceIdConfigRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlertsAcquirerReferenceIdConfig'
          examples:
            AlertsAcquirerReferenceIdConfig:
              $ref: '#/components/examples/AlertsAcquirerReferenceIdConfig'

Mastercard Alerts Merchants API

Operations 4

Documentation

Specifications

Code Examples

Other Resources