Skip to content

Add Credit Card

Request URL

POST /ibis/credit-card/add

Description

This endpoint will add a new credit card to the specified customer if the customer has an approved credit application on file.

When adding a credit 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 cardHolder addresses, phone numbers, and/or email are not current, please make a request to /customer/update before adding new cards to the desired cardHolder.

The /ibis/credit-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 credit cards may be added to this customer if the customer's credit limit allows, since two requests were made with unique reference IDs (even though the remaining properties are identical)
    "customerId" : "cstap_1Vu13vFOsYLXR2Tsvm68jW",
    "reference" : "EXT_REFERENCE_ID1", //Different reference IDs
    "cardProgramId": "Evolve_Test", 
    "applicationId": "gsa_1odQnDkGpFw6h3CPABjMW0",
    "profile" : {
        "occupation" : "Student",
        "nameOnCard" : "JOHN TESTMAN"
    },
    "creditLimit": 500,
    "creditLimitCurrency": "USD"
}
{ //Two separate credit cards may be added to this customer if the customer's credit limit allows, since two requests were made with unique reference IDs (even though the remaining properties are identical)
    "customerId" : "cstap_1Vu13vFOsYLXR2Tsvm68jW",
    "reference" : "EXT_REFERENCE_ID2", //Different reference IDs
    "cardProgramId": "Evolve_Test", 
    "applicationId": "gsa_1odQnDkGpFw6h3CPABjMW0",
    "profile" : {
        "occupation" : "Student",
        "nameOnCard" : "JOHN TESTMAN"
    },
    "creditLimit": 500,
    "creditLimitCurrency": "USD"
}

Schema

Property table for ibis/credit-card/add

Property Description Required Schema
customerId Customer ID in connectFi Yes {
  "type": "string",
  "pattern": "^[0-9a-zA-Z_]+$",
  "minLength": 1,
  "maxLength": 36,
  "description": "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,
  "description": "common-reference"
}
cardProgramId The card program ID Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "description": "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,
  "description": "common-id"
}
profile An object containing profile details Yes ibisFacade profile object
businessInfo An object containing business details No ibisFacade businessInfo object
applicationId The application ID in connectFi No {
  "type": "string",
  "pattern": "^[0-9a-zA-Z_]+$",
  "minLength": 1,
  "maxLength": 36,
  "description": "common-id"
}
creditLimit The requested credit limit for this card. The minimum and maximum values are configured based on the card program ID. No {
  "type": "number",
  "exclusiveMinimum": 0,
  "amountPrecision": 2,
  "description": "common-amount"
}
creditLimitCurrency A three character ISO alphabetic code to identify the currency No {
  "type": "string",
  "maxLength": 3,
  "minLength": 3,
  "pattern": "^[A-Z]+$",
  "description": "common-currency"
}

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,
  "description": "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,
  "description": "common-idNullable"
}
cardHolderType The type of card holder (required for business account holders only, nullable for individual customers). The value 'representative' indicates that this account holder is categorized as a business representative of the business customer. The value 'individual' indicates that this account holder is either an individual customer or an employee of a business customer, but is not categorized as a business representative. No {
  "type": "string",
  "enum": [ "representative", "individual" ]
}
occupation occupation Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 50,
  "isNotOnlyWhitespace": true,
  "description": "common-commonStr50Req"
}
nameOnCard The name that will be displayed on the card Yes {
  "type": "string",
  "pattern": "^((?![<>]).)*$",
  "minLength": 1,
  "maxLength": 100,
  "isNotOnlyWhitespace": true,
  "description": "common-commonStr100Req"
}

Request Body

{
    "customerId" : "cstap_7uvAC6nLftLGCq7yic3TfI",
    "reference" : "ExtRefICC100", 
    "cardProgramId": "Evolve_Test", 
    "applicationId": "gsa_6iIlCsrasyIr8iwwu7LK8N",
    "profile" : {
        "occupation" : "Student",
        "nameOnCard" : "John Testman"
    },
    "creditLimit": 1500,
    "creditLimitCurrency": "USD"
}

Snippet Examples

javascript

