Getting Started Guides

Get Started: Working with ACH Transactions

Use an ACH transaction to move money between bank accounts. ACH transactions use the Automated Clearing House (ACH) financial network to move funds between financial institutions in the U.S.

In this guide, we’ll send funds from a Business Financial Account to a Customer Financial Account:

The Business Financial Account is the debit account (provides the funds). This account can be an integrated bank or internal Financial Account. In our example, we’ll use an integrated bank Financial Account.
Note An external bank Financial Account owned by the Business Account could also be used as the debit account. However, the transaction would be processed as a multi-leg transaction (MLT).
The Customer Financial Account is the credit account (receives the funds). This account must be an external bank Financial Account.

In this guide, you’ll learn how to:

Add a Financial Account for a Customer.
Create an ACH transaction.
View the transaction’s status history.
Retrieve the transaction.

Before You Start

Sandbox Account: Sign up for a RocketKOR sandbox account. When your sandbox account is created, one or more Service Accounts will be created for your Business Account. A Service Account is a non-human user of a Business Account that performs functions (such as creating transactions) via the RocketKOR APIs on behalf of the Business Account.

Authentication: Before you can call the APIs, you must authenticate a Service Account by exchanging the account’s API key and secret for an access token.

Customer Account: Ensure the Business Customer or Individual Customer has an active Customer Account.

Step 1: Add a Financial Account for the Customer

Make sure an external bank Financial Account has been created for the Customer.

Step 2: Create an ACH Transaction

Create an ACH transaction that will transfer funds between two bank Financial Accounts.

In our example, we’ll transfer funds from the Business Account’s integrated bank Financial Account to the Customer’s external bank Financial Account.

At a minimum, the request must include the following information. The request must also include an idempotency key that uniquely identifies the request. In the case of a network error, the idempotency key allows you to call the API multiple times without creating duplicate requests.

Parameter	Description
metadata	rkorACHEntryType is required for all ACH transactions. This parameter contains the ACH Standard Entry Class (SEC) code. rkorACHIndividualId is required if rkorACHEntryType is CIE, PPD, or TEL. This parameter contains the Individual Identification Number. rkorACHCheckSerialNumber is required if rkorACHEntryType is ARC, BOC, POP, or RCK. This parameter contains the serial number of the check from a Converted Check Copy. rkorACHTerminalCity is required if rkorACHEntryType is POP. This parameter contains the terminal city. rkorACHTerminalState is required if rkorACHEntryType is POP. This parameter contains the terminal state.
debitFinancialAccountId	ID of the Financial Account used as the debit account (source of funds) for the transaction. In our example, this is an integrated bank Financial Account owned by the Business Account.
creditFinancialAccountId	ID of the Financial Account used as the credit account (receiver of funds) for the transaction. In our example, this is an external bank Financial Account owned by the Customer.
transactionType	Type of transaction. The following values are supported for ACH transactions: SEND Funds are pushed from the debit account to the credit account. This type of transaction is used when the debit account owner is sending money to the credit account owner. REQUEST Funds are pulled from the credit account to the debit account. This type of transaction is used when the debit account owner is requesting money from the credit account owner. In our example, we want to SEND funds from the debit account to the credit account.
solution	Name of the RocketKOR solution used for the transaction. In our example, we’ll use ach.
paymentReasonId	ID representing the payment reason for the transaction. In our example, we’ll use bill-payment.
amount	Amount to be transferred from the debit account to the credit account. The amount must conform to any transaction limits.
currency	Currency used for the transaction. Must be USD.
settlementPriority	Expected priority for settling the transaction. The following values are supported for ACH transactions: SAME_DAY Same business day. NEXT_DAY Next business day.

API Reference

Create an SLT

Endpoint

POST /v1/transactions

Request Example

				
					{
  "metadata": {
    "rkorACHEntryType": "CCD"
  },
  "debitFinancialAccountId": "6a017f06-83a3-44b7-be6f-5e5cae4a9ed7",
  "creditFinancialAccountId": "4py56a34-4686-1539-c2ga-1a723g55dlq3",
  "transactionType": "SEND",
  "solution": "ach",
  "paymentReasonId": "bill-payment",
  "amount": "1000.00",
  "currency": "USD",
  "settlementPriority": "SAME_DAY"
}

