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 Did 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 RDR.match Alert
A rdr.match event is sent when Midigator matches your RDR case to its original order.
Note: The rdr.match event is new and is in beta. Midigator will continue to monitor match performance and make enhancements to the feature as necessary.
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
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
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:
- When a new subscription is created, the Events API sends a
registration.newpayload to your webhook. - 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.
- 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.
-
If both of the validation tests fail (return an HTTP status of 400 of greater) then the event subscription will remain inactive.
-
If the vetting check succeeds, a status email will be sent to the email address associated with the subscription.
- If the vetting check fails, Midigator will automatically try the activation process 8 more times over the following 24 hour period.
- Every time a vetting check fails, a failure status email will be sent to the email address associated with the subscription.
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.
The request was invalid, usually because of missing or invalid parameters or headers.
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
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.
The request was invalid, usually because of missing or invalid parameters or headers.
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
This path will return all the information that Midigator has available for the specified subscription.
The globally unique identifier (GUID) for the event subscription
Everything worked as expected. The response will include the details of your subscription.
The request was invalid, usually because of missing or invalid parameters or headers.
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
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.
The globally unique identifier (GUID) for the event subscription
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.
The request was invalid, usually because of missing or invalid parameters or headers.
An invalid authorization header was provided.
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
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.
The globally unique identifier (GUID) for the event subscription
Everything worked as expected. Your subscription was successfully deleted.
The request was invalid, usually because of missing or invalid parameters or headers.
An invalid authorization header was provided.
Test 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.
The event type you want to test
Everything worked as expected. The response will include a listing of URLs that will be pinged.
The request was invalid, usually because of missing or invalid parameters or headers.
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.
rdr.match - Midigator matched your RDR case to its original order.
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 did not fight.
When one of these events occur, Midigator will notify you with the corresponding call.
New Chargeback
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
{
"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"
}
Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.
Chargeback Matched
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
{
"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"
}
Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.
Chargeback Result
This callback sends information to your registered URL every time Midigator signals when a representment was delivered.
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"
}
Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.
Chargeback DNF
This callback sends information to your registered URL every time Midigator signals when a chargeback was marked as did not fight.
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"
}
Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.
New Order Validation
This callback sends information to your registered URL every time Midigator receives an order validation request.
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"
}
Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.
Order Validation Matched
This callback sends information to your registered URL every time Midigator matches an order validation request to its original order.
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"
}
Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.
New Prevention Alert
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
{
"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"
}
Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.
Prevention Alert Matched
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
{
"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"
}
Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.
New RDR Alert
This callback sends information to your registered URL every time Midigator receives a new Rapid Dispute Resolution (RDR) alert.
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"
}
Everything worked as expected. For any response code other than a 200, Midigator will attempt to send the event again.
New RDR Match Alert
This callback sends information to your registered URL every time Midigator matches a Rapid Dispute Resolution (RDR) alert to its original order.
See the rdr.match 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.match",
"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",
"order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
"order_id": "abcdef123",
"crm_account_guid": "crm_2ec227c00d8c11eb82e3e2adcbae8b42"
}
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
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.
The globally unique identifier (GUID) for the chargeback
Everything worked as expected. The response will include your chargeback data.
The request was invalid, usually because of missing or invalid parameters or headers.
An invalid authorization header was provided.
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"
}
Get Prevention Data
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.
The globally unique identifier (GUID) for the prevention alert
Everything worked as expected. The response will include your prevention data.
The request was invalid, usually because of missing or invalid parameters or headers.
An invalid authorization header was provided.
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"
}
Get Order Validation Data
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.
The globally unique identifier (GUID) for the order validation request
Everything worked as expected. The response will include your order validation data.
The request was invalid, usually because of missing or invalid parameters or headers.
An invalid authorization header was provided.
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"
}
Get Order Data
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.
The globally unique identifier (GUID) for the order
Everything worked as expected. The response will include your order data.
The request was invalid, usually because of missing or invalid parameters or headers.
An invalid authorization header was provided.
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_numberis the same as thearn. 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_receivedvalue. 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_numberis the same as thearn. 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_receivedvalue. 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_numberis the same as thearn. 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_receivedvalue. 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_numberis the same as thearn. 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 did 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_numberis the same as thearn. 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
amountfield. 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
arnfield. - 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
arnfield. - 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
arnfield. - 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"
}
rdr.match: object
This payload will be sent to your registered URL when a Midigator rdr.match event occurs.
Note: The rdr.match event is new and is in beta. Midigator will continue to monitor match performance and make enhancements to the feature as necessary.
- 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.
- 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.
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.match",
"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",
"order_guid": "ord_dfgdefdea06e48af9b46c1f5160784c3",
"order_id": "abcdef123",
"crm_account_guid": "crm_2ec227c00d8c11eb82e3e2adcbae8b42"
}
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, rdr.match)
- 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 , rdr.match , 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 , rdr.match }
-
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"
}
}