Midigator® Order Data API API Reference

Introduction

Midigator’s order data API is structured around the REST architectural style and returns JSON-encoded responses. It uses standard HTTP response codes and authentication.

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

If you have questions about the information in this API document or are unable to resolve an error message, please contact the integrations team at integrations@midigator.com.

API Flow

Midigator suggests using the order data API in the following flow:

1. Obtain an API Bearer Token

Use the Authentication API to obtain a bearer token for subsequent POST requests to /order.

2. Send Order Information

Information is passed to Midigator in multiple stages. The first data exchange happens immediately after the order has been processed.

Certain parameters (such as the date the order was processed, the order amount, payment card information, etc.) will be shared with Midigator as soon as it becomes available.

To share the order information, make a POST request to /order with all the required fields and any other information you have available.

3. Update Order Information

Any time order information is added or changed, you’ll want to pass the new or updated data to Midigator. Examples of such situations are: refunding the order, obtaining a tracking number, adding customer service notes, etc.

To share updated order information, make a POST request to /order with the applicable parameters. Please note that all required parameters must be provided when orders are updated.

API Endpoint
Production:https://api.midigator.com/orders/v2
Sandbox:https://api-sandbox.midigator.com/orders/v2
Contact: integrations@midigator.com
Schemes: https
Version: 0.7.3

Authentication

AuthorizationBearerToken

in
header
name
Authorization

Paths

Add or Update an Order

POST /order

Midigator uses the Order endpoint to receive order information, evidence, product/service information, and order notes. Each of these four sets of data are placed in separate objects and sent to the endpoint as a complete order object.

Some of the fields are required in order for Midigator to complete certain necessary actions. These fields are noted with “required” tags. Other properties are important and highly recommended.

Use the Order object to send order information to Midigator.

Content-Type

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

type
string
in
header
Request Content-Types: application/json
Request Example
{
  "order_id": "741258",
  "order_date": "2019-09-30T09:20:11Z",
  "mid": "189250002",
  "card_brand": "visa",
  "card_last_4": "1883",
  "card_first_6": "401288",
  "card_exp_month": "04",
  "card_exp_year": "2022",
  "order_amount": 1030,
  "avs": "y",
  "cvv": "m",
  "email": "jane@example.com",
  "phone": "555-254-4925",
  "refunded": true,
  "refunded_amount": 1030,
  "subscription_cycle": 3,
  "subscription_parent_id": "56",
  "ip_address": "192.168.133.7",
  "currency": "USD",
  "processor_auth_code": "741256",
  "processor_transaction_id": "NMI0983",
  "billing_first_name": "Jane",
  "billing_last_name": "Doe",
  "billing_street_address_1": "123 Sample Address",
  "billing_street_address_2": "Apt. B",
  "billing_city": "Detroit",
  "billing_state": "MI",
  "billing_postcode": "48201",
  "billing_country": "US",
  "marketing_source": "Facebook 234",
  "sub_marketing_sources": [
    "Age 18-25"
  ],
  "evidence": {
    "shipping_details": [
      {
        "carrier": "usps",
        "tracking_number": "8546315789936",
        "first_name": "Jane",
        "last_name": "Doe",
        "street_address_1": "123 Sample Address",
        "street_address_2": "Apt. B",
        "city": "Detroit",
        "state": "MI",
        "postcode": "48201",
        "country": "US"
      }
    ],
    "proof": [
      {
        "type": "login date",
        "value": "2019-09-30T09:23:10Z"
      }
    ]
  },
  "items": [
    {
      "id": "1098",
      "name": "Widget - Black",
      "price": 1030,
      "quantity": 1,
      "sku": "WID-06-BK-LG"
    }
  ],
  "notes": [
    {
      "timestamp": "2019-10-04T08:15:45Z",
      "value": "CRM API - Customer was refunded"
    }
  ]
}
200 OK

Everything worked as expected.

400 Bad Request

The request was unacceptable, usually because a required parameter was omitted.

401 Unauthorized

A valid API key wasn’t provided.

412 Precondition Failed

One or more conditions in the header were false when tested on the server.

422 Unprocessable Entity

