Depending on applicable regulations or business limitations, specific API requests may not be available for your use.

Create an ACH Push Withdrawal

Description

This request creates a withdrawal request by ACH push from a brokerage account.

Notes

  • Please note that there are numerous restrictions related to withdrawals from different types of brokerage accounts based upon account and user characteristics (e.g., certain states have defined minimum withholdings from IRA accounts.) which will be checked when sent through this API and or when the funds are received at Folio. Learn more in the Folio Institutional Help Center.
  • The system will reject attempts to create transactions after the 12:00:00pm the current date. If the current time is after 12:00:00, the transactions must be future dated.
  • The system will perform an immediate cash availability check on a transaction if the request date is the current date prior to 12:00pm, otherwise, the cash availability check occurs on the requested date.
  • The system will enforce withdrawal limits for the target account. The default system limit is $200,000.00 over a 30 day period.
  • The system will reject transactions that fall on non-settlement days (holidays or weekends),
  • The system will reject attempts to create transactions with account 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 with amounts less than $00.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.
  • 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 witholding 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. See State Income Tax table for more information. The system will verify state withholding amoutns in accordance with that state's tax rules.
  • In terms of the error messages, process date equals request date.

Error Codes

Code Description
transaction.rule.validation.error Internal validation error for request. Possible causes range from bad account number in request URL to exceeding the deposit limits. The precise causes will be returned in the response body.
uri.matching.rule Occurs when the account provided in the uri doesn't match the account passed via the request body JSON.
transaction.withdrawal.account.limit.has.been.reached The monthly withdrawal limit has been reached.
transaction.withdrawal.amount.exceeds.withdrawal.limit The account has insufficient cash to process the transaction.
transaction.withdrawal.account.limit.has.been.reached" The monthly withdrawal limit for the account has been reached.
transaction.distribution.reason.can.only.be.N.P.S.or.E The distribution reason code was invalid.

Error Code Details: transaction.rule.validation.error

The "transaction.rule.validation.error" series of errors are generated when the system encounters errors that would prevent the successful creation of a transaction. Before the system attempts to persist a transaction, it performs a series of validations on a CashTransaction object that has been created based on data passed to the CashTransactionService. The service may return one or more validation errors encountered during the creation call.

It should be noted that 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.

Message Text Cause Internal(Y/N)
The process date cannot be on a settlement holiday. Week-ends and most holidays cannot be used for the request date. What API users know as "request date" is known internally, to us, as "process date". N
The transaction amount should be greater than $0.00. Amounts must be greater than $0.00. N
The transaction amount is greater than the maximum allowed. The system will not process any transaction amount greater than $2,000,000.00. This option is configurable on a firm by firm basis. N
The process date must be equal or after [current date in format MM/dd/yyyy]. Transaction can be same day or later before 12:00pm N
The process date must be equal or after [current day + 1 in format MM/dd/yyyy]. Transaction must be tomorrow or later if system time is after 12:00pm. N
The creator does not have the appropriate access to the selected source account. The entity attempting to create the transaction doesn't have money mover permission N
The selected banklink is disabled. Attempting to use a deleted banklink to create a transaction. N
You cannot withdraw from this account: [Account number here], transactionOid:
[transaction oid here] because of the [Restriction code here] restriction.
Attempt to withdraw funds from a restricted account N
The creator does not have the appropriate access to the selected source account. The entity attempting to create the transaction doesn't have "money mover" or better permission N
The IRA Distribution method cannot be DISABILITY User type "Member" cannot be used with method "DISABILITY". N
Source account doesn't appear to have any banklinks. The Folio account for the deposit doesn't have banklinks. N
Account and banklink are unrelated and cannot be used together. The Folio account and banklink not associated in the system. N
The source is null. The system must have a valid Folio account. Self-explanatory Y
The transaction doesn't contain any IRA info. Transaction is missing ira config info, such as, withholding types or amounts. Y
The IRA Distribution method for IRA config cannot be null. Self-explanatory Y
The Account entityOid for IRA config cannot be null Self-explanatory Y
The Cash Transaction Repeat template entityOid must be a valid Repeating template. Internal oid value doesn't reference Repeat template. Y
The IRA config info must have a valid creator oid. Null creator oid is not allowed. Y
The IRA config info must have a valid creator type Null creator type oid is not allowed. Y
The IRA config info must have a valid modifier oid. Null modifier oid is not allowed. Y
The IRA config info must have a valid modifier type. Null modifier type is not allowed. Y
The target is null. The system must have a valid Banklink The target(banklink) is null. Y
The source is null. The system must have a valid Folio Account. The source(Folio Account) is null. Y
The banklink type is invalid. It is [banklinktype] and should be an ACH. Attempt to use non-ACH banklink for an EFT transaction. Y
The selected banklink is not available yet for use. The creation time of the banklink is later than the request date(internally knownn as "process date"). Y

