Add vAccount

Request URL

POST /ibis/account/add

Description

This endpoint will add an ibis vAccount to an existing connectFi customer. The account that is created will not be automatically associated with a debit or credit card. The vAccountNumber and abaRoutingNumber are included as part of the response body. The vAccount only account that is created can be used both as a bank account (using the account number and routing number) and similar to a debit card (using the cFiAccountId that is issued in place of the cFiCardId where applicable). The cFiAccountId can be used to make requests to the following debit card related endpoints: /ibis/card/activate, /ibis/card/cardholder-profile, /ibis/card/status, /ibis/card/list (will include all cards and vAccounts for the specified customer), /ibis/financial/funds-credit, /ibis/financial/funds-debit, /ibis/financial/card-to-card, and /ibis/inquiry/transaction-history

When adding an account, the accountHolder profile is configured using information on file in connectFi, including first name, last name, the "PRIMARY" address, the "MOBILE" phone number, an optional "LANDLINE" or "PRIMARY" phone number, and email. If the relevant customer is an individual, the customer and accountHolder are the same entity and the "PRIMARY" address in connectFi will also be used as the billing address in the back-office. If the relevant customer is a business, the "PRIMARY" business address will be used as the billing address in the back office instead of the accountHolder address. In addition, the "PRIMARY" business phone number will be configured as the accountHolder work phone number in the back-office. If the accountHolder addresses, phone numbers, and/or email (or the business addresses/business phone numbers, if applicable) are not current, please make a request to /customer/update before adding new accounts to the desired accountHolder.

To check the KYC/KYB status of a customer before requesting an ibis vAccount, you may use the /akepa/status endpoint and verify that the outcome for the KYC/KYB verification application is "Approved". Note that when using /akepa/status, every entityApplications object must have an "approved" status in order for the overall verification application outcome to resolve to "Approved". It is the client's responsibility to check the KYC/KYB status before requesting card or account products if necessary.

The /ibis/account/add endpoint supports idempotency and will not accept requests with duplicate reference IDs. Multiple requests using the same reference ID will result in an error indicating that the specified reference ID already exists in the connectFi system. The external reference ID included in the request body is how connectFi controls for duplicate card requests. It is important to note that card requests submitted with unique reference IDs will not be considered duplicates, even if there are other properties with identical values. For example, the following requests are not considered duplicates.

{ //Two separate vAccounts will be added to this customer, since two requests were made with unique reference IDs (even though the remaining properties are identical)
    "customerId" : "cstap_4kuirHlq31JkYwNJtzUJn2", //same customer ID in connectFi
    "reference" : "EXT_REFERENCE_ID1", //Different reference IDs
}
{ //Two separate vAccounts will be added to this customer, since two requests were made with unique reference IDs (even though the remaining properties are identical)
    "customerId" : "cstap_4kuirHlq31JkYwNJtzUJn2", //same customer ID in connectFi
    "reference" : "EXT_REFERENCE_ID2", //Different reference IDs
}

Schema

Property table for ibis/account/add

Property	Description	Required	Schema
customerId	Customer ID in connectFi	Yes	{ "type": "string", "pattern": "^[0-9a-zA-Z_]+$", "minLength": 1, "maxLength": 36, "$id": "common-id" }
reference	An external alphanumeric reference ID for the entity in your system	Yes	{ "type": "string", "pattern": "^[0-9a-zA-Z]+$", "minLength": 1, "maxLength": 32, "$id": "common-reference" }
profile	An object containing profile details	No	ibisFacade accountProfile object

Property table for ibisFacade accountProfile object

Property	Description	Required	Schema
accountHolderId	A connectFi ID for the account holder (required for business account holders only, nullable for individual customers). Must match customerId if included for individual customers.	No	{ "type": "string", "pattern": "^[0-9a-zA-Z_]+$", "minLength": 1, "maxLength": 36, "nullable": true, "$id": "common-idNullable" }
occupation	occupation	No	{ "type": "string", "pattern": "^((?![<>]).)*$", "minLength": 1, "maxLength": 50, "isNotOnlyWhitespace": true, "$id": "common-commonStr50Req" }

