FLEXBridge ATM Service API

1. Introduction to the ATM Service API

The ATM Service API is a crucial part of FLEXBridge, enabling transactions on a member’s account using either their account or card number. This API facilitates several key functions: deposits, loan payments, transfers, or withdrawals. The documentation details the necessary endpoints/service calls, object types, and attributes required to perform these functions through FLEXBridge and impact a member’s account.

2. FLEXBridge Core Functions

FLEXBridge operates as a RESTful API and incorporates built-in authentication. Authentication headers must be included with every request. For details on adding these headers, refer to the FLEX Core System documentation.

The FLEXBridge ATM Processing API currently offers the following primary functions:

Transactions: Allows for direct financial operations.
- Can be initiated using an Account Number for deposits, withdrawals, transfers, or loan payments.
- Can be initiated using a Card Number for deposits, withdrawals, transfers, or loan payments.
Reversals: Provides options to reverse previously executed transactions.
- Account Number Reversal for deposits, withdrawals, transfers, or loan payments.
- Card Number Reversal for deposits, withdrawals, transfers, or loan payments.
Modifying Transactions: Used for adjusting transactions, such as performing a partial transaction reversal.
- Account Number Transaction Modification for deposits, withdrawals, transfers, or loan payments.
- Card Number Transaction Modification for deposits, withdrawals, transfers, or loan payments.

3. API Request Structure

All operations described in this documentation utilize the HTTP POST method.

3.1. Transaction Endpoints

Transaction requests are made to specific RESTful URLs, which dynamically incorporate whether the transaction is by account or card, and the type of transaction.

RESTful URL Structure: https://{BASE_URL}/api/atm/{ACCOUNT_OR_CARD}/{TRANSACTION_TYPE}
- {ACCOUNT_OR_CARD}: Can be account or card.
- {TRANSACTION_TYPE}: Can be withdrawal, transfer, deposit, or loanpayment.
Examples of Transaction Endpoint Requests:
- https://{URL_ADDRESS}/api/atm/account/withdrawal/
- https://{URL_ADDRESS}/api/atm/card/deposit
- https://{URL_ADDRESS}/api/atm/account/transfer
- https://{URL_ADDRESS}/api/atm/card/loanpayment

3.2. Reversing Transaction Endpoints

Reversal endpoints are similar to transaction endpoints but include /reverse at the end.

RESTful URL Structure: https://{BASE_URL}/api/atm/{ACCOUNT_OR_CARD}/{TRANSACTION_TYPE_TO_REVERSE}/reverse
- {ACCOUNT_OR_CARD}: Can be account or card.
- {TRANSACTION_TYPE_TO_REVERSE}: Can be withdrawal, transfer, deposit, or loanpayment.
Examples of Reversal Endpoint Requests:
- https://{URL_ADDRESS}/api/atm/account/withdrawal/reverse
- https://{URL_ADDRESS}/api/atm/card/deposit/reverse
- https://{URL_ADDRESS}/api/atm/account/transfer/reverse
- https://{URL_ADDRESS}/api/atm/card/loanpayment/reverse

3.3. Modifying Transaction Endpoints

Modification endpoints are used for scenarios like partial reversals, where an ATM might dispense an incorrect amount of tender. The service credits back the original transaction and then posts the new adjusted transaction.

RESTful URL Structure: https://{BASE_URL}/api/atm/{ACCOUNT_OR_CARD}/{TRANSACTION_TO_MODIFY}/modify
- {ACCOUNT_OR_CARD}: Can be account or card.
- {TRANSACTION_TO_MODIFY}: Can be withdrawal, transfer, deposit, or loanpayment.
Examples of Modification Endpoint Requests:
- https://{URL_ADDRESS}/api/atm/account/withdrawal/modify
- https://{URL_ADDRESS}/api/atm/card/deposit/modify
- https://{URL_ADDRESS}/api/atm/account/transfer/modify
- https://{URL_ADDRESS}/api/atm/card/loanpayment/modify

