FLEXBridge Card Processing API Documentation

FLEXBridge FLEXBridge FLEXBridge Card Processing API Documentation

This document provides comprehensive technical documentation for the FLEXBridge Card Processing API. This API serves as a vital utility for credit union staff, offering programmatic access to a segment of the FLEX system database that contains essential debit and credit card information.

The Card Processing API is designed to help users:

  • Acquire card data.
  • Extract relevant card information.
  • Disseminate card details.
  • Maintain or modify certain data elements as outlined in this documentation.

API Overview

The FLEXBridge Card Processing API is a RESTful API. It requires built-in authentication that must be attached to every request as HTTPS request headers. For detailed information on how to add authentication headers, please consult the FLEX Core System documentation.

This API is available for FLEX Releases 8.04 and up, with API Version 1.29 and up.

Key FLEXBridge Card Processing API Functions

The following core functions are currently available through the FLEXBridge Card Processing API:

  • Search for a card by account or card number.
  • Add a new card.
  • Update an existing card.

Revisions to the Card Processing API

This section details significant updates and adjustments made to the Card Processing API attributes.

Updates as of September 2022

The following attribute names were modified to reflect the valid attributes returned in response data or when adding a card:

  • currentExpirationDate modified to currentExpireDate.
  • lastExpirationDate modified to lastExpireDate.
  • pendingExpirationDate modified to pendingExpireDate.
  • lastIssueProcessor modified to lastIssProcessor.
  • lastInstantIssuueSuccess modified to lastInstIssSuccess.
  • pendingIssueProcessor modified to pendingIssProcessor.
  • nextCardActivationCode modified to nextCardActiveCode.
  • crossReferenceNumber modified to xrefNumber.
  • pinReferenceNumber modified to pinReferenceNum.
  • photoReferenceNumberName modified to photoRefNumName.

Implementation Timeline for September 2022 Changes:

  • These changes should be implemented with any new integration starting on or after October 1, 2022.
  • FLEXBridge will continue to accept the previous attribute names in card exports until they are phased out of the FLEXBridge services on July 1, 2024.

Updates as of March 2022

The same attribute name modifications mentioned above were also documented as updates as of March 2022:

  • currentExpirationDate modified to currentExpireDate.
  • lastExpirationDate modified to lastExpireDate.
  • pendingExpirationDate modified to pendingExpireDate.
  • lastIssueProcessor modified to lastIssProcessor.
  • lastInstantIssuueSuccess modified to lastInstIssSuccess.
  • pendingIssueProcessor modified to pendingIssProcessor.
  • nextCardActivationCode modified to nextCardActiveCode.
  • crossReferenceNumber modified to xrefNumber.
  • pinReferenceNumber modified to pinReferenceNum.
  • photoReferenceNumberName modified to photoRefNumName.

Removed Items as of March 2022:

  • The attribute nextExpirationDate was removed under the pendingIssueInfo object because it is not a valid attribute for the Card Processing service.

Updates as of June 2021

  • The word “truncated” was adjusted to “maximum” to correspond with how the service API handles data fields with too many characters.
  • All attribute date formats were changed from CCYY-MM-DD to MM/DD/CCYY. This standardization affects the following attributes:
    • openDate
    • lastDateAmountUsed
    • photoDate
    • lastIssueDate
    • blockDate
    • currentReclassDate
    • captureRequestDate
    • actualCaptureDate

Card Processing Search

This function retrieves a list of cards and their associated information, which can then be used to update a card. The service provides two primary search functions:

  • Search by Account Number
  • Search by Card Number

Request Details:

  • Method: GET
  • REST URL: https://{BASE_URL}/api/cardprocessing/search/{SEARCH_TYPE}?query={QUERY_STRING}
  • Parameters:
    • {SEARCH_TYPE}:
      • Type: String
      • Description: Specific type of search performed.
      • Possible Values: accountnumber, cardnumber, or thirdpartycard.
      • Required: Yes.
      • Note: To search for all cards associated with an individual’s account, use the SEARCH_TYPE value accountnumber.
    • {QUERY_STRING}:
      • Type: String
      • Description: The account or card number used to retrieve information based on the search type request.
      • Required: Yes.

