Midigator® Events API API Reference

Introduction

Midigator’s events 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, Golang, PHP, and Python, and it can be deployed on multiple platforms, such as Windows, Mac OS, or Linux.

Midigator does not dictate how the actions must be taken in your CRM; the Events API is only concerned with publishing event-specific information and receiving confirmation that the event was successfully received by the subscriber.

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.

Event Types

This API includes the following event types:

New Chargeback

A chargeback.new event is fired when Midigator receives your chargeback.

New Prevention Alert

A prevention.new event is fired when Midigator receives your prevention alert (Ethoca, Verifi, or VMPI).

Chargeback Matched to Order

A chargeback.match event is fired when Midigator matches your chargeback to its original order.

Prevention Alert Matched to Order

A prevention.match event is fired when Midigator matches your prevention alert to its original order.

Order Refund

A order.refund event is fired when you need to refund an order that's received a prevention alert.

API Flow

Midigator suggests using the events API in the following flow:

1. Obtain an API Bearer Token

Use the Authentication API to obtain a bearer token for subsequent requests to /subscribe and other event API endpoints.

2. Subscribe to Desired Event Types

To receive information from Midigator, you need subscriptions to the different event types. Make a POST request to /subscribe and indicate which event type you are subscribing to. Be sure to include the required details.

If your business would like to receive information from more than one event type, you'll repeat this step for each individual subscription.

3. Test Your Subscription

Midigator will send out an initial test /ping for each new subscription. You may also choose to test your registered URLs by manually triggering a /ping at any time.

4. Update Your Subscription

Any time your webhook information changes, you’ll want to update the subscription event with Midigator. Examples of such situations are: your webhook URL changes, your e-mail changes, or you wish to deactive (or re-activate) a particular subscription.

API Endpoint
Production:https://api.midigator.com/events/v1
Sandbox:https://api-sandbox.midigator.com/events/v1
Contact: integrations@midigator.com
Schemes: https
Version: 0.6.0

Authentication

AuthorizationBearerToken

in
header
name
Authorization

Event Subscriptions

Midigator can notify you when certain events take place. To receive these notifications, you need to subscribe to the event. The following paths allow you to create and manage your subscriptions.

Add New Subscription

POST /subscribe

This API includes several different event types. If you want to receive information from Midigator, you need to subscribe to the events that are relevant to your business. Keep in mind, some events won’t be applicable.

For example, if you aren’t using Midigator’s prevention alert service, you don’t need to subscribe to the prevention.new event type. If your order management system or CRM isn’t integrated with Midigator, the chargeback.match and prevention.match event types won’t be relevant.

Use this path to add a new event subscription to your account.

See the subscribe schema definition below for more details.

Request Content-Types: application/json
Request Example
{
  "email": "jdoe@email.com",
  "url": "https://yourdomain.com/chargeback-new-hook",
  "event_type": "chargeback.new",
  "auth": {
    "username": "jdoe",
    "password": "my-password"
  }
}

Everything worked as expected. The response will include the details of your subscription.

400 Bad Request

The request was invalid, usually because of missing or invalid parameters or headers.

401 Unauthorized

An invalid authorization header was provided.

Response Content-Types: application/json
Response Example (200 OK)
{
  "guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "email": "jdoe@email.com",
  "url": "https://yourdomain.com/chargeback-new-hook",
  "event_type": "chargeback.new",
  "active": false,
  "created_at": "2019-09-27T20:42:43Z",
  "updated_at": "2019-10-15T08:12:31Z",
  "auth": {
    "username": "jdoe",
    "password": "my-password"
  }
}

List All Subscriptions

GET /subscribe

This path will return a list of all the events you are currently subscribed to and the information associated with each one. Use this to manage your account and either add, update, or delete subscriptions.

Everything worked as expected. The response will include the list of all your subscriptions.

400 Bad Request

The request was invalid, usually because of missing or invalid parameters or headers.

401 Unauthorized

An invalid authorization header was provided.

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
    "email": "jdoe@email.com",
    "url": "https://yourdomain.com/chargeback-new-hook",
    "event_type": "chargeback.new",
    "active": false,
    "created_at": "2019-09-27T20:42:43Z",
    "updated_at": "2019-10-15T08:12:31Z",
    "auth": {
      "username": "jdoe",
      "password": "my-password"
    }
  }
]

Subscription Confirmation

GET /subscribe/{event_guid}

This path will return all the information that Midigator has available for the specified subscription.

event_guid

