Development Using REST-Legacy

Enterprise SOAP API > Getting Started > Development > Development Using 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 page.
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

REST-Legacy (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 API’s, their use and accompanying documentation. Below is information about the type of security used, the sandbox location, message requirements and JSON examples. The site is IP restricted and requires a configuration by the Developer Relations team to create a Client ID and Secret.

DMZ Environment Access


Authorization Type:	Bearer Token
Security:	Use OAuth2 with a client ID and secret to retrieve your token
Token Server:	`https://jxdmz.jackhenry.com/jxchange/identity/authserver/connect/token`
grant_type:	client_credentials
Scope:	`http://jackhenry.com/auth/jha/jxrl`
ClientID:	Provided by JH
ClientSecret:	Provided by JH

These additional keys must be included on each message request:


`X-AuditUserId`	Vendor determined value
`X-AuditDeviceId`	Vendor determined value
`X-Request-ID`	We recommend a new GUID per request
`X-BusinessCorrelationId`	We recommend a new GUID per request
`X-WorkflowCorrelationId`	We recommend a new GUID per request

API URL Formatting

Base API URL: https://{FQDN}/v1/institutions/{InstRtId}/environments/{InstEnv}/JXRL/{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 created.

The InstRtId and InstEnv values will be unique per institution, as will the client_id and secret.

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	011001276	TEST
CIF 2020	102100552	TEST
Core Director	011111900	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 011001276 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.

Important items to note

A single username and password may be used during initial development against the DMZ jXchange environment. However, for production installs, JHA will provide a unique set of credentials for each institution environment. The jXchange URL, InstRtId, and InstEnv could also vary per production fininacial 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 environment listed above, 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://jxdmz.jackhenry.com/jxchange/identity/authserver/connect/token' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'grant_type=client_credentials' \
     --data-urlencode 'scope=http://jackhenry.com/auth/jha/jxrl' \
     --data-urlencode 'client_id={ClientID}’ \
     --data-urlencode 'client_secret={ClientSecret}’

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 Integration Sandbox (aka DMZ) is a developer focused environment where all consumers are integrating with shared systems of record, whether banking cores, SilverLake, CIF 2020, Core Director and Episys, or complimentary products such as Synergy and Synapsys. The nature of this environment does not necessarily lend itself to Third Party Vendor product demonstrations utilizing 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, Tutorials and Sample Data

See Commonly Used APIs for a quick list of apis that are most used when consuming jXchange APIs. 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.

Sample data is provided to assist with starting your development journey. Within the SOAP Documentation page, locate the file named DMZTestAccounts_SL_2020_CoreDirector_Episys.

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://jx-rl-rest-proxy-alpha.dev.ipaas.jha-sys.com/v1/institutions/011001276/environments/TEST/JXRL/Customer/CustSrch?Count=5&NextOffset=0

CustSrch (by TaxID/SSN)

{
"TaxId" : "552552239",
  "Ver_1": "",
  "Ver_2": "",
  "Ver_3": "",
  "Ver_4": ""
}

CustSrch (by Name)

https://jx-rl-rest-proxy-alpha.dev.ipaas.jha-sys.com/v1/institutions/011001276/environments/TEST/JXRL/Customer/CustSrch?Count=5&NextOffset=0

CustSrch (by Name)

{
  "PersonName": {
    "FirstName": "",
    "MiddleName": "",
    "LastName": "Jones"
  }
}

CustSrch (by Name using attributes)

https://jx-rl-rest-proxy-alpha.dev.ipaas.jha-sys.com/v1/institutions/011001276/environments/TEST/JXRL/Customer/CustSrch?Count=5&NextOffset=0

CustSrch (by Name using attributes)

{
  "PersonName": {
   "ComName": {
            "@JHANull": "",
            "@Rstr": "",
            "@SrchType": "ContainsAll",
            "#text": "Tom"
          },
    "FirstName": "",
    "MiddleName": "",
    "LastName": ""
  }
}

CustInq (by CustomerId)

https://jx-rl-rest-proxy-alpha.dev.ipaas.jha-sys.com/v1/institutions/011001276/environments/TEST/JXRL/Customer/CustInq

CustInq (by CustomerId)

{
  "CustId": "E000008",
  "AccountId": {
    "AcctId": "",
    "AcctType": ""
  },
   "IncXtendElemArray": {
         "IncXtendElemInfo": [
            {
               "XtendElem": "x_TaxDetail",
               "Ver_1": ""
            },
            {
               "XtendElem": "x_BusDetail",
               "Ver_1": ""
            }
         ]
      },
  "SvcPrvdInfo": {},
  "Custom": {}
}

CustAdd

https://jx-rl-rest-proxy-alpha.dev.ipaas.jha-sys.com/v1/institutions/011001276/environments/TEST/JXRL/Customer/CustAdd

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://jx-rl-rest-proxy-alpha.dev.ipaas.jha-sys.com/v1/institutions/011001276/environments/TEST/JXRL/Deposit/AcctAdd

AcctAdd – Checking

{
    "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://jx-rl-rest-proxy-alpha.dev.ipaas.jha-sys.com/v1/institutions/011001276/environments/TEST/JXRL/Deposit/AcctAdd

AcctAdd – Savings

{
    "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://jx-rl-rest-proxy-alpha.dev.ipaas.jha-sys.com/v1/institutions/011001276/environments/TEST/JXRL/Customer/CustRelAdd

CustRelAdd – Joint account

{
    "CustId": "SAA6135",
    "RelAcctId": "33",
    "RelAcctType": "D",
    "CustRelRec": {
        "AcctRelCode": "J",
        "CopyRelCustMail": "N"
    }
}

Have a Question?

Have a how-to question? Seeing a weird error? Get help on StackOverflow.

Register for the Digital Toolkit Meetup where we answer technical Q&A from the audience.

Last updated Thu Jul 14 2022