PhoenixXM

Category: Core Connectors

Market: US

Overview

The PhoenixXM connector exposes REST endpoints under /phoenixxm/v1 and translates JSON requests into Finastra PhoenixXM XAPI SOAP operations.

The connector provides:

  • Customer/member onboarding (RIM record creation)
  • Deposit and ATM account creation
  • Customer search and lookup by name, RIM, TIN, phone, or account
  • Account and email inquiries
  • DepositPro flows (product data, forms, CIP/eSign config, and TIS submission)

The connector handles token acquisition and caching, Phoenix operation routing, and Phoenix error normalization.

Vault Configuration

Key Description
phoenixxmUrl PhoenixXM SOAP endpoint template. Supports <BankID>, {BankID}, ${BankID} placeholder replacement.
bankId Bank identifier injected into the URL template.
phoenixxmConnString Phoenix connection string passed in auth/process calls.
phoenixDefaultEmployeeId Employee ID used in Phoenix user context.
phoenixServiceId Service/application ID used for Phoenix authentication.
phoenixServiceSecretKey Service secret key used for Phoenix authentication.

Example Vault Configuration

Copy 
{
                "phoenixxmUrl": "https://<host>/<BankID>/ST1_WS/phoenixxm.asmx",
                "bankId": "2669",
                "phoenixxmConnString": "",
                "phoenixDefaultEmployeeId": "8859",
                "phoenixServiceId": "1003",
                "phoenixServiceSecretKey": "******"
        }

Customer and Account Onboarding

Endpoints

Endpoint Method Description
/finastra/v1/phoenixxm/customers POST Create a new Phoenix customer/member (RIM).
/finastra/v1/phoenixxm/deposits POST Create a new deposit account.
/finastra/v1/phoenixxm/atm-accounts POST Create ATM account, card, and relations.

 

Create Customer

POST /finastra/v1/phoenixxm/customers

Request Structure

Copy 
{
  "rmAcct": {},
  "rmAddress": [],
  "rmPersonalInfo": {},
  "rmRel": [],
  "rmUserDefVal": [],
  "rmIdent": {},
  "rmNonPersonalInfo": {},
  "dpUmb": {},
  "dpUmbBene": []
}

Sample Request

Copy 
{
  "rmAcct": {
    "new": "",
    "classCode": 100,
    "lastName": "Wayne",
    "rimType": "Personal",
    "branchNo": 1,
    "firstName": "Bruce",
    "tin": "123-34-2345",
    "tinFormat": "S"
  },
  "rmAddress": [
    {
      "new": "",
      "addrTypeId": 1,
      "addressLine1": "1007 Mountain Dr",
      "city": "Gotham",
      "state": "NJ",
      "zip": "07001"
    }
  ]
}

Sample Response

Copy 
{
  "response": {
    "record": {
      "rmAcct": {
        "rimNo": 74846
      }
    }
  },
  "returnCode": 0
}

Create Deposit

POST /finastra/v1/phoenixxm/deposits

Request Structure

Copy 
{
  "dpAcct": {},
  "createNewCustomer": {},
  "dpUmb": {},
  "dpUmbBene": [],
  "dpAcctIntOpt": [],
  "dpUserDefVal": [],
  "gbCombStmt": {},
  "gbCombStmtAcct": {},
  "gbCombStmtAddr": [],
  "gbMapAcctRel": [],
  "gbMapAcctImage": [],
  "gbServices": [],
  "gbAdditionTitles": [],
  "generateAccountNumberRequest": {
    "outputDepLoan": "string",
    "acctType": "string"
  }
}

Sample Request

Copy 
{
  "dpAcct": {
    "new": "",
    "rimNo": 21535,
    "acctType": "CK",
    "acctNo": "",
    "classCode": 100,
    "title1": "Test CK Account",
    "branchNo": 1,
    "rsmId": 1
  }
}

Sample Response

Copy 
{
  "record": {
    "dpAcct": {
      "acctNo": "965437"
    }
  },
  "returnCode": 0
}

