MiDiGATOR® Data 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.

The Midigator Data API must be used in the following flow:

  1. Make a POST to /auth to retrieve your Bearer Authorization Token
  2. Store that token for re-use as it does not expire
  3. After every completed or settled transaction make a POST to /order with the required parameters
  4. On every update to each transaction after it’s been completed make a POST to /order along with the order_id and any of the parameters that have been updated. ie. If an order is refunded or if there are any notes added to the order

API Endpoint

Production:https://dapi.midigator.com/v1
Sandbox:https://dapi.midigator.com/stage
Contact: integrations@midigator.com
Schemes: https
Version: 1.1.0

Paths

POST /auth

Authentication request in order to receive an auth token which will be required in all DAPI requests

Authentication request parameter details

Content-Type
in header
string

We only allow application/json content type for this resource.

Request Content-Types: application/json
Request Example
{
  "username": "sandbox_user",
  "password": "4f86fed3605b647f948a69ec6bcf728d"
}
200 OK

200 response

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 Content-Types: application/json
Response Example (200 OK)
{
  "authorization_key": "$6$rounds=193723$Nhy7aSYN/i4bMQFd$390H2DQUWF5.n0BHp/GPpy5CsmzJaxFIIr2"
}

POST /order

The Order endpoint is used to create and update orders.
We recommend that every order upon being completed or settled to be sent to our api, as well as anytime that order is update from then.

Details about the order request parameters

Content-Type
in header
string

We only allow application/json content type for this resource.

Authorization
in header
string

Obtain your bearer authorization token by making a POST to /auth endpoint. You must structure your header to include the key:value {Authorization: Bearer xxxx}

Request Content-Types: application/json
Request Example
{
  "order_id": "741258",
  "order_date": "2017-06-28 09:20:11",
  "order_total": "26.85",
  "sales_tax": "4.1%",
  "sales_tax_amount": "1.10",
  "currency": "USD",
  "order_status": "Complete",
  "transaction_merchant_id": "242",
  "processor_id": "NMI0983",
  "cc_type": "visa",
  "cc_first_6": "401288",
  "cc_last_4": "1883",
  "cc_exp_month": "04",
  "cc_exp_year": "2022",
  "avs": "Y",
  "cvv": "M",
  "eci": "05",
  "customer_id": "7458963214",
  "ip_address": "192.168.133.7",
  "email_address": "jane@example.com",
  "customers_telephone": "555-254-4925",
  "is_refund": 1,
  "refunded_to_date": "25.00",
  "rma_number": "567843",
  "rma_reason": "Customer called for refund",
  "is_recurring": 1,
  "recurring_date": "2017-06-28 09:20:11",
  "is_chargeback": 0,
  "is_fraud": 0,
  "billing_cycle": "3",
  "auth_id": "741256",
  "transaction_id": "985631214878714",
  "billing_first_name": "Jane",
  "billing_last_name": "Doe",
  "billing_street_address": "123 Sample Address",
  "billing_street_address_2": "Apt. B",
  "billing_city": "Detroit",
  "billing_state": "MI",
  "billing_postcode": "48201",
  "billing_country": "US",
  "affiliate": "456",
  "sub_affiliate": "23",
  "main_product_id": "56",
  "main_product_qty": "23",
  "is_test_cc": 0,
  "fulfillment": {
    "shipments": [
      {
        "shipping_method": "usps",
        "shipping_date": "2017-06-28 09:20:11",
        "tracking_number": "8546315789936",
        "shipping_first_name": "Jane",
        "shipping_last_name": "Doe",
        "shipping_street_address": "123 Sample Address",
        "shipping_street_address_2": "Apt. B",
        "shipping_city": "Detroit",
        "shipping_state": "MI",
        "shipping_postcode": "48201",
        "shipping_country": "US"
      }
    ],
    "proof_of_service": [
      {
        "type": "key1",
        "value": "value1"
      },
      {
        "type": "key2",
        "value": "value2"
      }
    ]
  },
  "products": [
    {
      "name": "Facial Toner",
      "price": "13.95",
      "product_id": "98",
      "product_qty": "1",
      "sku": "LEV-JN-36-GN"
    }
  ],
  "notes": [
    {
      "timestamp": "2017-06-28 09:20:11",
      "note": "CRM API - Customer was blacklisted."
    }
  ]
}

200 response

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 Content-Types: application/json
Response Example (200 OK)
{
  "id": "5910b744324a3f18b43f1653"
}

Schema Definitions

Auth: object

Authenticating against Midigator Data API (DAPI). This will generate a new token.

username: string

Username provided by Midigator

password: string

Password provided by Midigator

Example
{
  "username": "sandbox_user",
  "password": "4f86fed3605b647f948a69ec6bcf728d"
}

Auth Response: object

Response to expect from DAPI

authorization_key: string

A unique bearer token generated to be used for authentication. This token is set to live forever by default, but if for any reason if you'd like to renew your token, just recall the auth endpoint and you'll receive a fresh new token.

