Version 2.3 Last Update: 12/06/2017

Page 1 of 14

Shared Accounting Module

Trading Partner Integration Guide

Document Version 2.3

Table of Contents

How to Use This Document.................................................................................................2

Section 1: Services and Options...........................................................................................2

Section 2: SAM Technical Overview ..................................................................................7

Section 3: Getting Started ..................................................................................................10

Step by Step Instructions................................................................................................10

Testing Considerations...................................................................................................11

Appendix A: Revision History...........................................................................................12

Appendix B: Contact Information......................................................................................12

Appendix C: Glossary ........................................................................................................14
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 2 of 14

How to Use This Document

The purpose of the SAM Trading Partners Integration Guide is to communicate how the bureau of Fiscal

Service (FS) will bring aboard trading partners to use Shared Accounting Module (SAM) services on 

behalf of the United States Department of Treasury (US Treasury). This document addresses three 

categories of questions that are typically asked by potential trading partners:

 What types of SAM services are available, and what options are available for these services?

 What is SAM’s role in supporting the US Treasury and the Central Accounting Reporting System

(CARS)?

 What steps must be taken to establish a system interface that utilizes a SAM service?

The document is intended for the trading partner’s business and technical resources, who will be 

working with the extended SAM Team to devise a way to implement an automated interface with SAM. 

To address the questions stated above, this guide is organized into the following sections:

Section 1: Services and Options define the various methods used for obtaining services from SAM.

This information will be used to select the most effective interface options for each trading partner.

Section 2: SAM Technical Overview describes the technical architecture necessary to support SAM.

Section 3: Getting Started provides some guidance and a list of SAM contacts, to help a trading 

partner begin interfacing with SAM services.

Section 1: Services and Options

This section provides an overview of the SAM service delivery and connectivity options for trading 

partners. Trading partners should use this information to determine how best to interact with SAM to 

utilize its shared services. 

SAM currently provides three shared services to authorized trading partners. They are Reference Data Service, 

Verification Service and Classification Service. All three are covered below. 

Reference Data Service

SAM has been authorized by FMS to distribute accounting reference data to other organizations 

requiring such data. Currently SAM can distribute Agency Location Codes (ALC) and Treasury 

Account Symbols (TAS-BETC) on behalf of the Bureau of Fiscal Service. 

The Reference Data Service provides the most flexibility, where multiple formats, filters and other 

options are supported. Depending on the service, several connectivity and data transfer options are 

available. Those options are discussed below the overview.

• Reference Data Service will deliver information based on a configurable profile in SAM 

established for each trading partner.
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 3 of 14

• A dynamic database query is built when a request is initiated by a trading partner or a when 

scheduled delivery is triggered. The query is created from metadata stored with the partner 

profile. 

• SAM extracts a standardized XML document containing the requested reference data. The 

standard XML schemas are described at http://fiscal.treasury.gov/data/. 

• Depending on the partner’s needs, the standard XML may be transformed via XML stylesheet 

created for each unique data format. Utilizing XML stylesheets provides the SAM application 

flexibility for accommodating a wide variety of formatting needs without application changes.

• Triggers and Frequency dictate how and when the Reference Data Service is started. Trading

partners may choose to pull reference data from SAM, or may want SAM to push data to them.

o Pull Reference Data. Automated pull type services are currently limited to a Web 

Service data transfer method. Trading partners residing outside the TWAI environment 

who choose to pull reference data from SAM must be issued a digital certificate to be 

presented with each web service request. (See XML Gateway below).

o Push Reference Data. There are several options for triggers and frequency of automated 

interfaces involving a push of reference data from SAM to a trading partner. 

 A push of reference data may be scheduled. SAM can accommodate any 

recurring frequency (e.g., weeknights at 1 AM, every Saturday at 10 PM, etc.).

 A push of reference data may be initiated automatically when changes to the data 

type are received from the source.

 A push of reference data can also be sent on demand by the SAM team. 

Reference Data Service Options:

The Table below describes the Reference Data Service options currently available from SAM. 

Data Type Service Data Format Full File or Changes (Deltas) only Triggers

ALC Push XML, CSV, Fixed Full Scheduled

ALC Push XML, CSV, Fixed Changes Immediate

ALC Pull XML Full On demand

TAS-BETC Push XML, CSV, Fixed Full Scheduled
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 4 of 14

Reference Data Filter Options:

The table below lists the various Reference Data Record Filters available for each data type. 

