Bank Instructions

In this section we will review how to create, view, and delete banking instructions using the Web API. Please be advised options available using the API are limited in comparison to methods that are supported using the IBKR Hosted Application.

Add Bank Instructions

The /gw/api/v1/bank-instructions endpoint can be used to add banking instructions to an existing IBKR brokerage account. The banking instructions can be used to facilitate future fund transfers.

ACH_INSTRUCTION

Create bank instructions for Automated Clearing House (ACH) transfer initiated by IBKR.

1. Counterparty will provide bank account information to IBKR (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 /gw/api/v1/client-instructions/{clientInstructionId} endpoint.
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 for DEPOSIT and WITHDRAWAL using the Web API 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 to IBKR using "instructionType":"TRADITIONAL_BANK_INSTRUCTION_VERIFICATION"
   • Once this step has been complete, the status will be updated to PROCESSED. The banking instructions can be used to submit deposits and withdrawals using the Web API 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.

Schema

Example

POST /gw/api/v1/bank-instructions
{"instructionType": "ACH_INSTRUCTION",
"instruction": 
{
"clientInstructionId": "1012983",
"bankInstructionCode": "USACH",
"achType": "DEBIT_CREDIT",
"bankInstructionName": "TestInstr",
"currency": "USD",
"accountId": "U223454",
"clientAccountInfo": {
"bankRoutingNumber": "202012983",
"bankAccountNumber": "101267576983",
"bankName": "JPM Chase",
"bankAccountTypeCode": 1
}
}
}

TRADITIONAL_BANK_INSTRUCTION_VERIFICATION

Verify micro deposits for ACH instructions initiated via Web API.

1. We use EWS (Early Warning System) to verify ACH Instructions.
2. Within 1-3 business days, two random credits (deposits) each less than one dollar and a corresponding debit (withdrawal) will be issued to the clients bank account.
3. Client will need to monitor their bank account for these transactions as they will be needed to confirm this funding instruction. Note that these transactions may take place on different days.
4. Once the client has these amounts, submit traditional_bank_instruction_verification request to verify the amounts. Once verified, the client can use ACH instructions for deposit and withdrawal requests.

Schema

Example

POST /gw/api/v1/bank-instructions
{
"instructionType": "TRADITIONAL_BANK_INSTRUCTION_VERIFICATION",
"instruction": {
"clientInstructionId": 7013057,
"bankInstructionCode": "USACH",
"bankInstructionName": "ACH-Tst1Random172",
"accountId": "U117717",
"pendingInstructionId": 43086786,
"creditAmount1": 0.32,
"creditAmount2": 0.46
}
}

EDDA_INSTRUCTION

Create bank instructions for Electronic Direct Debit Authorization (EDDA). EDDA can be used transfer HKD and CNY between Hong Kong bank account and IBKR Brokerage account.

Electronic Direct Debit Authorization, applicable for individuals that maintain Hong Kong bank account.

The /gw/api/v1/participating-banks endpoint can be used to view list of participating banks which support connection with Interactive Brokers for eDDA transfers and includes bankClearingCode, BIC and bank name.

Schema

Example

POST /gw/api/v1/bank-instructions
{
"instructionType": "EDDA_INSTRUCTION",
"instruction": {
"clientInstructionId": 7012743,
"bankInstructionName": "My EDDA Instructions",
"currency": "CNH",
"accountId": "U8072517",
"bankBranchCode": "003",
"bankAccountNumber": "132456",
"bankClearingCode": "003",
"debtorIdentificationDocumentType": "hkId"
}

PREDEFINED_DESTINATION_INSTRUCTION

Service can be used to create standing bank instruction for withdrawals. Only available if all accounts associated with clientID maintain bank account at the same bank.

1. Create standing wire instructions.
2. If all clients have account at a single bank, IB will hard-code the bank on the back-end and only client’s account # will be submitted to IB.

Schema

Example

POST /gw/api/v1/bank-instructions
{
"instructionType": "PREDEFINED_DESTINATION_INSTRUCTION",
"instruction": {
"clientInstructionId": 7013053,
"bankInstructionName": "Test Wire Instructions",
"bankInstructionMethod": "WIRE",
"accountId": "U123456",
"currency": "USD",
"financialInstitution": {
"name": "Test Bank",
"branchCode": "0",
"branchCodetype": "BSB_AUD",
"identifier": "SBIN001000",
"identifierType": "BIC",
"clientAccountId": "132456789"
}
}
}

View Saved Bank Instructions

When initiating deposit or withdrawal, the user can save the banking information, also referred to as the bankInstructionName. If banking information is saved, the user can reference the bank information for future funding requests rather than re-entering the banking information. The /gw/api/v1/bank-instructions/query endpoint can be used to view list of saved banking instructions on file by accountId and bankInstructionMethod. The response will return the corresponding bankInstructionName and, bankRoutingNumber, currency last 4 digits of the bankAccountNumber (if applicable).

Example

POST /gw/api/v1/bank-instructions/query
{
  "instructionType": "QUERY_BANK_INSTRUCTION",
    "instruction": {
    "clientInstructionId": "1012983",
    "accountId": "U46377",
    "bankInstructionMethod": "ACH"
  }
}

Delete Bank Instructions

The /gw/api/v1/bank-instructions can be used to delete banking instructions (bankInstructionName) for an existing account by bankInstructionName, currency, and bankInstructionMethod. Users are limited to 6 active banking instructions at a single time.

Example

POST /gw/api/v1/bank-instructions
{
  "instructionType": "DELETE_BANK_INSTRUCTION",
  "instruction": {
    "clientInstructionId": 7013055,
    "accountId": "U46377",
    "bankInstructionName": "Test Delete",
    "bankInstructionMethod": "WIRE",
    "currency": "USD"
  }
}