Example
{
  "authorization_key": "$6$rounds=193723$Nhy7aSYN/i4bMQFd$390H2DQUWF5.n0BHp/GPpy5CsmzJaxFIIr2"
}

Order: object

Details about an individual unique transaction.

order_id: string

Unique order/invoice identifier for this transaction from Merchant's order manager

order_date: string (date-time)

Date/time when transaction was approved in UTC ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

order_total: string

Total amount charged to customer for this order including shipping & tax, if applicable

sales_tax: string

The tax percentage on the transaction, if applicable

sales_tax_amount: string

The tax amount on the transaction, if applicable

currency: string

The currency of the transaction amount

order_status: string Complete, Refunded, Cancelled

Complete: Settled transaction
Refunded: Refunded transaction
Cancelled: Void transaction

transaction_merchant_id: string

Any unique identifier which maps the transaction to the merchant account number it was transacted on

processor_id: string

Unique identifier of the processor for this transaction

cc_type: string

Type of credit card used

cc_first_6: string

First six digits of the credit card used

cc_last_4: string

Last four digits of the credit card used

cc_exp_month: string

Month of expiration indicated in numeric form on credit card used

cc_exp_year: string

Year of expiration indicated in numeric form on credit card used

avs: string

Address verification service response code

cvv: string

Card verification value response code

eci: string

Electronic Commerce Indicator (ECI) is a value that is returned from the Directory Server (Visa, MasterCard) to indicate the authentication results of your customer's credit card payment on 3D Secure.

customer_id: string

Unique identification number for the customer in your Merchant's order manager

ip_address: string

Consumer’s IP address

email_address: string

Email address indicated on order or customer account

customers_telephone: string

Phone number indicated on order or customer account

is_refund: boolean

Set 1 or 0 based on if any amount of the order has been refunded to the customer

refunded_to_date: string

When order refund, indicate amount refunded to date for this order (not other orders on customer’s account)

rma_number: string

The original transaction id for the order that is refunded, if refund

rma_reason: string

Text description of reason for refund, if refund

is_recurring: boolean

Set 1 or 0 based on if the order is recurring

recurring_date: string (date-time)

When recurring, indicate date of next rebill cycle in UTC ISO 8601 format, can be null

is_chargeback: boolean

Set 1 or 0 based on if the transaction has been marked as a dispute

is_fraud: boolean

Set 1 or 0 based on if the transaction has been marked as fraudulent

billing_cycle: string

The current number of the billing cycle for this transaction, if recurring

auth_id: string

Pre-authorization code returned by the processor

transaction_id: string

Post-authorization code returned by the processor

billing_first_name: string

First name of credit card holder

billing_last_name: string

Last name of credit card holder

billing_street_address: string

Billing street address of credit card holder

billing_street_address_2: string

Billing street address line 2 of credit card holder

billing_city: string

Billing city of credit card holder

billing_state: string

State acronym for billing state, region or province

billing_postcode: string

Billing Post/Zip code of credit card holder

billing_country: string

Country code for billing country of credit card holder

affiliate: string

Unique id assigned to affiliate this transaction came from, if applicable

sub_affiliate: string

Unique id assigned to the sub affiliate this transaction came from, if applicable

main_product_id: string

Unique id assigned to the the main product if transaction consists of multiple products

main_product_qty: string

Quantity of main product if transaction consists of multiple products

is_test_cc: boolean

Set to 1 or 0 if the transaction is a test transaction, defaults to 0

fulfillment: Fulfillment

Fulfilment object includes shipments and/or proof of service. For shippable products, shipment information is required and for other services proof of service is required.

products: Products
notes: Product Notes
Example
{
  "order_id": "741258",
  "order_date": "2017-06-28 09:20:11",
  "order_total": "26.85",
  "sales_tax": "4.1%",
  "sales_tax_amount": "1.10",
  "currency": "USD",
  "order_status": "Complete",
  "transaction_merchant_id": "242",
  "processor_id": "NMI0983",
  "cc_type": "visa",
  "cc_first_6": "401288",
  "cc_last_4": "1883",
  "cc_exp_month": "04",
  "cc_exp_year": "2022",
  "avs": "Y",
  "cvv": "M",
  "eci": "05",
  "customer_id": "7458963214",
  "ip_address": "192.168.133.7",
  "email_address": "jane@example.com",
  "customers_telephone": "555-254-4925",
  "is_refund": 1,
  "refunded_to_date": "25.00",
  "rma_number": "567843",
  "rma_reason": "Customer called for refund",
  "is_recurring": 1,
  "recurring_date": "2017-06-28 09:20:11",
  "is_chargeback": 0,
  "is_fraud": 0,
  "billing_cycle": "3",
  "auth_id": "741256",
  "transaction_id": "985631214878714",
  "billing_first_name": "Jane",
  "billing_last_name": "Doe",
  "billing_street_address": "123 Sample Address",
  "billing_street_address_2": "Apt. B",
  "billing_city": "Detroit",
  "billing_state": "MI",
  "billing_postcode": "48201",
  "billing_country": "US",
  "affiliate": "456",
  "sub_affiliate": "23",
  "main_product_id": "56",
  "main_product_qty": "23",
  "is_test_cc": 0,
  "fulfillment": {
    "shipments": [
      {
        "shipping_method": "usps",
        "shipping_date": "2017-06-28 09:20:11",
        "tracking_number": "8546315789936",
        "shipping_first_name": "Jane",
        "shipping_last_name": "Doe",
        "shipping_street_address": "123 Sample Address",
        "shipping_street_address_2": "Apt. B",
        "shipping_city": "Detroit",
        "shipping_state": "MI",
        "shipping_postcode": "48201",
        "shipping_country": "US"
      }
    ],
    "proof_of_service": [
      {
        "type": "key1",
        "value": "value1"
      },
      {
        "type": "key2",
        "value": "value2"
      }
    ]
  },
  "products": [
    {
      "name": "Facial Toner",
      "price": "13.95",
      "product_id": "98",
      "product_qty": "1",
      "sku": "LEV-JN-36-GN"
    }
  ],
  "notes": [
    {
      "timestamp": "2017-06-28 09:20:11",
      "note": "CRM API - Customer was blacklisted."
    }
  ]
}

