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
Production: 
https://reporting.midigator.com
Sandbox: 
https://reporting-api.stage01.midigator.net
Contact: integrations@midigator.com
Schemes: https
Version: 1.1.0

Paths

POST /chargebacks

Endpoint for requesting chargeback data

Chargeback Request

Request for chargeback data

Content-Type

Only application/JSON content type is allowed for this resource

type
string
in
header
Authorization

Contact an account manager to obtain a bearer authorization key. The header must be structured to include the key:value {Authorization:Bearer xxxx}

type
string
in
header
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 OK
Chargeback Response

200 response
If no data can be found for valid parameters, the response will be an empty 200

400 Bad Request

400 response

401 Unauthorized

401 response

412 Precondition Failed

412 response

422 Unprocessable Entity

422 response

500 Internal Server Error

500 response

504 Gateway Timeout

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

Prevention Request

Request for prevention alert data

Content-Type

Only application/JSON content type is allowed for this resource

type
string
in
header
Authorization

Contact an account manager to obtain a bearer authorization key. The header must be structured to include the key:value {Authorization:Bearer xxxx}

type
string
in
header
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 OK
Prevention Response

200 response
If no data can be found for valid parameters, the response will be an empty 200

400 Bad Request

400 response

401 Unauthorized

401 response

412 Precondition Failed

412 response

422 Unprocessable Entity

422 response

500 Internal Server Error

500 response

504 Gateway Timeout

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

MID Report Request

Request for MID data

Content-Type

Only application/JSON content type is allowed for this resource

type
string
in
header
Authorization

Contact an account manager to obtain a bearer authorization key. The header must be structured to include the key:value {Authorization:Bearer xxxx}

type
string
in
header
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 OK
MID Report Response

200 response
If no data can be found for valid parameters, the response will be an empty 200

400 Bad Request

400 response

401 Unauthorized

401 response

412 Precondition Failed

412 response

422 Unprocessable Entity

422 response

500 Internal Server Error

500 response

504 Gateway Timeout

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

object
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

object
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

object
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.

For Example:
500 (July chargebacks) / 45,000 (June transactions) = 1.11%
Chargeback data for all Mastercard transactions on the specified MID during a given date range

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

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.

For Example:
500 (July chargebacks) / 45,000 (June transactions) = 1.11%
Report of requested chargeback data for all Mastercard transactions on the specified MID

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
}
Documentation by Midigator®