ach_instruction

https://[domain]/ws/fb/new-request

  • Create a standing banking instruction which can be used to initiate deposit/ withdrawals between IBKR account and bank account.

    Eligibility: 

    • Automated Clearing House (ACH) - United States applicants only.

    • Electronic Fund Transfer (EFT)- Canada applicants only.

  • Customer Type: Fully Disclosed, Non-Disclosed and Advisor-Clients.

  • Requests to verify instructions can take up to 2 business days to be verified.

  1. Counterparty submits the ACH instruction via DAM (ach_instruction).

  2. IBKR will provide a real-time response including a unique IBKR id and PENDING status.

  3. IBKR verifies the ACH instruction using JPM’s Account Validation Service (AVS) which leverages EWS’ PaymentChek and Account Ownership Authentication services as a data source.

    • Verification can take anywhere from 7-15 minutes.

    • Notification will be sent via /callback once verification has been completed. Optionally, poll for status using /get-status

  4. Once verification has been completed, status will be updated to reflect one of:

    • PROCESSED: ACH Instruction was processed. The ACH instructions can be used to submit deposit_funds AND withdraw_funds requests via DAM or IBKR Portal (Transfer & Pay).

    • PENDING: EWS Verification is in progress.

    • PENDING_VERIFICATION:IBKR automatically sends micro amount to the bank account provided. Counterparty will need to submit micro amounts via traditional_bank_link_verification.

      • Once this step has been complete, the status will be updated to PROCESSED. The banking instructions can be used to submit deposit_funds AND withdraw_funds requests via DAM or IBKR Portal (Transfer & Pay).

    • REJECTED : Instruction cannot be verified using EWS. To proceed with ACH, client will need to log into the IBKR Portal to add instructions via IBKR hosted Portal. Optionally, the user can use different funding method will need to be used.

  1. Counterparty submits the EFT instruction via DAM (ach_instruction).

  2. IBKR will provide a real-time response including a unique IBKR id and PENDING status.

  3. IBKR verifies the instruction using JPM’s Account Validation Service (AVS) which leverages EWS’ PaymentChek and Account Ownership Authentication services as a data source.

    • Verification can take anywhere from 7-15 minutes.

    • Notification will be sent via /callback once verification has been completed. Optionally, poll for status using /get-status

  4. Once verification has been completed, status will be updated to reflect one of:

    • PENDING: EWS Verification is in progress.

    • PENDING_VERIFICATION:Traditional verification required. IBKR automatically sends micro amount to the bank account provided. Counterparty will need to submit micro amounts via traditional_bank_link_verification.

      • Once this step has been complete, the status will be updated to PROCESSED. The banking instructions can be used to submit deposit_funds AND withdraw_funds requests via DAM or IBKR Portal (Transfer & Pay).

    • REJECTED : ACH instruction cannot be verified using EWS. To proceed with ACH, client will need to log into the IBKR Portal to add ACH instructions via IBKR hosted Portal. Optionally, the user can use different funding method will need to be used.

Name Type Description

id

ID is a unique identifier which you create for each funding request.

  • ID cannot be reused

  • ID must be established in sequential order ie 1, 2, 3, 4  or 100, 101, 102, 103 not 777, 589, 123

  • Max 10 digits for file ID

  • Max 20 digits for counterparty transaction ID

instruction_code

ACHUS

Static value and will always be ACHUS

instruction_type

DEBIT_CREDIT

DEBIT

CREDIT

DEBIT_CREDIT: ACH Instructions for deposits and withdrawals.

DEBIT: ACH Instructions for deposits only.

CREDIT: ACH instructions for withdrawals only.

instruction_name

String; max 32 characters

Name of the instructions. This is defined by counterparty.

instruction_initiated_by_ib

true

false

Should always be true.

bank_name

String

Name of Bank.

bank_routing_number

Numeric value; max 9 characters.

Routing number associated with the bank.

bank_client_acct_num

String

Bank account number.

bank_client_acct_type_code

1

2

1: Checking

2: Savings

If unspecified, defaults to checking.

currency

USD

Currency of the assets being transferred.  Only supports USD at this time.

client_ib_acct_id

String

IBKR account ID of the advisor/broker client account which funds are being deposited to. 

XSD

Copy 
<xsd:complexType name="ach_instruction" maxOccurs="unbounded" >
<xsd:sequence>
<xsd:attribute name="id" use="required" type="Non-Negative-Integer" maxOccurs="1" />
<x/sd:sequence>
<xsd:sequence>
 <xsd:element name="instruction_code" use="required" type="instruction_code" maxOccurs="1" />
 <xsd:element name="instruction_type" use="required" type="instruction_type" maxOccurs="1" />
 <xsd:element name="instruction_name" use="required" type="string" maxOccurs="1" />
 <xsd:element name="instruction_initiated_by_ib" use="required" type="boolean" maxOccurs="1" />
 <xsd:element name="bank_name" use="required"  type="string" maxOccurs="1" />
 <xsd:element name="bank_routing_number" use="required"  type="string" maxOccurs="1" />
 <xsd:element name="bank_client_acct_num" use="required" type="string" maxOccurs="1" />
 <xsd:element name="bank_client_acct_type_code" use="required" type="bank_client_acct_type_code" maxOccurs="1" />
 <xsd:element name="currency" use="required" type="currency" maxOccurs="1" />
 <xsd:element name="client_ib_acct_id" use="required" type="String" maxOccurs="1" />
</xsd:sequence>

Sample

Copy 
<?xml version="1.0" encoding="UTF-8"?>
<instruction_set
    xmlns="http://www.interactivebrokers.com/fbfb_instruction_set"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.interactivebrokers.com/fbfb_instruction_set fbfb_instruction_set.xsd "
    creation_date="2022-03-03" id="1" version="1.1">
    <ach_instruction id="_TRANSID_">
        <instruction_code>ACHUS</instruction_code>
        <instruction_type>DEBIT_CREDIT</instruction_type>
        <instruction_name>Test-ACH-Instr</instruction_name>
        <instruction_initiated_by_ib>true</instruction_initiated_by_ib>
        <bank_name>Citibank, N.A.</bank_name>
        <bank_routing_number>221172610</bank_routing_number>
        <bank_client_acct_num>12345678</bank_client_acct_num>
        <bank_client_acct_type_code>999</bank_client_acct_type_code>
        <currency>USD</currency>
        <client_ib_acct_id>U1111111</client_ib_acct_id>
    </ach_instruction>
</instruction_set>
Name Type Description

creation_date

YYYY-MM-DD

Date/Time which the file was processed by IBKR.

id

Id of the instruction to which this node is a response

 

instr_id

Id of the instruction to which this node is a response

ID is a unique identifier which you create for each funding request.

status

PENDING or PENDING_VERIFICATION

PROCESSED

REJECTED

PROCESSED: ACH Instruction was processed.

PENDING :Request passed initial validation and is pending EWS verification.

REJECTED or PENDING_VERIFICATION:To proceed with ACH, client will need to log into the IBKR Portal to add ACH instructions via IBKR hosted Portal.

Optionally, the user can use different funding method will need to be used.

code

String

Error code- (included only if there is an error)

description

String

Description of the error (included only if there is an error)

ib_instr_id

String

ID defined by IBKR.

Sample

Copy 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<instr_result_set xmlns="http://www.interactivebrokers.com/fbfb_result_set"
    id="1" version="1.2" creation_date="2022-03-03-05:00">
    <result>
        <instr_id>1</instr_id>
        <status>PENDING</status>
        <ib_instr_id>12</ib_instr_id>
        <code></code>
        <description></description>
    </result>
</instr_result_set>