The server understands the content type and the syntax is correct but was unable to process the instructions.

500 Internal Server Error

Midigator experienced a problem (rare).

504 Gateway Timeout

Midigator experienced a problem (rare).

Schema Definitions

order: object

Use the Order object to send order information to Midigator.

Certain fields should be shared as soon as the order has been completed. This includes information such as the date the order was processed, the order amount, payment card information, etc.

Other fields can be sent any time the order information is updated. For example, make a POST request if the order was refunded.

order_id: string

The order_id field is the unique code you use in your CRM or order management system to identify an order.

order_date: string (date-time)

The order_date field is the date and time that the customer's bank approved (or authorized) the order.

FORMATTING REQUIREMENTS: Please use UTC date-time formatted as specified in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ), For example, "2012-05-11T13:15:47Z". ISO formatting references can be found here and here.

mid: string

The mid field identifies the merchant account used to process the order. This is generally the merchant account ID (MID), but any unique account ID will be accepted. This is the ID provided to Midigator during on-boarding to identify the merchant account.

card_brand: string , x ∈ { visa , mastercard , american_express , discover , diners , elo , paypal , jcb }

The card_brand field is the payment card network that issued the card to the customer. For example, Visa and Mastercard are payment card networks.

card_last_4: string

The card_last_4 field is the last four digits of the payment card number used to process the order.

FORMATTING REQUIREMENTS: Please do not use asterisks (*) to represent the preceding digits of the payment card number. Leading zeros should be included (i.e. "0004").

card_first_6: string

The card_first_6 field is the first six digits of the payment card number used to process the order. This field isn’t required, but it is highly recommended.

FORMATTING REQUIREMENTS: Please do not use asterisks (*) to represent the remaining digits of the payment card number.

card_exp_month: string , x ∈ { 01 , 02 , 03 , 04 , 05 , 06 , 07 , 08 , 09 , 10 , 11 , 12 }

The card_exp_month field is the month that the customer’s card expires. Please send data in numeric form, using a two-digit code. For example: '01' for January. This field isn’t required, but it is highly recommended.

card_exp_year: string , x ∈ { 2019 , 2020 , 2021 , ... }

The card_exp_year field is the year that the customer’s card expires. Please send data in numeric form, using a four-digit code. This field isn’t required, but it is highly recommended.

order_amount: integer

The order_amount field is the total order amount that was charged to the customer's card. If applicable, this amount should also include shipping and tax. This field isn’t required, but it is highly recommended.

FORMATTING REQUIREMENTS: The value should be in the currency’s smallest denomination. For example, USD $10.30 would be 1030. This field will not accept floating point numbers.

avs: string , x ∈ { a , b , c , d , e , f , g , h , i , k , l , m , n , o , p , r , s , t , u , v , w , x , y , z , 0 , 1 , 2 , 3 , 4 , ae1 , ae2 , ae3 , ae4 , ae5 , ae6 , ae7 , ae8 }

The avs field is the Address Verification Service (AVS) response code provided by the customer’s bank during the authorization process. AVS is an identity verification tool that compares the billing address provided during checkout to the address on file with the cardholder’s bank. If you do not use AVS during the checkout process, this field can be left empty. However, you should consider using AVS as it plays an important role in winning disputes.

cvv: string , x ∈ { a , b , d , e , i , m , n , p , s , u , x , y , 0 , 1 , 2 , 3 , 4 }

The cvv field is the card verification response code provided by the customer’s bank during the authorization process. The three or four-digit card verification value (called CVV, CVV2, CVC 2, etc.) is printed on the customer’s card. Asking for this number during the checkout process helps ensure the shopper has the card in-hand. If you do not ask for the card verification value during the checkout process, this field can be left empty. However, you should consider using CVV as it plays an important role in winning disputes.

email: string

The email field is the customer’s email address. If the customer didn’t provide an email address or the information isn’t included in the order details, this field can be left empty.

phone: string

The phone field is the customer’s phone number. If the customer didn’t provide a phone number or the information isn’t included in the order details, this field can be left empty. This field isn’t required, but it is highly recommended.

refunded: boolean