Examples of Card Processing Searches:

  • By Card Number: https://101.88.101.17/api/cardprocessing/search/cardnumber?query=1234567890123456
  • By Account Number: https://192.51.10.09/api/cardprocessing/search/accountnumber?query=123456789
  • By Third-Party Account Number: https://192.51.10.09/api/cardprocessing/search/thirdparty/accountnumber?query=123456789

Response:

  • Name: cards
  • Type: cards List
  • Description: A list of card detail information.

Adding a New Card

The process for adding a new card requires an existing member account number.

Steps to Add a New Card:

  1. Retrieve Default Settings: Use the GET method populatedefaults to retrieve the default settings for a specified card type.
  2. Verify and Adjust Attributes: Ensure all required attributes are populated and make any necessary data adjustments before posting the card.
  3. Add the Card: Use the POST method addcard to complete the process and add the card to the member’s account.

Important Note:

  • The maximum length of the member’s name (first, middle, and last names combined) that can be embossed on a card is 21 characters.
  • The member’s name is required when adding a card.

Request for populatedefaults

  • Method: GET 
  • REST URL: https://{BASE_URL}/api/cardprocessing/populatedefaults/accountnumber/{ACCOUNT_NUMBER}/cardtype/{CARD_TYPE} 
  • Parameters: 
    • {ACCOUNT_NUMBER}:
      • Type: String
      • Description: Specify the account number of the individual.
    • {CARD_TYPE}:
      • Type: String
      • Description: Specify the card type (credit union defined) to be used in populating the credit union’s card defaults.
  • Example Request: https:/101.51.26.19/api/cardprocessing/populatedefaults/accountNumber/123456789/cardtype/DB 
  • Response for populatedefaults: 
    • Name: cardDetailDefaults
    • Type: cardDetailDefaults object
    • Description: A list of card information, based on the credit union’s current card type configuration.

Request for addcard

  • Method: POST 
  • REST URL: https://{BASE_URL}/api/cardprocessing/addcard?tellerID={TELLER_ID}workstation={WORKSTATION_ID} 
  • Parameters (Optional): 
    • {TELLER_ID}:
      • Type: String
      • Description: Teller ID involved in adding a card.
    • {WORKSTATION_ID}:
      • Type: String
      • Description: Workstation ID involved in adding a card.
  • Example Request: https://101.168.59.17/api/cardprocessing/addcard?tellerID=78AD&workstation=QP 
  • Example JSON Body for Adding a New Card: 

{

  “accountNumber”: 89891,

  “plasticNumber”: 0,

  “cardType”: “AT”,

  “openDate”: “12/28/2018”,

  “cardStyleCode”: “”,

  “lastIssueInfo”: {

    “lastIssueOption”: “C”,

    “lastExpireDate”: 0

  },

  “pendingIssueInfo”: {

    “nextIssueOption”: “C”,

    “pendingExpireDate”: 0

  },

  “currentExpireDate”: 1710,

  “cardHolders”: [

    {

      “firstNameCard”: “PAUL”,

      “middleInitCard”: “J”,

      “lastNameCard”: “WALKER”,

      “numberToIssueName”: 1

    }

  ],

  “incorrectPinCount”: 0,

  “feesActive”: “Y”,

  “xrefNumber”: 0,

  “participationCode”: “”,

  “cardLimit”: {

    “dailyLimitWD”: 0,

    “dailyLimitATM”: 0,

    “dailyLimitPOS”: 0

  },

  “cardNotes”: [

    {

      “noteField”: “Note Line 1″

    },

    {

      “noteField”: “Note Line 2″

    }

  ],

  “cardFundingSuffixes”: [

    {

      “classSuffix”: 1,

      “classType”: “SAV”,

      “classRestrict”: “”

    },

    {

      “classSuffix”: 11,

      “classType”: “CHK”,

      “classRestrict”: “”

    },

    {

      “classSuffix”: 201,

      “classType”: “VSA”,

      “classRestrict”: “”

    }

  ]

}


  • Note: cardLimit attributes will default to zero unless different limits are specified for an individual member. The FLEX system will populate the credit union’s configured limit settings when adding a new card. 
  • Response for addcard: 
    • Attribute: cardnumber
    • Type: Number
    • Description: The card number is returned upon a successful request. If the request fails, an exception error is sent as the response.
    • Sample Response: {“cardnumber”: 64164900000350487}

