Banner → TouchNet payment gateway integration

Payments touch the most sensitive part of the student record — money. Charges raised in Banner have to reach TouchNet, and payments and refunds have to post back and reconcile, without double-posting or dropped transactions. This integration keeps the two ledgers consistent with idempotent posting and a daily reconciliation that catches any drift.

Free reference snippet

Yours to use

A working piece from this integration — no sign-up. The full build handles the edge cases, safeguards, and cutover.

Banner-to-TouchNet field mapping for student account synchronization (charges, payments, refunds):

-- Banner source query for TouchNet payload population
SELECT spriden_pidm         -- Student ID (mapped to TouchNet account ID)
     , spriden_surname        -- Last name
     , spriden_first_name     -- First name
     , spbpers_ssn            -- SSN (hashed for TouchNet token)
     , tbbexpt_term_code      -- Academic term
     , tbraccd_detail_code    -- Charge/payment type
     , tbraccd_amount         -- Transaction amount
     , tbraccd_effective_date-- Transaction date
     , tbraccd_doc_ref        -- Banner document reference
FROM  spriden
JOIN  spbpers ON spriden_pidm = spbpers_pidm
JOIN  tbbexpt ON spriden_pidm = tbbexpt_pidm
JOIN  tbraccd ON spriden_pidm = tbraccd_pidm
WHERE tbraccd_detail_code IN ('TU', 'ML', 'RF')  -- Tuition, Meal, Refund
   AND tbraccd_effective_date >= TRUNC(SYSDATE - 1);  -- Daily delta

Banner Field	TouchNet Field	Notes
`tbraccd_pidm`	`accountId`	Hashed PIDM as student account ID
`spriden_first_name \|\| spriden_surname`	`accountHolder.name`	Student display name
`tbbexpt_term_code`	`termCode`	Banner term (e.g., 202410)
`tbraccd_detail_code`	`transactionType`	CHARGE / PAYMENT / REFUND
`tbraccd_amount`	`amount`	Absolute value; sign in type field
`tbraccd_effective_date`	`postDate`	Date transaction posts in Banner
`tbraccd_doc_ref`	`referenceId`	For reconciliation match-back

Implementation pathway

Step by step

How we'd take this from discovery to a production-safe cutover — the phases, the canonical mapping, and the edge cases that bite.

This integration connects Ellucian Banner's student accounts receivable module to TouchNet's payment gateway, ensuring that student charges (tuition, fees, housing) created in Banner are visible for online payment in TouchNet, and that payments, refunds, and adjustments flow back into Banner accurately. The goal is a daily reconciled state where Banner's TBRACCD and SFRCRMT tables reflect what TouchNet processed, with no orphaned or duplicate transactions.

Phases

Discovery and environment preparation. Enumerate every Banner charge code (TTVATyp/TTVACOD) that must appear in TouchNet. Confirm TouchNet merchant account IDs (one per fund/processing type) and GL posting codes. Set up isolated development and QA environments for both Banner (Oracle database) and TouchNet (sandbox u.pay tenant). Obtain TouchNet API credentials (client ID, client secret, merchant ID) and Banner Web Advisor service account with SFAREGS and TBRACCD read/write roles.
Design the data flow and idempotency strategy. Banner is the system of record for charges; TouchNet is the system of record for payments. Define that each Banner charge gets a unique TBRACCD sequence number (TBRACCD_SEQNO) that becomes the TouchNet invoice reference. Each payment response from TouchNet must carry that reference back to avoid duplicate application. Establish a TOUCHNET_POST_LOG staging table in Banner to track sent charges and received payments with status flags (Pending, Applied, Error).
Build Banner → TouchNet charge push. Create a PL/SQL procedure (or Banner Integration Server job) that queries TBRACCD where TBRACCD_TRAN_DATE = TODAY and TBRACCD_TYPE = 'C' (charge) and no matching entry exists in TOUCHNET_POST_LOG with DEST = 'TN'. For each row, POST to TouchNet's /api/v1/invoices endpoint with invoice_number = TBRACCD_SEQNO, amount = TBRACCD_AMOUNT, description = TTVATYP_DESC, and student_id = Banner PIDM padded to TouchNet's required format. Log the call with a UUID in TOUCHNET_POST_LOG and mark STATUS = 'SENT'. Schedule this as a near-real-time event-driven trigger on TBRACCD insert, with a fallback batch every 15 minutes.
Build TouchNet → Banner payment and refund pull. Implement a polling job (every 5 minutes) that calls TouchNet's /api/v1/transactions?status=COMPLETED&since={last_check}. For each transaction, parse invoice_reference to match TBRACCD_SEQNO. If not found (refund scenario where TouchNet initiated the credit), query TBBDIST and SFRCRMT to locate the original payment. Apply the payment to Banner by inserting into SFRCRMT with SFRCRMT_CRN = related course, SFRCRMT_AMOUNT = transaction.amount, and SFRCRMT_RECEIPT_NO = TouchNet transaction_id. Insert the reverse charge entry into TBRACCD with TBRACCD_AMOUNT negative for refunds. Write receipts to SFRRECT. Mark TOUCHNET_POST_LOG.STATUS = 'APPLIED' only after the Banner commit.
Implement daily reconciliation job. Run end-of-day (after 22:00 processing window) comparing TOUCHNET_POST_LOG aggregated by TBRACCD_SEQNO against TouchNet's /api/v1/reports/daily-summary endpoint. Flag any TOUCHNET_POST_LOG rows with STATUS = 'SENT' that never received a payment response (likely abandoned carts or gateway timeouts) and generate an exceptions report. Reconcile total dollar amounts by fund code. If variance > $0.01, halt auto-posting and alert the bursar office before manual resolution.
User acceptance testing. Use three test personas: a resident student with housing and tuition charges, a financial aid disbursement creating an excess, and a refund scenario initiated by TouchNet. Verify that TouchNet displays the correct charge description and amount, that the Banner PIDM links correctly to the TouchNet payer record, that partial payments apply proportionally to TBRACCD rows in chronological order, and that the daily reconciliation report matches the sum of SFRCRMT_AMOUNT by fund code. Include timeout and retry testing: simulate a TouchNet 503 response and confirm the idempotent retry does not double-post.
Security and compliance hardening. Ensure TouchNet API calls use TLS 1.2+. Store credentials in Banner's encrypted credential vault, not in plaintext package bodies. Log all API payloads (without full card numbers) to TOUCHNET_AUDIT_LOG. Confirm PCI-DSS scope: because TouchNet handles card data, Banner never stores PANs; validate the tokenization workflow so Banner receives only a tokenized_payment_id. Enable TouchNet webhook notifications for chargebacks and disputed transactions, routing these to the bursar queue.
Training and runbook. Document the reconciliation exception runbook: step 1 — download TOUCHNET_POST_LOG exceptions; step 2 — cross-reference TouchNet dashboard for transaction status; step 3 — if payment exists in TouchNet but not Banner, manually insert SFRCRMT and update log; step 4 — if charge exists in Banner but not TouchNet, re-POST to /api/v1/invoices. Train student financial services staff on the TouchNet admin portal for refund initiation and chargeback response.
Staged production cutover. Go live with a single term and one academic college (≈2,000 students) for the first two weeks before expanding to the full institution. Monitor TOUCHNET_POST_LOG exceptions in real time via dashboard. Maintain the legacy payment channel (cash/check walk-in at cashier) in parallel for the transition period. After day 14, decommission legacy feed if reconciliation accuracy exceeds 99.95% for the pilot group.