Request Body

{
    "customerId" : "cstap_5mgmsbsKCdzeozyX54PdcK",
    "reference" : "extIvAccount102",
    "profile" : {
        "accountHolderId" : "cstap_7uvAC6nLftLGCq7yic3TfI"
    }
}

Snippet Examples

javascript

const axios = require('axios');
const data = {
    "customerId" : "cstap_5mgmsbsKCdzeozyX54PdcK",
    "reference" : "extIvAccount102",
    "profile" : {
        "accountHolderId" : "cstap_7uvAC6nLftLGCq7yic3TfI"
    }
};
const config = {
  method: 'POST',
  url: '${CONNECTFI_BASE_URL}/ibis/account/add',
  headers: {
    'Content-Type': "application/json",
    'x-connectfi-token': "A long random string token received from /auth/get-token request"
  },
  data
};

let result;
try {
  result = await axios.request(config);
  if (result.status === 200) {
    console.log(JSON.stringify(result.data));
  }
} catch (err) {
  console.log({
    errCode: err.code,
    responseStatus: err.response && err.response.status,
    data: err.response && JSON.stringify(err.response.data)
  });
}

cURL

curl --location "CONNECTFI_BASE_URL/ibis/account/add" --data "{\"customerId\": \"cstap_5mgmsbsKCdzeozyX54PdcK\",   \"reference\": \"extIvAccount102\",   \"profile\": {        \"accountHolderId\": \"cstap_7uvAC6nLftLGCq7yic3TfI\"    }}" --header "Content-Type: application/json" --header "x-connectfi-token: A long random string token received from /auth/get-token request"

Successful Response Examples

200 SUCCESSFUL RESPONSE INDIVIDUAL

HEADERS

Header	Value
Content-Type	application/json
x-connectfi-token	A long random string token received from /auth/get-token request

REQUEST BODY

{
    "customerId" : "cstap_7uvAC6nLftLGCq7yic3TfI",
    "reference" : "extIvAccount100"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiAccountId": "icrd_1G7XuScZRw0JaXH0oOWrIK",
        "accountProgramId": "d_gpr_test",
        "cFiStatus": "Complete",
        "customerId": "cstap_7uvAC6nLftLGCq7yic3TfI",
        "cFiAggregatorId": "CLIENTID",
        "reference": "extIvAccount100",
        "memberNumber": "cstcp_2WZ7ariGgrtumtUlD452LM",
        "programType": "vAccountOnly",
        "boReferenceId": "110195634079801",
        "boCustomerId": "110000001956340798",
        "vAccountNumber": "1234567890123456",
        "abaRoutingNumber": "122244184",
        "dtsCreatedAt": "2023-11-01T17:43:49.907Z",
        "batchReferenceId": "1083808",
        "transId": "F2165986607",
        "batchRecordId": "1766368",
        "fee": 0,
        "balance": 0,
        "lastDepositAmount": 0,
        "ledgerBalance": 0
    },
    "requestId": "3712b5f078de11eeb5658f28ab5fe311"
}

200 SUCCESSFUL RESPONSE INDIVIDUAL WITH PROFILE

HEADERS

Header	Value
Content-Type	application/json
x-connectfi-token	A long random string token received from /auth/get-token request

REQUEST BODY

