Mastercard Acquirer Merchant I Ds API

openapi: 3.2.0
info:
  title: Mastercard Ethoca Merchant Self Services Acquirer  Merchant  I Ds 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: Acquirer  Merchant  I Ds
paths:
  /sub-merchants/{guid}/locations/{location_id}/acquirer-merchant-ids:
    parameters:
    - $ref: '#/components/parameters/UserIdParam'
    - $ref: '#/components/parameters/SubmitterFirstNameParam'
    - $ref: '#/components/parameters/SubmitterLastNameParam'
    - $ref: '#/components/parameters/MerchantGuidParam'
    - $ref: '#/components/parameters/LocationIdParam'
    post:
      summary: Mastercard Add Acquirer Reference Id and Card Acceptor Id Pairs
      description: Returns added pairs of Acquirer Reference ID and Card Acceptor ID. Non unique pairs are placed in the rejected list.
      operationId: addAcquirerMerchantIds
      tags:
      - Acquirer  Merchant  I Ds
      requestBody:
        $ref: '#/components/requestBodies/AcquirerMerchantIdsRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/AcquirerMerchantIdsSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        default:
          $ref: '#/components/responses/Default'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      parameters:
      - $ref: '#/components/parameters/ClarityOffsetParam'
      - $ref: '#/components/parameters/ClarityPageNumberParam'
      - $ref: '#/components/parameters/ClaritySortDirectionParam'
      - $ref: '#/components/parameters/AcquirerMerchantIdsSortFieldParam'
      - $ref: '#/components/parameters/AcquirerMerchantIdsSearchTextParam'
      summary: Mastercard Get Accepted Acquirer Reference Id and Card Acceptor Id Pairs
      description: Returns accepted Acquirer Reference ID and CardAcceptor ID pairs with pagination metadata
      operationId: getAcceptedAcquirerMerchantIds
      tags:
      - Acquirer  Merchant  I Ds
      responses:
        '200':
          $ref: '#/components/responses/PageableAcceptedAcquirerMerchantIdsSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        default:
          $ref: '#/components/responses/Default'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  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: ''
    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: ''
    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: ''
    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: ''
    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: ''
    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
    ClarityResponseHeader:
      allOf:
      - $ref: '#/components/schemas/ResponseHeader'
      - type: object
        properties:
          currentPage:
            type: integer
            description: Current page
            minimum: 0
            maximum: 999999999
            example: 2
    AcquirerMerchantId:
      type: object
      title: Acquirer reference ID & card acceptor ID pair
      description: Acquirer reference ID & card acceptor ID pair
      required:
      - acquirerReferenceId
      - cardAcceptorId
      properties:
        acquirerReferenceId:
          $ref: '#/components/schemas/AcquirerReferenceId'
        cardAcceptorId:
          $ref: '#/components/schemas/CardAcceptorId'
        firstPartyTrustEnabled:
          type: boolean
          description: Marks the ARID/CAID pair as relevant for the FPT engine. When false, the FPT engine won't use the ARID/CAID pair for identifying transactions.
          example: true
          default: false
    AcquirerMerchantIdsResource:
      title: Acquirer reference ID & card acceptor ID pairs resource
      description: Set of acquirer reference ID & card acceptor ID pairs resource
      properties:
        acceptedIds:
          $ref: '#/components/schemas/AcceptedAcquirerMerchantIdsResource'
        rejectedIds:
          description: Rejected acquirer reference ID & card acceptor ID pairs
          type: array
          items:
            $ref: '#/components/schemas/AcquirerMerchantId'
          example: []
    AcquirerMerchantIds:
      title: Acquirer reference ID & card acceptor ID pairs
      maxItems: 100
      minItems: 1
      type: array
      uniqueItems: true
      description: Set of acquirer reference ID & card acceptor ID pairs
      items:
        $ref: '#/components/schemas/AcquirerMerchantId'
    FirstName:
      title: First Name
      maxLength: 30
      minLength: 1
      type:
      - string
      - 'null'
      description: The individual's first name
      example: Michael
    CardAcceptorId:
      title: Card Acceptor's ID (CAID)
      description: Identifies the card acceptor ID assigned by the acquirer. This ID must represent a unique identifier for each merchant name/location within the acquirer BIN. This is represented by Mastercard DE 42 and Visa Field 42.
      type: string
      minLength: 1
      maxLength: 15
      example: card_acceptor1
    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'
    PageableAcceptedAcquirerMerchantIdsResource:
      title: Pageable accepted acquirer reference ID & card acceptor ID pairs resource
      description: Pageable accepted acquirer reference ID & card acceptor ID pairs resource with pagination metadata
      properties:
        data:
          $ref: '#/components/schemas/AcceptedAcquirerMerchantIdsResource'
        metadata:
          $ref: '#/components/schemas/ClarityResponseHeader'
    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
    AcceptedAcquirerMerchantIdsResource:
      description: Accepted acquirer reference ID & card acceptor ID pairs
      type: array
      items:
        $ref: '#/components/schemas/AcquirerMerchantIdResource'
    ResourceId:
      type:
      - string
      - 'null'
      minLength: 1
      maxLength: 40
      description: Unique identifier of resource
      example: Mxyz123
    MerchantGuid:
      title: Merchant GUID
      maxLength: 16
      minLength: 11
      type: string
      description: Consumer Clarity internal merchant's GUID
      example: jK2dA5aybhQQBq6C
    LastName:
      title: Last Name
      maxLength: 30
      minLength: 1
      type:
      - string
      - 'null'
      description: The individual's last name
      example: Fox
    AcquirerMerchantIdResource:
      type: object
      title: Acquirer reference ID & card acceptor ID resource
      description: Acquirer reference ID & card acceptor ID resource
      required:
      - id
      allOf:
      - $ref: '#/components/schemas/AcquirerMerchantId'
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/ResourceId'
    ResponseTime:
      type: string
      description: Total response time in ms
      minLength: 0
      maxLength: 10
      example: 300 ms
    AcquirerMerchant:
      description: Acquirer & Merchant IDs information
      title: AcquirerMerchant
      required:
      - acquirerMerchantIds
      properties:
        acquirerMerchantIds:
          $ref: '#/components/schemas/AcquirerMerchantIds'
    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
  parameters:
    ClarityOffsetParam:
      name: offset
      in: query
      required: false
      description: The number of items to skip before starting to collect the result set
      schema:
        type: integer
        default: 50
        minimum: 0
        example: 0
    AcquirerMerchantIdsSortFieldParam:
      name: sort_field
      in: query
      required: false
      description: Field to Sort data in response
      schema:
        type: string
        default: acquirerReferenceId
        maxLength: 30
      example: acquirerReferenceId
    ClarityPageNumberParam:
      name: page_number
      in: query
      required: false
      description: current page number
      schema:
        type: integer
        default: 0
        minimum: 0
      example: 2
    LocationIdParam:
      name: location_id
      in: path
      required: true
      example: Mxyz123
      description: Unique identifier of location
      schema:
        $ref: '#/components/schemas/ResourceId'
    MerchantGuidParam:
      name: guid
      in: path
      required: true
      description: Consumer Clarity internal merchant's GUID
      example: jK2dA5aybhQQBq6C
      schema:
        $ref: '#/components/schemas/MerchantGuid'
    ClaritySortDirectionParam:
      name: sort_direction
      in: query
      required: false
      description: Direction to sort the data using sort_field in response
      schema:
        type: string
        default: DESC
        enum:
        - ASC
        - DESC
        example: ASC
    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'
    AcquirerMerchantIdsSearchTextParam:
      name: search_text
      in: query
      required: false
      description: 'Input field used as wild search against Acquirer Reference ID and Card Acceptor

        ID. The service searches for substring, following the %search_text% pattern.

        '
      schema:
        type: string
        maxLength: 30
      example: Test
    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'
  responses:
    AcquirerMerchantIdsSuccess:
      description: Acquirer Reference ID and CardAcceptor ID response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AcquirerMerchantIdsResource'
    Default:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ServerError:
              $ref: '#/components/examples/ServerError'
    PageableAcceptedAcquirerMerchantIdsSuccess:
      description: Pageable accepted acquirer reference ID and card acceptor ID response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PageableAcceptedAcquirerMerchantIdsResource'
    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'
    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'
  requestBodies:
    AcquirerMerchantIdsRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AcquirerMerchant'