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 or order management system; 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 sent when Midigator receives your chargeback.

Chargeback Matched to Order

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

Chargeback Result

A chargeback.result event is sent when a chargeback result (win, loss, pre-arb) changes.

Chargeback DNF

A chargeback.dnf event is sent when a chargeback is marked as Do Not Fight.

New Order Validation

An order_validation.new event is sent when Midigator receives your order validation request from Order Insight or Consumer Clarity.

Order Validation Matched to Order

An order_validation.match event is sent when Midigator matches your order validation request to its original order.

New Prevention Alert

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

Prevention Alert Matched to Order

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

New RDR Alert

A rdr.new event is sent when Midigator receives a new Rapid Dispute Resolution (RDR) alert.

New Subscription Registration

A registration.new event is sent when you subscribe to any of the above Midigator events.

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 email changes, or you wish to deactivate (or re-activate) a particular subscription.

Base URL
Production:https://api.midigator.com/events/v1
Sandbox:https://api-sandbox.midigator.com/events/v1
Contact: integrations@midigator.com
Schemes: https
Version: 0.8.15

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.

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

NOTE: When you initially create a subscription, the value of "active" is set to false. "active" will be set to true once the webhook is tested (via the vetting check detailed below) and confirmed working. If the vetting check process fails, the subscription will remain false, and the only way to resolve this is to delete the failing subscription and create a new one.

The process for the subscription vetting check is as follows:

  1. When a new subscription is created, the Events API sends a registration.new payload to your webhook.
  2. If your webhook sends back any HTTP status under 400 (e.g. HTTP 200), then the webhook is validated and the event subscription is activated.
  3. If your webhook sends back a status of 400 or greater, then a second test is performed using the HTTP OPTIONS method. If this test returns an HTTP status under 400, the webhook is validated and the event subscription is is activated.

  4. If both of the validation tests fail (return an HTTP status of 400 of greater) then the event subscription will remain inactive.

  5. If the vetting check succeeds, a status email will be sent to the email address associated with the subscription.

  6. If the vetting check fails, Midigator will automatically try the activation process 8 more times over the following 24 hour period.
  7. Every time a vetting check fails, a failure status email will be sent to the email address associated with the subscription.
subscribe

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"
  }
}
200 OK
subscription_confirmation

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"
  }
}
Event Subscriptions

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.

200 OK
subscription_confirmation

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"
    }
  }
]
Event Subscriptions

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
200 OK
subscription_confirmation

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"
  }
}
Event Subscriptions

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.

subscription_update

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"
  }
}
200 OK
subscription_confirmation

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"
  }
}
Event Subscriptions

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.

Event Subscriptions

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 , chargeback.result , chargeback.dnf , prevention.new , order_validation.new , chargeback.match , prevention.match , order_validation.match , rdr.new }
in
path
200 OK
ping_response

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 ten event types.

chargeback.new - Midigator received your chargeback.

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

rdr.new - Midigator received your Rapid Dispute Resolution (RDR) alert.

order_validation.new - Midigator received your order validation request from Order Insight or Consumer Clarity.

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

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

order_validation.match - Midigator matched your order validation request to its original order.

chargeback.result - Midigator signals when a chargeback result (win, loss, pre-arb) changes.

chargeback.dnf - Midigator signals when a chargeback was marked as do not fight.

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

Event Callbacks

New Chargeback

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

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

chargeback.new

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

Request Example
{
  "alternate_transaction_id": "order1234",
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "auth_code": "741256",
  "card_brand": "visa",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "case_number": "27873223854042",
  "chargeback_date": "2019-09-27",
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "currency": "USD",
  "date_received": "2019-09-27",
  "due_date": "2019-09-27",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_type": "chargeback.new",
  "mid": "189250002",
  "processor_transaction_date": "2019-09-30T09:20:11Z",
  "processor_transaction_id": "NMI0983",
  "reason_code": "10.4",
  "reason_description": "Other Fraud: Card-Absent Environment"
}
200 OK

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

Event Callbacks

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.

chargeback.match

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

