Create a Transaction Batch

Submit multiple transactions as a batch. You can submit a maximum of 10,000 transactions in a single request. Transactions will be validated and processed as individual transactions.

Endpoint

POST /v1/transaction-batches

Authorization Header

Authorization: Bearer <access_token>

Idempotency-Key Header

Idempotency-Key: <key>

where <key> is a v4 UUID or any other unique string with a minimum length of 6 characters and a maximum length of 255 characters.

The idempotency key identifies the request. If a network error occurs, you can safely retry the request using the same idempotency key and the request will only be executed once. This ensures that calling the API multiple times will not result in duplicate requests. For more information, see Idempotent Calls.

Request Body

metadata

string, max items: 6, value max length: 1024

Key/value pairs to store additional information with a transaction batch.

transactionType REQUIRED

string enum, values: SEND, REQUEST

Type of transaction. The following values are supported:

SEND Push funds from the debit Financial Account to the credit Financial Account.

For example, a SEND transaction would be used if a Business Account (owner of the debit Financial Account) is sending a refund to a Customer (owner of the credit Financial Account).
REQUEST Pull funds to the credit Financial Account from the debit Financial Account.

For example, a REQUEST transaction would be used if a Business Account (owner of the credit Financial Account) is collecting a rent payment from a Customer (owner of the debit Financial Account).

batchMode

string enum, values: RELAXED, STRICT

default value: RELAXED

Batch mode. The following values are supported:

RELAXED RocketKOR will validate the request header only and not the transaction line items. Individual transactions may be rejected based on validation rules.
STRICT RocketKOR applies zero-tolerance validation rules on the request header as well as the transaction line items. If one of the validation rules fail, the entire batch will be rejected.

solution REQUIRED

string

Name of the RocketKOR solution used for the transaction batch.

initiatorAccountHolderId

string (UUID)

ID of the RocketKOR account that initiated the transaction batch. This can be a Business Account or a Customer Account.

externalTransactionInitiatorId

string

External identifier. Can be used to capture your internal ID for the user that initiated the transaction batch on the client application.

description REQUIRED

string

Description of the transaction batch.

settlementPriority

string enum, values: IMMEDIATE, SAME_DAY, NEXT_DAY, SCHEDULED

Expected priority for settling the transactions in the batch. The following values are supported:

IMMEDIATE Near real-time.
SAME_DAY Same business day.
NEXT_DAY Next business day.
SCHEDULED Reserved for future use.

This parameter is configurable for some RocketKOR solutions, such as ACH and Wire.

Notes:

Push-to-Card transactions always use the IMMEDIATE settlement priority.
Wire transactions only allow the SAME_DAY and NEXT_DAY settlement priorities.

currency REQUIRED

string

Currency used for the transactions in the batch. Must be an ISO 4217 alpha 3-character currency code.

transactionCount REQUIRED

integer (int32)

Total number of transactions in the batch.

totalAmount REQUIRED

string (currency)

Total amount of all transactions in the batch.

transactions

object

Transactions in the batch.

metadata CONDITIONAL

string, max items: 6, value max length: 1024

Key/value pairs used to store additional information about the transaction. ACH transactions must include one or more of the following metadata parameters.

Parameter	Description
rkorACHEntryType	Required for all ACH transactions. ACH Standard Entry Class (SEC) code. The following codes are supported. For more information, see ACH File Details. ARC Accounts Receivable Entry BOC Back Office Conversion CCD Cash Concentration or Disbursement CIE Customer Initiated Entry CTX Corporate Trade Exchange IAT International POP Point of Purchase Entry PPD Prearranged Payment and Deposit Entry RCK Re-Presented Check Entry TEL Telephone-Initiated Entry WEB Internet Initiated Entry
rkorACHIndividualId	Required if rkorACHEntryType is CIE, PPD, or TEL. Individual Identification Number.
rkorACHCheckSerialNumber	Required if rkorACHEntryType is ARC, BOC, POP, or RCK. Serial number of the check from a Converted Check Copy.
rkorACHTerminalCity	Required if rkorACHEntryType is POP. Terminal city.
rkorACHTerminalState	Required if rkorACHEntryType is POP. Terminal state.

The following metadata parameters are returned in the response.

Parameter	Description
rkorProvider	ACH Provider. Possible values are PAYGEARS and SNB.
rkorReasonCode	Return Reason Code. Present in RETURN transaction responses.
rkorReasonDescription	Return Reason Description. Present in RETURN transaction responses.
rkorDiscretionaryData	Return Transaction Identifier. Present in RETURN transaction responses.

debitFinancialAccountId REQUIRED

string (UUID)

ID of the Financial Account used as the debit account (source of funds) for the transaction.

creditFinancialAccountId REQUIRED

string (UUID)

ID of the Financial Account used as the credit account (receiver of funds) for the transaction.

paymentReasonId REQUIRED

string

ID representing the payment reason for the transaction. Use the Payment Reasons API to retrieve a list of available IDs.

amount REQUIRED

string (currency)

Transaction amount. The amount must conform to any transaction limits.

Returns

The URI of the newly created transaction batch is returned in the Location header.

SAMPLE REQUEST

				
					{
  "metadata": {
    "department": "billing"
  },
  "transactionType": "SEND",
  "batchMode": "RELAXED",
  "solution": "ach",
  "initiatorAccountHolderId": "ebfa3e16-63c4-48e3-ae59-a3194a867269",
  "externalTransactionInitiatorId": "c62d1e6b-39ce-496e-bf6d-8a019d2f534e",
  "description": "This is a batch",
  "settlementPriority": "SAME_DAY",
  "currency": "USD",
  "transactionCount": 5000,
  "totalAmount": "52450.26",
  "transactions": [
    {
      "metadata": {
        "rkorACHEntryType": "CCD",
        "myPaymentId": "100000333",
        "invoiceNumber": "123232333",
        "authorizedBy": "user@email.com"
      },
      "debitFinancialAccountId": "00303bff-29af-4213-bc7d-d9127a16927e",
      "creditFinancialAccountId": "cf2944c7-465b-427c-b933-4d33526b391a",
      "paymentReasonId": "loan-payments",
      "amount": "250.00"
    },
    {...},
    {...}
  ]
}

SAMPLE RESPONSE

				
					{
  201 Batch created successfully. Batch resource URI is returned in the Location header.
}