Record Filters are used to reduce the number of reference data records transmitted. Introducing a filter 

limits the transmissions to those records that match one of the filter values supplied. Multiple values 

may be supplied for each record filter and multiple filters may be used. The omission of a filter allows 

all records of that type to pass. 

Data Type Record Filter Comments or Description

ALC ALC Type e.g., NTDORPT

ALC Agency Treasury agency code ... e.g., 010, 014

ALC State Currently Active or Not Expired (includes future dated)

TAS-BETC System Type Collection, Payment, NTDO Payment or Intragovernmental

TAS-BETC Main Account e.g., 0100

TAS-BETC Debit/Credit e.g., Debit (only)

TAS-BETC Agency Treasury agency identifier ... e.g., 010, 014

TAS-BETC State Currently Active or Not Expired (includes future dated)

Other Reference Data Options:

The following table describes the Other Reference Data Options that are available for data delivery. 

Name Description Comments

Changes 

Only (ALCs)

SAM detects reference data changes and limits 

transmissions to partners to just the information 

that has changed since the last transmission

This method limits the amount of data transmitted. The 

ability to process a full file is required, to seed the 

partners database and keep SAM and partner in sync.

Validate 

Before 

Transmission

SAM has an option to validate the XML output 

before it is transformed and distributed to the 

partner. If any invalid entries are found, the 

transmission will be flagged in error.

This option is most useful for XML messages, but the 

same concept may be applied to stop other formats. 

Note that SAM will accept invalid reference data (from 

CARS) as long as it does not interrupt its services.

Compression Win-zip may be applied to reduce transmission 

sizes.

Compression rates of 80-90 percent are typical, 

depending on the data format.

SOAP 

Envelope

The optional SOAP wrapper contains attributes 

such as a unique ID, transmission number, 

date/time of source update, operating 

environment, etc.

Normally XML transmissions include a SOAP 

envelope. 

The SOAP envelope is required for all “pull” requests.

An XML schema is available upon request. 
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 5 of 14

Date/time in 

file name

For transmissions involving a file (e.g., 

Connect:Direct, e-Mail), the date and time of file 

generation may be included in the file name.

The partner must decide if the new file is to overlay the 

previous one, or if each file is to have a distinct name.

Alert Level A Failure on the SAM side would trigger an 

alert. The severity would be set according to the 

partners specification.

Partners must choose whether alerts (to SAM support) 

should be sent immediately, or if a “wait until 

morning” approach is acceptable.

Presentation 

Options

XML stylesheets may be created and applied to 

transform standard XML to a custom XML, a 

CSV file or a fixed length format.

Standard XML is recommended, and a business case is 

required (from the trading partner) to deviate from the 

norm.

Reference Data Connectivity and Data Transfer:

The table below describes the Reference Data Connectivity and Data Transfer options. 

Connectivity options describe the transport mechanism used to move data from SAM to the trading 

partner. Data transfer methods describe the technology used to transport the data. 

For trading partners operating within the TWAI environment, direct connectivity is available. For 

trading partners operating outside the TWAI, connectivity options include Internet and VPN (IPSec over 

Internet). For Internet connections, data transfer method is via Web Services (SOAP over HTTPS). For 

VPN connections, a Connect:Direct file transfer method is available. 

Operating Environment Connectivity Options Data Transfer Method

TWAI Direct Web Services

TWAI Direct Connect:Direct

TWAI Direct Message Queue (MQ)

TWAI Direct Secure Transport

TWAI E-mail (TAS-BETC)

Non-TWAI Internet Web Services

Non-TWAI Internet Secure Transport

Non-TWAI VPN over Internet Connect:Direct

Non-TWAI VPN over Internet Message Queue (MQ)

Non-TWAI E-mail (TAS-BETC)
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 6 of 14

Manual Service

While most of this section is devoted to SAM’s automated services, there are two manual services 

whereby a user may pull reference data from SAM as needed. 

TAS-BETC reference data is available through a public website hosted by SAM on behalf of FMS -

https://www.sam.fms.treas.gov/sampublic. From this site any Internet user may download TAS-BETC 

reference data in CSV, Excel CSV or XML format.

ALC reference data may be downloaded directly from the SAM application by an authorized user. This 

data is available in PDF or MS-Excel formats. See Appendix B – Contact Information to request a SAM 

user ID.

Verification Service 

SAM allows Federal Agencies to set up the classification keys and default rules necessary to translate or default a 