Request Example
{
  "alternate_transaction_id": "order1234",
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "auth_code": "741256",
  "card_brand": "visa",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "case_number": "27873223854042",
  "chargeback_date": "2019-09-27",
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "crm_account_guid": "crm_2ec227c00d8c11eb82e3e2adcbae8b42",
  "currency": "USD",
  "date_received": "2019-09-27",
  "due_date": "2019-09-27",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_type": "chargeback.match",
  "mid": "189250002",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "processor_transaction_date": "2019-09-30T09:20:11Z",
  "processor_transaction_id": "NMI0983",
  "reason_code": "10.4",
  "reason_description": "Other Fraud: Card-Absent Environment"
}
200 OK

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

Event Callbacks

Chargeback Result

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

This callback sends information to your registered URL every time Midigator signals when a representment was delivered.

chargeback.result

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

Request Example
{
  "arn": "99992989193702154389999",
  "case_number": "27873223854042",
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_type": "chargeback.result",
  "mid": "189250002",
  "result": "won"
}
200 OK

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

Event Callbacks

Chargeback DNF

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

This callback sends information to your registered URL every time Midigator signals when a chargeback was marked as do not fight.

chargeback.dnf

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

Request Example
{
  "arn": "99992989193702154389999",
  "case_number": "27873223854042",
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "dnf_reason": "not_cost_effective",
  "dnf_timestamp": "2019-09-27T20:42:43Z",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_type": "chargeback.dnf",
  "mid": "189250002"
}
200 OK

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

Event Callbacks

New Order Validation

POST /your-domain.com/order-validation-new-event

This callback sends information to your registered URL every time Midigator receives an order validation request.

order_validation.new

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

Request Example
{
  "order_validation_type": "order_insight",
  "order_validation_timestamp": "2020-10-17T12:32:33Z",
  "order_validation_guid": "ov_d8cb61dea06e48af9b46c1f5160784c3",
  "transaction_timestamp": "2020-09-27T20:42:43Z",
  "amount": "10.04",
  "currency": "USD",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "arn": "99992989193702154389999",
  "auth_code": "abc123",
  "card_brand": "visa",
  "event_guid": "evr_1e3147abd961497c9ce34d1c0b0e63c9",
  "event_timestamp": "2020-09-27T20:42:43Z",
  "event_type": "order_validation.new"
}
200 OK

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

Event Callbacks

Order Validation Matched

POST /your-domain.com/order-validation-match-event

This callback sends information to your registered URL every time Midigator matches an order validation request to its original order.

order_validation.match

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

Request Example
{
  "order_validation_type": "consumer_clarity",
  "order_validation_timestamp": "2020-10-17T12:32:33Z",
  "order_validation_guid": "ov_xyzdefdea06e48af9b46c1f5160784c3",
  "transaction_timestamp": "2020-09-27T20:42:43Z",
  "amount": "10.04",
  "currency": "USD",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "arn": "99992989193702154389999",
  "auth_code": "abc123",
  "card_brand": "visa",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "crm_account_guid": "crm_2ec227c00d8c11eb82e3e2adcbae8b42",
  "mid": "189250002",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_timestamp": "2020-09-27T20:42:43Z",
  "event_type": "order_validation.match"
}
200 OK

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

Event Callbacks

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

prevention.new

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

Request Example
{
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "currency": "USD",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_type": "prevention.new",
  "merchant_descriptor": "Merchant Descriptor",
  "mid": "189250002",
  "prevention_case_number": "98453223854042",
  "prevention_guid": "pre_abcdefdea06e48af9b46c1f5160784c3",
  "prevention_timestamp": "2019-09-27T20:42:43Z",
  "prevention_type": "ethoca",
  "transaction_timestamp": "2019-05-15T19:00:02Z"
}
200 OK

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

Event Callbacks

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.

prevention.match

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

Request Example
{
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "crm_account_guid": "crm_2ec227c00d8c11eb82e3e2adcbae8b42",
  "currency": "USD",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_type": "prevention.match",
  "merchant_descriptor": "Merchant Descriptor",
  "mid": "189250002",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "prevention_case_number": "98453223854042",
  "prevention_guid": "pre_abcdefdea06e48af9b46c1f5160784c3",
  "prevention_timestamp": "2019-09-27T20:42:43Z",
  "prevention_type": "ethoca",
  "transaction_timestamp": "2019-09-25T21:12:23Z"
}
200 OK

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

