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'