Updating Card Information

When updating card information, the member’s card number is a required parameter.

Important Note:

  • Only attributes being changed should be submitted in the request.

Request for updatecard

  • Method: PATCH 
  • REST URL: https://{BASE_URL}/api/cardprocessing/updatecard/cardnumber/{CARD_NUMBER}?tellerID={TELLER_ID}&workstation={WORKSTATION_ID} 
  • Parameters: 
    • {CARD_NUMBER}:
      • Type: String
      • Description: Indicates the card number to be updated.
      • Required: Yes.
    • {TELLER_ID}:
      • Type: String
      • Description: User or Teller ID involved in the update.
      • Required: Optional.
    • {WORKSTATION_ID}:
      • Type: String
      • Description: Workstation ID involved in the update.
      • Required: Optional.
  • Example JSON Body for Updating a Single Card Attribute: 
    • Example Request: https://101.10.101.12/api/cardprocessing/updatecard/cardnumber/1234567891234567?tellerID=78AD&workstation=QP

[

  {

    “op”: “replace”,

    “path”: “/lastIssueInfo/lastIssueDate”,

    “value”: “09/07/2018”

  }

]


  • Example JSON Body for Updating Multiple Card Attributes: 

    • Example Request: https://101.56.26.19/api/cardprocessing/updatecard/cardnumber/1234567891234567?tellerID=78AD&workstation=QP

[

  {

    “op”: “replace”,

    “path”: “/blockInfo/blockDate”,

    “value”: “09/07/2018”

  },

  {

    “op”: “replace”,

    “path”: “/blockInfo/blockCode”,

    “value”: “L”

  },

  {

    “op”: “replace”,

    “path”: “/cardNotes/0/noteField”,

    “value”: “test this is a”

  },

  {

    “op”: “replace”,

    “path”: “/cardNotes/1/noteField”,

    “value”: “test”

  }

]

Response for updatecard

  • Name: success
  • Type: Boolean
  • Description: Indicates if the request was successful. An exception will occur if there was an error.
  • Sample Response: {“success”: true}

Object Types

This section details the various object types and their attributes used within the Card Processing API.

1. Cards Detail Information (cards)

This object represents comprehensive information about a card.