Event Callbacks

New RDR Alert

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

This callback sends information to your registered URL every time Midigator receives a new Rapid Dispute Resolution (RDR) alert.

rdr.new

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

Request Example
{
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "auth_code": "123456",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "currency": "USD",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_type": "rdr.new",
  "merchant_descriptor": "Merchant Descriptor",
  "rdr_case_number": "123456789",
  "rdr_guid": "rdr_abcdefdea06e48af9b46c1f5160784c3",
  "rdr_date": "2019-09-27",
  "rdr_resolution": "Accepted",
  "prevention_type": "rdr",
  "transaction_date": "2019-05-15"
}
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.

Event Data

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
chargeback

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) 
{
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "card_brand": "visa",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "case_number": "27873223854042",
  "chargeback_date": "2019-09-27",
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "currency": "USD",
  "date_received": "2019-09-27",
  "mid": "189250002",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "reason_code": "10.4"
}
Event Data

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
prevention

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) 
{
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "card_brand": "visa",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "currency": "USD",
  "merchant_descriptor": "Merchant Descriptor",
  "mid": "189250002",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "prevention_case_number": "98453223854042",
  "prevention_guid": "pre_abcdefdea06e48af9b46c1f5160784c3",
  "prevention_timestamp": "2019-09-27T20:42:43Z",
  "prevention_type": "ethoca",
  "transaction_timestamp": "2019-09-25T21:12:23Z"
}
Event Data

Get Order Validation Data

GET /order_validation/{order_validation_guid}

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

order_validation_guid

The globally unique identifier (GUID) for the order validation request

type
string
in
path
200 OK
order_validation

Everything worked as expected. The response will include your order validation 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_validation_type": "order_insight",
  "order_validation_timestamp": "2020-10-17T12:32:33Z",
  "order_validation_guid": "ov_xyzdefdea06e48af9b46c1f5160784c3",
  "transaction_timestamp": "2020-09-27T20:42:43Z",
  "amount": "10.04",
  "currency": "USD",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "arn": "99992989193702154389999",
  "auth_code": "abc123",
  "card_brand": "visa",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "crm_account_guid": "crm_2ec227c00d8c11eb82e3e2adcbae8b42",
  "mid": "189250002"
}
Event Data

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
order

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"
}

chargeback: object

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

amount: number

The amount field is the amount of the chargeback.

arn: string

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

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

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.

chargeback_date: string (date)

The chargeback_date field is the date the issuing bank filed the chargeback. If the bank doesn’t provide a date, this field will list the date_received value. It will be expressed in ISO 8601 (YYYY-MM-DD) format. For example, "2019-09-27".

chargeback_guid: string

The chargeback_guid field contains the globally unique identifier that Midigator assigned to this 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.

date_received: string (date)

The date_received field is the date the chargeback was received by the acquiring bank. It will be expressed in ISO 8601 (YYYY-MM-DD) format. For example, "2019-09-27".

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.

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.

reason_code: string

The reason_code field lists the reason code the issuing bank has assigned to the chargeback. A reason code helps explain why a transaction was disputed. Reason codes differ by card brand (Visa, Mastercard); a complete list can be found here.

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

chargeback.new: object

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

alternate_transaction_id: string

The alternate_transaction_id is used for storing a processor-specific transaction ID (Vantiv, TSYS, Braintree, Amex)

amount: number

The amount field is the amount of the chargeback.

arn: string

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

auth_code: string

The auth_code field contains the authorization code that was provided by the issuer during authorization of the transaction.

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

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.

chargeback_date: string (date)

The chargeback_date field is the date the issuing bank filed the chargeback. If the bank doesn’t provide a date, this field will list the date_received value. It will be expressed in ISO 8601 (YYYY-MM-DD) format. For example, "2019-09-27".

chargeback_guid: string

The chargeback_guid field contains the globally unique identifier that Midigator assigned to this 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.

date_received: string (date)

The date_received field is the date the chargeback was received by the acquiring bank. It will be expressed in ISO 8601 (YYYY-MM-DD) format. For example, "2019-09-27".