The refund field indicates whether or not the order has been refunded. This field isn’t required, but it is highly recommended.

refunded_amount: integer

The refund_amount field is the amount that has been refunded to the customer. If one or more partial refunds have been issued, share the total refund amount to date in this field. This field isn’t required, but it is highly recommended.

FORMATTING REQUIREMENTS: The value should be in the currency’s smallest denomination. For example, USD $10.30 would be 1030. This field will not accept floating point numbers.

subscription_cycle: integer

The subscription_cycle field is the running count of orders that have been made in an ongoing subscription. If the order wasn’t part of a subscription, this field can be left empty.

FORMATTING REQUIREMENTS: The value of an initial payment in a subscription billing model is 0. The first subscription payment after the initial order is 1 and so on.

subscription_parent_id: string

The subscription_parent_id field is a unique value that is used to identify and group orders that have been processed in a given subscription. Assign the subscription_parent_id to the initial order and then add it to all subsequent orders. If the order wasn’t part of a subscription, this field can be left empty.

ip_address: string

The ip_address field is the internet protocol (IP) address of the device the customer used to place the order. If you do not record IP addresses during the checkout process, this field can be left empty. However, you should consider collecting an IP address for each order as it plays an important role in winning disputes.

FORMATTING REQUIREMENTS: Both IPv4 and IPv6 formats are both accepted.

currency: string , x ∈ { USD , GBP , JPY , etc. }

The currency field is the currency of the order amount (order_amount field). If this information is not passed to Midigator, USD will be used by default.

FORMATTING REQUIREMENTS: This field value is the three-character ISO 4217 code. ISO formatting references can be found here and here.

processor_auth_code: string

The processor_auth_code field is the authorization code returned by the processor after you submit an authorization request. Authorization requests are made and codes returned before the order is finalized. This field isn’t required, but it is highly recommended.

processor_transaction_id: string

The processor_transaction_id field is the unique ID your processor or gateway uses for the order. This field isn’t required, but it is highly recommended.

billing_first_name: string

The billing_first_name field is the customer’s first name as it appears on their payment card.

billing_last_name: string

The billing_last_name field is the customer’s last name as it appears on their payment card.

billing_street_address_1: string

The billing_street_address_1 field is the first line of the customer’s billing address (the billing address is the address the customer’s bank has on file and where monthly statements are sent). This line typically contains street and building information. If you do not ask for a billing address during the checkout process, this field can be left empty.

billing_street_address_2: string

The billing_street_address_2 field is the second line of the customer’s billing address (the billing address is the address the customer’s bank has on file and where monthly statements are sent). This line typically contains a suite or apartment number when applicable. If you do not ask for a billing address during the checkout process or the customer doesn’t have a two-line address, this field can be left empty.

billing_city: string

The billing_city field is the city associated with the customer’s billing address (the billing address is the address the customer’s bank has on file and where monthly statements are sent). If you do not ask for a billing address during the checkout process, this field can be left empty.

billing_state: string

The billing_state field is the state, region, or providence associated with the customer’s billing address (the billing address is the address the customer’s bank has on file and where monthly statements are sent). If you do not ask for a billing address during the checkout process, this field can be left empty.

FORMATTING REQUIREMENTS: Please use the ISO 3166-2 subdivision codes. When applicable, please use a two-letter state abbreviation. For example, use CA for California, FL for Florida, IA for Iowa, etc. ISO formatting references can be found here and here.

billing_postcode: string

The billing_postcode field is the zip code or postal code associated with the customer’s billing address (the billing address is the address the customer’s bank has on file and where monthly statements are sent). If you do not ask for a billing address during the checkout process, this field can be left empty.

billing_country: string

The billing_country field is the country associated with the customer’s billing address (the billing address is the address the customer’s bank has on file and where monthly statements are sent). If you do not ask for a billing address during the checkout process, this field can be left empty.

FORMATTING REQUIREMENTS: Please use two-digit ISO 3166-1 country codes. For example, use AU for Australia, CA for Canada, US for United States of America, etc. ISO formatting references can be found here and here.

marketing_source: string

