### List Document Types and Filter Supporting Documents

Source: https://apidocs.emscorporate.com/docs/submitting-an-unsigned-deal

Retrieve a list of document types available in the system. Only document types with 'SupportingDocument' set to true will be saved during deal submission. This example shows how to identify documents that will be saved and those that will not.

```json
{
    "Id": 28,
    "Description": "Firearms Addendum",
    "SupportingDocument": false,
    "flatten": true
  },
  {
    "Id": 30,
    "Description": "Driver's License",
    "SupportingDocument": true,
    "flatten": true
  }
```

--------------------------------

### List Batch Detail API

Source: https://apidocs.emscorporate.com/docs/getting-batch-information

Get detailed information about a specific batch ID.

```APIDOC
## GET /reference/list-batch-detail

### Description
Retrieve detailed information about a specific batch by submitting its ID.

### Method
GET

### Endpoint
/reference/list-batch-detail

### Parameters
#### Query Parameters
- **batch_id** (string) - Required - The ID of the batch to retrieve details for.

### Response
#### Success Response (200)
- **batch_detail** (object) - Detailed information about the specified batch.
  - **batch_id** (string) - The unique identifier for the batch.
  - **transaction_count** (integer) - The total number of transactions in the batch.
  - **total_amount** (number) - The total amount of transactions in the batch.
  - **creation_date** (string) - The date and time the batch was created.

#### Response Example
```json
{
  "batch_detail": {
    "batch_id": "batch_123",
    "transaction_count": 150,
    "total_amount": 7500.50,
    "creation_date": "2023-10-27T10:00:00Z"
  }
}
```
```

--------------------------------

### List Daily Batch Card Summary API

Source: https://apidocs.emscorporate.com/docs/getting-batch-information

Get batch data broken down by card type for a specific day and merchant.

```APIDOC
## GET /reference/list-daily-batch-card-summary

### Description
Retrieve batch data broken down by card type for a merchant on a given day.

### Method
GET

### Endpoint
/reference/list-daily-batch-card-summary

### Parameters
#### Query Parameters
- **MID** (string) - Required - The merchant ID.
- **date** (string) - Required - The date in YYYY-MM-DD format.

### Response
#### Success Response (200)
- **card_summary** (array) - A list of batch summaries broken down by card type.
  - **card_type** (string) - The type of card (e.g., Visa, Mastercard).
  - **transaction_count** (integer) - The number of transactions for this card type.
  - **total_amount** (number) - The total amount for this card type.

#### Response Example
```json
{
  "card_summary": [
    {
      "card_type": "Visa",
      "transaction_count": 100,
      "total_amount": 5000.00
    },
    {
      "card_type": "Mastercard",
      "transaction_count": 50,
      "total_amount": 2500.50
    }
  ]
}
```
```

--------------------------------

### Get MCC List Async

Source: https://apidocs.emscorporate.com/docs/submitting-an-unsigned-deal

Retrieves a list of Merchant Category Codes (MCCs) asynchronously. It then validates if a given MCC ID exists within the retrieved list. If the MCC ID is invalid, it throws an exception.

```csharp
var mccList = await mmcApiHelper.GetMCCListAsync(myToken.Token);

if (unsignedDeal.MerchantData.MccId is not null
    && !mccList.Any(m => m.Id == unsignedDeal.MerchantData.MccId))
{
    throw new Exception("The MCC id is invalid. " +
            "This deal should not be submitted because it will " +
            "just be rejected and will have to be fixed anyway.");
}
```

--------------------------------

### Get Specific Chargeback

Source: https://apidocs.emscorporate.com/docs/disputes

Retrieves header information for a specific chargeback using its Dash ID, bypassing list views.

```APIDOC
## GET /websites/apidocs_emscorporate/reference/get-specific-chargeback

### Description
Retrieves the header information about a specific chargeback using its Dash ID. This endpoint is useful when you have the Dash ID and want to quickly access chargeback data without going through a list.

### Method
GET

### Endpoint
/websites/apidocs_emscorporate/reference/get-specific-chargeback

### Parameters
#### Query Parameters
- **dashId** (string) - Required - The unique Dash ID of the chargeback.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **chargebackId** (string) - The unique identifier for the chargeback.
- **disputeCategory** (string) - The category of the dispute.
- **merchantId** (string) - The identifier of the merchant.
- **transactionDate** (string) - The date of the transaction.
- **amount** (number) - The amount of the chargeback.
- **currency** (string) - The currency of the chargeback.
- **status** (string) - The current status of the chargeback.

#### Response Example
```json
{
  "chargebackId": "cb_123",
  "disputeCategory": "fraud",
  "merchantId": "mid_456",
  "transactionDate": "2023-10-27T10:00:00Z",
  "amount": 50.00,
  "currency": "USD",
  "status": "open"
}
```
```

--------------------------------

### C# APIToken Class and Token Acquisition Example

Source: https://apidocs.emscorporate.com/docs/authentication-tokens

