openapi: 3.0.0 info: version: 1.0.0 title: Segmint Data Services API description: "#### Merchant\nRetrieve transaction details such as: cleansed merchant name, merchant classification, links to download merchant logo (if available) and MCC logo (if available)." servers: - url: https://dataservices-demo.segmint.net/ - url: https://dataservices-stage.segmint.net/ - url: https://dataservices.segmint.net/ paths: "/merchant/v1/partners/{partner_id}/merchant": post: summary: Merchant name scrubbing API (deprecated) deprecated: true description: |- NOTE: This endpoint remains fully functional for existing clients but has been deprecated for future use. Call this API passing transaction details to retrieve cleansed merchant name, merchant classification, merchant logo (if available) and MCC logo (if available). ### For the best results: Debit transactions should be designated with with a transaction type of "debit". Credit transactions should be designated with a transaction type of "credit". This includes both credit card and ACH transactions, such as POS returns, peer-to-peer receipts, payroll deposits, government benefit payments, business receipts, and fund transfers from other institutions. Additionally, point of sale return transactions should include a transaction category of “pos”. ### IMPORTANT NOTE: In order to receive the most accurate and complete results, trans_Category (olb, pos, other) and trans_Type (debit/credit) MUST BE PROVIDED. For trans_category, “pos” is the most critical value to include. This will ensure that the transaction strings will be routed to the optimal matching table. ### Fields marked with an * are required. responses: '200': description: Ok content: "*/*": schema: "$ref": "#/components/schemas/Merchant" '400': description: Bad Request content: "*/*": schema: properties: error: type: array items: type: string example: - Field merchant_description is required. - When using the VISA parser, the merchant_description must be 40 characters. '401': "$ref": "#/components/responses/UnauthorizedError" '404': description: Not found '500': description: Server error security: - BearerAuthentication: [] parameters: - name: partner_id in: path required: true description: The partner ID provided to the financial institution by Segmint schema: type: integer - name: parser in: query schema: type: string enum: - VISA requestBody: content: application/json: schema: type: object required: - merchant_description - mcc properties: ucic: type: string description: Unique customer identification code assigned to the customer by the Financial Institution. Select accounts may be permissioned to NOT require this attribute. example: e2c96790-fd69-11e8-9ff7-bf083b0e566c required: true uaic: type: string description: For account-based KLIs only, a unique account identification code for the account. example: '123456' terminal_id: type: string description: Terminal ID assigned to the merchant POS system by credit card processor. example: 078942319 acquirer_id: type: string description: Acquirer ID assigned to the merchant POS system by credit card processor. example: '9345345232' merchant_id: type: string description: Merchant ID assigned to the merchant POS system by credit card processor. example: '823482982839223332' merchant_description: type: string description: The transaction that is to be cleansed and classified. example: SHELL OIL WHITE BEAR LAMNUS mcc: type: string description: The Merchant Classification Code for the merchant example: '5541' trans_amount: type: number format: currency description: The dollar amount (USD) of the transaction example: '12.55' trans_timestamp: type: string format: date-time description: The timestamp of when the transaction was processed at the merchant POS example: '2018-05-18T15:22:15.000Z' pattern: YYYY-MM-DD HH:MM:SS trans_vehicle: type: string enum: - cc - dc - ach description: The means by which the transaction was initiated. Credit Card (cc), Debit Card (dc), or ACH (ach) trans_category: type: string enum: - olb - pos - other description: Where the transaction took place. Online banking / bill pay (olb), Point of Sale (pos), Other (other) trans_type: type: string enum: - debit - credit description: The type of transaction. Debit (debit) to the account. Credit (credit) to the account. description: The JSON Body of the POST to retrieve a cleansed merchant name required: true tags: - "/merchant" "/v2/partners/{partnerId}/merchants/cleanse-transaction": post: summary: Merchant Payment Cleansing description: |- Call this API and pass transaction details to retrieve a cleansed transaction description, merchant name, merchant logo, detailed merchant category, top-level merchant category, top-level category icon, and MCC code if provided A list of sample transactions can be found [here](/developer-docs/data-cleansing/sample-transactions.txt). These would values would be placed in the `merchantDescription` field. ### For the best results: Debit transactions should be designated with with a transaction type of "debit". Credit transactions should be designated with a transaction type of "credit". This includes both credit card and ACH transactions, such as POS returns, peer-to-peer receipts, payroll deposits, government benefit payments, business receipts, and fund transfers from other institutions. Additionally, point of sale return transactions should include a transaction category of “pos”. ### IMPORTANT NOTE: In order to receive the most accurate and complete results, trans_Category (olb, pos, other) and trans_Type (debit/credit) MUST BE PROVIDED. For trans_category, “pos” is the most critical value to include. This will ensure that the transaction strings will be routed to the optimal matching table. ### Fields marked with an * are required. *Match Types* |Type|Category| |---|---| |DIRECT|An exact merchant brand name and merchant category match was identified.| |SIMILAR|A merchant brand name and merchant category match was identified. Only match scores correlating to high statistical accuracy are included.| |CATEGORY|A merchant category match was identified.| |CLEANSED|A consumer-friendly version of the transaction string is provided. A merchant match was not identified.| |MCC|An MCC categorization and consumer-friendly version of the transaction string is provided. A merchant match was not identified.| #### Example |Type|Category| |---|---| |Merchant|WAREHOUSE CLUBS| security: - BearerAuthentication: [] parameters: - name: partnerId in: path required: true description: The partner ID provided to the financial institution by Segmint schema: type: integer - name: parser in: query description: A known format the transaction is in. _*If the value 'custom' is used the property parserDefinition of the post body is required.*_ schema: type: string enum: - VISA - VISA2 - custom # - name: consumer # in: query # description: |- # #### Example # |Type|Category| # |---|---| # |Merchant|WAREHOUSE CLUBS| # |Consumer|WAREHOUSE CLUB SHOPPER| # schema: # type: boolean requestBody: content: application/json: schema: type: object required: - merchantDescription properties: ucic: type: string nullable: true description: Unique customer identification code assigned to the customer by the Financial Institution. Select accounts may be permissioned to NOT require this attribute. example: e2c96790-fd69-11e8-9ff7-bf083b0e566c required: true uaic: type: string nullable: true description: For account-based KLIs only, a unique account identification code for the account. example: '123456' terminalId: type: string nullable: true description: Terminal ID assigned to the merchant POS system by credit card processor. example: 078942319 acquirerId: type: string nullable: true description: Acquirer ID assigned to the merchant POS system by credit card processor. example: '9345345232' merchantId: type: string nullable: true description: Merchant ID assigned to the merchant POS system by credit card processor. example: '823482982839223332' merchantDescription: type: string description: The transaction string that is to be cleansed and classified. example: SHELL OIL WHITE BEAR LAMNUS mcc: type: string nullable: true description: The Merchant Classification Code for the merchant example: '5541' transAmount: type: number format: currency nullable: true description: The dollar amount (USD) of the transaction example: '12.55' transTimestamp: type: string format: date-time nullable: true description: The timestamp of when the transaction was processed at the merchant POS example: '2018-05-18T15:22:15.000Z' pattern: YYYY-MM-DD HH:MM:SS transVehicle: type: string nullable: true enum: - cc - dc - ach description: The means by which the transaction was initiated. Credit Card (cc), Debit Card (dc), or ACH (ach) transCategory: type: string nullable: true enum: - olb - pos - other description: Where the transaction took place. Online banking / bill pay (olb), Point of Sale (pos), Other (other) transType: type: string nullable: true enum: - debit - credit description: The type of transaction. Debit (debit) to the account. Credit (credit) to the account. parserDefinition: type: object nullable: true properties: maxLength: type: integer example: 36 description: The max length of the merchant description. Use a value of '-1' to skip the length check fields: type: array items: type: object properties: name: type: string enum: - merchant - city - state - country start: type: number example: 0 description: The starting index for this token. Indexes begin with 0 length: type: number example: 5 description: The length of this token. description: The JSON Body of the POST to retrieve a cleansed merchant name required: true responses: '200': description: Ok content: application/json: schema: "$ref": "#/components/schemas/MerchantV2" '400': description: Bad Request content: application/json: schema: properties: error: type: object properties: code: type: string example: INVALID_MERCHANT_DESCRIPTION description: type: string example: When using the 'VISA2' parser, the merchant_description must be 43 characters long. Was 34. '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/Forbidden" '429': "$ref": "#/components/responses/ToManyRequests" '500': description: Server error tags: - "/merchant" servers: - url: https://dataservices-demo.segmint.net/ components: responses: UnauthorizedError: description: Unauthorized BadRequest: description: Bad Request. Check your credentials BadPasswordUpperCase: description: 'Password did not conform with policy: Password must have uppercase characters' BadPasswordLowerCase: description: 'Password did not conform with policy: Password must have lowercase characters' BadPasswordLength: description: New password must have a length greater than 8 BadPasswordSpecial: description: 'Password did not conform with policy: Password must have symbol characters' content: application/json: schema: "$ref": "#/components/schemas/PasswordErrors" ToManyRequests: description: You have exceeded your throughput rate or quota for your account plan. Forbidden: description: You do not have permission to access this resource. securitySchemes: BearerAuthentication: type: http description: Obtain a token using the /auth/v1/token endpoint scheme: bearer bearerFormat: JWT schemas: Merchant: properties: match_type: type: string example: DIRECT match_score: type: number example: 1 match_detail: properties: merchant: properties: classification: type: string example: SHELL logo_url: type: string example: https://cdn.segmint.net/shell.com.png location: properties: city: type: string example: WHITE BEAR LA state: type: string example: MN country: type: string example: US zip: type: string example: '55110' type: object type: object category_1: properties: classification: type: string example: GASOLINE BRANDS type: object category_2: properties: classification: type: string example: GASOLINE PURCHASES type: object mcc: properties: classification: type: string example: SERVICE STATIONS (WITH OR WITHOUT ANCILLARY SERVICES) logo_url: type: string example: https://cdn.segmint.net/421702041306671bk.png type: object type: object merchant_id: type: string example: '4445001651067' trans_id: type: string example: 0b6ffdf0-2619-4b5a-94f3-2abf0230c6cb acquirer_id: type: string example: '444500' network: type: string example: VISA MerchantClassification: properties: {} MerchantV2: properties: matchType: type: string example: SIMILAR matchScore: type: number example: 0.99 network: type: string example: custom transId: type: string example: 0633f250-3616-4e19-95e0-1fa302fbbfe5 transType: type: string example: debit ucic: type: string example: e2c96790-fd69-11e8-9ff7-bf083b0e566c uaic: type: string example: "123456" matchDetail: properties: cleansed: type: string example: SHELL OIL merchant: type: object nullable: true properties: classification: type: string example: SHELL logoUrl: type: string example: "" location: type: object nullable: true properties: city: type: string example: "" state: type: string example: "" zip: type: string example: "" country: type: string example: "" category1: type: object nullable: true properties: classification: type: string example: GASOLINE STATIONS logoUrl: type: string example: "" category2: type: object nullable: true properties: classification: type: string example: TRANSPORTATION & AUTOMOTIVE logoUrl: type: string example: https://merchantlogos.net/vehicle.svg mcc: type: object nullable: true properties: classification: type: string example: SERVICE STATIONS (WITH OR WITHOUT ANCILLARY SERVICES) logoUrl: type: string example: https://merchantlogos.net/fuel.svg merchantId: type: string nullable: true example: '4445001651067' transId: type: string example: 0b6ffdf0-2619-4b5a-94f3-2abf0230c6cb acquirerId: type: string nullable: true example: '444500' network: type: string nullable: true example: VISA TokenResponse: properties: token: type: string description: The token that is used for endpoints that require Bearer Authentication example: eyJraWQiOiJKNHl6dmdGZ3VWbityS2s3Wmt2NnBQTGtMK2hwY20zS09lSlJ5MHNaZnJBPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI3ZjQzZTM3YS0wMzQ3LTRmMTktYmRlMC1hNTgwNGE3YjNkYjQiLCJjdXN0b206cGFydG5lcl9saXN0IjoiODc1NjI2ODgiLCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAudXMtZWFzdC0xLmFtYXpvbmF3cy5jb21cL3VzLWVhc3QtMV9BS2tNT1VBN0YiLCJjb2duaXRvOnVzZXJuYW1lIjoibGFuY2UuY3V0aGJlcnRAc2VnbWludC5jb20iLCJjdXN0b206cm9vdF9wYXJ0bmVyIjoiODc1NjI2ODgiLCJhdWQiOiIzZjUzM2I1czI4OHI0YmNsamNndWN1NHY0ciIsImV2ZW50X2lkIjoiYmJkZTYzNjEtMjBkNC0xMWU5LWJiYTktNGI2MGIzMjg1NDE4IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NDg0NDMzNjcsImN1c3RvbTpwZXJtaXNzaW9uX2xpc3QiOiIsTUVSQ0hBTlQiLCJleHAiOjE1NDg0NDY5NjcsImlhdCI6MTU0ODQ0MzM2NywiZW1haWwiOiJsYW5jZS5jdXRoYmVydEBzZWdtaW50LmNvbSJ9.L9ORpHtxwJ3nBtgMZrQowDotlI0zQy9SZN2uAJj8g_JfJgQ-liK3rTn21IcJdWoS7iPKu-Wq9PT6Zl9jnn71Z7CZ97ipkd9JgLb2W0Brptgm69TRGLr0xWDAsXgqvW8VChT8KHSr3fOCeiz1zDWI2ZBKNj_PDiHRsJn7Xmrkc-joS3TiXtJRyW6TqtoWlf_--GKivzAoJiMkQxlNKYGm5I_NOUYL7x2awJce74jE4b6uqrRG5On1_1X9hKTD2G5L6CYZpz95Xzzeegl-ccuV3lRkzrau-lrc5eHABaFUupm7vMcp3JIbBTCvgJgw8WcuP1JA57TIAW67rfqaMmkWdg expires_in: type: integer description: The time-to-live for the token (in seconds) example: 3600 PasswordErrors: type: object properties: error: type: string description: The error message returned example: 'Password did not conform with policy: Password must have uppercase characters'