MerchantE API Docs
POST/funding-amounts
Download OpenAPI (this endpoint)JSON|Download OpenAPI (generated)JSON

Create or modify funding amounts

Used to create or modify MerchantFundingAmount for approved, non-PIN-debit, cardholder-debit or credit Transactions.

Request Constraints:

  • Can contain 1 to 10,000 Transaction(s)
  • Must not contain any debit Transactions that have been settled
  • Can contain credit transactions that have been settled
  • Must not contain duplicate Transactions
  • Debit transactions can be specified by either retrievalReferenceNumber or id (transactionId), but not both
  • Credit transactions can only be specified by id (transactionId)

HTTP Status Code Evaluation: Status Code conditions are assessed in the following order, and the first matching condition determines the response:

  1. 400 - Request body issues
  2. 401 - Authentication failure
  3. 403 - Profile inactive
  4. 500 - Server error
  5. 200 - Success (none of above conditions met)

Request Body

Content type: application/json

Required1 field
transactionsarray<object>
Array of Transaction objects (1 to 10,000 transactions allowed)
minItems=1 · maxItems=10000

Example Request

Sample payload with starter values. Replace with your own data.

{
  "transactions": [
    {
      "id": "ABC12345678901234567890123456789",
      "merchantFundingAmounts": [
        {
          "merchantId": "9999999999",
          "amount": "10000"
        },
        {
          "merchantId": "8888888888",
          "amount": "500"
        }
      ]
    },
    {
      "id": "XYZ12345678901234567890123456789",
      "merchantFundingAmounts": [
        {
          "merchantId": "9999999999",
          "amount": "10000"
        },
        {
          "merchantId": "8888888888",
          "amount": "500"
        }
      ]
    }
  ]
}

Responses

200
Request processed successfully

Request processed successfully.

Note: A 200 response may still contain transaction-level errors in the transactionLevelErrors array. Check successfulTransactionCount vs transactionCount to determine if all transactions succeeded.

Common2 fields
transactionCountstring
The number of Transactions specified in the corresponding request.
pattern=^[0-9]+$ · maxLength=6
successfulTransactionCountstring
The number of Transactions specified in the corresponding request that did not contain errors and that were processed successfully.
pattern=^[0-9]+$ · maxLength=6
When Provided3 fields
errorCodestringenum
Specifies a client error that occurred at the request level.
When an error occurs at the request level, the value of successfulTransactionCount will be zero.
When no error occurs at the request level, no value for errorCode and errorMessage will be provided in the response.
**Request-Level Error Codes:**
| Code | Condition |
|------|-----------|
| 1 | Both retrievalReferenceNumber and transactionId were provided for a Transaction |
| 2 | Neither retrievalReferenceNumber nor transactionId were provided for a Transaction |
| 3 | Duplicate Transactions are specified in the request |
pattern=^[0-9]*$ · maxLength=3
errorMessagestring
A human-readable description of the corresponding errorCode.
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.
maxLength=200
transactionLevelErrorsarray<object>
Array of transaction-level errors. Contains zero or many TransactionLevelError objects.
Each error in this array corresponds to a transaction that failed to process.
Other Fields2 fields
merchantFundingAmountCountstring
The number of MerchantFundingAmount(s) specified in the corresponding request.
pattern=^[0-9]+$ · maxLength=7
amountsSumstring
The hash sum of amount(s) for all MerchantFundingAmount(s) specified in the corresponding request.
**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.
pattern=^[0-9]+$ · maxLength=15

Example response

{
  "transactionCount": "2",
  "merchantFundingAmountCount": "4",
  "amountsSum": "21000",
  "successfulTransactionCount": "1",
  "errorCode": "",
  "errorMessage": "",
  "transactionLevelErrors": [
    {
      "transactionId": "XYZ12345678901234567890123456789",
      "retrievalReferenceNumber": "",
      "errorCode": "100",
      "errorMessage": "unknown transactionId"
    }
  ]
}
400
Bad Request - Request body cannot be processed

Bad Request - Request body cannot be processed.

Conditions:

  • Unsupported content type
  • Malformed body
  • Values exceeding the max field size
  • Values of incorrect data type
  • Too many or not enough records

Note: No response body is provided for this error.

401
Unauthorized - Authentication failure

Unauthorized - Authentication failure.

Conditions:

  • The provided profileId is unknown
  • The provided profileKey is incorrect for the provided profileId

Note: No response body is provided for this error.

403
Forbidden - Profile inactive

Forbidden - Profile inactive.

Conditions:

  • The provided profileId and profileKey is known and correct
  • But the profileId is associated with a profile that is no longer active (suspended or closed)

Note: No response body is provided for this error.

500
Internal Server Error - The server encountered an unexpected error and could not process the request

Internal Server Error - The server encountered an unexpected error and could not process the request.

Note: No response body is provided for this error.

Code samples

Copy-paste ready code in your preferred language.

API call

Copy/paste friendly
curl -X POST "https://{host}{basePath}/funding-amounts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64(profileId:profileKey)>" \
  -d '{
  "transactions": [
    {
      "id": "ABC12345678901234567890123456789",
      "merchantFundingAmounts": [
        {
          "merchantId": "9999999999",
          "amount": "10000"
        },
        {
          "merchantId": "8888888888",
          "amount": "500"
        }
      ]
    },
    {
      "id": "XYZ12345678901234567890123456789",
      "merchantFundingAmounts": [
        {
          "merchantId": "9999999999",
          "amount": "10000"
        },
        {
          "merchantId": "8888888888",
          "amount": "500"
        }
      ]
    }
  ]
}'