4. JSON Body Information for Requests

All endpoints require a JSON body as part of the request.

4.1. Transaction JSON Body

The JSON body for a transaction request is required for successful processing and references the ATM POST Request Object Attributes.

Key Attributes for Deposits, Withdrawals, Loan Payments (Account & Card Options):
- Can include “cashAmount” and/or “checkAmount” attributes.
Key Attributes for Card Transfer Requests:
- Requires “fromAccountType” and “toAccountType” attributes.
Key Attributes for Account Transfer Requests:
- Requires the member’s accountNumber and the “fromSuffix” and “toSuffix” attributes.
Terminal Timestamp: FLEX has simplified this attribute by removing time zone characters.

4.1.1. Example of a Card Number Transaction JSON Body: Deposit

{

“cardNumber”: 1234567890123452,

“plasticNumber”: 2,

“accountType”: “S”,

“amount”: 10.00,

“traceNumber”: 1,

“terminalTimestamp”: “05/31/2019 15:30:45″,

“settlementDate”: “06/01/2019”,

“transactionFee”: 1.00,

“institutionId”: “CMC”,

“track2Data”: “TRACK”,

“retrievalReferenceNumber”: 12345,

“terminalId”: “TERM”,

“location”: “ TestLocation”,

“merchant”: “MER”,

“network”: “NET”,

“denialCode”: “”,

“d1ProcessingCode”: “N”,

“cashAmount”: 5.00,

“checkAmount”: 10.00

}

4.1.2. Example of an Account Number Transaction JSON Body: Loan Payment

{

“accountNumber”: 123456789,

“suffix”: 25,

“amount”: 10.00,

“traceNumber”: 1,

“terminalTimestamp”: “05/31/2019 15:30:45″,

“settlementDate”: “06/01/2019”,

“transactionFee”: 1.00,

“institutionId”: “CMC”,

“track2Data”: “TRACK”,

“retrievalReferenceNumber”: 16345,

“terminalId”: “TERM”,

“location”: “ TestLocation”,

“merchant”: “MER”,

“network”: “NET”,

“denialCode”: “”,

“d1ProcessingCode”: “Y”,

“cashAmount”: 5.00,

“checkAmount”: 0

}

4.2. Reversing Transaction JSON Body

A reversal request’s JSON body is exactly the same as the original transaction it is reversing.

Key Attributes for Deposits, Withdrawals, Loan Payments Reversals (Account & Card Options):
- Can include “cashAmount” and/or “checkAmount” attributes.
Key Attributes for Card Transfer Reversals:
- Requires “fromAccountType” and “toAccountType” attributes.
Key Attributes for Account Transfer Reversals:
- Requires the member’s accountNumber and the “fromSuffix” and “toSuffix” attributes.
Terminal Timestamp: FLEX has simplified this attribute by removing time zone characters.

4.2.1. Example of a Card Number Reversal JSON Body: Deposit

(Note: This JSON is identical to the original card deposit transaction JSON, as per documentation).

{

“cardNumber”: 1234567890123452,

“plasticNumber”: 2,

“accountType”: “S”,

“amount”: 10.00,

“traceNumber”: 1,

“terminalTimestamp”: “05/31/2019 15:30:45″,

“settlementDate”: “06/01/2019”,

“transactionFee”: 1.00,

“institutionId”: “CMC”,

“track2Data”: “TRACK”,

“retrievalReferenceNumber”: 12345,

“terminalId”: “TERM”,

“location”: “ TestLocation”,

“merchant”: “MER”,

“network”: “NET”,

“denialCode”: “”,

“d1ProcessingCode”: “N”,

“cashAmount”: 5.00,

“checkAmount”: 10.00

}

4.2.2. Example of an Account Number Reversal JSON Body: Loan Payment