Fulfillment: object

JSON object of fulfillment information for this transaction. For shippable products, shipment information is required and for other services proof of service is required.

shipments: Shipping

Shipping array object with in the fulfillment object. Includes all shipping details. This object is required for shippable goods.

proof_of_service: Proof of Service

Transactions proof of service array, if applicable. The proof of service array is design so that any extra data about the transaction can be communicated as a key value pair to Midigator. This object is required for all non shippable products.

Example
{
  "shipments": [
    {
      "shipping_method": "usps",
      "shipping_date": "2017-06-28 09:20:11",
      "tracking_number": "8546315789936",
      "shipping_first_name": "Jane",
      "shipping_last_name": "Doe",
      "shipping_street_address": "123 Sample Address",
      "shipping_street_address_2": "Apt. B",
      "shipping_city": "Detroit",
      "shipping_state": "MI",
      "shipping_postcode": "48201",
      "shipping_country": "US"
    }
  ],
  "proof_of_service": [
    {
      "type": "key1",
      "value": "value1"
    },
    {
      "type": "key2",
      "value": "value2"
    }
  ]
}

Shipping: array

JSON array object of all shipping information for this transaction. These fields are required when the product is shippable.

object
shipping_method: string

Parcel or method used for shipment

shipping_date: string (date-time)

Date shipment was made in UTC ISO 8601 format

tracking_number: string

Tracking number for the shipment

shipping_first_name: string

Shipping first name

shipping_last_name: string

Shipping last name

shipping_street_address: string

Shipping street address

shipping_street_address_2: string

Shipping street address line 2

shipping_city: string

Shipping city

shipping_state: string

State acronym for shipping state, region or province

shipping_postcode: string

Shipping Post/Zip code

shipping_country: string

Country code for shipping country

Example
[
  {
    "shipping_method": "usps",
    "shipping_date": "2017-06-28 09:20:11",
    "tracking_number": "8546315789936",
    "shipping_first_name": "Jane",
    "shipping_last_name": "Doe",
    "shipping_street_address": "123 Sample Address",
    "shipping_street_address_2": "Apt. B",
    "shipping_city": "Detroit",
    "shipping_state": "MI",
    "shipping_postcode": "48201",
    "shipping_country": "US"
  }
]

Proof of Service: array

Array object for the transactions proof of service, this object is required for all non shippable products.
Proof of service array is design so that any extra data about the transaction can be communicated as a key value pair to Midigator.
Proof of service array will accept any number of type value pairs.
Type and value pairs that are provided under proof of service will be displayed on the re-presentment as provided.

object
type: string

The parameter name to be used in the re-presentment

value: string

The value to that parameter to be use in the re-presentment

Example
[
  {
    "type": "key1",
    "value": "value1"
  },
  {
    "type": "key2",
    "value": "value2"
  }
]

Product Notes: array

JSON array of customer service notes for this transaction

object
timestamp: string (date-time)

Timestamp for customer service note entry for this order in UTC ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

note: string

Content of the customer service note record *NOTE: No customer service agent name should be included

Example
[
  {
    "timestamp": "2017-06-28 09:20:11",
    "note": "CRM API - Customer was blacklisted."
  }
]

Products: array

JSON array of products attributes purchased with this transaction

object
name: string

The name of the purchased product

price: string

Price of product with in the order

product_id: string

A unique identifier associated with this product within your database

product_qty: string

The total number of this product the customer purchased

sku: string

Product sku assigned to this product

Example
[
  {
    "name": "Facial Toner",
    "price": "13.95",
    "product_id": "98",
    "product_qty": "1",
    "sku": "LEV-JN-36-GN"
  }
]

Order Response: object

Response to expect from DAPI

id: string

Internal order identifier for the midigator Data API system.

Example
{
  "id": "5910b744324a3f18b43f1653"
}