ACH Transfers¶

POST /v3/createExternalAccount¶

Note: To connect an investor's bank account through Plaid, use linkExternalAccount; see ACH. Use this method when you already have verified bank details, for example from your own Plaid integration.

This method is used to add information to an Account (createAccount) for an external bank account which an ACH transfer can be initiated from. Only one external account can be created for an account. External accounts can have funds debited from them (externalFundMove).

Parameters¶

Example Request¶

curl -X POST "$TAPI_HOST/v3/createExternalAccount" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d types=Account \
  -d accountId=A20168 \
  -d "ExtAccountfullname=John Abraham" \
  -d "Extnickname=John Nick" \
  -d "ExtBankname=Union Bank" \
  -d ExtRoutingnumber=34543534 \
  -d ExtAccountnumber=1234567890 \
  -d updatedIpAddress=10.0.0.115

Response¶

The details are returned under the key External Account Details when types is Account, or Issuer External Account Details when types is Issuer.

Example Response¶

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "External Account Details": [
    true,
    [
      {
        "accountId": "A78129645",
        "ExtAccountfullname": "Lauren Test",
        "Extnickname": "Testing",
        "ExtRoutingnumber": "MDUzMDAwMTk2",
        "ExtAccountnumber": "MTAwMDAwMDA=",
        "types": "Account",
        "accountType": "Checking"
      }
    ]
  ]
}

POST /v3/deleteExternalAccount¶

This method is used to delete a particular external bank account (createExternalAccount) that was created for an account (createAccount). The Account ID must be specified as a request parameter to delete the external account.

Parameters¶

Example Request¶

curl -X POST "$TAPI_HOST/v3/deleteExternalAccount" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  --header 'content-type: application/json' \
  --data '
{
  "accountId": "A123456",
  "types": "Account"
}
'

Response¶

Example Response¶

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "Account External Account Details": [
    true,
    [
      {
        "accountId": "A123456",
        "Ext_status": "Deleted"
      }
    ]
  ]
}

POST /v3/externalFundMove¶

This method is used to initiate an ACH debit that moves funds from an investor's external bank account into the escrow account for the offering. A trade must already exist (createTrade) with a transactionType of ACH, and the account must have an external bank account on file, added through createExternalAccount or linkExternalAccount. A trade may only be funded once — a fund move that reached Pending, Submitted or Settled blocks any further attempt on the same trade.

The response returns a reference number (RefNum) identifying the fund move, which starts in a Pending status. Pending transactions are submitted for processing at 6:00 PM Eastern Time every business day; until then the debit can be cancelled with requestForVoidACH. Settlement is not immediate — track progress with getExternalFundMoveInfo or getExternalFundMove, or subscribe to the externalFundMove webhook, which fires on initiation with the trade ID and reference number.

Parameters¶

Account selection¶

externalFundMove does not accept bank account details, and the NickName parameter does not select one. It debits the single external account on file for accountId, exactly as returned by getExternalAccount. That stored account must have a nickname, routing number, account number and account holder name populated, or the request fails with 149. Because an account may only ever have one external account, no parameter is needed to select between accounts.

Preconditions and limits¶

• The account must be authorized for ACH; a blocked account returns 773.
• The trade must exist (188) and be an ACH trade (194).
• The trade must not already have a fund move in a Pending, Submitted or Settled status (150, or 210). Only a fund move that was Returned or Voided may be retried — a settled trade cannot be funded again.
• The stored routing number must be a valid nine-digit ABA number (207, 215).
• The trade total must not exceed the maximum single ACH transaction amount configured for your client (234). Contact support to review your limit.
• amount may exceed the trade total by up to 7%; beyond that returns 721.
• Your client must be configured with a supported payment provider (211).

Example Request¶

curl -X POST "$TAPI_HOST/v3/externalFundMove" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d accountId=985742 \
  -d offeringId=97421 \
  -d tradeId=7766362363632 \
  -d "NickName=Tester Jones" \
  -d amount=10000.50 \
  -d checkNumber=7766362363632 \
  -d "description=Example Transaction" \
  -d createdIpAddress=10.0.0.9