Defines a C# class 'APIToken' to hold the token and its expiration time. Demonstrates acquiring an API token asynchronously using a 'tokenGetter' object, which requires username and password. The token is valid for 24 hours.

```csharp
public class APIToken
{
  public string Token { get; set; }
  public DateTime Expires { get; set; }
}

APIToken myToken = await tokenGetter.GetAPITokenAsync(myUsername, myPassword);
```

--------------------------------

### Get MCCs API

Source: https://apidocs.emscorporate.com/docs/submitting-a-signed-deal

Retrieves a list of valid Merchant Category Codes (MCCs). Validate the MCC ID in the deal against this list.

```APIDOC
## MCC Code

### Description
Retrieves a list of valid Merchant Category Codes (MCCs). It is essential to ensure that the MCC ID value is accurate prior to submission. Use this endpoint to validate the MCC ID.

### Method
GET

### Endpoint
/list-mccs

### Parameters
#### Query Parameters
- **token** (string) - Required - Authentication token.

### Response
#### Success Response (200)
- **mccs** (array) - A list of MCC objects.
  - **id** (integer) - The unique identifier for the MCC.
  - **description** (string) - The description of the MCC.

#### Response Example
```json
[
  {
    "id": 5411,
    "description": "Grocery Stores"
  },
  {
    "id": 5812,
    "description": "Eating Places, Restaurants"
  }
]
```

### Code Example (C#)
```csharp
var mccList = await mmcApiHelper.GetMCCListAsync(myToken.Token);

if (!mccList.Any(m => m.Id == signedDeal.MerchantData.MccId))
{
  throw new Exception("The MCC ID is invalid. This deal should not be submitted because it will just be rejected and will have to be fixed anyway.");
}
```
```

--------------------------------

### Prepare and Attach Documents for Deal Submission in C#

Source: https://apidocs.emscorporate.com/docs/submitting-an-unsigned-deal

This C# snippet demonstrates how to retrieve valid documents, create a DealDocument object, set its ID and filename, and convert the document's byte content to a base64 string for transmission. It assumes the existence of helper classes and a valid token.

```csharp
var validDocuments = await documentAPIHelper.ListDocumentsAsync(myToken.Token);

DealDocument bankStatement = new();
bankStatement.Id = validDocuments.First(d => d.Description == "Bank Statement").Id;
bankStatement.Name = Path.GetFileName(statementPath);
bankStatement.File = Convert.ToBase64String(File.ReadAllBytes(statementPath));
```

--------------------------------

### Deal Types, Pricing, Merchant Data, and Owners

Source: https://apidocs.emscorporate.com/docs/submitting-a-signed-deal

This section outlines the rules and requirements for setting up deals, including deal types, pricing models, merchant data specifics, and owner information.

```APIDOC
## Deal Setup Requirements

### Deal Types
At least one deal type must be set to true:
- Processing
- Leasing
- WebHosting
- CashAdvance
- CheckAcept
- Gift
- Bizfunds (Requires Processing to be true)
- MaxxPay
- Cryptocurrency

### Pricing
Only one pricing type can be set to true:
- Surcharge
- CashDiscount
- DualPricing

### Merchant Data
- If `InternetPercent` is not zero, an `URL` must be set.
- For retail deals with `MonthlyBilling` set to true, `Surcharge`, `CashDiscount`, or `DualPricing` cannot be true.
- For non-retail deals, `ExpeditedFunding` and `MonthlyBilling` must be false.

### Owners
- A deal cannot have more than 11 owners.
- At least one owner must be set as a signer.
- A maximum of two signers are allowed.
- The sum of `OwnershipPercent` among owners cannot exceed 100.
- Owner driver's licenses are optional but recommended for faster processing. If provided, `DriverIdNum` and `DriverIdState` must be valid. Use the [Validate Drivers License endpoint](https://apidocs.emscorporate.com/reference/validate-drivers-license) for validation.
- Owner phone numbers (home and mobile) should be validated using the [Validate Phone Number endpoint](https://apidocs.emscorporate.com/reference/validate-phone-number).
```

--------------------------------

### Get MMCs

Source: https://apidocs.emscorporate.com/docs/submitting-an-unsigned-deal

Retrieves a list of Merchant Category Codes (MCCs). This is used to validate the MCC ID associated with a deal.

```APIDOC
## GET /websites/apidocs_emscorporate/recipes/get-mmcs

### Description
Retrieves a list of Merchant Category Codes (MCCs) to validate against a deal's MCC ID.

### Method
GET

### Endpoint
/websites/apidocs_emscorporate/recipes/get-mmcs

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **mccList** (array) - An array of MCC objects, each with an 'Id' field.

#### Response Example
```json
[
  {
    "Id": "1234",
    "Description": "Sample MCC"
  }
]
```
```

--------------------------------

### List Daily Batch Summary With Details API

Source: https://apidocs.emscorporate.com/docs/getting-batch-information

Retrieve detailed information about daily batches for a merchant.

