Debit and Credit Cards Using /ibis
The /ibis endpoint is used to manage debit cards, credit cards, and vAccounts associated with existing connectFi customers.
| Endpoint | Action |
|---|---|
| /ibis/account/add | Create a vAccount for a specified customer that is not automatically associated with a debit or credit card |
| /ibis/debit-card/add | Create a debit card and associated vAccount for a specified customer |
| /ibis/credit-card/application | Start a credit application |
| /ibis/credit-card/application/:applicationId | Get the status of a credit application |
| /ibis/credit-card/add | Add a credit card for a customer who has received credit approval |
| /ibis/card/activate | Activate a card |
| /ibis/card/set-pin | Set a card PIN |
| /ibis/card/check-pin | Check a card PIN |
| /ibis/card/status | Get the current status of a card |
| /ibis/card/set-status | Set the status of a card |
| /ibis/card/cardholder-profile | Get a card holder profile |
| /ibis/card/reissue | Reissue a card |
| /ibis/card/list | List cards/vAccounts for a specified customer |
| /ibis/financial/card-to-card | Make a card to card funds transfer |
| /ibis/financial/funds-credit | Push funds to a card |
| /ibis/financial/funds-debit | Pull funds from a card |
| /ibis/financial/reversal | Reverse a card to card funds transfer |
| /ibis/financial/retrieve | Retrieve the details of a funds transfer |
| /ibis/inquiry/transaction-history | Get the transaction history for a specified card |
Add Account Only with /ibis
Request method and 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.
To check the KYC/KYB status of a customer before requesting an ibis vAccount, you may use the /customer/status/:customerId endpoint and refer to the kycStatus attribute, or you may use the /akepa/status/:customerId endpoint and verify that the outcome for the KYC/KYB verification application is "Approved". Note that when using /akepa/status/:customerId, 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
}
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| customerId | Customer ID in connectFi | string | "cstap_52fZPjmd0jqFaR3FpZRhec" |
| reference | An external alphanumeric reference ID (1-32 characters) for the account in your system | string | "extCrd118" |
| Additional Properties | Description | Schema | Example Values |
|---|---|---|---|
| profile | An object containing account holder details (required for business account holders only, nullable for individual customers) | object | See profile Object below |
profile Object
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| occupation | The occupation of the account holder | string | "Student" |
| Additional Properties | Description | Schema | Example Values |
|---|---|---|---|
| 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. | string | "extHldr123" |
| accountHolderType | The type of account 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. | string | "individual" or "representative" |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples
Individual Customer
{
"customerId" : "cstap_2IJAI8v1tztwGgdF0tbaHu", //individual customer ID in connectFi
"reference" : "extICrd267", //external reference in your system
}
OR
{
"customerId" : "cstap_2IJAI8v1tztwGgdF0tbaHu", //individual customer ID in connectFi
"reference" : "extICrd267", //external reference in your system
"profile" : {
"accountHolderType": "individual",
"accountHolderId": "cstap_2IJAI8v1tztwGgdF0tbaHu" //same individual customer ID in connectFi
}
}
Business Customer (business representative account holder)
{
"customerId" : "cstab_6DwNo4XuvUYb33vFyAklGE", //customer ID in connectFi
"reference" : "extBICrd297", //external reference in your system
"profile" : {
"accountHolderType": "representative",
"accountHolderId": "cstab_6DwRI8fFRPro1zVNVy8bpe" //business representative ID in connectFi
}
}
Business Customer (employee account holder)
{
"customerId" : "cstab_6DwNo4XuvUYb33vFyAklGE", //customer ID in connectFi
"reference" : "extBICrd298", //external reference in your system
"profile" : {
"accountHolderType": "individual",
"accountHolderId": "cstap_lv8Et5vminK2msONiUFT6" //employee ID in connectFi
}
}
Possible responses
200 (HTTP response status code) -- Account was created
{
"code": "0", //Success
"data": {
"cFiAccountId": "icrd_3Yeh2SYzgv3JXR6zbIauCw", //account ID in connectFi
"accountProgramId": "d_gpr_test", //program ID
"cFiStatus": "Complete", //current status of account in connectFi
"customerId": "cstap_2IJAI8v1tztwGgdF0tbaHu", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "extICrd267", //external reference in your system
"memberNumber": "cstcp_bAceHsbtuPoKTuP3I6zZS", //cFiCommonCustomerId in connectFi
"programType": "vAccountOnly",
"boReferenceId": "110195630208951", //reference ID in the back office
"boCustomerId": "110000001956302089", //customer ID in the back office
"vAccountNumber": "1234567890123456", //vAccountNumber for the account
"abaRoutingNumber": "122244184", //routing number for the account
"dtsCreatedAt": "2023-07-07T16:01:18.780Z",
"batchReferenceId": "1047462",
"transId": "F2165741062",
"batchRecordId": "1728609",
"fee": 0,
"balance": 0,
"lastDepositAmount": 0,
"ledgerBalance": 0
},
"requestId": "826b03001cdf11ee8d0856da8a867924"
}
400 (HTTP response status code) -- Reference already exists
In this example, an account with the requested reference ID already exists. /ibis endpoints support idempotency, therefore reference IDs cannot be reused.
{
"requestId": "70838b906e8c11eebc4256da8a8696e4",
"code": "referenceExists",
"context": {
"reference": "extIAcct289",
"entityId": "icrd_6CWtK180lY8ctp9uhodRMY"
},
"message": "Reference already exists."
}
400 (HTTP response status code) -- Must have required property
In this example, the request body is missing a required field.
{
"requestId": "98ba7f606e8c11eebc4256da8a8696e4",
"code": "requestValidateError",
"context": [
{
"instancePath": "",
"schemaPath": "#/required",
"keyword": "required",
"params": {
"missingProperty": "customerId"
},
"message": "must have required property 'customerId'"
}
]
}
Add a Debit Card with /ibis
Request method and URL
POST /ibis/debit-card/add
Description
This endpoint initializes a debit card for an existing connectFi customer. To check the KYC/KYB status of a customer before requesting an ibis debit card, you may use the /customer/status/:customerId endpoint and refer to the kycStatus attribute, or you may use the /akepa/status/:customerId endpoint and verify that the outcome for the KYC/KYB verification application is "Approved". Note that when using /akepa/status/:customerId, 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/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"
}
}
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| customerId | Customer ID in connectFi | string | "cstap_52fZPjmd0jqFaR3FpZRhec" |
| reference | An external alphanumeric reference ID (1-32 characters) for the card in your system | string | "extCrd118" |
| cardProgramId | The card program ID (the /ibis methods allowed may be limited by the chosen card program) | string | "d_gpr_test" |
| profile | An object containing card holder details | object | See profile Object below |
| Additional Properties | Description | Schema | Example Values |
|---|---|---|---|
| businessInfo | An object containing business details (required for business customers only) | Object | See businessInfo Object below |
| 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.) | string | "icrd_1TstWQoBWENbktDzHv5wmI" |
profile Object
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| nameOnCard | The name that will be displayed on the card | string | "JOHN TESTMAN" |
| occupation | The occupation of the card holder | string | "Student" |
| Additional Properties | Description | Schema | Example Values |
|---|---|---|---|
| cardHolderId | An ID for the cardholder (required for business card holders only, nullable for individual customers). Must match customerId if included for individual customers. | string | "extHldr123" |
| cardHolderType | The type of card holder (required for business card holders only, nullable for individual customers). The value "representative" indicates that this card holder is categorized as a business representative of the business customer. The value "individual" indicates that this card holder is either an individual customer or an employee of a business customer, but is not categorized as a business representative. | string | "individual" or "representative" |
businessInfo Object
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| companyNameOnCard | The name of the company with which the business card is associated | string | "ABC123 Inc." |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples
Individual Customer
{
"customerId" : "cstap_52fZPjmd0jqFaR3FpZRhec", //customer ID in connectFi
"reference" : "extCrd119", //external reference in your system
"cardProgramId": "d_gpr_test", //card program ID
"profile" : {
"occupation" : "Student",
"nameOnCard" : "JOHN TESTMAN"
}
}
OR
{
"customerId" : "cstap_52fZPjmd0jqFaR3FpZRhec", //customer ID in connectFi
"reference" : "extCrd119", //external reference in your system
"cardProgramId": "d_gpr_test", //card program ID
"profile" : {
"occupation" : "Student",
"nameOnCard" : "JOHN TESTMAN",
"cardHolderType": "individual", //will be ignored if the value of cardHolderType is "representative" for an individual customer
"cardHolderId": "cstap_52fZPjmd0jqFaR3FpZRhec" //same individual customer ID in connectFi
}
}
Business Customer (business representative card holder)
{
"customerId" : "cstab_6DwNo4XuvUYb33vFyAklGE", //customer ID in connectFi
"reference" : "extBCrd138", //external reference in your system
"cardProgramId": "d_gpr_test", //card program ID
"businessInfo" : {
"companyNameOnCard" : "ABC123 Inc."
},
"profile" : {
"cardHolderId" : "cstab_1Vu13vFOsYLXR2TsvmaB15", //business representative ID in connectFi
"cardHolderType": "representative",
"occupation" : "Business Owner",
"nameOnCard" : "JOHN TESTMAN"
}
}
Business Customer (employee card holder)
{
"customerId" : "cstab_6DwNo4XuvUYb33vFyAklGE", //customer ID in connectFi
"reference" : "extBCrd138", //external reference in your system
"cardProgramId": "d_gpr_test", //card program ID
"businessInfo" : {
"companyNameOnCard" : "ABC123 Inc."
},
"profile" : {
"cardHolderId" : "cstap_lv8Et5vminK2msONiUFT6", //employee ID in connectFi
"cardHolderType": "individual",
"occupation" : "ABC123 Technician",
"nameOnCard" : "JOHN TESTMAN"
}
}
Possible responses
200 (HTTP response status code) -- Debit card was created
{
"code": "0", //Success
"data": {
"cFiCardId": "icrd_1oSrT1U8G73S5Jdt27YvYk", //card ID in connectFi
"cFiStatus": "Complete", //current status of card in connectFi
"customerId": "cstap_52fZPjmd0jqFaR3FpZRhec", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "extCrd119", //external reference in your system
"memberNumber": "cstcp_52e2LP956OeKH3dnaDBVlS", //cFiCommonCustomerId in connectFi
"cardProgramId": "d_gpr_test", //card program ID
"programType": "debit",
"boReferenceId": "123456789012", //reference ID in the back office
"boCustomerId": "333000000001234567", //customer ID in the back office
"vAccountNumber": "1234567890123456",
"abaRoutingNumber": "122244184",
"dtsCreatedAt": "2023-03-15T18:19:36.135Z",
"newCardNumber": {
"number": "1234567890123456", //16 digit card PAN
"expiryDate": "032026" //card expiration date
},
"batchReferenceId": "838161",
"nameOnCard": "JOHN TESTMAN",
"transId": "F2156023329",
"batchRecordId": "1518398",
"fee": 0,
"balance": 0, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 0 //ledger balance
},
"requestId": "f0e640f0c35d11edaa15c5641dffda7c"
}
400 (HTTP response status code) -- Reference already exists
In this example, a debit card with the same reference ID already exists. /ibis endpoints support idempotency, therefore reference IDs cannot be reused.
{
"requestId": "089834906e9111eebc4256da8a8696e4",
"code": "referenceExists",
"context": {
"reference": "extBCrd190",
"entityId": "icrd_3r2Jh1t0G4IXFvz5Q559cQ"
},
"message": "Reference already exists."
}
400 (HTTP response status code) -- Card program not found
In this example, the cardProgramId used was invalid.
{
"requestId": "71286f606e9211eebc4256da8a8696e4",
"code": "ibisProgramNotSupported",
"context": {
"programId": "d_gpr_test1"
},
"message": "The requested card or account program is not supported for this customer."
}
Apply for Credit with /ibis
Request method and URL
POST /ibis/credit-card/application
Description
This endpoint initializes a credit card application for the indicated customer. To check the KYC/KYB status of a customer before requesting an ibis debit card, you may use the /customer/status/:customerId endpoint and refer to the kycStatus attribute, or you may use the /akepa/status/:customerId endpoint and verify that the outcome for the KYC/KYB verification application is "Approved". Note that when using /akepa/status/:customerId, 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.
Note: It is possible to have multiple credit applications for the same customer. For example, the following requests may result in two separate credit applications.
{ //same customer data
"customerId" : "cstap_1Vu13vFOsYLXR2Tsvm68jW",
"employer" : "ABC123 Inc.",
"totalAnnualIncome" : 50000,
"totalAnnualIncomeCurrency" : "USD"
}
{ //same customer data
"customerId" : "cstap_1Vu13vFOsYLXR2Tsvm68jW",
"employer" : "ABC123 Inc.",
"totalAnnualIncome" : 50000,
"totalAnnualIncomeCurrency" : "USD"
}
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| customerId | Customer ID in connectFi | string | "cstap_1Vu13vFOsYLXR2Tsvm68jW" |
| employer | The card holder's employer | string | "ABC123 Inc." |
| totalAnnualIncome | The card holder's total annual income | number, >=0 | 50000 |
| totalAnnualIncomeCurrency | A three character ISO alphabetic code to identify the currency | String, regex pattern: "^[A-Z]{3}$" | "USD" |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example
{
"customerId" : "cstap_1Vu13vFOsYLXR2Tsvm68jW", //customer ID in connectFi
"employer" : "ABC123 Inc.", //card holder's employer
"totalAnnualIncome" : 50000, //card holder's total annual income
"totalAnnualIncomeCurrency" : "USD" //currency code (represented by 3 characters)
}
Possible responses
200 (HTTP response status code) -- Application was initialized
{
"code": "0", //Success
"data": {
"applicationId": "gsa_1odQnDkGpFw6h3CPABjMW0", //application ID in connectFi
"customerId": "cstap_1Vu13vFOsYLXR2Tsvm68jW", //customer ID in connectFi
"creditFreeze": false, //true if the customer is under a credit freeze
"creditLimit": 2700, //credit limit is present if the "decision" property has an "Approve" value
"creditLimitCurrency": "USD", //currency code (represented by 3 characters)
"decision": "Approve", //current application decision status
"adverseAction": []
},
"requestId": "2db13360e8f611ed90c856da8a864fc4"
}
400 (HTTP response status code) -- Customer requires KYC/KYB
In this example, a credit application request was made before the customer has passed the KYC/KYB process with an "APPROVED" status.
{
"requestId": "e2dc0ac0733011ee94f256da8a860d80",
"code": "kycNotInitialized",
"context": {
"customerId": "cstap_6CE6xwrQbTXb8RB2zp2qB2"
},
"message": "KYC/KYB identification not found for this customer."
}
Get Credit Card Application Status with /ibis
Request method and URL
GET /ibis/credit-card/application/:applicationId
Description
This endpoint retrieves the current details of an existing credit card application for the indicated customer. The applicationId is passed as a path parameter.
Request headers
{
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example None
Possible responses
200 (HTTP response status code) -- Application status was retrieved
{
"code": "0", //Success
"data": {
"applicationId": "gsa_1odQnDkGpFw6h3CPABjMW0", //application ID in connectFi
"customerId": "cstap_1Vu13vFOsYLXR2Tsvm68jW", //customer ID in connectFi
"creditFreeze": false, //true if the customer is under a credit freeze
"creditLimit": 2700, //credit limit is present if the "decision" property has an "Approve" value
"creditLimitCurrency": "USD", //currency code (represented by 3 characters)
"decision": "Approve", //current application decision status
"adverseAction": []
},
"requestId": "9c9acbf0e8f711edab7956da8a863158"
}
400 (HTTP response status code) -- Application not found
In this example, the applicationId requested does not exist.
{
"requestId": "7980f1206e9511eebc4256da8a8696e4",
"code": "ibisApplicationNotFound",
"context": {
"applicationId": "gsa_hsTrKNlU8sapLGjUimPrG1"
},
"message": "Credit application not found."
}
Add a Credit Card with /ibis
Request method and 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.
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"
}
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| customerId | Customer ID in connectFi | string | "cstap_1Vu13vFOsYLXR2Tsvm68jW" |
| reference | An external alphanumeric reference ID (1-32 characters) for the card in your system | string | "extCrd120" |
| profile | An object containing card holder details | object | See profile Object |
| cardProgramId | The card program ID (the /ibis methods allowed may be limited by the chosen card program) | string | "Evolve_Test" |
| applicationId | The application ID in connectFi | string | "gsa_1odQnDkGpFw6h3CPABjMW0" |
| creditLimit | The requested card holder credit limit for this card. The minimum and maximum values are configured based on the card program ID. | number, >=0 | 600 |
| creditLimitCurrency | A three character ISO alphabetic code to identify the currency | string, regex pattern: "^[A-Z]{3}$" | "USD" |
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| businessInfo | An object containing business details if this is a business card | Object | See businessInfo Object |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example
Individual Customer
{
"customerId" : "cstap_1Vu13vFOsYLXR2Tsvm68jW", //customer ID in connectFi
"reference" : "324333260", //external reference in your system
"cardProgramId": "Evolve_Test", //card program ID
"applicationId": "gsa_1odQnDkGpFw6h3CPABjMW0", //application ID in connectFi
"profile" : {
"occupation" : "Student",
"nameOnCard" : "JOHN TESTMAN"
},
"creditLimit": 600, //requested credit limit
"creditLimitCurrency": "USD" //currency code (represented by 3 characters)
}
Possible responses
200 (HTTP response status code) -- Credit card was added
{
"code": "0", //Success
"data": {
"cFiCardId": "icrd_5lFBjJG6pPlapyodSxZ97a", //card ID in connectFi
"cFiStatus": "Complete", //current status of card in connectFi - "Initiated", "Complete", or "Error"
"customerId": "cstap_1Vu13vFOsYLXR2Tsvm68jW", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "324333260", //external reference in your system
"memberNumber": "cstcp_bAceHsbtuPoKTuP3I6zZS", //cFiCommonCustomerId in connectFi
"cardProgramId": "Evolve_Test", //card program ID
"boReferenceId": "123456789012", //reference ID in the back office
"boCustomerId": "333000000001234567", //customer ID in the back office
"vAccountNumber": "1234567890123456",
"abaRoutingNumber": "121182810",
"dtsCreatedAt": "2023-05-02T15:12:00.185Z",
"newCardNumber": {
"number": "1234567890123456", //16 digit card PAN
"expiryDate": "052026" //card expiration date
},
"batchReferenceId": "942860",
"nameOnCard": "JOHN TESTMAN", //card holder name as shown on card
"transId": "F10287390",
"batchRecordId": "955680",
"fee": 0,
"balance": 0, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 0 //ledger balance
},
"requestId": "afaf73e0e8fb11edab7956da8a863158"
}
400 (HTTP response status code) -- Application is not approved
In this example, a request was made to add a credit card to a customer whose application has not yet been approved.
{
"requestId": "e2b550a06e9511eebc4256da8a8696e4",
"code": "ibisApplicationIsNotApproved",
"context": {
"applicationId": "gsa_74gOOiTLXLB0xGxAM3r6ac" //application ID in connectFi
},
"message": "Application is not APPROVED."
}
400 (HTTP response status code) -- Reference ID exists
In this example, a request was made using a reference ID that already exists.
{
"requestId": "089834906e9111eebc4256da8a8696e4",
"code": "referenceExists",
"context": {
"reference": "extBCrd190",
"entityId": "cstap_3r2Jh1t0G4IXFvz5Q559cQ"
},
"message": "Reference already exists."
}
400 (HTTP response status code) -- Requested credit limit is over the approved credit limit for this customer
In this example, a request was made with a desired credit limit of 3600, but the customer's credit application was only approved for a limit of up to 2700.
{
"requestId": "1ee1d3506e9611eebc4256da8a8696e4",
"code": "ibisApplicationCreditLimit",
"context": {
"applicationId": "gsa_3CewkFVb2fHgIUUHJkKm8",
"creditLimit": 2700
},
"message": "Credit limit in application is less than the requested credit limit."
}
400 (HTTP response status code) -- Allocated credit limit must be less than or equal to ___
In this example, the customer is requesting a card with a credit limit of 2600. Even though the requested credit limit of 2600 is less than the 2700 approved credit limit for this customer, it is over the allocated credit limit of 2000 for a single card.
{
"requestId": "4bc8baa06e9611eebc4256da8a8696e4",
"code": "extIbis",
"subCode": "12",
"context": {
"transId": "F12584198",
"fee": 0
},
"message": "New Card Purchase Decline (Allocated credit limit must be less than or equal to [2000.0]; )"
}
400 (HTTP response status code) -- Allocated credit limit must be greater than or equal to ___
In this example, a request was made for a card with a 200 credit limit, which is below the minimum 500 credit limit threshold.
{
"requestId": "7a5ae0f06e9611eebc4256da8a8696e4",
"code": "extIbis",
"subCode": "12",
"context": {
"transId": "F12584199",
"fee": 0
},
"message": "New Card Purchase Decline (Allocated credit limit must be greater than or equal to [500.0]; )"
}
Activate a Card
Request method and URL
POST /ibis/card/activate
Description
Use this endpoint to activate a card created with /ibis. A successful request will activate the card and return the relevant details for the card.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiCardId | The card ID in connectFi | string | "icrd_1oSrT1U8G73S5Jdt27YvYk" |
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| attributes | An object containing an optional cardExpDate property, nullable | object | { //See attributes Object below } |
attributes Object
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| cardExpDate | The card expiration date in MMYY format, nullable | string, regex pattern "^\d{4}$" | "1226" |
Status Values Allowed
An /ibis/card/activate request can successfully be made for cards with the following status values: "A" (Pre-Active), "S" (OFF), "I". (Inactive)
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example
Possible responses
200 (HTTP response status code) -- Card was activated
{
"code": "0", //Success
"data": {
"cFiCardId": "icrd_6UkNHDUvtNpY39qAyWAruU", //card ID in connectFi
"cFiStatus": "Complete", //current status of card in connectFi
"customerId": "cstap_52fZPjmd0jqFaR3FpZRhec", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "extCrd118", //external reference in your system
"memberNumber": "cstcp_52e2LP956OeKH3dnaDBVlS", //cFiCommonCustomerId in connectFi
"cardProgramId": "d_gpr_test", //card program ID
"programType": "debit",
"boReferenceId": "123456789012", //reference ID in the back office
"boCustomerId": "333000000001234567", //customer ID in the back office
"vAccountNumber": "1234567890123456",
"abaRoutingNumber": "122244184",
"dtsCreatedAt": "2023-03-15T18:47:50.599Z",
"expiryDate": "032026", //card expiration date
"cardReferenceId": "110195062153442",
"maaSubUnSubRespDesc": "Approved",
"transId": "F2156023986",
"fee": 0,
"balance": 0, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit
"ledgerBalance": 0 //ledger balance
},
"requestId": "195b94f0c36c11edaa15c5641dffda7c"
}
400 (HTTP response status code) -- Card is already active
A request was made to activate a card that has already been activated.
{
"requestId": "eabf40606e9c11eebc4256da8a8696e4",
"code": "extIbis",
"subCode": "97",
"context": {
"transId": "F2165959893",
"fee": 0
},
"message": "Activate Debit Card Decline (Card is already active)"
}
400 (HTTP response status code) -- The given card is closed
In this example, the given card is closed (status code "F" - Closed Card).
{
"requestId": "37b936f06e9d11eebc4256da8a8696e4",
"code": "extIbis",
"subCode": "SD",
"context": {
"transId": "F2165959898",
"fee": 0
},
"message": "Activate Debit Card Decline (Closed Card)"
}
Set a Card PIN with /ibis
Request method and URL
POST /ibis/card/set-pin
Description
This endpoint will set a specified valid PIN for the given card. The PIN must be set using /ibis/card/set-pin before an /ibis/card/check-pin request can succeed. You may use this endpoint to set an initial card PIN, as well as to update an existing card PIN.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiCardId | The card ID in connectFi | string | "icrd_1PnLbkm5fJpMELm4Z8l2AM" |
| pin | A four digit PIN | string, regex pattern: "^\d{4}$" | "1234" |
Status Values Allowed
An /ibis/card/set-pin request can successfully be made for pre-active (status "A") and active/ON (status "B") cards.
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example
Possible responses
200 (HTTP response status code) -- Success, the PIN was set
{
"code": "0", //Success
"data": {
"cFiCardId": "icrd_1PnLbkm5fJpMELm4Z8l2AM", //card ID in connectFi
"cFiStatus": "Complete", //current status of card in connectFi - "Initiated", "Complete", or "Error"
"customerId": "cstap_52fZPjmd0jqFaR3FpZRhec", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "extCrd127", //external reference in your system
"memberNumber": "cstcp_52e2LP956OeKH3dnaDBVlS", //cFiCommonCustomerId in connectFi
"cardProgramId": "d_gpr_test", //card program ID
"programType": "debit",
"boReferenceId": "123456789012", //reference ID in the back office
"boCustomerId": "333000000001234567", //customer ID in the back office
"vAccountNumber": "1234567890123456",
"abaRoutingNumber": "121182810",
"dtsCreatedAt": "2023-03-17T18:12:10.275Z",
"cardProgramName": "GPR Card Program",
"transId": "F2156126323",
"fee": 0,
"balance": 0, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 0 //ledger balance
},
"requestId": "8650fb50c4f111ed996dc5641dffde20"
}
400 (HTTP response status code) -- Must match pattern
A PIN must be a 4 digit numeric string.
{
"requestId": "43bcea10c4f111ed996dc5641dffde20",
"code": "requestValidateError",
"context": [
{
"instancePath": "/pin",
"schemaPath": "#/properties/pin/pattern",
"keyword": "pattern",
"params": {
"pattern": "^\\d{4}$"
},
"message": "must match pattern \"^\\d{4}$\""
}
]
}
400 (HTTP response status code) -- The given card is blocked
In this example, the given card has been blocked (status code "S" - blocked because lost or suspected fraud).
{
"requestId": "212683f0c4f411ed996dc5641dffde20",
"code": "extIbis",
"subCode": "59",
"context": {
"transId": "F2156126360",
"fee": 0
},
"message": "Set Card PIN Decline (Suspected Fraud Hit, Card is Already Blocked)"
}
400 (HTTP response status code) -- The given card is inactive
In this example, the given card is inactive (status code "I" - inactive).
{
"requestId": "77c3b6a0c4f511ed996dc5641dffde20",
"code": "extIbis",
"subCode": "SA",
"context": {
"transId": "F2156126375",
"fee": 0
},
"message": "Set Card PIN Decline (Inactive Card)"
}
400 (HTTP response status code) -- The given card is closed
In this example, the given card is closed (status code "F" - Closed Card).
{
"requestId": "388cbda0c4f611ed996dc5641dffde20",
"code": "extIbis",
"subCode": "SD",
"context": {
"transId": "F2156126393",
"fee": 0
},
"message": "Set Card PIN Decline (Closed Card)"
}
Check a Card PIN with /ibis
Request method and URL
POST /ibis/card/check-pin
Description
This endpoint accepts requests to check to see if a specified PIN matches the given card PIN. The request is successful only if the PIN is a match. The PIN must be set using an /ibis/card/set-pin request before attempting to check the PIN. In addition, the request will fail if the card has not yet been activated, even if the correct PIN is given. Make sure to activate the card with an /ibis/card/activate request before checking for a PIN match.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiCardId | The card ID in connectFi | string | "icrd_1PnLbkm5fJpMELm4Z8l2AM" |
| pin | A four digit PIN to check for a match against the PIN stored for the given card | string, regex pattern: "^\d{4}$" | "1234" |
Status Values Allowed
An /ibis/card/check-pin request can successfully be made for cards with the following status values: "B" (ON).
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example
Possible responses
200 (HTTP response status code) -- Success, the given PIN matches the stored PIN for the card
{
"code": "0", //Success
"data": {
"cFiCardId": "icrd_1PnLbkm5fJpMELm4Z8l2AM", //card ID in connectFi
"cFiStatus": "Complete", //current status of card in connectFi - "Initiated", "Complete", or "Error"
"customerId": "cstap_52fZPjmd0jqFaR3FpZRhec", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "extCrd127", //external reference in your system
"memberNumber": "cstcp_52e2LP956OeKH3dnaDBVlS", //cFiCommonCustomerId in connectFi
"cardProgramId": "d_gpr_test", //card program ID
"programType": "debit",
"boReferenceId": "123456789012", //reference ID in the back office
"boCustomerId": "333000000001234567", //customer ID in the back office
"vAccountNumber": "1234567890123456",
"abaRoutingNumber": "121182810",
"dtsCreatedAt": "2023-03-17T18:12:10.275Z",
"transId": "F2156126330",
"fee": 0,
"balance": 0, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 0 //ledger balance
},
"requestId": "520a4d50c4f211ed996dc5641dffde20"
}
400 (HTTP response status code) -- The given card is pre-active
In this example, the given card has not yet been activated (status code "A" - pre-active).
{
"requestId": "36c48f80c4f011ed996dc5641dffde20",
"code": "extIbis",
"subCode": "PA",
"context": {
"transId": "F2156126313",
"fee": 0
},
"message": "Card Number(99*************4286) is pre-active"
}
400 (HTTP response status code) -- The given card is blocked
In this example, the given card has been blocked (status code "S" - blocked because lost or suspected fraud).
{
"requestId": "bc4c56d0c4f311ed996dc5641dffde20",
"code": "extIbis",
"subCode": "59",
"context": {
"transId": "F2156126354",
"fee": 0
},
"message": "Card Number(99*************4286) is blocked due to suspected fraud"
}
400 (HTTP response status code) -- The given card is inactive
In this example, the given card is inactive (status code "I" - inactive).
{
"requestId": "54752b70c4f511ed996dc5641dffde20",
"code": "extIbis",
"subCode": "SA",
"context": {
"transId": "F2156126374",
"fee": 0
},
"message": "Card Number(99*************4286) is inactive"
}
400 (HTTP response status code) -- The given card is closed
In this example, the given card is closed (status code "F" - Closed Card).
{
"requestId": "8f126620c4f611ed996dc5641dffde20",
"code": "extIbis",
"subCode": "SD",
"context": {
"transId": "F2156126396",
"fee": 0
},
"message": "Card Number(99*************4286) is closed"
}
400 (HTTP response status code) -- Invalid PIN supplied
In this example, the specified PIN is not a match for the given card.
{
"requestId": "25fa8190c4f111ed996dc5641dffde20",
"code": "extIbis",
"subCode": "55",
"context": {
"transId": "F2156126322",
"fee": 0
},
"message": "Invalid PIN supplied for Card No(99*************4286)"
}
400 (HTTP response status code) -- Must match pattern
A PIN must be a 4 digit numeric string.
{
"requestId": "43bcea10c4f111ed996dc5641dffde20",
"code": "requestValidateError",
"context": [
{
"instancePath": "/pin",
"schemaPath": "#/properties/pin/pattern",
"keyword": "pattern",
"params": {
"pattern": "^\\d{4}$"
},
"message": "must match pattern \"^\\d{4}$\""
}
]
}
Get the Status of a Card
Request method and URL
POST /ibis/card/status
Description
Use this endpoint to check the status of a card created with /ibis. A successful request will return the available details for the requested card. Either the cFiCardId or the reference ID can be used to request the card status, but not both in the same request.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiCardId | The card ID in connectFi | string | "icrd_1oSrT1U8G73S5Jdt27YvYk" |
OR
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| reference | An external alphanumeric reference ID (1-32 characters) for the card in your system | string | "extCrd119" |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples
Using cFiCardId:
Using reference:
Possible responses
200 (HTTP response status code) -- Card details are returned
{
"code": "0", //Success
"data": {
"cFiCardId": "icrd_1oSrT1U8G73S5Jdt27YvYk", //card ID in connectFi
"cFiStatus": "Complete", //current status of card in connectFi - "Initiated", "Complete", or "Error"
"customerId": "cstap_52fZPjmd0jqFaR3FpZRhec", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "extCrd119", //external reference in your system
"memberNumber": "cstcp_52e2LP956OeKH3dnaDBVlS", //cFiCommonCustomerId in connectFi
"cardProgramId": "d_gpr_test", //card program ID
"programType": "debit",
"boReferenceId": "123456789012", //reference ID in the back office
"boCustomerId": "333000000001234567", //customer ID in the back office
"vAccountNumber": "1234567890123456",
"abaRoutingNumber": "121182810",
"dtsCreatedAt": "2023-03-15T19:04:15.498Z",
"isBadPinTriesExceeded": "N",
"status": {
"code": "A", //Newly issued card, not yet activated
"description": "Card was issued but has not yet been activated"
},
"transitionFlag": "N",
"isOfflinePinTryLimitExceeded": "N",
"fee": 0,
"balance": 0, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 0 //ledger balance
},
"requestId": "4c8018d0c36511edaa15c5641dffda7c"
}
400 (HTTP response status code) -- Must match exactly one schema in oneOf, must NOT have additional properties
In this example, both the cFiCardId property and the reference ID property were used in the same request. Use only one type of ID in a single request.
{
"requestId": "abab8cc0c43911ed9e40c5641e001f9c",
"code": "requestValidateError",
"context": [
{
"instancePath": "",
"schemaPath": "#/oneOf/0/additionalProperties",
"keyword": "additionalProperties",
"params": {
"additionalProperty": "reference"
},
"message": "must NOT have additional properties"
},
{
"instancePath": "",
"schemaPath": "#/oneOf/1/additionalProperties",
"keyword": "additionalProperties",
"params": {
"additionalProperty": "cFiCardId"
},
"message": "must NOT have additional properties"
},
{
"instancePath": "",
"schemaPath": "#/oneOf",
"keyword": "oneOf",
"params": {
"passingSchemas": null
},
"message": "must match exactly one schema in oneOf"
}
]
}
Set the Status of a Card
Request method and URL
POST /ibis/card/set-status
Description
Use this endpoint to set the status of a card created with /ibis. A successful request will update the card status and return the relevant details for the requested card.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiCardId | The card ID in connectFi | string | "icrd_1oSrT1U8G73S5Jdt27YvYk" |
| statusCode | The desired status code, see Ibis Card Status Codes below | string | "I", "B", "S", or "F" |
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| description | An optional description of the reason for the status update (1-60 characters) | string | "Lost the card" |
Ibis Card Status Codes
The following table gives a brief description of each status code and specifies which /ibis/card/ endpoints are allowed for the given status codes.
| Status Code | Description | activate allowed? |
check-pin allowed? |
set-pin allowed? |
status allowed? |
set-status allowed? |
|---|---|---|---|---|---|---|
| "A" | Card was issued but has not yet been activated (This is an initial card status only. You may not set a card to this status value through this endpoint.) | Yes | NO | Yes | Yes | Yes |
| "B" | ON, Open - All Transactions Allowed | NO | Yes | Yes | Yes | Yes |
| "I" | Inactive | Yes | NO | NO | Yes | Yes |
| "S" | OFF, FRAUD or LOST | Yes | NO | NO | Yes | Yes |
| "F" | Closed | NO | NO | NO | Yes | NO |
Allowed Status Changes
The following table explains which status code changes may occur using the /ibis/card/set-status endpoint.
| Initial Status Code | Allowed Status Update Values |
|---|---|
| "A" | "B", "F", "I", "S" |
| "B" | "F", "I", "S" |
| "F" | none |
| "I" | "F", "S" |
| "S" | "B", "F" |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example
{
"cFiCardId" : "icrd_1oSrT1U8G73S5Jdt27YvYk", //card ID in connectFi
"statusCode" : "B" //"I" = Inactive, "B" = ON, "S" = OFF, or "F" = Closed
}
Possible responses
200 (HTTP response status code) -- Debit card status was updated
{
"code": "0", //Success
"data": {
"cFiCardId": "icrd_1oSrT1U8G73S5Jdt27YvYk", //card ID in connectFi
"cFiStatus": "Complete", //current status of card in connectFi - "Initiated", "Complete", or "Error"
"customerId": "cstap_52fZPjmd0jqFaR3FpZRhec", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "extCrd119", //external reference in your system
"memberNumber": "cstcp_52e2LP956OeKH3dnaDBVlS", //cFiCommonCustomerId in connectFi
"cardProgramId": "d_gpr_test", //card program ID
"programType": "debit",
"boReferenceId": "123456789012", //reference ID in the back office
"boCustomerId": "333000000001234567", //customer ID in the back office
"vAccountNumber": "1234567890123456",
"abaRoutingNumber": "121182810",
"dtsCreatedAt": "2023-03-15T19:04:15.498Z",
"status": {
"code": "B", //ON
"description": "Open - All Transactions Allowed"
},
"cardProgramName": "GPR Card Program",
"transId": "F2156023550",
"fee": 0,
"balance": 0, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 0 //ledger balance
},
"requestId": "e7794b80c36611edaa15c5641dffda7c"
}
400 (HTTP response status code) -- Must be equal to one of the allowed values
In this example, a request was made to set the card status to "A". Even though cards do have a status of "A" when first created in order to indicate that the card needs to be activated, this is not a status that can be set with the /ibis/card/set-status endpoint. Any other invalid statusCode will receive a similar result.
{
"requestId": "5afd3a70c36d11edaa15c5641dffda7c",
"code": "requestValidateError",
"context": [
{
"instancePath": "/statusCode",
"schemaPath": "#/properties/statusCode/enum",
"keyword": "enum",
"params": {
"allowedValues": [
"I", //Inactive
"B", //ON
"S", //OFF
"F" //CLOSED
]
},
"message": "must be equal to one of the allowed values"
}
]
}
400 (HTTP response status code) -- The given card is closed
In this example, the given card is closed (status code "F" - Closed Card).
{
"requestId": "046caa70c4f711ed996dc5641dffde20",
"code": "extIbis",
"subCode": "SD",
"context": {
"transId": "F2156126400",
"fee": 0
},
"message": "Card Number(99*************4286) is closed"
}
400 (HTTP response status code) -- Changing card status from existing status to status (I) is not allowed
In this example, an attempt was made to change a card with status "S" (blocked because lost or fraud) to "I" (inactive) was made. This status change is not allowed.
{
"requestId": "0535dbf0c4f911ed996dc5641dffde20",
"code": "extIbis",
"subCode": "57",
"context": {
"transId": "F2156126426",
"fee": 0
},
"message": "Changing card status from existing status to status (I) is not allowed for card (99*************2802)"
}
Get a Card Holder Profile
Request method and URL
POST /ibis/card/cardholder-profile
Description
Use this endpoint to retrieve the card holder profile for the specified card.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiCardId | The card ID in connectFi | string | "icrd_71iRvTzeQckz3fNxQ2DVqM" |
OR
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| reference | An external alphanumeric reference ID (1-32 characters) for the card in your system | string | "extCrd119" |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples
Using cFiCardId:
Using reference:
Possible responses
200 (HTTP response status code) -- Card holder profile was returned
{
"code": "0", //Success
"data": {
"cFiCardId": "icrd_71iRvTzeQckz3fNxQ2DVqM", //card ID in connectFi
"cFiStatus": "Complete", //current status of card in connectFi - "Initiated", "Complete", or "Error"
"customerId": "cstap_1Vu13vFOsYLXR2Tsvm68jW", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "324333263", //external reference in your system
"memberNumber": "cstcp_bAceHsbtuPoKTuP3I6zZS", //cFiCommonCustomerId in connectFi
"cardProgramId": "Evolve_Test", //card program ID'
"programType": "credit",
"boReferenceId": "123456789012", //reference ID in the back office
"boCustomerId": "333000000001234567", //customer ID in the back office
"vAccountNumber": "1234567890123456",
"abaRoutingNumber": "121182810",
"dtsCreatedAt": "2023-05-02T15:42:10.301Z",
"abaRoutingNumber": "123456789",
"stakeholderId": "StakHolder",
"status": {
"code": "A",
"description": "Card was issued but has not yet been activated"
},
"transitionFlag": "N",
"statusCode": "A",
"firstName": "JOHN",
"lastName": "TESTMAN",
"address1": "1234 SWEETBRIAR LN",
"address2": "Apt 1",
"dob": "1970-01-01",
"city": "TYLER",
"stateCode": "TX",
"postalCode": "12345",
"country": "USA",
"expDate": "2026-05-31",
"cardType": "E",
"cellNumber": "1234567890",
"email": "brucey@gmail.com",
"occupation": "Student",
"cipCleared": "N",
"pseudoDdaNumbers": [
{
"pseudoDdaNumber": "1211210001590305"
}
],
"cardDeliveryMode": "P",
"cardNumber": "123456******1234",
"fee": 0,
"balance": 0, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 0 //ledger balance
},
"requestId": "13e06be0e90011edab7956da8a863158"
}
400 (HTTP response status code) -- The given card is closed
In this example, the given card is closed (status code "F" - Closed Card).
{
"requestId": "3de6b750c4f711ed996dc5641dffde20",
"code": "extIbis",
"subCode": "SD",
"context": {
"fee": 0,
"lastDepositAmount": 0
},
"message": "Get Cardholder Profile Decline (Closed Card)"
}
Reissue a Card
Request method and URL
POST /ibis/card/reissue
Description
Use this endpoint to reissue a specified card. A card can be reissued with the existing card number (in cases such as when the expiration date is updated), or the card can be reissued using a new card number (in cases such as if the card has been lost or stolen).
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiCardId | The card ID in connectFi | string | "icrd_71iRvTzeQckz3fNxQ2DVqM" |
| reference | An external alphanumeric reference ID (1-32 characters) for the card in your system | string | "extCrd119" |
| profile | An object containing card holder details | object | See profile Object |
| reissueType | The type of reissue, allowed reissue types are dependent on card program permissions (see Reissue Codes below) | string | "1", "2", or "3" |
| reasonCode | The reason for the reissue, allowed reason codes are dependent on card program permissions (see Reissue Codes below) | string | "1", "2", "3", "4", "5", or "6" |
| cardShippingMethodId | The shipping method for the new card, "1" is default (see Reissue Codes below) | string | "1", "2", or "3" |
| activateNewCard | If "Y", the new card will be activated upon reissue, "N" is default | string | "Y" or "N" |
Reissue Codes
| reasonCode Value | reissueType Value | cardShippingMethodId Value |
|---|---|---|
| "1" - Damaged | "1" - same card number with same profile | "1" - Normal shipment (default) |
| "2" - Expired | "2" - same card number with updated expiration | "2" - Urgent shipment |
| "3" - Lost/Stolen | "3" - new card number with existing profile | "3" - VIP shipment |
| "4" - Fraud/Compromised | ||
| "5" - Return | ||
| "6" - New Enrollment |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples
Using cFiCardId:
{
"cFiCardId" : "icrd_71iRvTzeQckz3fNxQ2DVqM", //card ID in connectFi
}
{
"cFiCardId" : "icrd_4cFaZs9DMGC38tT7z3XPok", //card ID in connectFi
"reference": "extReI126", //external reference in your system, ignored unless card is reissued with a new card number
"profile": {
"address": "1234 SWEETBRIAR LN",
"address2": "Apt 1",
"city": "TYLER",
"stateCode": "TX",
"postalCode": "12345",
"cellNumber": "1234567890",
"email": "newemail1@test.email",
"nameOnCard": "JOHN TESTMAN"
},
"reissueType": "3", //type of reissue (see Reissue Codes)
"reasonCode": "3", //reason for reissue (see Reissue Codes)
"cardShippingMethodId": "1", //shipping method (see Reissue Codes)
"activateNewCard": "N" //if "Y", card is activated upon reissue
}
Possible responses
200 (HTTP response status code) -- Card was reissued
{
"code": "0", //Success
"data": {
"cFiCardId": "icrd_5KvDGUYMyUWX5JB8XcuZvy", //card ID in connectFi, new only if card was reissued with a new number
"cFiStatus": "Complete", //current status of card in connectFi - "Initiated", "Complete", or "Error"
"customerId": "cstap_1Vu13vFOsYLXR2Tsvm68jW", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "extReI126", //external reference in your system
"memberNumber": "cstcp_bAceHsbtuPoKTuP3I6zZS", //cFiCommonCustomerId in connectFi
"cardProgramId": "Evolve_Test", //card program ID
"programType": "credit",
"boReferenceId": "123456789012", //reference ID in the back office
"boCustomerId": "333000000001234567", //customer ID in the back office
"vAccountNumber": "1234567890123456",
"abaRoutingNumber": "121182810",
"dtsCreatedAt": "2023-06-07T12:49:27.649Z",
"newCardReferenceId": "123456789012", //present if card was reissued with a new number
"transId": "F10332010",
"fee": 0,
"balance": 0, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 0 //ledger balance
},
"requestId": "bc5bc010053111ee841656da8a864888"
}
400 (HTTP response status code) -- Reference already exists
In this example, a request was made to reissue the card with a new card number, but the given reference ID already exists.
{
"requestId": "089834906e9111eebc4256da8a8696e4",
"code": "referenceExists",
"context": {
"reference": "extBCrd190",
"entityId": "icrd_3r2Jh1t0G4IXFvz5Q559cQ"
},
"message": "Reference already exists."
}
400 (HTTP response status code) -- Reason Code is Invalid for Given Permissions
In this example, a request was made to reissue the card with a reason code that is not supported by the cardProgramId.
{
"requestId": "e0a1e950053f11ee841656da8a864888",
"code": "extIbis",
"subCode": "57",
"context": {
"transId": "F10332124",
"fee": 0
},
"message": "Reissue Damaged Card Decline (Reissue Damaged Card Service is Not Allowed)"
}
400 (HTTP response status code) -- Card is Closed
In this example, a request was made to reissue the card that has been closed.
{
"requestId": "19f07960054011ee841656da8a864888",
"code": "extIbis",
"subCode": "SD",
"context": {
"transId": "F10332128",
"fee": 0
},
"message": "Update Profile (OFAC/AVS) Decline (Closed Card)"
}
List Customer Cards
Request method and URL
POST /ibis/card/list
Description
Use this endpoint to list all cards belonging to the specified customer that were issued through /ibis endpoints.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| customerId | Customer ID in connectFi | string | "cstap_1Vu13vFOsYLXR2Tsvm68jW" |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples
Using cFiCardId:
Possible responses
200 (HTTP response status code) -- Card list was returned
{
"code": "0", //Success
"data": [
{
"cFiCardId": "icrd_5lFBjJG6pPlapyodSxZ97a", //card ID in connectFi
"cFiStatus": "Complete", //current status of card in connectFi
"customerId": "cstap_1Vu13vFOsYLXR2Tsvm68jW", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "324333260", //external reference in your system
"memberNumber": "cstcp_bAceHsbtuPoKTuP3I6zZS", //cFiCommonCustomerId in connectFi
"cardProgramId": "Evolve_Test", //card program ID
"programType": "credit",
"boReferenceId": "123456789012", //reference ID in the back office
"boCustomerId": "333000000001234567", //customer ID in the back office
"vAccountNumber": "1234567890123456",
"abaRoutingNumber": "121182810",
"dtsCreatedAt": "2023-05-02T15:12:00.185Z"
},
{
"cFiCardId": "icrd_4cFaZs9DMGC38tT7z3XPok", //card ID in connectFi
"cFiStatus": "Complete", //current status of card in connectFi
"customerId": "cstap_1Vu13vFOsYLXR2Tsvm68jW", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "extReI125", //external reference in your system
"memberNumber": "cstcp_bAceHsbtuPoKTuP3I6zZS", //cFiCommonCustomerId in connectFi
"cardProgramId": "Evolve_Test", //card program ID
"programType": "credit",
"boReferenceId": "123456789012", //reference ID in the back office
"boCustomerId": "333000000001234567", //customer ID in the back office
"vAccountNumber": "1234567890123456",
"abaRoutingNumber": "121182810",
"dtsCreatedAt": "2023-06-07T12:33:43.428Z"
},
{
"cFiCardId": "icrd_7trq6iTobscnAAlb0unuvC", //card ID in connectFi
"cFiStatus": "Error", //current status of card in connectFi
"error": {
"code": "12",
"message": "New Card Purchase Decline (Allocated credit limit must be less than or equal to [2000.0]; )"
},
"customerId": "cstap_1Vu13vFOsYLXR2Tsvm68jW", //customer ID in connectFi
"cFiAggregatorId": "evolve",
"reference": "324333261", //external reference in your system
"memberNumber": "cstcp_bAceHsbtuPoKTuP3I6zZS", //cFiCommonCustomerId in connectFi
"cardProgramId": "Evolve_Test", //card program ID
"programType": "credit",
"dtsCreatedAt": "2023-05-02T15:35:25.822Z"
},
],
"requestId": "db2dd8f0053311ee841656da8a864888"
}
200 (HTTP response status code) -- No Cards Found for the Specified Customer
In this example, the specified customer does not have any cards issued through /ibis endpoints.
{
"code": "0", //Success
"data": [], //no cards found
"requestId": "b4fa74f0054111ee841656da8a864888"
}
Card to Card Transactions with /ibis
Request method and URL
POST /ibis/financial/card-to-card
Description
This endpoint will transfer funds from one card to another card.
Note that funds cannot be pulled from a debit card unless the card status code is "B" (ON) and funds are available. You can, however, transfer funds to a pre-active card (issued but not yet activated). Also, when pulling funds from a credit card, the requested transfer will be declined if it causes the credit card to go over the available credit limit.
The /ibis/financial/card-to-card endpoint supports idempotency and will not accept requests with duplicate reference IDs. The external reference ID included in the request body is how connectFi controls for duplicate transaction requests. It is important to note that transaction 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.
{
"reference": "EXT_REFERENCE_ID1", //Different reference IDs
"cardFromId": "icrd_5lFBjJG6pPlapyodSxZ97a",
"cardToId": "icrd_71iRvTzeQckz3fNxQ2DVqM",
"description": "Both of these transactions will post.",
"amount": 50,
"currency": "USD"
}
{
"reference": "EXT_REFERENCE_ID2", //Different reference IDs
"cardFromId": "icrd_5lFBjJG6pPlapyodSxZ97a",
"cardToId": "icrd_71iRvTzeQckz3fNxQ2DVqM",
"description": "Both of these transactions will post.",
"amount": 50,
"currency": "USD"
}
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| reference | An external alphanumeric reference ID (1-32 characters) for the transaction in your system | string | "ExtDFunds123" |
| cardFromId | The card ID in connectFi of the card to pull funds from | string | "icrd_3ZBErpQcsauarnR0Qj97Lu" |
| cardToId | The card ID in connectFi of the card to push funds to | string | "icrd_7sF5HbXzSEb45QLFyc7GMQ" |
| amount | The amount to be transferred | number, >=0 | 11 |
| currency | A three character ISO alphabetic code to identify the currency | String, regex pattern: "^[A-Z]{3}$" | "USD" |
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| description | An optional description of the transaction | string | "Transfer to other card" |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example
{
"reference": "ExtC2CFunds123", //external reference in your system
"cardFromId": "icrd_3ZBErpQcsauarnR0Qj97Lu", //card ID in connectFi of the card to pull funds from
"cardToId": "icrd_7sF5HbXzSEb45QLFyc7GMQ", //card ID in connectFi of the card to push funds to
"description": "Transfer to other card", //description of transaction
"amount": 11, //amount to be transferred
"currency": "USD" //currency code (represented by 3 characters)
}
Possible responses
200 (HTTP response status code) -- Specified funds amount was transferred
{
"code": "0", //Success
"data": {
"reference": "ExtC2CFunds123", //external reference in your system
"cFiFundsId": "ifnd_H9WdNOizlRynTIxoH6l1O", //funds transfer ID in connectFi
"cFiAggregatorId": "evolve",
"type": "cardToCard", //type of transaction
"cardFromId": "icrd_3ZBErpQcsauarnR0Qj97Lu", //card ID in connectFi of the card to pull funds from
"cardToId": "icrd_7sF5HbXzSEb45QLFyc7GMQ", //card ID in connectFi of the card to push funds to
"cFiStatus": "Complete", //current status of transaction in connectFi - "Initiated", "Complete", or "Error"
"boTransId": "F2156032006", //transaction ID in the back office
"arn": "0000000000000006LAzr",
"fee": 0,
"balance": 33, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 33, //ledger balance
"dtsCreatedAt": "2023-03-16T18:55:15.973Z",
"fromCardBalance": "33.00",
"toCardBalance": "11.00"
},
"requestId": "16de35a0c42c11ed9e40c5641e001f9c"
}
400 (HTTP response status code) -- Shortfall Currency Exchange Decline (From Card) (Pre-Active Card)
Cannot use an inactive card to pull funds from. The cardFromId should reference a card with a status of "B" (ON).
{
"requestId": "bb6bf3e0c42d11ed9e40c5641e001f9c",
"code": "extIbis",
"subCode": "PA",
"context": {
"transId": "F2156032937",
"arn": "0000000000000006LAzt",
"fee": 0
},
"message": "Shortfall Currency Exchange Decline (From Card) (Pre-Active Card)"
}
400 (HTTP response status code) -- Funds Transfer Decline (From Card)
In the following example, the requested transfer would have caused the "from" card to exceed the available credit limit. In this case, the "from" card, or source of the funds, was a credit card.
{
"requestId": "27c68a10e90311edab7956da8a863158",
"code": "extIbis",
"subCode": "51",
"context": {
"fromCardBalance": "-2.00",
"transId": "F10287474",
"arn": "0000000000000006LAAa",
"fee": 0
},
"message": "Funds Transfer Decline (From Card) (Insufficient Funds [498.0])"
}
400 (HTTP response status code) -- Reference already exists
In this request, the reference ID has already been used. Reference IDs cannot be reused.
{
"requestId": "1ce64ce0733511ee94f256da8a860d80",
"code": "referenceExists",
"context": {
"reference": "ExtC2CFunds145",
"entityId": "ifnd_6CcKJdrj3mwx8c40ZUJNwU"
},
"message": "Reference already exists."
}
Push Funds to Card with /ibis
Request method and URL
POST /ibis/financial/funds-credit
Description
This endpoint will credit (add) funds to the specified card.
The /ibis/financial/funds-credit endpoint supports idempotency and will not accept requests with duplicate reference IDs. The external reference ID included in the request body is how connectFi controls for duplicate transaction requests. It is important to note that transaction 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.
{
"reference": "EXT_REFERENCE_ID1", //Different reference IDs
"cFiCardId": "icrd_4Iex5dfzlnJWTYal2K5YQI",
"description": "Both of these transactions will post.",
"amount": 24,
"currency": "USD"
}
{
"reference": "EXT_REFERENCE_ID2", //Different reference IDs
"cFiCardId": "icrd_4Iex5dfzlnJWTYal2K5YQI",
"description": "Both of these transactions will post.",
"amount": 24,
"currency": "USD"
}
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiCardId | The card ID in connectFi | string | "icrd_1oSrT1U8G73S5Jdt27YvYk" |
| reference | An external alphanumeric reference ID (1-32 characters) for the transaction in your system | string | "ExtCFunds123" |
| amount | The amount to be credited (added to) the available card balance | number, >=0 | 21 |
| currency | A three character ISO alphabetic code to identify the currency | String, regex pattern: "^[A-Z]{3}$" | "USD" |
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| description | An optional description of the transaction | string | "Topping up debit card" |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example
{
"reference": "ExtCFunds123", //external reference in your system
"cFiCardId": "icrd_3ZBErpQcsauarnR0Qj97Lu", //card ID in connectFi
"description": "Topping up debit card", //description of the transaction
"amount": 21, //amount to be credited (added to) card
"currency": "USD" //currency code (represented by 3 characters)
}
Possible responses
200 (HTTP response status code) -- Card was credited with specified funds amount
{
"code": "0", //Success
"data": {
"reference": "ExtCFunds123", //external reference in your system
"cFiFundsId": "ifnd_5YVmYv3PAdUafhyEBi1kQA", //funds transfer ID in connectFi
"cFiAggregatorId": "evolve",
"type": "credit", //type of transaction, "credit" = push to card, "debit" = pull from card
"cFiCardId": "icrd_3ZBErpQcsauarnR0Qj97Lu", //card ID in connectFi
"cFiStatus": "Complete", //current status of transaction in connectFi - "Initiated", "Complete", or "Error"
"boTransId": "F2156028290", //transaction ID in the back office
"arn": "0000000000000006LAzl",
"fee": 0,
"balance": 21, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 21, //ledger balance
"dtsCreatedAt": "2023-03-16T17:48:32.425Z",
"outstandingSettlementBalance": 0
},
"requestId": "c48e5db0c42211ed9e40c5641e001f9c"
}
400 (HTTP response status code) -- Currency CND is not support
In this request, a currently other than USD was used. Currently, only "USD" currency is supported.
{
"requestId": "0a5a6ba0c42711ed9e40c5641e001f9c",
"code": "ibisFundsCurrency",
"message": "Currency CND is not support"
}
400 (HTTP response status code) -- Amount must be > 0
In this request, an amount less than or equal to 0 was requested. The amount property has an exclusive minimum of 0.
{
"requestId": "47714e50c42711ed9e40c5641e001f9c",
"code": "requestValidateError",
"context": [
{
"instancePath": "/amount",
"schemaPath": "common#/definitions/amount/exclusiveMinimum",
"keyword": "exclusiveMinimum",
"params": {
"comparison": ">",
"limit": 0
},
"message": "must be > 0"
},
{
"instancePath": "",
"schemaPath": "#/$merge",
"keyword": "$merge",
"params": {},
"message": "must pass \"$merge\" keyword validation"
}
]
}
400 (HTTP response status code) -- Reference already exists
In this request, the reference ID has already been used. Reference IDs cannot be reused.
{
"requestId": "5cbde0c0733611ee94f256da8a860d80",
"code": "referenceExists",
"context": {
"reference": "ExtCFunds143",
"entityId": "ifnd_1JtrIpQ3S1D6bsksiwmddO"
},
"message": "Reference already exists."
}
Pull Funds from Card with /ibis
Request method and URL
POST /ibis/financial/funds-debit
Description
This endpoint will debit (pull) funds from the specified card.
Note that funds cannot be pulled from a debit card unless the card status code is "B" (ON) and funds are available. Also, when pulling funds from a credit card, the requested transfer will be declined if it causes the credit card to go over the available credit limit.
The /ibis/financial/funds-debit endpoint supports idempotency and will not accept requests with duplicate reference IDs. The external reference ID included in the request body is how connectFi controls for duplicate transaction requests. It is important to note that transaction 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.
{
"reference": "EXT_REFERENCE_ID1", //Different reference IDs
"cFiCardId": "icrd_4Iex5dfzlnJWTYal2K5YQI",
"description": "Both of these transactions will post.",
"amount": 24,
"currency": "USD"
}
{
"reference": "EXT_REFERENCE_ID2", //Different reference IDs
"cFiCardId": "icrd_4Iex5dfzlnJWTYal2K5YQI",
"description": "Both of these transactions will post.",
"amount": 24,
"currency": "USD"
}
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiCardId | The card ID in connectFi | string | "icrd_1oSrT1U8G73S5Jdt27YvYk" |
| reference | An external alphanumeric reference ID (1-32 characters) for the transaction in your system | string | "ExtDFunds123" |
| amount | The amount to be debited (pulled from) the available card balance (for debit cards) or available credit limit (for credit cards) | number, >=0 | 15 |
| currency | A three character ISO alphabetic code to identify the currency | String, regex pattern: "^[A-Z]{3}$" | "USD" |
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| description | An optional description of the transaction | string | "Paying bill" |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example
{
"reference": "ExtDFunds123", //external reference in your system
"cFiCardId": "icrd_3ZBErpQcsauarnR0Qj97Lu", //card ID in connectFi
"description": "Paying bill", //description of the transaction
"amount": 15, //amount to be credited (added to) card
"currency": "USD" //currency code (represented by 3 characters)
}
Possible responses
200 (HTTP response status code) -- Specified funds amount was pulled from the card
{
"code": "0", //Success
"data": {
"reference": "ExtDFunds123", //external reference in your system
"cFiFundsId": "ifnd_4CGWObikeWrC1m99oZdCjG", //funds transfer ID in connectFi
"cFiAggregatorId": "evolve",
"type": "debit", //type of transaction, "credit" = push to card, "debit" = pull from card
"cFiCardId": "icrd_3ZBErpQcsauarnR0Qj97Lu", //card ID in connectFi
"cFiStatus": "Complete", //current status of transaction in connectFi - "Initiated", "Complete", or "Error"
"boTransId": "F2156031298", //transaction ID in the back office
"arn": "0000000000000006LAzo",
"fee": 0,
"balance": 20, //balance available on card (previous balance was 35)
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 20, //ledger balance (previous ledger balance was 35)
"dtsCreatedAt": "2023-03-16T18:44:33.504Z",
"cardPrgName": "GPR Card Program"
},
"requestId": "97edfba0c42a11ed9e40c5641e001f9c"
}
400 (HTTP response status code) -- Cash Withdrawal Decline (Pre-Active Card)
In this request, a request was made to pull funds from a debit card that is not yet active.
{
"requestId": "95194d40c42911ed9e40c5641e001f9c",
"code": "extIbis",
"subCode": "PA",
"context": {
"status": {
"code": "A",
"description": "Card was issued but has not yet been activated"
},
"cardPrgName": "GPR Card Program",
"transId": "F2156030835",
"arn": "0000000000000006LAzn",
"fee": 0
},
"message": "Cash Withdrawal Decline (Pre-Active Card)"
}
400 (HTTP response status code) -- Insufficient Funds
In this request, the a request was made to debit a credit card for an amount that would cause the credit card to exceed its available credit limit.
{
"requestId": "9b299cd0e90411edab7956da8a863158",
"code": "extIbis",
"subCode": "51",
"context": {
"status": {
"code": "B",
"description": "Open - All Transactions Allowed"
},
"cardPrgName": "Evolve_Test_Updated",
"transId": "F10287476",
"arn": "0000000000000006LAAb",
"fee": 0,
"balance": -2, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"ledgerBalance": -2 //ledger balance
},
"message": "Manual Sig Based Cash Withdrawal Intl (with currency conversion) Decline (Insufficient Funds [498.0])"
}
400 (HTTP response status code) -- Reference already exists
In this request, the reference ID has already been used. Reference IDs cannot be reused.
{
"requestId": "8990a3d0733611ee94f256da8a860d80",
"code": "referenceExists",
"context": {
"reference": "ExtDFunds143",
"entityId": "ifnd_3jGWcWt8UGrPKF41xaZEle"
},
"message": "Reference already exists."
}
Reverse a Transaction with /ibis
Request method and URL
POST /ibis/financial/reversal
Description
This endpoint will reverse an existing eligible transaction. Currently, reversals are not supported for /ibis/financial/funds-credit or /ibis/financial/funds-debit transactions. Reversals are available for /ibis/financial/card-to-card transactions in which both cards belong to the same cardProgramId.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiFundsId | The funds transfer ID in connectFi | string | "ifnd_4CGWObikeWrC1m99oZdCjG" |
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| amount | The amount of the reversal, nullable | number | 11 |
| description | An optional description of the reversal, nullable | string | "Transaction reversal" |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example
Possible responses
200 (HTTP response status code) -- Transaction was reversed
{
"code": "0", //Success
"data": {
"reference": "ExtC2CFunds125", //external reference in your system
"cFiFundsId": "ifnd_5UIXacW0Wk3u1dtsn8zUaM",
"cFiAggregatorId": "evolve",
"type": "cardToCard", //type of transaction
"cardFromId": "icrd_7sF5HbXzSEb45QLFyc7GMQ", //card ID in connectFi of the card to pull funds from
"cardToId": "icrd_3ZBErpQcsauarnR0Qj97Lu", //card ID in connectFi of the card to push funds to
"cFiStatus": "Complete", //current status of transaction in connectFi - "Initiated", "Complete", or "Error"
"boTransId": "F2156034072", //transaction ID in the back office
"arn": "0000000000000006LAzu",
"fee": 0,
"balance": 32, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 0, //ledger balance
"dtsCreatedAt": "2023-03-16T19:21:32.145Z",
"reversal": {
"cFiStatus": "Complete", //current status of reversal in connectFi - "Initiated", "Complete", or "Error"
"dtsReversalInitiated": "2023-03-16T19:21:59.289Z",
"arn": "0000000000000006LAzv",
"responseDesc": "Shortfall Currency Exchange - Reversal",
"boTransId": "F2156034109" //transaction ID in the back office
}
},
"requestId": "d285e250c42f11ed9e40c5641e001f9c"
}
400 (HTTP response status code) -- Can only reverse card to card transactions
In this example, an attempt was made to reverse a debit (pull from card) transaction without having access to the destination account or card from the original transaction. Currently, reversals are not supported for /ibis/financial/funds-credit or /ibis/financial/funds-debit transactions. Reversals are available for /ibis/financial/card-to-card transactions.
{
"requestId": "d0d1e970733611ee94f256da8a860d80",
"code": "ibisCannotReverseError",
"context": {
"fundsContext": {
"entityId": "ifnd_4AMYgtpc9kgAk5Ku21q3JG",
"entityStatus": "Complete",
"reference": "ExtDFunds144",
"aggregatorId": "evolve",
"cFiReference": "0000000000000006LAIR",
"externalId": "F12586624"
}
},
"message": "Can only reverse card to card transactions."
}
Retrieve a Transaction with /ibis
Request method and URL
POST /ibis/financial/retrieve
Description
This endpoint will retrieve the details of an existing transaction. You may use one of the following IDs to retrieve a transaction: cFiFundsId, reference, or arn. If you include more than one of these ID types in a single request, an error will be thrown.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiFundsId | The funds transfer ID in connectFi | string | "ifnd_4CGWObikeWrC1m99oZdCjG" |
OR
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| reference | An external alphanumeric reference ID (1-32 characters) for the transaction in your system | string | "ExtDFunds123" |
OR
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| arn | An arn ID that was returned with the initial transaction response | string | "0000000000000006LAzw" |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples
Using cFiFundsId:
Using reference:
Using arn:
Possible responses
200 (HTTP response status code) -- Transaction details were retrieved
{
"code": "0", //Success
"data": [
{
"reference": "ExtCFunds126", //external reference in your system
"cFiFundsId": "ifnd_18Zh3Ubna3ZNIMgz0EZlAw", //funds transfer ID in connectFi
"cFiAggregatorId": "evolve",
"type": "credit", //type of transaction, "credit" = push to card, "debit" = pull from card
"cFiCardId": "icrd_3ZBErpQcsauarnR0Qj97Lu", //card ID in connectFi
"cFiStatus": "Complete", //current status of transaction in connectFi - "Initiated", "Complete", or "Error"
"boTransId": "F2156034276", //transaction ID in the back office
"arn": "0000000000000006LAzw",
"fee": 0,
"balance": 56, //For debit cards, "balance" = available funds on card. For credit cards "balance" = available funds - credit limit. Current credit card "balance" may be positive (overpaid), negative (money owed), or 0 (paid in full). A credit card with a "balance" of -2 and a credit limit of 500 has available funds of 498.
"lastDepositAmount": 0, //most recent deposit (debit cards) or card payment (credit cards)
"ledgerBalance": 56, //ledger balance
"dtsCreatedAt": "2023-03-16T19:24:18.701Z"
}
],
"requestId": "9a838be0c43011ed9e40c5641e001f9c"
}
400 (HTTP response status code) -- Must match exactly one schema in oneOf, must NOT have additional properties
In this example, more than one type of ID was used to attempt a transaction retrieval in a single transaction.
{
"requestId": "15f378c0c43211ed9e40c5641e001f9c",
"code": "requestValidateError",
"context": [
{
"instancePath": "",
"schemaPath": "#/oneOf/0/additionalProperties",
"keyword": "additionalProperties",
"params": {
"additionalProperty": "arn"
},
"message": "must NOT have additional properties"
},
{
"instancePath": "",
"schemaPath": "#/oneOf/1/required",
"keyword": "required",
"params": {
"missingProperty": "reference"
},
"message": "must have required property 'reference'"
},
{
"instancePath": "",
"schemaPath": "#/oneOf/2/additionalProperties",
"keyword": "additionalProperties",
"params": {
"additionalProperty": "cFiFundsId"
},
"message": "must NOT have additional properties"
},
{
"instancePath": "",
"schemaPath": "#/oneOf",
"keyword": "oneOf",
"params": {
"passingSchemas": null
},
"message": "must match exactly one schema in oneOf"
}
]
}
400 (HTTP response status code) -- Funds transfer not found
{
"requestId": "30b11050733711ee94f256da8a860d80",
"code": "ibisFundsTransferNotFound",
"context": {
"fundsId": "cFiFundsId=ifnd_4AMYgtpc9kgAk5Ku21q3JGe "
},
"message": "Funds transfer not found."
}
Transaction History Inquiry with /ibis
Request method and URL
POST /ibis/inquiry/transaction-history
Description
This endpoint will retrieve the transaction history of a card issued through /ibis.
| Required Properties | Description | Schema | Example Values |
|---|---|---|---|
| cFiCardId | The card ID in connectFi | string | "icrd_1oSrT1U8G73S5Jdt27YvYk" |
| Optional Properties | Description | Schema | Example Values |
|---|---|---|---|
| dateFrom | The beginning of the requested transaction period in "YYYY-MM-DD" format | string, regex pattern "^\d{4}-\d{2}-\d{2}$" | "2023-03-01" |
| dateTo | The end of the requested transaction period in "YYYY-MM-DD" format | string, regex pattern "^\d{4}-\d{2}-\d{2}$" | "2023-03-16" |
| numberOfRecords | Represents the number of desired transactions to return, nullable | integer >= 1 | 15 |
| skipRecords | A number of transactions to skip, nullable | integer >=0 | 5 |
Request headers
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example
{
"cFiCardId": "icrd_71iRvTzeQckz3fNxQ2DVqM", //card ID in connectFi
"dateFrom" : "2023-03-01",
"dateTo" : "2023-05-02"
}
Possible responses
200 (HTTP response status code) -- The specified transaction history was returned
{
"code": "0", //Success
"data": {
"transactions": [
{
"transId": "F10287483",
"traceAuditNo": "10287483",
"originalTraceAuditNo": "10287482",
"accountNumber": "1234567890123456",
"transTypeId": "40",
"businessDate": "05/02/2023",
"acceptorNameAndLocation": "USA",
"availableBalance": "520.50",
"amount": "-50.00",
"description": "Funds Transfer",
"messageTypeIdentifier": "0400",
"billed": "N",
"arn": "0000000000000006LAAf",
"mcc": "0",
"deviceType": "H",
"transDate": "2023-05-02T09:21:00",
"remainingBalance": "520.50",
"panSequenceNo": "00",
"localDateTime": "2023-05-02 09:21:00",
"serviceId": "C2C_FUNDS_TRSFR",
"isRecurring": "N",
"is3DSecure": "N",
"isDigitalWalletTrans": "N",
"isPaymentTrans": "I"
},
{
"transId": "F10287482",
"traceAuditNo": "10287482",
"accountNumber": "1234567890123456",
"transTypeId": "40",
"businessDate": "05/02/2023",
"acceptorNameAndLocation": "USA",
"availableBalance": "570.50",
"amount": "50.00",
"description": "Funds Transfer",
"messageTypeIdentifier": "0200",
"billed": "N",
"arn": "0000000000000006LAAf",
"mcc": "0",
"deviceType": "H",
"transDate": "2023-05-02T09:20:45",
"remainingBalance": "570.50",
"panSequenceNo": "00",
"authorizationCode": "287481",
"localDateTime": "2023-05-02 09:20:44",
"serviceId": "C2C_FUNDS_TRSFR",
"isRecurring": "N",
"is3DSecure": "N",
"isDigitalWalletTrans": "N",
"isPaymentTrans": "I"
},
{
"transId": "F10287478",
"traceAuditNo": "10287478",
"accountNumber": "1234567890123456",
"transTypeId": "21",
"businessDate": "05/02/2023",
"acceptorNameAndLocation": "USA",
"availableBalance": "520.50",
"amount": "24.00",
"description": "test trn 11 from Network PaygearsCorporation",
"messageTypeIdentifier": "0200",
"billed": "N",
"arn": "0000000000000006LAAd",
"mcc": "0",
"deviceType": "H",
"transDate": "2023-05-02T09:19:31",
"remainingBalance": "520.50",
"panSequenceNo": "00",
"authorizationCode": "287478",
"localDateTime": "2023-05-02 09:19:31",
"serviceId": "SW_DEPOSIT",
"isRecurring": "N",
"is3DSecure": "N",
"isDigitalWalletTrans": "N",
"isPaymentTrans": "I"
},
{
"transId": "F10287477",
"traceAuditNo": "10287477",
"accountNumber": "1234567890123456",
"transTypeId": "01",
"businessDate": "05/02/2023",
"acceptorNameAndLocation": "USA",
"availableBalance": "496.50",
"amount": "-1.50",
"description": "Paying bill",
"messageTypeIdentifier": "0200",
"billed": "N",
"arn": "0000000000000006LAAc",
"mcc": "0",
"deviceType": "H",
"transDate": "2023-05-02T09:17:31",
"remainingBalance": "496.50",
"panSequenceNo": "00",
"authorizationCode": "287477",
"localDateTime": "2023-05-02 09:17:30",
"serviceId": "MNL_CSH_SIG_INT_M",
"isRecurring": "N",
"is3DSecure": "N",
"isDigitalWalletTrans": "N",
"isPaymentTrans": "N"
},
// rest of the transactions
]
},
"requestId": "836cd750e90511edab7956da8a863158"
}
400 (HTTP response status code) -- Get Transaction History Decline (Get Transaction History Service is Not Allowed)
Transaction history retrieval is not allowed for the specified card.
{
"requestId": "d4578db0c43211ed9e40c5641e001f9c",
"code": "extIbis",
"subCode": "57",
"context": {
"transId": "F2156035711",
"fee": 0
},
"message": "Get Transaction History Decline (Get Transaction History Service is Not Allowed)"
}
400 (HTTP response status code) -- Get Transaction History Decline (FromDate is greater than ToDate in request)
The specified from date cannot be after the to date.