The globally unique identifier (GUID) for the event subscription

type
string
in
path

Everything worked as expected. The response will include the details of your subscription.

400 Bad Request

The request was invalid, usually because of missing or invalid parameters or headers.

401 Unauthorized

An invalid authorization header was provided.

Response Content-Types: application/json
Response Example (200 OK)
{
  "guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "email": "jdoe@email.com",
  "url": "https://yourdomain.com/chargeback-new-hook",
  "event_type": "chargeback.new",
  "active": false,
  "created_at": "2019-09-27T20:42:43Z",
  "updated_at": "2019-10-15T08:12:31Z",
  "auth": {
    "username": "jdoe",
    "password": "my-password"
  }
}

Update Subscription

PUT /subscribe/{event_guid}

Use this path to update an event subscription any time your webhook information changes. Examples of such situations are your webhook URL changes, your email changes, or you want to deactivate (or re-activate) a subscription.

See the subscription_update schema definition below for more details.

event_guid

The globally unique identifier (GUID) for the event subscription

type
string
in
path
Request Content-Types: application/json
Request Example
{
  "email": "jdoe@email.com",
  "url": "https://yourdomain.com/chargeback-new-hook",
  "active": false,
  "auth": {
    "username": "jdoe",
    "password": "my-password"
  }
}

Everything worked as expected. The response will include the details of your updated subscription.

400 Bad Request

The request was invalid, usually because of missing or invalid parameters or headers.

401 Unauthorized

An invalid authorization header was provided.

418

An invalid update parameter was provided. Please use DELETE /subscribe/{event_guid} to change event_type.

Response Content-Types: application/json
Response Example (200 OK)
{
  "guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "email": "jdoe@email.com",
  "url": "https://yourdomain.com/chargeback-new-hook",
  "event_type": "chargeback.new",
  "active": false,
  "created_at": "2019-09-27T20:42:43Z",
  "updated_at": "2019-10-15T08:12:31Z",
  "auth": {
    "username": "jdoe",
    "password": "my-password"
  }
}

Delete Subscription

DELETE /subscribe/{event_guid}

Use this path to delete an event subscription. You may want to delete a subscription if you change services or upgrade your integration with Midigator.

event_guid

The globally unique identifier (GUID) for the event subscription

type
string
in
path
200 OK

Everything worked as expected. Your subscription was successfully deleted.

400 Bad Request

The request was invalid, usually because of missing or invalid parameters or headers.

401 Unauthorized

An invalid authorization header was provided.

Test Subscription

GET /ping/{event_type}

Midigator will send out an initial test /ping for each new subscription. You may also choose to test your registered URLs by manually triggering a /ping at any time.

event_type

The event type you want to test

type
string , x ∈ { chargeback.new , prevention.new , chargeback.match , prevention.match , order.refund }
in
path
200 OK

Everything worked as expected. The response will include a listing of URLs that will be pinged.

400 Bad Request

The request was invalid, usually because of missing or invalid parameters or headers.

401 Unauthorized

An invalid authorization header was provided.

Response Example (200 OK)
{
  "urls": [
    "https://yourdomain.com/chargeback-new-hook1",
    "https://yourdomain.com/chargeback-new-hook2",
    "..."
  ]
}

Event Callbacks

Midigator’s API includes five event types.

chargeback.new - Midigator received your chargeback.

prevention.new - Midigator recieved your prevention alert (Ethoca, Verifi, or VMPI).

chargeback.match - Midigator matched your chargeback to its original order.

prevention.match - Midigator matched your prevention alert to its original order.

order.refund - You need to refund an order that's received a prevention alert.

When one of these events occur, Midigator will notify you with the corresponding call.

New Chargeback

POST /your-domain.com/chargeback-new-event

This callback sends information to your registered URL every time Midigator receives a new chargeback.

See the chargeback.new schema definition below for more details.

Request Example
{
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "event_type": "chargeback.new",
  "mid": "189250002",
  "arn": "99992989193702154389999",
  "case_number": "27873223854042",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "card_brand": "visa",
  "amount": 10.04,
  "chargeback_date": "2019-09-27",
  "event_timestamp": "2019-09-27T20:42:43Z"
}
200 OK

Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.

New Prevention Alert

POST /your-domain.com/prevention-new-event

This callback sends information to your registered URL every time Midigator receives a new prevention alert (Ethoca, Verifi, VMPI).

See the prevention.new schema definition below for more details.

