Development Using OAuth REST-Legacy
Introduction
The following information is intended to jump start your development using REST-Legacy within the jXchange Service Gateway (jXchange) environment. Please review all the information below. We also recommend that you review the following before starting development:
- The minimum and optional reading items found on the Getting Started and jXchange Environment pages.
- Please review the Development using SOAP as the REST-Legacy product is a JSON wrapper communicating to the SOAP infrastructure.
As a new consumer of Enterprise Integration & Services (EI&S) services, your company will be responsible for the complete development life cycle of your new product. JHA does not provide code reviews, nor do we require code supervision for your product.
Jack Henry application programming interfaces (API) are developed as contract-first, meaning the structure is designed prior to the supporting service. The are several reasons for this, one being the contracts are designed with the enterprise perspective, ensuring all potential providers of the services are represented.
Any references made regarding contracts for the SOAP APIs, refer to the XSDs and WSDLs that can be found on the SOAP Documentation of this portal. The file name contains the contract version, using this name format - TPG_RYYYY.X.XX_XSD.zip.
First Steps
jXchange REST-Legacy (JX-RL) is SOAP under the covers. The existing documentation contained within the Enterprise SOAP API section of this portal may be used to explore available APIs, their use, and accompanying documentation. Below is information about the type of security used, the sandbox location, message requirements, and JSON examples.
The JX-RL service uses Jack Henry Identity’s client credential workflow. To register, the consumer must generate a public/private key pair and provide the PEM Public Key or JWKS URL to the Developer Relations team. Developer Relations will then configure a Client ID for the application. The consumer uses their Private Key to generate signed JWTs. See the Jack Henry Identity Documentation for more details.
DMZ Access We support both key‑pair authentication and JWKS for DMZ integrations.
Bank‑Level Access For higher‑security, bank‑grade integrations, JWKS URL support is required whenever key rotation is expected. This ensures seamless rotation and prevents service interruptions that can occur when relying solely on a static key pair.
Pre-Production Environment Access
| Authorization Type: | Bearer Token |
| Security: | Client Credential flow with Signed JWT |
| Token Server: | https://banno.com/a/oidc-provider/api/v0/token |
| grant_type: | client_credentials |
| Scope: | https://jackhenry.com/jx/service-gateway.write https://jackhenry.com/platform/translations/jx-rl.write |
| ClientID: | Provided by JH |
| Public Key: | Provided by Consumer |
HTTP Request Headers
The following HTTP Header entries MUST be provided on each message request:
X-ConsumerName | This value will be supplied to the consuming product by a Developer Relations contact. |
X-ConsumerProd | This value will be supplied to the consuming product by a Developer Relations contact. |
X-ValidConsmName | This value will be supplied to the consuming product by a Developer Relations contact. |
X-ValidConsmProd | This value will be supplied to the consuming product by a Developer Relations contact. |
X-AuthenUsrCred | For systems where the consumer would like to indicate a specific user being represented in the call. |
These additional HTTP Header keys MAY be provided on each message request:
X-AuditUserId | For systems where the user (human) is not represented in the access token, this value will indicate the user. The value will generally be the unique value the foreign system uses to identify the user. |
X-AuditDeviceId | For systems where the device information is of interest to the provider or consumer, this element will contain that information. |
x-request-id | The “X-Request-Id” header is included “unique for every request” and is typically generated by the client or server (API initiator). This header is used to track and identify individual requests as they go through the various systems to enable tracing, replay detection, and troubleshoot requests. By including this header in API requests, developers and system administrators may correlate logs and monitor the flow of requests through multiple systems as it proceeds to the intended target. See here for details. |
X-correlation-id | The X-Correlation-ID header is an optional header that can be included in REST API for use in tracking and correlating related requests and responses within a distributed system. This header allows clients to assign a unique identifier to a request, which can then be used by servers or middleware components to track and link subsequent requests and responses that are part of the same logical operation or transaction. |
X-workflowcorrelationid | The X-WorkflowCorrelationId header is used to correlate different requests or events as part of a workflow or process. It is primarily utilized for tracking and managing the flow of requests throughout multiple systems or multiple calls. When a workflow client sends multiple related requests, they can include the X-WorkflowCorrelationId header with the same value to indicate that these requests are part of the same workflow to support in the grouping and associating the requests together thus enabling reporting systems to identify them as a single logical unit. Additionally, this header element can be used to assist in monitoring and troubleshooting the workflow by allowing administrators or developers to trace and analyze the flow of requests using this common identifier. |
API URL Formatting
Base API URL: https://{FQDN}/api/translations/v1/jx-rl/institutions/{institution-routing-id}/environments/{institution-environment}/{GroupName}/{API}
This is the base URL for testing with a single institution in the DMZ development environment. This will change in a bank’s environment and will be provided when bank level credentials are created.
The {institution-routing-id} and {institution-environment} values will be unique per institution, as will the client_id and key pair.
The rest of the standard URL will include the group name (container) and the operation. You can find the group name within this portal by selecting API by Provider, Provider Name, and the operation, and Developer Resources. Below is a sample table for the AcctAdd API.
| SoapAction | http://jackhenry.com/ws/AcctAdd |
| Input Name | AcctAdd |
| Output Name | AcctAddResponse |
| Input Namespace | http://jackhenry.com/jxchange/TPG/2008 |
| Group Name | Deposit |
| Container | TPG_DepositMaster.xsd |
| Accessibility | Accessible internally and externally |
Cores
| Core Name | InstRtId | InstEnv |
|---|---|---|
| SilverLake | 999800100 | TEST |
| CIF 2020 | 999800200 | TEST |
| Core Director | 999800900 | TEST |
The information above can be used to send operations to our externally accessible jXchange instance. This is a sandbox environment that is commonly referred to as the DMZ. This instance is used by third parties to develop their jXchange integration.
The InstRtId and InstEnv values above denote three different jXchange configurations, each tied to a different JH core provider. The DMZ jXchange currently tied to SilverLake uses 999800100 and TEST, the CIF2020 gateway uses 2020 and TEST, and Core Director uses 11111900 and TEST.
Your provisioned access to these gateways may vary depending on which core(s) your company identified for use in the initial onboarding documentation.
For all jXchange integrations, the combination of InstRtId and InstEnv values will be unique to each jXchange instance.
A member of the Developer Relations team will configure an external client in our pre-production environment and provide you with a client-id and private key to use to sign session tokens to the Jack Henry Identity provider (JHID). For production installs, you will receive a different client-id and private key for each institution environment. The jXchange URL, InstRtId, and InstEnv could also vary per production financial institution (FI) environment as well. The ValidConsmName and ValidConsmProd values will always be the same per consuming product.
Also please note that all development work should be done against our DMZ institution environment shown in JSON message examples below, and never against a FI’s production environment.
URL Addition for *Srch APIs
For any API that is of type Srch an addition to the endpoint is required to utilize the MaxRec and Cursor features found in the XML code. These are normally passed in within the XML itself but for the REST Legacy they are contained within the endpoint. The format of the addition is as follows: ?Count=5&NextOffset=0
The Count= is the MaxRec XML element and usually can go up to a maximum of 3999. The NextOffset is the Cursor XML element and is used to page the results as warranted.
Sample CURL To Retrieve Token
curl --location --request POST 'https://banno.com/a/oidc-provider/api/v0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=https://jackhenry.com/jx/service-gateway.write' \
--data-urlencode 'client_id={ClientID}’ \
--data-urlencode 'client_secret={ClientSecret}’
Migration Guide for Existing Consumers
As part of continuing maintenance and improvement of Jack Henry services, the jXchange Rest-Legacy service will be migrating to a new, enhanced version (the new platform). This section covers steps needed for existing consumers only to switch to the new platform. Changes will be required for how the service is accessed and what is required for Authentication, but should otherwise behave the same as the current platform.
The following topics will be covered in greater detail below:
- Authentication & scope
- jXchange Rest Legacy hostname & URL
- Request formatting
- Feature support & unexpected behavior
- IP Access Restrictions
Authentication & scope
Accessing the new platform will require interacting with the Jack Henry Identity (JHID) OAuth provider in order to obtain a session token. Please see JHID documentation for guidance on integrating with this system.
Your Developer Relations contact will help you in this process, providing needed details to complete this integration.
Previously, the authentication solution for jXchange Rest Legacy required an OAuth access token with the http://jackhenry.com/auth/jha/jxrl scope. The new platform will instead require an OAuth access token with the https://jackhenry.com/jx/service-gateway.write scope. This is the same scope used for all interactions with OAuth-enhanced jXchange SOAP services.
jXchange Rest Legacy hostname & URL
Production
https://banno.com/api/translations/v1/jx-rl/institutions/{institution-routing-id}/environments/{institution-environment}/{group-name}/{api}
Pre-Production
NOTE the pre-populated
{institution-routing-id}&{institution0-environment}parameters in the pre-production version of the URL
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/{group-name}/{api}
URL composition
The following values are required to form a complete request URL:
{institution-routing-id} | The numeric identifier for a consumer institution. This information is provided by Developer Relations. |
{instition-environment} | The environment within jXchange systems. This value may change in different usage scenarios and across demo/production environments. Guidance will be provided by Developer Relations. The value should be set to TEST for pre-production testing. |
{group-name} & {api} | The Service contract and API message being sent in a given request to jXchange Rest Legacy. |
Request formatting
The HTTP Request Headers sections of this document outlines optional and required HTTP headers for each request. Your automation processes must be updated to reflect these changed requirements.
It is recommended that all headers be provided, even the optional ones.
The X-ConsumerName, X-ConsumerProd, X-ValidConsmName, and X-ValidConsmProd HTTP headers are non-optional and MUST be provided to every request to the jXchange Rest Legacy service on its new platform.
The optional x-request-id, x-correlation-id, and x-workflowcorrelationid headers are case-sensitive and MUST be in lower-case format.
The optional x-request-id, x-correlation-id, and x-workflowcorrelationid headers are useful when seeking assistance for production errors or other issues with JHA Support resources. They can be a random UUID/GUID value generated at the time of the request, or an existing transactional identifier from a process in the consumer’s system. It is recommended that consumers log these values when unexpected behavior is encountered in the jXchange Rest Legacy system, because JHA Support resources can use them to pinpoint the root cause of an issue.
Feature support & unexpected behavior
The new platform should cover all existing behavior of the as-is jXchange Rest Legacy system, while also fixing some limitations that were previously in place.
All messages, Srch-based or otherwise, should work as before, and all Srch-based messages should be detected properly provided they contain Srch in the operation-name. NextOffset & Count behavior to should work as before. As new messages/operations are added to existing service contracts, they should be supported in jXchange Rest Legacy service’s new platform.
Messages requiring <Custom> elements should be supported and work as expected.
If any deviation from the described behavior is encountered, please reach out to your Developer Relations contact.
IP access restrictions
The as-is production solution for jXchange Rest Legacy requires an IP allow-list of all consumers.
The new platform for JX-RL has lifted this rule. All requests will be authenticated through the JHID OAuth2 identity infrastructure. The Jack Henry environment is now limiting access to geographic location. Please reach out to your Jack Henry contact if you have issues connecting to the jXchange Rest Legacy API and your calling system is located outside of the continental United States.
Multi-Provider Testing
If a solution will be touching multiple JH providers (ex: SilverLake, CIF 20/20, Core Director, etc.) it is important to understand that although most of the operations are not provider specific and are interchangeable from the consumer standpoint. However, the jXchange environment and its APIs do not provide normalization and behaviors/responses can differentiate a great deal based on the provider that is being accessed. It is the responsibility of the consumer to test their service calls across every provider environment to ensure their product can handle any potential different behavior/responses between individual providers.
A simple example of this can be found in the account types between SilverLake and Core Director. A deposit account for SilverLake uses the identifier of D while Core Director uses the identifier of 10.
DMZ Demonstration Use Statement
Jack Henry’s pre-production environment is a developer focused environment where all consumers are integrating with shared systems of record, whether banking cores, SilverLake, CIF 2020, or Core Director, or complimentary products such as Synergy and Synapsys. The nature of this environment does not necessarily lend itself to third-party vendor product demonstrations using Jack Henry’s Enterprise Integration solutions. Third-party vendors may use these systems for demonstrations with the following understanding.
- Data can and may change based on usage and access by other consumers during your demonstration window.
- Access will not be limited to prevent other consumers from using the environment during a window of time.
- Jack Henry personnel will not be available for immediate troubleshooting if issues arise during a demonstration.
- System maintenance is scheduled Monday between 4:00 pm and 6:00 pm US Central time.
- The SilverLake banking core runs its nightly processing Monday through Friday, beginning at 8:00 pm Central and normally completing before 9:00 pm US Central time.
- After hours support is not available for the DMZ. Business hours are 8:00 am to 5:00 pm US Central time.
Sample process flow diagram for jXchange integrations

