UTA Bank of America CashPro API Integration Specification

Version: 1.0 (Draft) Project: Sub-Ledger Automation — AR & Treasury Replacement Primary Engine: CashPro Payments V2 API (JSON for RTP/SEPA Instant; ISO XML for all other payment types) [SOURCE: BofA Integration Manager Kim, March 2026] Audit Rail: CashPro Reporting API (JSON, on-demand) + BAI2/H2H File Delivery [SOURCE: BofA Integration Manager Kim, March 2026] Developer Portal: https://developer.bankofamerica.com

Architecture Note — Kim's Recommendation (BofA Integration Manager): This integration follows the channel guidance provided directly by BofA:
Payments: ISO XML via API is the recommended default for most payment types (Fed Wire, ACH Credits, FX/International Wire), offering immediate response and real-time status inquiry. JSON is used for US RTP and SEPA Instant only, as those types receive accelerated processing via the JSON path.
ACH Debits: File-only (NACHA direct transmission to BofA ACH system). ACH Debits are not available via API and are out of scope for this integration's API layer.
Reporting: JSON API is the recommended channel for balances and transaction data, enabling on-demand real-time calls rather than waiting for scheduled file delivery.
Collections (Press X Debit files): Direct NACHA transmission. Out of scope for API layer.
[SOURCE: BofA Integration Manager Kim, March 2026]

Isolation Rule: This document is exclusively for Bank of America / CashPro. No CNB or JPM behavior, endpoint patterns, field names, or logic may be borrowed or inferred. Every field, endpoint, and behavior in this document is cited to a specific CashPro Developer Studio page or tagged [CONFIRM with BofA].

Scope Boundary: UTA's BofA accounts are US-domiciled. UK, EU, Brazil, HK, and Indonesia payment types are documented in the Kim matrix for completeness but are tagged [OUT OF SCOPE — US ACCOUNTS ONLY] unless UTA confirms cross-border requirements.

Scope boundary — and who owns what. This document covers the UTA ↔ BofA CashPro integration boundary only at two layers:

The wire contract — what data crosses, in what format, on what schedule, via which channel, with which credentials. Documented per service in §1–§13.
The business requirements UTA imposes on each call at the integration boundary — when to call each endpoint, what to do with the response payload, how to handle each exception class at the integration boundary. Examples already documented inline: §3's ISO XML vs. JSON channel split (RTP/SEPA Instant on the JSON path, all other payment types on ISO XML), §4's polling cadence and terminal-state criteria for RTP/SEPA Instant status, §7's webhook dedup-and-acknowledgment rules for CashPro Intraday push notifications, §8's inbound-credit handling for Payment Receipts, §12's BAI2/EOD lock that anchors §13's Three-Way Match reconciliation. Cliff (Product) owns this layer.

Three-document set required for full implementation:

Doc	Owner	Covers	Status
(A) This spec — UTA ↔ BofA CashPro integration spec	Cliff	The integration boundary: wire contract + integration-boundary requirements (above)	In flight (v1 — open items in Appendix A)
(B) Client Processing behavior spec — what inside Client Processing triggers integration calls and processes the resulting payloads	Cliff (Product)	The upstream business-rules layer: AR-side matching rules, GL-posting cadence, settlement-payout triggers, refund-authorization workflow, rail-selection policy (when to choose RTP vs. ACH vs. Wire), manual-review queue ownership, reconciliation rules	Not yet started — Cliff to scope and draft
(C) Engineering design doc — class decomposition, queue architecture, retry semantics, error-handling matrices, webhook-receiver structure	Amir's engineering team	The technical implementation of (A) + (B)	Drafted by Amir's team after (A) and (B) are both ready

This spec (A) alone is not sufficient input for engineering — (C) needs both the integration contract (A) AND the Client Processing behavior (B) to design against. Without (B), the engineering team can build the CashPro-facing plumbing (webhook receiver, ISO XML payment-submission pipeline, JSON polling loop, OAuth + cert-refresh scheduling) but won't know what inside Client Processing fires it or how the data is consumed once received.

Within this spec (A) only: if implementation surfaces a requirement gap at the integration boundary (an exception class with no documented handling rule, an unspecified polling cadence on the Reporting API, a webhook-replay edge case, an ISO XML rejection scenario, a JWS/JWE failure path), Amir's team flags it back to Cliff for a requirements decision, which gets landed in this spec — not in the engineering design. Requirement gaps inside Client Processing (matching rules, GL posting, refund authorization, rail-selection policy) land in (B), not (A).

Authentication & Security
Account Pre-Validation ("Pre-Flight")
Payment Initiation (RTP / ACH / Wire)
Payment Status Inquiry (Polling)
The Two-Step FX Lock (International Wire)
Stop Payment / Check Management
Intraday "Engine" (Push Notifications / Webhooks)
Payment Receipts (Incoming AR)
Error Codes & Debugging
Account Balances API
Transaction Details / Reporting
BAI2 / End-of-Day "Brakes"
Reconciliation Logic (Three-Way Match)
Kim's Integration Matrix (Reference)

1. Authentication & Security

1.1 Security Stack

CashPro APIs use a layered security model confirmed in BofA product materials: [SOURCE: CashPro API Client Presentation, p. 4]

Layer	Technology	Scope
Authentication	OAuth 2.0	All API calls
Transport Security	Mutual TLS (mTLS)	All API calls
Payload Encryption	JSON Web Encryption (JWE)	Sensitive payloads
Payload Signing	JSON Web Signatures (JWS)	Payment initiation

1.2 OAuth Token Acquisition

Pattern: Client Credentials grant. The sub-ledger exchanges a clientID and clientSecret for a Bearer access token, which is then passed in the Authorization header of every subsequent API call. [SOURCE: CashPro Developer Studio — OAuth Token Push Notification page]

Token Endpoint URL: [CONFIRM with BofA] — The OAuth token endpoint URL is not exposed in the Developer Studio pages provided. BofA's STS domain observed in a sample JWT payload is sts-int.bankofamerica.com (internal/test environment). The production token endpoint must be confirmed during onboarding.

Token Request (inferred from Push Notification auth page):

POST [CONFIRM: OAuth token endpoint]
Content-Type: application/json

{
  "clientID": "ACME1099_BD129A34",
  "clientSceret": "NFMIJSnPiE2296d2sH0AM0PBLZZRytpU6O0QMChVXJns4NNT8tn28JuobrXINY8T"
}

Note: clientSceret is the exact field name as documented in the Developer Studio — this appears to be a BofA typo in their spec. Use this exact spelling until BofA confirms otherwise. [CONFIRM with BofA]

Token Response:

json

{
  "accessToken": "eyJhbGciOiJSUzM4NCIsImtpZCI6InByb2QiLCJ4NXQiOiJIanRmUFR0QVZrbFI4dkE2QURVZDVxRWpEc1EifQ...",
  "status": "SUCCESS"
}

[SOURCE: CashPro Developer Studio — OAuth Token Push Notification page]

Usage: All API calls include the token as Authorization: Bearer [accessToken].

Token TTL: [CONFIRM with BofA] — TTL not specified in provided documentation.

1.3 API Base URL

[CONFIRM with BofA] — The production API base URL is not stated in the Developer Studio pages provided. All endpoint paths in this document use the relative path only (e.g., /cashpro/payments/v2/payment-initiations). The full production URL must be confirmed during onboarding at developer.bankofamerica.com.

1.4 Idempotency

All payment initiation endpoints require an X-Idempotency-Key header — a unique identifier (up to 256 characters) that prevents duplicate submissions. [SOURCE: CashPro Developer Studio — Payments V2 Initiation, Repetitive Payments pages]

Rule: The sub-ledger must generate a fresh UUID for each new payment attempt. If retrying a failed request with the same payload, reuse the original key. If the payload has changed, generate a new key.

1.5 Company Identifier

Several endpoints require a companyId header — the CashPro Company ID (up to 15 characters). [SOURCE: CashPro Developer Studio — Check Issues and Cancels page]

[CONFIRM with BofA] — Confirm UTA's assigned CashPro Company ID value during onboarding.

1.6 Environments

[CONFIRM with BofA] — The Developer Studio references a sandbox environment ("Design and test in our sandbox") at developer.bankofamerica.com but does not provide explicit sandbox vs. production base URLs in the pages provided. Confirm sandbox URL and credential provisioning process during technical onboarding. [SOURCE: CashPro API Client Presentation, p. 7]