due_date: string (date)

The due_date field is the the date the representment document is due to the processor. It will be expressed in ISO 8601 (YYYY-MM-DD) format. For example, "2019-09-27".

event_guid: string

The event_guid field contains the globally unique identifier that Midigator assigned to this event registration.

event_timestamp: string (date-time)

The event_timestamp field is the date and time of the event. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2019-09-27T20:42:43Z. All timestamps are in UTC time.

event_type: string

The event_type field indicates which kind of event has taken place.

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.

processor_transaction_date: string

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

processor_transaction_id: string

The processor_transaction_id field is the unique ID the processor or gateway uses for the transaction.

reason_code: string

The reason_code field lists the reason code the issuing bank has assigned to the chargeback. A reason code helps explain why a transaction was disputed. Reason codes differ by card brand (Visa, Mastercard); a complete list can be found here.

reason_description: string

The reason_description field lists the chargeback reason code description issuing bank has assigned to the chargeback. (See reason_code above)

Example
{
  "alternate_transaction_id": "order1234",
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "auth_code": "741256",
  "card_brand": "visa",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "case_number": "27873223854042",
  "chargeback_date": "2019-09-27",
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "currency": "USD",
  "date_received": "2019-09-27",
  "due_date": "2019-09-27",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_type": "chargeback.new",
  "mid": "189250002",
  "processor_transaction_date": "2019-09-30T09:20:11Z",
  "processor_transaction_id": "NMI0983",
  "reason_code": "10.4",
  "reason_description": "Other Fraud: Card-Absent Environment"
}

chargeback.match: object

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

alternate_transaction_id: string

The alternate_transaction_id is used for storing a processor-specific transaction ID (Vantiv, TSYS, Braintree, Amex)

amount: number

The amount field is the amount of the chargeback.

arn: string

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

auth_code: string

The auth_code field contains the authorization code that was provided by the issuer during authorization of the transaction.

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

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.

chargeback_date: string (date)

The chargeback_date field is the date the issuing bank filed the chargeback. If the bank doesn’t provide a date, this field will list the date_received value. It will be expressed in ISO 8601 (YYYY-MM-DD) format. For example, "2019-09-27".

chargeback_guid: string

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

crm_account_guid: string

The crm_account_guid field contains the unique identifier assigned to the CRM or order management system used to process the transaction. This field is helpful when you have multiple CRMs.

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.

date_received: string (date)

The date_received field is the date the chargeback was received by the acquiring bank. It will be expressed in ISO 8601 (YYYY-MM-DD) format. For example, "2019-09-27".

due_date: string (date)

The due_date field is the the date the representment document is due to the processor. It will be expressed in ISO 8601 (YYYY-MM-DD) format. For example, "2019-09-27".

event_guid: string

The event_guid field contains the globally unique identifier that MMidigator assigned to this event registration.

event_timestamp: string (date-time)

The event_timestamp field is the date and time of the event. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2019-09-27T20:42:43Z. All timestamps are in UTC time.

event_type: string

The event_type field indicates which kind of event has taken place.

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.

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.

processor_transaction_date: string

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

processor_transaction_id: string

The processor_transaction_id field is the unique ID the processor or gateway uses for the transaction.

reason_code: string

The reason_code field lists the reason code the issuing bank has assigned to the chargeback. A reason code helps explain why a transaction was disputed. Reason codes differ by card brand (Visa, Mastercard); a complete list can be found here.

reason_description: string

The reason_description field lists the chargeback reason code description issuing bank has assigned to the chargeback. (See reason_code above)

Example
{
  "alternate_transaction_id": "order1234",
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "auth_code": "741256",
  "card_brand": "visa",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "case_number": "27873223854042",
  "chargeback_date": "2019-09-27",
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "crm_account_guid": "crm_2ec227c00d8c11eb82e3e2adcbae8b42",
  "currency": "USD",
  "date_received": "2019-09-27",
  "due_date": "2019-09-27",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_type": "chargeback.match",
  "mid": "189250002",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "processor_transaction_date": "2019-09-30T09:20:11Z",
  "processor_transaction_id": "NMI0983",
  "reason_code": "10.4",
  "reason_description": "Other Fraud: Card-Absent Environment"
}