The marketing_source field is the unique identifier you use in your CRM or order management system to track the marketing source, advertisement, or affiliate that brought you the order. For example, "Facebook 234", "Spring Campaign 1", etc. If you don’t collect or track this information, this field can be left empty.

sub_marketing_sources: string[]

The sub_marketing_sources field are the additional tags associated with the main marketing source, advertisement, or affiliate. For example, your marketing_source could be "Facebook 234", and your sub_marketing_sources field could be "Age 18-25", "Age 30-40", etc.

Or your marketing_source field could be "Affiliate Network", and your sub_marketing_sources field could be "Affiliate 1", "Affiliate 2", etc.

If you don’t collect or track sub marketing sources, this field can be left empty.

evidence: evidence
items: items
notes: notes
Example
{
  "order_id": "741258",
  "order_date": "2019-09-30T09:20:11Z",
  "mid": "189250002",
  "card_brand": "visa",
  "card_last_4": "1883",
  "card_first_6": "401288",
  "card_exp_month": "04",
  "card_exp_year": "2022",
  "order_amount": 1030,
  "avs": "y",
  "cvv": "m",
  "email": "jane@example.com",
  "phone": "555-254-4925",
  "refunded": true,
  "refunded_amount": 1030,
  "subscription_cycle": 3,
  "subscription_parent_id": "56",
  "ip_address": "192.168.133.7",
  "currency": "USD",
  "processor_auth_code": "741256",
  "processor_transaction_id": "NMI0983",
  "billing_first_name": "Jane",
  "billing_last_name": "Doe",
  "billing_street_address_1": "123 Sample Address",
  "billing_street_address_2": "Apt. B",
  "billing_city": "Detroit",
  "billing_state": "MI",
  "billing_postcode": "48201",
  "billing_country": "US",
  "marketing_source": "Facebook 234",
  "sub_marketing_sources": [
    "Age 18-25"
  ],
  "evidence": {
    "shipping_details": [
      {
        "carrier": "usps",
        "tracking_number": "8546315789936",
        "first_name": "Jane",
        "last_name": "Doe",
        "street_address_1": "123 Sample Address",
        "street_address_2": "Apt. B",
        "city": "Detroit",
        "state": "MI",
        "postcode": "48201",
        "country": "US"
      }
    ],
    "proof": [
      {
        "type": "login date",
        "value": "2019-09-30T09:23:10Z"
      }
    ]
  },
  "items": [
    {
      "id": "1098",
      "name": "Widget - Black",
      "price": 1030,
      "quantity": 1,
      "sku": "WID-06-BK-LG"
    }
  ],
  "notes": [
    {
      "timestamp": "2019-10-04T08:15:45Z",
      "value": "CRM API - Customer was refunded"
    }
  ]
}

evidence: object

The evidence object is nested in the order object. It consists of two arrays that contain information about proof of delivery for physical goods and proof of use for digital goods or services. The information in the evidence object is typically passed as additions or updates to previously passed orders. For example, you’ll pass the shipment tracking number after the order has been processed, POSTed to Midigator, and shipped.

shipping_details: shipping_details
proof: proof
Example
{
  "shipping_details": [
    {
      "carrier": "usps",
      "tracking_number": "8546315789936",
      "first_name": "Jane",
      "last_name": "Doe",
      "street_address_1": "123 Sample Address",
      "street_address_2": "Apt. B",
      "city": "Detroit",
      "state": "MI",
      "postcode": "48201",
      "country": "US"
    }
  ],
  "proof": [
    {
      "type": "login date",
      "value": "2019-09-30T09:23:10Z"
    }
  ]
}

shipping_details: object[]

The shipping_details array is nested in the evidence object. It consists of objects that contain information about the shipment and delivery of physical goods.

While this information isn’t required, it is very important. Midigator recommends you send this information for all orders with physical goods. If you do not sell physical goods, this array can be left empty.

object
carrier: string

The carrier field is the carrier you used to deliver the order. Examples of carriers are FedEx, USPS, UPS, DHL, etc. This field isn’t required, but it is highly recommended.

tracking_number: string

The tracking_number field is the unique ID provided by the carrier that is used to identify and track a shipment. This field isn’t required, but it is highly recommended.