This is an example flowchart of how a workflow might look and can be modified to meet certain product requirements. Note that the customer record is the root and must exist prior to associating accounts.
Commonly Used APIs and Tutorials
Common APIs
See Commonly Used APIs for a quick list of apis that are most used when consuming jXchange APIs.
Tutorials
We also offer a Tutorials section for additional use cases. A full list of APIs may be found within the API by Provider or API by Reference.
Development Data
Preselected Data for Development
To help you get started, sample data is available in the SOAP Documentation section. Look for the file named: DMZTestAccounts_SL_2020_CoreDirector_Episys.
Creating Your Own Data
We also recommend consumers create their own data to meet their use case needs. APIs with the suffix of *Add indicates an API that would be used to create a system record. Several often used examples include:
- CustAdd Create a new customer record
- AcctAdd Open a new account
- TrnAdd Perform a transaction
- EFTCardAdd Issue a new EFTCard
- CollatTrckAdd Create a collateral tracking record
Sample REST-Legacy APIs
RL is a SOAP API environment presented via REST. The structure provided by the SOAP call can provide a developer with the guidance they need to build the REST call into our RL environment. Below are some common API samples for you to review and understand the differences between SOAP versus RL structure.
Postman Collection
You may download a Postman Collection that contains various tests using the jXchange Rest-Legacy integration layer.
CustSrch (by TaxID/SSN)
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/CustSrch?Count=5&NextOffset=0
{
"TaxId" : "552552239",
"Ver_1": "",
"Ver_2": "",
"Ver_3": "",
"Ver_4": ""
}
CustSrch (by Name)
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/CustSrch?Count=5&NextOffset=0
{
"PersonName": {
"FirstName": "",
"MiddleName": "",
"LastName": "Jones"
}
}
CustSrch (by Name using attributes)
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/CustSrch?Count=5&NextOffset=0
{
"PersonName": {
"ComName": {
"@JHANull": "",
"@Rstr": "",
"@SrchType": "ContainsAll",
"#text": "Tom"
},
"FirstName": "",
"MiddleName": "",
"LastName": ""
}
}
CustInq (by CustomerId)
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/CustInq
{
"CustId": "E000008",
"AccountId": {
"AcctId": "",
"AcctType": ""
},
"IncXtendElemArray": {
"IncXtendElemInfo": [
{
"XtendElem": "x_TaxDetail",
"Ver_1": ""
},
{
"XtendElem": "x_BusDetail",
"Ver_1": ""
}
]
},
"SvcPrvdInfo": {},
"Custom": {}
}
CustAdd
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/CustAdd
{
"ErrOvrRdInfoArray": {
"ErrOvrRd": {
"ErrCode": "410031"
}
},
"CustDetail": {
"PersonName": {
"ComName": "April Smith",
"FirstName": "April",
"LastName": "Smith",
"Ver_1": ""
},
"Addr": {
"StreetAddr1": "100 Twisted Oak",
"StreetAddr2": "Apartment 200",
"City": "CIty",
"StateProv": "",
"StateCode": "AL",
"PostalCode": "351200000",
"Ver_1": "",
"StreetAddr3": "",
"Ver_2": ""
},
"CustType": "Y",
"Gender": "Female",
"PhoneArray": {
"PhoneInfo": {
"PhoneNum": "5555555555",
"PhoneType": "Home",
"Ver_1": "",
"Ver_2": "",
"Ver_3": "",
"Ver_4": ""
}
}
},
"TaxDetail": {
"TINInfo": {
"TINCode": "I",
"TaxId": "123222269",
"Ver_1": "",
"Ver_2": "",
"Ver_3": ""
},
"IRSPostAddr": {
"StreetAddr1": "IRS1 Address",
"StreetAddr2": "IRS2 Address",
"City": "Nashville",
"StateCode": "TN",
"Ver_1": "",
"Ver_2": ""
}
},
"BusDetail": {
"CustCode": "I"
}
}
AcctAdd – Checking
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Deposit/AcctAdd
{
"AccountId": {
"AcctId": "474480",
"AcctType": "D"
},
"DepAdd": {
"DepInfoRec": {
"BrCode": "2" ,
"ProdCode": "CC",
"OpenDt": "2022-07-18",
"AcctClsfCode": "P",
"SerChgWav": "Chg",
"SigVerifyCode": "N",
"CustId": "SAA6135",
"Ver_1": "",
"Ver_2": "",
"Ver_3": "",
"ODPrvlgOptInfoArray": {
"ODPrvlgOptInfoRec": {
"ODPrvlgOptVal": "Accept",
"Ver_1": ""
}
} ,
"Ver_4": "",
"Ver_5": "",
"Ver_6": "",
"Ver_7": ""
} ,
"DepAcctInfo": {
"ClubPln": "",
"ChkGuar": "N",
"ATMCard": "N",
"ClsOnZeroBal": "N",
"HighVolAcctCode": "N",
"LstPostAcctCode": "N",
"Ver_1": "",
"Ver_2": "",
"Ver_3": "",
"Ver_4": "",
"EstbPersonName": {
"ComName": "Harry Houdini",
"FirstName": "Harry",
"MiddleName": "S",
"LastName": "Houdini",
"Ver_1": ""
} ,
"EstbPersonTitle": "Mr.",
"Ver_5": ""
} ,
"DepNSFODInfo": {
"ChgODCode": "N",
"AllowReDepCode": "N",
"ReDepNotCode": "N",
"Ver_1": "",
"Ver_2": "",
"Ver_3": "",
"Ver_4": ""
} ,
"DepStmtInfo": {
"IncCombStmt": "Y",
"StmtCycle": "30",
"IntCycle": "30",
"SerChgCycle": "30",
"ItmTrunc": "NoTrunc",
"ImgPrtChkOrderCode": "N",
"Ver_1": "",
"ElecStmtType": "Email",
"Ver_2": ""
} ,
"Ver_1": "",
"Ver_2": ""
}
}
AcctAdd – Savings
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Deposit/AcctAdd
{
"AccountId": {
"AcctId": "474480",
"AcctType": "S"
},
"DepAdd": {
"DepInfoRec": {
"BrCode": "2",
"ProdCode": "PB",
"OpenDt": "2022-07-18",
"AcctClsfCode": "P",
"SerChgWav": "Chg",
"SigVerifyCode": "N",
"CustId": "SAA6135",
"Ver_1": "",
"Ver_2": "",
"Ver_3": "",
"ODPrvlgOptInfoArray": {
"ODPrvlgOptInfoRec": {
"ODPrvlgOptVal": "Accept",
"Ver_1": ""
}
} ,
"Ver_4": "",
"Ver_5": "",
"Ver_6": "",
"Ver_7": ""
} ,
"DepAcctInfo": {
"ClubPln": "",
"ChkGuar": "N",
"ATMCard": "N",
"ClsOnZeroBal": "N",
"HighVolAcctCode": "N",
"LstPostAcctCode": "N",
"Ver_1": "",
"Ver_2": "",
"Ver_3": "",
"Ver_4": "",
"EstbPersonName": {
"ComName": "Harry Houdini",
"FirstName": "Harry",
"MiddleName": "S",
"LastName": "Houdini"
} ,
"EstbPersonTitle": "Mr."
} ,
"DepNSFODInfo": {
"ChgODCode": "N",
"AllowReDepCode": "N",
"ReDepNotCode": "N"
} ,
"DepStmtInfo": {
"IncCombStmt": "Y",
"StmtCycle": "30",
"IntCycle": "30",
"SerChgCycle": "30",
"StmtPasCode": "Pas",
"ItmTrunc": "NoTrunc",
"ImgPrtChkOrderCode": "N",
"Ver_1": "",
"ElecStmtType": "Email",
"Ver_2": ""
} ,
"Ver_1": "",
"Ver_2": ""
}
}
CustRelAdd – Joint account
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/CustRelAdd
{
"CustId": "SAA6135",
"RelAcctId": "33",
"RelAcctType": "D",
"CustRelRec": {
"AcctRelCode": "J",
"CopyRelCustMail": "N"
}
}
AcctInq – Checking
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/AcctInq
{
"InAcctId": {
"AcctId": {
"#text": "1"
},
"AcctType": {
"#text": "D"
}
},
"IncXtendElemArray": {
"IncXtendElemInfo": [
{
"XtendElem": "x_DepStmtInfo"
},
{
"XtendElem": "x_DepInfoRec"
},
{
"XtendElem": "x_DepBalDtInfo"
},
{
"XtendElem": "x_DepAcctInfo"
},
{
"XtendElem": "x_DepNSFODInfo"
}
]
}
}
AcctSrch – Checking
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/AcctSrch
{
"CustId": "SAA4788",
"AcctType": "D"
}
AddrSrch (by CustomerId)
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/AddrSrch
{
"CustId": "SAA4788"
}
AcctHistSrch – Checking
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/AcctHistSrch
{
"InAcctId": {
"AcctId": {
"#text": "1"
},
"AcctType": {
"#text": "D"
}
}
}
CustAcctRelInq (by CustomerId)
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/CustAcctRelInq
{
"CustId": "SAA4788"
}
EFTCardSrch – Checking
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/EFTCardSrch
{
"InAcctId": {
"AcctId": {
"#text": "1"
},
"AcctType": {
"#text": "D"
}
}
}
XferSrch – Checking
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/XferSrch
{
"InAcctId": {
"AcctId": {
"#text": "1"
},
"AcctType": {
"#text": "D"
}
}
}
AcctMemoPostSrch – Checking
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/AcctMemoPostSrch
{
"InAcctId": {
"AcctId": {
"#text": "1"
},
"AcctType": {
"#text": "D"
}
}
}
NSFHistSrch
https://banno.com/api/translations/v1/jx-rl/institutions/999800100/environments/TEST/Customer/NSFHistSrch
{
"LowAmt": "0.01",
"HighAmt": "1000.00"
}
- Have a how-to question? Seeing a weird error? Get help on StackOverflow.
- Register for the Developer Office Hours where we answer technical Q&A from the audience.