Key Attributes:

  • accountNumber:
    • Type: Number
    • Description: Base account number (maximum 9 characters).
    • Required: Yes.
  • cardNumber:
    • Type: Number
    • Description: Card Number to be added or updated (maximum 22 characters).
    • Required: Optional.
  • plasticNumber:
    • Type: Number
    • Description: Card sequence number, used if the same card number is in use (rarely used, maximum 1 character).
    • Required: Optional (default = 0).
  • cardType:
    • Type: String
    • Description: Card type code (credit union defined), e.g., (DB) = Debit Card or (VS) = Visa Card (maximum 2 characters).
    • Required: Yes.
  • openDate:
    • Type: Date
    • Description: Date card was opened (format: MM/DD/CCYY).
    • Required: Yes.
  • blockInfo:
    • Type: List
    • Description: Card block and reclassification information.
    • Required: Optional.
  • cardLimit:
    • Type: List
    • Description: Daily card limits and usage.
    • Required: Optional.
  • cardStyleCode:
    • Type: String
    • Description: Gallery design image number set at bin level (maximum 10 characters).
    • Required: Optional.
  • lastIssueInfo:
    • Type: List
    • Description: Information regarding the last issue of the card.
    • Required: Optional.
  • pendingIssueInfo:
    • Type: List
    • Description: Information on pending issues of the card.
    • Required: Optional.
  • currentExpireDate:
    • Type: Number
    • Description: The current expiration date of the card (formatted as YYMM). Interchangeable with lastExpireDate. FLEX advises setting this when adding a new card and leaving lastExpireDate blank.
    • Required: Yes.
  • activationCode:
    • Type: String
    • Description: Card activation code (not normally used, maximum 1 character).
    • Required: Optional.
  • cardHolders:
    • Type: List
    • Description: List of cardholder’s information.
    • Required: Yes.
  • pinOffset:
    • Type: Number
    • Description: PIN offset. Should always be “0000” when adding a new card (maximum 4 characters).
    • Required: Yes.
  • pinReferenceNum:
    • Type: Number
    • Description: PIN reference number (credit union defined, maximum 22 characters).
    • Required: Optional.
  • incorrectPinCount:
    • Type: Number
    • Description: Number of incorrect PIN tries on a daily basis (rarely used, requires authorization).
    • Required: Optional.
  • cardFundingSuffixes:
    • Type: List
    • Description: List of card funding suffixes (credit union defined).
    • Required: Yes.
  • feesActive:
    • Type: String
    • Description: Indicates if fees will be charged for this card. Valid Options: (Y) = Yes or (N) = No (maximum 1 character).
    • Required: Yes (default = Y).
  • xrefNumber:
    • Type: Number
    • Description: Cross Reference number from prior conversion (not used for new cards, maximum 22 characters).
    • Required: Optional.
  • participationCode:
    • Type: String
    • Description: Indicates if the individual is enrolled in a rewards program. Valid Options: (Y) = Yes or (N) = No (maximum 1 character).
    • Required: Yes (default = N).
  • cardNotes:
    • Type: List
    • Description: List of card notes.
    • Required: Optional.
  • cardTeller:
    • Type: String
    • Description: Identifies the teller requesting the add or update on a card, as defined by the credit union (maximum 4 characters).
    • Required: Yes.

2. Card Detail Defaults (cardDetailDefaults)

This object provides default card information based on the credit union’s current card type configuration.

Key Attributes:

  • accountNumber: Number, Base account number (Required).
  • plasticNumber: Number, Card sequence number (rarely used). Default to zero (Optional, default = 0).
  • cardType: String, Card type code (credit union defined), e.g., (DB) = Debit Card or (VS) = Visa Card (maximum 2 characters) (Required).
  • openDate: Date, Date card was opened (format: MM/DD/CCYY) (Required).
  • cardStyleCode: String, Gallery design image number set at bin level (maximum 10 characters) (Optional).
  • lastIssueInfo: List, Information regarding last issue of card (Optional).
  • pendingIssueInfo: List, Information on pending issue of card (Optional).
  • currentExpireDate: Number, Current expiration date (formatted YYMM). FLEX advises setting this when adding a new card and leaving lastExpireDate blank (Required).
  • cardHolders: List, List of cardholder’s information (Required).
  • incorrectPinCount: Number, Number of incorrect PIN tries on a daily basis (rarely used, requires authorization) (Optional).
  • feesActive: String, Indicates if fees will be charged. Valid Options: (Y) = Yes or (N) = No (maximum 1 character) (Required, default = Y).
  • xrefNumber: Number, Cross Reference number from prior conversion (not used for new cards) (Optional).
  • participationCode: String, Indicates if enrolled in rewards program. Valid Options: (Y) = Yes or (N) = No (maximum 1 character) (Required, default = N).

3. Last Issue Information (lastIssueInfo)

This object contains details about the last issuance of a card.