Create ATM Account

POST /finastra/v1/phoenixxm/atm-accounts

Request Structure

Copy 
{
  "atmAcct": {},
  "atmCard": [],
  "atmRelAcct": [],
  "atmUserDefVal": []
}

Validation: atmAcct is required.

Sample Request

Copy 
{
  "atmAcct": {
    "new": "",
    "rimNo": 21535,
    "atmAcctNo": "",
    "atmAcctType": "V11"
  },
  "atmCard": [
    {
      "new": "",
      "rimNo": 21535,
      "atmAcctType": "V11",
      "atmAcctNo": "",
      "branchNo": 1,
      "cardMailer": "Y"
    }
  ],
  "atmRelAcct": [
    {
      "new": "",
      "atmAcctType": "V11",
      "atmAcctNo": "",
      "acctType": "SV",
      "acctNo": "5025-187"
    }
  ]
}

Sample Response

Copy 
{
  "record": {
    "atmAcct": {
      "atmAcctType": "V11",
      "atmAcctNo": "000058128"
    }
  },
  "returnCode": 0
}

Search and Inquiry

Endpoints

Endpoint Method Description
/finastra/v1/phoenixxm/customers/search POST Search customers by name criteria.
/finastra/v1/phoenixxm/customers/search/rim POST Search by RIM number.
/finastra/v1/phoenixxm/customers/search/tin POST Search by TIN.
/finastra/v1/phoenixxm/customers/search/phone POST Search by phone number.
/finastra/v1/phoenixxm/customers/search/account POST Search by account number.
/finastra/v1/phoenixxm/customers/accounts POST Get customer accounts.
/finastra/v1/phoenixxm/customers/emails POST Get customer email addresses.

Search Customers

POST /finastra/v1/phoenixxm/customers/search*

All search endpoints share the same request structure. The connector routes the request based on which fields are populated:

  • /search/rim uses rimNo
  • /search/tin uses tin
  • /search/phone uses phone
  • /search/account uses tranAcct.acctNo
  • /search uses name fields (lastName/firstName)

Request Structure

Copy 
{
  "tranInfo": {
    "referenceNo": "string",
    "xapiTranCode": "13005"
  },
  "lastName": "string",
  "firstName": "string",
  "rimNo": "string",
  "tin": "string",
  "phone": "string",
  "defPhoneFormat": "string",
  "tranAcct": {
    "acctNo": "string"
  }
}

Note: Customer search enforces Phoenix transaction code 13005 server-side. The connector overrides any client-provided transaction code.

Get Customer Accounts

POST /finastra/v1/phoenixxm/customers/accounts

Copy 
{
  "tranInfo": {
    "xapiTranCode": "13015"
  },
  "rimNo": "string",
  "tranAcct": {},
  "outputDepLoan": "string",
  "closedDt": "string"
}

Get Customer Emails

POST /finastra/v1/phoenixxm/customers/emails

Copy 
{
  "rimNo": "string",
  "relRimNo": "string"
}

Validation: rimNo is required.

Update Operations

Endpoints

Endpoint Method Description
/finastra/v1/phoenixxm/accounts/generate-number POST Generate a new account number.
/finastra/v1/phoenixxm/customers/emails/create POST Create a customer email address.

Generate Account Number

POST /finastra/v1/phoenixxm/accounts/generate-number

Copy 
{
  "outputDepLoan": "string",
  "acctType": "string"
}

Create Customer Email

POST /finastra/v1/phoenixxm/customers/emails/create

Copy 
{
  "tranInfo": {},
  "rimNo": "string",
  "relRimNo": "string",
  "email": "string",
  "sendStmtAlert": "Y|N"
}

Validation: rimNo and email are required.

DepositPro

Endpoints