first_name: string

TThe first_name field is the first name of the shipment recipient.

last_name: string

The last_name field is the last name of the shipment recipient.

street_address_1: string

The street_address_1 field is the first line of the recipient's address. This line typically contains street and building information.

street_address_2: string

The street_address_2 field is the second line of the recipient's address. This line typically contains a suite or apartment number when applicable. If the recipient doesn’t have a two-line address, this field can be left empty.

city: string

The city field is the city the package was shipped to.

state: string

The state field is the state, region, or providence the package was shipped to.

FORMATTING REQUIREMENTS: Please use the ISO 3166-2 subdivision codes. When applicable, please use a two-letter state abbreviation. For example, use CA for California, FL for Florida, IA for Iowa, etc. ISO formatting references can be found here and here.

postcode: string

The postcode field is the zip code or postal code the package was shipped to.

country: string

The country field is the country the package was shipped to.

FORMATTING REQUIREMENTS: Please use two-digit ISO 3166-1 country codes. For example, use AU for Australia, CA for Canada, US for United States of America, etc. ISO formatting references can be found here and here.

Example
[
  {
    "carrier": "usps",
    "tracking_number": "8546315789936",
    "first_name": "Jane",
    "last_name": "Doe",
    "street_address_1": "123 Sample Address",
    "street_address_2": "Apt. B",
    "city": "Detroit",
    "state": "MI",
    "postcode": "48201",
    "country": "US"
  }
]

proof: object[]

The proof array is nested in the evidence object. It consists of objects that prove the customer received or used the purchased services or digital goods.

You can share an unlimited number of type/value pairs.

If order information is updated frequently (for example, real-time login and usage data), send the information to Midigator in a daily batch.

While this information isn’t required, it is very important. Midigator recommends you send this information for all service or digital good orders. If you do not sell services or digital goods, this array can be left empty.

NOTE: Midigator includes this information in dispute responses. It may be shared with your customer and your customer’s bank. Only professional, accurate information should be included.

object
type: string

The type field is the type of information being passed. Examples of "proof of service" include signed contracts, emails, phone call transcript, etc. Examples of "proof of use" include login data, app usage, account updates, etc.

value: string

The value field is the content of the proof.

Example
[
  {
    "type": "login date",
    "value": "2019-09-30T09:23:10Z"
  }
]

items: object[]

The items array is nested in the order object. It consists of several strings and contains information about the products or services included in the order.

Midigator uses this information to create detailed analytics. If you’d like access to these analytics, certain fields in this array are required.

Also, please note that if more than one product or service is included, Midigator will use the first id in the array for analytics.

object
id: string

The id field is the unique ID for your product or service. If you are utilizing the item array, this field is required.

name: string

The name field is the name you use to identify the product or service.

price: integer

The price field is the price of the product or service.

FORMATTING REQUIREMENTS: The value should be in the currency’s smallest denomination. For example, USD $10.30 would be 1030. This field will not accept floating point numbers.

quantity: integer

The quantity field is the quantity of the item purchased.

sku: string

The sku field is the unique SKU (stock keeping unit) number you use to identify the product.

Example
[
  {
    "id": "1098",
    "name": "Widget - Black",
    "price": 1030,
    "quantity": 1,
    "sku": "WID-06-BK-LG"
  }
]

notes: object[]

The notes array is nested in the order object. It contains order notes logged in your CRM or order management system. This can include notes that were manually added to your system (for example, comments recorded by a customer service representative) or notes automatically created by the system (for example, a refund being issued).

You can share an unlimited number of timestamp/value pairs.

NOTE: Midigator includes this information in chargeback responses. It may be shared with your customer and your customer’s bank. Only professional, accurate information should be included.

object
timestamp: string (date-time)

The timestamp field is the date and time the note was added to your system.

FORMATTING REQUIREMENTS: Please use UTC ISO 8601 format: YYYY-MM-DDThh:mm:ssSZ. ISO formatting references can be found here and here.

value: string

The value field is the content of the note.

Example
[
  {
    "timestamp": "2019-10-04T08:15:45Z",
    "value": "CRM API - Customer was refunded"
  }
]