Response Example

Returns the SLT object.

Make a note of the transaction id. You’ll need this ID in the next steps when you check the transaction status and retrieve the transaction.

				
					{
  "id": "2av81w47-9367-1295-h4ng-1q520p28wfn1",
  "businessAccountId": "de30132c-e67a-4af7-89ec-f2109863b7f7",
  "metadata": {
    "rkorACHEntryType": "CCD",
    "rkorProvider": "SNB"
  },
  "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",
  ...
}

Step 3: Check the Transaction Status

View the transaction’s status history, including the current status.

API Reference

Retrieve an SLT’s Status History

Endpoint

GET /v1/transaction-histories

In the request, pass the transaction id from step 2 to the transactionId query parameter.

Response Example

Returns an array of SLT Status objects. These objects represent the statuses that have been assigned to the transaction during the transaction processing lifecycle.

				
					{
  "totalElements": 2,
  "totalPages": 1,
  "number": 0,
  "numberOfElements": 2,
  "hasNext": false,
  "content": [
    {
      "createdBy": {
        "id": "f29200b9-4817-474a-a958-aa8b352f2e45",
        "type": "internal"
      },
      "createdAt": "2023-02-03T05:00:05.634158Z",
      "id": "aafcea88-2b6d-4151-b1ce-9e4deb9547af",
      "transactionId": "23733586-9135-42a5-8365-d0a2ec9eead0",
      "eventType": "STATUS_CHANGE",
      "description": "Transaction status changed to ‘PENDING’"
    },
    {
      "createdBy": {
        "id": "f29200b9-4817-474a-a958-aa8b352f2e45",
        "type": "internal"
      },
      "createdAt": "2023-02-03T04:00:05.634158Z",
      "id": "d7bed9a7-c55f-4b13-8d46-835f65d06939",
      "transactionId": "23733586-9135-42a5-8365-d0a2ec9eead0",
      "eventType": "CREATE",
      "description": "New transaction created"
    }
  ]
}

Step 4: Retrieve the Transaction

Retrieve the transaction details.

API Reference

Retrieve an SLT

Endpoint

GET /v1/transactions/{transactionId}

In the request:

Pass the transaction id from step 2 to the transactionId parameter.
Use the embed query parameter to embed subresources in the response, such as details for the debit and credit Financial Accounts.

Response Example

Returns the SLT object. The following example includes embedded subresources for the debit and credit Financial Accounts used in the transaction.

				
					{
  "id": "2av81w47-9367-1295-h4ng-1q520p28wfn1",
  "businessAccountId": "de30132c-e67a-4af7-89ec-f2109863b7f7",
  "metadata": {
    "rkorACHEntryType": "CCD",
    "rkorProvider": "SNB"
  },
  "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",
  ...
  "_embedded": {
    "debitFinancialAccount": {
      "id": "6a017f06-83a3-44b7-be6f-5e5cae4a9ed7",
      "businessAccountId": "de30132c-e67a-4af7-89ec-f2109863b7f7",
      "name": "Checking Account",
      "category": "INTEGRATED",
      "type": "BANK",
      "subtype": "CHECKING",
      ....
    },
    "creditFinancialAccount": {
      "id": "4py56a34-4686-1539-c2ga-1a723g55dlq3",
      "businessAccountId": "de30132c-e67a-4af7-89ec-f2109863b7f7",
      "name": "Savings Account",
      "category": "EXTERNAL",
      "type": "BANK",
      "subtype": "SAVING",
      ...
    }
  }
}

Next Steps

Create Push-To-Card transactions.
Create Wire transactions.

Get Started: Working with ACH Transactions

Before You Start

Step 1: Add a Financial Account for the Customer

Step 2: Create an ACH Transaction

API Reference

Endpoint

Request Example

Response Example

Step 3: Check the Transaction Status

API Reference

Endpoint

Response Example

Step 4: Retrieve the Transaction

API Reference

Endpoint

Response Example

Next Steps

ON THIS PAGE