openapi: 3.2.0
info:
  contact:
    name: MX Platform API
    url: https://www.mx.com/products/platform-api
  description: 'The MX Platform API is a powerful, fully-featured API designed to make aggregating and enhancing financial data easy and reliable. It can seamlessly connect your app or website to tens of thousands of financial institutions.


    ## What''s Changed?


    Several endpoints, headers, and fields changed in `v20250224`. For more on breaking changes, refer to our [versioning](/api-reference/platform-api/overview/versioning#v20250224) and [migration](/api-reference/platform-api/overview/migration) guides.


    ## Version Header

    Versions are set in the `Accept-Version` header of API requests. Version numbers correspond with the date associated with that version.  The example below uses the version `v20250224`.


    ```

    -H ''Accept: application/json''

    -H ''Accept-Version: v20250224''

    ```


    ---

    '
  title: MX Platform Merchants API
  version: '20250224'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: merchants
  description: 'Merchants are representations of a transaction’s origin. For example, if you buy a coffee at Starbucks, the transaction merchant will be `Starbucks`.


    Use the `merchant_guid` and a `merchant_location_guidon` any `transaction` object to access Merchant endpoints for details like the merchant’s name, logo URL, website, street address, and more.

    '
paths:
  /merchant_locations/{merchant_location_guid}:
    get:
      description: This endpoint returns the specified `merchant_location` resource. The `merchant_location_guid` can be found on `transaction` objects.
      operationId: readMerchantLocation
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/merchantLocationGuid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantLocationResponseBody'
          description: OK
      summary: Read merchant location
      tags:
      - merchants
  /merchants:
    get:
      description: This endpoint returns a paginated list of all the merchants in the MX system.
      operationId: listMerchants
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/merchantName'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantsResponseBody'
          description: OK
      summary: List merchants
      tags:
      - merchants
  /merchants/{merchant_guid}:
    get:
      description: Returns information about a particular merchant, such as a logo, name, and website.
      operationId: readMerchant
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/merchantGuid'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantResponseBody'
          description: OK
      summary: Read merchant
      tags:
      - merchants
components:
  parameters:
    merchantGuid:
      description: The unique id for a `merchant`.
      example: MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b
      in: path
      name: merchant_guid
      required: true
      schema:
        type: string
    page:
      description: Results are paginated. Specify current page.
      example: 1
      in: query
      name: page
      schema:
        type: integer
    acceptVersion:
      name: Accept-Version
      in: header
      required: true
      schema:
        type: string
        default: v20250224
        example: v20250224
      description: MX Platform API version.
    recordsPerPageMax1000:
      description: This specifies the number of records to be returned on each page. Defaults to `25`. The valid range is from `10` to `1000`. If the value exceeds `1000`, the default value of `25` will be used instead.
      example: 10
      in: query
      name: records_per_page
      schema:
        type: integer
    merchantLocationGuid:
      description: The unique id for a `merchant_location`.
      example: MCH-09466f0a-fb58-9d1a-bae2-2af0afbea621
      in: path
      name: merchant_location_guid
      required: true
      schema:
        type: string
    merchantName:
      description: This will list only merchants in which the appended string appears.
      example: Comcast
      in: query
      name: name
      schema:
        type: string
  schemas:
    PaginationResponse:
      properties:
        current_page:
          description: The page delivered by the current response.
          example: 1
          type: integer
        per_page:
          description: The number of records delivered with each page.
          example: 25
          type: integer
        total_entries:
          description: The total number of records available.
          example: 1
          type: integer
        total_pages:
          description: The total number of pages available.
          example: 1
          type: integer
      type: object
    MerchantLocationResponse:
      properties:
        city:
          description: The city name.
          example: North Kishaberg
          type:
          - string
          - 'null'
        country:
          description: The country name.
          example: US
          type:
          - string
          - 'null'
        created_at:
          description: The date and time the merchant was created, represented in ISO 8601 format with a timestamp.
          example: '2025-02-13T18:08:00+00:00'
          type:
          - string
          - 'null'
        guid:
          description: The unique identifier for the merchant location. Defined by MX.
          example: MCL-00024e59-18b5-4d79-b879-2a7896726fea
          type:
          - string
          - 'null'
        latitude:
          description: The latitude of the location where the transaction occurred. The number is a signed decimal (for example, Rio de Janeiro's latitude is -22.9027800 and Tokyo's latitude is 35.689488).
          example: 39.5963005
          type:
          - number
          - 'null'
        longitude:
          description: The longitude of the location where the transaction occurred. The number is a signed decimal (for example, Rio de Janeiro's longitude is -43.2075000 and Tokyo's longitude is 139.691706).
          example: -104.89158799999998
          type:
          - number
          - 'null'
        merchant_guid:
          description: The unique identifier for the merchant. Defined by MX.
          example: MCH-09466f0a-fb58-9d1a-bae2-2af0afbea621
          type:
          - string
          - 'null'
        phone_number:
          description: The phone number of the merchant location.
          example: (303) 689-0728
          type:
          - string
          - 'null'
        postal_code:
          description: The postal code of the merchant location.
          example: '801121436'
          type:
          - string
          - 'null'
        state:
          description: The state abbreviation of the merchant location.
          example: CO
          type:
          - string
          - 'null'
        street_address:
          description: The street address of the merchant location.
          example: 8547 E Arapahoe Rd, Ste 1
          type:
          - string
          - 'null'
        updated_at:
          description: 'The date and time the resource was last updated in ISO 8601 format with a timestamp.


            For categories, this field will always be `null` when `is_default` is `true`.

            '
          example: '2025-02-13T18:09:00+00:00'
          type:
          - string
          - 'null'
      type: object
    MerchantResponseBody:
      properties:
        merchant:
          $ref: '#/components/schemas/MerchantResponse'
      type: object
    MerchantResponse:
      properties:
        created_at:
          description: The date and time the merchant was created, represented in ISO 8601 format with a timestamp.
          example: '2025-02-13T18:08:00+00:00'
          type:
          - string
          - 'null'
        guid:
          description: The unique identifier for the merchant. Defined by MX.
          example: MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b
          type:
          - string
          - 'null'
        logo_url:
          description: The URL for a 100px X 100px logo for the merchant.
          example: https://s3.amazonaws.com/MD_Assets/merchant_logos/comcast.png
          type:
          - string
          - 'null'
        name:
          description: The name of the merchant.
          example: Comcast
          type:
          - string
          - 'null'
        updated_at:
          description: 'The date and time the resource was last updated in ISO 8601 format with a timestamp.


            For categories, this field will always be `null` when `is_default` is `true`.

            '
          example: '2025-02-13T18:09:00+00:00'
          type:
          - string
          - 'null'
        website_url:
          description: URL to the merchant's website.
          example: https://www.example.com
          type:
          - string
          - 'null'
      type: object
    MerchantLocationResponseBody:
      properties:
        merchant_location:
          $ref: '#/components/schemas/MerchantLocationResponse'
      type: object
    MerchantsResponseBody:
      properties:
        merchants:
          items:
            $ref: '#/components/schemas/MerchantResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
  securitySchemes:
    basicAuth:
      scheme: basic
      type: http
      description: 'The MX Platform API requires basic access authentication using your `client_id` and `api_key`. These credentials must be Base64 encoded and included in the Authorization header of each API request to ensure secure access.


        Here''s an example using curl to access `v20250224`. Replace `https://int-api.mx.com/endpoint` with the actual API endpoint you wish to access and your Base64 encoded `client_id` and `api_key`.


        ```

        curl -L -X POST `https://int-api.mx.com/endpoint'' \

        -H ''Content-Type: application/json'' \

        -H ''Accept: application/json'' \

        -H ''Accept-Version: v20250224''

        -H ''Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}''

        ```

        '
    bearerAuth:
      type: http
      scheme: bearer