Response¶

Example Response¶

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "TradeFinancialDetails": [
    {
      "accountId": "A49501",
      "tradeId": "257528259",
      "offeringId": "81272",
      "totalAmount": "1000.000000",
      "RefNum": "464266069",
      "fundStatus": "Pending"
    }
  ]
}

Errors¶

Note: the 149 response text reads "Investor External Account does not exist / Nickname mismatch." No nickname comparison is performed; the condition is only that a complete external account exists for the given accountId.

Simulating ACH outcomes in Sandbox¶

Outside Production, a fund move can be driven to a final status immediately, without waiting for a real ACH cycle. The trigger is the nickname stored on the external account: when Extnickname matches one of the reserved values below, the fund move is advanced through Submitted and then to the outcome shown, and the trade status is updated to match. Nothing is sent to the bank.

Test ACH Settled and Test ACH R01 are available in every non-Production environment. Further return codes can be configured per environment; contact support if you need a specific NACHA return code for your testing.

The simulation runs synchronously. The fundStatus in the externalFundMove response is already the final status, and getExternalFundMoveInfo reflects it straight away — it reports the return code in error, while getExternalFundMove reports the same value in errors. Each transition also fires the updateExternalFundMoveStatus webhook — first Submitted, then the final status — so webhook handling can be tested end to end.

Any other nickname leaves the fund move Pending for normal processing. The facility is disabled in Production.

The reserved value must be the nickname stored on the external account, not the NickName parameter passed to externalFundMove. Set it as Extnickname when calling createExternalAccount. For an account already linked through linkExternalAccount, which assigns a Plaid-generated nickname, change it with updateExternalAccount — that method replaces the whole external account record, so resend the account holder name, routing number, account number and types along with the new nickname or those fields will be cleared.

POST /v3/getAchPendingId¶

This method returns the pending Tristate ACH fund-move transactions for an account. It returns only records whose fundStatus is Pending — i.e. ACH debits that have been initiated (externalFundMove) but not yet settled or voided. If the account has no pending Tristate ACH records, the response returns statusCode 212 with no transaction array.

Parameters¶

Example Request¶

curl -X POST "$TAPI_HOST/v3/getAchPendingId" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  --header 'content-type: application/json' \
  --data '
{
  "accountId": "A12345"
}
'

Response¶

Returns the matching pending Tristate ACH transactions in the investorExternalAccountDetails array. Each element contains the following fields:

Example Response¶

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "investorExternalAccountDetails": [
    {
      "accountId": "A1543842",
      "tradeId": "257528259",
      "offeringId": "81272",
      "Bankname": "America First Credit Union",
      "totalAmount": "1000.000000",
      "Accountnumber": "MTExMTIyMjIzMzMzMTExMQ==",
      "Routingnumber": "MDIxNTMxMzIz",
      "Accountfullname": "Test Account Name",
      "transactionstatus": "Pending",
      "routingNumberStatus": "Verified",
      "fundStatus": "Pending",
      "createdDate": "2024-05-01 10:15:00"
    }
  ]
}

POST /v3/getExternalAccount¶

This method retrieves the external bank account (createExternalAccount) linked to an account or issuer.

Parameters¶

Example Request¶

curl -X POST "$TAPI_HOST/v3/getExternalAccount" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  --header 'content-type: application/json' \
  --data '
{
  "accountId": "A12345",
  "types": "Account"
}
'

Response¶

Example Response¶

{
  "statusCode": "101",
  "accountId": "A1543842",
  "statusDesc": {
    "AccountName": "Test Account Name",
    "AccountNickName": "Plaid Saving - America First Credit Union",
    "AccountRoutingNumber": "021531323",
    "AccountNumber": "1111222233331111",
    "accountType": "Savings",
    "updatedDate": "0000-00-00 00:00:00",
    "createdDate": "2022-10-26 23:10:39"
  }
}