Endpoint Method Description
/finastra/v1/phoenixxm/deposit-pro/product-data GET Retrieve product data.
/finastra/v1/phoenixxm/deposit-pro/forms POST Retrieve forms.
/finastra/v1/phoenixxm/deposit-pro/cip-config GET Retrieve CIP configuration.
/finastra/v1/phoenixxm/deposit-pro/esign-config GET Retrieve eSign configuration.
/finastra/v1/phoenixxm/deposit-pro/tis POST Submit TIS (Transaction Integration Services).

Get Product Data

GET /finastra/v1/phoenixxm/deposit-pro/product-data

Parameter Type Required Description
depositProProdType string No Product type filter
depositProProduct string No Product filter
acctType string No Account type filter
classCode string No Class code filter

Get Forms

POST /finastra/v1/phoenixxm/deposit-pro/forms

Copy 
{
  "depositProTransNumber": "string",
  "depositProFormName": "string"
}

Validation: Both fields are required.

Get CIP Config

GET /finastra/v1/phoenixxm/deposit-pro/cip-config

No request body required.

Get eSign Config

GET /finastra/v1/phoenixxm/deposit-pro/esign-config

No request body required.

Submit TIS

POST /finastra/v1/phoenixxm/deposit-pro/tis

Copy 
{
  "rmAcct": [],
  "rmAddress": [],
  "rmNonPersonalInfo": [],
  "rmPersonalInfo": [],
  "rmIdent": [],
  "rmRel": [],
  "rmCipAdditional": [],
  "rmTrust": [],
  "rmTrustCapacity": [],
  "dpAcct": [],
  "dpAcctIntOpt": [],
  "gbMapAcctRel": [],
  "depositproEsignAuth": [],
  "depositproAuthQa": []
}

Error Handling

Errors follow the platform-standard problem JSON format. Request validation errors and Phoenix application-level errors are classified by the connector. Transport, timeout, and dependency failures are classified by the Data Core platform.

Error Response Format

Copy 
{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Dependency failure",
  "code": "Server",
  "instance": "/finastra/v1/phoenixxm/customers/search/phone",
  "timestamp": "2026-06-16T12:51:12Z",
  "dependency": {
    "status": 500,
    "title": "Server was unable to process request. ...",
    "detail": "..."
  }
}
  • code carries the upstream SOAP fault code when present (for example, Server); otherwise it contains the mapped HTTP status.
  • dependency is present only for upstream/transport failures, not for client validation or 500 errors.

HTTP Status Codes

Status Meaning Triggered By
200 Success Successful call; body contains the XAPI response.
400 Bad Request (validation) Invalid or missing fields, malformed JSON, bean-validation failure.
400 Bad Request (Phoenix business rule) PhoenixXM returned HTTP 200 with non-zero ReturnCode/Rc/UserReturnCode or an E-severity message.
403 Forbidden Access denied.
4xx Passthrough Upstream returned a 4xx (preserved as-is). Upstream 401/403 are remapped to 502.
500 Internal Server Error Unexpected runtime error not otherwise classified.
502 Bad Gateway Phoenix system/auth failure (__SystemException tag), upstream 5xx (other than 503/504), upstream 401/403, repeated 401 after token refresh.
503 Service Unavailable Connection refused, DNS failure, no route to host, TLS/SSL failure.
504 Gateway Timeout Connect/read/request timeout reaching PhoenixXM.

Dependency Status Mapping

Upstream Status Returned Status
401, 403 502
Other 4xx Same status (passthrough)
503 503
504 504
Other 5xx 502

PhoenixXM Application-Level Codes

PhoenixXM always responds over HTTP 200, even on failure. The connector inspects the XAPI_RESPONSE and classifies errors as follows:

  • System error: A message tagged __SystemException maps to 502.
  • Business error: Non-zero ReturnCode / Rc / UserReturnCode, or a message with MsgSeverity = E maps to 400.
  • No error: Passes through unchanged (200), including empty search results.

The Phoenix ReturnCode / UserReturnCodeDesc is propagated into the response detail field. These codes are defined by Phoenix; consult the PhoenixXM Technical Guide for their meaning.