(Note: This JSON is identical to the original account loan payment transaction JSON, as per documentation).

{

“accountNumber”: 123456789,

“suffix”: 25,

“amount”: 10.00,

“traceNumber”: 1,

“terminalTimestamp”: “05/31/2019 15:30:45″,

“settlementDate”: “06/01/2019”,

“transactionFee”: 1.00,

“institutionId”: “CMC”,

“track2Data”: “TRACK”,

“retrievalReferenceNumber”: 16345,

“terminalId”: “TERM”,

“location”: “ TestLocation”,

“merchant”: “MER”,

“network”: “NET”,

“denialCode”: “”,

“d1ProcessingCode”: “Y”,

“cashAmount”: 5.00,

“checkAmount”: 0

}

4.3. Modifying Transaction JSON Body

The JSON body for modifying transactions requires two main objects: originalRequest and newRequest.

originalRequest: Must be an exact match of the transaction that was originally sent and now needs modification.
newRequest: Represents the new transaction request replacing the original. This is typically used to designate the amount a member actually received if an ATM/ITM or other dispenser could not provide the full original amount due to lack of funds or malfunctions.

4.3.1. Example of a Modification JSON Body with an Account Number

{

“originalRequest”: {

“accountNumber”: 24687,

“suffix”: 1,

“amount”: 105.25,

“traceNumber”: 1,

“terminalTimestamp”: “10/29/2019 15:30:45″,

“settlementDate”: “10/29/2019”,

“transactionFee”: 0.00,

“institutionId”: “CMCTEST”,

“track2Data”: “CardMagData”,

“retrievalReferenceNumber”: 85688,

“terminalId”: “FLEX001”,

“location”: “FLEXBranch 01″,

“merchant”: “FLEXITM001”,

“network”: “NHA”,

“denialCode”: “”,

“d1ProcessingCode”: “Y”

“newRequest”: {

“accountNumber”: 24687,

“suffix”: 1,

“amount”: 101.00,

“traceNumber”: 1,

“terminalTimestamp”: “10/29/2019 15:30:45″,

“settlementDate”: “10/29/2019”,

“transactionFee”: 0.00,

“institutionId”: “CMCTEST”,

“track2Data”: “CardMagData”,

“retrievalReferenceNumber”: 85688,

“terminalId”: “FLEX001”,

“location”: “FLEXBranch 01″,

“merchant”: “FLEXITM001”,

“network”: “NHA”,

“denialCode”: “”,

“d1ProcessingCode”: “Y”

}

4.3.2. Example of a Modification JSON Body with a Card Number

{

“originalRequest”: {

“cardNumber”: 4136190000702215,

“plasticNumber”: 0,

“accountType”: “C”,

“amount”: 75.00,

“traceNumber”: 1,

“terminalTimestamp”: “10/28/2019 15:30:45″,

“settlementDate”: “10/28/2019”,

“transactionFee”: 0.00,

“institutionId”: “CMCTEST”,

“track2Data”: “CardMagData”,

“retrievalReferenceNumber”: 85778,

“terminalId”: “FLEX001”,

“location”: “FLEXBranch 01″,

“merchant”: “FLEXITM001”,

“network”: “NHA”,

“denialCode”: “”,

“d1ProcessingCode”: “Y”

“newRequest”: {

“cardNumber”: 4136190000702215,

“plasticNumber”: 0,

“accountType”: “C”,

“amount”: 55.00,

“traceNumber”: 1,

“terminalTimestamp”: “10/28/2019 15:30:45″,

“settlementDate”: “10/28/2019”,

“transactionFee”: 0.00,

“institutionId”: “CMCTEST”,

“track2Data”: “CardMagData”,

“retrievalReferenceNumber”: 85778,

“terminalId”: “FLEX001”,

“location”: “FLEXBranch 01″,

“merchant”: “FLEXITM001”,

“network”: “NHA”,

“denialCode”: “”,

“d1ProcessingCode”: “Y”

}

5. Object Types and Attributes for Requests

The same JSON attributes are generally used for both Account and Card Transactions and Reversals, as well as within the originalRequest and newRequest objects for modifications.

5.1. Common Required Attributes for Transactions, Reversals, and Modifications

amount: The transaction amount (max 12 characters).
traceNumber: Unique number for the transaction (max 6 characters).
terminalTimestamp: Timestamp of the transaction. FLEX has removed time zone characters for simplification.
settlementDate: The settlement date (MM/DD/CCYY format), which doesn’t have to match terminalTimestamp.
institutionId: Routing number for the credit union or another ID (max 11 characters).
track2Data: Information from the card’s magnetic strip (max 37 characters).
retrievalReferenceNumber: Unique reference number associated with a transaction (max 12 characters).
terminalId: Unique ID defining a Terminal (max 8 characters).
location: Location where the transaction occurred (e.g., “flextechcreditunionsaltlakecityUTUS”) (max 40 characters).
merchant: Location of the ATM (max 40 characters).
network: Assigned by the online network (max 3 characters).
denialCode: Denial Code for invalid transactions (default: “”) (max 3 characters).
d1ProcessingCode: Indicates D1 processing support (Y=supported, N=not supported, A=fee accepted). Defaults to ‘Y’.

5.2. Optional Attributes

transactionFee: Terminal Fee charge for a transaction (max 9 characters).
cashAmount: Cash amount involved (max 9 characters).
checkAmount: Check amount involved (max 9 characters).

5.3. Card-Specific Required Attributes

cardNumber: Card Number for the transaction (max 19 characters). Required for Card Transactions.
plasticNumber: Card sequence number, rarely used; default to zero (max 1 character). Optional for Card Transactions.
accountType: FLEX Online Service value for suffix (S=Savings, C=Checking, L=Loan/Credit Card, M=Money Market, D=Default) (max 1 character). Required for Card Transactions.

5.4. Card Transfer-Specific Required Attributes

fromAccountType: Card Account Type from which amount debits (S, C, L, M, D) (max 1 character). Required only for Card Transfer Transactions.
toAccountType: Card Account Type to which amount credits (S, C, L, M, D) (max 1 character). Required only for Card Transfer Transactions.

5.5. Account-Specific Required Attributes

accountNumber: Individual’s account number (max 9 characters). Required for Account Transactions.
suffix: Individual’s suffix number (max 3 characters). Required for Account Transactions.

5.6. Account Transfer-Specific Required Attributes

fromSuffix: Suffix number from which amount debits. Required only for Account Transfer Transactions.
toSuffix: Suffix number to which amount credits. Required only for Account Transfer Transactions.

6. Transaction Response Structure

The ATM Service API returns a JSON response indicating the success or failure of the transaction, reversal, or modification. The same JSON attributes are sent back for both Card and Account operations.

6.1. Response Attributes

success (Boolean): Indicates if the operation was successful (True or False).
response (Object): Contains detailed information about the operation.
- responseCode (String): Indicates if the transaction was approved or denied (e.g., “00” for approved).
- receiptNumber (Number): Unique transaction receipt number.
- currentBalance (Number): Current suffix balance.
- availableBalance (Number): Available suffix balance.
- accountNumber (Number): Account number involved in the transaction.
- d1FeeAmount (Number): The D1 fee amounts charged.
- errors (List): Additional information listing why a transaction was unsuccessful.
- fromCurrentBalance (Number): Current suffix balance of the account debit for a transfer.
- fromAvailableBalance (Number): Available suffix balance of the account debit for a transfer.
- toCurrentBalance (Number): Current suffix balance of the account credit for a transfer.
- toAvailableBalance (Number): Available suffix balance of the account credit for a transfer.
- holdAmount (Number): Indicates the amount on hold from the transaction.
- holdReason (String): Indicates the reason for the hold.

6.2. Example of a Successful Transaction Response

{

“success”: true,

“response”: {

“responseCode”: “00”,

“receiptNumber”: 1527,

“currentBalance”: 351.49,

“availableBalance”: 301.49,

“accountNumber”: 24687,

“d1FeeAmount”: 0.00,

“errors”: []

}

6.3. Example of a Successful Response with Hold Information (e.g., ATM Deposit)

{

“success”: true,

“response”: {

“responseCode”: “00”,

“receiptNumber”: 1537,

“currentBalance”: 5608.57,

“availableBalance”: 5303.57,

“accountNumber”: 15929,

“d1FeeAmount”: 0.00,

“holdAmount”: 300.00,

“holdReason”: “ATM Deposit”,

“errors”: []

}

6.4. Example of a Failed Transaction Response

{

“success”: false,

“response”: {

“responseCode”: “56”,

“receiptNumber”: 475,

“fromCurrentBalance”: 0,

“fromAvailableBalance”: 0,

“toCurrentBalance”: 0,

“toAvailableBalance”: 0,

“accountNumber”: 0,

“d1FeeAmount”: 0,

“errors”: []

}

Or, with specific error messages:

{

“success”: false,

“response”: {

“receiptNumber”: 0,

“accountNumber”: 0,

“errors”: [

“Failed to process card withdrawal.”

]

}

7. Response Codes: Approved and Denial

The responseCode attribute in the API response provides critical information about the transaction’s outcome.

00: Approved
10: Partial Approval
41: Lost Card
43: Stolen Card
51: NSF (Insufficient Funds)
52: No Checking Account
53: No Saving Account
56: No Card Record
61: Exceeds Withdrawal Limit (Note: code is EX with Jack Henry)
62: Restricted Card
12: Unknown Transaction Code

8. Document Revisions and Important Notes

As of March 2021, the document has received the following adjustments:

The term “truncated” has been updated to “maximum,” reflecting how the service API handles data fields with excessive characters.
The URL Header Parameter workstationId (or workstationID) has been corrected to workstation. Sending the old parameter name will nullify the parameter and its value, leading to request errors if the value is required.
The URL Header Parameter tellerId has been corrected to tellerID. Sending the old parameter name will nullify the parameter and its value, leading to request errors if the value is required.

FLEXBridge ATM Service API

1. Introduction to the ATM Service API

2. FLEXBridge Core Functions

3. API Request Structure

3.1. Transaction Endpoints

3.2. Reversing Transaction Endpoints

3.3. Modifying Transaction Endpoints

4. JSON Body Information for Requests

4.1. Transaction JSON Body

4.1.1. Example of a Card Number Transaction JSON Body: Deposit

4.1.2. Example of an Account Number Transaction JSON Body: Loan Payment

4.2. Reversing Transaction JSON Body

4.2.1. Example of a Card Number Reversal JSON Body: Deposit

4.2.2. Example of an Account Number Reversal JSON Body: Loan Payment

4.3. Modifying Transaction JSON Body

4.3.1. Example of a Modification JSON Body with an Account Number

4.3.2. Example of a Modification JSON Body with a Card Number

5. Object Types and Attributes for Requests

5.1. Common Required Attributes for Transactions, Reversals, and Modifications

5.2. Optional Attributes

5.3. Card-Specific Required Attributes

5.4. Card Transfer-Specific Required Attributes

5.5. Account-Specific Required Attributes

5.6. Account Transfer-Specific Required Attributes

6. Transaction Response Structure

6.1. Response Attributes

6.2. Example of a Successful Transaction Response

6.3. Example of a Successful Response with Hold Information (e.g., ATM Deposit)

6.4. Example of a Failed Transaction Response

7. Response Codes: Approved and Denial

8. Document Revisions and Important Notes

Schedule your demonstration today!

Get our latest news, articles, and resources delivered straight to your inbox.

Company Links

Useful Links