Onboarding steps per BofA:

Register at developer.bankofamerica.com
Design and test in sandbox
Request production deployment
Go live [SOURCE: CashPro API Client Presentation, p. 7]

2. Account Pre-Validation ("Pre-Flight")

The sub-ledger runs pre-flight checks before any payment is initiated. BofA provides three distinct validation APIs depending on payment type.

2.1 US Account Validation (ACH / Wire Pre-Flight)

Purpose: Validates the status and ownership of a US bank account prior to initiating ACH credits, ACH debits, wire transfers, or RTP. Transmits account information to the National Shared Database (NSD) and returns results asynchronously. [SOURCE: CashPro Developer Studio — US Account Validation page]

Endpoint: POST /validation/v1/accounts [SOURCE: CashPro Developer Studio — US Account Validation page]

Key Business Rules: [SOURCE: CashPro Developer Studio — US Account Validation page]

Reduces risk of payments to fraudulent entities and misdirected payments.
Faster than pre-notification or micro-deposit methods.
Complies with NACHA WEB Debit Rule.
The NSD does not cover 100% of all US accounts. If results are insufficient to validate, an alternate method is required (direct contact, pre-notification, micro-deposit, or check for B2B).
Results are delivered asynchronously via a webhook callback. The sub-ledger must expose a callback endpoint to receive validation results.

[CONFIRM with BofA] — The full request/response schema for the US Account Validation endpoint was not available in the Developer Studio pages provided (only the overview was pasted). Confirm: (1) request body field names and required parameters, (2) response field names and status values, (3) callback/webhook payload schema for async result delivery, (4) timing SLA for validation response.

Possible Outcomes: Match, Close Match, No Match, Verification Check Not Possible.

Integration Rule: If validation returns No Match or Check Not Possible, escalate to the AR team before proceeding. Do not automatically reject — the NSD is not exhaustive.

2.2 US RTP Network Membership Validation

Purpose: Confirms whether a US financial institution is a member of The Clearing House RTP network before initiating an RTP payment. [SOURCE: CashPro Developer Studio — US RTP Validation page]

Endpoint: POST /validation/v1/usrtp [SOURCE: CashPro Developer Studio — US RTP Validation page]

Request:

json

{
  "countryCode": "US",
  "memberBankId": "123456789",
  "schemeName": "USRTP"
}

[SOURCE: CashPro Developer Studio — US RTP Validation page]

Response (200):

json

{
  "countryCode": "US",
  "isMember": true,
  "memberBankId": "123456789",
  "reason": [
    {
      "reasonCode": "000",
      "reasonDescription": "Success"
    }
  ],
  "schemeName": "USRTP"
}

[SOURCE: CashPro Developer Studio — US RTP Validation page]

Integration Rule: If isMember is false, the sub-ledger must automatically downgrade the payment to ACH. Per BofA product documentation, BofA can either reject or route to ACH if the beneficiary bank is not RTP-enabled. Confirm BofA's default behavior for this integration. [CONFIRM with BofA]

2.3 Zelle Token Validation

Purpose: Determines a recipient's Zelle enrollment status before initiating a Zelle payment. [SOURCE: CashPro Developer Studio — Zelle Token Validation page]

Endpoint: POST /validation/v1/zelle/aliastoken/verify [SOURCE: CashPro Developer Studio — Zelle Token Validation page]

Possible Status Values: [SOURCE: CashPro Developer Studio — Zelle Token Validation page]

Status	Meaning
`Active`	Enrolled and available to send/receive
`Inactive`	Not registered or previously unregistered
`Opted Out`	Token opted out; cannot register or transact
`Restricted`	Blocked in EWS; cannot send/receive

[CONFIRM with BofA] — Full request/response schema not available in provided pages (only overview pasted). Confirm field names and response structure.

2.4 SEPA Verification of Payee

[OUT OF SCOPE — US ACCOUNTS ONLY] — Documented for completeness. SEPA VOP validates account name against IBAN before initiating SEPA payments. Four outcomes: Match, Close Match, No Match, Verification Check Not Possible. [SOURCE: CashPro Developer Studio — SEPA Verification of Payee page]

Endpoint: POST /validation/v1/accounts [SOURCE: CashPro Developer Studio — SEPA Verification of Payee page]

Note: The US Account Validation and SEPA VOP endpoints share the same path /validation/v1/accounts. The differentiating factor is the payload schema and the entitled payment type. [CONFIRM with BofA] — Confirm whether these are truly the same endpoint with different schemas, or if there is a routing header/parameter that distinguishes them.

3. Payment Initiation (RTP / ACH / Wire)

3.1 Channel Architecture Decision

Per Kim's recommendation, UTA uses two channels for payment initiation: [SOURCE: BofA Integration Manager Kim, March 2026]

Payment Type	Channel	Reason
US RTP	JSON API (`/cashpro/payments/v2/payment-initiations`)	Faster processing than XML
SEPA Instant	JSON API	Faster processing than XML
Fed Wire (Domestic)	ISO XML API (`/cashpro/payments/v2/isoxml-transfers`)	Recommended default
Swift / USD International	ISO XML API	Recommended default
FX Wire	ISO XML API	Recommended default
ACH CCD/PPD Credits	ISO XML API	Recommended default; batch-forwarded, no speed difference
ACH CTX Credits	ISO XML API	Recommended default
ACH Debits	NACHA file only — OUT OF SCOPE for API	Not available via API

3.2 Payments V2 Initiation — JSON (US RTP and SEPA Instant)

Endpoint: POST /cashpro/payments/v2/payment-initiations [SOURCE: CashPro Developer Studio — Payments V2 Initiation - JSON page]

Required Headers:

Header	Description
`Authorization`	`Bearer [accessToken]`
`Content-Type`	`application/json`
`X-Idempotency-Key`	Unique identifier, 1–256 characters

[SOURCE: CashPro Developer Studio — Payments V2 Initiation - JSON page (header list from V1 Initiation page, which exposes the schema)]

US RTP Key Facts: [SOURCE: CashPro Developer Studio — Payments V2 Initiation - JSON page]

24/7/365 availability
Transactions up to $10,000,000
Completed in 15 seconds or less
Immediate and final settlement; irrevocable
If beneficiary bank is not RTP-enabled, BofA can reject or route to ACH

Request Schema (inferred from V1 Initiation and Repetitive Template schemas — primary structure):

json

{
  "amount": {
    "type": "CREDIT",
    "value": "1.00"
  },
  "creditor": {
    "name": "Beneficiary Name",
    "postalAddress": {
      "addressLine": ["Beneficiary Address Line 1"],
      "city": "Beneficiary City",
      "country": "US"
    }
  },
  "creditorAccount": {
    "currency": "USD",
    "identification": "[Account Number]",
    "schemeName": "BBAN"
  },
  "creditorAgent": {
    "institution": {
      "identifiers": [
        {
          "identification": "[Routing Number]",
          "schemeName": "USABA"
        }
      ],
      "name": "[Bank Name]"
    }
  },
  "debtorAccount": {
    "currency": "USD",
    "identification": "[UTA Account Number]",
    "schemeName": "BBAN"
  },
  "debtorAgent": {
    "institution": {
      "identifiers": [
        {
          "identification": "BOFAUS3N",
          "schemeName": "BIC"
        }
      ]
    }
  },
  "paymentIdentification": {
    "endToEndIdentification": "[UTA Reference, max 35 chars]",
    "instructionIdentification": "[UTA UID, max 35 chars]"
  },
  "paymentMethod": "TRF",
  "paymentType": {
    "serviceLevel": "SDVA"
  },
  "requestedExecutionDate": "2026-03-04",
  "unstructuredRemittance": "[Remittance info / invoice reference]"
}

[SOURCE: CashPro Developer Studio — Payments V1 Initiation page (request schema); Repetitive Payments Template Information (single) page (full creditInitiation schema)]

[CONFIRM with BofA] — The V2 JSON Initiation page only showed the API overview, not the Code/schema tab. Confirm whether the V2 request schema differs materially from the V1 schema shown above, particularly the paymentType.serviceLevel value for RTP (SDVA vs. another code).

Response (200):

json