chargeback.result: object

*

This payload will be sent to your registered URL when a Midigator chargeback.result event occurs, which indicates when a representment result (won, lost, pre-arbitration) was obtained.

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.

chargeback_guid: string

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

event_timestamp: string (date-time)

The event_timestamp field is the date and time of the event, expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2019-09-27T20:42:43Z. All timestamps are in UTC time.

event_guid: string

The event_guid field contains the globally unique identifier that Midigator assigned to this event registration.

event_type: string

The event_type field indicates a chargeback.responded event has taken place.

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.

result: string

The current result of the chargeback case.

Allowed values for result

  • won

  • lost

  • pre-arbitration

Example
{
  "arn": "99992989193702154389999",
  "case_number": "27873223854042",
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_type": "chargeback.result",
  "mid": "189250002",
  "result": "won"
}

chargeback.dnf: object

*

This payload will be sent to your registered URL when a Midigator chargeback.dnf event occurs, when a chargeback was marked as do not fight.

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.

chargeback_guid: string

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

dnf_reason: string

The reason that was selected for not fighting the CB (standard reasons or free form description of the other values)

dnf_timestamp: string (date-time)

The time the chargeback case was closed and marked as not fought, expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2019-09-27T20:42:43Z. All timestamps are in UTC time.

event_timestamp: string (date-time)

The event_timestamp field is the date and time of the event, expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2019-09-27T20:42:43Z. All timestamps are in UTC time.

event_guid: string

The event_guid field contains the globally unique identifier that Midigator assigned to this event registration.

event_type: string

The event_type field indicates a chargeback.responded event has taken place.

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.

Example
{
  "arn": "99992989193702154389999",
  "case_number": "27873223854042",
  "chargeback_guid": "cbc_xyzdefdea06e48af9b46c1f5160784c3",
  "dnf_reason": "not_cost_effective",
  "dnf_timestamp": "2019-09-27T20:42:43Z",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_type": "chargeback.dnf",
  "mid": "189250002"
}

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"
}

order_validation: object

This payload is returned from GET /order_validation/{order_guid} requests. It contains all the information Midigator has about the order validation request.

order_validation_type: string

The order_validation_type contains the name of the vendor that sent the order validation request.

order_validation_timestamp: string (date-time)

The order_validation_timestamp field is the date and time the order validation request was issued. The default is to use the date and time the vendor reports. If the vendor doesn’t provide a timestamp, this field will list the date and time that Midigator received the order validation request. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, "2020-10-17T12:32:33Z". All timestamps are in UTC time.

order_validation_guid: string

The order_valiation_guid field contains the globally unique identifier that Midigator assigned to this order validation request.

transaction_timestamp: string

The transaction_timestamp field is the authorization or settlement date and time for the transaction associated with this order validation request. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2020-09-27T20:42:43Z. All timestamps are in UTC time.

amount: number

The amount field contains the amount of the order validation request.

currency: string

The currency field is the currency of the request 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.

card_first_6: number

The card_first_6 field is the first six digits of the payment card number used to process the order associated with this order validation request. 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 order validation request.

arn: string

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

auth_code: string

The auth_code field is the alphanumeric message that an issuer sends in response to a merchant’s authorization request at the time the transaction is initiated.

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.

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.

crm_account_guid: string

The crm_account_guid field contains the unique identifier assigned to the CRM or order management system used to process the transaction. This field is helpful when you have multiple CRMs.

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.

Example
{
  "order_validation_type": "order_insight",
  "order_validation_timestamp": "2020-10-17T12:32:33Z",
  "order_validation_guid": "ov_xyzdefdea06e48af9b46c1f5160784c3",
  "transaction_timestamp": "2020-09-27T20:42:43Z",
  "amount": "10.04",
  "currency": "USD",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "arn": "99992989193702154389999",
  "auth_code": "abc123",
  "card_brand": "visa",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "crm_account_guid": "crm_2ec227c00d8c11eb82e3e2adcbae8b42",
  "mid": "189250002"
}

