{ "openapi": "3.0.3", "info": { "title": "MerchantE Split Funding API", "description": "The Split Funding API enables partners' businesses to split their daily settlement amount into two different bank accounts.\n\nThis API allows creation or modification of MerchantFundingAmount for approved, non-PIN-debit, cardholder-debit or credit Transactions.\n\n**Documentation Resources:**\n- MerchantE Technical Documentation: https://anypoint.mulesoft.com/exchange/portals/merchante-solutions-3/\n- PCI Security Standards: https://www.pcisecuritystandards.org/\n- NAICS Lookup: https://www.census.gov/econ/isp/\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", "version": "1.2", "contact": { "name": "MerchantE Support", "url": "https://www.merchante.com" }, "x-address": { "street": "1150 Sanctuary Parkway, Suite 300", "city": "Alpharetta", "state": "GA", "zip": "30009" } }, "servers": [ { "url": "https://{host}{basePath}", "description": "API server. The PDF specifies the resource as [root]/funding-amounts; verify the host and any base path (for example, /v1) with MerchantE.", "variables": { "host": { "default": "test.api.merchante.com", "description": "Hostname for the test/certification environment." }, "basePath": { "default": "", "description": "Optional base path if your environment uses versioned routing (for example, /v1).", "enum": [ "", "/v1" ] } } } ], "paths": { "/funding-amounts": { "post": { "summary": "Create or modify funding amounts", "description": "Used to create or modify MerchantFundingAmount for approved, non-PIN-debit, cardholder-debit or credit Transactions.\n\n**Request Constraints:**\n- Can contain 1 to 10,000 Transaction(s)\n- Must not contain any debit Transactions that have been settled\n- Can contain credit transactions that have been settled\n- Must not contain duplicate Transactions\n- Debit transactions can be specified by either retrievalReferenceNumber or id (transactionId), but not both\n- Credit transactions can only be specified by id (transactionId)\n\n**HTTP Status Code Evaluation:**\nStatus Code conditions are assessed in the following order, and the first matching condition determines the response:\n1. 400 - Request body issues\n2. 401 - Authentication failure\n3. 403 - Profile inactive\n4. 500 - Server error\n5. 200 - Success (none of above conditions met)\n", "operationId": "createFundingAmounts", "tags": [ "Funding Amounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingAmountsRequest" }, "examples": { "twoTransactions": { "summary": "Two transactions with split funding", "value": { "transactions": [ { "id": "ABC12345678901234567890123456789", "merchantFundingAmounts": [ { "merchantId": "9999999999", "amount": "10000" }, { "merchantId": "8888888888", "amount": "500" } ] }, { "id": "XYZ12345678901234567890123456789", "merchantFundingAmounts": [ { "merchantId": "9999999999", "amount": "10000" }, { "merchantId": "8888888888", "amount": "500" } ] } ] } }, "usingRRN": { "summary": "Debit transaction using retrievalReferenceNumber", "value": { "transactions": [ { "retrievalReferenceNumber": "123456789012", "merchantFundingAmounts": [ { "merchantId": "9999999999", "amount": "5000" }, { "merchantId": "8888888888", "amount": "2500" } ] } ] } } } } } }, "responses": { "200": { "description": "Request processed successfully.\n\n**Note:** A 200 response may still contain transaction-level errors in the transactionLevelErrors array.\nCheck successfulTransactionCount vs transactionCount to determine if all transactions succeeded.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingAmountsResponse" }, "examples": { "successWithError": { "summary": "Partial success with one transaction error", "value": { "transactionCount": "2", "merchantFundingAmountCount": "4", "amountsSum": "21000", "successfulTransactionCount": "1", "errorCode": "", "errorMessage": "", "transactionLevelErrors": [ { "transactionId": "XYZ12345678901234567890123456789", "retrievalReferenceNumber": "", "errorCode": "100", "errorMessage": "unknown transactionId" } ] } }, "allSuccess": { "summary": "All transactions processed successfully", "value": { "transactionCount": "2", "merchantFundingAmountCount": "4", "amountsSum": "21000", "successfulTransactionCount": "2", "errorCode": "", "errorMessage": "", "transactionLevelErrors": [] } }, "requestLevelError": { "summary": "Request-level error (duplicate transactions)", "value": { "transactionCount": "2", "merchantFundingAmountCount": "4", "amountsSum": "21000", "successfulTransactionCount": "0", "errorCode": "3", "errorMessage": "Duplicate transactions in request", "transactionLevelErrors": [] } } } } } }, "400": { "description": "Bad Request - Request body cannot be processed.\n\n**Conditions:**\n- Unsupported content type\n- Malformed body\n- Values exceeding the max field size\n- Values of incorrect data type\n- Too many or not enough records\n\n**Note:** No response body is provided for this error.\n" }, "401": { "description": "Unauthorized - Authentication failure.\n\n**Conditions:**\n- The provided profileId is unknown\n- The provided profileKey is incorrect for the provided profileId\n\n**Note:** No response body is provided for this error.\n" }, "403": { "description": "Forbidden - Profile inactive.\n\n**Conditions:**\n- The provided profileId and profileKey is known and correct\n- But the profileId is associated with a profile that is no longer active (suspended or closed)\n\n**Note:** No response body is provided for this error.\n" }, "500": { "description": "Internal Server Error - The server encountered an unexpected error and could not process the request.\n\n**Note:** No response body is provided for this error.\n" } } } } }, "components": { "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic", "description": "The Authorization field contains the credentials of the client making the request and uses the 'Basic' HTTP Authentication Scheme.\n\nThe value in the Authorization field has the following format:\n`Basic [encoded credentials]`\n\nWhere [encoded credentials] is constructed as follows:\n1. The **profileId** and **profileKey** of the Terminal making the request are combined with a colon separating the two values\n2. The resulting string is encoded using base-64\n3. The resulting encoded string is appended to the literal 'Basic '\n\n**Example:** `Basic cHJvZmlsZUlkOnByb2ZpbGVLZXk=`\n" } }, "schemas": { "FundingAmountsRequest": { "type": "object", "description": "Request body for the Funding Amounts endpoint.\n\nContains one or more Transaction objects, each with one or more MerchantFundingAmount objects.\n", "required": [ "transactions" ], "properties": { "transactions": { "type": "array", "description": "Array of Transaction objects (1 to 10,000 transactions allowed)", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/Transaction" } } }, "x-parameterGroups": [ { "name": "Required", "fields": [ "transactions" ] }, { "name": "Recommended", "fields": [] }, { "name": "Others", "fields": [] } ] }, "Transaction": { "oneOf": [ { "$ref": "#/components/schemas/TransactionById" }, { "$ref": "#/components/schemas/TransactionByRetrievalReferenceNumber" } ], "description": "Transaction identifier. For debit transactions, specify either `id` or `retrievalReferenceNumber` (but not both). For credit transactions, specify `id`.", "x-parameterGroups": [ { "name": "Required", "fields": [ "merchantFundingAmounts", "id OR retrievalReferenceNumber" ] }, { "name": "Recommended", "fields": [] }, { "name": "Others", "fields": [] } ] }, "MerchantFundingAmount": { "type": "object", "description": "Used to specify a Merchant and the amount the Merchant should be funded/debited for a given Transaction.\n\n**Constraints:**\n- A Transaction can contain 1 to 10 MerchantFundingAmount(s)\n- For a given Transaction, merchantId must be unique (no duplicate merchantIds)\n- The sum of all amounts must equal the transaction amount\n", "required": [ "merchantId", "amount" ], "properties": { "merchantId": { "type": "string", "description": "ME's unique identifier of the Merchant that will be funded the specified amount for the corresponding Transaction.\n\nFor a given Transaction, merchantId must be unique.\n", "maxLength": 16, "pattern": "^[0-9]+$", "example": "9999999999" }, "amount": { "type": "string", "description": "The unsigned amount (> 0) the corresponding Merchant should be funded/debited for the corresponding Transaction.\n\n**Currency:** The currency of the amount is implied and is the same as the currency of the corresponding Transaction.\n\n**Decimal Position:** The location of the decimal point is implied based on the minor units of the currency of the corresponding Transaction.\n\n**Example:** If the currency of the Transaction is USD, then an amount of \"100\" is interpreted as 1.00 USD.\n\n**Sum Requirement:** The sum of all amount(s) of a given MerchantFundingAmount must equal:\n- The current authorized amount (if Transaction has not been captured for settlement)\n- The settlement amount (if Transaction has been captured but not yet settled)\n", "maxLength": 9, "pattern": "^(?!0+$)[0-9]+$", "example": "10000" } }, "x-parameterGroups": [ { "name": "Required", "fields": [ "merchantId", "amount" ] }, { "name": "Recommended", "fields": [] }, { "name": "Others", "fields": [] } ] }, "FundingAmountsResponse": { "type": "object", "description": "The response body for the Funding Amounts endpoint.\n\nContains fields that summarize the request, request-level error fields, and zero or many TransactionLevelError objects.\n\n**Important:** When the response contains HTTP Status Code other than 200, a body will NOT be provided in the response.\n", "required": [ "transactionCount", "merchantFundingAmountCount", "amountsSum", "successfulTransactionCount", "transactionLevelErrors" ], "properties": { "transactionCount": { "type": "string", "description": "The number of Transactions specified in the corresponding request.", "maxLength": 6, "pattern": "^[0-9]+$", "example": "2" }, "merchantFundingAmountCount": { "type": "string", "description": "The number of MerchantFundingAmount(s) specified in the corresponding request.", "maxLength": 7, "pattern": "^[0-9]+$", "example": "4" }, "amountsSum": { "type": "string", "description": "The hash sum of amount(s) for all MerchantFundingAmount(s) specified in the corresponding request.\n\n**Note:** Since the request could contain Transactions in more than one currency, the value of amountsSum should NOT be interpreted as a monetary sum of amounts with a single currency.\n", "maxLength": 15, "pattern": "^[0-9]+$", "example": "21000" }, "successfulTransactionCount": { "type": "string", "description": "The number of Transactions specified in the corresponding request that did not contain errors and that were processed successfully.", "maxLength": 6, "pattern": "^[0-9]+$", "example": "1" }, "errorCode": { "type": "string", "description": "Specifies a client error that occurred at the request level.\n\nWhen an error occurs at the request level, the value of successfulTransactionCount will be zero.\nWhen no error occurs at the request level, no value for errorCode and errorMessage will be provided in the response.\n\n**Request-Level Error Codes:**\n| Code | Condition |\n|------|-----------|\n| 1 | Both retrievalReferenceNumber and transactionId were provided for a Transaction |\n| 2 | Neither retrievalReferenceNumber nor transactionId were provided for a Transaction |\n| 3 | Duplicate Transactions are specified in the request |\n", "maxLength": 3, "pattern": "^[0-9]*$", "enum": [ "", "1", "2", "3" ], "example": "", "default": "" }, "errorMessage": { "type": "string", "description": "A human-readable description of the corresponding errorCode.\n\n**Warning:** For a given error code, there is no guarantee of what the corresponding errorMessage will be. Thus, no programming decisions should be made based on this value.\n", "maxLength": 200, "example": "", "default": "" }, "transactionLevelErrors": { "type": "array", "description": "Array of transaction-level errors. Contains zero or many TransactionLevelError objects.\n\nEach error in this array corresponds to a transaction that failed to process.\n", "items": { "$ref": "#/components/schemas/TransactionLevelError" } } }, "x-parameterGroups": [ { "name": "Common", "fields": [ "transactionCount", "successfulTransactionCount" ] }, { "name": "When Provided", "fields": [ "errorCode", "errorMessage", "transactionLevelErrors" ] }, { "name": "Other Fields", "fields": [ "merchantFundingAmountCount", "amountsSum" ] } ] }, "TransactionLevelError": { "type": "object", "description": "Specifies an error that occurred at the Transaction level.\n\nAn error that occurred at Transaction level results in the failure to process all MerchantFundingAmount(s) for the Transaction that contained the error.\n\nFor each Transaction level error that occurs, the value of successfulTransactionCount will be decremented by one from transactionCount.\n", "required": [ "errorCode", "errorMessage" ], "properties": { "transactionId": { "type": "string", "description": "If a transactionId (id) was provided in the request to specify the Transaction, this field will contain the transactionId of the Transaction that was provided in the request that contains the error; otherwise, no value will be provided in this field.\n", "maxLength": 32, "pattern": "^[a-zA-Z0-9]*$", "example": "XYZ12345678901234567890123456789" }, "retrievalReferenceNumber": { "type": "string", "description": "If a retrievalReferenceNumber was provided in the request to specify the Transaction, this field will contain the retrievalReferenceNumber of the Transaction that was provided in the request that contains the error; otherwise, no value will be provided in this field.\n", "maxLength": 12, "pattern": "^[0-9]*$", "example": "" }, "errorCode": { "type": "string", "description": "Specifies a client error that occurred at the Transaction level.\n\n**Transaction-Level Error Codes (evaluated in order):**\n| Code | Condition |\n|------|-----------|\n| 100 | Unknown transactionId/retrievalReferenceNumber, or Transaction is not approved non-PIN-debit/cardholder-debit/credit initiated by the Profile |\n| 101 | Debit Transaction has already been settled |\n| 102 | Unknown merchantId or Merchant is no longer active |\n| 103 | Duplicate merchantId(s) in MerchantFundingAmount |\n| 104 | Amount is not greater than zero |\n| 105 | Sum of amounts does not equal authorized/settlement amount |\n\n**Note:** Error code conditions are assessed in the order listed above. The errorCode returned will be that of the first condition encountered.\n", "maxLength": 3, "pattern": "^[0-9]+$", "enum": [ "100", "101", "102", "103", "104", "105" ], "example": "100" }, "errorMessage": { "type": "string", "description": "A human-readable description of the corresponding errorCode.\n\n**Warning:** For a given error code, there is no guarantee of what the corresponding errorMessage will be. Thus, no programming decisions should be made based on this value.\n", "maxLength": 200, "example": "unknown transactionId" } }, "x-parameterGroups": [ { "name": "Required", "fields": [ "errorCode", "errorMessage" ] }, { "name": "Recommended", "fields": [ "transactionId", "retrievalReferenceNumber" ] }, { "name": "Others", "fields": [] } ] }, "TransactionById": { "type": "object", "description": "Used to specify an approved, non-PIN-debit, cardholder-debit or cardholder-credit Transaction that has corresponding MerchantFundingAmount(s).\n\n**Constraints:**\n- A Funding Amounts Request can contain 1 to 10,000 Transaction(s)\n- A Funding Amounts Request must not contain any debit Transactions that have been settled\n- A Funding Amounts Request that has credit transactions can contain transactions that have been settled\n- A Funding Amounts Request must not contain the same Transaction more than once (i.e. no duplicate Transactions)\n- Debit transactions can be specified by either retrievalReferenceNumber or id (transactionId), but not both\n- Credit transactions can only be specified by id (transactionId)\n\n**Field Usage:**\n- Use `id` OR `retrievalReferenceNumber`, not both\n- For debit transactions: either field may be used\n- For credit transactions: only `id` may be used\n\n\nUse this form when specifying the Transaction by ME-generated transactionId (`id`). Required for credit transactions; allowed for debit transactions.", "required": [ "id", "merchantFundingAmounts" ], "properties": { "id": { "type": "string", "nullable": false, "description": "A value generated by ME for each authorization request.\n\nAlso referred to as transactionId in error responses.\n\n**Note:** For a debit transaction, provide either id OR retrievalReferenceNumber, not both.\nFor a credit transaction, only id may be used.\n", "maxLength": 32, "pattern": "^[a-zA-Z0-9]{1,32}$", "example": "ABC12345678901234567890123456789" }, "merchantFundingAmounts": { "type": "array", "description": "Array of MerchantFundingAmount objects (1 to 10 per transaction).\n\nThe sum of all amounts must equal the transaction's authorized amount (if not captured) \nor settlement amount (if captured but not settled).\n", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/MerchantFundingAmount" } } }, "additionalProperties": false, "x-parameterGroups": [ { "name": "Required", "fields": [ "id", "merchantFundingAmounts" ] }, { "name": "Recommended", "fields": [] }, { "name": "Others", "fields": [] } ] }, "TransactionByRetrievalReferenceNumber": { "type": "object", "description": "Used to specify an approved, non-PIN-debit, cardholder-debit or cardholder-credit Transaction that has corresponding MerchantFundingAmount(s).\n\n**Constraints:**\n- A Funding Amounts Request can contain 1 to 10,000 Transaction(s)\n- A Funding Amounts Request must not contain any debit Transactions that have been settled\n- A Funding Amounts Request that has credit transactions can contain transactions that have been settled\n- A Funding Amounts Request must not contain the same Transaction more than once (i.e. no duplicate Transactions)\n- Debit transactions can be specified by either retrievalReferenceNumber or id (transactionId), but not both\n- Credit transactions can only be specified by id (transactionId)\n\n**Field Usage:**\n- Use `id` OR `retrievalReferenceNumber`, not both\n- For debit transactions: either field may be used\n- For credit transactions: only `id` may be used\n\n\nUse this form when specifying a debit Transaction by retrievalReferenceNumber. Not valid for credit transactions.", "required": [ "retrievalReferenceNumber", "merchantFundingAmounts" ], "properties": { "retrievalReferenceNumber": { "type": "string", "nullable": false, "description": "A value generated by ME for each new authorization request.\n\n**Note:** For a debit transaction, provide either retrievalReferenceNumber OR id, not both.\nCannot be used for credit transactions.\n", "maxLength": 12, "pattern": "^[0-9]{1,12}$", "example": "123456789012" }, "merchantFundingAmounts": { "type": "array", "description": "Array of MerchantFundingAmount objects (1 to 10 per transaction).\n\nThe sum of all amounts must equal the transaction's authorized amount (if not captured) \nor settlement amount (if captured but not settled).\n", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/MerchantFundingAmount" } } }, "additionalProperties": false, "x-parameterGroups": [ { "name": "Required", "fields": [ "retrievalReferenceNumber", "merchantFundingAmounts" ] }, { "name": "Recommended", "fields": [] }, { "name": "Others", "fields": [] } ] } } }, "tags": [ { "name": "Funding Amounts", "description": "Operations for creating and modifying merchant funding amounts for split settlement" } ], "x-document-info": { "original-document": "ME_Split_Funding_API_Specification_March2024.pdf", "publication-date": "March 2024", "version": "1.0", "conversion-notes": "**Issues identified and addressed in this conversion:**\n\n1. **Pattern corrections for nullable fields:** Changed patterns from `'^[a-zA-Z0-9]+$'` and \n `'^[0-9]+$'` to `'^[a-zA-Z0-9]*$'` and `'^[0-9]*$'` for nullable string fields \n (Transaction.id, Transaction.retrievalReferenceNumber, TransactionLevelError.transactionId,\n TransactionLevelError.retrievalReferenceNumber). This allows empty strings when the \n field is not provided.\n\n2. **Server URL clarification:** Added notes that server URLs are assumed values since the \n PDF only specifies \"[root]/funding-amounts\" without defining the actual base URL.\n Users should verify with MerchantE documentation.\n\n3. **HTTP Status Code evaluation order:** Added explicit documentation that status codes \n are evaluated in order (400 → 401 → 403 → 500 → 200) per PDF Page 5.\n\n4. **Transaction-level error code evaluation order:** Added explicit documentation that \n error codes are evaluated in order (100 → 101 → 102 → 103 → 104 → 105) per PDF Page 8.\n\n5. **Field naming clarification:** The PDF uses `id` in the request but `transactionId` in \n the response errors. Added clarifying notes to the Transaction.id field description.\n\n6. **Added additional examples:** Added example showing use of retrievalReferenceNumber \n for debit transactions, and example of request-level error response.\n\n**Note on PDF sample JSON:** The sample request body in the PDF (Page 4) contains invalid \nJSON syntax (missing commas between array elements). The OpenAPI examples correct this.\n", "version-history": [ { "date": "May 2022", "version": "1.0", "changes": "New document" }, { "date": "April 2023", "changes": "Switched to Monthly Review" } ], "portal-optimized": { "date": "2026-02-26", "changes": [ "Removed hard-coded /v1 from servers; use variables for host/basePath (PDF specifies [root]/funding-amounts).", "Added x-parameterGroups (Required/Recommended/Others) for portal UX.", "Modeled Transaction identifier as oneOf(TransactionById | TransactionByRetrievalReferenceNumber) to enforce “either/or”.", "Cleaned request examples to match oneOf variants (no null placeholder fields).", "Ensured transactionLevelErrors is always present (empty array when no errors)." ] }, "portal-optimized-version": "v1.2" } }