{
  "endToEndIdentification": "SenderRefSIT18",
  "paymentStatus": "Rejected By Bank",
  "reason": [
    {
      "reasonCode": "CP700",
      "reasonDescription": "Invalid transaction status for cancel"
    }
  ],
  "transactionIdentification": "1234567890ABC"
}

[SOURCE: CashPro Developer Studio — Payments V2 Status - JSON page (status response schema)]

Key Fields:

Field	Description
`transactionIdentification`	BofA-assigned bank reference. This is the primary key for all subsequent status and cancellation calls. Store this value immediately upon response.
`endToEndIdentification`	UTA's end-to-end reference echoed back
`paymentStatus`	Current status string (see §9 for status values)

3.3 Payments V2 Initiation — ISO XML (Wire / ACH Credits)

Endpoint: POST /cashpro/payments/v2/isoxml-transfers [SOURCE: CashPro Developer Studio — Payments V2 Initiation - ISO XML page]

Content Type: multipart/form-data [SOURCE: CashPro Developer Studio — Payments V2 Initiation - ISO XML page]

Note: The ISO XML channel uses multipart/form-data rather than application/json. The XML payload is submitted as a file attachment. This is architecturally different from CNB and JPM.

[CONFIRM with BofA] — The full ISO XML schema was not included in the Developer Studio pages provided. Request the complete ISO XML pain.001 message specification from BofA, including: (1) exact XML namespace and version, (2) required vs. optional element set for each US payment type (ACH CCD, ACH PPD, Fed Wire), (3) BofA-specific extensions or mandatory fields not in the base ISO 20022 standard, (4) maximum file size and batch size limits.

Required Headers:

Header	Description
`Authorization`	`Bearer [accessToken]`
`X-Idempotency-Key`	Unique identifier, 1–256 characters

[SOURCE: CashPro Developer Studio — Payments V2 Status - ISO XML page]

File ID: The response will return a fileId which is the reference used for all subsequent status calls on ISO XML submissions. Store this separately from the JSON transactionIdentification.

3.4 Payments V1 Initiation (Legacy — Requires CashPro Online Approval)

Endpoint: POST /cashpro/payments/v1/payment-initiations [SOURCE: CashPro Developer Studio — Payments V1 Initiation page]

Architecture Note: V1 payments are placed in PEND_APPROV status and require manual approval in CashPro Online or CashPro Mobile before processing. This is NOT suitable for automated sub-ledger workflows. V2 is the correct channel for this integration. V1 is documented here for completeness only.

Response (200):

json

{
  "mid": "1234567890ABC",
  "paymentStatus": "PEND_APPROV"
}

[SOURCE: CashPro Developer Studio — Payments V1 Initiation page]

3.5 Payment Cancellation

Endpoint: POST /cashpro/payments/v2/payment-initiations/cancellation [SOURCE: CashPro Developer Studio — Payments V2 Cancellation page]

Supported Payment Types for Cancellation: [SOURCE: CashPro Developer Studio — Payments V2 Cancellation page]

Brazil RTP Pix
Canada Interac
PayPal
Recipient Select
Venmo
US Fedwire
US Real Time Payments
Zelle

Key Rule: Cancellation must be received and executed prior to final settlement. Use the Payment Status API (§4) to check whether a payment is still cancellable before submitting.

[CONFIRM with BofA] — Confirm the request body schema for the Cancellation endpoint. The Developer Studio page showed only the overview, not the Code tab. The transactionIdentification from the initial payment response is required in the payload per the API description.

ACH Credits: ACH is not listed as cancellable via this API. [CONFIRM with BofA] — Confirm whether ACH credits can be cancelled, and if so, via what mechanism and within what time window.

4. Payment Status Inquiry (Polling)

4.1 JSON Payment Status

Endpoint: GET /cashpro/payments/v2/payment-initiations/status [SOURCE: CashPro Developer Studio — Payments V2 Status - JSON page]

Required Headers:

Header	Description
`Authorization`	`Bearer [accessToken]`
`TransactionIdentification`	BofA-assigned transaction ID from the initiation response. Length: 1–36.

[SOURCE: CashPro Developer Studio — Payments V2 Status - JSON page]

Response (200):

json

{
  "endToEndIdentification": "SenderRefSIT18",
  "paymentStatus": "Rejected By Bank",
  "reason": [
    {
      "reasonCode": "CP700",
      "reasonDescription": "Invalid transaction status for cancel"
    }
  ],
  "transactionIdentification": "1234567890ABC"
}

[SOURCE: CashPro Developer Studio — Payments V2 Status - JSON page]

4.2 ISO XML Payment Status

Endpoint: GET /cashpro/payments/v2/isoxml-transfers/status [SOURCE: CashPro Developer Studio — Payments V2 Status - ISO XML page]

Required Headers:

Header	Description
`Authorization`	`Bearer [accessToken]`
`X-Idempotency-Key`	Original idempotency key used for the submission
`fileId`	File identifier returned at ISO XML submission time

[SOURCE: CashPro Developer Studio — Payments V2 Status - ISO XML page]

Response (200):

json

{
  "statusResponse": [
    {
      "reason": [
        {
          "reasonCode": "CPS-ENT-001",
          "reasonDescription": "Entitlement SenderID Failed"
        }
      ],
      "status": "Unsuccessful",
      "transaction": [
        {
          "endToEndIdentification": "2L2TLL1J42JK",
          "reason": [
            {
              "reasonCode": "VDT-VAL-007",
              "reasonDescription": "Value Date cannot be older than 30 days."
            }
          ],
          "status": "Rejected",
          "tranId": "T0MAPD66OJNMDGDC"
        }
      ],
      "transactionIdentification": "FS1APD54L2RZ0MCL"
    }
  ]
}

[SOURCE: CashPro Developer Studio — Payments V2 Status - ISO XML page]

Note: The ISO XML status response is hierarchical — a file-level status wraps individual transaction-level statuses. A file can be Unsuccessful at the outer level (e.g., entitlement failure) while individual transactions have their own status and reason codes.

4.3 Polling Strategy

Per Kim's recommendation, most clients opt to originate status requests (polling) rather than relying exclusively on push notifications. The recommended cadence is: [SOURCE: BofA Integration Manager Kim, March 2026]

For wires: Poll within 1 minute of origination, then at 5-minute intervals until a terminal status is reached.
For RTP: Expect completion within 15 seconds; poll at 30-second intervals up to 3 times.
For ACH: No real-time benefit — ACH is batched. Poll once daily after the expected settlement window.

[CONFIRM with BofA] — Confirm whether there is a rate limit on status polling calls, and the recommended maximum polling frequency to avoid throttling.

5. The Two-Step FX Lock (International Wire)

