ACH Transactions

GS Advisor Solutions APIs can be used to create ACH deposits and withdrawals using a new or existing bank link.

There are numerous restrictions related to deposits and withdrawals into different types of accounts based upon account and user characteristics which will be checked when sent through this API and or when the funds are received by us.

Learn more in the Advisor Help Center.

General Rules for Cash Transactions

• The system will reject attempts to create transactions after the 3:00:00 PM ET for the current date. If the current time is after 3:00:00 PM ET, the transactions must be future dated.
• The system will reject transactions that fall on non-settlement days (holidays or weekends),
• The system will reject attempts to create transactions on with accounts with restrictions.
• The system will allow transactions to be created on unverified banklinks. However, the system will not process those transactions until the banklinks are verified, request date notwithstanding.
• The system will reject attempts to create transactions for amounts less than $0.01.
• The system will reject attempts to create transactions using deleted banklinks.
• The system will reject attempts to create transactions where the banklink is newer than the transaction. In other words, the transaction request date cannot precede the banklink creation date.
• The system will reject attempts to create transactions using banklinks with no explicit relationship with the account.
• In terms of the error messages, process date equals request date.

Deposit Rules

• The contribution year is the current year UNLESS the deposit occurs between the start of the calendar year and the IRS published due date for federal annual income tax filing (e.g., 01/01/YEAR 00:00:00 ET and 04/15/YEAR 23:59:59 ET). During this time the contribution year could be the current or previous year, until the client has filed their US federal income tax forms with the IRS for the previous year.
• The IRA contribution year is required for one-time IRA deposits. The system will reject deposits without a contribution year provided with the transaction request.
• The IRA contribution year SHOULD NOT be sent with recurring IRA deposit requests.
• The system will enforce deposit limits that are applicable for the target account based on the firm configuration and other factors. The default system limit is $100,000.00.
• The system will reject attempts to create individual transactions for IRA accounts where the individual transaction amount exceeds the annual IRA contribution limits.
• The system WILL NOT sum individual transactions to enforce yearly IRA contribution limits.

Withdrawal Rules

• The system will perform an immediate cash availability check on a transaction if the request date is the current date prior to 3:00 PM ET, otherwise, the cash availability check occurs on the requested date.
• The system will enforce withdrawal limits for the target account.
• The system requires that withholding information is provided if the withdrawal is from non-ROTH IRA account.
• The withholding types can be represented as fixed dollar('D') or percentage('P'). If you select those options, the withholding amounts MUST be greater than 0.00.
• To elect not to withhold, option NONE('N') must be used. Withholding amounts of 0.00 can then be used.
• Withholding types can be mixed and match. For example, state withholding can be a percentage, while fed can be a fixed dollar amount.
• The sum of state and fed withholding amounts cannot exceed the requested withdrawal amount.
• Different states can have different withholding amounts. Distributions from your IRA are subject to state taxes which vary by state. The system will verify state withholding amounts in accordance with that state's tax rules.

Deposit Creation

To create a deposit, POST /v1/accounts/RA1234ABCD/cashtransactions with this payload:

{
	"amount" : "250",
	"processDate" : "2022-07-09T15:07:38.360-05:00",
	"repeatType" : "0",
	"sourceId" : "2594073385611396851",
	"targetId" : "RA1234ABCD",
	"transactionType" : "AHD"
}

If the deposit success, the system will return a '201 Created' with location information.

HTTP/1.1 201 Created
Date: Wed, 20 Jul 2016 20:18:30 GMT
Location: http://api.uat.foliofn.com/restapi/accounts/RA1234ABCD/cashtransactions/2017612635063278223
Content-Length: 0
Content-Language: en

If the deposit attempt fails, the system will return a 400 Bad Request with information regarding the nature of the error in the response body.

The error code is returned in the errorCode field, while the message field contains information about the error.

Here is an example of a failure response for a $0 ACH deposit transaction.

HTTP/1.1 400 Bad Request
Date: Fri, 29 Jul 2016 15:10:59 GMT
Location: https://api.uat.foliofn.com/restapi/accounts/RA1234ABCD/cashtransactions
Content-Type: application/json
Transfer-Encoding: chunked
[
	 {
	  "type":"VALIDATION_FIELD",
	  "field":"amount",
	  "errorCode":"1003",
	  "message":"Invalid field value"
	  }
]

Below is an example where a failure may occur due to multiple failed validations.

In this example, the failure was due to deposit request with non-settlement date of 09/24/2022 (Saturday) and amount exceeds maximum amount limit in request body.

HTTP/1.1 400 Bad Request
Date: Fri, 23 Sep 2022 15:10:59 GMT
Location: https://api.uat.foliofn.com/restapi/accounts/RA1234ABCD/cashtransactions
Content-Type: application/json
Transfer-Encoding: chunked
[
	 {
	  "type":"VALIDATION_RULE",
	  "errorCode":"9060",
	  "message":"ACH amount exceed IRA contribution limit."
	  },
	  {
	  "type":"VALIDATION_RULE",
	  "errorCode":"9001",
	  "message":"The process date for current transaction cannot be a non-settlement date."
	  }
]

Withdrawal Creation

To create a withdrawal request, POST /v1/accounts/RA1234ABCD/cashtransactions with this payload:

{
	"amount" : "250",
	"processDate" : "2022-07-09T15:07:38.360-05:00",
	"repeatType" : "0",
	"targetId" : "2594073385611396851",
	"sourceId" : "RA1234ABCD",
	"transactionType" : "AHW"
}

Error Codes

This section captures the error codes returned by the cash transactions API.

Some errors are strictly internal errors that API consumers are never expected to encounter during the course of normal operations. They are most likely caused by a bug in the API or some other internal issue. For those errors, the only solution is to contact apisupport@folioinstitutional.com.