Skip to content

Add Debit Card

Request URL

POST /ibis/debit-card/add

Description

This endpoint initializes a debit card for an existing connectFi customer.

When adding a debit card, the back-office cardHolder 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 cardHolder are the same entity and the "PRIMARY" address in connectFi will also be used as the card 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 cardHolder address. In addition, the "PRIMARY" business phone number will be configured as the cardHolder work phone number in the back-office. If the cardHolder 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 cards to the desired cardHolder.

To check the KYC/KYB status of a customer before requesting an ibis debit card, 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 connectFi API uses tokenization to redact the issued card PAN and does not store the security code or card PAN at any point. It is your (the client's) responsibility to ensure that sensitive card data is redacted when being handled in your system.

The /ibis/debit-card/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 debit cards 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
    "cardProgramId": "d_gpr_test", //same card program
    "profile" : { //same profile data
        "occupation" : "Student",
        "nameOnCard" : "JOHN TESTMAN"
    }
}
{ //Two separate debit cards 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
    "cardProgramId": "d_gpr_test", //same card program
    "profile" : { //same profile data
        "occupation" : "Student",
        "nameOnCard" : "JOHN TESTMAN"
    }
}

Schema

Property table for ibis/debit-card/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"
}
cardProgramId The card program ID Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr50Req"
}
cFiPrimaryCardId The card ID in connectFi of the primary card. (If included, the returned card will be a secondary card account. If excluded, the returned card will be a primary card account.) No {
  "type": "string",
  "pattern": "^[0-9a-zA-Z_]+$",
  "minLength": 1,
  "maxLength": 36,
  "$id": "common-id"
}
profile An object containing profile details Yes ibisFacade profile object
businessInfo An object containing business details No ibisFacade businessInfo object

Property table for ibisFacade businessInfo object

Property Description Required Schema
companyNameOnCard The name of the company with which the business card is associated Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 100,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr100Req"
}

Property table for ibisFacade profile object

Property Description Required Schema
cardHolderId An ID for the cardholder (required for business card 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 Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr50Req"
}
nameOnCard The name that will be displayed on the card Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 100,
  "isNotOnlyWhitespace": true,
  "$id": "common-commonStr100Req"
}

Request Body

{
    "customerId" : "cstap_7uvAC6nLftLGCq7yic3TfI",
    "reference" : "extIDCrd102", 
    "cardProgramId": "d_gpr_test",
    "profile" : {
        "occupation" : "Student",
        "nameOnCard" : "JOLEEN KAPSCH"
    }
}

Snippet Examples

javascript

const axios = require('axios');
const data = {
    "customerId" : "cstap_7uvAC6nLftLGCq7yic3TfI",
    "reference" : "extIDCrd102", 
    "cardProgramId": "d_gpr_test",
    "profile" : {
        "occupation" : "Student",
        "nameOnCard" : "JOLEEN KAPSCH"
    }
};
const config = {
  method: 'POST',
  url: '${CONNECTFI_BASE_URL}/ibis/debit-card/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/debit-card/add" --data "{\"customerId\": \"cstap_7uvAC6nLftLGCq7yic3TfI\",   \"reference\": \"extIDCrd102\",    \"cardProgramId\":\"d_gpr_test\",   \"profile\": {        \"occupation\": \"Student\",       \"nameOnCard\": \"JOLEEN KAPSCH\"    }}" --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 EXAMPLE 1

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" : "extIDCrd100", 
    "cardProgramId": "d_gpr_test",
    "profile" : {
        "occupation" : "Student",
        "nameOnCard" : "JOLEEN KAPSCH"
    }
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiCardId": "icrd_1qaR2QEPXIRKr4jOyjQkTw",
        "cFiStatus": "Complete",
        "customerId": "cstap_7uvAC6nLftLGCq7yic3TfI",
        "cFiAggregatorId": "CLIENTID",
        "reference": "extIDCrd100",
        "memberNumber": "cstcp_2WZ7ariGgrtumtUlD452LM",
        "cardProgramId": "d_gpr_test",
        "programType": "debit",
        "boReferenceId": "110195634081158",
        "boCustomerId": "110000001956340811",
        "vAccountNumber": "1234567890123456",
        "abaRoutingNumber": "122244184",
        "dtsCreatedAt": "2023-11-01T18:05:04.208Z",
        "newCardNumber": {
            "number": "1234567890654321",
            "expiryDate": "112026"
        },
        "batchReferenceId": "1083818",
        "nameOnCard": "JOLEEN KAPSCH",
        "transId": "F2165986778",
        "batchRecordId": "1766378",
        "fee": 0,
        "balance": 0,
        "lastDepositAmount": 0,
        "ledgerBalance": 0
    },
    "requestId": "2eb850b078e111eeb5658f28ab5fe311"
}