```APIDOC
## GET /reference/list-daily-batch-summary-with-details

### Description
Retrieve detailed information regarding the batches a merchant had on a specific day.

### Method
GET

### Endpoint
/reference/list-daily-batch-summary-with-details

### Parameters
#### Query Parameters
- **MID** (string) - Required - The merchant ID.
- **date** (string) - Required - The date in YYYY-MM-DD format.

### Response
#### Success Response (200)
- **batch_details** (array) - A list of detailed batch information for the specified date.
  - **batch_id** (string) - The unique identifier for the batch.
  - **transaction_count** (integer) - The total number of transactions in the batch.
  - **total_amount** (number) - The total amount of transactions in the batch.
  - **details** (object) - More granular details about the batch.

#### Response Example
```json
{
  "batch_details": [
    {
      "batch_id": "batch_123",
      "transaction_count": 150,
      "total_amount": 7500.50,
      "details": {
        "avg_transaction_amount": 50.00
      }
    }
  ]
}
```
```

--------------------------------

### C# - Prepare Service Ticket Document for Upload

Source: https://apidocs.emscorporate.com/docs/working-with-service-tickets

This C# snippet demonstrates how to prepare a document for upload with a service ticket. It converts a file into a Base64 string and extracts its name and extension, which are necessary for the API. Ensure the `ServiceTicketDocument` class and necessary `System.IO` methods are available.

```csharp
var doc = new ServiceTicketDocument();
doc.Name = Path.GetFileName(documentPath);
doc.Extension = Path.GetExtension(documentPath);
doc.Base64File = Convert.ToBase64String(File.ReadAllBytes(documentPath));
```

--------------------------------

### List Transaction Profiles Async

Source: https://apidocs.emscorporate.com/docs/submitting-an-unsigned-deal

Fetches a list of transaction profiles asynchronously. It then checks if a provided transaction profile ID is valid within the fetched list. If the transaction profile ID is not found, an exception is thrown.

```csharp
var transactionProfiles = await transactionProfileAPIHelper.ListTransactionProfilesAsync(myToken.Token);

if (unsignedDeal.DealProcessing?.TransactionProfile is not null
    && !transactionProfiles.Any(tp => tp.Id == unsignedDeal.DealProcessing.TransactionProfile))
{
  throw new Exception($"The transaction profile is invalid. " +
                      "This deal should not be submitted because it will " +
                      "just be rejected and will have to be fixed anyway.");
}
```

--------------------------------

### List Chargeback Summary

Source: https://apidocs.emscorporate.com/docs/disputes

Retrieves a list of chargebacks without the detailed information, offering a faster response time.

```APIDOC
## GET /websites/apidocs_emscorporate/reference/list-chargeback-summary

### Description
Retrieves a summary list of chargebacks within a specified time frame. This endpoint is faster as it does not include full details, which can be fetched separately.

### Method
GET

### Endpoint
/websites/apidocs_emscorporate/reference/list-chargeback-summary

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for filtering chargebacks.
- **endDate** (string) - Required - The end date for filtering chargebacks.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **chargebacks** (array) - A list of chargeback summary objects.
  - **chargebackId** (string) - The unique identifier for the chargeback.
  - **disputeCategory** (string) - The category of the dispute.
  - **merchantId** (string) - The identifier of the merchant.
  - **transactionDate** (string) - The date of the transaction.
  - **amount** (number) - The amount of the chargeback.
  - **currency** (string) - The currency of the chargeback.
  - **status** (string) - The current status of the chargeback.

#### Response Example
```json
{
  "chargebacks": [
    {
      "chargebackId": "cb_123",
      "disputeCategory": "fraud",
      "merchantId": "mid_456",
      "transactionDate": "2023-10-27T10:00:00Z",
      "amount": 50.00,
      "currency": "USD",
      "status": "open"
    }
  ]
}
```
```

--------------------------------

### List Chargebacks With Details

Source: https://apidocs.emscorporate.com/docs/disputes

Retrieves a list of chargebacks along with all associated details within a specified time frame.

```APIDOC
## GET /websites/apidocs_emscorporate/reference/list-chargebacks

### Description
Retrieves a comprehensive list of chargebacks, including all details associated with each chargeback, within a specified time frame.

### Method
GET

### Endpoint
/websites/apidocs_emscorporate/reference/list-chargebacks

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for filtering chargebacks.
- **endDate** (string) - Required - The end date for filtering chargebacks.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **chargebacks** (array) - A list of chargeback objects, each containing detailed information.
  - **chargebackId** (string) - The unique identifier for the chargeback.
  - **disputeCategory** (string) - The category of the dispute.
  - **merchantId** (string) - The identifier of the merchant.
  - **transactionDate** (string) - The date of the transaction.
  - **amount** (number) - The amount of the chargeback.
  - **currency** (string) - The currency of the chargeback.
  - **status** (string) - The current status of the chargeback.
  - **details** (object) - Additional details about the chargeback.

#### Response Example
```json
{
  "chargebacks": [
    {
      "chargebackId": "cb_123",
      "disputeCategory": "fraud",
      "merchantId": "mid_456",
      "transactionDate": "2023-10-27T10:00:00Z",
      "amount": 50.00,
      "currency": "USD",
      "status": "open",
      "details": {
        "reasonCode": "R01",
        "description": "Illegitimate transaction"
      }
    }
  ]
}
```
```