financial transaction to valid GWA accounting codes (i.e., TAS-BETC). The Verification Service accepts 

various CARS accounting codes (i.e., ALC, TAS, BETC, TAS-BETC) from a trading partner and 

returns a verdict on whether or not the code is valid and active at the present time. 

Currently this functionality is supported only as a web service for trading partners operating in the 

TWAI environment.

Service Data Types

Data 

Format

Connectivity 

and Data 

Transfer Triggers

Record 

Filters

Other 

Options

Verification 

Service

ALC, TAS, 

BETC, 

TAS-BETC

XML

Web service 

within the 

TWAI

Requested on 

demand n/a n/a
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 7 of 14

Classification Service

The Classification Service accepts a set of financial transactions from a TWAI trading partner in a 

prescribed XML format through a Message Queue interface. SAM returns the same transactions with a 

valid set of Treasury accounting codes.

Service Data Types

Data 

Format

Connectivity 

and Data 

Transfer Triggers

Record 

Filters

Other 

Options

Classification 

Service

TAS-BETC, 

C-KEY XML MQ within the 

TWAI

Requested on 

demand n/a n/a

Section 2: SAM Technical Overview

Figure 1 (SAM High-Level Logical Architecture) depicts the technical architecture that provides the security and 

functionality necessary to support the various SAM services. 

The technical architecture supports the following major functions:

• XML Gateway • Authentication Subsystem

• E-Mail Server • User/System Directory

• User/System Provisioning • Secure File Transport

• SAM Database • Business Logic

SAM utilizes a combination of secure direct file transfers and secure web services to deliver information to a

trading partner. For some services, these delivery options are customizable for each trading partner. 
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 8 of 14

F

I

R

E

S

W

A

L

L SAM DB

SAM BUSINESS LOGIC

SAM High-Level Logical Architecture

Release 3.x

LEGEND

SAM

SUB-SYSTEM

EXTERNAL

SYSTEM

Directional Data Flow

System Connectivity

System Users

System Support Users

XML 

GATEWAY SSL/Web Services

TWAI USER/

SYSTEM

DIRECTORY

F

I

R

E

W

A

L

L

F

I

R

E

W

A

L

L

USER/SYSTEM

PROVISIONING

Ref. Data Services

(Retrieval, Validation, 

Distribution)

System Support

(Partner Profiling)

Classification Engine

Data Load

AUTHENTICATION

SUBSYSTEM

SECURE FILE

TRANSPORT

<CONNECTDIRECT>

Zone 1 Zone 2 Zone 3

TRADING

PARTNER E-MAIL

SERVER

Figure 1. SAM High-Level Logical Architecture

1. XML Gateway

The XML Gateway is a Service Oriented Architecture (SOA) appliance that is used to secure and 

accelerate XML & Web Services processing. The XML Gateway provides a variety of functionality,

including terminating the server side SSL connection between a web service client and the TWAI 

infrastructure. For SAM trading partners, the SSL is a two-way SSL connection requiring both a client 

and a server digital certificate to authenticate both ends of the connection. Without a valid client 

certificate, the XML Gateway will not establish the connection between SAM and an external trading 

partner, and access to services will be denied.

Once the two-way SSL connection has been established, the XML Gateway provides the same client 

digital certificate used to establish the connection to the Authentication System, which authenticates the 

client to the application/web service.

2. Authentication Subsystem

The Authentication system utilizes the client digital certificate to look up the web services client in the 

User/System directory, by subject name. Finding the web services client in the User/System directory 

authenticates the client to the web service. Otherwise the client is not authenticated and the 

Authentication System instructs the web services client that it is not authorized for SAM services. 
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 9 of 14

3. E-Mail Server

The e-mail server is used to distribute reference data via e-mail attachments. If the trading partner’s 

Profile indicates that data is to be distributed via e-mail, the Reference Data Service creates a file in the 

format specified in the profile. The profile contains the e-mail address where the attached data is sent. 

Presently, the (TWAI) operating environment only supports outbound e-mail messages.

4. User/System Directory

The User/System directory is an LDAP-based directory that contains information for all users and 

systems requiring access to Treasury infrastructure and applications. Once a user or system is 

authenticated, authorization information from the LDAP is provided to the application for additional 

security and other application functionality.

5. User/System Provisioning

In order for the user or system information to be contained within the user/system directory, there is 

another process that provisions users as well as external systems (such as web service clients). The 