Request Example
{
  "prevention_guid": "pre_abcdefdea06e48af9b46c1f5160784c3",
  "event_type": "prevention.new",
  "partner": "ethoca",
  "mid": "189250002",
  "arn": "99992989193702154389999",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "amount": 10.04,
  "event_timestamp": "2019-09-27T20:42:43Z"
}
200 OK

Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.

Chargeback Matched

POST /your-domain.com/chargeback-match-event

This callback sends information to your registered URL every time Midigator matches a chargeback to its original order.

See the chargeback.match schema definition below for more details.

Request Example
{
  "event_type": "chargeback.match",
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "event_timestamp": "2019-09-27T20:42:43Z"
}
200 OK

Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.

Prevention Alert Matched

POST /your-domain.com/prevention-match-event

This callback sends information to your registered URL every time Midigator matches a prevention alert to its original order.

See the prevention.match schema definition below for more details.

Request Example
{
  "event_type": "prevention.match",
  "prevention_guid": "pre_abcdefdea06e48af9b46c1f5160784c3",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "event_timestamp": "2019-09-27T20:42:43Z"
}
200 OK

Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.

Order Refund

POST /your-domain.com/order-refund-event

This callback sends information to your registered URL every time there is an order that needs to be refunded. This happens when you receive a prevention alert.

See the order.refund schema definition below for more details.

Request Example
{
  "event_type": "order.refund",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "amount": 10.04,
  "event_timestamp": "2019-09-27T20:42:43Z"
}
200 OK

Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.

Event Data

After an event takes place, you have the option to request additional information from Midigator. The following paths are available to get more information.

Get Chargeback Data

GET /chargeback/{chargeback_guid}

After a chargeback.new event takes place, you might want to receive additional information about the chargeback. The information that Midigator has available may help you create your chargeback response and prevent other disputes in the future.

chargeback_guid

The globally unique identifier (GUID) for the chargeback

type
string
in
path
200 OK

Everything worked as expected. The response will include your chargeback data.

400 Bad Request

The request was invalid, usually because of missing or invalid parameters or headers.

401 Unauthorized

An invalid authorization header was provided.

404 Not Found

The data entity was not found.

Response Content-Types: application/json
Response Example (200 OK)
{
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "case_number": "27873223854042",
  "mid": "189250002",
  "arn": "99992989193702154389999",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "card_brand": "visa",
  "amount": 10.04,
  "currency": "USD",
  "chargeback_date": "2019-09-27",
  "matched_order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "matched_order_id": "abcdef123"
}

Get Prevention Data

GET /prevention/{prevention_guid}

After a prevention.new event takes place, you might want to receive additional information about the prevention alert. The information that Midigator has available may help you prevent other disputes in the future.

prevention_guid

The globally unique identifier (GUID) for the prevention alert

type
string
in
path
200 OK

Everything worked as expected. The response will include your prevention data.

400 Bad Request

The request was invalid, usually because of missing or invalid parameters or headers.

401 Unauthorized

An invalid authorization header was provided.

404 Not Found

The data entity was not found.

Response Content-Types: application/json
Response Example (200 OK)
{
  "prevention_guid": "pre_abcdefdea06e48af9b46c1f5160784c3",
  "prevention_case_number": "98453223854042",
  "partner": "ethoca",
  "mid": "189250002",
  "arn": "99992989193702154389999",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "card_brand": "visa",
  "amount": 10.04,
  "currency": "USD",
  "prevention_timestamp": "2019-09-27T20:42:43Z",
  "matched_order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "matched_order_id": "abcdef123"
}

Get Order Data

GET /order/{order_guid}

After a chargeback.match event takes place, you might want to receive additional information about the order associated with the chargeback. The information that Midigator has available may help you create your chargeback response and prevent other disputes in the future.

order_guid

The globally unique identifier (GUID) for the order

type
string
in
path
200 OK

Everything worked as expected. The response will include your order data.

400 Bad Request

The request was invalid, usually because of missing or invalid parameters or headers.

401 Unauthorized

An invalid authorization header was provided.

404 Not Found

The data entity was not found.

Response Content-Types: application/json
Response Example (200 OK)
{
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "crm_order_id": "abcdef123",
  "mid": "189250002",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "card_brand": "visa",
  "amount": 10.04,
  "currency": "USD",
  "billing_first_name": "Jane",
  "billing_last_name": "Doe",
  "order_date": "2019-09-27T13:15:47Z"
}

Schema Definitions

auth: object