order_validation.new: object

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

order_validation_type: string

The order_validation_type contains the name of the vendor that sent the order validation request.

order_validation_timestamp: string (date-time)

The order_validation_timestamp field is the date and time the order validation request was issued. The default is to use the date and time the vendor reports. If the vendor doesn’t provide a timestamp, this field will list the date and time that Midigator received the order validation request. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, "2020-10-17T12:32:33Z". All timestamps are in UTC time.

order_validation_guid: string

The order_valiation_guid field contains the globally unique identifier that Midigator assigned to this order validation request.

transaction_timestamp: string

The transaction_timestamp field is the authorization or settlement date and time for the transaction associated with this order validation request. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2020-09-27T20:42:43Z. All timestamps are in UTC time.

amount: number

The amount field contains the amount of the order validation request.

currency: string

The currency field is the currency of the order validation request 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.

card_first_6: number

The card_first_6 field is the first six digits of the payment card number used to process the order associated with this order validation request. 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 order validation request.

arn: string

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

auth_code: string

The auth_code field is the alphanumeric message that an issuer sends in response to a merchant’s authorization request at the time the transaction is initiated.

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.

event_guid: string

The event_guid field contains the globally unique identifier that Midigator assigned to this event registration.

event_timestamp: string (date-time)

The event_timestamp field is the date and time of the event. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2020-09-27T20:42:43Z. All timestamps are in UTC time.

event_type: string

The event_type field indicates which kind of event has taken place.

Example
{
  "order_validation_type": "order_insight",
  "order_validation_timestamp": "2020-10-17T12:32:33Z",
  "order_validation_guid": "ov_d8cb61dea06e48af9b46c1f5160784c3",
  "transaction_timestamp": "2020-09-27T20:42:43Z",
  "amount": "10.04",
  "currency": "USD",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "arn": "99992989193702154389999",
  "auth_code": "abc123",
  "card_brand": "visa",
  "event_guid": "evr_1e3147abd961497c9ce34d1c0b0e63c9",
  "event_timestamp": "2020-09-27T20:42:43Z",
  "event_type": "order_validation.new"
}

order_validation.match: object

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

order_validation_type: string

The order_validation_type contains the name of the vendor that sent the order validation request.

order_validation_timestamp: string (date-time)

The order_validation_timestamp field is the date and time the order validation request was issued. The default is to use the date and time the vendor reports. If the vendor doesn’t provide a timestamp, this field will list the date and time that Midigator received the order validation request. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, "2020-10-17T12:32:33Z". All timestamps are in UTC time.

order_validation_guid: string

The order_valiation_guid field contains the globally unique identifier that Midigator assigned to this order validation request.

transaction_timestamp: string

The transaction_timestamp field is the authorization or settlement date and time for the transaction associated with this order validation request. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2020-05-15T19:00:02Z. All timestamps are in UTC time.

amount: number

The amount field contains the amount of the order validation request.

currency: string

The currency field is the currency of the order validation request 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.

card_first_6: number

The card_first_6 field is the first six digits of the payment card number used to process the order associated with this order validation request. 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 order validation request.

arn: string

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

auth_code: string

The auth_code field is the alphanumeric message that an issuer sends in response to a merchant’s authorization request at the time the transaction is initiated.

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.

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.

crm_account_guid: string

The crm_account_guid field contains the unique identifier assigned to the CRM or order management system used to process the transaction. This field is helpful when you have multiple CRMs.

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.

event_guid: string

The event_guid field contains the globally unique identifier that Midigator assigned to this event registration.

event_timestamp: string (date-time)

The event_timestamp field is the date and time of the event. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2020-09-27T20:42:43Z. All timestamps are in UTC time.

event_type: string

The event_type field indicates which kind of event has taken place.

Example
{
  "order_validation_type": "consumer_clarity",
  "order_validation_timestamp": "2020-10-17T12:32:33Z",
  "order_validation_guid": "ov_xyzdefdea06e48af9b46c1f5160784c3",
  "transaction_timestamp": "2020-09-27T20:42:43Z",
  "amount": "10.04",
  "currency": "USD",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "arn": "99992989193702154389999",
  "auth_code": "abc123",
  "card_brand": "visa",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "crm_account_guid": "crm_2ec227c00d8c11eb82e3e2adcbae8b42",
  "mid": "189250002",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_timestamp": "2020-09-27T20:42:43Z",
  "event_type": "order_validation.match"
}

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",
    "..."
  ]
}

