Debit Cards Using /condor
The /condor endpoint is used to manage debit cards and corresponding checking accounts associated with existing connectFi customers.
Endpoint | Action |
---|---|
/condor/customer/create | Create a debit card and corresponding checking account |
/condor/customer/update | Update customer details |
/condor/customer/get/:customerId | Get customer details |
/condor/card/add | Add secondary debit card and corresponding checking account |
/condor/card/activate | Activate a debit card |
/condor/card/set-pin | Set debit card PIN |
/condor/card/change-status | Change status of debit card |
/condor/card/re-issue | Reissue a debit card |
/condor/card/balance/:cardId | Get a debit card's available balance |
/condor/card/get/:cardId | Get details of a specified debit card |
Financial Credits and Debits Overview | Overview of financial credits and debits, along with request body property descriptions that are common to both |
/condor/financial/credit | Load funds onto (credit) a debit card |
/condor/financial/debit | Subtract funds from (debit) a debit card |
/condor/financial/p2p | Transfer funds from one debit card account (source) to another debit card account (beneficiary) |
/condor/transaction/history | Retrieve specified transaction history |
/condor/transaction/reversal | Reverse a previously completed transaction |
Common /condor Error Responses | Descriptions of possible error responses that are common to most /condor endpoints |
Create a Debit Card and Checking Account with /condor
Description:
This endpoint initializes a debit card and a checking account for an existing connectFi customer who has completed the KYC (Know Your Customer) or KYB (Know Your Business) approval process. The KYC/KYB status of the connectFi customer must be marked as "APPROVED" before this request can successfully be completed. This request can only be made one time per customer. Multiple requests using the same connectFi customer ID will result in an error indicating that the specified debit card customer already exists in the connectFi system. Note that requests to this endpoint for "APPROVED" connectFi customers do not alter the customerId, but it will:
- Create a checking account for the connectFi customer, example account ID: "acca_dR4cAgLuv0naFhswOcZcI"
- Issue a debit card associated with the new account for the connectFi customer, example debit card ID: "crda_5k11BrCFFq5BQX5VV2AnSU"
- Enable the use of other /condor endpoint requests (/condor/customer/create is a prerequisite request for all other /condor endpoints).
Required Properties | Description | Schema | Example Values |
---|---|---|---|
customerId | Customer ID in connectFi | String | "csta_6clNH3W2pBehujY8mpTCU8" |
Optional Properties | Description | Schema | Example Values |
---|---|---|---|
cardAttributes | Attributes of the card that will be assigned to the customer | Object | See cardAttributes Object below |
cardAttributes Object
Required Properties | Description | Schema | Example Values |
---|---|---|---|
productID | Product ID of card which will specify what type of debit card is being issued (this could be a physical debit card or a virtual debit card.) The productID (also referred to as program_id) will be specific to your products that are offered through this endpoint. | String | "Virtual_Debit_Card" |
nameOnCard | Full customer name that will appear on the card | String | "JESSIE U TESTMAN" |
designId | An ID representing the design chosen for the card | String | "1" |
addressType | Type of address | String | "PRIMARY" or "SECONDARY" |
issueType | Description identifying issue category of card | String | "NEW", "REGISTRATION", "RE-ISSUE", "EXPIRED", or "DAMAGED" |
Optional Properties | Description | Schema | Example Values |
---|---|---|---|
reference | An external alphanumeric reference ID (1-20 characters) for the card in your system | String, regex pattern "^[0-9a-zA-Z]+$" | "externalCrdId1234" |
cardShippingMethod | Shipping method chosen for card | String | "Standard" |
additionalData | An object containing any necessary additional key:value pair properties not listed elsewhere | Object | {"someProperty" : "Property value"} |
Request method and URL:
POST /condor/customer/create
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" : "csta_MlNTVaPPqdvvl1swwSGbC", //customer ID in connectFi
"cardAttributes" : { //optional object specifying desired card attributes
"productID" : "Virtual_Debit_Card",
"nameOnCard" : "JESSIE U TESTMAN",
"designId" : "1",
"addressType": "PRIMARY",
"issueType" : "NEW", //default "NEW"
"reference" : "externalCrdId1234",
"cardShippingMethod" : "Standard",
"additionalData" : {
"someProperty" : "Property value"
}
}
}
Possible responses:
200 (HTTP response status code) -- Debit card was created, along with a corresponding checking account
{
"code": "0", //Success
"data": {
"reference": "222236133", //unique external reference in your system
"customerId": "csta_6clNH3W2pBehujY8mpTCU8", //customer ID in connectFi
"customerType": "individual", //or "business"
"customer": { //customer object: firstName, lastName, gender, dateOfBirth, email, addresses, phones, identificationDocuments, etc.
"firstName": "Jessie",
"lastName": "Testman",
"gender": "M",
"dateOfBirth": "1978-10-15",
"email": "aa@aa.ae",
"addresses": [
{
"type": "PRIMARY",
"addressLine1": "123 Some Str.",
"city": "Mycityname",
"countryCodeA3": "USA",
"postalCode": "#####", //a postal code, ##### is used as a placeholder here for documentation purposes
"stateCode": "PA"
}
],
"phones": [
{
"type": "MOBILE",
"phoneNumber": "##########", //a phone number, "##########", is used as a placeholder here for documentation purposes
"countryDialingCode": "01"
}
],
"identificationDocuments": [
{
"type": "SSN",
"value": "#########", //a 9 digit Social Security Number, ######### is used as a placeholder here for documentation purposes
"issuanceCountryCodeA3": "USA"
},
{
"type": "DRIVING LICENSE",
"value": "#########", //a Driver's License Number, ######### is used as a placeholder here for documentation purposes
"issuanceCountryCodeA3": "USA",
"issuanceRegion": "Pennsylvania",
"expiryDate": "2023-04-08"
}
]
},
"kycStatus": "APPROVED", //KYC/KYB status must be "APPROVED" to make a /condor/customer/create request
"boises": [
"condor"
],
"dtsCreatedAt": "2022-10-25T15:50:48.841Z",
"cards": [ //all cards of the customer
{
"id": "crda_5k11BrCFFq5BQX5VV2AnSU", //card ID in connectFi
"cFiBoisId": "condor", //backend system which keeps the account
"customerId": "csta_6clNH3W2pBehujY8mpTCU8", //customer ID in connectFi
"cFiAccountIds": [
"acca_dR4cAgLuv0naFhswOcZcI" //customer account ID
]
}
],
"accounts": [ //all accounts of the customer
{
"id": "acca_dR4cAgLuv0naFhswOcZcI", //customer account ID
"cFiBoisId": "condor", //backend system which keeps the account
"accountNumber": "##############", //customer checking account number, ############## is used as a placeholder for documentation purposes
"customerId": "csta_13ne82vRMHkf3vBuq9zWj6", //customer ID in connectFi
"cFiCardIds": [ //list of ids of cards linked to the account
"crda_24JI1uyHYLr73dr7OsU4ta" //card ID in connectFi
],
"routingParams": { //additional account parameters
"routingNumber": "#########" //a US ABA account routing number, ######### is used as a placeholder here for documentation purposes
}
}
]
}
}
US accounts get routingParams.routingNumber
attribute. Accounts opened in other jurisdictions may have other attributes.
400 (HTTP response status code) -- Customer already exists
In this example, a duplicate request was made for a connectFi customer that already has an account and debit card initialized through the /condor/customer/create
endpoint.
In this example, an existing connectFi customerId was used, but the KYC/KYB status for this customer has not yet been "APPROVED". The customer KYC/KYB status must be "APPROVED" before opening a debit card account. Check customer KYC/KYB status by making a GET /customer/kyc/status/:customerId
request. If KYC/KYB status is "PENDING", no action is required on your part and you should wait for the status to update to "APPROVED" before re-attempting the /condor/customer/create
request. If the KYC/KYB status is "WAITING-DATA", then additional attributes or document images are expected and action is required before re-attempting the /condor/customer/create
request. See KYC status.
{
"code": "badKYCStatus", //or badKYBStatus
"message": "For create customer KYC status must have APPROVED" //or KYB status
}
Update a Customer
Description:
This endpoint is used to update or add customer information. The "customerId" property is required for a successful response. Optional properties include "firstName", "lastName", "gender", "dateOfBirth", "email", the "addresses" array, and the "phones" array. Use cases may include instances where a customer needs to change their name, add a new phone number, update their email address, etc.
Including any properties other than those listed will result in an error. Note that you may NOT use this endpoint to update or add identification document information.
Required Properties | Description | Schema | Example Values |
---|---|---|---|
customerId | Customer ID in connectFi | String | "csta_6clNH3W2pBehujY8mpTCU8" |
Optional Properties | Description | Schema | Example Values |
---|---|---|---|
firstName | First name of customer | String | "Jessie" |
lastName | Last name of customer | String | "Testman" |
gender | Customer's gender ("M" or "F") | String | "M" or "F" |
dateOfBirth | Customer's date of birth in YYYY-MM-DD format | String, regex pattern "^\d{4}-\d{2}-\d{2}$" | "1978-10-25" |
Customer's email address | String, regex pattern "^(.+)@(.+)$" | "bb@bb.be" | |
addresses | Array of objects representing customer's addresses | Array | [{//address1}, {//address2}, {//etc.}] , See Address Object below |
phones | Array of objects representing customer's phone numbers | Array | [{//phone1}, {//phone2}, {//etc.}] , See Phone Object below |
Address Object
Properties | Description | Schema | Example Values |
---|---|---|---|
type | Type of address (required) | String | "PRIMARY" or "SECONDARY" |
addressLine1 | Customer's address line 1 (required) | String | "123 Some Str." |
addressLine2 | Customer's address line 2 (optional) | String | "Apt A123" |
city | Customer's city (required) | String | "Mycityname" |
state | Customer's state (required) | String | "PA" |
postalCode | Customer's postal code (required), each # in the example should be replaced with a digit 0-9 | String | "#####" |
countryCodeA3 | Customer's country (required) | String | "USA" |
Phone Object
Properties | Description | Schema | Example Values |
---|---|---|---|
type | Type of phone number (required) | String | "MOBILE" or "LANDLINE" |
phoneNumber | Customer's 6 to 12 digit phone number (required), each # in the example should be replaced with a digit 0-9 | String | "##########" |
countryDialingCode | Customer's 1 to 4 digit country dialing code (optional) | String | "01" |
Request method and URL:
POST /condor/customer/update
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" : "csta_6clNH3W2pBehujY8mpTCU8", //customer ID in connectFi
"firstName" : "Jessie", //Optional property - will be updated if different from existing property value. Otherwise, existing value will remain the same.
"lastName" : "Testman", //Optional property - will be updated if different from existing property value. Otherwise, existing value will remain the same.
"gender" : "M", //Optional property - will be updated if different from existing property value. Otherwise, existing value will remain the same.
"dateOfBirth" : "1978-10-25", //Optional property - will be updated if different from existing property value. Otherwise, existing value will remain the same. YYYY-MM-DD format
"email" : "bb@bb.be", //Optional property - will be updated if different from existing property value. Otherwise, existing value will remain the same.
"addresses" : [ //Optional property - will be updated if different from existing property value. Otherwise, existing value will remain the same. Note that multiple addresses of the same "type" are not allowed and will result in an error.
{
"type": "PRIMARY",
"addressLine1": "123 Some Str.",
"city": "Mycityname",
"countryCodeA3": "USA",
"postalCode": "#####", //a postal code, ##### is used as a placeholder here for documentation purposes
"stateCode": "PA"
},
{
"type": "SECONDARY",
"addressLine1": "124 Some Str.",
"city": "Mycityname",
"countryCodeA3": "USA",
"postalCode": "#####", //a postal code, ##### is used as a placeholder here for documentation purposes
"stateCode": "PA"
}
],
"phones": [ //Optional property - will be updated if different from existing property value. Otherwise, existing value will remain the same. Note that multiple phone elements of the same "type" are not allowed and will result in an error.
{
"type": "MOBILE",
"phoneNumber": "##########", //a phone number, "##########", is used as a placeholder here for documentation purposes
"countryDialingCode": "01"
}
]
}
Possible responses:
200 (HTTP response status code) -- Success, information was updated and/or added
{
"code": "0", //Success
"data": {
"condorCustomer": {
"first_name": "Jessie",
"last_name": "Testman",
"gender": "M",
"email": "bb@bb.be",
"phone_details": [
{
"phone_type": "MOBILE", //May only have one of each phone type (you cannot have two phone numbers listed as type "MOBILE", etc.)
"country_dialing_code": 1,
"phone_number": "##########", //a phone number, "##########", is used as a placeholder here for documentation purposes
}
],
"date_of_birth": "1978-10-25",
"addresses": [
{
"address_type": "PRIMARY", //May only have one of each address type (you cannot have two addresses listed as type "PRIMARY", etc.)
"address1": "123 Some Str.",
"city": "Mycityname",
"region": "PA",
"postal_code": "#####", //a postal code, ##### is used as a placeholder here for documentation purposes
"country": "USA"
},
{
"address_type": "SECONDARY", //May only have one of each address type (you cannot have two addresses listed as type "SECONDARY", etc.)
"address1": "124 Some Str.",
"city": "Mycityname",
"region": "PA",
"postal_code": "#####", //a postal code, ##### is used as a placeholder here for documentation purposes
"country": "USA"
}
],
"identification_docs": [ //Existing identification documents will returned in the response, even though the /condor/customer/update endpoint will not allow you to update or add identification document information.
{
"identification_type": "DRIVING LICENSE",
"identification_value": "#########", //a Driver's License Number, ######### is used as a placeholder here for documentation purposes
"identification_issuance_country": "USA",
"identification_issuance_region": "Pennsylvania",
"identification_expiry_date": "2023-04-08"
},
{
"identification_type": "SSN",
"identification_value": "#########", //a 9 digit Social Security Number, ######### is used as a placeholder here for documentation purposes
"identification_issuance_country": "USA"
}
],
"customerId": "csta_6clNH3W2pBehujY8mpTCU8" //customer ID in connectFi
}
}
}
400 (HTTP response status code) -- Duplicate address/phone type found
In this example, a request to include two "PRIMARY" type addresses was made. You may only have one of a specific type of address or phone number. If the request body address array or phone array contains duplicate type values, an error will be returned.
{
"code": "extCondor",
"subCode": "C0900",
"context": {
"title": "cardholdersUpdate"
},
"message": "Duplicate address type found."
}
400 (HTTP response status code) -- Must have required property
While all properties other than "customerId" are optional, if you DO include a property such as "addresses", all required parts of that property must be present. In this example, a request was made to update the addresses array, but the new address was missing the required address property "stateCode".
{
"code": "requestValidateError",
"context": [
{
"instancePath": "/addresses/0",
"schemaPath": "#/definitions/address/required",
"keyword": "required",
"params": {
"missingProperty": "stateCode"
},
"message": "must have required property 'stateCode'"
}
]
}
400 (HTTP response status code) -- Must not have additional properties
The "customerId" property should be present when making this request. Optional properties include "firstName", "lastName", "gender", "dateOfBirth", "email", the "addresses" array, and the "phones" array. Any other property values present will result in an error. In this example, an additional property "cardAttributes" was included in the request.
Note: You may not use this endpoint to update or add identification document information.
{
"code": "requestValidateError",
"context": [
{
"instancePath": "",
"schemaPath": "#/additionalProperties",
"keyword": "additionalProperties",
"params": {
"additionalProperty": "cardAttributes"
},
"message": "must NOT have additional properties"
}
]
}
Get a Customer
Description:
This endpoint is used to retrieve an existing customer. The connectFi customerId should be included in the url as a path parameter.
Request method and URL:
GET /condor/customer/get/:customerId
Request headers:
{
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body: none
Possible responses:
200 (HTTP response status code) -- Success, customer is returned
{
"code": "0", //Success
"data": {
"condorCustomer": {
"first_name": "JESSIE",
"last_name": "TESTMAN",
"gender": "M",
"email": "aa@aa.ae",
"phone_details": [
{
"phone_type": "MOBILE",
"country_dialing_code": 1,
"phone_number": "##########", //a phone number, "##########", is used as a placeholder here for documentation purposes
}
],
"date_of_birth": "1978-10-15", //YYYY-MM-DD format
"addresses": [
{
"address_type": "PRIMARY",
"address1": "123 Some Str.",
"city": "Mycityname",
"region": "PA",
"postal_code": "#####", //a postal code, ##### is used as a placeholder here for documentation purposes
"country": "USA"
}
],
"identification_docs": [
{
"identification_type": "DRIVING LICENSE",
"identification_value": "#########", //a Driver's License Number, ######### is used as a placeholder here for documentation purposes
"identification_issuance_country": "USA",
"identification_issuance_region": "Pennsylvania",
"identification_expiry_date": "2023-04-08"
},
{
"identification_type": "SSN",
"identification_value": "#########", //a 9 digit Social Security Number, ######### is used as a placeholder here for documentation purposes
"identification_issuance_country": "USA"
}
],
"customerId": "csta_MlNTVaPPqdvvl1swwSGbC" //customer ID in connectFi
}
}
}
Add a Debit Card
Description
This request will add a secondary debit card and checking account to the customer specified in the request. Multiple debit cards/checking accounts can be added to a single customer.
Required properties in the request body are: "customerId" and the "cardAttributes" object. The "cardAttributes" object property must contain these properties: "productID", "nameOnCard", "designId", "addressType", and "issueType". An optional "additionalData" object property may also be present in the "cardAttributes" object.
Required Properties | Description | Schema | Example Values |
---|---|---|---|
customerId | Customer ID in connectFi | String | "csta_6clNH3W2pBehujY8mpTCU8" |
cardAttributes | Attributes of the card that will be assigned to the customer | Object | See cardAttributes Object in Create a Debit Card and Checking Account |
Request method and URL
POST /condor/card/add
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" : "csta_MlNTVaPPqdvvl1swwSGbC", //customer ID in connectFi
"cardAttributes": {
"productID": "Virtual_Debit_Card",
"nameOnCard": "JESSIE U TESTMAN 2",
"designId": "1",
"addressType": "PRIMARY",
"issueType": "NEW",
"additionalData": {
"designId": "1"
}
}
}
Possible responses:
200 (HTTP response status code) -- Success, new secondary debit card and checking account was added to connectFi customer
{
"code": "0", //Success
"data": {
"last_four": "####", //last 4 digits on the card, #### is used as a placeholder here for documentation purposes
"status": "NEW",
"program_id": "Virtual_Debit_Card",
"name_on_card": "JESSIE U TESTMAN 2",
"available_balance": 0, //money has not yet been loaded onto the card so available balance is 0
"currency_code": "USD",
"additional_data": {
"account_number": "##############", //customer checking account number corresponding to the new card, ############## is used as a placeholder for documentation purposes
"issue_date": "2022-10-25T18:08:32.985266Z", //date the card was issued
"design_id": "1",
"designId": "1",
"card_expiration": "102025", //card expiration date MMYYYY
"processor_token": "369029826861",
"routing_number": "#########" //a US ABA account routing number, ######### is used as a placeholder here for documentation purposes
"accountId": "acca_gV0FG6ZTxVvjxNMZDym2Q" //account ID in connectFi corresponding to the new card
},
"cardId": "crda_fO2N93TnJZvSmUgFFClUA" //card ID in connectFi
}
}
400 (HTTP response status code) -- Missing property in request
In the example below, the "productID" was not included in the "cardAttributes" object in the request body.
{
"code": "requestValidateError",
"context": [
{
"instancePath": "/cardAttributes",
"schemaPath": "#/required",
"keyword": "required",
"params": {
"missingProperty": "productID"
},
"message": "must have required property 'productID'"
}
]
}
Activate a Debit Card
Description:
This endpoint is used to activate a "NEW" debit card. Cards cannot be activated using this endpoint if they have status codes "BLOCK", "FRAUD_BLOCK", "CLOSED", or are already "ACTIVE". To change a card marked as "BLOCK" or "FRAUD_BLOCK" back to "ACTIVE", see Change Debit Card Status. You may choose to allow customer card activation using the cardId alone, or you may choose to include the activateAttributes object in order to validate the cardholder's identity and assure that the card is not being activated fraudulently. Any combination of activateAttributes key:value pairs that you choose to include will be checked against the card and customer information stored in connectFi. You choose which activation rules to include.
Required Properties | Description | Schema | Example Values |
---|---|---|---|
cardId | The card ID in connectFi | String | "crda_6v9nQ3AKKyD5bzvTVbnkN2" |
Optional Properties | Description | Schema | Example Values |
---|---|---|---|
activateAttributes | Attributes that can be used to verify the validity of the card activation and cardholder identity | Object | see *activateAttributes Object below |
activateAttributes Object
Optional Properties | Description | Schema | Example Values |
---|---|---|---|
cardLastFour | The last four digits on the card, each # in the example should be replaced with a digit 0-9 | String, regex pattern "^\d{4}$" | "####" |
cardExpDate | The expiration date on the card in MMYY-YY format (a card expiration value of "102025" will be entered here as "1020-25") | String, regex pattern "^\d{4}-\d{2}$" | "1020-25" |
ssnLastFour | The last four digits of the cardholder's Social Security Number, each # in the example should be replaced with a digit 0-9 | String, regex pattern "^\d{4}$" | "####" |
otherIdentificationType | The type of identification to check "otherIdentificationValue" against (must be the form of identification stored for the specified customer) | String | "SSN", "SIN", "NIN", "TIN", "PASSPORT", "DRIVING LICENSE", "CONSULAR", "VOTER", "MILITARY ID", or "GOVERNMENT ISSUED ID" |
otherIdentificationValue | The value (ID number) of the "otherIdentificationType" provided, each # in the example should be replaced with a digit 0-9 (the length of the value will be determined by the type of identification used) | String | "################" |
dateOfBirth | Date of birth of the cardholder | String, regex pattern "^\d{4}-\d{2}-\d{2}$" | "1978-10-15" |
routingNo | Routing number of the account linked to the card, each # in the example should be replaced with a digit 0-9 | String, regex pattern "^\d+$" | "#########" |
Types of Identification
- "SSN" - US SSN
- "SIN" - Canada SIN
- "NIN" - Other national ID number
- "TIN" - Taxpayer identification number
- "PASSPORT" - Any country passport
- "DRIVING LICENSE" - For US only
- "CONSULAR" - For foreign, consular ID
- "VOTER" - US only, voter ID
- "MILITARY ID" - Military ID, US only
- "GOVERNMENT ISSUED ID" - Other Government-issued ID
Request method and URL:
POST /condor/card/activate
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples:
This example contains the required cardId, plus each of the optional activateAttributes that can be included in a card activation request.
{
"cardId" : "crda_6v9nQ3AKKyD5bzvTVbnkN2", //card ID in connectFi
"activateAttributes": { //optional combination of object properties used to verify identity of cardholder and validity of the activation request. Any properties included in the "activateAttributes" object must match actual card/cardholder data stored in connectFi.
"cardLastFour" : "####", //The last four digits on the card, #### is used as a placeholder here for documentation purposes
"cardExpDate" : "1020-25", //The expiration date on the card in MMYY-YY format
"ssnLastFour" : "####", //The last four digits of the cardholder's Social Security Number, #### is used as a placeholder here for documentation purposes
"otherIdentificationType" : "SSN", //The type of identification to check "otherIdentificationValue" against
"otherIdentificationValue" : "#########", //a 9 digit Social Security Number, ######### is used as a placeholder here for documentation purposes, paired with "otherIdentificationType"
"dateOfBirth" : "1978-10-15", //Date of birth of the cardholder
"routingNo" : "#########" //a US ABA account routing number, ######### is used as a placeholder here for documentation purposes
}
}
This example contains the required cardId, plus the last four digits on the card.
{
"cardId" : "crda_6v9nQ3AKKyD5bzvTVbnkN2", //card ID in connectFi
"activateAttributes": {
"cardLastFour" : "####", //The last four digits on the card, #### is used as a placeholder here for documentation purposes
}
}
This example contains the required cardId, plus a combination of "otherIdentificationType" and "otherIdentificationValue" activateAttribute properties.
{
"cardId" : "crda_6v9nQ3AKKyD5bzvTVbnkN2", //card ID in connectFi
"activateAttributes": {
"otherIdentificationType" : "SSN", //The type of identification to check "otherIdentificationValue" against
"otherIdentificationValue" : "#########", //a 9 digit Social Security Number, ######### is used as a placeholder here for documentation purposes, paired with "otherIdentificationType"
}
}
This example contains only the required cardId. You may decide to choose this option if you have already verified the customer identification and validity of the activation through your existing front-end or middle-ware.
Possible responses
200 (HTTP response status code) -- Success, the card status is updated to "ACTIVE"
{
"code": "0", //Success
"data": {
"last_four": "####", //last 4 digits on the card, #### is used as a placeholder here for documentation purposes
"status": "ACTIVE", //card status is now "ACTIVE"
"program_id": "Virtual_Debit_Card",
"name_on_card": "JESSIE TESTMAN UWUR",
"available_balance": 0, //amount that has been loaded onto the card
"currency_code": "USD",
"additional_data": {
"account_number": "##############", //customer account number associated with the card, ############## is used as a placeholder for documentation purposes
"issue_date": "2022-10-25T17:10:13.185919Z", //date the card was issued
"activation_date": "2022-10-26T17:07:36.327260Z", //date the card was activated
"design_id": "1",
"designId": "1",
"card_expiration": "102025", //card expiration date MMYYYY
"processor_token": "369029824451",
"routing_number": "#########" //a US ABA account routing number, ######### is used as a placeholder here for documentation purposes
"accountId": "acca_6JbMasxECOj7a4IN45NpXi" //account ID in connectFi
},
"cardId": "crda_6v9nQ3AKKyD5bzvTVbnkN2" //card ID in connectFi
}
}
400 (HTTP response status code) -- Cardholder does not have __ as identification stored
In this example, the "otherIdentificationType" requested as one of the activateAttributes properties is not a type of identification that has been stored for the specified cardholder.
{
"code": "extCondor",
"subCode": "C0917",
"context": {
"title": "cardsActivateByToken"
},
"message": "Cardholder does not have DRIVING LICENSE as identification stored."
}
400 (HTTP response status code) -- Provided data didn't match card data
In this example, the values in the request body activateAttributes object did not match the card/cardholder data stored in connectFi.
{
"code": "extCondor",
"subCode": "C0917",
"context": {
"title": "cardsActivateByToken"
},
"message": "Provided data didn't match card data."
}
400 (HTTP response status code) -- Card cannot be activated, via this API, from current status
In this example, an activation request was made for a card without status "NEW". Cards cannot be activated using this endpoint if they have status codes "BLOCK", "FRAUD_BLOCK", "CLOSED", or are already "ACTIVE". To change a card marked as "BLOCK" or "FRAUD_BLOCK" back to "ACTIVE", see Change Debit Card Status.
{
"code": "extCondor",
"subCode": "C1014",
"context": {
"title": "cardsActivateByToken"
},
"message": "Card cannot be activated, via this API, from current status."
}
400 (HTTP response status code) -- Unknown Error
This error might occur for a number of reasons. In this case, an attempt was made to activate a card using only "otherIdentificationValue" as an activeAttributes property, without including the "otherIdentificationType" property to pair with it.
{
"code": "extCondor",
"subCode": "G0000",
"context": {
"title": "Unknown Error"
},
"message": "Please contact support with error code and request id: LR-01379c08-1edb-4f34-8258-55a659c995f2"
}
Set a Debit Card PIN
Description:
This endpoint is used to set the PIN for a debit card. The card must have an "ACTIVE" or "NEW" status to be able to set the PIN. Attempts to change or set the PIN on a card with status codes "BLOCK", "FRAUD_BLOCK", or "CLOSED" will result in an error. The PIN must be a four digit whole number.
Required Properties | Description | Schema | Example Values |
---|---|---|---|
cardId | The card ID in connectFi | String | "crda_fO2N93TnJZvSmUgFFClUA" |
newPin | The desired new pin number | String, regex pattern "^\d{4}$" | "1234" |
Request method and URL:
POST /condor/card/set-pin
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example:
{
"cardId" : "crda_fO2N93TnJZvSmUgFFClUA", //card ID in connectFi
"newPin": "1234" //a four digit whole number
}
Possible responses:
200 (HTTP response status code) -- Success, the pin number was changed
```JSON { "code": "0", //Success "data": { "cardSetPin": { "verified": true, "cardId": "crda_fO2N93TnJZvSmUgFFClUA" //card ID in connectFi } } }
400 (HTTP response status code) -- Set Card PIN Decline (Inactive Card) or (Closed Card)
In this example, an attempt was made to set the PIN nmber for a card with a status of "BLOCK". If an attempt to set the PIN of a card with status "CLOSED" is made, a similar error will be returned indicating that the card is closed instead of inactive.
```JSON
{
"code": "extCondor",
"subCode": "C1004",
"context": {
"title": "cardsSetPinByToken"
},
"message": "Set Card PIN Decline (Inactive Card)"
}
400 (HTTP response status code) -- Set Card PIN Decline (Suspected Fraud Hit, Card is Already Blocked)
In this example, an attempt was made to set the PIN nmber for a card with a status of "FRAUD_BLOCK". This indicates a suspected fraud hit.
{
"code": "extCondor",
"subCode": "C1004",
"context": {
"title": "cardsSetPinByToken"
},
"message": "Set Card PIN Decline (Suspected Fraud Hit, Card is Already Blocked)"
}
400 (HTTP response status code) -- Must match pattern
In this example, the requested PIN was not a four digit whole number.
{
"code": "requestValidateError",
"context": [
{
"instancePath": "/newPin",
"schemaPath": "#/properties/newPin/pattern",
"keyword": "pattern",
"params": {
"pattern": "^\\d{4}$"
},
"message": "must match pattern \"^\\d{4}$\""
}
]
}
Change Debit Card Status
Description:
This type of request is used to change the status of a debit card. Valid status values are:
- "ACTIVE" - Open, all actions allowed
- "BLOCK" - Inactive, cannot set PIN or activate card through the /condor/card/activate endpoint.
- "FRAUD_BLOCK" - Blocked (inactive) due to fraud, cannot set PIN, reissue card, or activate card through the /condor/card/activate endpoint.
- "CLOSED" - closed, card status can no longer be changed. Card cannot be reactivated or reissued.
Required Properties | Description | Schema | Example Values |
---|---|---|---|
cardId | The card ID in connectFi | String | "crda_fO2N93TnJZvSmUgFFClUA" |
statusAction | The requested status | String | "ACTIVE", "BLOCK", "FRAUD_BLOCK", or "CLOSED" |
Optional Properties | Description | Schema | Example Values |
---|---|---|---|
reason | The reason why the card status is being changed, nullable | String | "Test space" |
Request method and URL:
POST /condor/card/change-status
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example:
{
"cardId" : "crda_fO2N93TnJZvSmUgFFClUA", //card ID in connectFi
"statusAction": "FRAUD_BLOCK", //desired status
"reason" : "Test space" //reason why the status change is being requested, optional
}
Possible responses:
200 (HTTP response status code) -- Success, the status of the card was changed
{
"code": "0", //Success
"data": {
"cardChangeStatus": {
"last_four": "####", //last 4 digits on the card, #### is used as a placeholder here for documentation purposes
"status": "FRAUD_BLOCK", //updated status after request succeeded
"program_id": "Virtual_Debit_Card",
"name_on_card": "JESSIE U TESTMAN 2",
"available_balance": 0, //amount that has been loaded onto the card
"currency_code": "USD",
"additional_data": {
"account_number": "##############", //customer account number associated with the card, ############## is used as a placeholder for documentation purposes
"issue_date": "2022-10-25T18:08:32.985266Z", //date the card was issued
"activation_date": "2022-10-26T17:30:30.261288Z", //date the card was activated
"design_id": "1",
"designId": "1",
"card_expiration": "102025", //card expiration date MMYYYY
"processor_token": "369029826861",
"routing_number": "#########" //a US ABA account routing number, ######### is used as a placeholder here for documentation purposes
},
"cardId": "crda_fO2N93TnJZvSmUgFFClUA" //card ID in connectFi
}
}
}
400 (HTTP response status code) -- Set Card Status Decline
In this example, a request to change a "NEW" card to status code "BLOCK" was attempted. You may use this endpoint to change a "NEW" card to status code "FRAUD_BLOCK", "CLOSED", or "ACTIVE".
{
"code": "extCondor",
"subCode": "C1014",
"context": {
"title": "cardsUpdateStatusByToken"
},
"message": "Set Card Status Decline (Changing card status from existing status to status (Inactive) is not allowed))"
}
400 (HTTP response status code) -- Status action must be equal to one of the allowed values
In this example, an invalid statusAction was requested.
{
"code": "requestValidateError",
"context": [
{
"instancePath": "/statusAction",
"schemaPath": "#/properties/statusAction/enum",
"keyword": "enum",
"params": {
"allowedValues": [
"ACTIVE",
"BLOCK",
"FRAUD_BLOCK",
"CLOSED"
]
},
"message": "must be equal to one of the allowed values"
}
]
}
Reissue a Debit Card
Description:
This endpoint will reissue an existing debit card. Cards with a status of "CLOSED" or "FRAUD_BLOCK" cannot be reissued. If a card with a "BLOCK" status is reissued, its status will remain as "BLOCK" and will still be inactive.
Required Properties | Description | Schema | Example Values |
---|---|---|---|
cardId | Card ID in connectFi | String | "crda_gYVPQlVLIW0QETZzLQg1i1" |
cardAttributes | Attributes of the card - unlike the /condor/card/create request, the only required cardAttribute property for this endpoint is the issueType | Object | See cardAttributes Object below |
cardAttributes Object
Required Properties | Description | Schema | Example Values |
---|---|---|---|
issueType | Description identifying issue category of card | String | "NEW", "REGISTRATION", "RE-ISSUE", "EXPIRED", or "DAMAGED" |
Optional Properties | Description | Schema | Example Values |
---|---|---|---|
reference | An external alphanumeric reference ID (1-20 characters) for the card in your system | String, regex pattern "^[0-9a-zA-Z]+$" | "externalCrdId1234" |
productID | Product ID of card | String | "Virtual_Debit_Card" |
nameOnCard | Full customer name that will appear on the card | String | "JESSIE U TESTMAN" |
cardShippingMethod | Shipping method chosen for card | String | "Standard" |
designId | An ID representing the design chosen for the card | String | "1" |
addressType | Type of address | String | "PRIMARY" or "SECONDARY" |
additionalData | An object containing any necessary additional key:value pair properties not listed elsewhere | Object | {"someProperty" : "Property value"} |
Request method and URL:
POST /condor/card/re-issue
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example:
{
"cardId" : "crda_5ovuxBHc9DSTsXjv4LpJO4", //card ID in connectFi
"cardAttributes": {
"issueType" : "DAMAGED"
}
}
Possible responses:
200 (HTTP response status code) -- Success, card was reissued
{
"code": "0", //Success
"data": {
"last_four": "####", //last 4 digits on the card, #### is used as a placeholder here for documentation purposes
"status": "NEW",
"program_id": "Virtual_Debit_Card",
"name_on_card": "SUSAN TESTMAN UWUR 3",
"available_balance": 0, //amount that has been loaded onto the card
"currency_code": "USD",
"additional_data": {
"account_number": "##############", //customer account number corresponding to the new card, ############## is used as a placeholder for documentation purposes
"issue_date": "2022-10-13T16:25:48.915766Z",
"design_id": "1",
"designId": "1",
"card_expiration": "112025",
"processor_token": "369029384829",
"routing_number": "#########" //a US ABA account routing number, ######### is used as a placeholder here for documentation purposes
"accountId": "acca_5pPqA1imoRrOtoC8i8QTGk" //account ID in connectFi
},
"cardId": "crda_5ovuxBHc9DSTsXjv4LpJO4" //card ID in connectFi
}
}
400 (HTTP response status code) -- Card is closed, cannot be reissued
In this example, a request to reissue a card that has a "CLOSED" status was attempted.
{
"code": "extCondor",
"subCode": "C1022",
"context": {
"title": "cardsPost"
},
"message": "Card is Closed, cannot be reissued."
}
400 (HTTP response status code) -- Suspected Fraud Hit
In this example, an attempt was made to reissue a card that has status code "FRAUD_BLOCK" and this indicates a suspected fraud hit.
{
"code": "extCondor",
"subCode": "C0010",
"context": {
"title": "cardsPost"
},
"message": "Reissue Card Decline (Suspected Fraud Hit, Card is Already Blocked)"
}
400 (HTTP response status code) -- Must be equal to one of the allowed values
In this example, an invalid issueType value was included in the request.
{
"code": "requestValidateError",
"context": [
{
"instancePath": "/cardAttributes/issueType",
"schemaPath": "#/properties/issueType/enum",
"keyword": "enum",
"params": {
"allowedValues": [
"NEW",
"REGISTRATION",
"RE-ISSUE",
"EXPIRED",
"DAMAGED"
]
},
"message": "must be equal to one of the allowed values"
}
]
}
Get a Debit Card Available Balance
Description:
This endpoint will return the available balance and ledger balance on a debit card. The cardId must be included in the URL as a path parameter.
Request method and URL:
GET /condor/card/balance/:cardId
Request headers:
{
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body: none
Possible responses:
200 (HTTP response status code) -- Success, card balance was returned (0 balance)
{
"code": "0", //Success
"data": {
"cardBalance": {
"currency_code": "USD",
"available_balance": 0, //amount that has been loaded onto the card
"ledger_balance": 0,
"cardId": "crda_6s3I3eWyRwOMkvoofAu50U" //card ID in connectFi
}
}
}
200 (HTTP response status code) -- Success, card balance was returned (positive balance)
{
"code": "0", //Success
"data": {
"cardBalance": {
"currency_code": "USD",
"available_balance": 50.99, //amount that has been loaded onto the card
"ledger_balance": 50.99,
"cardId": "crda_7yjMsjGeipBP0D0dJ1HxKo" //card ID in connectFi
}
}
}
Get Debit Card Details
Description:
This endpoint will return the requested card details. The cardId must be included in the URL as a path parameter.
Request method and URL:
GET /condor/card/get/:cardId
Request headers:
{
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body: none
Possible responses:
200 (HTTP response status code) -- Success, card details are returned
{
"code": "0", //Success
"data": {
"condorCard": {
"last_four": "####", //last 4 digits on the card, #### is used as a placeholder here for documentation purposes
"status": "NEW",
"program_id": "Virtual_Debit_Card",
"name_on_card": "JESSIE TESTMAN UWUR",
"available_balance": 0, //amount that has been loaded onto the card
"currency_code": "USD",
"additional_data": {
"account_number": "##############", //customer account number associated with the card, ############## is used as a placeholder for documentation purposes
"issue_date": "2022-10-13T18:57:06.787212Z",
"design_id": "1",
"designId": "1",
"card_expiration": "112025",
"processor_token": "369029391377",
"routing_number": "#########" //a US ABA account routing number, ######### is used as a placeholder here for documentation purposes
"accountId": "acca_6tnMJL85Ozk7hZxicTwUkk" //account ID in connectFi
},
"cardId": "crda_6s3I3eWyRwOMkvoofAu50U" //card ID in connectFi
}
}
}
Financial Credits and Debits Overview
A financial credit is when money is credited to (loaded onto) the balance of the specified debit card. A financial debit is when money is debited (subtracted) from the balance of the specified debit card. Required request body properties for both financial credits and financial debits are "cardId", "amount", and "currency". Optional properties include "reference", "merchant", "transactionType", and "additionalData".
Required Properties | Description | Schema | Example Values |
---|---|---|---|
cardId | The unique card ID in connectFi | String | "crda_1EnrcK7QgBU2030pNCaygA" |
amount | The requested credit/debit amount | Number > 0 | 560.99 |
currency | A three character ISO alphabetic code to identify the currency | String, regex pattern: "^[A-Z]{3}$" | "USD" |
Optional Properties | Description | Schema | Example Values |
---|---|---|---|
reference | An external reference in your system (1-20 alphanumeric characters) | String, regex pattern: "^[0-9a-zA-Z]+$" | "externlCrdtId123" |
merchant | An object containing merchant properties | Object | See Merchant Object below |
transactionType | The type of transaction | String | "DEBIT_ADJUSTMENT", "PROVISIONAL_DEBIT", "CREDIT_ADJUSTMENT", "PROVISIONAL_CREDIT ", "CREDIT", "DEBIT", "DD_ACH_DEBIT", "DD_CREDIT", "BANK_TRANSFER_DEBIT", "BANK_TRANSFER_CREDIT", "ACH_RETURN", "FEE", "FEE_REVERSAL", "RETAIL_CREDIT", "AGENT_LOC_CREDIT", "RETAIL_DEBIT", "WITHDRAWAL", "PRE_AUTH", "PRE_AUTH_COMPLETE", or "DIRECT_LOADS" |
additionalData | An object containing any necessary additional key:value pair properties not listed elsewhere | Object | {"someProperty" : "Property value"} |
Merchant Object:
Required Properties | Description | Schema | Example Values |
---|---|---|---|
mcc | The merchant category code | String, regex pattern: "^\d+$" | "5813" |
mccName | Name of the mcc category | String | "Restaurant" |
mccGroup | The mcc group in which the category is included | String | "F002-Restaurant-Eating and Drinking Places" |
name | The name of the merchant | String | "Fantastic Fancy Dining" |
Optional Properties | Description | Schema | Example Values |
---|---|---|---|
city | The city in which the merchant is located | String | "Chicago" |
region | The region in which the merchant is located | String | "Mid-West" |
countryCodeA3 | The three letter country code in which the merchant is located | String | "USA" |
Financial Credit
Description:
This endpoint is used to request a credit to a specified debit card. The funds amount loaded onto the card must be greater than 0.
Request method and URL:
POST /condor/financial/credit
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example:
This example request body has only the required properties.
{
"cardId" : "crda_1EnrcK7QgBU2030pNCaygA", //card ID in connectFi
"amount": 700.00, //amount to be credited to the card, must be greater than 0
"currency": "USD" //currency code (represented by 3 characters)
}
This example request body contains all required properties, plus optional properties: "reference", "merchant" object, and "transactionType".
{
"cardId" : "crda_1dNEursRaiIY2Kz4WNzvcw", //card ID in connectFi
"amount": 5.01, //amount to be credited to the card, must be greater than 0
"currency": "USD", //currency code (represented by 3 characters)
"reference" : "externlCrdtId123", //external reference in your system
"merchant" : {
"mcc" : "5813", //Merchant Category Code
"mccName" : "Restaurant", //Name of Merchant Category Code
"mccGroup" : "F002-Restaurant-Eating and Drinking Places", //Merchant Category Code Group
"name" : "Fantastic Fancy Dining", //Name of merchant
"city" : "Chicago", //merchant city
"region" : "Mid-West", //merchant region
"countryCodeA3" : "USA" //merchant country code
},
"transactionType" : "CREDIT" //transaction type (even if a more specific type of credit is indicated here, the transaction_type property in the response will still be designated "CREDIT")
}
Possible responses:
200 (HTTP response status code) -- Success, the debit card was credited with the requested amount, only required request properties were used
{
"code": "0", //Success
"data": {
"transaction": {
"transaction_type": "CREDIT",
"amount": 700, //the amount that was credited (loaded) to the card balance
"currency_code": "USD", //currency code (represented by 3 characters)
"state": "COMPLETE", //internal status of transaction
"running_balance": 1529.72, //card balance after the current transaction
"international": false,
"transaction_datetime": "2022-10-17T15:27:49.656Z",
"additional_data": {
"fee_amount": 0
},
"id": "cс_20aIosKGV35ZFkAd7ef3ys", //transaction ID in connectFi
"cardId": "crda_1EnrcK7QgBU2030pNCaygA" //card ID in connectFi
}
}
}
200 (HTTP response status code) -- Success, the card was credited with the requested amount, optional request properties "reference", "merchant" object, and "transactionType" were included.
{
"code": "0", //Success
"data": {
"transaction": {
"transaction_type": "CREDIT",
"amount": 5.01, //the amount that was credited (loaded) to the card balance
"currency_code": "USD", //currency code (represented by 3 characters)
"state": "COMPLETE", //internal status of transaction
"merchant": {
"mcc": 5813, //Merchant Category Code
"mcc_name": "Restaurant", //Name of Merchant Category Code
"mcc_group": "F002-Restaurant-Eating and Drinking Places", //Merchant Category Code Group
"merchant_name": "Fantastic Fancy Dining", //Name of merchant
"merchant_city": "Chicago", //merchant city
"merchant_region": "Mid-West", //merchant region
"merchant_country": "USA" //merchant country code
},
"running_balance": 323.78, //card balance after the current transaction
"international": false,
"transaction_datetime": "2022-10-17T18:20:12.619Z",
"additional_data": {
"fee_amount": 0
},
"id": "cс_2D5itp254oNp8Ejdj6wLjm", //transaction ID in connectFi
"cardId": "crda_1dNEursRaiIY2Kz4WNzvcw" //card ID in connectFi
}
}
}
400 (HTTP response status code) -- Numeric instance is greater than required maximum
In this example, a credit amount greater than 9999999999.99 was requested.
{
"code": "extCondor",
"subCode": "C1013",
"context": {
"title": "cardsCreditTransaction"
},
"message": "numeric instance is greater than the required maximum (maximum: 9999999999.99, found: 1E+16) for [/amount]"
}
400 (HTTP response status code) -- MoneyGram POS Money Load Decline
In this example, a credit amount of exactly 9999999999.99 was requested, but the card already had funds loaded. This would result in a card balance greater than the 9999999999.99 maximum.
{
"code": "extCondor",
"subCode": "T0003",
"context": {
"title": "cardsCreditTransaction"
},
"message": "MoneyGram POS Money Load Decline"
}
400 (HTTP response status code) -- Credit amount must be greater than 0
In this example, a credit amount of 0 was requested.
{
"code": "requestValidateError",
"context": [
{
"instancePath": "/amount",
"schemaPath": "financial#/definitions/amount/exclusiveMinimum",
"keyword": "exclusiveMinimum",
"params": {
"comparison": ">",
"limit": 0
},
"message": "must be > 0"
}
]
}
Financial Debit
Description:
This endpoint is used to request a debit from a specified card. The card must have sufficient funds loaded onto it in order for the request to succeed. A card must have a positive balance and an "ACTIVE" status in order to be debited. If the set maximum allowed withdrawal amount is exceeded within a certain time interval, the request will throw an error, even if the card has sufficient funds available.
Request method and URL:
POST /condor/financial/debit
Request headers:
{
"Content-Type": "application/json",
"x-connectFi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples:
This example request body has only the required properties.
{
"cardId" : "crda_1EnrcK7QgBU2030pNCaygA", //card ID in connectFi
"amount": 250, //amount to be debited from the card, must be greater than 0
"currency": "USD" //currency code (represented by 3 characters)
}
This example request body contains all required properties, plus optional properties: "reference", "merchant" object, and "transactionType".
{
"cardId" : "crda_1dNEursRaiIY2Kz4WNzvcw", //card ID in connectFi
"amount": 15.62, //amount to be debited from the card, must be greater than 0
"currency": "USD", //currency code (represented by 3 characters)
"reference" : "externlCrdtId123", //external reference in your system
"merchant" : {
"mcc" : "5813", //Merchant Category Code
"mccName" : "Restaurant", //Name of Merchant Category Code
"mccGroup" : "F002-Restaurant-Eating and Drinking Places", //Merchant Category Code Group
"name" : "Fantastic Fancy Dining", //Name of merchant
"city" : "Chicago", //merchant city
"region" : "Mid-West", //merchant region
"countryCodeA3" : "USA" //merchant country code
},
"transactionType" : "DEBIT" //transaction type (even if a more specific type of debit is indicated here, the transaction_type property in the response will still be designated "DEBIT")
}
Possible responses:
200 (HTTP response status code) -- Success, debit was successful (only required properties present)
{
"code": "0", //Success
"data": {
"transaction": {
"transaction_type": "DEBIT",
"amount": 250, //amount debited from the card, greater than 0
"currency_code": "USD", //currency code (represented by 3 characters)
"state": "COMPLETE", //internal status of transaction
"running_balance": 1209.72, //card balance after the current transaction
"international": false,
"transaction_datetime": "2022-10-17T15:14:23.641Z",
"additional_data": {
"fee_amount": 0
},
"id": "cс_2RQkugaT85ITUToNCaaepm", //transaction ID in connectFi
"cardId": "crda_1EnrcK7QgBU2030pNCaygA" //card ID in connectFi
}
}
}
200 (HTTP response status code) -- Success, debit was successful (optional properties "reference", "merchant" object, and "transactionType" present)
{
"code": "0", //Success
"data": {
"transaction": {
"transaction_type": "DEBIT",
"amount": 15.62, //amount debited from the card, greater than 0
"currency_code": "USD", //currency code (represented by 3 characters)
"state": "COMPLETE", //internal status of transaction
"merchant": {
"mcc": 5813,
"mcc_name": "Restaurant",
"mcc_group": "F002-Restaurant-Eating and Drinking Places",
"merchant_name": "Fantastic Fancy Dining",
"merchant_city": "Chicago",
"merchant_region": "Mid-West",
"merchant_country": "USA"
},
"running_balance": 334.39, //card balance after the current transaction
"international": false,
"transaction_datetime": "2022-10-17T17:36:23.816Z",
"additional_data": {
"fee_amount": 0
},
"id": "cс_1BML3aTIevV7fDbzGABtrm", //transaction ID in connectFi
"cardId": "crda_1dNEursRaiIY2Kz4WNzvcw" //card ID in connectFi
}
}
}
400 (HTTP response status code) -- Transaction denied due to maximum cash withdrawal amount in given interval
In this example, the maximum amount of combined debit transactions was exceeded within a specified interval.
{
"code": "extCondor",
"subCode": "T0002",
"context": {
"title": "cardsDebitTransaction"
},
"message": "Manual Signature Based Cash Withdrawal Decline (Transaction Denied, due to Maximum Cash Withdrawal Amount in Given Interval (1000))"
}
400 (HTTP response status code) -- Transaction denied due to maximum cash withdrawal amount within last 1 day
In this example, a debit amount of 9000000000 was requested.
{
"code": "extCondor",
"subCode": "T0002",
"context": {
"title": "cardsDebitTransaction"
},
"message": "Manual Signature Based Cash Withdrawal Decline (Transaction Denied, due to Maximum Cash Withdrawal Amount (1000000) within last 1 Day / specific limits on {Service Id[MNL_CSH_SIG]})"
}
400 (HTTP response status code) -- Insufficient funds
In this example, the attempted debit exceeded the funds balance available.
{
"code": "extCondor",
"subCode": "T0002",
"context": {
"title": "cardsDebitTransaction"
},
"message": "Manual Signature Based Cash Withdrawal Decline (Insufficient Funds [1529.72])"
}
400 (HTTP response status code) -- Debit amount must be greater than 0
In this example, a debit amount of 0 was requested.
{
"code": "requestValidateError",
"context": [
{
"instancePath": "/amount",
"schemaPath": "financial#/definitions/amount/exclusiveMinimum",
"keyword": "exclusiveMinimum",
"params": {
"comparison": ">",
"limit": 0
},
"message": "must be > 0"
}
]
}
400 (HTTP response status code) -- Pre-Active Card
In this example, a debit transaction was attempted on a card that has not yet been activated.
{
"code": "extCondor",
"subCode": "C1016",
"context": {
"title": "cardsDebitTransaction"
},
"message": "Manual Signature Based Cash Withdrawal Decline (Pre-Active Card)"
}
400 (HTTP response status code) -- Blocked Card
In this example, a debit transaction was attempted on a card that has been blocked and is currently inactive. If a card has been blocked, you must make a request to the /condor/card/change-status endpoint to change the card status to "ACTIVE" before attempting a debit transaction from the card.
{
"code": "extCondor",
"subCode": "T0002",
"context": {
"title": "cardsDebitTransaction"
},
"message": "Manual Signature Based Cash Withdrawal Decline (Inactive Card)"
}
Financial p2p
Description:
This endpoint is used for peer-to-peer (p2p) money transfers between two participants: the source participant and the beneficiary participant. The source participant and the beneficiary participant should be different. Peer-to-peer transactions cannot be made, for example, between a card and itself. A Peer-to-Peer Transactions chart has been included below to illustrate valid and invalid p2p transaction examples. Request body properties are listed below as well.
Required Properties | Description | Schema | Example Values |
---|---|---|---|
source | The participant from whom the money is being transferred | Object | See Participant Object below |
beneficiary | The participant to whom the money is being transferred | Object | See Participant Object below |
amount | The requested transfer amount | Number > 0 | 65.99 |
currency | A three character ISO alphabetic code to identify the currency | String, regex pattern: "^[A-Z]{3}$" | "USD" |
Optional Properties | Description | Schema | Example Values |
---|---|---|---|
reference | An external reference in your system (1-20 alphanumeric characters) | String, regex pattern: "^[0-9a-zA-Z]+$" | "externlCrdtId123" |
additionalData | An object containing any necessary additional key:value pair properties not listed elsewhere | Object | {"someProperty" : "Property Value"} |
Participant Object
Required Properties | Description | Schema | Example Values |
---|---|---|---|
type | The type of participant | String | "CARD" or "CARDHOLDER" |
id | The participant ID | String | "csta_2Z8UujOAAEmaKdbiveb7hS" |
Peer-to-Peer Transactions
Source | Beneficiary | Valid? |
---|---|---|
Cardholder1 | Cardholder2 | Yes, as long as Cardholder1's primary debit account is ACTIVE and Cardholder2's primary debit account status is either ACTIVE, NEW, or BLOCK |
Cardholder1 | Card2 (any card belonging to Cardholder2) | Yes, as long as Cardholder1's primary debit account is ACTIVE and Card2 has ACTIVE, NEW, or BLOCK status |
Card1 with ACTIVE status | Cardholder2 | Yes, as long as Cardholder2's primary debit account status is either ACTIVE, NEW, or BLOCK |
Cardholder1 | Card1 (any secondary debit card belonging to Cardholder1) | Yes, as long as Cardholder1's primary debit account is ACTIVE and Cardholder1's secondary debit card has ACTIVE, NEW, or BLOCK status |
Cardholder1 | Card1 (primary debit card belonging to Cardholder1) | No |
Card1 with ACTIVE status | Card2 with ACTIVE/NEW/BLOCK status | Yes |
Card1 with ACTIVE status | Card2 with FRAUD_BLOCK/CLOSED status | No |
Card1 with NEW/BLOCK/FRAUD_BLOCK/CLOSED status | Any | No |
A primary debit account is defined as the initial debit account created for the customer through the /condor/customer/create endpoint. Secondary debit accounts are defined as any additional debit accounts created for the customer through the /condor/card/add endpoint.
Request method and URL:
POST /condor/financial/p2p
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body example:
In this p2p example, both participants (source and beneficiary) are of type "CARD"
{
"source" : {
"type" : "CARD",
"id" : "crda_YAJLWlQhVQLFDrcREki9i" //source card ID in connectFi
},
"beneficiary" : {
"type" : "CARD",
"id" : "crda_2QoNFEnRbJ1V6bS68Folja" //beneficiary card ID in connectFi
},
"amount": 10, //the amount to transfer
"currency": "USD" //currency code
}
In this p2p example, the source participant is of type "CARDHOLDER" and the beneficiary participant is of type "CARD".
{
"source" : {
"type" : "CARDHOLDER",
"id" : "csta_4KJQrxiRRrvyyxx9jT5fXq" //source customer ID in connectFi
},
"beneficiary" : {
"type" : "CARD",
"id" : "crda_2QoNFEnRbJ1V6bS68Folja" //beneficiary card ID in connectFi
},
"amount": 10, //the amount to transfer
"currency": "USD" //currency code
}
In this p2p example, both participants (source and beneficiary) are of type "CARDHOLDER"
{
"source" : {
"type" : "CARDHOLDER",
"id" : "csta_4KJQrxiRRrvyyxx9jT5fXq" //source customer ID in connectFi
},
"beneficiary" : {
"type" : "CARDHOLDER",
"id" : "csta_793KgLmuRlKXhTCO0TJJcA" //beneficiary customer ID in connectFi
},
"amount": 18.65, //the amount to transfer
"currency": "USD" //currency code
}
Possible responses:
200 (HTTP response status code) -- Success, funds transferred from source to beneficiary
{
"code": "0", //Success
"data": {
"transaction": {
"transaction_type": "DEBIT",
"amount": 10, //amount that was transferred from the source card to the beneficiary card
"currency_code": "USD", //currency code
"state": "COMPLETE", //current status of the transaction
"running_balance": 90, //amount available on the source card after the transaction occurs
"international": false,
"transaction_datetime": "2022-10-18T18:13:03.746Z",
"additional_data": {
"fee_amount": 0
},
"id": "cс_3UQKZVIUN3BnxOQxTO9fMQ", //transaction ID in connectFi
"cardId": "crda_YAJLWlQhVQLFDrcREki9i" //primary debit card ID for the source participant in connectFi
}
}
}
400 (HTTP response status code) -- Pre-Active Card
In this example, a p2p transaction was attempted on a card that has not yet been activated (either source participant card, beneficiary participant card, or both).
{
"code": "extCondor",
"subCode": "C1016",
"context": {
"title": "cardsDebitTransaction"
},
"message": "Manual Signature Based Cash Withdrawal Decline (Pre-Active Card)"
}
400 (HTTP response status code) -- Insufficient Funds
In this example, the source participant card does not have sufficient funds loaded to be able to complete the transaction.
{
"code": "extCondor",
"subCode": "T0007",
"context": {
"title": "p2pFundsTransfer"
},
"message": "Funds Transfer Decline (From Card) (Insufficient Funds [0.0])"
}
400 (HTTP response status code) -- FROM card and TO card should be different
In this example, a request was made to transfer funds from a customer (source participant) to the primary debit card issued to that same customer (beneficiary participant). When requesting a "CARDHOLDER" as a participant, the primary debit account of that cardholder is used for the transaction. So, if a request is made from a "CARDHOLDER" (as the source participant) to the same customer's primary debit card (as the beneficiary), then the source account and the beneficiary account are the exact same and the request will throw an error. Requesting a transfer from a "CARD" to the same "CARD" or a transfer from a "CARDHOLDER" to the same "CARDHOLDER" will throw a similar error.
{
"code": "extCondor",
"subCode": "T0007",
"context": {
"title": "p2pFundsTransfer"
},
"message": "Funds Transfer Decline (From Card) (FROM card and TO card should be different.)"
}
400 (HTTP response status code) -- Property must be object
In this example, the source and beneficiary values were given as card ID Strings instead of participant objects.
{
"code": "requestValidateError",
"context": [
{
"instancePath": "/source",
"schemaPath": "financial#/definitions/participant/type",
"keyword": "type",
"params": {
"type": "object"
},
"message": "must be object"
}
]
}
Retrieve Transaction History
Description:
This endpoint will return a list of transactions associated with the given cardId. The system will return any transactions located that meet the filter criteria specified. The "cardId" is a required property of the request body object. If no other properties are present in the request body, only the 20 most recent transactions associated with the requested cardId will be returned. Optional request body properties are "dateFrom", "dateTo", "offset", "numberOfTransactions", and "status". Transactions will be listed in order starting with the most recent transaction at index 0.
Required Properties | Description | Schema | Example Values |
---|---|---|---|
cardId | The card ID in connectFi for which you are requesting the transaction history | String | "crda_5Mx3p6lSIQevd0qwfFhhSs" |
Optional Properties | Description | Schema | Example Values |
---|---|---|---|
"dateFrom" | The beginning of the requested transaction period in "YYYY-MM-DD" format | String | "2021-01-01" |
"dateTo" | The end of the requested transaction period in "YYYY-MM-DD" format | String | "2022-10-14" |
"offset" | A value representing the desired number of transaction groups by which to offset the result (the number of transactions in each group is defined by the "numberOfTransactions" property and defaults to 20). For example, "offset" : 1 will return the most recent 20 transactions, "offset" : 2 will return the next set of 20 transactions, and so on. |
Integer > 0 | 2 |
"numberOfTransactions" | Represents the number of desired transactions to return. The default is 20 transactions. If the number of transactions meeting all other criteria is less than the requested "numberOfTransactions", it is fine. All transactions located that meet remaining criteria will be returned. If a value of 0 is used, this filter will be ignored | Integer >= 0 | 15 |
"status" | If present, will filter the results to return only the transactions matching the requested status | String | "ALL", "PENDING", "COMPLETE", or "DECLINED" |
Request method and URL:
POST /condor/transaction/history
Request headers:
{
"Content-Type": "application/json",
"x-connectfi-token": "a long random string" //Authorization token received from /auth/get-token request
}
Request body examples:
This request has no optional properties and will return the 20 most recent transactions associated with the requested cardId
This request includes a date filter and will only return transactions between the dates of "2021-01-01" and "2022-10-13".
{
"cardId" : "crda_1EnrcK7QgBU2030pNCaygA", //card ID in connectFi
"dateFrom" : "2021-01-01",
"dateTo" : "2022-10-13"
}
This request will only return the 2 most recent transactions.
{
"cardId" : "crda_1EnrcK7QgBU2030pNCaygA", //card ID in connectFi
"numberOfTransactions" : 2 //non-negative integer representing the number of transactions to return, will be ignored if 0 is requested
}
This request sets the number of transactions to be returned as 15. It will skip the first set of transactions (15 most recent transactions) and return the second set of transactions because the offset value is 2.
{
"cardId" : "crda_1EnrcK7QgBU2030pNCaygA", //card ID in connectFi
"numberOfTransactions" : 15, //non-negative integer representing the number of transactions to return, will be ignored if 0 is requested
"offset" : 2 //skip the most recent group of 15 (value defined by "numberOfTransactions") transactions and return the 2nd set of 15 transactions.
}
This request will only return the 20 most recent transactions with a "PENDING" status. If less than 20 "PENDING" transactions exist, then any "PENDING" transactions located for this card will be returned.
{
"cardId" : "crda_1EnrcK7QgBU2030pNCaygA", //card ID in connectFi
"status" : "PENDING" //or "ALL", "COMPLETE", "DECLINED"
}
Possible responses:
200 (HTTP response status code) -- Success, requested transactions were returned
{
"code": "0", //Success
"data": {
"transactions": [
{
"transaction_type": "DEBIT", //Possible types include: "DEBIT_ADJUSTMENT", "PROVISIONAL_DEBIT", "CREDIT_ADJUSTMENT", "PROVISIONAL_CREDIT ", "CREDIT", "DEBIT", "DD_ACH_DEBIT", "DD_CREDIT", "BANK_TRANSFER_DEBIT", "BANK_TRANSFER_CREDIT", "ACH_RETURN", "FEE", "FEE_REVERSAL", "RETAIL_CREDIT", "AGENT_LOC_CREDIT", "RETAIL_DEBIT", "WITHDRAWAL", "PRE_AUTH", "PRE_AUTH_COMPLETE", "DIRECT_LOADS"
"amount": -250, //transaction amount
"currency_code": "USD", //currency code
"state": "COMPLETE", //internal status of transaction
"running_balance": 1459.72, //Current account balance as of this transaction
"iso_message_type": "0200",
"device_type": "API",
"international": false,
"transaction_datetime": "2022-10-14T12:52:59.000Z",
"additional_data": {
"memo": "Manual Signature Based Cash Withdrawal",
"fee_amount": 0,
"transaction_details": "Cash Withdrawal"
},
"id": "cс_jGyBv9loClJxnl2MSnKRy", //transaction ID in connectFi
"cardId": "crda_1EnrcK7QgBU2030pNCaygA" //card ID in connectFi
},
{
"transaction_type": "CREDIT",
"amount": 700, //transaction amount
"currency_code": "USD", //currency code
"state": "COMPLETE", //internal status of transaction
"running_balance": 1709.72, //current account balance as of this transaction
"iso_message_type": "0200",
"device_type": "API",
"international": false,
"transaction_datetime": "2022-10-14T12:52:47.000Z",
"additional_data": {
"memo": "MoneyGram POS Money Load",
"fee_amount": 0,
"transaction_details": "Load Money Onto Card"
},
"id": "cс_6lWzQEEbHILWAuG6MppkA", //transaction ID in connectFi
"cardId": "crda_1EnrcK7QgBU2030pNCaygA" //card ID in connectFi
},
{
"transaction_type": "DEBIT",
"amount": -18.21, //transaction amount
"currency_code": "USD", //currency code
"state": "COMPLETE", //internal status of transaction
"running_balance": 1009.72, //current account balance as of this transaction
"iso_message_type": "0200",
"device_type": "API",
"international": false,
"transaction_datetime": "2022-10-14T12:52:37.000Z",
"additional_data": {
"memo": "Manual Signature Based Cash Withdrawal",
"fee_amount": 0,
"transaction_details": "Cash Withdrawal"
},
"id": "cс_7HqlEFvWUiMnkMNQW8BPcc", //transaction ID in connectFi
"cardId": "crda_1EnrcK7QgBU2030pNCaygA" //card ID in connectFi
},
// ... remaining transaction objects ...
]
}
}
200 (HTTP response status code) -- Success, no transactions were returned
In this example, the request was successful, but no transactions matched the search criteria.
{
"code": "0", //Success
"data": {
"transactions": [] //no transactions were found for the requested card ID and filters
}
}
400 (HTTP response status code) -- Date must match pattern
In this example, an incorrect date format was requested as a filter. The optional "dateFrom" and "dateTo" properties must be a string in the format "YYYY-MM-DD" if present in the request body.
{
"code": "requestValidateError",
"context": [
{
"instancePath": "/dateFrom",
"schemaPath": "request#/definitions/dateOnly/pattern",
"keyword": "pattern",
"params": {
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"message": "must match pattern \"^\\d{4}-\\d{2}-\\d{2}$\""
}
]
}
400 (HTTP response status code) -- FromDate is greater than ToDate in request
In this example, the "dateFrom" requested is after the "dateTo", which is invalid. The "dateTo" must be a later date than the "dateFrom".
{
"code": "extCondor",
"subCode": "T0004",
"context": {
"title": "cardsGetTransactionsByToken"
},
"message": "Get Transaction History Decline (FromDate is greater than ToDate in request)"
}
400 (HTTP response status code) -- Must be > 0
In this example, an offset of 0 was used. If an offset is not desired, remove the "offset" property from the request body.
{
"code": "requestValidateError",
"context": [
{
"instancePath": "/offset",
"schemaPath": "#/properties/offset/exclusiveMinimum",
"keyword": "exclusiveMinimum",
"params": {
"comparison": ">",
"limit": 0
},
"message": "must be > 0"
}
]
}
400 (HTTP response status code) -- Must NOT have additional properties
In this example, a request was made with an additional property that is not an allowed option: "amount".
{
"code": "requestValidateError",
"context": [
{
"instancePath": "",
"schemaPath": "#/additionalProperties",
"keyword": "additionalProperties",
"params": {
"additionalProperty": "amount"
},
"message": "must NOT have additional properties"
}
]
}
400 (HTTP response status code) -- Request error
In this example, the "numberOfTransactions" filter was used with a decimal value instead of an integer value. If you receive this error, check to make sure all filter property values match the required schema. If the error persists, contact support with the given error code and request ID.
{
"code": "extCondor",
"subCode": "G0000",
"context": {
"title": "Request error"
},
"message": "Please contact support with error code and request id: TMM-7bacc27c-23aa-49d3-a9db-9c1482c32a8d"
}
Reverse Transaction
Description:
This endpoint will reverse a previously completed transaction. Transactions can not be reversed for debit cards with status values of "BLOCK", "FRAUD_BLOCK", or "CLOSED" or if the checking account associated with the debit card used has insufficient funds to complete the reversal.
Required Properties | Description | Schema | Example Values |
---|---|---|---|
transactionId | The transaction ID in connectFi of the transaction to reverse | String | "cс_3mMsxtaBouaAe6mJGY0kty" |
Optional Properties | Description | Schema | Example Values |
---|---|---|---|
"forcePost" | Boolean, nullable | false | |
"reason" | A description of the reason for the reversal. The value can be null. | String, nullable | "Transaction refund" |
Request method and URL:
POST /condor/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) -- Success, the specified transaction was reversed
{
"code": "0", //Success
"data": {
"transaction": {
"transaction_type": "DEBIT", //type of tranaction that was reversed (In this case, the original transaction was a DEBIT, so the reversal CREDITed the card)
"amount": -1.05, //amount that was reversed (In this case, the original transaction was for -1.05, so the reversal ADDED 1.05 to the available balance)
"currency_code": "USD", //currency code
"state": "COMPLETE", //state of the transaction that was reversed
"running_balance": 682.57, //available balance after the reversal has occurred (In this case, original available balance was 681.52. After 1.05 was credited back to the debit card, 682.57 is now available.)
"iso_message_type": "0400",
"international": false,
"transaction_datetime": "2022-11-02T16:57:56.614Z",
"additional_data": {},
"id": "cс_3mMsxtaBouaAe6mJGY0kty_B", //transaction ID in connectFi
"cardId": "crda_5Mx3p6lSIQevd0qwfFhhSs" //card ID in connectFi
}
}
}
400 (HTTP response status code) -- Transaction already reversed
In this example, a request to reverse a transaction that had already been successfully reversed was attempted.
{
"code": "extCondor",
"subCode": "T0010",
"context": {
"title": "cardsTransactionReversal"
},
"message": "Transaction already reversed."
}
400 (HTTP response status code) -- Insufficient funds
In this example, a reversal was attempted that would result in a negative available balance after the transaction reversal. This resulted in an error because the transaction was not allowed. Insufficient funds were available to complete the reversal.
{
"code": "extCondor",
"subCode": "T0005",
"context": {
"title": "cardsTransactionReversal"
},
"message": "MoneyGram POS Money Load Decline (MoneyGram POS Money Load Service is Not Allowed)"
}
400 (HTTP response status code) -- Reversal Decline (Inactive Card)
In this example, a request to reverse a transaction for a debit card with a status of "BLOCK" was attempted.
{
"code": "extCondor",
"subCode": "T0005",
"context": {
"title": "cardsTransactionReversal"
},
"message": "Reversal Decline (Inactive Card)"
}
400 (HTTP response status code) -- Reveral Decline (Suspected Fraud Hit, Card is Already Blocked)
In this example, a request to reverse a transaction for a debit card with a status of "FRAUD_BLOCK" was attempted.
{
"code": "extCondor",
"subCode": "T0005",
"context": {
"title": "cardsTransactionReversal"
},
"message": "Reversal Decline (Suspected Fraud Hit, Card is Already Blocked)"
}
400 (HTTP response status code) -- Reversal Decline (Closed Card)
In this example, a request to reverse a transaction for a debit card with a status of "CLOSED" was attempted.
{
"code": "extCondor",
"subCode": "T0005",
"context": {
"title": "cardsTransactionReversal"
},
"message": "Reversal Decline (Closed Card)"
}
400 (HTTP response status code) -- Transaction not found
In this example, a reversal was requested on a transaction ID that does not exist in the connectFi system.
Common /condor Error Responses
400 (HTTP response status code) -- Customer not found (debit card customer)
In this example, a valid connectFi customerId was used, but the customer has not yet been initialized as a debit card customer. See Create a Debit Card and Checking Account.
{
"code": "condorCustomerNotFound",
"message": "Condor Customer Not Found customerId=csta-YbQeg60v7orvQFIYA7gKU"
}
400 (HTTP response status code) -- Customer not found (connectFi)
In this example, an invalid connectFi customerId was used.
{
"code": "aggregatorCustomerNotFound",
"context": {
"customerId": "csta-YbQeg60v7orvQFIYA7gKU1"
},
"message": "Customer not found"
}
400 (HTTP response status code) -- Card not found
In this example, an invalid cardId was used in the request body. The cardId does not exist.