--------------------------------

### Submit Unsigned Deal and Process Response in C#

Source: https://apidocs.emscorporate.com/docs/submitting-an-unsigned-deal

Submit an unsigned deal using the provided API helper. This C# code snippet shows how to call the submission endpoint and then check the result. It distinguishes between a successful submission (outputting the EMSDealId) and a failed submission (outputting an error message).

```csharp
var dealSubmissionResult = await dealAPIHelper.SubmitUnsignedDeal(myToken.Token, unsignedDeal);
if (dealSubmissionResult.EMSDealId != string.Empty)
{
  Console.WriteLine($"Deal ID: {dealSubmissionResult.EMSDealId}");
}
else
{
  Console.WriteLine(dealSubmissionResult.Message);
}
```

--------------------------------

### List Daily Batch Summary API

Source: https://apidocs.emscorporate.com/docs/getting-batch-information

Retrieve a summary of batches a merchant had on any given day by passing the MID and the date.

```APIDOC
## GET /reference/list-daily-batch-summary

### Description
Retrieve a summary of batches a merchant had on any given day by passing the MID and the date in question.

### Method
GET

### Endpoint
/reference/list-daily-batch-summary

### Parameters
#### Query Parameters
- **MID** (string) - Required - The merchant ID.
- **date** (string) - Required - The date in YYYY-MM-DD format.

### Response
#### Success Response (200)
- **batch_summary** (array) - A list of batch summaries for the specified date.
  - **batch_id** (string) - The unique identifier for the batch.
  - **transaction_count** (integer) - The total number of transactions in the batch.
  - **total_amount** (number) - The total amount of transactions in the batch.

#### Response Example
```json
{
  "batch_summary": [
    {
      "batch_id": "batch_123",
      "transaction_count": 150,
      "total_amount": 7500.50
    }
  ]
}
```
```

--------------------------------

### List Daily Batch Interchange Summary API

Source: https://apidocs.emscorporate.com/docs/getting-batch-information

Retrieve the interchange summary for a merchant on any given date.

```APIDOC
## GET /reference/list-daily-batch-interchange-summary

### Description
Retrieve the interchange summary for a merchant on a specified date.

### Method
GET

### Endpoint
/reference/list-daily-batch-interchange-summary

### Parameters
#### Query Parameters
- **MID** (string) - Required - The merchant ID.
- **date** (string) - Required - The date in YYYY-MM-DD format.

### Response
#### Success Response (200)
- **interchange_summary** (array) - A list of interchange summaries for the specified date.
  - **interchange_type** (string) - The type of interchange fee.
  - **total_interchange_amount** (number) - The total interchange amount for this type.

#### Response Example
```json
{
  "interchange_summary": [
    {
      "interchange_type": "Interchange Fee A",
      "total_interchange_amount": 150.75
    },
    {
      "interchange_type": "Interchange Fee B",
      "total_interchange_amount": 75.25
    }
  ]
}
```
```

--------------------------------

### Documents API

Source: https://apidocs.emscorporate.com/docs/submitting-a-signed-deal

This section details how to list document types and prepare documents for upload. Documents need to be converted to a Base64 string before transmission.

```APIDOC
## Documents API

### List Document Types

Use the `List Document Types` endpoint to retrieve a list of available document types and their IDs.

### Method
GET

### Endpoint
/reference/list-documents

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Id** (integer) - The unique identifier for the document type.
- **Description** (string) - The name or description of the document type.

#### Response Example
```json
[
  {
    "Id": 1,
    "Description": "Kurv Checklist"
  },
  {
    "Id": 2,
    "Description": "E-SIGN Certificate of Completion"
  }
]
```

### Document Preparation
Convert the bytes of the document to a base 64 string for transmission.

#### Request Example (C#)
```csharp
var validDocuments = await documentAPIHelper.ListDocumentsAsync(myToken.Token);

DealDocument esignDocument = new DealDocument(); 
esignDocument.Id = validDocuments.First(d => d.Description == "E-SIGN Certificate of Completion").Id;
esignDocument.Name = Path.GetFileName(esignPath);
esignDocument.File = Convert.ToBase64String(File.ReadAllBytes(esignPath));
```

### Required Documents Based on Deal Type

- **Always Required:**
  - Kurv Checklist
  - E-SIGN Certificate of Completion

- **If Processing Deal:**
  - W9
  - If MCC is HighRisk: Merchant Application (High Risk)
  - If MCC is not HighRisk: Merchant Application (Retail)
  - If MCC is MC_HighRisk or VS_HighRisk: High Risk Registration
  - If MCC is not set: Merchant Application (Retail) and Merchant Application (High Risk)
  - If Bizfunds is true: BizFunds Merchant Information Form, BizFunds Permission to Release Information, BizFunds Merchant Agreement
  - If Surcharge is true: Surcharge Addendum
  - If CashDiscount is true: Cash Discount Addendum
  - If DualPricing is true: Dual Pricing Addendum
  - Additional addendums may be required based on MCC. Use the [List MCCs endpoint](https://apidocs.emscorporate.com/reference/list-mccs) for details.

- **Other Conditional Documents:**
  - If more than two owners: Owner Addendum
  - If CheckAccept is true: eCheck Application
  - If Gift is true: Altus Premier Agreement
  - If Leasing is true: LeaseMax Agreement
  - If MaxxPay is true: MaxxPay Order Form
  - If Cryptocurrency is true: Rolling Reserve Addendum
```