prevention: object

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

amount: number

The amount field contains the amount of the prevention alert.

arn: string

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

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

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.

merchant_descriptor: string

The merchant_descriptor field lists the billing descriptor for the transaction associated with this prevention alert. A billing descriptor is the short explanation of the transaction that appears on the cardholder’s statement and is what the cardholder’s bank uses to issue alerts.

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.

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.

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.

prevention_guid: string

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

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". All timestamps are in UTC time.

prevention_type: string , x ∈ { ethoca , verifi , tc40 }

The prevention_type contains the name of the prevention alert vendor that sent the alert.

transaction_timestamp: string (date-time)

The transaction_timestamp field is the authorization or settlement date and time for the transaction associated with this prevention alert.It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2019-09-25T21:12:23Z. All timestamps are in UTC time.

Example
{
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "card_brand": "visa",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "currency": "USD",
  "merchant_descriptor": "Merchant Descriptor",
  "mid": "189250002",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "prevention_case_number": "98453223854042",
  "prevention_guid": "pre_abcdefdea06e48af9b46c1f5160784c3",
  "prevention_timestamp": "2019-09-27T20:42:43Z",
  "prevention_type": "ethoca",
  "transaction_timestamp": "2019-09-25T21:12:23Z"
}

prevention.new: object

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

amount: number

The amount field contains the amount of the prevention alert.

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.

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.

event_guid: string

The event_guid field contains the globally unique identifier that Midigator assigned to this event registration.

event_timestamp: string (date-time)

The event_timestamp field is the date and time of the event. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2019-09-27T20:42:43Z. All timestamps are in UTC time.

event_type: string

The event_type field indicates which kind of event has taken place.

merchant_descriptor: string

The merchant_descriptor field lists the billing descriptor for the transaction associated with this prevention alert. A billing descriptor is the short explanation of the transaction that appears on the cardholder’s statement and is what the cardholder’s bank uses to issue alerts.

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.

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.

prevention_guid: string

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

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". All timestamps are in UTC time.

prevention_type: string , x ∈ { ethoca , verifi , tc40 }

The prevention_type contains the name of the prevention alert vendor that sent the alert.

transaction_timestamp: string (date-time)

The transaction_timestamp field is the authorization or settlement date and time for the transaction associated with this prevention alert.It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2019-05-15T19:00:02Z. All timestamps are in UTC time.

Example
{
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "currency": "USD",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_type": "prevention.new",
  "merchant_descriptor": "Merchant Descriptor",
  "mid": "189250002",
  "prevention_case_number": "98453223854042",
  "prevention_guid": "pre_abcdefdea06e48af9b46c1f5160784c3",
  "prevention_timestamp": "2019-09-27T20:42:43Z",
  "prevention_type": "ethoca",
  "transaction_timestamp": "2019-05-15T19:00:02Z"
}

prevention.match: object

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

amount: number

The amount field contains the amount of the prevention alert.

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.

crm_account_guid: string

The crm_account_guid field contains the unique identifier assigned to the CRM or order management system used to process the transaction. This field is helpful when you have multiple CRMs.

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.

event_guid: string

The event_guid field contains the globally unique identifier that Midigator assigned to this event registration.

event_timestamp: string (date-time)

The event_timestamp field is the date and time of the event. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2019-09-27T20:42:43Z. All timestamps are in UTC time.

event_type: string

The event_type field indicates which kind of event has taken place.

merchant_descriptor: string

The merchant_descriptor field lists the billing descriptor for the transaction associated with this prevention alert. A billing descriptor is the short explanation of the transaction that appears on the cardholder’s statement and is what the cardholder’s bank uses to issue alerts.

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.

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.

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.

prevention_guid: string

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

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". All timestamps are in UTC time.

prevention_type: string , x ∈ { ethoca , verifi , tc40 }