const axios = require('axios');
const data = {
    "customerId" : "cstap_7uvAC6nLftLGCq7yic3TfI",
    "reference" : "ExtRefICC100", 
    "cardProgramId": "Evolve_Test", 
    "applicationId": "gsa_6iIlCsrasyIr8iwwu7LK8N",
    "profile" : {
        "occupation" : "Student",
        "nameOnCard" : "John Testman"
    },
    "creditLimit": 1500,
    "creditLimitCurrency": "USD"
};
const config = {
  method: 'POST',
  url: '${CONNECTFI_BASE_URL}/ibis/credit-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/credit-card/add" --data "{\"customerId\": \"cstap_7uvAC6nLftLGCq7yic3TfI\",   \"reference\": \"ExtRefICC100\",    \"cardProgramId\":\"Evolve_Test\",    \"applicationId\":\"gsa_6iIlCsrasyIr8iwwu7LK8N\",   \"profile\": {        \"occupation\": \"Student\",       \"nameOnCard\": \"John Testman\"    },   \"creditLimit\":1500,   \"creditLimitCurrency\":\"USD\"}" --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" : "ExtRefICC100", 
    "cardProgramId": "Evolve_Test", 
    "applicationId": "gsa_34doT0IgvGnvDgHEmsi54l",
    "profile" : {
        "occupation" : "Student",
        "nameOnCard" : "John Testman"
    },
    "creditLimit": 1500,
    "creditLimitCurrency": "USD"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiCardId": "icrd_5jp4oVmXTH9siQNTouZ7vY",
        "cFiStatus": "Complete",
        "customerId": "cstap_7uvAC6nLftLGCq7yic3TfI",
        "cFiAggregatorId": "CLIENTID",
        "reference": "ExtRefICC100",
        "memberNumber": "cstcp_2WZ7ariGgrtumtUlD452LM",
        "cardProgramId": "Evolve_Test",
        "programType": "credit",
        "boReferenceId": "333219449753",
        "boCustomerId": "333000000002194497",
        "vAccountNumber": "1234567890123456",
        "abaRoutingNumber": "121182810",
        "dtsCreatedAt": "2023-11-01T18:01:29.193Z",
        "newCardNumber": {
            "number": "1234567890654321",
            "expiryDate": "112026"
        },
        "batchReferenceId": "949464",
        "nameOnCard": "John Testman",
        "transId": "F12589471",
        "batchRecordId": "963083",
        "fee": 0,
        "balance": 0,
        "lastDepositAmount": 0,
        "ledgerBalance": 0
    },
    "requestId": "ae8da57078e011eeb5658f28ab5fe311"
}

200 SUCCESSFUL RESPONSE SECONDARY CARD 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",
    "cFiPrimaryCardId": "icrd_5jp4oVmXTH9siQNTouZ7vY",
    "reference" : "ExtRefICC300", 
    "cardProgramId": "Evolve_Test", 
    "applicationId": "gsa_2CA7NFl9c7NBcYi7QpVebE",
    "profile" : {
        "occupation" : "Student",
        "nameOnCard" : "John Testman"
    },
    "creditLimit": 1500,
    "creditLimitCurrency": "USD"
}

RESPONSE BODY

{
    "code": "0",
    "data": {
        "cFiCardId": "icrd_4RAy4xVeEKawTnwEnsg5Ym",
        "cFiPrimaryCardId": "icrd_5jp4oVmXTH9siQNTouZ7vY",
        "cFiStatus": "Complete",
        "customerId": "cstap_7uvAC6nLftLGCq7yic3TfI",
        "cFiAggregatorId": "CLIENTID",
        "reference": "ExtRefICC300",
        "memberNumber": "cstcp_2WZ7ariGgrtumtUlD452LM",
        "cardProgramId": "Evolve_Test",
        "programType": "credit",
        "boReferenceId": "333223240372",
        "boCustomerId": "333000000002232403",
        "vAccountNumber": "1234567890123456",
        "abaRoutingNumber": "121182810",
        "dtsCreatedAt": "2024-01-18T16:35:43.684Z",
        "newCardNumber": {
            "number": "1234567890654321",
            "expiryDate": "012027"
        },
        "batchReferenceId": "954423",
        "nameOnCard": "John Testman",
        "transId": "F12693551",
        "batchRecordId": "968158",
        "fee": 0,
        "balance": 0,
        "lastDepositAmount": 0,
        "ledgerBalance": 0
    },
    "requestId": "9fd03d50b61f11eeaa76ffd7d3224a12"
}