User/System Provisioning system automates the process of provisioning user information required by 

the Authentication Subsystem and application to perform authentication and authorization functions.

The information provisioned for an external system (e.g., web service client) includes system 

identification information as well as the client digital certificate and web service-related information. 

Currently this process is manual for system provisioning and automated for user provisioning. 

SAM Administrators are primarily responsible for utilizing the User/System Provisioning interface to 

provision SAM users and external trading partners. Coordinating with the trading partner, the SAM 

System Support User ensures all information required by SAM services is provisioned in to the 

User/System Directory.

6. Secure File Transport

For file-oriented processing, the SAM architecture supports two-way secure file transfer from a trading 

partner to/from the SAM application. Files will be securely transmitted from specified locations within 

the trading partner’s infrastructure to the SAM application infrastructure.

7. SAM Database

The SAM database is a repository that contains the necessary reference data, partner profiles, 

classification rules and interface communication status. The database is fully replicated and clustered to 

handle scalability and fault tolerance requirements.

8. Business Logic

Contained within the SAM web application is the business logic that drives SAM capabilities. The 

business logic is broken out into the following areas.
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 10 of 14

a. Data Load components are used to manage reference data provided to the SAM application by 

CARS. The Data Load component uses stored procedures and temporary database tables to 

efficiently compare old and new reference data copies. Changes are logged to support 

automated communication to users and trading partners.

b. Classification Engine consists of (a) classification rules which are used to translate federal 

program agency financial transactions to valid accounting codes based on default rules and 

classification keys, and (b) default rules that are applied to financial transactions that otherwise 

would result in invalid Treasury accounting codes. Both sets of rules are maintained by the 

Federal Agencies. 

c. System Support provides the user interface and functionality for support personnel to 

customize a trading partner’s profile. The profile information is used by the SAM application 

to identify the content and format needs of a trading partner’s interface.

d. Reference Data Services and their options are described in detail in Section 1. SAM is 

available 24x7 to provide these services.

Section 3: Getting Started

The SAM Team can help you answer any questions you might have pertaining to SAM services. We 

will arrange meetings with your team to discuss the options available. 

Once all the options are understood and selected, the SAM Team can establish a test window and a GoLive date for production. Most interfaces can be configured very quickly. Lead time may be required for

trading partners to acquire and install any new products and establish connectivity with the TWAI 

environments. There may be a delay if the trading partner requires a custom data format, or some other 

special consideration.

Step by Step Instructions

1. Contact someone on the SAM Team or one of the resources listed in Appendix E to get your

initial questions answered.

2. Meet with the SAM Team to discuss your business requirements. Discuss the information in this 

guide to chose data format and connectivity options.

3. Work with the SAM Team if you require documentation such as Memo of Understanding or 

Interface Specifications. 

4. Work with the SAM and TWAI teams to establish and test connectivity to your Test and 

Production environments. 

5. Procure any hardware and/or software necessary to establish connectivity to the Treasury Web 

Application Infrastructure (TWAI) Test and Production environments.

6. Issue any required certificates, providing system access to SAM or trading partner’s application.

7. Test your automated interface(s) with the SAM Team. (See Testing Considerations below).

8. Support the new interface(s) throughout the Go-Live period.

9. Monitor your interface(s) on an ongoing basis.
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 11 of 14

Testing Considerations

Testing ensures that all chosen interface options are completely understood, are configured properly and 

support the needed reference data transmissions in the production environment. Testing the interface 

between the TWAI Quality Assurance (QA) environment and the trading partner’s test environment is 

mandatory for all trading partners, prior to migration to the production. SAM also has a Functional Test 

(FT) environment available for testing.

Sufficient lead-time should be included to establish connectivity to the test environment(s), based on 

both TWAI and trading partner resource availability. All available technologies for data transfer are 

available for testing in the QA environment, including full support for all security controls applied.
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 12 of 14

Appendix A: Revision History

Ver. Author Revised Description

1.0 W. Schmidt 11/24/2007 Initial version --- architecture section by Dave Baganski

1.1 W. Schmidt 12/8/2007 Minor changes suggested by SAM mgt.

1.2 W. Schmidt 1/21/2008 Enhanced to include SAM 3.7 functionality

1.3 W. Schmidt 2/26/2008 Updated contact info.

1.4 W. Schmidt 2/15/2009 Enhanced to include SAM 3.8 functionality and show new business owners