Field mapping

Banner identifier	Description	TouchNet identifier	Description	Transform rule
`TBRACCD_SEQNO`	Charge sequence number (primary key)	`invoice_number`	TouchNet invoice reference	Pass through unchanged; must be unique per merchant account
`PIDM`	Internal person identifier	`payer.external_id`	TouchNet payer lookup key	Map Banner `PIDM` to TouchNet `external_id` on payer creation; if existing payer, use `GET /api/v1/payers?external_id={PIDM}`
`TBRACCD_AMOUNT`	Charge amount (positive)	`amount`	Invoice amount due	Decimal(10,2); pass as string "1250.00"; negative amounts (refunds) POST as separate credit invoice
`TTVATYP_DESC` (joined from `TTVATYP`)	Charge type description (e.g., "Fall 2024 Tuition")	`description`	Line-item label in TouchNet checkout	Truncate to 255 chars; concatenate `TTVATYP_DESC + ' - ' + TBRACCD_TERM_CODE`
`TBRACCD_TERM_CODE`	Academic term (e.g., 202440)	`metadata.term_code`	TouchNet custom attribute	Store for reconciliation filtering by term in TouchNet reporting
`SFRCRMT_AMOUNT`	Payment amount applied	`transaction.amount`	Captured payment amount	Positive value; insert into `SFRCRMT` with `SFRCRMT_RECEIPT_NO` = TouchNet `transaction_id`
`transaction_id` (TouchNet)	TouchNet gateway transaction ID	`SFRCRMT_RECEIPT_NO`	Banner payment receipt reference	Store 36-char UUID from TouchNet as `SFRCRMT_RECEIPT_NO` for traceability
`TOUCHNET_POST_LOG.STATUS`	Integration status flag	N/A (Banner-only tracking)	Local log state	Values: `SENT` (pushed to TouchNet, no response yet), `APPLIED` (payment received and Banner updated), `ERROR` (failed; requires manual review)

Edge cases

Duplicate push. If the Banner→TouchNet trigger fires twice for the same TBRACCD_SEQNO (e.g., database retry or dual-node execution), TouchNet will reject the duplicate invoice with a 409. The procedure must catch this, set STATUS = 'SENT' from the first attempt, and discard the second without erroring the job.
Partial payment mismatch. If a student pays $50 against a $100 charge in TouchNet, the full TBRACCD row must not be marked closed. Apply $50 to the oldest charge and leave the remaining $50 balance open. Failure to implement partial payment logic will cause the remaining balance to disappear from TouchNet on the next reconciliation cycle.
TouchNet-initiated refunds without a Banner charge reference. When TouchNet processes a chargeback or manual refund triggered by the merchant (not Banner), the webhook payload will not carry a matching invoice_number. The polling job must fall back to searching SFRCRMT by SFRCRMT_RECEIPT_NO and creating a compensating TBRACCD credit row, otherwise the refund posts to Banner's payment side only and leaves the charge row unbalanced.
Term rollover mismatch. If a charge carries TBRACCD_TERM_CODE = 202440 but TouchNet's fiscal close for that term runs before the nightly batch, the charge may appear in the wrong TouchNet accounting period. Freeze the TouchNet merchant account configuration for a term only after confirming all TBRACCD records for that term have STATUS = 'APPLIED'.
Tokenization failure on payer create. If Banner has a PIDM with a missing or malformed email address (required by TouchNet for payer creation), the POST /api/v1/payers call returns 422. These charges must be held in TOUCHNET_POST_LOG with STATUS = 'PENDING_PAYER' until SPRIDEN (Banner person table) is corrected; manual intervention required — no auto-retry.
Currency and rounding. TouchNet expects amounts as decimal strings; Banner stores

What a full implementation includes

Canonical mapping between Ellucian Banner and TouchNet, to the field level.
The edge cases that corrupt data at cutover — identified, handled, and tested.
Production-safe rollout: reversible, phased, with reconciliation checks.
Handover documentation your team can operate from.