--------------------------------

### Validate Address using C#

Source: https://apidocs.emscorporate.com/docs/submitting-an-unsigned-deal

This C# code snippet demonstrates how to validate an owner's address using the Validate Address endpoint. It checks if the provided Zip, City, and State combination is valid before submitting the deal. If the address is invalid, it throws an exception.

```csharp
foreach (var owner in unsignedDeal.Owners)
{
    var addressToValidate = owner.Address;
    if (addressToValidate is not null
        && await addressAPIHelper.ValidateAddressByZipCityAndStateAsync(myToken.Token,
                                                                     addressToValidate.Zip,
                                                                     addressToValidate.City,
                                                                     addressToValidate.State) is null)
    {
      throw new Exception($"The address for {owner.LastName}, {owner.FirstName} is invalid. " +
                          "This deal should not be submitted because it will " +
                          "just be rejected and will have to be fixed anyway.");
    }
}
```

--------------------------------

### HTML Structure for Deal Submission with CSS Styling

Source: https://apidocs.emscorporate.com/docs/submitting-an-unsigned-deal

This snippet provides the HTML structure for displaying deal submission information, along with embedded CSS for styling various visual elements like containers and text blocks. It does not include functional code but rather presentation logic.

```html
<HTMLBlock>
  {
  <style>
  .imgContainer {
      background-position:center;
      border: 3px solid black;
      padding: 5px;
  }
  .mapContainer {
      background-image:url(https://files.readme.io/1f21ea3-photo-1520299607509-dcd935f9a839.avif);
  }
  .keyContainer {
      background-image:url(https://files.readme.io/0c2ce25-3a1bba50-951f-44c5-8994-f94de63a41c4.jfif);
      background-position: top right;
  }
  .bankContainer {
      background-image:url(https://files.readme.io/120d457-ea508911-28d2-4d20-aeaa-b54c022d112e.jfif);
      background-position:top;
  }
  .transactionContainer {
      background-image:url(https://files.readme.io/120d457-ea508911-28d2-4d20-aeaa-b54c022d112e.jfif);
      background-position:bottom;
  }
  .businessmanContainer {
      background-image:url(https://files.readme.io/a350808-1894d7a2-4d9b-4ca1-b3e8-0fd643856868.jfif);
  }
  .officeContainer {
      background-image:url(https://files.readme.io/120d457-ea508911-28d2-4d20-aeaa-b54c022d112e.jfif);
      background-position: top -400px ;
  }
  .documentContainer {
      background-image:url(https://files.readme.io/abda93f-225cf8b7-8108-43a5-af6e-9cf44a877c4b.jfif);
  }
  .mccContainer {
      background-image:url(https://files.readme.io/65e5644-86287e71-02fd-49fb-890f-0a7828f04b76.jfif);
  }
  .mailContainer {
      background-image:url(https://files.readme.io/840e41f-9a033c9c-f362-436f-817a-892a2ec062b0.jfif);
  }
  .storeContainer {
      background-image:url(https://files.readme.io/cebef96-a71f45ac-72e1-4e3c-bca3-ea3987ff2bd8.jfif);
  }
  .store2Container {
      background-image:url(https://files.readme.io/cebef96-a71f45ac-72e1-4e3c-bca3-ea3987ff2bd8.jfif);
      background-position: top right;
  }
  .store3Container {
      background-image:url(https://files.readme.io/cebef96-a71f45ac-72e1-4e3c-bca3-ea3987ff2bd8.jfif);
      background-position: bottom left;
  }
  .carContainer {
      background-image:url(https://files.readme.io/29b6dcb-d402bb7b-4597-415d-a0ff-7e90acc34763.jfif);
      background-position: top -480px right 0px;
  }
  .phoneContainer {
      background-image:url(https://files.readme.io/e3430a0-81378edc-d472-4962-813b-7d5ac68a7255.jfif);
      background-position: top -370px right -200px;
  }
  .textBlock {
      border: 3px solid black;
      background-color: white;
      color: black;
      font-weight: bold;
      padding: 3px;
  }
  </style>
  }
</HTMLBlock>
<Image align="center" width="300px" src="https://files.readme.io/1244f8c-photo-1554224155-1696413565d3.avif" />
```

--------------------------------

### List Chargeback Details

Source: https://apidocs.emscorporate.com/docs/disputes

Retrieves detailed information for a specific chargeback using its Dash ID.