1.5 W. Schmidt 8/31/2009 Drafted version 2.0 (as v1.5) – describing all SAM services

1.6 W. Schmidt 9/18/2009 Changes based on input from IPAC (for v1.4) and CBAF (for v1.5)

1.7 W. Schmidt 4/27/2010 Updated contact info and removed the Access Group record filter for ALCs

1.8 W. Schmidt 7/21/2010 XML over HTTPS is no longer an option ... always wrapped in SOAP

2.0 K. Hood 3/11/2013 Re-write---removed ABA reference data, TAS-BETC changes. Added validate 

before transmission

2.1 K. Hood 12/2/2013 Remove CGAC only filter for TAS-BETCs

2.2 K. Hood 7/7/2015 Added Secure Transport

2.3 K. Hood 12/5/17 Updated contact information 

Appendix B: Contact Information

Topic Contact Role/Resp. Phone # Address

More Information 

on FMS

FMS Website http://www.fiscal.treasury.gov/

More Information 

on CARS

CARS

Website

http://fiscal.treasury.gov/cars/

More Information 

on SAM

SAM Website http://www.fiscal.treasury.gov/sam/index.

html

Standard FMS 

XML Schemas

EDA Website http://fiscal.treasury.gov/data/

TAS-BETC 

Manual Download

SAM Public 

Website https://www.sam.fms.treas.gov/sampublic
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 13 of 14

SAM Business 

Guidance

Cyndi Pham FMS Business 

Owner

(202)874-8947 Cyndi.Pham@fiscal.treasury.gov

SAM Business 

Guidance

Matt 

Horenkamp

SAM Business 

Manager

(314)444-4773 matt.r.horenkamp@stls.frb.org

SAM Technical 

Guidance

Karen Hood SAM Technical 

Analyst

(314)444-8648 cbaf.cars.support@stls.frb.org

XML Schemas Enterprise Data 

Architecture

Data.Info@fiscal.treasury.gov

ALC Manual 

Download

Treasury 

Support Center

Provide new 

SAM user ID

(877)440-9476 sam_tsc@stls.frb.org

Request Automated 

Interface

Karen Hood Service Request 

Processing

(314) 444-8648 cbaf.cars.support@stls.frb.org

Test Automated 

Interface

Karen Hood Service Request 

Processing

(314)444-8648 cbaf.cars.support@stls.frb.org

Problems with 

Auto. Interface

Treasury 

Support Center

Service Request 

Processing

(877)440-9476 sam_tsc@stls.frb.org
Shared Accounting Module Trading Partners Integration Guide

Version 2.3 Last Update: 12/06/2017

Page 14 of 14

Appendix C: Glossary

ALC – Agency Location Code, which identifies a virtual or physical location of a Federal agency

BETC – Business Event Type Code, which describes the purpose of a financial transaction (e.g., collection 

adjustment)

CAFÉ – Central Accounting Front End, which is a module of GWA that accepts financial transactions from 

systems reporting to the US Treasury

CARS – Central Accounting Reporting System, the US Treasury’s core accounting systems

C-Key – Classification Key, which may be used to translate a Federal agency’s accounting codes to the US 

Treasury’s accounting codes

CSV – Comma Separated Value, which is a data format commonly used as input to spreadsheet applications

ERD – Enterprise Reference Data, which is fairly static information commonly used to report transactional data

FMS – Financial Management Service, which is a bureau of the US Treasury

LDAP – Lightweight Directory Access protocol, which is used to house access information

MS – Microsoft, the vendor that supports the Excel spreadsheet product

PDF – Portable Document Format, which is primarily used for formatting print documents

SAM – Shared Accounting Module

Service Request – A form completed by the SAM team for each system interface established between SAM and a 

trading partner. This service request forms the basis of a Partner Profile.

SOA – Service Oriented Architecture, whereby common business needs are automated in one place

SSL – Secure Sockets Layer, which provides security and data integrity for communications over the Internet

TAS – Treasury Account Symbol, which is a budgeted account for a financial transaction. Beginning in 2010, the 

“symbol” is being replaced by a set of eight business keys, commonly known as TAS components.

Trading Partner – a system with which SAM has an automated exchange of data

TWAI – Treasury Web Application Infrastructure, which is the environment in which the SAM application runs

UPS – User Provisioning Service, used by SAM and other TWAI applications to control access

URL – Uniform Resource Locator, which is a Web address

XML – eXtensible Markup Language, which is a self-describing format of data