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 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/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, "$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 |
applicationId | The application ID in connectFi | No | { "type": "string", "pattern": "^[0-9a-zA-Z_]+$", "minLength": 1, "maxLength": 36, "$id": "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, "$id": "common-amount" } |
creditLimitCurrency | A three character ISO alphabetic code to identify the currency | No | { "type": "string", "maxLength": 3, "minLength": 3, "pattern": "^[A-Z]+$", "$id": "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, "$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" : "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"
}