FLEXBridge Transaction Service API Documentation

FLEXBridge FLEXBridge FLEXBridge Transaction Service API Documentation

Publication Date: July 2021 Version: 1.152 FLEX Release 8.04

1. Introduction to FLEXBridge Transaction Service API

The FLEXBridge Transaction Service API is a crucial component of FLEXBridge that facilitates financial transactions within the Flex system. It specifically enables transfers between account suffixes or across different member accounts, and check withdrawals from an individual’s account.

2. General API Information

FLEXBridge is built as a RESTful API. All requests to the API must include built-in authentication attached as HTTPS request headers. For details on adding authentication headers or computing a HASH before posting data, refer to the FLEX Core System documentation.

HTTPS POST body request data must be encoded in JSON data format. You can refer to the JSON specifications for more information on encoding objects.

3. Available FLEXBridge Transaction Service Functions

The following core functions are currently available through the FLEXBridge Transaction Service API:

  • Account Transfers
    • Transfers can be performed between a member’s own account suffixes or between different member accounts.
  • Check Withdrawal

For a detailed breakdown, this documentation includes sections on:

  • Account Transfers
  • Check Withdrawal Transaction
  • Object References
  • Transfer Fees (TSFee)
  • Transaction Response
  • Response Transaction Fees Information
  • Additional Information
  • Transaction Warnings
  • Transaction Errors
  • Transaction Comments
  • HTTPS 500 Error Messages

4. Revisions to Transaction Service Document

As of March 2021, important adjustments have been made to the document and API parameters:

  • The term “truncated” has been updated to “maximum” when referring to how the service API handles data fields with too many characters.
  • URL Header Parameter Corrections:
    • The workstationId (or workstationID) parameter has been corrected to workstation.
    • The tellerId parameter has been corrected to tellerID.
    • Crucial Note: Sending the old parameter names will nullify the parameter and value, potentially leading to request errors if the value is required. Always use the new parameter names.

5. Account Transfers

This service function allows the transfer of funds either between an individual’s account suffixes or between different member accounts (also known as cross-account transfers).

5.1. Transaction Fees for Transfers

FLEX recommends consulting with the credit union to determine if any transaction fees are charged.

  • Transaction fees only apply to the amount being debited from the “fromSuffix”.
  • To charge a Transaction fee, the “acceptFees” attribute must be sent with a value of true in the request.
  • To determine if a “fromSuffix” will be subject to a fee for the transfer transaction:
    • Set the “acceptFees” and “acceptWarnings” attributes to false.
    • Set the “calculateFee” attribute to true.
    • Possible fees include Excess Withdrawal, Minimum Balance, and Cash Advances Fees.
  • To charge modified fees, utilize the TSFee object and its attributes within the transaction request. When using the TSFee object:
    • Set the “acceptFees” and “acceptWarnings” attributes to true.
    • Set the “calculateFee” attribute to false.

5.2. Transaction Warnings for Transfers

Setting the “acceptWarnings” attribute to true overrides any transaction warnings. However, this does not guarantee a successful transaction request. If a transaction fails, refer to the “Transaction Response” sections (specifically “Errors” and “Comments”) to understand the reason for failure. Warnings might prevent a transfer without proper acknowledgment but can be bypassed. FLEX advises checking with the credit union to determine which warnings should or should not be ignored.

5.3. URL Request for an Immediate Transfer Transaction

  • Function Request Type: transfer
  • Method: POST
  • REST URL: https://{URL_ADDRESS}/api/transfer/immediate?tellerID={TELLER_ID}&workstation={WORKSTATION_ID}

URL Parameters:

  • immediate: Indicates that the transfer will immediately affect an individual’s account.
  • tellerID:
    • Description: The Teller ID associated with the transfer.
    • Recommendation: FLEX suggests assigning a specified Teller ID to every transaction.
    • Maximum Characters: 4.
  • workstation:
    • Description: The Workstation ID for a transfer.
    • Configuration: Depending on credit union preference, it may be configured as the same workstation value for all transactions.
    • Recommendation: FLEX suggests including a Workstation ID in all transaction requests.
    • Maximum Characters: 10.