The auth object is used to authenticate the URL you'd like to use to receive Midigator events. It consists of Basic Auth parameters. Midigator currently only supports Basic Auth authentication when pushing events to webhook URLs.

username: string

The username field is the username that will be used to authenticate your webhook URL.

password: string

The password field is the password that will be used to authenticate your webhook URL.

Example
{
  "username": "jdoe",
  "password": "my-password"
}

subscribe: object

The subscribe object is used to subscribe to one or more of Midigator’s events. It includes information about the type of event you are subscribing to and where you would like the information sent.

email: string

The email field should include a valid email address. This is where Midigator will send notices, error messages, and subscription changes.

url: string

The URL field is the URL where you would like Midigator to send events. We send events in JSON, so make sure your URL is able to handle this format.

event_type: string , x ∈ { chargeback.new , prevention.new , chargeback.match , prevention.match , order.refund }

The event_type field is an explanation of which event type you would like a subscription to.

auth: auth
Example
{
  "email": "jdoe@email.com",
  "url": "https://yourdomain.com/chargeback-new-hook",
  "event_type": "chargeback.new",
  "auth": {
    "username": "jdoe",
    "password": "my-password"
  }
}

subscription_confirmation: object

The subscription_confirmation object contains information about a subscription after it has been successfully created.

guid: string

The guid field contains the unique identifier that has been assigned to the subscription. This field is used to retrieve information with the GET subscribe/{guid} call.

email: string (email)

The email field is the email address associated with the subscription.

url: string (url)

The URL field is the URL that was specified during the initial subscription setup.

event_type: string , x ∈ { chargeback.new , chargeback.match , prevention.new , prevention.match , order.refund }

The event_type field indicates which event type is associated with this subscription.

active: boolean

The active field indicates whether or not the subscription is currently active. If active is set to true, events will be pushed to the registered URL. If active is set to false, this subscription will be skipped.

created_at: string (date-time)

The created_at field indicates the date and time the subscription was created. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format.

updated_at: string (date-time)

The updated_at field indicates the date and time the subscription was last updated. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format.

auth: auth
Example
{
  "guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "email": "jdoe@email.com",
  "url": "https://yourdomain.com/chargeback-new-hook",
  "event_type": "chargeback.new",
  "active": false,
  "created_at": "2019-09-27T20:42:43Z",
  "updated_at": "2019-10-15T08:12:31Z",
  "auth": {
    "username": "jdoe",
    "password": "my-password"
  }
}

subscription_update: object

The subscription_update object contains subscription information that has been updated or changed. Updates should happen when webhook URLs change, when emails change, or when subscriptions need to be activated or deactivated.

email: string (email)

The email field is the email address associated with the subscription.

url: string (url)

The URL field is the URL that is associated with the subscription.

active: boolean

The active field indicates whether or not the subscription is currently active. If active is set to true, events will be pushed to the registered URL. If active is set to false, this subscription will be skipped.

auth: auth
Example
{
  "email": "jdoe@email.com",
  "url": "https://yourdomain.com/chargeback-new-hook",
  "active": false,
  "auth": {
    "username": "jdoe",
    "password": "my-password"
  }
}

ping_response: object

The ping_response object provides the information requested with a GET /ping/{event_type} call.

urls: string[]

The URLs field contains the webhook URLs that were tested.

Example
{
  "urls": [
    "https://yourdomain.com/chargeback-new-hook1",
    "https://yourdomain.com/chargeback-new-hook2",
    "..."
  ]
}

chargeback.new: object

This payload will be sent to your registered URL when a Midigator chargeback.new event occurs.

chargeback_guid: string

The chargeback_guid field contains the globally unique identifier that Midigator assigned to this chargeback.

event_type: string

The event_type field indicates which event type is associated with this subscription.

mid: string

The mid field identifies the merchant account used to process the order associated with this chargeback. 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.

arn: string

The arn field contains the acquirer reference number associated with this chargeback (if available).

case_number: string

The case_number field contains a unique ID the payment processor assigns to each chargeback. Sometimes the case_number is the same as the arn. Most often, it is a number that exists only within the payment processor’s system.

card_first_6: string

The card_first_6 field is the first six digits of the payment card number used to process the order associated with this chargeback. Please note, this information isn't always shared with Midigator.

card_last_4: string

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

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.

amount: number

The amount field contains the amount of the chargeback.

chargeback_date: string (date)