Key Attributes:

  • lastIssueCase: String, Credit union specific case (maximum 1 character) (Optional).
  • lastIssProcessor: String, Credit union specific processor (maximum 2 characters) (Optional).
  • lastInstIssSuccess: String, Last instant issue success (maximum 1 character) (Optional).
  • lastIssueFormat: String, Format of file issued (FLEX defined, maximum 1 character) (Optional).
  • lastIssueOption: String, Last chosen renewal of card type. Valid Options: (C) = Card, (P) = Pin, or (B) = Both (maximum 1 character) (Optional, default = C).
  • lastInstantResponse: String, Last instant response (maximum 10 characters) (Optional).
  • lastIssueDate: Date, Date of last card issue (format: MM/DD/CCYY) (Optional).
  • lastExpireDate: Number, Used to change the current expiration date (format: YYMM). If blank, currentExpireDate remains unchanged. FLEX advises leaving this blank if currentExpireDate is valid; otherwise, use this attribute. (Optional).

4. Pending Issue Information (pendingIssueInfo)

This object provides information on a card’s pending issuance.

Key Attributes:

  • nextIssueOption: String, Next issue option. Valid Options: (C) = Card, (P) = Pin, or (B) = Both (maximum 1 character) (Optional, default = C).
  • nextCardActiveCode: String, Next card activation code (not normally used). Valid Options: (Y) = Yes or (N) = No or leave blank (maximum 1 character) (Optional, default = blank).
  • pendingIssueCase: String, Credit Union specific pending issue case (maximum 1 character) (Required).
  • pendingIssProcessor: String, Credit union specific pending issue processor (maximum 2 characters) (Optional).
  • pendingIssueFormat: String, Pending issue format (maximum 1 character) (Optional).
  • pendingIssueOption: String, Pending issue option. Valid Options: (C) = Card, (P) = Pin, or (B) = Both (maximum 1 character) (Optional, default = C).
  • pendingExpireDate: Number, Pending expiration date (format: YYMM) (Required).
  • pendingCardActive: String, Pending card activation code (not typically used, maximum 1 character) (Optional).
  • rushCode: String, Rush Code. Valid Options: (Y) = Yes or (N) = No (maximum 1 character) (Required, default = N).

5. Block Information (blockInfo)

This object details a card’s block status.

Key Attributes:

  • blockCode: String, Block codes (credit union defined). Valid Options: (N) = Null, (A) = Active, (L) = Lost, or (S) = Stolen (maximum 1 character) (Optional, default = blank).
  • blockDate: Date, Date of last card block (format: MM/DD/CCYY) (Optional).
  • currentReclassCode: String, Current reclassification code (Card Processor defined, maximum 1 character) (Optional).
  • currentReclassDate: Date, Current reclassification date (format: MM/DD/CCYY) (Optional).
  • captureRequestDate: Date, Date card was requested to be captured (format: MM/DD/CCYY) (Optional).
  • actualCaptureDate: Date, Date card was actually captured (format: MM/DD/CCYY) (Optional).

6. Card Limit Information (cardLimit)

This object specifies daily card limits and usage.

Key Attributes:

  • dailyLimitWD: Number, Daily limit for total transaction withdrawal (maximum 6 characters) (Optional, default = blank).
  • dailyLimitATM: Number, Daily limit for ATM use (maximum 6 characters) (Optional, default = blank).
  • dailyLimitPOS: Number, Daily limit for point of sale transaction (maximum 6 characters) (Optional, default = blank).
  • dailyAmountUsedWD: Number, Total amount of withdrawal used in the last 24-hour period (maximum 9 characters) (Optional).
  • dailyAmountUsedATM: Number, Total amount of ATM used in the last 24-hour period (maximum 9 characters) (Optional).
  • dailyAmountUsedPOS: Number, Total amount of point of sale used in the last 24-hour period (maximum 9 characters) (Optional).
  • lastDateAmountUsed: Date, Last date card was used for card limit calculation (format: DD/MM/CCYY) (Optional).

7. Card Holders Information (cardHolders)

This object contains a list of cardholder information.

Note: A member’s full name on a card is limited to 21 maximum characters for the first, middle, and last name combined, per Visa/Master Card Mandates for logos.