```APIDOC
## GET /websites/apidocs_emscorporate/reference/list-chargeback-detail

### Description
Retrieves detailed information for a specific chargeback by its Dash ID. This is typically used after fetching a summary list.

### Method
GET

### Endpoint
/websites/apidocs_emscorporate/reference/list-chargeback-detail

### Parameters
#### Query Parameters
- **dashId** (string) - Required - The unique Dash ID of the chargeback.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **chargebackId** (string) - The unique identifier for the chargeback.
- **disputeCategory** (string) - The category of the dispute.
- **merchantId** (string) - The identifier of the merchant.
- **transactionDate** (string) - The date of the transaction.
- **amount** (number) - The amount of the chargeback.
- **currency** (string) - The currency of the chargeback.
- **status** (string) - The current status of the chargeback.
- **details** (object) - Additional details about the chargeback.
  - **reasonCode** (string) - The reason code for the chargeback.
  - **description** (string) - A description of the chargeback reason.

#### Response Example
```json
{
  "chargebackId": "cb_123",
  "disputeCategory": "fraud",
  "merchantId": "mid_456",
  "transactionDate": "2023-10-27T10:00:00Z",
  "amount": 50.00,
  "currency": "USD",
  "status": "open",
  "details": {
    "reasonCode": "R01",
    "description": "Illegitimate transaction"
  }
}
```
```

--------------------------------

### Validate Ownership Type with C#

Source: https://apidocs.emscorporate.com/docs/submitting-a-signed-deal

This C# snippet demonstrates how to retrieve a list of valid ownership types and validate a deal's ownership type against this list. It ensures that the provided ownership type ID exists within the valid options before submitting the deal.

```csharp
var ownershipTypes = await ownershipAPIHelper.GetOwnershipTypesAsync(myToken.Token);

if (!ownershipTypes.Any(t => t.Id == signedDeal.MerchantData.OwnershipType))
{
  throw new Exception("The ownership type is invalid. " +
                      "This deal should not be submitted because it will " +
                      "just be rejected and will have to be fixed anyway.");
}
```

--------------------------------

### List Document Types API

Source: https://apidocs.emscorporate.com/docs/submitting-an-unsigned-deal

Retrieves a list of available document types. Use this endpoint to ensure that attached documents have the correct document type ID. Only document types with 'SupportingDocument' set to true will be saved during deal submission.

```APIDOC
## GET /websites/apidocs_emscorporate/reference/list-documents

### Description
Retrieves a list of document types, indicating whether they are considered supporting documents.

### Method
GET

### Endpoint
/websites/apidocs_emscorporate/reference/list-documents

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Id** (integer) - The unique identifier for the document type.
- **Description** (string) - The name of the document type.
- **SupportingDocument** (boolean) - Indicates if this document type is considered a supporting document for deal submission.
- **flatten** (boolean) - Indicates if the document should be flattened.

#### Response Example
```json
{
  "Id": 28,
  "Description": "Firearms Addendum",
  "SupportingDocument": false,
  "flatten": true
}
```
```json
{
  "Id": 30,
  "Description": "Driver's License",
  "SupportingDocument": true,
  "flatten": true
}
```
```

--------------------------------

### Submit Unsigned Deal API

Source: https://apidocs.emscorporate.com/docs/submitting-an-unsigned-deal

Submits an unsigned deal. Documents that are not marked as supporting documents will be noted in the success message but will not prevent the deal submission.

```APIDOC
## POST /websites/apidocs_emscorporate/reference/submit-unsigned-deal

### Description
Submits an unsigned deal for processing. Attached documents that are not flagged as supporting documents will be reported but the submission will still be considered successful if other criteria are met.

### Method
POST

### Endpoint
/websites/apidocs_emscorporate/reference/submit-unsigned-deal

### Parameters
#### Request Body
- **unsignedDeal** (object) - Required - The unsigned deal object containing all necessary information.
  - **Id** (integer) - Required - The ID of the document type for the bank statement.
  - **Name** (string) - Required - The filename of the bank statement.
  - **File** (string) - Required - The bank statement file content encoded in Base64.

### Request Example
```csharp
var validDocuments = await documentAPIHelper.ListDocumentsAsync(myToken.Token);

DealDocument bankStatement = new();
bankStatement.Id = validDocuments.First(d => d.Description == "Bank Statement").Id;
bankStatement.Name = Path.GetFileName(statementPath);
bankStatement.File = Convert.ToBase64String(File.ReadAllBytes(statementPath));

var dealSubmissionResult = await dealAPIHelper.SubmitUnsignedDeal(myToken.Token, unsignedDeal);
```

### Response
#### Success Response (200)
- **EMSDealId** (string) - The unique identifier for the submitted deal if successful.
- **Message** (string) - A message indicating the status of the submission, including any documents that were not saved.

#### Response Example (Success)
```json
{
	"EMSDealId": "M-50978",
	"Message": "Document(s): ESign.pdf: Not a supporting documents, EMSChecklist.pdf: Not a supporting documents not saved. Other Saved Successfully."
}
```

#### Error Response (e.g., 400 Bad Request)
- **Title** (string) - A general title for the error.
- **Errors** (array of strings) - A list of specific errors encountered during submission.

#### Response Example (Error)
```json
{
	"Title": "The request is invalid.",
	"Errors": [
		"Owners.Address City/State/Zip are invalid."
	]
}
```
```

