FLEXBridge Stop Payment Service API
1. Introduction and Overview
The Checking Service API (Version 1.47 FLEX Release: 8.04) is a vital part of the FLEXBridge System. Its primary function is to manage Check Stop Payments for member accounts, encompassing both the retrieval of existing stop payments and the creation of new ones. This documentation provides details on all data elements and their definitions related to Check Stop Payments.
2. FLEXBridge API Fundamentals
The FLEXBridge API operates on several key principles:
- RESTful Design: FLEXBridge is a RESTful API.
- Authentication: Every request must include built-in authentication attached as HTTPS request headers. For specific instructions on adding these headers, refer to the FLEX Core System documentation.
- Data Format: All data exchanged with the API, both sent and returned, is processed in JSON format.
3. Available Functions
The Checking Service API offers the following core functionalities for managing check stop payments:
- Retrieve Stop Payment for an Account: This function allows users to fetch a list of existing stop payments associated with a particular account.
- Create a Stop Payment for an Account: This function enables users to establish a new stop payment for an account.
4. Key Revisions and Updates (as of 05.20.2020)
Important adjustments have been made to the API’s attributes and documentation:
- reason Attribute: This attribute now enforces a maximum length of 20 characters. Any value exceeding this limit will result in an error.
- amount Attribute Update: When creating a Stop Payment, the amount attribute has been updated and renamed to stopPaymentAmount.
- enteredDate Attribute Update: When creating a Stop Payment, the enteredDate attribute has been updated and renamed to startDate.
- releaseDate Attribute Update: When creating a Stop Payment, the releaseDate attribute has been updated and renamed to expirationDate.
- draftNumber Attribute Removal (from creation JSON): The draftNumber attribute has been removed from the JSON information required for creating a stop payment. It is now only returned as an attribute under the stoppedPayments object when retrieving stop payments.
5. Retrieving Check Stop Payments for an Account Suffix
This function is used to obtain a list of all stopped payments linked to a specific Member account.
- Method: GET
- REST URL: https://{BASE_URL}/account/{ACCOUNT_NUMBER}/stoppedpayments/{SUFFIX_NUMBER}
- Required Request Parameters:
- {ACCOUNT_NUMBER}: A Number type representing the member account number for which to retrieve stop payment information. Required.
- {SUFFIX_NUMBER}: A Number type representing the member suffix number for which to retrieve stop payment information. Required.
- Example Query URL: https://example.com/api/account/12345/stoppedPayments/25
- Response Structure:
- Object Type: stoppedPayments (a List).
- Description: This list contains all available check stopped payments for the specified account.
- Sample Response:
{
“stoppedPayments”: [
{
“accountNumber”: 89891,
“suffix”: 115,
“draftNumber”: 1,
“sequenceNumber”: 1,
“amount”: 0.00,
“enteredDate”: “05/18/2020 00:00:00 MDT”,
“reason”: “BANKRUPT 13″,
“memberName”: “WALKEPAULW”
},
{
“accountNumber”: 89891,
“suffix”: 115,
“draftNumber”: 20,
“sequenceNumber”: 0,
“amount”: 0.00,
“releaseDate”: “11/23/2018 00:00:00 MST”,
“enteredDate”: “05/18/2020 00:00:00 MDT”,
“reason”: “Lost Checks”,
“memberName”: “WALKEPAULW”
}
// … more stopped payment objects …
]
}
stoppedPayments Object Attributes (in Response):- accountNumber: Number. The account number for the Stop Payment (maximum 9 characters).
- suffix: Number. The account suffix for the Stop Payment (maximum 3 characters).
- draftNumber: Number. The draft number (maximum 9 characters).
- sequenceNumber: Number. The sequence number (maximum 2 characters).
- amount: Number. The check amount (maximum 9 characters).
- releaseDate: Date. The date when the Stop Payment is released, formatted as MM/DD/CCYY.
- enteredDate: Date. The date the Stop Payment was added, formatted as MM/DD/CCYY.
- reason: String. The reason for the Stop Payment (maximum 20 characters).
- memberName: String. The abbreviated full member name (maximum 10 characters).
6. Creating Check Stop Payments for an Account Suffix
When creating a stop payment, FLEX advises checking with the credit union regarding any applicable fees. Regardless of whether a fee is charged, the attributes chargeFee, setupFee, and feeSuffix must be included in the JSON data.
- Method: POST
- REST URL: https://{BASE_URL}/createstoppayment
- Request Body: This method requires a JSON body, structured as described in the “Stop Payment Request Object” section below.
- Draft Number Requirement:
- A draft number or range of draft numbers is mandatory when creating a Stop Payment.
- You can specify a single draft number using the draftNumber attribute, or a range of draft numbers using draftNumberFrom and draftNumberTo.
- Examples of Creating a Stop Payment Request:
- Using a Range of Draft Numbers (Not Charging a Fee):
{
“accountNumber”: 1234567,
“suffix”: 1,
“draftNumberFrom”: 1,
“draftNumberTo”: 1000,
“stopPaymentAmount”: 500.00,
“startDate”: “04/01/2017”, // Per revisions, “enteredDate” is now “startDate”
“expirationDate”: “04/02/2018”, // Per revisions, “realeaseDate” is now “expirationDate”
“reason”: “Reason for stop”,
“chargeFee”: false,
“setupFee”: 0,
“feeSuffix”: 0,
“printNotice”: false
}
Using a Single Draft Number (Charging a Fee):
{
“accountNumber”: 1234567,
“suffix”: 1,
“draftNumber”: 195,
“stopPaymentAmount”: 500.00,
“startDate”: “04/01/2017”,
“expirationDate”: “04/02/2018”,
“reason”: “Reason for stop”,
“chargeFee”: true,
“setupFee”: 10,
“feeSuffix”: 05,
“printNotice”: false
}
Response for Create Stop Payment:- success: A Boolean value indicating whether the request was successful. Unsuccessful requests will trigger exception errors.
- Sample Response:
{
“success”: true
}
Stop Payment Request Object Attributes (in Request Body):- accountNumber: Number. The account number for the Stop Payment (maximum 9 characters). Required.
- suffix: Number. The suffix for the Stop Payment (maximum 3 characters). Required.
- draftNumberFrom: Number. The starting draft number (maximum 9 characters). Optional. (Note: A draft number or range is still required).
- draftNumberTo: Number. The ending draft number (maximum 9 characters). Optional. (Note: A draft number or range is still required).
- stopPaymentAmount: Number. The check amount (maximum 9 characters). Required.
- sequenceNumber: Number. The sequence number assigned to Stop Payment items (maximum 2 characters). FLEX suggests a default starting value of zero; FLEX will then assign subsequent sequence numbers as stop payments are added. Required.
- startDate: Date. The starting date for the Stop Payment, formatted as MM/DD/CCYY. Required.
- expirationDate: Date. The expiration date for the Stop Payment, formatted as MM/DD/CCYY. Optional.
- reason: String. The reason for the Stop Payment (maximum 20 characters). Required.
- chargeFee: Boolean. Indicates whether a Stop Payment fee should be charged. Valid options are true or false. Required.
- setupFee: Number. The fee amount for creating the Stop Payment (maximum 6 characters). Required.
- feeSuffix: Number. The suffix to be charged for the Stop Payment fee (maximum 3 characters). A value is required even if no fee is charged (in which case, the value should default to 0).
- printNotice: Boolean. Indicates whether a Stop Payment notice was printed. Valid options are true or false. Required.
7. HTTPS Status Code 500 Errors and FLEX Validation Checks
FLEX has enhanced the 500 HTTP Status Code errors within the API Service responses to improve troubleshooting capabilities.
- Resolution Process: Once the underlying issue causing the error is identified and corrected, the request should be re-attempted.
- Common Causes: The majority of errors encountered via the service stem from invalid attribute values or values that are not configured within the credit union database options. Certain HTTPS messages are also triggered by preset conditions to uphold data integrity and accuracy.
- Troubleshooting Recommendation: FLEX suggests providing the specific error message directly to the credit union. Credit unions are typically familiar with most error messages and can often correct the data without requiring assistance from FLEX or third-party support.
- Most Common Error Messages and Their Causes:
- {“message”: “Internal server error – Fee Suffix must be entered”}
- Cause: This error occurs when the feeSuffix attribute is missing or has no value in the JSON data.
- Correction: The feeSuffix value should default to 0 if no Stop Payment fee is being charged. If a fee is charged, the value must be the suffix from which the fee will be debited.
- {“message”: “Internal server error – Account 8989891 does not exist”}
- Cause: The request contains an invalid account number.
- Correction: Validate and correct the account number before resubmitting the request.
- {“message”: “Internal server error – Failed to setup stop payments”}
- Cause: One or more attribute values within the request are either missing or invalid.
- Correction: Verify that all attribute values are valid and that all required attributes are present in the JSON request body.
- {“message”: “Internal server error – java.lang.RuntimeException: reason cannot exceed 20 characters”}
- Cause: The reason attribute for the Stop Payment contains more than its allowed maximum of 20 characters.
- Correction: Ensure the reason attribute value does not exceed 20 characters.
- {“message”: “Internal server error – Suffix number 155 does not exist for account 89891”}
- Cause: The provided suffix number value is not valid for the specified Member account number.
- Correction: Verify that the suffix value is correct and associated with the account before resubmitting the request.
- {“message”: “Internal server error – Fee Suffix must be entered”}