The prevention_type contains the name of the prevention alert vendor that sent the alert.

transaction_timestamp: string (date-time)

The transaction_timestamp field is the authorization or settlement date and time for the transaction associated with this prevention alert.It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2019-09-25T21:12:23Z. All timestamps are in UTC time.

Example
{
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "crm_account_guid": "crm_2ec227c00d8c11eb82e3e2adcbae8b42",
  "currency": "USD",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_type": "prevention.match",
  "merchant_descriptor": "Merchant Descriptor",
  "mid": "189250002",
  "order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
  "order_id": "abcdef123",
  "prevention_case_number": "98453223854042",
  "prevention_guid": "pre_abcdefdea06e48af9b46c1f5160784c3",
  "prevention_timestamp": "2019-09-27T20:42:43Z",
  "prevention_type": "ethoca",
  "transaction_timestamp": "2019-09-25T21:12:23Z"
}

rdr.new: object

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

amount: number

The amount field contains the amount of the RDR alert.

arn: string

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

auth_code: string

The auth_code field contains the authorization code that was provided by the issuer during authorization of the transaction.

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 RDR 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 RDR alert.

currency: string

The currency field is the currency of the RDR 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.

event_guid: string

The event_guid field contains the globally unique identifier that Midigator assigned to this event registration.

event_timestamp: string (date-time)

The event_timestamp field is the date and time of the event. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2019-09-27T20:42:43Z. All timestamps are in UTC time.

event_type: string

The event_type field indicates which kind of event has taken place.

merchant_descriptor: string

The merchant_descriptor field lists the billing descriptor for the transaction associated with this RDR alert. A billing descriptor is the short explanation of the transaction that appears on the cardholder’s statement and is what the cardholder’s bank uses to issue alerts.

rdr_case_number: string

The rdr_case_number is the unique identifier that the RDR alert vendor assigned to the alert.

rdr_guid: string

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

rdr_date: string (date)

The rdr_date field is the date the RDR alert was issued. It will be expressed in YYYY-MM-DD format.

rdr_resolution: string , x ∈ { Accepted , Declined }

The resolution of the alert provided by the RDR alert vendor.

prevention_type: string , x ∈ { rdr }

The prevention_type contains the name of the RDR alert vendor.

transaction_date: string (date)

The transaction_date field is the authorization or settlement date for the transaction associated with this RDR alert. It will be expressed in YYYY-MM-DD format.

Example
{
  "amount": 10.04,
  "arn": "99992989193702154389999",
  "auth_code": "123456",
  "card_first_6": "401288",
  "card_last_4": "1883",
  "currency": "USD",
  "event_guid": "evr_d8cb61dea06e48af9b46c1f5160784c3",
  "event_timestamp": "2019-09-27T20:42:43Z",
  "event_type": "rdr.new",
  "merchant_descriptor": "Merchant Descriptor",
  "rdr_case_number": "123456789",
  "rdr_guid": "rdr_abcdefdea06e48af9b46c1f5160784c3",
  "rdr_date": "2019-09-27",
  "rdr_resolution": "Accepted",
  "prevention_type": "rdr",
  "transaction_date": "2019-05-15"
}

registration.new: object

This payload will be sent to your registered URL when a new event subscription is created (chargeback.new, chargeback.match, chargeback.result, chargeback.dnf, prevention.new, prevention.match, rdr.new)

event_guid: string

The globally unique identifier (GUID) for the event subscription

event_type: string
subscribed_event_type: string

This is the type of event subscription that is being registered.

event_timestamp: string (date-time)

The event_timestamp field is the date and time for the creation of the event subscription. It will be expressed in ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) format. For example, 2019-09-25T21:12:23Z. All timestamps are in UTC time.

Example
{
  "event_guid": "evr_e98ebf09f8044232a82b9b5ff6150eb58",
  "event_type": "registration.new",
  "subscribed_event_type": "prevention.new",
  "event_timestamp": "2019-09-25T21:12:23Z"
}

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 , rdr.new , chargeback.match , prevention.match , chargeback.result , chargeback.dnf }

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 , chargeback.result , chargeback.dnf , rdr.new }

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"
  }
}
Documentation by Spectacle