{
  "openapi": "3.0.3",
  "info": {
    "title": "MerchantE Batch Processing API",
    "description": "The MerchantE (ME) Batch Processing API enables merchants and resellers to process live credit card transactions in a batch format. Additionally, merchants can utilize the ME reporting tool to upload batches manually.\n\nBatch Processing functionality allows a merchant to send a batch of transactions to the MerchantE (ME) Reporting Tool for processing. Batch request files can be sent to ME in two ways:\n- Through the ME reporting portal\n- Through an API call to ME\n\nBatch response files can be retrieved from ME in two ways:\n- Through an API call to ME\n- From the ME reporting web portal\n\nProcessing time will vary depending on the transaction type and overall size of the batch, however all batches will be processed within 24 hours of submission. The batch processing option may be used for large recurring files that require both authorization and capture (sale transaction), or in conjunction with the Payment Gateway (ex: captures at the end of day for all online authorizations).\n\n**Batch Processing Best Practices:**\nThere are some functions in the Payment Gateway that may not be ideal when submitting transactions in a batch mode. Examples include:\n- Transactions that need to reference a prior transactions are not good candidates for batch processing\n- Sending multiple settlements for a single authorization concurrently is not recommended within the same batch\n- Transactions such as a settlement followed immediately by a void should be avoided\n\n**Related Documentation:**\n- MerchantE Payment Gateway Specification\n- MerchantE Technical Documentation: http://developer.merchante.com\n- PCI Security Standards: https://www.pcisecuritystandards.org/\n\n**Copyright Notice:**\n©2024 Merchant eSolutions, Inc. All rights reserved.\n\nMerchant e-Solutions, Inc. is a registered Agent of KeyBank, Cleveland, OH, and a registered ISO/MSP of Synovus Bank, Columbus, GA and FFB, Fresno, CA.\n\n**Trademarks:**\n- Mastercard® is a federally registered trademark of Mastercard International, Inc.\n- Visa® is a federally registered trademark of Visa, U.S.A., Inc.\n- Discover® Card is a federally registered trademark of Discover Financial Services Inc.\n- American Express® is a federally registered trademark of American Express Company.\n- ZIP code® and ZIP + 4® are federally registered trademarks of the United States Postal Service.\n\n**Note:** Transactions are formatted according to the layout defined in the ME Payment Gateway Specification.\n\n**Email Confirmation:**\nAn email will be sent upon successful receipt of a batch. A follow up email is sent once the batch has been processed and will contain a response file. Email address is configured by ME at the profile ID level.\n",
    "version": "3.0",
    "contact": {
      "name": "MerchantE Support",
      "url": "https://www.merchante.com",
      "email": "help@MerchantE.com"
    },
    "x-address": {
      "street": "1150 Sanctuary Parkway, Suite 300",
      "city": "Alpharetta",
      "state": "GA",
      "zip": "30009"
    },
    "x-support": {
      "phone": "888-288-2692",
      "email": "help@MerchantE.com"
    }
  },
  "servers": [
    {
      "url": "https://test.merchante-solutions.com/srv/api",
      "description": "Test server"
    }
  ],
  "paths": {
    "/bpUpload": {
      "post": {
        "summary": "Upload batch request file",
        "description": "Used to upload a batch of transactions to ME. All batch API requests are handled by an HTTPS POST to this endpoint. File data should be passed to the server using Content-Type: multipart/form-data. After uploading a file, a confirmation message is sent containing the response identification number.\n\nThe transactional data that is being uploaded should be a text file (.TXT) that has transactions formatted as outlined in the ME Payment Gateway Specification.\n",
        "operationId": "uploadBatchFile",
        "tags": [
          "Batch Upload"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/UploadRequest"
              },
              "examples": {
                "batchUpload": {
                  "summary": "Batch file upload request",
                  "value": {
                    "userId": "merchant123",
                    "userPass": "password123",
                    "profileId": "12345678901234567890",
                    "testFlag": "N",
                    "reqFile": "(binary file content)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "File successfully uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadConfirmation"
                },
                "examples": {
                  "successfulUpload": {
                    "summary": "Successful upload confirmation",
                    "description": "Response returned when batch file is successfully received",
                    "value": {
                      "respFileId": "123456789012345",
                      "profileId": "12345678901234567890",
                      "rspCode": "000",
                      "rspMessage": "OK"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid or missing parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "invalidParameter": {
                    "summary": "Invalid parameter error",
                    "value": {
                      "rspCode": "003",
                      "rspMessage": "Invalid Parameter"
                    }
                  },
                  "missingParameter": {
                    "summary": "Missing parameter error",
                    "value": {
                      "rspCode": "004",
                      "rspMessage": "Missing parameter"
                    }
                  },
                  "invalidProfileId": {
                    "summary": "Invalid Profile ID error",
                    "value": {
                      "rspCode": "300",
                      "rspMessage": "Invalid Profile ID"
                    }
                  },
                  "invalidTestFlag": {
                    "summary": "Invalid test flag error",
                    "value": {
                      "rspCode": "302",
                      "rspMessage": "Invalid test flag"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "authError": {
                    "summary": "Authentication error",
                    "value": {
                      "rspCode": "002",
                      "rspMessage": "Authentication Error"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - Batch processing not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "batchNotAllowed": {
                    "summary": "Batch processing not enabled",
                    "value": {
                      "rspCode": "303",
                      "rspMessage": "Batch processing not allowed"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "systemError": {
                    "summary": "System error",
                    "value": {
                      "rspCode": "001",
                      "rspMessage": "System Error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/bpDownload": {
      "post": {
        "summary": "Download batch response file",
        "description": "Used to download a batch response file. All batch API requests are handled by an HTTPS POST to this endpoint. Response files are used to determine the status of each of the transactions that was submitted in a batch.\n\nThe response file contains transaction data formatted according to the ME Payment Gateway Specification, with each transaction response on a separate line.\n\n**Note:** A JSON error response is only returned if an error has occurred. On success, the raw text file is returned.\n",
        "operationId": "downloadBatchFile",
        "tags": [
          "Batch Download"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/DownloadRequest"
              },
              "examples": {
                "downloadRequest": {
                  "summary": "Download response file request",
                  "value": {
                    "userId": "merchant123",
                    "userPass": "password123",
                    "respFileId": "123456789012345"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Response file successfully retrieved",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Text file containing transaction responses, one per line, formatted according to ME Payment Gateway Specification.\n\nEach line contains key=value pairs separated by ampersands (&) including:\n- transaction_id: Unique identifier for the transaction\n- error_code: Response code (000 = success)\n- auth_response_text: Authorization response description\n- avs_result: Address Verification Service result\n- cvv2_result: Card verification value result\n- auth_code: Authorization code from the processor\n"
                },
                "examples": {
                  "successfulBatch": {
                    "summary": "Successful batch response file",
                    "value": "transaction_id=ce79a48df5733202ad5f533286f6d943&error_code=000&auth_response_text=Approved&avs_result=Y&cvv2_result=M&auth_code=T7997H\ntransaction_id=b2d7bfc52e5f3be0ad2a1845dd9f6235&error_code=000&auth_response_text=Approved&avs_result=Y&cvv2_result=M&auth_code=T8000H\ntransaction_id=4eb67cb684e03f739a51b4eba71daba8&error_code=000&auth_response_text=Approved&avs_result=Y&cvv2_result=M&auth_code=T8004H\ntransaction_id=aaccde8419423723b119bed4d25673a7&error_code=000&auth_response_text=Approved&avs_result=Y&cvv2_result=M&auth_code=T8008H\ntransaction_id=de359cfeca5d389b8d351e3a9fdc0a49&error_code=000&auth_response_text=Approved&avs_result=Y&cvv2_result=M&auth_code=T8012H\n"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid response file ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DownloadErrorResponse"
                },
                "examples": {
                  "invalidFileId": {
                    "summary": "Invalid response file ID",
                    "value": {
                      "userId": "merchant123",
                      "respFileId": "123456789012345",
                      "rspCode": "301",
                      "rspMessage": "Invalid response file ID"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Authentication error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "authError": {
                    "summary": "Authentication error",
                    "value": {
                      "rspCode": "002",
                      "rspMessage": "Authentication Error"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "systemError": {
                    "summary": "System error",
                    "value": {
                      "rspCode": "001",
                      "rspMessage": "System Error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UploadRequest": {
        "type": "object",
        "description": "Request parameters for uploading a batch file.\n\nPer PDF Page 3 - Upload Request Parameters table.\n",
        "required": [
          "reqFile",
          "userId",
          "userPass",
          "profileId"
        ],
        "x-parameterGroups": [
          {
            "name": "Required",
            "fields": [
              "reqFile",
              "userId",
              "userPass",
              "profileId"
            ]
          },
          {
            "name": "Recommended",
            "fields": []
          },
          {
            "name": "Others",
            "fields": [
              "testFlag"
            ]
          }
        ],
        "properties": {
          "reqFile": {
            "type": "string",
            "format": "binary",
            "description": "Contains the transaction file that is being transmitted to ME.\nShould be a text file (.TXT) with transactions formatted as outlined in the ME Payment Gateway Specification.\n\nEach transaction should be on a separate line using the format:\ntransaction_type=P&card_number=XXXXXXXXXXXXXXXX&card_exp_date=MMYY&transaction_amount=X.XX&...\n"
          },
          "userId": {
            "type": "string",
            "description": "ME login ID",
            "maxLength": 32,
            "example": "merchant123"
          },
          "userPass": {
            "type": "string",
            "description": "ME login password",
            "maxLength": 32,
            "format": "password",
            "example": "password123"
          },
          "profileId": {
            "type": "string",
            "description": "The ME gateway profile ID the record is associated with",
            "maxLength": 20,
            "pattern": "^[0-9]+$",
            "example": "12345678901234567890"
          },
          "testFlag": {
            "type": "string",
            "description": "Indicates if the file is a test file or not.\nThe default value is N, but Y can be set in order to send a test file that will route to the ME simulator.\n",
            "maxLength": 1,
            "pattern": "^[YN]$",
            "default": "N",
            "enum": [
              "Y",
              "N"
            ],
            "example": "N"
          }
        }
      },
      "UploadConfirmation": {
        "type": "object",
        "description": "Upload request confirmation parameters returned on successful file upload.\n\nPer PDF Page 4 - Upload Request Confirmation table.\n\n**Implementation Note:** The source PDF shows userPass in this response, which is atypical\nfor API design (credentials should not be echoed in responses). This schema omits userPass\nfor security best practices. Implementers should verify actual API behavior.\n",
        "required": [
          "respFileId",
          "profileId"
        ],
        "x-parameterGroups": [
          {
            "name": "Common",
            "fields": [
              "respFileId",
              "rspCode",
              "rspMessage"
            ]
          },
          {
            "name": "When Provided",
            "fields": [
              "profileId"
            ]
          }
        ],
        "properties": {
          "respFileId": {
            "type": "string",
            "description": "The File ID from the processed batch. Use this ID to download the response file.",
            "maxLength": 15,
            "pattern": "^[0-9]+$",
            "example": "123456789012345"
          },
          "profileId": {
            "type": "string",
            "description": "The ME gateway profile ID the record is associated with",
            "maxLength": 20,
            "pattern": "^[0-9]+$",
            "example": "12345678901234567890"
          },
          "rspCode": {
            "type": "string",
            "description": "Response code (000 indicates success)",
            "maxLength": 3,
            "example": "000"
          },
          "rspMessage": {
            "type": "string",
            "description": "Response message",
            "maxLength": 45,
            "example": "OK"
          }
        }
      },
      "DownloadRequest": {
        "type": "object",
        "description": "Request parameters for downloading a batch response file.\n\nPer PDF Page 6 - Download Request Parameters table.\n",
        "required": [
          "userId",
          "userPass",
          "respFileId"
        ],
        "x-parameterGroups": [
          {
            "name": "Required",
            "fields": [
              "userId",
              "userPass",
              "respFileId"
            ]
          },
          {
            "name": "Recommended",
            "fields": []
          },
          {
            "name": "Others",
            "fields": []
          }
        ],
        "properties": {
          "userId": {
            "type": "string",
            "description": "ME login ID",
            "maxLength": 32,
            "example": "merchant123"
          },
          "userPass": {
            "type": "string",
            "description": "ME login password",
            "maxLength": 32,
            "format": "password",
            "example": "password123"
          },
          "respFileId": {
            "type": "string",
            "description": "The File ID from the processed batch (returned in the upload confirmation)",
            "maxLength": 15,
            "pattern": "^[0-9]+$",
            "example": "123456789012345"
          }
        }
      },
      "DownloadErrorResponse": {
        "type": "object",
        "description": "Error response for download requests. This response is only returned if an error has occurred.\n\nPer PDF Page 6 - Download Request Confirmation table.\nNote: \"This request confirmation is only received if an error has occurred.\"\n",
        "required": [
          "userId",
          "respFileId",
          "rspCode",
          "rspMessage"
        ],
        "x-parameterGroups": [
          {
            "name": "Common",
            "fields": [
              "rspCode",
              "rspMessage"
            ]
          },
          {
            "name": "When Provided",
            "fields": [
              "userId",
              "respFileId"
            ]
          }
        ],
        "properties": {
          "userId": {
            "type": "string",
            "description": "ME login ID (echoed from request)",
            "maxLength": 32,
            "example": "merchant123"
          },
          "respFileId": {
            "type": "string",
            "description": "The File ID from the processed batch (echoed from request)",
            "maxLength": 15,
            "pattern": "^[0-9]+$",
            "example": "123456789012345"
          },
          "rspCode": {
            "type": "string",
            "description": "Three-digit response/error code",
            "maxLength": 3,
            "pattern": "^[0-9]+$",
            "example": "301"
          },
          "rspMessage": {
            "type": "string",
            "description": "Text that accompanies the three-digit response/error code",
            "maxLength": 45,
            "example": "Invalid response file ID"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Standard error response for general errors (authentication, system errors).\n\nUsed when the error occurs before request parameters can be validated/echoed.\n",
        "required": [
          "rspCode",
          "rspMessage"
        ],
        "x-parameterGroups": [
          {
            "name": "Common",
            "fields": [
              "rspCode",
              "rspMessage"
            ]
          }
        ],
        "properties": {
          "rspCode": {
            "type": "string",
            "description": "Three-digit response/error code.\n\n**Error Codes (per PDF Page 9):**\n| Code | Description | Required Action |\n|------|-------------|-----------------|\n| 000 | OK | Batch was successfully received |\n| 001 | System Error | Contact ME for research and resolution |\n| 002 | Authentication Error | Invalid access right or invalid user ID and/or user password |\n| 003 | Invalid Parameter | Check format to correct the invalid parameter |\n| 004 | Missing parameter | Check format for missing parameter |\n| 300 | Invalid Profile ID | Verify Profile ID is correct and resend batch |\n| 301 | Invalid response file ID | Verify that user ID, user password, and file ID are valid and retry |\n| 302 | Invalid test flag | Valid values are Y and N, default is N, field not required |\n| 303 | Batch processing not allowed | Contact ME, batch processing must be enabled for the profile ID used |\n",
            "maxLength": 3,
            "pattern": "^[0-9]+$",
            "enum": [
              "000",
              "001",
              "002",
              "003",
              "004",
              "300",
              "301",
              "302",
              "303"
            ],
            "example": "001"
          },
          "rspMessage": {
            "type": "string",
            "description": "Text that accompanies the three-digit response/error code",
            "maxLength": 45,
            "example": "System Error"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Batch Upload",
      "description": "Operations for uploading batch transaction files"
    },
    {
      "name": "Batch Download",
      "description": "Operations for downloading batch response files"
    }
  ],
  "x-document-info": {
    "original-document": "ME_Batch_Processing_APISpec_March2024.pdf",
    "publication-date": "March 2024",
    "version": "3.0",
    "conversion-notes": "**Issues identified and addressed in this conversion:**\n\n1. **UploadConfirmation schema (PDF Page 4):** The source PDF shows userPass as a required\n   response field. This is atypical for secure API design (credentials should not be echoed\n   in responses). This conversion omits userPass from the confirmation response for security\n   best practices. Implementers should verify actual API behavior.\n\n2. **Download error responses:** The PDF specifies that the Download Request Confirmation\n   (with userId, respFileId, rspCode, rspMessage) is \"only received if an error has occurred.\"\n   This conversion uses separate schemas:\n   - DownloadErrorResponse: For 400 errors where request params can be echoed\n   - ErrorResponse: For 401/500 errors where echoing params may not be appropriate\n\n3. **Response file example (PDF Page 8):** The sample shows truncated field values. The\n   auth_response_text value appears to show \"Match\" which is likely display artifact.\n   This conversion uses \"Approved\" as a more typical authorization response value.\n\n4. **Tags:** Split into \"Batch Upload\" and \"Batch Download\" for clearer API organization\n   rather than single \"Batch Processing\" tag.\n\n5. **Error code mapping to HTTP status:** Added 403 Forbidden for error code 303\n   (batch processing not allowed) as this better represents the semantic meaning.\n",
    "version-history": [
      {
        "date": "October 2017",
        "version": "1.0",
        "changes": "New document"
      },
      {
        "date": "November 2019",
        "version": "2.0",
        "changes": "Applied current MeS-branded template to the document"
      },
      {
        "date": "May 2022",
        "version": "3.0",
        "changes": "Company Information: Updated statement on page ii to include KeyBank; removed mention of SDK libraries in Related Documentation section on page 1.\nBranding: Applied current ME-branded template to the document.\n"
      },
      {
        "date": "April 2023",
        "changes": "Switched to monthly updates.\nRevised template.\n"
      }
    ]
  },
  "x-email-notifications": {
    "file-received": {
      "from": "mesPGbatchprocessing@merchante-solutions.com",
      "subject": "ME Payment Gateway Batch File processing was received",
      "description": "Email sent upon successful receipt of a batch. Sample content:\n\n\"ME Payment Gateway batch file processing has received and prepared your file for processing.\nYou will be receiving a second email with the response data.\"\n"
    },
    "batch-processed": {
      "from": "mesPGbatchprocessing@merchante-solutions.com",
      "subject": "ME Payment Gateway Batch File processing completed",
      "description": "Email sent once the batch has been processed, contains response file attachment and summary statistics.\n\nSample summary format:\n- # of Transaction: 4, $ Amount: $4.00\n- # Approved: 4, $ Approved: $4.00\n- # Declined: 0, $ Declined: $0.00\n",
      "summary-fields": [
        "number-of-transactions",
        "total-amount",
        "number-approved",
        "amount-approved",
        "number-declined",
        "amount-declined"
      ]
    }
  }
}