Examples of Immediate Transfer Requests:

  • Example 1 URL: https://example.com/api/transfer/immediate?tellerID=77&workstation=ASANCHEZ
  • Example 2 URL: https://example.com/api/transfer/immediate?tellerID=123&workstation=QA
  • Example 3 URL: https://example.com/api/transfer/immediate?tellerID=123&workstation=MAINBRCH1

5.4. Account Transfer JSON Body Attributes

The JSON body for an Account Transfer request contains the following attributes:

Attribute Type Description Required Default Value
fromAccount Number Account number used to debit funds for the transfer (maximum 9 characters) Required
fromSuffix Number Suffix used to debit funds for the transfer (maximum 3 characters) Required
fromTranDescription String Transfer transaction history description on the account sending funds (maximum 45 characters) Optional
toAccount Number Account number receiving funds from the transfer (maximum 9 characters) Required
toSuffix Number Account suffix receiving funds from transfer (maximum 3 characters) Required
toTranDescription String Transfer transaction history description from the account receiving funds (maximum 45 characters) Optional
transactionAmount Number Amount of transaction (maximum 9 characters) Required
acceptFees Boolean Indicates whether a transaction will assess a fee Required false
calculateFee Boolean Indicates if a transaction needs to calculate a fee. If true, the response will return if there will be a fee. When true, the transactionFeeList object should not be sent. Optional false
acceptWarnings Boolean Indicates whether a transaction will disregard system warnings. If true, the transfer will occur regardless of warnings. Required true
principleOnlyPayment Boolean Only used with loan payment transactions and indicates if the payment will include interest. Optional false
regDTransfer Boolean Indicates if the transfer counts toward Regulation D. Optional
allowSuffixBalanceToGoNegative Boolean Indicates if the transfer is allowed to take a share suffix negative. Optional false
creditCardAdjustment Boolean Indicates if a transfer will be a balance adjustment or go toward the required payment for a credit card. Optional false
transactionFeeList transactionFeeList Object Object and attributes used to post a manual fee for a transaction. Optional

Example Account Transfer JSON Bodies:

  • Example 1:

{

  “fromAccount”:12345,

  “fromSuffix”:1,

  “fromTranDescription”:”Trans. to 12345-15″,

  “toAccount”:12345,

  “toSuffix”:15,

  “toTranDescription”:”Trans from 12345-1″,

  “transactionAmount”:125.00,

  “acceptFees”: false,

  “acceptWarnings”: true,

  “calculateFee”: false,

  “transactionFeeList”: [

    {

      “amout”:5.00,

      “description”:”Fee Description”,

      “glAccountNumber”:11101

    }

  ]

}


  • Example 2:

{

  “fromAccount”:12345,

  “fromSuffix”:1,

  “fromTranDescription”:”Trans. to 12345-15″,

  “toAccount”:12345,

  “toSuffix”:601,

  “toTranDescription”:”Trans from 12345-1″,

  “transactionAmount”:525.00,

  “acceptFees”: false,

  “acceptWarnings”: false,

  “principleOnlyPayment”: false

}


  • Example 3 (demonstrates calculateFee: true):

{

  “fromAccount”:12345,

  “fromSuffix”:1,

  “fromTranDescription”:”Trans. to 12345-15″,

  “toAccount”:12345,

  “toSuffix”:15,

  “toTranDescription”:”Trans from 12345-1″,

  “transactionAmount”:125.00,

  “regDTransfer”: false,

  “acceptFees”: true,

  “acceptWarnings”: false,

  “calculateFee”: true

}

5.5. Response for a Transfer Transaction

The transfer response lists all comments, errors, fees, and warnings associated with a transaction, regardless of success. Even successful transactions may list messages in the warnings and comments sections.

Response Attributes:

Attribute Type Description
success Boolean Indicates whether a transaction was successful or not.
transactionResponse transactionResponse Service response list, including any comments, errors, fees, or warnings associated with the transaction.
referenceNumber Number Unique transaction reference number, assigned by FLEX for each transaction.

transactionResponse Object Attributes:

Attribute Type Description
comments List List of comments/notes for the transaction.
warnings List Warnings regarding the transaction. Warning messages still display even if acceptWarnings is true.
errors List Transaction errors that occurred, preventing the transaction from being successful.
fees List Lists any fee that applies to the “fromSuffix” during a transaction. Fees will not occur unless acceptFees is true.
fromSuffixInfo fromSuffixInfo Account suffix debited for the transaction funds.
toSuffixInfo toSuffixInfo Account suffix credited for the transaction. Only populates information when a cross-account transfer occurs.
referenceNumber Number Unique transaction reference number, assigned by FLEX for each transaction.

fromSuffixInfo Object Attributes:

Attribute Type Description
accountNumber Number Account number debited for a transaction.
suffix Number Account suffix number debited for a transaction.
currentBalance Number Current balance of the suffix.
availableBalance Number Available balance of the suffix.

toSuffixInfo Object Attributes:

Attribute Type Description
accountNumber Number Account number credited for a transaction.
suffix Number Account suffix number credited for the transaction.
currentBalance Number Current balance of the suffix.

Example Transfer Response (Successful):

{

    “success”: true,

    “transactionResponse”: {

        “fees”: [],

        “warnings”: [

            “Delinquent loans exist for account 1599″,

            “This Loan Is Paid Via Payment method (C) not defined”

        ],

        “errors”: [],

        “comments”: [

            “Transaction completed successfully”,

            “Transaction warnings were ignored”

        ],

        “fromSuffixInfo”: {

            “accountNumber”: 1599,

            “suffix”: 1,

            “currentBalance”: 41751.44,

            “availableBalance”: 41701.44

        },

        “toSuffixInfo”: {

            “accountNumber”: 89891,

            “suffix”: 602,

            “currentBalance”: 12345.06

        },

        “referenceNumber”: 3264

    }

}

Example Transfer Response when “calculateFees” is set to true:

{

    “fees”: [

        {

            “amount”: 1.25,

            “description”: “Tran Fee”,

            “glAccountNumber”: 11101

        }

    ],

    “warnings”: [

        “Delinquent loans exist for account 259800″

    ],

    “errors”: [],

    “comments”: [

        “Transaction completed successfully”,

        “Transaction warnings were ignored”,

        “Transaction fees were processed”

    ],

    “fromSuffixInfo”: {

        “accountNumber”: 259800,

        “suffix”: 1,

        “currentBalance”: 8345.83,

        “availableBalance”: 3398.34

    },

    “toSuffixInfo”: {

        “accountNumber”: 259800,

        “suffix”: 9,

        “currentBalance”: 118867.00,

        “availableBalance”: 114466.0

    },

    “referenceNumber”: 889

}

6. Check Withdrawal Transaction

This service function debits a member’s account for a Check Withdrawal.

6.1. Withdrawal Transaction Fees

FLEX recommends speaking with the credit union to determine if any withdrawal transaction fees are charged. If fees apply, refer to the “Transaction Fee” section under Account Transfers for details on how to handle them.

6.2. Request for a Check Withdrawal

  • Function Request Type: checkwithdrawal
  • Method: POST
  • RESTful URL: https://{URL_ADDRESS}/api/checkwithdrawal/immediate?tellerID={TELLER_ID}&workstation={WORKSTATION_ID}

URL Parameters:

  • immediate: Indicates that the transfer will immediately affect an individual’s account.
  • tellerID:
    • Description: Teller ID associated with the transfer.
    • Recommendation: FLEX suggests every transaction is assigned a specified Teller ID.
    • Maximum Characters: 4.
  • workstation:
    • Description: Workstation ID for a transfer.
    • Configuration: Depending on credit union preference, it may be configured as the same workstation value for all transactions.
    • Recommendation: FLEX suggests all transaction requests include a Workstation ID.
    • Maximum Characters: 10.

Example Request URL: https://10.5.15.68/api/checkwithdrawal/immediate?tellerID=77&workstation=QP

6.3. Check Withdrawal JSON Body Attributes

The JSON body for a Check Withdrawal request contains the following attributes:

