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 should only happen after the order has been processed and funds have been collected.
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.
Base URL
Production:https://api.midigator.com/orders/v2
Sandbox:https://api-sandbox.midigator.com/orders/v2
Contact: integrations@midigator.com
Schemes: https
Version: 0.7.4
Authentication
AuthorizationBearerToken
Paths
Add or Update an 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.
Only application/json content type is allowed for this resource.
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"
}
],
"match": {
"chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3"
}
}
Everything worked as expected. Note: Each POST/order (new orders and updated orders) will generate a new order_guid that will be returned in the response. New Order GUIDs are associated with your company, crm account, and the order_id that is sent in the POST/order. Updated Order GUIDs are created and saved by Midigator, but the original order_guid association in our database will remain the same.
The request was unacceptable, usually because a required parameter was omitted.
A valid API key wasn’t provided.
One or more conditions in the header were false when tested on the server.
The server understands the content type and the syntax is correct but was unable to process the instructions.
Midigator experienced a problem (rare).
Midigator experienced a problem (rare).
Response Example (200 OK)
{
"order_guid": "ord_d8cb61dea06e48af9b46c1f5160784c3"
}
Schema Definitions
order_post: object
- order_guid: string
Example
{
"order_guid": "ord_d8cb61dea06e48af9b46c1f5160784c3"
}
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, do not include the AVS key/value pair. 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 use CVV during the checkout process, do not include the CVV key/value pair. 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_amountfield). 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
- match: match
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"
}
],
"match": {
"chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3"
}
}
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.
- 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.
- 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.
- 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. The item should be formatted as an integer within the id string.
- 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.
Example
[
{
"timestamp": "2019-10-04T08:15:45Z",
"value": "CRM API - Customer was refunded"
}
]
match: object
The match object is used to match a chargeback to an order. A match can be made when the order is added or updated.
- chargeback_guid: string
-
The chargeback_guid field is used to identify the chargeback you want to match to. The chargeback_guid is the Midigator chargeback guid obtained from the Eventing API.
Example
{
"chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3"
}