--------------------------------

### Update Documents on Unsigned Deal

Source: https://apidocs.emscorporate.com/docs/updating-existing-unsigned-deals

This lightweight endpoint is specifically designed for adding or updating attached documents for an unsigned deal. It's efficient when only document modifications are needed.

```APIDOC
## POST /websites/apidocs_emscorporate/reference/update-documents-on-unsigned-deal

### Description
Allows for adding or updating attached documents for an unsigned deal. This is a lightweight endpoint for document-specific modifications.

### Method
POST

### Endpoint
/websites/apidocs_emscorporate/reference/update-documents-on-unsigned-deal

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **deal_id** (string) - Required - The unique identifier for the deal.
- **documents** (array) - Required - A list of documents to be added or updated.
  - **document_name** (string) - Required - The name of the document.
  - **document_content** (string) - Required - The base64 encoded content of the document.

### Request Example
{
  "deal_id": "deal_123",
  "documents": [
    {
      "document_name": "updated_appraisal.pdf",
      "document_content": "JVBERi0xLjQKJcO..."
    }
  ]
}

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **message** (string) - A confirmation message.

#### Response Example
{
  "status": "success",
  "message": "Documents updated successfully."
}
```

--------------------------------

### Validate Merchant and Owner Addresses (C#)

Source: https://apidocs.emscorporate.com/docs/submitting-a-signed-deal

This C# code snippet demonstrates how to validate addresses for owners associated with a signed deal. It iterates through each owner, retrieves their address, and uses an `addressAPIHelper` to validate the address by zip code, city, and state. If an address is invalid, it throws an exception, preventing the deal submission.

```csharp
foreach (var owner in signedDeal.Owners)
{
  var addressToValidate = owner.Address;
  if (await addressAPIHelper.ValidateAddressByZipCityAndStateAsync(myToken.Token,
                                                                   addressToValidate.Zip,
                                                                   addressToValidate.City,
                                                                   addressToValidate.State) is null)
  {
    throw new Exception($"The address for {owner.LastName}, {owner.FirstName} is invalid. " +
                        "This deal should not be submitted because it will " +
                        "just be rejected and will have to be fixed anyway.");
  }
}
```

--------------------------------

### Convert Document to Base64 String (C#)

Source: https://apidocs.emscorporate.com/docs/submitting-a-signed-deal

Converts a document's bytes to a Base64 encoded string for transmission via the API. This snippet retrieves a document type ID, sets document properties, and encodes the file content. It assumes the existence of a documentAPIHelper and a Token object.

```csharp
var validDocuments = await documentAPIHelper.ListDocumentsAsync(myToken.Token);

DealDocument esignDocument = new DealDocument(); 
esignDocument.Id = validDocuments.First(d => d.Description == "E-SIGN Certificate of Completion").Id;
esignDocument.Name = Path.GetFileName(esignPath);
esignDocument.File = Convert.ToBase64String(File.ReadAllBytes(esignPath));
```

--------------------------------

### User Authentication

Source: https://apidocs.emscorporate.com/docs/submitting-a-signed-deal

Before submitting a signed deal, you need to obtain an authentication token. This token is used to validate data across all API endpoints.

```APIDOC
## Authentication

Before you can submit a signed deal, you'll need to get an [authentication token](https://dash.readme.com/project/myportfolio-developer-portal/v1.0/docs/authentication-tokens). This token will be sent to all of the API endpoints that we will be using to validate our data before successfully submitting our deal.
```

--------------------------------

### Submit Signed Deal - C#

Source: https://apidocs.emscorporate.com/docs/submitting-a-signed-deal

Submits a signed deal using the Submit Signed Deal endpoint. It requires authentication token and deal data. The result contains an EMSDealId on success or an error message on failure. Ensure correct office, branch, and rep numbers are included in the deal data.

```csharp
var dealSubmissionResult = await dealAPIHelper.SubmitSignedDeal(myToken.Token, signedDeal);
if (dealSubmissionResult.EMSDealId != string.Empty)
{
  Console.WriteLine($"Deal ID: {dealSubmissionResult.EMSDealId}");
} else
{
  Console.WriteLine(dealSubmissionResult.Message);
}
```

--------------------------------

### C# - Download and Save Service Ticket Comment Document

Source: https://apidocs.emscorporate.com/docs/working-with-service-tickets

This C# code retrieves documents associated with a service ticket comment and saves them to disk. It iterates through the returned documents, decodes the Base64 content, and writes it to files. This requires valid authentication tokens and existing service ticket data.

```csharp
var docs = await apiHelper.GetServiceTicketCommentDocument(myToken.Token,
                                                               updateResult.TicketNumber,
                                                               updateResult.ServiceTicketCommentId,
                                                               uploadDoc.Name);
foreach(var doc in docs)
{
    File.WriteAllBytes(Path.Combine(saveToFolder,doc.Name), 
        Convert.FromBase64String(doc.Base64File));
}
```