The chargeback_date field is the date the chargeback was received. The default is to use the date your acquiring bank provides. If the bank doesn’t provide a date, this field will list the date Midigator received the chargeback. It will be expressed in ISO 8601 (YYYY-MM-DD) format. For example, "2019-09-27".

event_timestamp: string (date-time)

The event_timestamp field shares the date and time the event was sent. It is expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format.

Example
{
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "event_type": "chargeback.new",
  "mid": "189250002",
  "arn": "99992989193702154389999",
  "case_number": "27873223854042",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "card_brand": "visa",
  "amount": 10.04,
  "chargeback_date": "2019-09-27",
  "event_timestamp": "2019-09-27T20:42:43Z"
}

prevention.new: object

This payload will be sent to your registered URL when a Midigator prevention.new event occurs.

prevention_guid: string

The prevention_guid field contains the globally unique identifier that Midigator assigned to this prevention alert.

event_type: string

The event_type field indicates which event type is associated with this subscription.

partner: string , x ∈ { ethoca , verifi , tc40 , vmpi }

The partner field contains the name of the prevention alert vendor that sent the alert.

mid: string

The mid field identifies the merchant account used to process the order associated with this prevention alert. 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

arn: string

The arn field contains the acquirer reference number associated with this prevention alert (if available).

card_first_6: string

The card_first_6 field is the first six digits of the payment card number used to process the order associated with this prevention alert. Please note, this information isn't always shared with Midigator.

card_last_4: string

The card_last_4 field is the last four digits of the payment card number used to process the order associated with this prevention alert.

amount: number

The amount field contains the amount of the prevention alert.

event_timestamp: string (date-time)

The event_timestamp field shares the date and time the event was sent. It is expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format.

Example
{
  "prevention_guid": "pre_abcdefdea06e48af9b46c1f5160784c3",
  "event_type": "prevention.new",
  "partner": "ethoca",
  "mid": "189250002",
  "arn": "99992989193702154389999",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "amount": 10.04,
  "event_timestamp": "2019-09-27T20:42:43Z"
}

chargeback.match: object

This payload will be sent to your registered URL when a Midigator chargeback.match event occurs.

event_type: string

The event_type field indicates which event type is associated with this subscription.

chargeback_guid: string

The chargeback_guid field contains the globally unique identifier that Midigator assigned to this chargeback.

order_guid: string

The order_guid field contains the globally unique identifier that Midigator assigned to the order associated with the chargeback.

order_id: string

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

event_timestamp: string (date-time)

The event_timestamp field shares the date and time the event was sent. It is expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format.

Example
{
  "event_type": "chargeback.match",
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "event_timestamp": "2019-09-27T20:42:43Z"
}

prevention.match: object

This payload will be sent to your registered URL when a Midigator prevention.match event occurs.

event_type: string

The event_type field indicates which event type is associated with this subscription.

prevention_guid: string

The prevention_guid field contains the globally unique identifier that Midigator assigned to this prevention alert.

order_guid: string

The order_guid field contains the globally unique identifier that Midigator assigned to the order associated with this prevention alert.

order_id: string

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

event_timestamp: string (date-time)

The event_timestamp field shares the date and time the event was sent. It is expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format.

Example
{
  "event_type": "prevention.match",
  "prevention_guid": "pre_abcdefdea06e48af9b46c1f5160784c3",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "event_timestamp": "2019-09-27T20:42:43Z"
}

order.refund: object

This payload will be sent to your registered URL when a Midigator order.refund event occurs.

event_type: string

The event_type field indicates which event type is associated with this subscription.

order_guid: string

The order_guid field contains the globally unique identifier that Midigator assigned to the order.

order_id: string

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

amount: number

The amount field is the total order amount that was charged to the customer's card. If applicable, this amount will also include shipping and tax.

event_timestamp: string (date-time)

The event_timestamp field shares the date and time the event was sent. It is expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format.

Example
{
  "event_type": "order.refund",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "amount": 10.04,
  "event_timestamp": "2019-09-27T20:42:43Z"
}

chargeback: object

This payload is returned from GET /chargeback/{chargeback_guid} requests. It contains all the information Midigator has about the chargeback.

chargeback_guid: string

The chargeback_guid field contains the globally unique identifier that Midigator assigned to this chargeback.

case_number: string

The case_number field contains a unique ID the payment processor assigns to each chargeback. Sometimes the case_number is the same as the arn. Most often, it is a number that exists only within the payment processor’s system.

mid: string

The mid field identifies the merchant account used to process the order associated with this chargeback. 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.

arn: string

