Midigator® Data API API Reference

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.

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

  1. Make a POST to /auth to retrieve Bearer Authorization Token.
  2. Store token for re-use.
  3. After every completed or settled transaction, make a POST to /order with the required parameters.
  4. If any changes are made to the order, make a POST to /order including the order_id and the updated parameters (for example, adding a parcel tracking number or refunding 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

Request to obtain required DAPI authorization token

Parameter details for authorization request

Content-Type
in header
string

Only application/JSON content type is allowed 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

Endpoint used to create and update orders (it’s recommend that every completed/settled order is sent to the API, as well as any order updates)

Parameter details for order request

Content-Type
in header
string

Only application/JSON content type is allowed for this resource.

Authorization
in header
string

Make a POST to the /auth endpoint to obtain a bearer authorization token. The header must be structured 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

Requested authorization token

authorization_key: string

A unique bearer authorization token created for infinite use (recalling the authorization endpoint will generate a new token if desired)

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

Order: object

Original and updated order details

order_id: string

CRM or order management system’s identifier for the order

order_date: string (date-time)

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

order_total: string

Total dollar amount charged to the customer’s card, including shipping and tax if applicable

sales_tax: string

Sales tax percentage, if applicable

sales_tax_amount: string

Sales tax amount, if applicable

currency: string

Currency of the original order

order_status: string Complete, Refunded, Cancelled

Current order status

transaction_merchant_id: string

ID for the merchant account used to process the order

processor_id: string

Unique identifier of the applicable processor

cc_type: string

Card network that issued the applicable payment card (Visa, Mastercard, etc.)

cc_first_6: string

First six digits of the card used to process the order, a unique identifier of the bank that issued the card

cc_last_4: string

Last four digits of the card number associated with the order

cc_exp_month: string

Month the applicable credit or debit card expires (in numeric form)

cc_exp_year: string

Year the applicable credit or debit card expires

avs: string

Response code for Address Verification Service (AVS), a cardholder identification tool

cvv: string

Response code for Card Verification Value (CVV), a cardholder identification tool

eci: string

Response code for Electronic Commerce Indicator (ECI), a cardholder identification tool

customer_id: string

CRM or order management system’s identifier for the customer

ip_address: string

Consumer’s IP address

email_address: string

Email address associated with the order or customer account

customers_telephone: string

Phone number associated with the order or customer account

is_refund: boolean

Indicator of whether or not the customer was refunded, depicted with 1/0

refunded_to_date: string

Indicates amount refunded to customer for applicable order

rma_number: string

Unique identifier for original transaction that is refunded, if applicable

rma_reason: string

Explanation of refund request, if applicable

is_recurring: boolean

Indicator of whether or not the transaction is recurring, depicted as 1/0

recurring_date: string (date-time)

Indicator of next rebill cycle in UTC ISO 8601 format, if applicable

is_chargeback: boolean

Indicator of whether or not the transaction received a chargeback, depicted as 1/0

is_fraud: boolean

Indicator of whether or not the transaction was identified as fraud, depicted as 1/0

billing_cycle: string

Current billing cycle for a recurring transaction, if applicable

auth_id: string

Pre-authorization code returned by the processor

transaction_id: string

Post-authorization code returned by the processor

billing_first_name: string

Cardholder’s first name

billing_last_name: string

Cardholder’s last name

billing_street_address: string

Cardholder’s billing street address, line 1

billing_street_address_2: string

Cardholder’s billing street address, line 2

billing_city: string

Cardholder’s billing city

billing_state: string

Cardholder’s billing state, region, or province

billing_postcode: string

Cardholder’s billing zip code or post code

billing_country: string

Cardholder’s billing country code

affiliate: string

Unique identifier assigned to the marketing source, advertisement, or affiliate this order came from, if applicable

sub_affiliate: string

Unique identifier assigned to the sub marketing source, advertisement, or affiliate this order came from, if applicable

main_product_id: string

Unique identifier of the product purchased (or primary product if multiple items were purchased)

main_product_qty: string

Quantity of the product purchased (or primary product if multiple items were purchased)

is_test_cc: boolean

Indicator of whether or not the transaction was conducted as a test, depicted as 1/0

fulfillment: Fulfillment

Shipping information for tangible products or proof of service for intangible services

products: Products

Product details for merchandise associated with the order, including product name, price, product ID, quantity, and SKU

notes: Product Notes

Additional details pertaining to the order not categorized elsewhere

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 consisting of two array objects–shipments and proof of service

shipments: Shipping

Shipping array object within the fulfillment object; this object is required if the order includes tangible, shippable merchandise

proof_of_service: Proof of Service

Proof of service array object within the fulfillment object; this object is required if the order includes non-tangible or non-shippable services

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 for shipping information; fields are required if the order includes tangible merchandise

shipping_method: string

Carrier 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

Recipient’s first name

shipping_last_name: string

Recipient’s last name

shipping_street_address: string

Recipient’s street address, line 1

shipping_street_address_2: string

Recipient’s street address, line 2

shipping_city: string

Recipient’s city

shipping_state: string

Recipient’s state, region, or province

shipping_postcode: string

Recipient’s postal code

shipping_country: string

Recipient’s country code

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

An array object for proof of service information; unlimited number of type/value pairs are available; fields are required if the transaction includes intangible services

The proof of service array can be used to store additional transaction details. These details may be used to dispute a chargeback. This information may be shared with the cardholder and the cardholder’s bank. Only professional, accurate information should be included.

type: string

Type of data being used as proof of service (for example, log in history or user name)

value: string

Customer or order information that can be used as proof of service

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

Product Notes: array

JSON array object of customer service notes

timestamp: string (date-time)

Date and time the customer service note was added, displayed in UTC ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

note: string

Customer service note (the customer service agent’s name should not be included)

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

Products: array

JSON array object of product attributes

name: string

Name of product that was purchased

price: string

Price of the product that was purchased

product_id: string

Merchant’s unique identifier for the product

product_qty: string

Quantity of the product(s) purchased

sku: string

SKU of the product purchased

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

Response ID returned from Midigator’s data API indicating a successful API call

Example
{
  "id": "5910b744324a3f18b43f1653"
}