Key Attributes:

  • firstNameCard: String, First name on card (maximum 36 characters) (Required).
  • middleInitCard: String, Middle initial (maximum 1 character) (Required).
  • lastNameCard: String, Last name on card (maximum 36 characters) (Required).
  • numberToIssueName: Number, Number of cards issued to the name above (maximum 2 characters) (Required).
  • forceIssueName: String, Used for reissuing existing or damaged/replacement cards. Valid Options: (+) = Force Issue of Increase Expiration Date by 1 Month, (B) = Force Issue of Card and PIN, (C) = Force Issue of Card, (D) = Direct Issue, (F) = Force Issue of Increase Expiration Date by Full Frequency from Current Date, (I) = Force Issue of Increase Expiration Date by Reissue Frequency of Card Type, (M) = Force Issue of Card Using Manual PIN, or (P) = Force Issue of PIN (maximum 1 character). Leave blank when adding a card (Optional).
  • associationCode: String, Association code. Valid Options: (C) = Comaker, (J) = Joint Owner, (A) = Authorized Signer, blank for Primary Member (maximum 1 character) (Required, default = blank for primary).
  • photoRefNumName: String, Individual photo file number tied to card name (maximum 25 characters) (Optional).
  • photoDate: Date, Date of photo reference stored name (format: MM/DD/CCYY) (Optional).
  • pendingPhotoFee: String, Charge fee for a photo. Valid Options: (Y) = Yes or (N) = No (maximum 9 characters) (Optional).

8. Card Notes (cardNotes)

This object allows for notes associated with a card.

Key Attribute:

  • noteField: String, Allows for up to two lines, with a maximum of 20 characters per line (Optional).
  • Updating Notes Pathway (Method: PATCH):

[

  {

    “op”: “replace”,

    “path”: “/cardNotes/0/noteField”,

    “value”: “test this is a”

  },

  {

    “op”: “replace”,

    “path”: “/cardNotes/1/noteField”,

    “value”: “test”

  }

]

9. Card Funding Suffix (cardFundingSuffixes)

This object defines how a card is funded.

Key Attributes:

  • classSuffix: Number, Credit union defined funding suffix (maximum 4 characters) (Required).
  • classType: String, Card class type. Valid Options: (CHK) = Checking, (SAV) = Saving, (VSA) = Visa, (HAS) = Health Saving, (LOC) = Line of Credit, or (MMA) Money Market (maximum 3 characters) (Required).
  • classRestrict: String, Class restriction (rarely used, maximum 1 character) (Optional, default = blank).

HTTPS Status Code 500 Error Includes FLEX Validation Checks

FLEX has added additional information to 500 HTTP Status Code errors in the API Service responses to assist with troubleshooting.

  • The majority of errors through the service occur due to invalid attribute values or values that are not present in the credit union database configurations.
  • Some HTTPS messages are triggered by preset conditions to ensure data integrity and accuracy.
  • If an error occurs, it is recommended to provide the error message to the credit union first, as they are often familiar with the messages and how to correct the data without requiring FLEX or third-party aid.
  • Once the issue is corrected, the request should be attempted again.

Common Error Messages (Internal Server Error – java.lang.RuntimeException): These messages typically indicate data values that need correction before resubmitting a request.

  • {“message”: “Internal server error – java.lang.RuntimeException: noteField1 cannot exceed 20 characters”}
  • {“message”: “Internal server error – java.lang.RuntimeException: noteField2 cannot exceed 20 characters”}
  • {“message”: “Internal server error – java.lang.RuntimeException: blockCode cannot exceed 1 characters”}
  • {“message”: “Internal server error – java.lang.RuntimeException: lastIssueOption cannot exceed 1 characters”}
  • {“message”: “Internal server error – Card type ZZ is not valid”}
  • {“message”: “Internal server error – java.lang.RuntimeException: currentExpireDate cannot exceed total length of 4 with 0 decimals”}
  • {“message”: “Internal server error – java.lang.RuntimeException: middleInitialOnCard1 cannot exceed 1 characters”}
  • {“message”: “Internal server error – java.lang.RuntimeException: cardStyleCode cannot exceed 10 characters”}
  • {“message”: “Internal server error – java.lang.RuntimeException: dailyLimitWD cannot exceed total length of 5 with 0 decimals”}