Create a Smart Transaction

Quickly create a transaction by providing minimum configuration parameters, including:

amount
from Financial Account (source of funds)
to Financial Account (receiver of funds)
processing priority (speed or cost)
paymentReasonId
(optional) date the funds must be delivered by
(optional) transaction schedule

The API will:

Determine the appropriate solution (Push-to-Card, ACH, Wire, or Transfer)
Determine the appropriate transaction type (single-leg, multi-leg, or scheduled)
Create the transaction (and transaction schedule, if applicable)
Return the transaction details including the transaction ID

Endpoint

POST /v1/move-money

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 CONDITIONAL

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

Important The API will not be able to create an ACH transaction if the following parameters are not provided.

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.

fromFinancialAccountId REQUIRED

string (UUID)

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

toFinancialAccountId REQUIRED

string (UUID)

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

processingPriority REQUIRED

string, enum values: SPEED_PRIORITY, COST_PRIORITY

Priority used to determine the best solution for the transaction. The following values are supported:

SPEED_PRIORITY Configure the transaction to achieve the shortest funds delivery time. If multiple solutions provide the same delivery time, the solution with the lowest cost will be used.
COST_PRIORITY Configure the transaction to achieve the lowest cost overall. If multiple solutions provide the same cost, the solution with the fastest delivery time will be used.

fundsDeliveryDate

string (date), format: yyyy-MM-dd

The latest possible date the funds can be delivered.

Note The date is interpreted using the specified timeZone. UTC format is used if timeZone is not provided.

timeZone

string (timeZone), default value: UTC

Time zone for fundsDeliveryDate. The following values are supported:

Z, UTC or GMT UTC
{+,-}N(N)(:MM) Zone offset in hours and minutes
UTC+<offset>, UTC-<offset>, GMT+<offset>, GMT-<offset>

paymentReasonId REQUIRED

string

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

description CONDITIONAL

string, max length: 100

Important The API will not be able to create a Wire transaction if description is not provided.

Required for the Wire solution. Not available for other solutions.

Brief description of the transaction. If the value exceeds the maximum length, the value will be truncated to 100 characters when the transaction is submitted for processing.

schedule

object

Transaction schedule. Use the following parameters to create a one-time or recurring scheduled transaction.

startDateTime REQUIRED

string, pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[01])T([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])(\.[0-9]{1,6})?$

Date and time to initiate the schedule. Must be provided in the following ISO 8601 format without the time zone designator:

year-month-dayThours:minutes:seconds[.fractions-of-second]

where:

year is four digits
month is two digits
day is two digits
T is the literal “T” character used to delimit a date portion from a time portion
hours is two digits representing the number of hours from 00 to 23
minutes is two digits representing the number of minutes from 00 to 59
seconds is two digits representing the number of seconds from 00 to 59
fractions-of-second (optional) is one or more digits representing a fraction of a second

Example: 2023‐08‐31T15:53:00.123

The date will be interpreted using the timeZone parameter, and UTC format will be used if timeZone is not provided.

For recurring transactions, this is the date and time when the recurrenceRule will take effect. For example, let’s say a request has the following parameters:

"startDateTime": "2023-08-31T12:00:00",

"recurrenceRule: "FREQ=WEEKLY;BYDAY=MO"

In this example, the start date is on a Thursday and the recurrence rule is weekly executions each Monday. Therefore the first transaction will be created on Monday, September 4th, at 12:00 pm in the specified time zone.

recurrenceRule

string

Rule used to schedule transactions on a recurring basis. Must be specified using the IETF iCalendar RFC 5545 RRULE property.

For example, let’s say a request has the following parameters:

"timeZone": "America/New_York",

"startDateTime": "1997-09-02T09:00:00",

"recurrenceRule": "FREQ=DAILY;UNTIL=19971224T000000"

This request will create transactions at the following times:

September 2, 1997 to October 25, 1997 (inclusive) at 9:00 AM EDT

October 26, 1997 to December 23, 1997 (inclusive) at 9:00 AM EST

amount REQUIRED

string (decimal)

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

externalTransactionInitiatorId

string

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

initiatorAccountHolderId

string (UUID)

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

Returns

Returns the Smart Transaction object.

SAMPLE REQUEST

				
					{
  "metadata": {
    "rkorACHEntryType": "CCD",
    "myPaymentId": "100000333",
    "invoiceNumber": "123232333",
    "authorizedBy": "user@email.com"
  },
  "fromFinancialAccountId": "6a017f06-83a3-44b7-be6f-5e5cae4a9ed7",
  "toFinancialAccountId": "4py56a34-4686-1539-c2ga-1a723g55dlq3",
  "processingPriority": "COST_PRIORITY",
  "fundsDeliveryDate": "2025-03-11",
  "timeZone": "GMT-4",
  "paymentReasonId": "bill-payment",
  "description": "",
  "schedule": {
    "startDateTime": "",
    "recurrenceRule": ""
  },
  "amount": "100.00",
  "externalTransactionInitiatorId": "c62d1e6b-39ce-496e-bf6d-8a019d2f534e",
  "initiatorAccountHolderId": "ebfa3e16-63c4-48e3-ae59-a3194a867269"
}

SAMPLE RESPONSE

				
					{
  "entityId": "84bb491c-5def-4bee-a16d-1b7f511b0e4a",
  "entityType": "SINGLE_TRANSACTION",
  "_embedded": {
    "transaction": {
      "businessAccountId": "de30132c-e67a-4af7-89ec-f2109863b7f7",
      "metadata": {
        "rkorACHEntryType": "CCD",
        "myPaymentId": "100000333",
        "invoiceNumber": "123232333",
        "authorizedBy": "user@email.com"
      },
      "debitFinancialAccountId": "6a017f06-83a3-44b7-be6f-5e5cae4a9ed7",
      "creditFinancialAccountId": "4py56a34-4686-1539-c2ga-1a723g55dlq3",
      "transactionType": "SEND",
      "solution": "ach",
      "paymentReasonId": "bill-payment",
      "paymentReason": "Bill payment",
      "amount": "1000.00",
      "currency": "USD",
      "settlementPriority": "SAME_DAY",
      "createdAt": "2025-03-01T17:40:22.601Z",
      "createdBy": {
        "id": "b6333b53-3222-4227-a71e-718b25ca3ea4",
        "type": "service-account"
      },
      "description": "",
      "memo": "",
      "initiatorAccountHolderId": "ebfa3e16-63c4-48e3-ae59-a3194a867269",
      "externalTransactionInitiatorId": "c62d1e6b-39ce-496e-bf6d-8a019d2f534e",
      "originatingChannel": "EXTERNAL",
      "id": "2av81w47-9367-1295-h4ng-1q520p28wfn1",
      "latestStatus": {
        "status": "NEW",
        "message": "Transaction creation successful",
        "createdBy": {
          "id": "b6333b53-3222-4227-a71e-718b25ca3ea4",
          "type": "service-account"
        },
        "createdAt": "2025-03-01T17:40:22.601Z"
      },
      "reversalReason": ""
    }
  }
}