POST /v3/getExternalFundMove¶

This method is used to get the details and current status for an external fund move. The Account ID and Reference Number must be specified as a request parameter to get the external fund move details and current status.

Parameters¶

Example Request¶

curl -X POST "$TAPI_HOST/v3/getExternalFundMove" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d accountId=A85742 \
  -d RefNum=685427152

Response¶

Example Response¶

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "investorExternalAccountDetails": [
    {
      "accountId": "A49501",
      "tradeId": "529293396",
      "offeringId": "81272",
      "Bankname": "Testing",
      "totalAmount": "1000.000000",
      "Accountnumber": "MTIzNDU2Nzg5MDAwMA==",
      "Routingnumber": "MTIxMDAwMzU4",
      "RefNum": "367253829",
      "Accountfullname": "John Smith",
      "transactionstatus": "Approved",
      "routingNumberStatus": "Verified",
      "fundStatus": "Submitted",
      "errors": null,
      "createdDate": "2018-09-19 08:57:04"
    }
  ]
}

POST /v3/getExternalFundMoveHistory¶

This method is used to retrieve all the external fund move details for all ACH transactions that have been processed for a particular Account (createAccount)

Parameters¶

Example Request¶

curl -X POST "$TAPI_HOST/v3/getExternalFundMoveHistory" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d accountId=A77952

Response¶

Each element contains the fields shown in the example below.

Example Response¶

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "accountDetails": [
    {
      "accountId": "A49501",
      "tradeId": "880696248",
      "offeringId": "81272",
      "Bankname": "Testing",
      "totalAmount": "1000.000000",
      "Accountnumber": "MTIzNDU2Nzg5MDAwMA==",
      "Routingnumber": "MTIzNDU2Nzg5",
      "RefNum": null,
      "Accountfullname": "Testing",
      "transactionstatus": "Approved",
      "routingNumberStatus": "Verified",
      "fundStatus": "Submitted",
      "errors": null,
      "createdDate": "2018-06-16 05:49:10"
    },
    {
      "accountId": "A49501",
      "tradeId": "623303227",
      "offeringId": "44238",
      "Bankname": "Testing",
      "totalAmount": "5.000000",
      "Accountnumber": "MTIzNDU2Nzg5MDAwMA==",
      "Routingnumber": "MTIzNDU2Nzg5",
      "RefNum": null,
      "Accountfullname": "Testing",
      "transactionstatus": "Pending",
      "routingNumberStatus": "Verified",
      "fundStatus": "Pending",
      "errors": null,
      "createdDate": "2018-07-06 11:35:45"
    },
    {
      "accountId": "A49501",
      "tradeId": "385938050",
      "offeringId": "44238",
      "Bankname": "Testing",
      "totalAmount": "1.000000",
      "Accountnumber": "MTIzNDU2Nzg5MDAwMA==",
      "Routingnumber": "MTIzNDU2Nzg5",
      "RefNum": null,
      "Accountfullname": "Testing",
      "transactionstatus": "Pending",
      "routingNumberStatus": "Verified",
      "fundStatus": "Pending",
      "errors": null,
      "createdDate": "2018-07-06 11:59:16"
    }
  ]
}

POST /v3/getExternalFundMoveInfo¶

This method is used to get all information for an external fund move. The Account ID (createAccount) and Reference Number (included in the externalFundMove response) must be specified as a request parameter to get all external fund move information.

Parameters¶

Example Request¶

curl -X POST "$TAPI_HOST/v3/getExternalFundMoveInfo" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d RefNum=685427152 \
  -d accountId=A12345

Response¶