200 SUCCESSFUL RESPONSE INDIVIDUAL EXAMPLE 2

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" : "extIDCrd265", 
    "cardProgramId": "d_gpr_test",
    "profile" : {
        "occupation" : "Student",
        "nameOnCard" : "JOLEEN KAPSCH",
        "cardHolderId": "cstap_7uvAC6nLftLGCq7yic3TfI"
    }
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiCardId": "icrd_7y9golbUVTGyBTU5HVBR3Y",
        "cFiStatus": "Complete",
        "customerId": "cstap_7uvAC6nLftLGCq7yic3TfI",
        "cFiAggregatorId": "CLIENTID",
        "reference": "extIDCrd265",
        "memberNumber": "cstcp_2WZ7ariGgrtumtUlD452LM",
        "cardProgramId": "d_gpr_test",
        "programType": "debit",
        "boReferenceId": "110195638888332",
        "boCustomerId": "110000001956388883",
        "vAccountNumber": "1234567890123456",
        "abaRoutingNumber": "122244184",
        "dtsCreatedAt": "2024-01-18T16:02:24.290Z",
        "newCardNumber": {
            "number": "1234567890654321",
            "expiryDate": "012027"
        },
        "batchReferenceId": "1141033",
        "nameOnCard": "JOLEEN KAPSCH",
        "transId": "F2166324957",
        "batchRecordId": "1823882",
        "fee": 0,
        "balance": 0,
        "lastDepositAmount": 0,
        "ledgerBalance": 0
    },
    "requestId": "f815d790b61a11eeaa76ffd7d3224a12"
}