{
    "customerId" : "cstap_7uvAC6nLftLGCq7yic3TfI",
    "reference" : "extIvAccount101",
    "profile": {
        "accountHolderId": "cstap_7uvAC6nLftLGCq7yic3TfI"
    }
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiAccountId": "icrd_4oMGe28tFhZ4I69KP0wN2O",
        "accountProgramId": "d_gpr_test",
        "cFiStatus": "Complete",
        "customerId": "cstap_7uvAC6nLftLGCq7yic3TfI",
        "cFiAggregatorId": "CLIENTID",
        "reference": "extIvAccount101",
        "memberNumber": "cstcp_2WZ7ariGgrtumtUlD452LM",
        "programType": "vAccountOnly",
        "boReferenceId": "110195634080113",
        "boCustomerId": "110000001956340801",
        "vAccountNumber": "1234567890123456",
        "abaRoutingNumber": "122244184",
        "dtsCreatedAt": "2023-11-01T17:46:19.857Z",
        "batchReferenceId": "1083811",
        "transId": "F2165986612",
        "batchRecordId": "1766371",
        "fee": 0,
        "balance": 0,
        "lastDepositAmount": 0,
        "ledgerBalance": 0
    },
    "requestId": "908df7c078de11eeb5658f28ab5fe311"
}

200 SUCCESSFUL RESPONSE BUSINESS REPRESENTATIVE

HEADERS

Header	Value
Content-Type	application/json
x-connectfi-token	A long random string token received from /auth/get-token request

REQUEST BODY

{
    "customerId" : "cstab_7BX5DO49J48VeWKsJ6gWNb",
    "reference" : "extIvAccount105",
    "profile" : {
        "accountHolderId" : "cstab_7BX5DPJcbmipymiokecA6d"
    }
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiAccountId": "icrd_1Qnj296yc0NciRmpz2FKUi",
        "accountProgramId": "d_gpr_test",
        "cFiStatus": "Complete",
        "customerId": "cstab_7BX5DO49J48VeWKsJ6gWNb",
        "cFiAggregatorId": "CLIENTID",
        "reference": "extIvAccount105",
        "memberNumber": "cstcb_7BVheqroxnTuAPC6csh9E6",
        "programType": "vAccountOnly",
        "boReferenceId": "110195635853812",
        "boCustomerId": "110000001956358538",
        "vAccountNumber": "1234567890123456",
        "abaRoutingNumber": "122244184",
        "dtsCreatedAt": "2023-12-06T22:17:26.370Z",
        "batchReferenceId": "1100512",
        "transId": "F2166178827",
        "batchRecordId": "1783205",
        "fee": 0,
        "balance": 0,
        "lastDepositAmount": 0,
        "ledgerBalance": 0
    },
    "requestId": "3c98c470948511eea89d7100487c0512"
}

200 SUCCESSFUL RESPONSE BUSINESS EMPLOYEE

HEADERS

Header	Value
Content-Type	application/json
x-connectfi-token	A long random string token received from /auth/get-token request

REQUEST BODY

{
    "customerId" : "cstab_7BX5DO49J48VeWKsJ6gWNb",
    "reference" : "extIvAccount106",
    "profile" : {
        "accountHolderId" : "cstap_6reGTr3k8vpAu8uFV7EdiN"
    }
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiAccountId": "icrd_7egpCIVUH6bAUOIOyhln4m",
        "accountProgramId": "d_gpr_test",
        "cFiStatus": "Complete",
        "customerId": "cstab_7BX5DO49J48VeWKsJ6gWNb",
        "cFiAggregatorId": "CLIENTID",
        "reference": "extIvAccount106",
        "memberNumber": "cstcb_7BVheqroxnTuAPC6csh9E6",
        "programType": "vAccountOnly",
        "boReferenceId": "110195635854098",
        "boCustomerId": "110000001956358540",
        "vAccountNumber": "1234567890123456",
        "abaRoutingNumber": "122244184",
        "dtsCreatedAt": "2023-12-06T22:22:23.226Z",
        "batchReferenceId": "1100514",
        "transId": "F2166178833",
        "batchRecordId": "1783207",
        "fee": 0,
        "balance": 0,
        "lastDepositAmount": 0,
        "ledgerBalance": 0
    },
    "requestId": "ed8a7760948511eea89d7100487c0512"
}