Example Response¶

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "investorExternalAccountDetails": {
    "fundStatus": "Returned",
    "error": "101 - Settled Trade"
  },
  "ACHDetails": {
    "accountId": "A3040386",
    "fundStatus": "Returned",
    "tradeId": "1001577983",
    "createdDate": "2024-07-31 17:18:59",
    "developerAPIKey": "somedeveloperkey",
    "accountName": "John Smith's Account",
    "clientName": "example client",
    "clientId": "someclientid",
    "issueName": "example offering"
  }
}

POST /v3/linkExternalAccount¶

This method is used to add an external account using Plaid. Only one external account can be created for an account. STEP ONE: Invoke the "LinkExternalAccount" API method from a web form using cURL. Failures will see the response with corresponding error codes. STEP TWO: Successful calls will provide the response as below : { "statusCode": "101", "statusDesc": "Ok", "AccountDetails":" https://api-sandboxdash.norcapsecurities.com/apiscript/plaid-link.php?params=[param_value] " } . STEP THREE: Get the content of the response and run it. You should see the Login widget on the webpage. Example PHP snippet : $res = json_decode($result); print_r(file_get_contents($res->accountDetails));

Parameters¶

Example Request¶

curl -X POST "$TAPI_HOST/v3/linkExternalAccount" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d accountId=A12345

Response¶

Example Response¶

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "accountDetails": " https://api-sandboxdash.norcapsecurities.com/apiscript/plaid-link.php?params=[param_value] "
}

POST /v3/requestForVoidACH¶

This method is used to update the pending ACH transaction to void. This can only be used on a transaction that is in a "Pending" status. "Pending" transactions are submitted for processing at 6:00 PM Eastern Time every business day.

A successful void sends the requestForVoidACH webhook, not updateExternalFundMoveStatus. Subscribe to both methods to see every status change on a transfer — see Webhooks.

Parameters¶

Example Request¶

curl -X POST "$TAPI_HOST/v3/requestForVoidACH" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d RefNum=313889266

Response¶

Example Response¶

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "investorExternalAccountDetails": "Status Updated Successfully"
}

POST /v3/updateExternalAccount¶

This method is used to update fields related to a particular external account for an Account (createAccount). The Account ID must be specified as a request parameter to update the record.

Parameters¶

Example Request¶

curl -X POST "$TAPI_HOST/v3/updateExternalAccount" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d types=Account \
  -d accountid=A12345 \
  -d "ExtAccountfullname=John Abraham" \
  -d "Extnickname=John Nick" \
  -d ExtRoutingnumber=34543534 \
  -d ExtAccountnumber=1234567890 \
  -d accountType=Checking \
  -d updatedIpAddress=10.0.0.115

Response¶

The details are returned under the key Account External Account Details when types is Account, or Issuer External Account Details when types is Issuer.

Example Response¶

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "Account External Account Details": [
    true,
    [
      {
        "accountId": "5705166",
        "ExtAccountfullname": "John",
        "Extnickname": "John account",
        "ExtRoutingnumber": "MzQ1NDM1MzQ=",
        "ExtAccountnumber": "MTIzNDU2Nzg5MA==",
        "accountType": "Checking",
        "types": "Account"
      }
    ]
  ]
}

POST /v3/updateLinkExternalAccount¶

This method is used to update an external account using Plaid. Only one external account can be created for an account

Parameters¶

Example Request¶

curl -X POST "$TAPI_HOST/v3/updateLinkExternalAccount" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d accountId=A12345

Response¶

Example Response¶

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "accountDetails": "https://api-sandboxdash.norcapsecurities.com/apiscript/plaid-link.php?params=[param_value]"
}

POST /v3/validateABARoutingNumber¶

This method is used to validate the routing number for an external account (createExternalAccount)

Parameters¶

Example Request¶

curl -X POST "$TAPI_HOST/v3/validateABARoutingNumber" \
  -H "Authorization: Bearer $TAPI_CLIENT_ID:$TAPI_API_KEY" \
  -d routingNumber=123456789

Response¶

Example Response¶

{
  "statusCode": "101",
  "statusDesc": "Ok",
  "accountDetails": "Valid routing number"
}