200 SUCCESSFUL RESPONSE INDIVIDUAL SUPPLEMENTARY CARD

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",
    "cFiPrimaryCardId": "icrd_1qaR2QEPXIRKr4jOyjQkTw",
    "reference" : "extIDCrd303", 
    "cardProgramId": "d_gpr_test",
    "profile" : {
        "occupation" : "Student",
        "nameOnCard" : "JOLEEN KAPSCH"
    }
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiCardId": "icrd_2mJN1FgNY1V5z7x73it9Zg",
        "cFiPrimaryCardId": "icrd_1qaR2QEPXIRKr4jOyjQkTw",
        "cFiStatus": "Complete",
        "customerId": "cstap_7uvAC6nLftLGCq7yic3TfI",
        "cFiAggregatorId": "CLIENTID",
        "reference": "extIDCrd303",
        "memberNumber": "cstcp_2WZ7ariGgrtumtUlD452LM",
        "cardProgramId": "d_gpr_test",
        "programType": "debit",
        "boReferenceId": "110195638966732",
        "boCustomerId": "110000001956389667",
        "vAccountNumber": "1234567890123456",
        "abaRoutingNumber": "122244184",
        "dtsCreatedAt": "2024-01-25T13:04:42.012Z",
        "newCardNumber": {
            "number": "1234567890654321",
            "expiryDate": "012027"
        },
        "nameOnCard": "JOLEEN KAPSCH",
        "transId": "F2166340025",
        "batchRecordId": "1824606",
        "fee": 0,
        "balance": 0,
        "lastDepositAmount": 0,
        "ledgerBalance": 0
    },
    "requestId": "4da44d60bb8211eeaa76ffd7d3224a12"
}

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" : "extIDCrd103", 
    "cardProgramId": "d_gpr_test",
    "businessInfo" : {
        "companyNameOnCard" : "ABC123 Inc."
    },
    "profile" : {
        "cardHolderId" : "cstab_7BX5DPJcbmipymiokecA6d",
        "occupation" : "Business Owner",
        "nameOnCard" : "JOLEEN KAPSCH"
    }
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiCardId": "icrd_3CPlStZBwCqCItwzYmNnLY",
        "cFiStatus": "Complete",
        "customerId": "cstab_7BX5DO49J48VeWKsJ6gWNb",
        "cFiAggregatorId": "CLIENTID",
        "reference": "extIDCrd103",
        "memberNumber": "cstcb_7BVheqroxnTuAPC6csh9E6",
        "cardProgramId": "d_gpr_test",
        "programType": "debit",
        "boReferenceId": "110195635853946",
        "boCustomerId": "110000001956358539",
        "vAccountNumber": "1234567890123456",
        "abaRoutingNumber": "122244184",
        "dtsCreatedAt": "2023-12-06T22:19:04.566Z",
        "newCardNumber": {
            "number": "1234567890654321",
            "expiryDate": "122026"
        },
        "batchReferenceId": "1100513",
        "nameOnCard": "JOLEEN KAPSCH",
        "transId": "F2166178830",
        "batchRecordId": "1783206",
        "fee": 0,
        "balance": 0,
        "lastDepositAmount": 0,
        "ledgerBalance": 0
    },
    "requestId": "77244150948511eea89d7100487c0512"
}

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" : "extIDCrd104", 
    "cardProgramId": "d_gpr_test",
    "businessInfo" : {
        "companyNameOnCard" : "ABC123 Inc."
    },
    "profile" : {
        "cardHolderId" : "cstap_6reGTr3k8vpAu8uFV7EdiN",
        "occupation" : "ABC123 Technician",
        "nameOnCard" : "JOLEEN KAPSCH"
    }
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiCardId": "icrd_kUSaQbnpNPgnru0SQYCZk",
        "cFiStatus": "Complete",
        "customerId": "cstab_7BX5DO49J48VeWKsJ6gWNb",
        "cFiAggregatorId": "CLIENTID",
        "reference": "extIDCrd104",
        "memberNumber": "cstcb_7BVheqroxnTuAPC6csh9E6",
        "cardProgramId": "d_gpr_test",
        "programType": "debit",
        "boReferenceId": "110195635854104",
        "boCustomerId": "110000001956358541",
        "vAccountNumber": "1234567890123456",
        "abaRoutingNumber": "122244184",
        "dtsCreatedAt": "2023-12-06T22:23:12.763Z",
        "newCardNumber": {
            "number": "1234567890654321",
            "expiryDate": "122026"
        },
        "batchReferenceId": "1100515",
        "nameOnCard": "JOLEEN KAPSCH",
        "transId": "F2166178834",
        "batchRecordId": "1783208",
        "fee": 0,
        "balance": 0,
        "lastDepositAmount": 0,
        "ledgerBalance": 0
    },
    "requestId": "0b1247e0948611eea89d7100487c0512"
}

200 SUCCESSFUL RESPONSE BUSINESS SECONDARY CARD

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",
    "cFiPrimaryCardId": "icrd_kUSaQbnpNPgnru0SQYCZk",
    "reference" : "extIDCrd304", 
    "cardProgramId": "d_gpr_test",
    "businessInfo" : {
        "companyNameOnCard" : "ABC123 Inc."
    },
    "profile" : {
        "cardHolderId" : "cstap_6reGTr3k8vpAu8uFV7EdiN",
        "occupation" : "ABC123 Technician",
        "nameOnCard" : "JOLEEN KAPSCH"
    }
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiCardId": "icrd_5bHvgEB2hNrWwjwQhRPJZ0",
        "cFiPrimaryCardId": "icrd_kUSaQbnpNPgnru0SQYCZk",
        "cFiStatus": "Complete",
        "customerId": "cstab_7BX5DO49J48VeWKsJ6gWNb",
        "cFiAggregatorId": "CLIENTID",
        "reference": "extIDCrd304",
        "memberNumber": "cstcb_7BVheqroxnTuAPC6csh9E6",
        "cardProgramId": "d_gpr_test",
        "programType": "debit",
        "boReferenceId": "110195638966866",
        "boCustomerId": "110000001956389668",
        "vAccountNumber": "1234567890123456",
        "abaRoutingNumber": "122244184",
        "dtsCreatedAt": "2024-01-25T13:07:17.555Z",
        "newCardNumber": {
            "number": "1234567890654321",
            "expiryDate": "012027"
        },
        "nameOnCard": "JOLEEN KAPSCH",
        "transId": "F2166340027",
        "batchRecordId": "1824607",
        "fee": 0,
        "balance": 0,
        "lastDepositAmount": 0,
        "ledgerBalance": 0
    },
    "requestId": "aa78cc50bb8211eeaa76ffd7d3224a12"
}