Attribute Type Description Required Default Value
fromAccount Number Account number used to debit funds for the check withdrawal (maximum 9 characters) Required
fromSuffix Number Suffix used to debit funds for the check withdrawal (maximum 3 characters) Required
fromTranDescription String Check withdrawal history description (maximum 45 characters) Optional
transactionAmount Number Amount to transfer (maximum 9 characters) Required
acceptFees Boolean Indicates whether a transaction will assess a fee Required false
acceptWarnings Boolean Indicates whether a transaction will disregard system warnings. If true, the transfer will occur regardless of the warning. Required true
calculateFee Boolean Indicates if a transaction needs to calculate a fee. If true, the response will return if there will be a fee. When true, the transactionFeeList object should not be sent. Optional false

Example Check Withdrawal JSON Body:

{

  “fromAccount”:89891,

  “fromSuffix”:201,

  “fromTranDescription”:”Cash Advance”,

  “transactionAmount”:500.00,

  “acceptFees”: true,

  “acceptWarnings”: true,

  “calculateFee”: false

}

6.4. Response for Check Withdrawal Transaction

The response attributes are similar to the Account Transfer Response.

Example Response of a Check Withdrawal Transaction:

{

    “success”: true,

    “transactionResponse”: {

        “warnings”: [

            “Delinquent loans exist for account 89891″

        ],

        “errors”: [],

        “comments”: [

            “Check withdrawal completed successfully”,

            “Transaction warnings were ignored”

        ],

        “fromSuffixInfo”: {

            “accountNumber”: 89891,

            “suffix”: 201,

            “currentBalance”: 79492.02,

            “availableBalance”: 78683.02

        },

        “toSuffixInfo”: {

            “accountNumber”: 0,

            “suffix”: 0

        },

        “referenceNumber”: 3265

    }

}

7. Transfer Fees (TSFee) Object

The transactionFeeList object is used to post a manual fee for a transaction. It is part of the TSFee attributes.

transactionFeeList Attributes:

Attribute Type Description
amount Number Amount of fee (maximum 9 characters).
description String Description used for charging the fee (maximum 16 characters).
glAccountNumber Number General Ledger account to which the fee is transferred (maximum 9 characters).

Example transactionFeeList Structure:

“transactionFeeList”: [

  {

    “amount”:5.00,

    “description”:”Fee Description”,

    “glAccountNumber”:11101

  }

]

8. Response Transaction Fees Information

The fees object will populate in the transaction response when the “calculateFees” attribute equals true in the request. Any calculated fee will be included in the response, applying to the debit suffix or the value listed in the “fromSuffix” attribute.

Example fees object structure in a response:

“fees”: [

  {

    “amount”:5.00,

    “description”:”Fee Description”,

    “glAccountNumber”:11101

  }

]

9. Additional Information and Attribute Interactions

Understanding the interaction between calculateFee, acceptFees, and transactionFeeList is critical:

  • If calculateFee is true AND acceptFees is true: The request will automatically post the transaction unless an error occurs.
  • If acceptFees is false BUT transactionFeeList is included: The service will generate an error: “Accept Fee is false and Transaction Fee List is not empty.”.
  • If calculateFee is true AND transactionFeeList is included: The service will generate an error: “Calculate Fee is true, and Transaction Fee List is not empty.”.
    • NOTE: When submitting a request, use either calculateFee or transactionFeeList, but not both together.
  • If using transactionFeeList to charge a fee: Ensure acceptFees and acceptWarnings are both true to ensure a successful transaction. The service will bypass warnings, but a transaction can still be unsuccessful; additional information on failure will be provided.
  • If using calculateFee to retrieve possible fees:
    • Set calculateFee to true.
    • Set acceptFees and acceptWarnings to false. This will prevent the transaction from posting to the account.
    • The response will contain any calculated fees and warnings/errors that might cause the transaction to fail to post.
  • If acceptFees is false AND calculateFee is true:
    • The service will return any applicable fees and warnings.
    • This provides a method of validation before posting, allowing fees to be waived or modified.
    • For the second request (after validation):
      • Set acceptFees to true.
      • Set acceptWarnings to true.
      • Set calculateFees to false.
      • If a modified fee amount is required, send the transactionFeeList in the request with the desired fee amount.

