MiDiGATOR® REPORTING API API Reference
Midigator is a chargeback and fraud technology platform that mitigates risk and recovers lost revenue.
The Midigator API can be called from any language, including .NET, Java, PHP, and Python, and it can be deployed on multiple platforms, such as Windows, Mac OS, or Linux.
To get started, contact integrations@midigator.com for API credentials and IP address whitelisting.
API Endpoint
https://reporting.midigator.com
https://reporting-api.stage01.midigator.net
Contact: integrations@midigator.com
Schemes: https
Version: 1.1.0
Paths
POST /chargebacks
Endpoint for requesting chargeback data
Request for chargeback data
Only application/JSON content type is allowed for this resource
Contact an account manager to obtain a bearer authorization key. The header must be structured to include the key:value {Authorization:Bearer xxxx}
Request Example
{
"start_date": "2017-01-01 12:30:01",
"end_date": "2017-02-01 23:30:01",
"company_token": "65183424Vnt4bY2fdVGy",
"mids": [
"987654321987"
],
"output_format": "JSON"
}
200 response
If no data can be found for valid parameters, the response will be an empty 200
400 response
401 response
412 response
422 response
500 response
504 response
Response Example (200 OK)
[
{
"case_number": "201765489123",
"status": "Pending",
"arn": "52236076286816009657108",
"mid": "987654321987",
"card_number": "555555******4444",
"card_type": "mastercard",
"amount": 94.76,
"currency": "USD",
"reason_code": "4837",
"reason": "No Cardholder Authorization",
"date_received": "2017-06-20 22:35:15",
"transaction_date": "2017-06-05 12:25:05",
"order_id": "8106",
"name": "John Doe",
"tracking_number": "9400111893275114002199"
}
]
POST /prevention
Endpoint for requesting prevention alert data
Request for prevention alert data
Only application/JSON content type is allowed for this resource
Contact an account manager to obtain a bearer authorization key. The header must be structured to include the key:value {Authorization:Bearer xxxx}
Request Example
{
"start_date": "2017-01-01 12:30:01",
"end_date": "2017-02-01 23:30:01",
"company_token": "65183424Vnt4bY2fdVGy",
"mids": [
"987654321987"
],
"output_format": "JSON"
}
200 response
If no data can be found for valid parameters, the response will be an empty 200
400 response
401 response
412 response
422 response
500 response
504 response
Response Example (200 OK)
[
{
"arn": "52236076286816009657108",
"alert_case_id": "50TB2Z4GK1NB77XE8QY9RKPVC",
"statuses": [
"New",
"Pending",
"Complete"
],
"mid": "987654321987",
"merchant_descriptor": "ACME Digital UK MID",
"source_partner": "Ethoca",
"bin": "555555",
"last_four": "4444",
"amount": 94.76,
"currency": "USD",
"date_received": "2017-06-28 09:20:11",
"transaction_date": "2017-06-25 19:30:31",
"order_id": "1106",
"name": "John Doe"
}
]
POST /mid_report
Endpoint for requesting MID data
Request for MID data
Only application/JSON content type is allowed for this resource
Contact an account manager to obtain a bearer authorization key. The header must be structured to include the key:value {Authorization:Bearer xxxx}
Request Example
{
"start_date": "2017-01-01 12:30:01",
"end_date": "2017-02-01 23:30:01",
"company_token": "65183424Vnt4bY2fdVGy",
"mids": [
"987654321987"
],
"output_format": "JSON"
}
200 response
If no data can be found for valid parameters, the response will be an empty 200
400 response
401 response
412 response
422 response
500 response
504 response
Response Example (200 OK)
[
{
"mid": "987654321987",
"alias": "ACME Digital UK MID",
"gateways": [
"64",
"213"
],
"chargeback_amount_ratio": 0.85,
"chargeback_amount": 801.94,
"chargeback_count": 20,
"chargeback_ratio": 0.86,
"transaction_amount": 94093.05,
"transaction_count": 2328,
"visa": {
"chargeback_amount_ratio": 0.68,
"chargeback_amount": 385.6,
"chargeback_count": 10,
"chargeback_ratio": 0.72,
"transaction_amount": 57021.69,
"transaction_count": 1396
},
"master_card": {
"chargeback_amount_ratio": 0.73,
"chargeback_amount": 274.4,
"chargeback_count": 7,
"chargeback_ratio": 0.78,
"transaction_amount": 26975.75,
"transaction_count": 675,
"previous_month_transaction_amount": 37372.45,
"previous_month_transaction_count": 897
},
"discover": {
"chargeback_amount_ratio": 1.3,
"chargeback_amount": 106.38,
"chargeback_count": 2,
"chargeback_ratio": 0.99,
"transaction_amount": 8167.61,
"transaction_count": 202
},
"amex": {
"chargeback_amount_ratio": 1.84,
"chargeback_amount": 35.56,
"chargeback_count": 1,
"chargeback_ratio": 1.81,
"transaction_amount": 1928,
"transaction_count": 55
}
}
]
Schema Definitions
Chargeback Request: object
Request for chargeback data
- start_date: string
-
The start date of the report in UTC ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
- end_date: string
-
The end date of the report in UTC ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
- company_token: string
-
Unique Midigator company token (contact an account manager for the company token)
- mids: array
-
Merchant account ID used to filter requests; if this parameter is not included, chargeback data for all MIDs will be returned
- output_format: string , x ∈ { JSON , CSV }
-
JSON or CSV response format; if left empty, defaults to JSON
Example
{
"start_date": "2017-01-01 12:30:01",
"end_date": "2017-02-01 23:30:01",
"company_token": "65183424Vnt4bY2fdVGy",
"mids": [
"987654321987"
],
"output_format": "JSON"
}
Chargeback Response: object[]
Report of requested chargeback data
- case_number: string
-
Chargeback case number assigned by bank or processor
- status: string , x ∈ { Lost , New , Pending , Won , Did Not Fight , Pre-Arbitration , Result Unobtainable }
-
Current status of the chargeback
- arn: string
-
Reference number assigned by acquiring bank (omitted if not applicable)
- mid: string
-
Merchant account ID associated with the chargeback
- card_number: string
-
Card number used to process the original transaction
- card_type: string
-
Card network that issued the card (Visa, Mastercard, etc.)
- amount: number (float)
-
Dollar amount of the chargeback
- currency: string
-
Currency of the chargeback
- reason_code: string
-
Chargeback reason code
- reason: string
-
Chargeback reason code description
- date_received: string (date-time)
-
Date and time the chargeback was received by the acquiring bank or processor; if time is not recorded, only the date will be reported
- transaction_date: string (date-time)
-
Date and time the original transaction was processed; if time is not recorded, only the date will be reported
- order_id: string
-
CRM or order management system’s identifier for the order; if the chargeback hasn’t been matched to the order yet, this field will be empty
- name: string
-
Customer’s name as it appears on the original order; if the chargeback hasn’t been matched to the order yet, this field will be empty
- tracking_number: string
-
Tracking number for shipment of physical goods; if digital goods or services were purchased, this field will be empty; if the chargeback hasn’t been matched to the order yet, this field will be empty
Example
[
{
"case_number": "201765489123",
"status": "Pending",
"arn": "52236076286816009657108",
"mid": "987654321987",
"card_number": "555555******4444",
"card_type": "mastercard",
"amount": 94.76,
"currency": "USD",
"reason_code": "4837",
"reason": "No Cardholder Authorization",
"date_received": "2017-06-20 22:35:15",
"transaction_date": "2017-06-05 12:25:05",
"order_id": "8106",
"name": "John Doe",
"tracking_number": "9400111893275114002199"
}
]
Prevention Request: object
Request for prevention alert data
- start_date: string
-
The start date of the report in UTC ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
- end_date: string
-
The end date of the report in UTC ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
- company_token: string
-
Unique Midigator company token (contact an account manager for the company token)
- mids: array
-
Merchant account ID used to filter requests; if this parameter is not included, prevention alert data for all MIDs will be returned
- output_format: string , x ∈ { JSON , CSV }
-
JSON or CSV response format; if left empty, defaults to JSON
Example
{
"start_date": "2017-01-01 12:30:01",
"end_date": "2017-02-01 23:30:01",
"company_token": "65183424Vnt4bY2fdVGy",
"mids": [
"987654321987"
],
"output_format": "JSON"
}
Prevention Response: object[]
Report of requested prevention alert data
- arn: string
-
Acquirer's Reference Number (omitted if not applicable)
- alert_case_id: string
-
Case ID assigned by the prevention alert source
- statuses: array , x ∈ { New , Pending , Complete }
-
Current status of the prevention alert
- mid: string
-
Merchant account ID associated with the prevention alert; if the prevention alert hasn’t been matched to the order yet, this field will be empty
- merchant_descriptor: string
-
Billing descriptor that appeared on the cardholder’s statement and resulted in a prevention alert
- source_partner: string , x ∈ { Ethoca , Verifi }
-
Applicable prevention alert source
- bin: string
-
First six digits of the card number associated with the original transaction; identifies the bank that issued the prevention alert
- last_four: string
-
Last four digits of the card number associated with the prevention alert
- amount: number (float)
-
Dollar amount of the prevention alert
- currency: string
-
Currency of the prevention alert
- date_received: string (date-time)
-
Date and time the alert was received by the prevention alert source; if time is not recorded, only the date will be reported
- transaction_date: string (date-time)
-
Date and time the original transaction was processed; if time is not recorded, only the date will be reported
- order_id: string
-
CRM or order management system’s identifier for the order; if the prevention alert hasn’t been matched to the order yet, this field will be empty
- name: string
-
Customer’s name as it appears on the original order; if the prevention alert hasn’t been matched to the order yet, this field will be empty
Example
[
{
"arn": "52236076286816009657108",
"alert_case_id": "50TB2Z4GK1NB77XE8QY9RKPVC",
"statuses": [
"New",
"Pending",
"Complete"
],
"mid": "987654321987",
"merchant_descriptor": "ACME Digital UK MID",
"source_partner": "Ethoca",
"bin": "555555",
"last_four": "4444",
"amount": 94.76,
"currency": "USD",
"date_received": "2017-06-28 09:20:11",
"transaction_date": "2017-06-25 19:30:31",
"order_id": "1106",
"name": "John Doe"
}
]
MID Report Request: object
Request for MID data
- start_date: string
-
The start date of the report in UTC ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
- end_date: string
-
The end date of the report in UTC ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
- company_token: string
-
Unique Midigator company token (contact an account manager for the company token)
- mids: array
-
Merchant account ID used to filter requests; if the parameter is not included, data for all MIDs will be returned
- output_format: string , x ∈ { JSON , CSV }
-
JSON or CSV response format; if left empty, defaults to JSON
Example
{
"start_date": "2017-01-01 12:30:01",
"end_date": "2017-02-01 23:30:01",
"company_token": "65183424Vnt4bY2fdVGy",
"mids": [
"987654321987"
],
"output_format": "JSON"
}
MID Report Response: object[]
Report of requested MID data
- mid: string
-
Merchant account ID
- alias: string
-
Alias name assigned to the specified merchant account
- gateways: array
-
ID listed on the transaction which correlates back to the merchant account (sometimes called gateway ID, CRM MID ID)
- chargeback_amount_ratio: number (float)
-
Ratio of the dollar amount of all chargebacks to the dollar amount of all transactions for the specified MID during a given date range
- chargeback_amount: number (float)
-
Total dollar amount of all chargebacks for the specified MID during a given date range
- chargeback_count: integer
-
Total number of chargebacks received on the specified MID during a given date range
- chargeback_ratio: number (float)
-
Ratio of the number of all chargebacks to the number of all transactions for the specified MID during a given date range
- transaction_amount: number (float)
-
Total dollar amount of all transactions for the specified MID during a given date range
- transaction_count: integer
-
Total number of transactions processed for the specified MID during a given date range
- visa: Visa MID Report
-
Chargeback data for all Visa transactions on the specified MID during a given date range
- master_card: Mastercard MID Report
-
Mastercard calculates the chargeback ratio differently than other card networks. Mastercard divides the current month’s chargeback count by the previous month’s transaction count.Chargeback data for all Mastercard transactions on the specified MID during a given date range
For Example:
500 (July chargebacks) / 45,000 (June transactions) = 1.11% - discover: Discover MID Report
-
Chargeback data for all Discover transactions on the specified MID during a given date range
- amex: Amex MID Report
-
Chargeback data for all American Express transactions on the specified MID during a given date range
Example
[
{
"mid": "987654321987",
"alias": "ACME Digital UK MID",
"gateways": [
"64",
"213"
],
"chargeback_amount_ratio": 0.85,
"chargeback_amount": 801.94,
"chargeback_count": 20,
"chargeback_ratio": 0.86,
"transaction_amount": 94093.05,
"transaction_count": 2328,
"visa": {
"chargeback_amount_ratio": 0.68,
"chargeback_amount": 385.6,
"chargeback_count": 10,
"chargeback_ratio": 0.72,
"transaction_amount": 57021.69,
"transaction_count": 1396
},
"master_card": {
"chargeback_amount_ratio": 0.73,
"chargeback_amount": 274.4,
"chargeback_count": 7,
"chargeback_ratio": 0.78,
"transaction_amount": 26975.75,
"transaction_count": 675,
"previous_month_transaction_amount": 37372.45,
"previous_month_transaction_count": 897
},
"discover": {
"chargeback_amount_ratio": 1.3,
"chargeback_amount": 106.38,
"chargeback_count": 2,
"chargeback_ratio": 0.99,
"transaction_amount": 8167.61,
"transaction_count": 202
},
"amex": {
"chargeback_amount_ratio": 1.84,
"chargeback_amount": 35.56,
"chargeback_count": 1,
"chargeback_ratio": 1.81,
"transaction_amount": 1928,
"transaction_count": 55
}
}
]
Visa MID Report: object
Report of requested chargeback data for all Visa transactions on the specified MID
- chargeback_amount_ratio: number (float)
-
Ratio of the dollar amount of all Visa chargebacks to the dollar amount of all Visa transactions for the specified MID during a given date range
- chargeback_amount: number (float)
-
Total dollar amount of all Visa chargebacks for the specified MID during a given date range
- chargeback_count: integer
-
Total number of Visa chargebacks received on the specified MID during a given date range
- chargeback_ratio: number (float)
-
Ratio of the number of all Visa chargebacks to the number of all Visa transactions for the specified MID during a given date range
- transaction_amount: number (float)
-
Total dollar amount of all Visa transactions for the specified MID during a given date range
- transaction_count: integer
-
Total number of Visa transactions processed for the specified MID during a given date range
Example
{
"chargeback_amount_ratio": 0.68,
"chargeback_amount": 385.6,
"chargeback_count": 10,
"chargeback_ratio": 0.72,
"transaction_amount": 57021.69,
"transaction_count": 1396
}
Mastercard MID Report: object
For Example:
500 (July chargebacks) / 45,000 (June transactions) = 1.11%
- chargeback_amount_ratio: number (float)
-
Ratio of the dollar amount of all Mastercard chargebacks to the dollar amount of all Mastercard transactions for the specified MID during a given date range
- chargeback_amount: number (float)
-
Total dollar amount of all Mastercard chargebacks for the specified MID during a given date range
- chargeback_count: integer
-
Total number of Mastercard chargebacks received on the specified MID during a given date range
- chargeback_ratio: number (float)
-
Ratio of the number of all Mastercard chargebacks to the number of all Mastercard transactions for the specified MID during a given date range
- transaction_amount: number (float)
-
Total dollar amount of all Mastercard transactions for the specified MID during a given date range
- transaction_count: integer
-
Total number of Mastercard transactions processed for the specified MID during a given date range
- previous_month_transaction_amount: number (float)
-
Total dollar amount of all Mastercard transactions processed in the previous month for the specified MID
- previous_month_transaction_count: integer
-
Total number of Mastercard transactions processed during the previous month for the specified MID
Example
{
"chargeback_amount_ratio": 0.73,
"chargeback_amount": 274.4,
"chargeback_count": 7,
"chargeback_ratio": 0.78,
"transaction_amount": 26975.75,
"transaction_count": 675,
"previous_month_transaction_amount": 37372.45,
"previous_month_transaction_count": 897
}
Discover MID Report: object
Report of requested chargeback data for all Discover transactions on the specified MID
- chargeback_amount_ratio: number (float)
-
Ratio of the dollar amount of all Discover chargebacks to the dollar amount of all Discover transactions for the specified MID during a given date range
- chargeback_amount: number (float)
-
Total dollar amount of all Discover chargebacks for the specified MID during a given date range
- chargeback_count: integer
-
Total number of Discover chargebacks received on the specified MID during a given date range
- chargeback_ratio: number (float)
-
Ratio of the number of all Discover chargebacks to the number of all Discover transactions for the specified MID during a given date range
- transaction_amount: number (float)
-
Total dollar amount of all Discover transactions for the specified MID during a given date range
- transaction_count: integer
-
Total number of Discover transactions processed for the specified MID during a given date range
Example
{
"chargeback_amount_ratio": 1.3,
"chargeback_amount": 106.38,
"chargeback_count": 2,
"chargeback_ratio": 0.99,
"transaction_amount": 8167.61,
"transaction_count": 202
}
Amex MID Report: object
Report of requested chargeback data for all American Express transactions on the specified MID
- chargeback_amount_ratio: number (float)
-
Ratio of the dollar amount of all American Express chargebacks to the dollar amount of all American Express transactions for the specified MID during a given date range
- chargeback_amount: number (float)
-
Total dollar amount of all American Express chargebacks for the specified MID during a given date range
- chargeback_count: integer
-
Total number of American Express chargebacks received on the specified MID during a given date range
- chargeback_ratio: number (float)
-
Ratio of the number of all American Express chargebacks to the number of all American Express transactions for the specified MID during a given date range
- transaction_amount: number (float)
-
Total dollar amount of all American Express transactions for the specified MID during a given date range
- transaction_count: integer
-
Total number of American Express transactions processed for the specified MID during a given date range
Example
{
"chargeback_amount_ratio": 1.84,
"chargeback_amount": 35.56,
"chargeback_count": 1,
"chargeback_ratio": 1.81,
"transaction_amount": 1928,
"transaction_count": 55
}