Request URL

Syntax POST /restapi/accounts/{accountnumber}/cashtransfers/achwithdrawals
Example URL https://api.uat.foliofn.com/restapi/accounts/RA1234ABCD/cashtransfers/achwithdrawals

Request Data Fields

Field Required? Description
amount Yes The amount of the ACH transfer request. ie, 0.00. Default limit is $200,000.00 over a thirty day period.
banklinkOid Yes The unique identifier of the bank link within the account.
ownerLoginId Yes Of whom the ACH push withdrawal request is made on behalf. Have to be one of the account owners.
requestDate Yes The date the ACH transfer is to be initiated. Follows ISO-8601 formatted date.
distributionReason Depends If IRA, valid reasons are 'N'(Normal), 'P'(Premature), 'S'(SEP_72T), and 'E'(Death)
fedWithholdAmount Depends If non-ROTH IRA, the amount to be withheld in format "00.00"
fedWithholdingType Depends If non-ROTH IRA, the type of withholding 'D'(Fixed Dollar), 'P'(Percentage), 'N'(None)
stateWithholdAmount Depends If non-ROTH IRA, the amount to be withheld in format "00.00"
stateWithholdingType Depends If non-ROTH IRA, the type of withholding 'D'(Fixed Dollar), 'P'(Percentage), 'N'(None)

Request Example 1


POST /accounts/RA1234ABCD/cashtransfers/achwithdrawals HTTP/1.1
{
   "amount": "123.45",
   "banklinkOid": "807807807807807",
   "requestDate": "2014-08-28T00:00:00.000-05:00"
   "distributionReason": "N"
   "fedWithholdAmount": "10.00",
   "fedWithholdingType": "P",
   "stateWithholdAmount": "5.00",
   "stateWithholdingType": "P"
}

Response Example 1: Successful withdrawal creation

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 actually error.


HTTP/1.1 200 OK
X-Powered-By: Servlet/2.5
Server: Sun GlassFish Enterprise Server v2.1.1
Location: http://api.uat.foliofn.com/restapi/accounts/RA0024900G/cashtransfers/achwithdrawals/2017612635063278223
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 05 Jul 2014 13:06:39 GMT

Response Example 2: Failure due to withdrawal request with non-settlement date of 11/11/2015 (Veterans's Day) and $0.00 amount in request body

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 actually error.


HTTP/1.1 400 Bad Request
X-Powered-By: Servlet/2.5
Server: Sun GlassFish Enterprise Server v2.1.1
Location: https://api.uat.foliofn.com/restapi/accounts/RA1234ABCD/cashtransfers/achwithdrawals
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 05 Jul 2014 13:06:39 GMT
[
	 {
	  "type":"VALIDATION_RULE",
	  "errorCode":"transaction.rule.validation.error",
	  "message":"Error: processDate:The process date cannot be on a settlement holiday."
	  },
	  {
	    "type":"VALIDATION_RULE",
	    "errorCode":"transaction.rule.validation.error",
	    "message":"Error: amount:The transaction amount should be greater than $0.00."
	  }
]


Change Log

03/12/2020

  1. Remove extra space

05/13/2016

  1. Added additional info about the transaction.rule.validation.error series of errors.
  2. Fixed type of word "banklink".

01/08/2016

  1. Edited Request Data Fields
  2. Modified notes section to add additional info about withholding types and amount values.

10/23/2015

  1. Added Change Log
  2. Error codes section
  3. Description header
  4. Added Notes section

Getting Started

REST APIs

Resources