10. Transaction Warnings

Warnings generally indicate conditions that might prevent a transfer without proper acknowledgment. They can be bypassed by setting the “acceptWarnings” attribute to true. However, FLEX recommends checking with the credit union to determine which warnings should or should not be ignored.

Common Transaction Warnings:

  • No interest will be collected for this payment. Interest income will be lost because interest for the period due has not yet been calculated.
  • Bad address exists on account.
  • This transaction will take the balance below the minimum required balance.
  • This advance is less than the required minimum disbursement for loan suffix.
  • Delinquent loans exist for account.
  • LoanCreditLimitExceededWarning.java.
  • This Loan Is Paid Via Automatic Transfer.
  • This Loan Is Paid Via Payroll.
  • This Loan Is Paid Via ACH.
  • Payment method (value) not defined.
  • Reg D Transfer Limit Exceeded.

11. Transaction Errors

Errors will prevent a transfer from occurring and cannot be overridden. Some errors can be resolved by adjusting the transaction account, while others require the credit union to make adjustments to the member’s account.

Common Transaction Errors:

  • Cannot draw from loan after draw expiration date.
  • Teller not authorized to perform transactions when loans are delinquent.
  • Teller is not authorized to exceed credit limit.
  • Teller is not authorized to transact on suffix group.
  • Teller is not authorized to transact on suffix type.
  • Teller not authorized to perform transactions on an account with a bad address.
  • Transaction amount exceeds available shares.
  • Balance after transaction greater than maximum allowed.
  • Payment amount cannot exceed loan payoff balance.
  • Amortized loan payment must not be less than the loan payment amount.
  • Amortized loan payment must not be less than the scheduled payment amount.
  • Amount is less than share $share maximum withdrawal of $amount.
  • Amount is less than share $share minimum withdrawal of $amount.
  • Amount is less than share $share maximum deposit of $amount.
  • Amount is less than share $share minimum deposit of $amount.
  • Transaction amount greater than the maximum allowed for teller.
  • Teller is not authorized to override the HELOC cash advance maximum limit.
  • Teller is not authorized to override the HELOC monthly limit.
  • Transaction amount greater than the maximum allowed for teller.

12. Transaction Comments

Comments provide informational status updates regarding a transfer and do not affect the transfer process.

Common Transaction Comments:

  • Transaction completed successfully.
  • Transaction warnings were ignored.
  • Transaction Declined.
  • Transaction fees were processed.
  • Check withdrawal completed successfully.

13. HTTPS 500 Error Messages

FLEX has added additional information to the 500 HTTP Status Code errors within API Service responses to assist with troubleshooting. Once an error or issue is corrected, the request can be resent for processing.

Key Points for 500 Errors:

  • Most service errors occur due to invalid attribute values or values not present in the credit union’s database configuration.
  • Some errors are triggered by preset conditions to ensure data integrity and accuracy.
  • Recommendation: FLEX recommends providing the error message to the credit union to aid in troubleshooting issues.

A few common 500 Error Messages:

  • “message”: “Internal server error – To Suffix is closed or frozen”
  • “message”: “Internal server error – From Suffix is closed or frozen”
  • “message”: “Internal server error – From Account/Suffix not valid”
  • “message”: “Internal server error – To Account/Suffix not valid”
  • “message”: “Internal server error – No Fees\nWarnings: \nDelinquent loans exist for account 89891\nErrors: \nAmount is less than share 4 minimum deposit of 250\nComments: \nTransaction declined”
  • “message”: “Internal server error – No Fees\nWarnings: \nDelinquent loans exist for account 89891\nErrors: \nAmount is less than share 270 minimum withdrawal of 500\nComments: \nTransaction declined”
  • “message”: “Internal server error – No Fees\nWarnings: \nDelinquent loans exist for account 1599\nThis Loan Is Paid Via Payment method (C) not defined\nErrors: \nAmount is less than share 270 minimum withdrawal of 500\nComments: \nTransaction declined”
  • “message”: “Internal server error – Teller Id 9904 is not valid”