The arn field contains the acquirer reference number associated with this chargeback (if available).

card_first_6: string

The card_first_6 field is the first six digits of the payment card number used to process the order associated with this chargeback. Please note, this information isn't always shared with Midigator.

card_last_4: string

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

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.

amount: number

The amount field is the amount of the chargeback.

currency: string

The currency field is the currency of the chargeback amount. If this information is not passed to Midigator, USD will be used by default. This field value is the three-character ISO 4217 code.

chargeback_date: string (date)

The chargeback_date field is the date the chargeback was received. The default is to use the date your acquiring bank provides. If the bank doesn’t provide a date, this field will list the date Midigator received the chargeback. It will be expressed in ISO 8601 (YYYY-MM-DD) format. For example, "2019-09-27".

matched_order_guid: string

The matched_order_guid field contains the globally unique identifier that Midigator assigned to the order.

matched_order_id: string

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

Example
{
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "case_number": "27873223854042",
  "mid": "189250002",
  "arn": "99992989193702154389999",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "card_brand": "visa",
  "amount": 10.04,
  "currency": "USD",
  "chargeback_date": "2019-09-27",
  "matched_order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "matched_order_id": "abcdef123"
}

prevention: object

This payload is returned from GET /prevention/{prevention_guid} requests. It contains all the information Midigator has about the prevention alert.

prevention_guid: string

The prevention_guid field contains the globally unique identifier that Midigator assigned to this prevention alert.

prevention_case_number: string

The prevention_case_number is the unique identifier that the prevention alert vendor assigned to the alert. Depending on the prevention alert vendor, this is sometimes the same as the arn field.

partner: string , x ∈ { ethoca , verifi , tc40 , vmpi }

The partner field contains the name of the prevention alert vendor that sent the alert.

mid: string

The mid field identifies the merchant account used to process the order associated with this prevention alert. 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.

arn: string

The arn field contains the acquirer reference number associated with this prevention alert (if available).

card_first_6: string

The card_first_6 field is the first six digits of the payment card number used to process the order associated with this prevention alert. Please note, this information isn't always shared with Midigator.

card_last_4: string

The card_last_4 field is the last four digits of the payment card number used to process the order associated with this prevention alert.

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.

amount: number

The amount field contains the amount of the prevention alert.

currency: string

The currency field is the currency of the pervention alert amount. If this information is not passed to Midigator, USD will be used by default. This field value is the three-character ISO 4217 code.

prevention_timestamp: string (date-time)

The prevention_timestamp field is the date and time the prevention alert was issued. The default is to use the date and time the alert vendor reports. If the vendor doesn’t provide a timestamp, this field will list the date and time that Midigator received the prevention alert. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, "2019-09-27T20:42:43Z".

matched_order_guid: string

The matched_order_guid field contains the globally unique identifier that Midigator assigned to the order.

matched_order_id: string

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

Example
{
  "prevention_guid": "pre_abcdefdea06e48af9b46c1f5160784c3",
  "prevention_case_number": "98453223854042",
  "partner": "ethoca",
  "mid": "189250002",
  "arn": "99992989193702154389999",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "card_brand": "visa",
  "amount": 10.04,
  "currency": "USD",
  "prevention_timestamp": "2019-09-27T20:42:43Z",
  "matched_order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "matched_order_id": "abcdef123"
}

order: object

This payload is returned from GET /order/{order_guid} requests. It contains all the information Midigator has available for the order.

order_guid: string

The order_guid field contains the globally unique identifier that Midigator assigned to this order.

crm_order_id: string

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

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_first_6: string

The card_first_6 field is the first six digits of the payment card number used to process the order. Please note, this information isn't always shared with Midigator.

card_last_4: string

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

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.

amount: number

The amount field is the total order amount that was charged to the customer's card. If applicable, this amount will also include shipping and tax.

currency: string

The currency field is the currency of the amount field. If this information is not passed to Midigator, USD will be used by default. This field value is the three-character ISO 4217 code.

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.

order_date: string (date)

The order_date field is the date and time that the customer's bank approved (or authorized) the order. It will be expressed in the UTC date-time format as specified in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). For example, "2019-09-27T13:15:47Z".

Example
{
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "crm_order_id": "abcdef123",
  "mid": "189250002",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "card_brand": "visa",
  "amount": 10.04,
  "currency": "USD",
  "billing_first_name": "Jane",
  "billing_last_name": "Doe",
  "order_date": "2019-09-27T13:15:47Z"
}