Create a Scheduled Transaction

Create a scheduled transaction that will be automatically executed at a future date and time. You can create a one-time scheduled transaction or a series of recurring scheduled transactions.

A transaction requires two Financial Accounts: a debit account and a credit account. These accounts must belong to the Business Account associated with the request access token.

Debit Financial Account
The funds will be taken from this account. The debit account can be a Business Financial Account or a Customer Financial Account.

Credit Financial Account
The funds will be transferred to this account. The credit account can be a Business Financial Account, a Recipient Financial Account, or a Customer Financial Account.

Endpoint

POST /v1/scheduled-transactions

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 items: 6, value max length: 1024

Use a maximum of 6 key/value pairs to store additional information with a 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 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. Check Serial Number.
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.
rkorTransactionType	Transaction Type. Possible values are SEND, REQUEST and RETURN.
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 the funds) for the transaction.

creditFinancialAccountId REQUIRED

string (UUID)

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

transactionType REQUIRED

string enum, values: SEND, REQUEST

Type of transaction. The following values are supported:

SEND Push funds from a Financial Account to another Financial Account.
REQUEST Pull funds to a Financial Account from another Financial Account.

solution REQUIRED

string

Name of the RocketKOR solution used 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 payment reasons.

amount CONDITIONAL

string (decimal)

Transaction amount. Must be a positive number. This amount will be transferred from the debit account to the credit account. The amount must conform to any transaction limits.

Either amount or debitBalancePercent is required. The request will fail if both parameters are provided.

debitBalancePercent CONDITIONAL

string (decimal)

Percentage of the debitFinancialAccountId balance to use as the transaction amount. Must be a positive number. This amount will be transferred from the debit account to the credit account. The amount must conform to any transaction limits.

Supports 4 decimal places. For example, to specify 12.25%, use the value 0.1225.

Either amount or debitBalancePercent is required. The request will fail if both parameters are provided.

currency REQUIRED

string

Currency used for the transaction. Must be an ISO 4217 alpha 3-character currency code. RocketKOR supports USD and CAD currencies.

settlementPriority

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

default value: IMMEDIATE

Expected priority for settling the transaction. 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 currently allow the SAME_DAY and NEXT_DAY settlement priorities.

description CONDITIONAL

string, max length: 100

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.

memo

string, max length: 100

Only available for the Wire solution.

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

startDateTime REQUIRED

string (date-time)

Date and time to initiate the transaction. Must be provided in ISO 8601 format without the time zone designator. 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"

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.

timeZone

string

Time zone for startDateTime. The following values are supported:

Z, GMT, UTC or UT for the UTC time zone
zone offsets from UTC starting with + or – (example: +4)
zone offsets from UTC starting with UTC+, UTC+, GMT+, GMT-, UT+ or UT-
any other ID is parsed as Region ID according to the IANA Time Zone Database (example: America/New_York is -04)

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

name CONDITIONAL

string, max length: 60

Name of the scheduled transaction. Required if recurrenceRule is provided.

Returns

Returns the Scheduled Transaction object. This object contains the scheduled transaction details, including a unique ID for the transaction.

SAMPLE REQUEST

				
					{
  "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": "loan-payouts",
  "amount": "1000.00",
  "currency": "USD",
  "settlementPriority": "SAME_DAY",
  "startDateTime": "2023-12-01T10:15:30:00",
  "timeZone": "America/Toronto",
  "recurrenceRule": "FREQ=DAILY;UNTIL=20231224T000000",
  "name": "Loan Payment"
}

SAMPLE RESPONSE

				
					{
  "id": "cc754cd5-292f-47e6-94f2-73319f979d53",
  "status": "ACTIVE",
  "createdTransactionsCount": 0,
  "pendingTransactionsCount": 0,
  "businessAccountId": "bf8714ed-501e-4a48-a11d-d2613350b643",
  "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": "loan-payouts",
  "paymentReason": "Loan Payouts",
  "amount": "1000.00",
  "debitBalancePercent": "",
  "currency": "USD",
  "settlementPriority": "SAME_DAY",
  "createdAt": "2023-10-30T21:12:32.366Z",
  "requestor": {
    "id": "fd1c6009-a35c-4ddf-a4c8-dd946af7b647",
    "type": "service-account"
  },
  "description": "",
  "memo": "",
  "startDateTime": "2023-12-01T10:15:30:00",
  "timeZone": "America/Toronto",
  "recurrenceRule": "FREQ=DAILY;UNTIL=20231224T000000",
  "name": "Loan Payment"
}