Architecture Note: For international wire payments requiring currency conversion, BofA supports two distinct FX models: (1) spot rate applied at execution — no pre-booking required; (2) pre-booked trade settlement — client books a trade via the FX Trading API, then submits the settlement instruction via the Payments V2 API with the trade reference. [SOURCE: CashPro Developer Studio — Payments V2 Initiation - JSON page, Use Case #2 and #3]

5.1 Model A — Spot Rate at Execution (Recommended for Automation)

Flow:

Sub-ledger → POST /cashpro/payments/v2/isoxml-transfers (with FX wire payload)
                    ↓
          BofA applies FX rate at payment execution
                    ↓
          BofA debits UTA USD account, sends instructions to correspondent
                    ↓
          Transaction settles via local clearing to beneficiary bank

[SOURCE: CashPro Developer Studio — Payments V2 Initiation - JSON page, Use Case #2]

[CONFIRM with BofA] — Confirm: (1) Which field in the ISO XML payment schema carries the FX instruction or the currency indicator that triggers BofA to apply a spot rate? (2) What is the FX rate reference returned in the payment response so the GL team can book the correct USD equivalent? (3) Is there a "Guaranteed FX" option that locks the rate at initiation rather than at execution?

5.2 Model B — Pre-Booked Trade Settlement

Flow:

Client books trade → FX Trading API (separate API — not in scope of provided docs)
                           ↓
                   Receive trade reference number
                           ↓
Sub-ledger → POST /cashpro/payments/v2/isoxml-transfers
             (include trade reference in payment payload)
                           ↓
          BofA settles against pre-booked trade rate

[SOURCE: CashPro Developer Studio — Payments V2 Initiation - JSON page, Use Case #3]

[CONFIRM with BofA] — The FX Trading API is referenced in the product overview but its endpoint and schema were not included in the Developer Studio pages provided. Request: (1) FX Trading API endpoint URL, (2) request/response schema for booking a spot trade, (3) the exact field name used to pass the trade reference in the payment initiation payload, (4) trade reference TTL (how long is the booked rate valid).

GL Impact: Regardless of model, the sub-ledger must capture the USD equivalent amount from the payment response before posting the Journal Entry to NetSuite. Do not post the foreign currency amount as the GL debit — post the USD debit.

6. Stop Payment / Check Management

6.1 Check Issue Registration (Positive Pay)

When UTA issues a check, the check details must be registered with BofA simultaneously so it can clear under Positive Pay controls.

Endpoint: POST /cashpro/checkmanagement/v1/check-issues [SOURCE: CashPro Developer Studio — Check Issues and Cancels page]

Required Headers:

Header	Description
`Authorization`	`Bearer [accessToken]`
`Content-Type`	`application/json`
`companyId`	UTA's CashPro Company ID (1–15 characters)

[SOURCE: CashPro Developer Studio — Check Issues and Cancels page]

Request:

json

{
  "issueList": [
    {
      "accountNumber": "000000000280",
      "amount": "1231.00",
      "checkNumber": "4452",
      "issueAction": "add_Issue",
      "issueDate": "2020-07-16",
      "payee": "John Smith"
    }
  ]
}

[SOURCE: CashPro Developer Studio — Check Issues and Cancels page]

issueAction Values: [SOURCE: CashPro Developer Studio — Check Issues and Cancels page]

add_Issue — Register a newly issued check
[CONFIRM with BofA] — The cancel/void action name is not shown in the provided documentation. Confirm the exact issueAction value for cancelling/voiding an issued check.

Response (200):

json

{
  "issueList": [
    {
      "accountNumber": "000000000280",
      "amount": "1231.00",
      "checkNumber": "4452",
      "issueAction": "add_Issue",
      "issueDate": "2020-07-16",
      "message": "Processing by Bank",
      "payee": "John Smith",
      "status": "200"
    }
  ],
  "processedItems": 1,
  "totalItems": 1,
  "unprocessedItems": 0
}

[SOURCE: CashPro Developer Studio — Check Issues and Cancels page]

Key Rule: A status of 200 with message: "Processing by Bank" means the issue has been received but not yet confirmed. Confirmation is provided on the next business day. [SOURCE: CashPro Developer Studio — Check Issues and Cancels page]

Batch Capability: The issueList array supports multiple checks per call. [SOURCE: CashPro Developer Studio — Check Issues and Cancels page]

6.2 Stop Payment / Void

A check void is submitted through the same POST /cashpro/checkmanagement/v1/check-issues endpoint using a cancel issueAction value. [SOURCE: CashPro Developer Studio — Check Issues and Cancels page]

[CONFIRM with BofA] — Confirm the exact issueAction value for a void/stop payment. Confirm whether a stop payment on a check that has already been presented (but not yet paid) uses a different endpoint or the same endpoint with a different action code. Confirm the cutoff window: how far before clearing must a stop/void be submitted?

6.3 Positive Pay Exceptions

[CONFIRM with BofA] — No Positive Pay exceptions inquiry endpoint was included in the Developer Studio pages provided. This is a critical control gap. Before development begins, confirm: (1) Is there an API endpoint to retrieve Positive Pay exceptions (checks presented that don't match issued register)? (2) Is there an API endpoint to submit a pay/return decision on an exception item? (3) If no API is available for exceptions, what is the BofA-delivered mechanism (SFTP file, email notification, CashPro Online portal only)?

Dependency Note: To use the Check Image Retrieval API (§6.4), the account must be entitled to both Check Positive Pay and Image Access in CashPro. [SOURCE: CashPro Developer Studio — Check Image Retrieval page]

6.4 Check Image Retrieval

Endpoint: POST /cashpro/checkmanagement/v1/images [SOURCE: CashPro Developer Studio — Check Image Retrieval page]

Key Features: [SOURCE: CashPro Developer Studio — Check Image Retrieval page]

Retrieves front and back images of paid checks
Up to 25 images per API call
Available within the check retention period
Requires entitlement to Check Positive Pay and Image Access

[CONFIRM with BofA] — Full request/response schema was not available in the provided Developer Studio pages (only the overview was pasted, not the Code tab). Confirm: (1) Request fields (account number, check number, date range), (2) Response format (base64 encoded TIFF? JPEG? PDF?), (3) Whether images are returned inline in the response or via a download URL.

Integration Note: Unlike CNB (which delivers a combined PDF of all check images), CashPro targets individual image retrieval per API call. This is architecturally cleaner for the sub-ledger's cash receipt matching pipeline.

7. Intraday "Engine" (Push Notifications / Webhooks)

CashPro delivers real-time payment events via push notifications (webhooks) sent to a URL the sub-ledger must expose. The system supports two authentication models for incoming webhook calls. [SOURCE: CashPro Developer Studio — OAuth Token Push Notification page]

7.1 Webhook Authentication

BofA supports two auth models for authenticating inbound webhook calls to the sub-ledger: [SOURCE: CashPro Developer Studio — Payment Status Push Notification page]

Model A — OAuth Bearer Token:

BofA calls the sub-ledger's endpoint with Authorization: Bearer [accessToken] header
The sub-ledger validates the token before processing the payload

Model B — Basic Authentication:

BofA calls the sub-ledger's endpoint with userId and userAuthKey headers
userId: User ID provided during onboarding
userAuthKey: Password provided during onboarding

[SOURCE: CashPro Developer Studio — Payment Status Push Notification, Payment Acknowledgement Push Notification, Payment Credit Advice Push Notification, Payment Request for Information Push Notification pages]

[CONFIRM with BofA] — Confirm which auth model is required for this integration (or if either is acceptable), and confirm the webhook registration process: how does UTA register the sub-ledger's callback URL with BofA? Is this a configuration step in CashPro Online, or a separate API call?

7.2 Payment Status Push Notification

BofA pushes payment status updates to the sub-ledger's registered callback URL.

BofA calls: POST [sub-ledger callback URL] [SOURCE: CashPro Developer Studio — Payment Status Push Notification page]

Payload:

json

{
  "endToEndIdentification": "SenderRef18",
  "reason": [
    {
      "reasonCode": "CP502",
      "reasonDescription": "Cannot process due to compliance. Please contact your treasury team."
    }
  ],
  "status": "Rejected By Bank",
  "transactionIdentification": "1234567890ABC"
}

[SOURCE: CashPro Developer Studio — Payment Status Push Notification page]

Required Response: The sub-ledger must respond 200 OK with {"status": "SUCCESS"} to acknowledge receipt. [SOURCE: CashPro Developer Studio — Payment Status Push Notification page]

GL Posting Rule: Upon receiving a terminal status (e.g., Completed, Rejected By Bank), the sub-ledger updates the payment record and triggers the NetSuite Journal Entry posting workflow. For Rejected By Bank, the sub-ledger must reverse any draft GL posting and alert the treasury team.

7.3 Payment Acknowledgement Push Notification (RTP ABR)

For US RTP payments, BofA delivers Acknowledgement by Receiver (ABR) updates — confirmation that the receiving bank has accepted or rejected the credit.

BofA calls: POST [sub-ledger callback URL] [SOURCE: CashPro Developer Studio — Payment Acknowledgement Push Notification page]

Payload:

json

{
  "createdDateTime": "2019-05-22 09:25:30 GMT+00:00",
  "senderName": "Sample Sender Name",
  "transactionIdentification": "1234567890ABC",
  "unstructuredText": "Additional information provided with the acknowledgement by receiver."
}

[SOURCE: CashPro Developer Studio — Payment Acknowledgement Push Notification page]

7.4 Payment Request for Information Push Notification (RTP RFI)

For US RTP payments, the receiving bank may send a Request for Information (RFI) back to the originator. BofA delivers this to the sub-ledger via push notification.

BofA calls: POST [sub-ledger callback URL] [SOURCE: CashPro Developer Studio — Payment Request for Information Push Notification page]

Payload:

json

{
  "createdDateTime": "2019-05-22 09:25:30 GMT+00:00",
  "rfiCodeNText": [
    {
      "rfiCode": "XX01",
      "rfiText": "Additional information provided with the request for information."
    }
  ],
  "rfiId": "12345678902234567890323456789042345",
  "senderName": "Sample Sender Name",
  "transactionIdentification": "1f64ceaf-6a70-45ef-8adb-17182f809ac6"
}

[SOURCE: CashPro Developer Studio — Payment Request for Information Push Notification page]

Response Workflow: When the sub-ledger receives an RFI notification, it must call the RRFI API (§7.5) to respond.

7.5 RRFI — Responding to an RTP Request for Information

Endpoint: POST /cashpro/payments/v2/payment-RRFI [SOURCE: CashPro Developer Studio — Payment V2 RRFI page]

Required Headers:

Header	Description
`Content-Type`	`application/json`
`Authorization`	`Bearer [accessToken]`
`X-Idempotency-Key`	Unique identifier, 1–256 characters
`TransactionIdentification`	Bank-assigned transaction ID, 1–36 characters

[SOURCE: CashPro Developer Studio — Payment V2 RRFI page]

Request:

json

{
  "rfiId": "RFIsample00001",
  "rfiText": "This transaction was submitted for invoice ABC12345."
}

[SOURCE: CashPro Developer Studio — Payment V2 RRFI page]

Response (200):

json

{
  "requestID": "12345678902234567890323456789042345",
  "rfiId": "RFIsample00001",
  "transactionIdentification": "T0b58053-f379-44c2-8999-21f1f7a706ac"
}

[SOURCE: CashPro Developer Studio — Payment V2 RRFI page]

Integration Rule: The sub-ledger must respond to RFIs within the RTP network's SLA window. [CONFIRM with BofA] — Confirm the response deadline for RFI messages (The Clearing House SLA).

8. Payment Receipts (Incoming AR)

Incoming credits to UTA's BofA accounts (royalty payments, AR receipts) are surfaced via the Payment Credit Advice push notification.

8.1 Payment Credit Advice Push Notification

Purpose: Notifies the sub-ledger when a US or Brazil real-time payment (RTP or Pix) is received into a UTA account. This is the primary inbound AR signal for RTP receipts. [SOURCE: CashPro Developer Studio — Payment Credit Advice Push Notification page]

BofA calls: POST [sub-ledger callback URL] [SOURCE: CashPro Developer Studio — Payment Credit Advice Push Notification page]

Payload (key fields):

json

{
  "creditAmount": "209",
  "creditorAccount": {
    "currency": "USD",
    "identification": "[UTA account number]"
  },
  "debtor": {
    "name": "[Sender name]"
  },
  "paymentIdentification": {
    "clearingSystemReference": "001",
    "endToEndIdentification": "MYREF123",
    "instructionIdentification": "20170712000000010B1B000000000005164"
  },
  "paymentType": {
    "localInstrument": "CONSUMER",
    "serviceLevel": "SDVA"
  },
  "settlementDate": "2018-01-13",
  "structuredRemittance": {
    "referredDocument": [
      {
        "date": "string",
        "number": "string",
        "type": "string"
      }
    ]
  },
  "unstructuredRemittance": "Beneficiary unstructured addenda"
}

[SOURCE: CashPro Developer Studio — Payment Credit Advice Push Notification page]

AR Matching Fields:

Field	Use for AR Matching
`creditAmount`	Match to open AR balance
`paymentIdentification.endToEndIdentification`	Sender's reference number — primary match key
`paymentIdentification.clearingSystemReference`	Network clearing reference
`structuredRemittance.referredDocument[].number`	Invoice number (if sender populated structured remittance)
`unstructuredRemittance`	Free-text — secondary match fallback
`debtor.name`	Payor name for fuzzy match to counterparty master

Required Response: Sub-ledger must respond 200 OK to acknowledge receipt. [SOURCE: CashPro Developer Studio — Payment Credit Advice Push Notification page]

Important Limitation: The Credit Advice push notification fires for RTP and Brazil Pix only. It does NOT fire for wire credits or ACH credits received intraday. For those payment types, incoming credits must be sourced from the Reporting API transaction feed (§11) or the BAI2 end-of-day file (§12).

[CONFIRM with BofA] — Confirm: (1) Is there a separate push notification for incoming wire credits? (2) Is there a separate push notification for incoming ACH credits? (3) For H2H reporting, what is the intraday refresh frequency for wire and ACH credits appearing in the transaction API?

9. Error Codes & Debugging

9.1 Error Code Catalog

Error codes appear in the reason array of both API responses and push notification payloads. Two code namespaces are present in the provided documentation:

Code	Source	Description	Recommended Action
`CP502`	BofA proprietary	Cannot process due to compliance	Contact treasury team; do not retry automatically
`CP700`	BofA proprietary	Invalid transaction status for cancel	Check current payment status before cancellation; terminal payments cannot be cancelled
`CPS-ENT-001`	BofA proprietary (ISO XML)	Entitlement SenderID Failed	Verify CashPro Company ID and sender entitlements
`VDT-VAL-007`	BofA proprietary (ISO XML)	Value Date cannot be older than 30 days	Correct the `requestedExecutionDate` — must be within 30 days of today
`000`	Validation API	Success	No action
`XX01`	RTP RFI code	Request for Information	Respond via RRFI endpoint (§7.5)

[SOURCE: CashPro Developer Studio — Payments V2 Status - JSON, Payments V2 Status - ISO XML, US RTP Validation, Payment Request for Information Push Notification pages]

[CONFIRM with BofA] — The provided Developer Studio pages expose only a small subset of error codes via sample responses. Request the full BofA CashPro error code reference document, including: (1) the complete CP code series, (2) the complete CPS/VDT code series for ISO XML, (3) HTTP status codes and their meaning in the CashPro context, (4) which error codes are retryable vs. terminal.

9.2 Payment Status Values

The following paymentStatus strings appear in the provided documentation:

Status String	Context	Meaning
`PEND_APPROV`	V1 Initiation	Awaiting manual approval in CashPro Online (V1 only — not applicable to V2)
`PDNG`	V2 Request	Payment is pending
`Rejected By Bank`	V2 Status / Push Notification	Payment rejected; see `reason` array for code and description
`Unsuccessful`	ISO XML Status	File-level failure
`Rejected`	ISO XML Status (transaction level)	Individual transaction rejected within a file

[SOURCE: CashPro Developer Studio — Payments V1 Initiation, Payments V2 Status - JSON, Payments V2 Status - ISO XML, Payments V2 Request Status pages]

[CONFIRM with BofA] — Request the complete paymentStatus enumeration for V2 JSON payments, including the success/completion status string (e.g., Completed, Settled, etc. — none of the provided pages showed a successful terminal status for V2).

9.3 Debugging Workflow

Payment fails (push notification or polling returns non-success status)
    ↓
1. Capture transactionIdentification and reasonCode from response
    ↓
2. Check reasonCode against §9.1 table
    ↓
3. If CP502 (compliance): escalate to treasury — do not retry
4. If CP700 (invalid status for cancel): check status first, cancel only if eligible
5. If CPS-ENT-001 (entitlement): check companyId header and CashPro entitlements
6. If VDT-VAL-007 (stale value date): correct date and resubmit with new idempotency key
7. If unknown code: pull status via polling endpoint for full reason detail
    ↓
8. Log all failed transactionIdentifications to sub-ledger exception queue
9. Alert treasury team for CP502 and any unknown codes

10. Account Balances API

BofA provides four balance-related endpoints. All are under the Reporting API (/cashpro/reporting/v1/). [SOURCE: CashPro Developer Studio — Current Day Balance Inquiry, Previous Day Balance Inquiry, Funds Check pages]

10.1 Current Day Balance Inquiry

Purpose: Returns intraday account balance data for a single date. [SOURCE: CashPro Developer Studio — Current Day Balance Inquiry page]

Endpoint: POST /cashpro/reporting/v1/balance-inquiries/current-day [SOURCE: CashPro Developer Studio — Current Day Balance Inquiry page]

Required Headers:

Header	Description
`Content-Type`	`application/json`
`Authorization`	`Bearer [accessToken]`

Request:

json

{
  "accounts": [
    {
      "accountNumber": "601022222222",
      "bankId": "BOFAFRPP"
    }
  ],
  "balanceAsOfDate": "2017-07-04"
}

[SOURCE: CashPro Developer Studio — Current Day Balance Inquiry page]

Response (200):

json

{
  "accountBalances": {
    "accountNumber": "600811111111",
    "balances": [
      {
        "amount": "983.97",
        "lastUpdatedDate": "2017-07-04",
        "transactionCode": "010",
        "transactionDescription": "Opening Ledger Balance"
      }
    ],
    "bankId": "BOFAGB22",
    "currency": "EUR"
  }
}

[SOURCE: CashPro Developer Studio — Current Day Balance Inquiry page]

Key Fields:

Field	Description
`transactionCode`	BAI2 type code for the balance type (e.g., `010` = Opening Ledger Balance)
`transactionDescription`	Human-readable balance type name
`amount`	Balance amount as a string
`bankId`	BofA BIC/routing identifier for the account's domicile

[CONFIRM with BofA] — Confirm: (1) Can multiple accounts be queried in a single call (the request schema shows an accounts array — confirm array limit), (2) What is the full set of transactionCode values returned for US USD accounts? (3) Does the current day balance reflect settled items only, or does it include float/pending items?

10.2 Previous Day Balance Inquiry

Purpose: Returns prior business day closing balance data. Supports historical queries back to the full two-year client retention period. [SOURCE: CashPro Developer Studio — Previous Day Balance Inquiry page]

Endpoint: POST /cashpro/reporting/v1/balance-inquiries/previous-day [SOURCE: CashPro Developer Studio — Previous Day Balance Inquiry page]

Request and response schema are identical in structure to §10.1.

Use Case: The previous day balance is the authoritative "brakes" input for the reconciliation equation (§13). Poll this endpoint daily at open of business to anchor the rec.

10.3 Funds Check

Purpose: Queries current day balance to determine whether a specific amount is available in the account. Supports a single account for the current date. [SOURCE: CashPro Developer Studio — Funds Check page]

Endpoint: POST /cashpro/reporting/v1/funds-checks [SOURCE: CashPro Developer Studio — Funds Check page]

Request:

json

{
  "account": {
    "accountNumber": "600811111111",
    "bankId": "BOFAGB22"
  },
  "amount": "1000.00"
}

[SOURCE: CashPro Developer Studio — Funds Check page]

Response (200):

json

{
  "fundsAvailable": true
}

[SOURCE: CashPro Developer Studio — Funds Check page]

Integration Rule: Run a Funds Check before initiating any large wire or same-day ACH to prevent NSF rejections. Log the check result as an event on the payment record. The boolean response is intentionally simple — the actual balance details are available via §10.1 if needed.

11. Transaction Details / Reporting

11.1 Current Day Transaction Inquiry

Purpose: Returns intraday transaction details for a date range. This is the "engine feed" — it populates the sub-ledger's real-time cash activity picture. [SOURCE: CashPro Developer Studio — Current Day Transaction Inquiry page]

Endpoint: POST /cashpro/reporting/v1/transaction-inquiries/current-day [SOURCE: CashPro Developer Studio — Current Day Transaction Inquiry page]

Required Headers:

Header	Description
`Content-Type`	`application/json`
`Authorization`	`Bearer [accessToken]`

Request:

json

{
  "accounts": [
    {
      "accountNumber": "601022222222",
      "bankId": "BOFAFRPP"
    }
  ],
  "fromDate": "2017-11-21",
  "toDate": "2017-11-21"
}

[SOURCE: CashPro Developer Studio — Current Day Transaction Inquiry page]

Response (200):

json

{
  "accountTransactions": {
    "accountNumber": "601022222222",
    "bankId": "BOFAFRPP",
    "currency": "EUR",
    "transactions": [
      {
        "amount": "1.00",
        "asOfDate": "2017-11-21",
        "availability1DayAmount": "string",
        "availability2PlusDayAmount": "string",
        "availabilityImmediateAmount": "string",
        "bankReference": "555555555555",
        "creditDebitIndicator": "Debit",
        "customerReference": "CUSTREF123",
        "detailText": "BENEFICIARY UNSTRUCTURED DETAIL TEXT",
        "itemCount": "1",
        "transactionCode": "400",
        "transactionDescription": "Total Debits",
        "transactionType": "Summary",
        "valueDate": "2017-11-21"
      }
    ]
  }
}

[SOURCE: CashPro Developer Studio — Current Day Transaction Inquiry page]

Key Fields for AR Matching:

Field	Description
`bankReference`	BofA-assigned bank reference number — primary match key for reconciliation
`customerReference`	UTA's reference echoed back — available for wires; not available for batched ACH [SOURCE: BofA Integration Manager Kim, March 2026]
`detailText`	Free-form transaction description — use for fuzzy AR matching
`transactionCode`	BAI2 type code
`creditDebitIndicator`	`Credit` or `Debit`
`valueDate`	Settlement date
`transactionType`	`Summary` (batch totals) or `Detail` (individual items)

Important: Per Kim, unique IDs for each payment are visible in the transaction text (customerReference) for wire transactions. This field is not available for transactions that batch post (e.g., US ACH). For ACH items, matching must rely on detailText content. [SOURCE: BofA Integration Manager Kim, March 2026]

11.2 Previous Day Transaction Inquiry

Purpose: Returns prior business day transaction details. Supports a date range. Used for EOD reconciliation and historical research. [SOURCE: CashPro Developer Studio — Previous Day Transaction Inquiry page]

Endpoint: POST /cashpro/reporting/v1/transaction-inquiries/previous-day [SOURCE: CashPro Developer Studio — Previous Day Transaction Inquiry page]

Request and response schema are identical in structure to §11.1.

[CONFIRM with BofA] — Confirm: (1) Maximum date range supported in a single call for the previous day inquiry. (2) Whether pagination is supported (and how — cursor? offset?). (3) Whether transactionType: "Detail" can be requested exclusively to suppress summary rows.

12. BAI2 / End-of-Day "Brakes"

12.1 H2H File Delivery vs. API Reporting

Per Kim's matrix, BofA supports both H2H (Host-to-Host) file delivery and the Reporting API. For this integration, the Reporting API is the primary channel for intraday and previous-day data. BAI2 file delivery serves as the authoritative end-of-day reconciliation anchor (the "brakes"). [SOURCE: BofA Integration Manager Kim, March 2026]

Feature	H2H BAI2 File	Reporting API
Delivery	Predetermined schedule	On-demand
Use Case	EOD rec "brakes"	Intraday engine
Customer Reference	Available for wires	Available for wires
ACH Reference	Not available (batched)	Not available (batched)

12.2 BAI2 File Delivery Specifications

[CONFIRM with BofA] — No BAI2 file specification document was included in the provided materials. The standard BAI2 format (per BAI2 spec, same as CNB) applies, but BofA may have custom type codes or extended transaction detail formats. Before development begins, confirm from BofA:
SFTP delivery path — What is the SFTP directory path where BofA deposits BAI2 files?
File naming convention — What is the file name pattern (e.g., BOFABAL.<accountgroup>.<yyyymmdd>.BAI2)?
Delivery schedule — What time (ET) does the previous day BAI2 file land? Is there an intraday BAI2 file?
SFTP host and credentials — Host URL, port, authentication method (password vs. SSH key)
Custom BAI2 type codes — Does BofA use non-standard type codes beyond the BAI2 specification?
Extended transaction detail — What additional data appears in the 88 continuation records for wire and ACH items? Is UTA's payment reference embedded here?

12.3 BAI2 Standard Record Structure

The standard BAI2 record types apply (consistent with the CNB BAI2 spec, which follows the BAI2 standard):

Record Code	Name	Purpose
`01`	File Header	Identifies sender, receiver, file structure
`02`	Group Header	Groups accounts by originator and as-of date
`03`	Account Identifier and Summary	Account number, balance summary, opening/closing balances
`16`	Transaction Detail	Individual transaction line items
`49`	Account Trailer	Account control totals
`88`	Continuation	Extends any record that exceeds physical record length
`98`	Group Trailer	Group control totals
`99`	File Trailer	File control totals

Common BAI2 Balance Type Codes (expected for US USD accounts):

Code	Description
`010`	Opening Ledger Balance
`015`	Closing Ledger Balance
`045`	Opening Available Balance
`050`	Closing Available Balance
`100`	Total Credits
`400`	Total Debits

[CONFIRM with BofA] — Confirm which balance type codes BofA reports for US accounts and whether any BofA-custom codes (outside the standard BAI2 range) appear.

13. Reconciliation Logic (Three-Way Match)

13.1 Architecture Principle

The sub-ledger owns the bank relationship exclusively. BAI2 files and Reporting API data never flow directly to NetSuite. NetSuite receives only Journal Entries posted by the sub-ledger. Reconciliation runs in two steps that serve distinct purposes.

BofA Bank ──► BAI2 / Reporting API ──► Sub-Ledger ──► Journal Entries ──► NetSuite GL
                                             │
                                        Owns all rec logic
                                        Bank ↔ Sub-Ledger (Step 1)
                                        Sub-Ledger ↔ NetSuite (Step 2)

13.2 Step 1 — Bank vs. Sub-Ledger (Automated)

Trigger: Previous Day BAI2 file lands on SFTP at [CONFIRM with BofA — delivery time]. Alternatively, poll the Previous Day Balance and Transaction APIs at 6:00 AM ET.

Mechanism: The sub-ledger auto-matches every transaction in the previous day data against its internal payment log, using three keys in priority order:

bankReference (primary) — BofA's bank reference number
customerReference (secondary) — UTA's reference echoed back (available for wires only)
Amount + value date (tertiary fallback — for ACH batches where individual references are unavailable)

The Three-Way Match Equation:

BofA Previous Day Closing Balance (BAI2 / Previous Day Balance API)
+ Deposits in Transit (sub-ledger credits not yet in previous day report)
− Outstanding Payments (sub-ledger debits not yet settled)
= Sub-Ledger Book Balance

Output Buckets:

Bucket	Description	Action
Matched / Cleared	Bank line matched to sub-ledger record	Mark record as bank-confirmed; release JE to NetSuite
Outstanding Items	Sub-ledger records not yet in bank statement	Age the item; flag if > 5 business days for wires, > 3 days for RTP
Bank Exceptions	Bank lines with no matching sub-ledger record	Escalate to treasury immediately
Sub-Ledger Exceptions	Sub-ledger records with no matching bank line beyond aging threshold	Escalate to treasury for investigation

13.3 Step 2 — Sub-Ledger vs. NetSuite (GL User Approval)

Mechanism: The sub-ledger compares the total of bank-confirmed JEs for the period against the NetSuite GL balance for each BofA account.

Cadence: Daily. Step 1 completes automatically at [CONFIRM with BofA — BAI2 delivery time + processing buffer]. Step 2 is a GL user approval task, expected by end of business each day.

Assurance Rule: Any discrepancy between the Bank's settled balance (Brakes) and the sub-ledger's recorded activity (Engine) must be flagged as a variance in the sub-ledger's exception queue before any JEs for that day are approved for NetSuite posting.

13.4 ACH Batch Reconciliation Special Case

ACH credits and debits post as batch summaries in the BofA reporting feeds — individual item details are not separately identified with UTA references. [SOURCE: BofA Integration Manager Kim, March 2026]

Matching Strategy for ACH Batches:

Match the total batch credit/debit amount on a given value date to the sub-ledger's expected ACH batch total for that date.
If the batch total matches, mark all constituent ACH items as bank-confirmed.
If the batch total does not match, pull the previous day transaction detail (§11.2) and use detailText content for item-level matching.
Any unmatched ACH items after detailText matching are escalated to the AR team for manual research.

14. Kim's Integration Matrix (Reference)

The following matrix was provided by BofA Integration Manager Kim and represents the authoritative channel recommendation for each payment type. All architecture decisions in this spec flow from this matrix. [SOURCE: BofA Integration Manager Kim, March 2026]

Country	Payment Type	H2H File (XML)	API (XML)	API (JSON)	Notes
US	Fed Wire	✓	✓	✓	JSON slightly faster
US	Swift (USD Int'l)	✓	✓	CA/EMEA only	JSON slightly faster
US	FX	✓	✓	N/A	File/API same processing time
US	ACH PPD/CCD Credits	✓	✓	✓	All batched; no real-time advantage via API
US	ACH CTX Credits	✓	✓	N/A	File/API same processing time
US	ACH CCD+/PPD+	✓	✓	N/A	File/API same processing time
US	ACH Debits	✓	N/A	N/A	FILE ONLY
US	US RTP	✓	✓	✓	JSON is faster than XML
US	Zelle / PayPal	✓	✓	✓	JSON faster than XML
UK - GBP	Domestic Wires	✓	✓	N/A	OUT OF SCOPE
UK - GBP	SWIFT (GBP Int'l)	✓	✓	N/A	OUT OF SCOPE
UK - GBP	Faster Payments	✓	✓	N/A	OUT OF SCOPE
UK - GBP	BACS	✓	✓	N/A	OUT OF SCOPE
UK - GBP	FX Wires	✓	✓	N/A	OUT OF SCOPE
UK - EUR	TARGET2	✓	✓	✓	OUT OF SCOPE
UK - EUR	SWIFT (EUR Int'l)	✓	✓	N/A	OUT OF SCOPE
UK - EUR	SEPA	✓	✓	✓	OUT OF SCOPE
UK - EUR	SEPA INSTANT	✓	✓	✓	JSON faster — OUT OF SCOPE
UK - EUR	FX Wires	✓	✓	N/A	OUT OF SCOPE
UK - USD	SWIFT	✓	✓	N/A	OUT OF SCOPE
UK - USD	FX	✓	✓	N/A	OUT OF SCOPE
UK - AUD	SWIFT	✓	✓	N/A	OUT OF SCOPE
UK - AUD	FX	✓	✓	N/A	OUT OF SCOPE

Channel Recommendation Summary (US accounts): [SOURCE: BofA Integration Manager Kim, March 2026]

Payments: ISO XML via API for most types. JSON for RTP only.
Reporting: API (JSON), on-demand.
Acknowledgements (H2H): File-based acknowledgements for XML; status available within 1 minute for JSON; file-based ACKs for ISO XML can take several hours for wires.
ACH Debits / Press X Debit collections: NACHA direct transmission only — not via API.

15. Next Actions

Engineering design document — Amir's team owns drafting (separate from this spec; see the three-document set in the Scope boundary — and who owns what block near the top of this document for context). Covers HOW the integration-boundary requirements in §3 / §4 / §7 / §8 / §12 plus the Client Processing behavior in document (B) are implemented: class decomposition, queue architecture, retry semantics, error-handling matrices for webhook delivery vs. polling fallback, webhook-receiver structure for CashPro Intraday push notifications, ISO XML payment-submission pipeline, JSON polling cadence for RTP/SEPA Instant status, OAuth + cert-refresh scheduling, retry semantics for ISO XML vs. JSON paths, and JWS/JWE failure handling on the payment-initiation channel. Cliff's role here is requirements clarification when Amir's team flags an implementation question that exposes a gap at the integration boundary (when to call X, what to do with payload Y, how to handle exception Z) — those answers land in this spec. Gaps inside Client Processing (business rules, triggers, payload consumption) land in document (B). Engineering hand-off depends on BOTH (A) this spec AND (B) Client Processing behavior spec being ready — Amir's design needs both inputs. (A)-only hand-off would leave (C) without the business-rules layer it implements against.

Appendix A — Open Items / Confirm List

The following items require confirmation from BofA before development can begin on the affected sections:

#	Section	Item
1	§1.2	Production OAuth token endpoint URL
2	§1.2	Token TTL
3	§1.2	Confirm spelling of `clientSceret` field (appears to be BofA typo)
4	§1.3	Production API base URL
5	§1.6	Sandbox base URL and credential provisioning process
6	§2.1	Full request/response schema for US Account Validation
7	§2.1	Callback/webhook payload schema for async validation results
8	§2.2	BofA's default behavior when RTP validation returns `isMember: false` (auto-downgrade to ACH vs. reject)
9	§2.3	Full request/response schema for Zelle Token Validation
10	§2.4	Whether US Account Validation and SEPA VOP truly share the same endpoint path
11	§3.2	V2 JSON initiation request schema (Code tab not pasted)
12	§3.2	Correct `paymentType.serviceLevel` value for RTP in V2
13	§3.3	Full ISO XML pain.001 message specification for US payment types
14	§3.3	Maximum file size and batch size for ISO XML submissions
15	§3.5	Cancellation request body schema
16	§3.5	ACH credit cancellation mechanism and time window
17	§4.3	Rate limit on status polling calls
18	§5.1	FX field name in ISO XML that triggers spot rate application
19	§5.1	FX rate reference returned in payment response for GL booking
20	§5.1	Availability of "Guaranteed FX" option
21	§5.2	FX Trading API endpoint, request/response schema, trade reference field name, TTL
22	§6.2	`issueAction` value for check void/stop payment
23	§6.2	Cutoff window for stop/void before clearing
24	§6.3	Positive Pay exceptions inquiry endpoint
25	§6.3	Pay/return decision submission endpoint
26	§6.4	Full request/response schema for Check Image Retrieval
27	§6.4	Image format returned (base64 TIFF? JPEG? PDF?)
28	§7.1	Webhook registration process (how UTA registers callback URL with BofA)
29	§7.1	Required auth model for this integration (OAuth vs. Basic)
30	§7.5	RFI response deadline (Clearing House SLA)
31	§8.1	Push notification availability for incoming wire credits
32	§8.1	Push notification availability for incoming ACH credits
33	§8.1	Intraday refresh frequency for wire/ACH credits in transaction API
34	§9.2	Complete `paymentStatus` enumeration for V2 JSON
35	§9.1	Full BofA CashPro error code reference document
36	§10.1	Maximum number of accounts in a single balance inquiry call
37	§10.1	Whether current day balance reflects settled items only or includes pending
38	§11.2	Maximum date range for previous day transaction inquiry
39	§11.2	Pagination mechanism
40	§12.2	SFTP host, port, directory path, and authentication method
41	§12.2	BAI2 file naming convention
42	§12.2	BAI2 delivery time (ET)
43	§12.2	Intraday BAI2 availability
44	§12.2	BofA-custom BAI2 type codes
45	§12.2	`88` continuation record format / UTA reference embedding
46	§13.3	UTA's assigned CashPro Company ID

Document prepared by sub-ledger development team. All content cited to CashPro Developer Studio pages (sourced March 2026) or BofA Integration Manager Kim (March 2026). Sections tagged [CONFIRM with BofA] must not be developed until confirmed.

Sample Deals

Touring Deal

Endorsement Deal

Sports Endo Deal

Appendices

Appendices

Appendices

UTA Bank of America CashPro API Integration Specification ​

Table of Contents ​

1. Authentication & Security ​

1.1 Security Stack ​

1.2 OAuth Token Acquisition ​

1.3 API Base URL ​

1.4 Idempotency ​

1.5 Company Identifier ​

1.6 Environments ​

2. Account Pre-Validation ("Pre-Flight") ​

2.1 US Account Validation (ACH / Wire Pre-Flight) ​

2.2 US RTP Network Membership Validation ​

2.3 Zelle Token Validation ​

2.4 SEPA Verification of Payee ​

3. Payment Initiation (RTP / ACH / Wire) ​

3.1 Channel Architecture Decision ​

3.2 Payments V2 Initiation — JSON (US RTP and SEPA Instant) ​

3.3 Payments V2 Initiation — ISO XML (Wire / ACH Credits) ​

3.4 Payments V1 Initiation (Legacy — Requires CashPro Online Approval) ​

3.5 Payment Cancellation ​

4. Payment Status Inquiry (Polling) ​

4.1 JSON Payment Status ​

4.2 ISO XML Payment Status ​

4.3 Polling Strategy ​

5. The Two-Step FX Lock (International Wire) ​

5.1 Model A — Spot Rate at Execution (Recommended for Automation) ​

5.2 Model B — Pre-Booked Trade Settlement ​

6. Stop Payment / Check Management ​

6.1 Check Issue Registration (Positive Pay) ​

6.2 Stop Payment / Void ​

6.3 Positive Pay Exceptions ​

6.4 Check Image Retrieval ​

7. Intraday "Engine" (Push Notifications / Webhooks) ​

7.1 Webhook Authentication ​

7.2 Payment Status Push Notification ​

7.3 Payment Acknowledgement Push Notification (RTP ABR) ​

7.4 Payment Request for Information Push Notification (RTP RFI) ​

7.5 RRFI — Responding to an RTP Request for Information ​

8. Payment Receipts (Incoming AR) ​

8.1 Payment Credit Advice Push Notification ​

9. Error Codes & Debugging ​

9.1 Error Code Catalog ​

9.2 Payment Status Values ​

9.3 Debugging Workflow ​

10. Account Balances API ​

10.1 Current Day Balance Inquiry ​

10.2 Previous Day Balance Inquiry ​

10.3 Funds Check ​

11. Transaction Details / Reporting ​

11.1 Current Day Transaction Inquiry ​

11.2 Previous Day Transaction Inquiry ​

12. BAI2 / End-of-Day "Brakes" ​

12.1 H2H File Delivery vs. API Reporting ​

12.2 BAI2 File Delivery Specifications ​

12.3 BAI2 Standard Record Structure ​

13. Reconciliation Logic (Three-Way Match) ​

13.1 Architecture Principle ​

13.2 Step 1 — Bank vs. Sub-Ledger (Automated) ​

13.3 Step 2 — Sub-Ledger vs. NetSuite (GL User Approval) ​

13.4 ACH Batch Reconciliation Special Case ​

14. Kim's Integration Matrix (Reference) ​

15. Next Actions ​

Appendix A — Open Items / Confirm List ​

UTA Bank of America CashPro API Integration Specification

Table of Contents

1. Authentication & Security

1.1 Security Stack

1.2 OAuth Token Acquisition

1.3 API Base URL

1.4 Idempotency

1.5 Company Identifier

1.6 Environments

2. Account Pre-Validation ("Pre-Flight")

2.1 US Account Validation (ACH / Wire Pre-Flight)

2.2 US RTP Network Membership Validation

2.3 Zelle Token Validation

2.4 SEPA Verification of Payee

3. Payment Initiation (RTP / ACH / Wire)

3.1 Channel Architecture Decision

3.2 Payments V2 Initiation — JSON (US RTP and SEPA Instant)

3.3 Payments V2 Initiation — ISO XML (Wire / ACH Credits)

3.4 Payments V1 Initiation (Legacy — Requires CashPro Online Approval)

3.5 Payment Cancellation

4. Payment Status Inquiry (Polling)

4.1 JSON Payment Status

4.2 ISO XML Payment Status

4.3 Polling Strategy

5. The Two-Step FX Lock (International Wire)

5.1 Model A — Spot Rate at Execution (Recommended for Automation)

5.2 Model B — Pre-Booked Trade Settlement

6. Stop Payment / Check Management

6.1 Check Issue Registration (Positive Pay)

6.2 Stop Payment / Void

6.3 Positive Pay Exceptions

6.4 Check Image Retrieval

7. Intraday "Engine" (Push Notifications / Webhooks)

7.1 Webhook Authentication

7.2 Payment Status Push Notification

7.3 Payment Acknowledgement Push Notification (RTP ABR)

7.4 Payment Request for Information Push Notification (RTP RFI)

7.5 RRFI — Responding to an RTP Request for Information

8. Payment Receipts (Incoming AR)

8.1 Payment Credit Advice Push Notification

9. Error Codes & Debugging

9.1 Error Code Catalog

9.2 Payment Status Values

9.3 Debugging Workflow

10. Account Balances API

10.1 Current Day Balance Inquiry

10.2 Previous Day Balance Inquiry

10.3 Funds Check

11. Transaction Details / Reporting

11.1 Current Day Transaction Inquiry

11.2 Previous Day Transaction Inquiry

12. BAI2 / End-of-Day "Brakes"

12.1 H2H File Delivery vs. API Reporting

12.2 BAI2 File Delivery Specifications

12.3 BAI2 Standard Record Structure

13. Reconciliation Logic (Three-Way Match)

13.1 Architecture Principle

13.2 Step 1 — Bank vs. Sub-Ledger (Automated)

13.3 Step 2 — Sub-Ledger vs. NetSuite (GL User Approval)

13.4 ACH Batch Reconciliation Special Case

14. Kim's Integration Matrix (Reference)

15. Next Actions

Appendix A — Open Items / Confirm List