--------------------------------

### List Ownership Types API

Source: https://apidocs.emscorporate.com/docs/submitting-a-signed-deal

Retrieves a list of valid ownership types. Ensure the ownership type set in the deal is a valid ID from this list.

```APIDOC
## Ownership Types

### Description
Retrieves a list of valid ownership types. It is crucial to ensure the ownership type set in the deal corresponds to a valid ID obtained from this endpoint before submission.

### Method
GET

### Endpoint
/list-ownership-types

### Parameters
#### Query Parameters
- **token** (string) - Required - Authentication token.

### Response
#### Success Response (200)
- **ownershipTypes** (array) - A list of ownership type objects.
  - **id** (integer) - The unique identifier for the ownership type.
  - **name** (string) - The name of the ownership type.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Sole Proprietorship"
  },
  {
    "id": 2,
    "name": "Partnership"
  }
]
```

### Code Example (C#)
```csharp
var ownershipTypes = await ownershipAPIHelper.GetOwnershipTypesAsync(myToken.Token);

if (!ownershipTypes.Any(t => t.Id == signedDeal.MerchantData.OwnershipType))
{
  throw new Exception("The ownership type is invalid. This deal should not be submitted because it will just be rejected and will have to be fixed anyway.");
}
```
```

--------------------------------

### Update Unsigned Deal

Source: https://apidocs.emscorporate.com/docs/updating-existing-unsigned-deals

This endpoint allows for comprehensive updates to any component of an unsigned deal. Use this method when multiple aspects of the deal need modification.

```APIDOC
## POST /websites/apidocs_emscorporate/reference/update-unsigned-deal

### Description
Allows for comprehensive updates to any component of an unsigned deal. Use this method when multiple aspects of the deal need modification.

### Method
POST

### Endpoint
/websites/apidocs_emscorporate/reference/update-unsigned-deal

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **deal_id** (string) - Required - The unique identifier for the deal to be updated.
- **[other_deal_fields]** (any) - Optional - Fields representing the components of the deal to be updated.

### Request Example
{
  "deal_id": "deal_123",
  "property_address": "123 Main St",
  "loan_amount": 500000
}

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **message** (string) - A confirmation message.

#### Response Example
{
  "status": "success",
  "message": "Deal updated successfully."
}
```

--------------------------------

### List Chargeback Dispute Categories

Source: https://apidocs.emscorporate.com/docs/disputes

Retrieves a list of all dispute categories currently being used against a merchant.

```APIDOC
## GET /websites/apidocs_emscorporate/reference/list-chargeback-dispute-categories

### Description
Retrieves a list of all distinct dispute categories that have been levied against a specific merchant ID (MID).

### Method
GET

### Endpoint
/websites/apidocs_emscorporate/reference/list-chargeback-dispute-categories

### Parameters
#### Query Parameters
- **merchantId** (string) - Required - The identifier of the merchant for whom to retrieve dispute categories.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **disputeCategories** (array) - A list of strings, where each string is a unique dispute category.

#### Response Example
```json
{
  "disputeCategories": [
    "fraud",
    "unauthorized_transaction",
    "duplicate_transaction"
  ]
}
```
```

--------------------------------

### List Retrievals

Source: https://apidocs.emscorporate.com/docs/disputes

Retrieves a list of all retrievals associated with a given MID.

```APIDOC
## GET /reference/list-retrievals

### Description
Retrieves a list of all retrievals associated with a specific MID.

### Method
GET

### Endpoint
/reference/list-retrievals

### Parameters
#### Query Parameters
- **mid** (string) - Required - The Merchant ID for which to retrieve retrievals.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **retrievals** (array) - A list of retrieval objects.
  - **retrieval_id** (string) - The unique identifier for the retrieval.
  - **mid** (string) - The Merchant ID associated with the retrieval.
  - **amount** (number) - The amount of the retrieval.
  - **currency** (string) - The currency of the retrieval.
  - **created_at** (string) - The timestamp when the retrieval was created.

#### Response Example
```json
{
  "retrievals": [
    {
      "retrieval_id": "ret_12345",
      "mid": "mid_abcde",
      "amount": 50.00,
      "currency": "USD",
      "created_at": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### List Sales People

Source: https://apidocs.emscorporate.com/docs/submitting-an-unsigned-deal

Retrieves a list of sales people. This is used to validate office identifiers for deal submission.

```APIDOC
## GET /websites/apidocs_emscorporate/recipes/list-sales-people

### Description
Retrieves a list of sales people, which includes valid office identifiers for deal submission.

### Method
GET

### Endpoint
/websites/apidocs_emscorporate/recipes/list-sales-people

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **salesPeopleList** (array) - An array of sales person objects, each containing office-related information.

#### Response Example
```json
[
  {
    "OfficeId": "office-123",
    "Name": "John Doe"
  }
]
```
```