Mastercard Searches API

openapi: 3.2.0
info:
  title: Mastercard Searches API
  version: 2.0.0
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
  description: 'Operations tagged Searches across 2 of this provider''s published API definitions: mastercard-atm-locations-openapi.yml, mastercard-merchant-locations-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mastercard.com/locations/atms
  description: Production server
- url: https://sandbox.api.mastercard.com/locations/atms
  description: Sandbox server
- url: https://api.mastercard.com/locations/merchants
  description: Production server
- url: https://sandbox.api.mastercard.com/locations/merchants
  description: Sandbox server
tags:
- name: Searches
paths:
  /searches:
    post:
      tags:
      - Searches
      summary: Mastercard Get a List of Atm Details
      description: Returns detailed information on ATMs based on the provided query parameters
      operationId: getAtms
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/DistanceParam'
      - $ref: '#/components/parameters/DistanceUnitParam'
      requestBody:
        $ref: '#/components/requestBodies/AtmSearch'
      responses:
        '200':
          $ref: '#/components/responses/Atms'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: https://api.mastercard.com/locations/atms
      description: Production server
    - url: https://sandbox.api.mastercard.com/locations/atms
      description: Sandbox server
components:
  responses:
    Atms:
      description: List of ATM details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Atms'
    ForbiddenError:
      description: Insufficient permissions for interacting with the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            Errors:
            - Error:
                Source: locations-atms-api
                ReasonCode: PERMISSION_DENIED
                Description: You don't seem authorized to do that
                Recoverable: false
                Details: Reading ATM information requires read-only permissions
    UnauthorizedError:
      description: Authentication information was missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            Errors:
            - Error:
                Source: locations-atms-api
                ReasonCode: UNAUTHORIZED
                Description: We couldn't recognize you
                Recoverable: false
                Details: Full authentication is required to access this resource
    BadRequestError:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            Errors:
            - Error:
                Source: latitude
                ReasonCode: INVALID_INPUT_VALUE
                Description: Latitude is missing, invalid, or could not be determined from address fields.
                Recoverable: false
                Details: null
    ForbiddenError_2:
      description: Insufficient permissions for interacting with the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            Errors:
            - Error:
                Source: locations-merchants-api
                ReasonCode: PERMISSION_DENIED
                Description: You don't seem authorized to do that
                Recoverable: false
                Details: Reading merchant information requires read-only permissions
    UnauthorizedError_2:
      description: Authentication information was missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            Errors:
            - Error:
                Source: locations-merchants-api
                ReasonCode: UNAUTHORIZED
                Description: We couldn't recognize you
                Recoverable: false
                Details: Full authentication is required to access this resource
    Merchants:
      description: List of Merchant details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Merchants'
  schemas:
    Error:
      description: Details of the error condition such as the source of the error, reason code for the error, if the error is recoverable, and details about the error
      required:
      - Description
      - ReasonCode
      - Recoverable
      - Source
      type: object
      properties:
        Source:
          description: The application that generated this error
          type: string
          minLength: 0
          maxLength: 150
          example: latitude
        ReasonCode:
          description: A unique constant identifying the error case encountered during transaction processing
          type: string
          minLength: 0
          maxLength: 150
          example: INVALID_INPUT_VALUE
        Description:
          description: Short description of the ReasonCode field
          type: string
          minLength: 0
          maxLength: 150
          example: Latitude is missing, invalid, or could not be determined from address fields.
        Recoverable:
          description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
          type: boolean
          example: 'false'
        Details:
          description: Description of the issue
          example: Latitude is missing, invalid, or could not be determined from address fields.
          type:
          - string
          - 'null'
          minLength: 0
          maxLength: 150
    ErrorResponse:
      description: Only returned in the event of an error condition
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    Errors:
      description: Only returned in the event of an error condition
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: An error object
          example:
          - Error:
              Source: latitude
              ReasonCode: INVALID_INPUT_VALUE
              Description: Latitude is missing, invalid, or could not be determined from address fields.
              Recoverable: false
              Details: null
      example:
        Errors:
        - Error:
            Source: latitude
            ReasonCode: INVALID_INPUT_VALUE
            Description: Latitude is missing, invalid, or could not be determined from address fields.
            Recoverable: false
            Details: null
    AtmSearch:
      title: AtmSearch
      description: Atm Search Request Info
      type: object
      properties:
        addressLine1:
          type: string
          description: Line 1 of the street address for the ATM location. Usually includes the street number and name. This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter and either City parameter or PostalCode parameter.
          example: 4033 Veterans Memorial Pkwy
        addressLine2:
          type: string
          description: Line 2 of the street address usually an apartment number or suite number. This parameter is used rarely and is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter and either City parameter or PostalCode parameter.
          example: ''
        city:
          type: string
          description: The name of the city for a ATM location. This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter.
          example: SAINT PETERS
        countryCode:
          type: string
          description: Any three character country code for an ATM location. Valid values are three digit alpha country codes. This parameter is ignored if latitude and longitude are provided. This parameter is required if any other address information is provided including AddressLine1 AddressLine2 City PostalCode or CountrySubdivision.
          example: USA
        countrySubdivisionCode:
          type: string
          description: The state or province for an ATM location (only supported for US and Canada locations). This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter.
          example: MO
        latitude:
          type: string
          description: The latitude of a ATM location. If latitude is provided longitude must also be provided.
          example: '38.794676'
        longitude:
          type: string
          description: The longitude of a ATM location. If longitude is provided latitude must also be provided.
          example: '-90.5689'
        postalCode:
          type: string
          description: The zip code or postal code for an ATM location. This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter.
          example: '63376'
    Atm:
      title: ATM
      description: ATM detail information
      type: object
      properties:
        accessFees:
          type: string
          description: This value indicates under what conditions access fees are charged. Options are UNKNOWN, DOMESTIC, INTERNATIONAL, DOMESTIC_AND_INTERNATIONAL, NO_FEE.
          example: DOMESTIC
        addressLine1:
          type: string
          description: Line 1 of the street address for the ATM location. Usually includes the street number and name.
          example: 1 Oak Street
        addressLine2:
          type: string
          description: Line 2 of the street address usually an apartment number or suite number.
          example: Apt 1
        airportCode:
          type: string
          description: The Airport Code
          example: STL
        atmTerminalId:
          type: string
          description: The ATM Terminal Id
          example: NH044143
        availability:
          type: string
          description: This value indicates the availability hours of the ATM. Options are UNKNOWN, ALWAYS_AVAILABLE, BUSINESS_HOURS, IRREGULAR_HOURS.
          example: BUSINESS_HOURS
        camera:
          type: string
          description: This value indicates whether or not a security camera is present or near ATM
          example: 'NO'
        countryCode:
          type: string
          description: Three digit alpha country code as defined in ISO
          example: USA
        countryName:
          type: string
          description: Name of the country.
          example: United States
        countrySubdivisionCode:
          type: string
          description: Code of the state or province for an ATM location.
          example: MO
        countrySubdivisionName:
          type: string
          description: Name of the state or province for an ATM location.
          example: Missouri
        city:
          type: string
          description: The name of the city for an ATM location.
          example: OFallon
        distance:
          type: number
          description: This is the numerical value for the distance from the provided location to the selected ATM.
          format: double
          example: 1.75723000000001
        distanceUnit:
          type: string
          description: This is the unit of measure value for the distance from the provided location to the selected ATM. Options are KM and MILE.
          example: MILE
        geocodingResult:
          type: string
          description: GeocodingResult for the ATM
          example: G3
        handicapAccessible:
          type: string
          description: This indicates whether the ATM has the ability to read chip cards or not. Options are UNKNOWN, IS_HANDICAP_ACCESSIBLE, NOT_HANDICAP_ACCESSIBLE.
          example: IS_HANDICAP_ACCESSIBLE
        hasSharedDeposit:
          type: string
          description: This value indicates whether or not the ATM participates in the Mastercard Shared Deposit network. Options are YES or NO.
          example: 'YES'
        isSurchargeFreeAlliance:
          type: string
          description: This value indicates whether or not the ATM participates in the Mastercard Shared (only) Surcharge Free Alliance network. Options are YES or NO.
          example: 'YES'
        latitude:
          type: string
          description: The latitude of the ATM
          example: '38.670337'
        locationName:
          type: string
          description: The name of the ATM location
          example: That Bank
        locationType:
          type: string
          description: Type of location for the ATM. Options are OTHER, AIRPORT, HOSPITAL, FINANCIAL_INSTITUTION.
          example: FINANCIAL_INSTITUTION
        longitude:
          type: string
          description: The longitude of the ATM.
          example: '-90.443727'
        owner:
          type: string
          description: This is the DBA name of the financial institution affiliate or independent service organization.
          example: That Bank LLC
        ownerICA:
          type: string
          description: This is the ICA of the entity that owns the ATM
          example: '9386'
        postalCode:
          type: string
          description: The postal code of the ATM location.
          example: '63366'
        routeTransactionNumber:
          type: string
          description: The routing transaction number
          example: '840180546'
        sponsor:
          type: string
          description: This is the legal or business name of the entity that sponsors the owner of the ATM into the Mastercard network.
          example: That Bank LLC
        sponsorICA:
          type: string
          description: This is the ICA of entity that sponsors the owner of the ATM
          example: '9386'
        supportsEmv:
          type: string
          description: This indicates whether the ATM has the ability to read chip cards or not. Options are UNKNOWN, SUPPORTS_EMV, DOES_NOT_SUPPORT_EMV.
          example: SUPPORTS_EMV
        surchargeFreeAllianceNetwork:
          type: string
          description: This value indicates whether or not the ATM participates in the Mastercard Shared (only) Surcharge Free Alliance network. Options are DOES_NOT_PARTICIPATE_IN_SFA, ALLPOINT_PREPAID, MONEYPASS_DEBIT, and ALL_SURCHARGE_FREE.
          example: DOES_NOT_PARTICIPATE_IN_SFA
    Atms:
      title: Atms
      type: object
      properties:
        count:
          type: integer
          format: int32
          description: The number of items in the retrieved data set
          example: 10
        limit:
          type: integer
          format: int32
          description: The number of items requested to be retrieved
          example: 10
        offset:
          type: integer
          format: int32
          description: The page offset used for the query
          example: 1
        total:
          type: integer
          format: int32
          description: The total number of ATMs available to be retrieved
          example: 210
        atms:
          type: array
          description: The list of ATMs retrieved
          items:
            $ref: '#/components/schemas/Atm'
          example: []
    Merchants:
      title: Merchants
      type: object
      properties:
        count:
          type: integer
          format: int32
          description: The number of items in the retrieved data set
          example: 10
        limit:
          type: integer
          format: int32
          description: The number of items requested to be retrieved
          example: 10
        offset:
          type: integer
          format: int32
          description: The page offset used for the query
          example: 1
        total:
          type: integer
          format: int32
          description: The total number of merchants available to be retrieved
          example: 210
        merchants:
          type: array
          description: The list of merchants retrieved
          items:
            $ref: '#/components/schemas/Merchant'
          example: []
    MerchantSearch:
      title: MerchantSearch
      description: Merchant Search Request Info
      type: object
      properties:
        addressLine1:
          type: string
          description: Line 1 of the street address for the merchant location. Usually includes the street number and name. This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter and either City parameter or PostalCode parameter.
          example: 4033 Veterans Memorial Pkwy
        addressLine2:
          type: string
          description: Line 2 of the street address usually an apartment number or suite number. This parameter is used rarely and is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter and either City parameter or PostalCode parameter.
          example: Apt 1
        city:
          type: string
          description: The name of the city for a merchant location. This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter.
          example: SAINT PETERS
        countryCode:
          type: string
          description: Any two digit country code for a Merchant location. Valid values are two digit alpha country code. This parameter is ignored if latitude and longitude are provided. This parameter is required if any other address information is provided including AddressLine1 AddressLine2 City PostalCode or CountrySubdivision.
          example: USA
        countrySubdivisionCode:
          type: string
          description: The state or province for a merchant location (only supported for US and Canada locations). This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter.
          example: MO
        latitude:
          type: string
          description: The latitude of a merchant location. If latitude is provided longitude must also be provided.
          example: '38.795089'
        longitude:
          type: string
          description: The longitude of a merchant location. If longitude is provided latitude must also be provided.
          example: '-90.572346'
        merchantCategory:
          type: string
          description: Category Id of the merchant location. See the Categories resource for a list of valid categories.  Input may be a comma delimited list of category ids.
          example: '0'
        merchantType:
          type: string
          description: Type of merchant location. Options are 'paypass' 'repower' 'easysavings' and 'cashback'.
          example: easysavings
        offerMerchantId:
          type: string
          description: Unique identifier that represents the merchant sponsor of an offer. Any valid merchant ID.
          example: '1143109'
        postalCode:
          type: string
          description: The zip code or postal code for a Merchant location. This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter.
          example: '63376'
    Merchant:
      title: Merchant
      description: Merchant detail information
      type: object
      properties:
        addressLine1:
          type: string
          description: Line 1 of the street address for the merchant location. Usually includes the street number and name.
          example: 1 Oak Street
        addressLine2:
          type: string
          description: Line 2 of the street address usually an apartment number or suite number.
          example: Apt 1
        cashbackMaximumAmount:
          type: string
          description: Maximum cashback amount permitted at the location.
          example: '40'
        category:
          type: string
          description: The Merchant Category
          example: 10 - Grocery Stores & Supermarkets
        countryCode:
          type: string
          description: Two digit alpha country code as defined in ISO
          example: US
        countryName:
          type: string
          description: Name of the country.
          example: United States
        countrySubdivisionCode:
          type: string
          description: Code of the state or province for a merchant location.
          example: MO
        countrySubdivisionName:
          type: string
          description: Name of the state or province for a merchant location.
          example: Missouri
        city:
          type: string
          description: The name of the city for a merchant location.
          example: OFallon
        distance:
          type: number
          description: This is the numerical value for the distance from the provided location to the selected merchant.
          format: double
          example: 1.75723000000001
        distanceUnit:
          type: string
          description: This is the unit of measure value for the distance from the provided location to the selected merchant. Options are KM and MILE.
          example: MILE
        easySavingsMerchantOfferId:
          type: string
          description: Merchant's Easy Savings Offer Id
          example: '1143109'
        geocodingResult:
          type: string
          description: GeocodingResult for the merchant
          example: S8HPNTSCZA
        id:
          type: integer
          description: Numerical merchant identifier.
          format: int32
          example: 1505451132
        isPayPassConcession:
          type: boolean
          description: Boolean value which indicates if the concession area is equipped with a PayPass card reader.
          example: true
        isPayPassPharmacy:
          type: boolean
          description: Boolean value which indicates if the pharmacy is equipped with a PayPass card reader.
          example: true
        isPayPassFuelPump:
          type: boolean
          description: Boolean value which indicates if the fuel pump is equipped with a PayPass card reader.
          example: true
        isPayPassTollBooth:
          type: boolean
          description: Boolean value which indicates if the toll booth is equipped with a PayPass card reader.
          example: true
        isPayPassDriveThrough:
          type: boolean
          description: Boolean value which indicates if the drive thru is equipped with a PayPass card reader.
          example: true
        isPayPassRegister:
          type: boolean
          description: Boolean value which indicates if the register is equipped with a PayPass card reader.
          example: true
        isPayPassTicketing:
          type: boolean
          description: Boolean value which indicates if the ticketing area is equipped with a PayPass card reader.
          example: true
        isPayPassVendingMachine:
          type: boolean
          description: Boolean value which indicates if the vending machine is equipped with a PayPass card reader.
          example: true
        isRepowerByCardSwipeSupported:
          type: boolean
          description: Boolean value which indicates if the repower card load type at this merchant supports Card Swipe.
          example: true
        isRepowerByMoneyPakSupported:
          type: boolean
          description: Boolean value which indicates if the repower card load type at this merchant supports MoneyPak.
          example: true
        latitude:
          type: string
          description: The latitude of the merchant
          example: '38.670337'
        locationName:
          type: string
          description: The name of the merchant
          example: QUIK TRIP STORE 1
        longitude:
          type: string
          description: The longitude of the merchant.
          example: '-90.443727'
        phoneNumber:
          type: string
          description: Merchant's phone number
          example: '8165442210'
        postalCode:
          type: string
          description: The postal code of the Merchant location.
          example: '63366'
        websiteUrl:
          type: string
          description: Merchant's website URL address
          example: www.mcdondalds.com
  parameters:
    LimitParam:
      name: limit
      in: query
      description: The number of items to be retrieved
      required: false
      schema:
        type: integer
      example: 25
    OffsetParam:
      name: offset
      in: query
      description: The page offset used for the query
      required: false
      schema:
        type: integer
      example: 1
    DistanceParam:
      name: distance
      in: query
      description: Distance measurement for calculating the radius search. Optional The length of distance from the centroid point. Value string(<25). The default will be 5 units
      required: false
      schema:
        type: integer
      example: 5
    DistanceUnitParam:
      name: distance_unit
      in: query
      description: Unit of measurement for calculating the radius search. Optional. Measurement of distance unit in miles or kilometers. Value string (MILE or KM)
      required: false
      schema:
        type: string
        enum:
        - MILE
        - KM
      example: MILE
  requestBodies:
    AtmSearch:
      description: A JSON object containing item data
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AtmSearch'
    MerchantSearch:
      description: A JSON object containing item data
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MerchantSearch'
x-refined-from:
- mastercard-atm-locations-openapi.yml
- mastercard-merchant-locations-openapi.yml