ESM_Attachment 4 Pay.Gov Technical Overview Final.pdf

i

Web Services Technical Overview December 15, 2021

ATTACHMENT 4

ii

This version of the Web Services Technical Overview supersedes all previous versions.

© Copyright 2021 Federal Reserve Bank of Cleveland

EuroPay® is a registered trademark of MasterCard Worldwide.

MasterCard® is a registered trademark of MasterCard International Incorporated.

Visa® is a registered trademark of Visa Inc.

American Express ® is a registered trademark of American Express Company

Discover® is a registered trademark of Discover Bank.

JCB® is a registered trademark of JCB Co., Ltd.

Union Pay® is a registered trademark of China UnionPay Co, Ltd.

Diners Club is a registered trademark of Diners Club International® Ltd a subsidiary of Discover Financial Services.

Pay.gov® is a registered trademark of the United States Department of the Treasury, Bureau of the Fiscal Service iii

Revision History Date Author Description

December 1, 2015 Walter Rowinsky FRB Cleveland

Initial version.

This document replaces the overview sections of the Trusted Collection Services and Pay.gov Hosted Collection Pages Technical Reference Manual.

June 13, 2016 Walter Rowinsky FRB Cleveland

Updated for Pay.gov 6.9 (updated sections 2, 4.5)

August 1, 2016 Walter Rowinsky FRB Cleveland

Renamed the document (updated sections 1, 5.6 5.7, 5.8; corrected typos).

September 18, 2016 Walter Rowinsky FRB Cleveland

Reviewed for Pay.gov 6.10 (no changes).

December 17, 2016 Walter Rowinsky FRB Cleveland

Reviewed for Pay.gov 6.11 (no changes).

April 17, 2017 Walter Rowinsky FRB Cleveland

Updated for Pay.gov 7.0 (added sections

7.1.1 and 7.2.1).

July 17, 2017 Walter Rowinsky FRB Cleveland

Updated for Pay.gov 7.1 (updated section 7.6; added new section 7.7).

October 16, 2017 Walter Rowinsky FRB Cleveland

Updated for Pay.gov 7.2 (added new section 7.1; updated section 3.1).

January 17, 2018 Walter Rowinsky FRB Cleveland

Updated for Pay.gov 7.3 (updated section 4).

July 16, 2018 Walter Rowinsky FRB Cleveland

Updated for Pay.gov 7.5 (added sections 7.2.2, 7.3.2, and 7.3.3).

April 1, 2019 Walter Rowinsky FRB Cleveland

Updated for Pay.gov 7.8 (added new sections 7.7.3 and 7.8.3).

July 1, 2019 Walter Rowinsky FRB Cleveland

Updated for Pay.gov 7.9 (updated section 7.6.1; updated website URLs;

corrected typos).

December 15, 2021 Walter Rowinsky FRB Cleveland

Deleted old section 7.5; updated sections 7.2, 7.3, 74, and new 7.5.

iv v

Table of Contents Revision History ............................................................................................... iii 1 Introduction

1.1 Related Documents

2 Web Services Overview

2.1 Non-Interactive Web Services

2.2 Interactive Web Services

2.3 Query Web Services

3 Security

3.1 Key Technologies

4 Accepted Payment Methods

4.1 All Pay.gov Web Services

4.2 Hosted Collections Pages and eBilling Web Services

4.3 Constraints

5 TAS/BETC

6 Custom Collection Fields 7 Web Service Descriptions

7.1 ACH Credit Web Service

7.2 TCS Single Web Service

7.3 TCS Batch Web Service

7.4 TCS Batch Results Web Service

7.5 Pay.gov Hosted Collection Pages

7.6 eBilling Web Services

7.7 eBilling Online Application

7.8 eBilling Online Web Service

7.9 Query Web Services

8 Testing 9 Customer Support

9.1 Contact Information

vi

1 Introduction This document provides an overview of Pay.gov’s TCS, eBilling, and Hosted Collection Pages web services.

It should be read by managers, developers and support staff involved with connecting their applications to a Pay.gov web service.

1.1 Related Documents

Separate technical references for each web service are available by request through the Pay.gov Agency Documentation site at https://qa.pay.gov/agencydocs/ or by contacting Pay.gov Customer Support.

Developers and technical support staff:

Request a copy of the Web Service Data Elements and Types, Return Codes and Country Codes reference and the technical reference for the web service you are implementing.

https://qa.pay.gov/agencydocs/

Web Services Overview

2 Web Services Overview Pay.gov’s suite of web services use industry-standard methods, which allow agency collection applications to use a single interface for their communications with Pay.gov. Pay.gov web services include non-interactive server-to-server interfaces and interactive interfaces that allow direct customer interaction when submitting information on Pay.gov.

A typical Pay.gov web service involves a request messages submitted by the agency and response messages returned by Pay.gov. The messages are in the form of XML files that conform to the schema specific to the web service used.

A message can include one or multiple transactions, depending on the web service.

2.1 Non-Interactive Web Services

Figure 1: Conceptual diagram of a non-interactive web service

Non-interactive web services are server-to-server interfaces used when an agency:

1. Collects all transaction data, including payment information, on its own system.

2. Submits the data to Pay.gov for processing in the form of a request message that:

• identifies the particular web service

• includes information about what is being submitted or requested. \

3. Pay.gov’s system responds with a message that:

• acknowledges the request

• provides Pay.gov-specific identification information for the transaction

• can include transaction and payment status

• can include detailed information about one or more transactions

• includes a status indicating the state of the transaction, for example, approved or declined

• includes data specific to the transaction.

The Pay.gov non-interactive web services are

• TCS Single Web Service

• TCS Batch Web Service

• TCS Batch Results Web Service

• TCS Plastic Card Web Service

• eBilling Web Services

2.2 Interactive Web Services

Figure 2: Conceptual diagram of an interactive web service

Pay.gov interactive web services are used when redirecting a customer from an agency’s site to Pay.gov’s website and returning them to the agency.

Pay.gov provides no stand-alone interactive web service, but the Hosted Collection Pages Web Service combines non-interactive and interactive web services. See section 7.6.

2.3 Query Web Services

Pay.gov provides non-interactive query web services. These allow agencies to make ad hoc requests for detailed information about one or more transactions.

The agency’s query request identifies the transaction or transactions being sought

Pay.gov’s response returns detailed information about the requested transaction(s).

Pay.gov’s query web services are

• TCS Single Query Web Service

• TCS Multiple Query Web Service

3 Security

3.1 Key Technologies

• HTTPS: HTTP/1.1 TLS/1.2 (Transport Layer Security), documented by

Internet RFC 2246, provides secure connections for data transmission.

• Industry-standard technology: Each Pay.gov web service is described by a

Web Services Definition Language (WSDL) file and one or more related XML Schema Document (XSD) files. By implementing web services, Pay.gov is able to present a single, industry-standard interface to the services offered.

• Certificate-based authentication: Pay.gov requires the use of security certificates issued by the U.S. Treasury’s certificate authority (TOCA) to identify and authenticate agency application servers and to communicate with Pay.gov.

You must obtain a security certificate before beginning development.

Contact your Pay.gov Agency Implementation Liaison to request a new certificate. Request the Pay.gov SSL Certificate Support Guide for instructions.

Note: Agencies already using a security certificate with an application that communicates with any Pay.gov web service may use the same certificate for all Pay.gov web services.

4 Accepted Payment Methods

4.1 All Pay.gov Web Services

All your web service applications may be configured to accept:

• ACH Debit (business and personal)

• Checking

• Savings

• General Ledger

• Plastic Card

• MasterCard®

• Visa®

• American Express®

• Discover-branded cards including (all are processed as Discover Cards):

• Discover®

• JCB®

• Union Pay®

• Diners Club® cards displaying the Discover logo (some do not)

• ACH Debit cards bearing the MasterCard or Visa logo

4.2 Hosted Collections Pages and eBilling Web Services

In addition to the payment methods above, Hosted Collection Pages and the eBilling Web Services applications can be configured to accept Digital Wallet payments.

• Amazon Pay®

• PayPal® (including PayPal Credit)

4.3 Constraints

The payment methods your application can accept depend on:

• The web service employed.

• Payment amounts (large payments might be restricted to ACH Debit).

• The purpose of the collection.

Contact your Bureau of the Fiscal Service and Pay.gov Agency Implementation Liaisons for advice on acceptable payment methods.

5 TAS/BETC

All web services used to submit transactions or create ebills support TAS/BETC classification data.

6 Custom Collection Fields All web services used to submit transactions or create ebills support agency custom collection fields.

7 Web Service Descriptions Following are summary descriptions of the available TCS services. Detailed technical information for each service can be found in the corresponding technical reference, available by request at https://qa.pay.gov/agencydocs/ or by contacting Pay.gov Customer Support.

7.1 ACH Credit Web Service

The non-interactive ACH Credit Web Service allows an agency to submit or cancel ACH Credit transactions on behalf of customers for immediate processing. ACH Credit transactions are submitted to Pay.gov in system-to-system request messages. A request message can include from one to 500 transactions.

Unlike an ACH debit, no actual payment is made on Pay.gov at the time the transaction is created. Instead, a “promise” to pay via an ACH funds transfer is recorded. Pay.gov responds to a request with the instructions and information needed to complete the transaction. The customer must then provide the instructions and information to their financial institution and authorize the funds transfer. The payment must be completed within 60 calendar days.

7.1.1 Payment Methods Accepted

Only ACH Credit transactions can be created by the web service.

7.1.2 Supported ACH Accounts

The customer’s account used for ACH Credit is not seen by Pay.gov. Customers can use any ACH account their bank allows for ACH Credit transactions.

7.1.3 Minimum and Maximum Amount Limits

Payments are limited to a maximum of $99,999,999.99, or the amount available in the funding account.

7.2 TCS Single Web Service

The non-interactive TCS Single web service is used by an agency application to send a single collection to Pay.gov for immediate processing. Customers or agency users never leave the agency’s application or website. Upon receipt, Pay.gov processes the collection request and forwards collection information to the appropriate settlement provider.

Pay.gov then responds to the agency application with the collection results. For plastic card transactions, which are sent to the processor immediately, this is the actual accept or decline. For ACH debit transactions, this just indicates that the payment request was received by Pay.gov and will be forwarded for settlement.

Collection transactions that can be submitted include

• ACH Debit

• ACH Prenotification

• ACH Cancel https://qa.pay.gov/agencydocs/

• Plastic Card Sale

• Plastic Card Authorization

• Plastic Card Force

• Plastic Card Refund

• Plastic Card Cancel

Details about a transaction, including real-time settlement information, can be retrieved using the TCS Single Item Query or the TCS Multiple Item Query web services.

7.2.1 Minimum and Maximum Amount Limits

Agency cash flow applications using the TCS Single Web Service can be configured to accept only transactions whose amounts fall into a minimum to maximum range. The range can be specified during initial setup in Pay.gov or by modifying the configuration later. Contact your Pay.gov Agency Implementation Liaison for more information.

7.2.2 Duplicate Transaction Detection

Agencies have the option to enable duplicate transaction detection for their cash flow applications using the TCS Single Web Service. The option examines submitted transactions to determine if they share an Agency Tracking ID with a previously submitted transaction. If the new transaction shares the same ID with a previous transaction it is rejected by Pay.gov.

7.3 TCS Batch Web Service

The non-interactive TCS Batch web service allows an agency application to send multiple collection transactions in a single transmission to Pay.gov for offline processing.

It is best suited for agencies that need to process large volumes of transactions that do not require immediate processing/response, or whose workflow is best suited to batch processing.

A single batch can include a mix of collection transaction types:

• ACH Debit

• ACH Prenotification

• ACH Cancel

• Plastic Card Sale

• Plastic Card Authorization

• Plastic Card Force

• Plastic Card Refund

• Plastic Card Cancel

When multiple actions, such as forces, or refunds, are taken on a single transaction, Pay.gov recommends that agencies include only one of these actions in any batch.

Ordinarily, TCS Batch returns a message showing that the batch was submitted. If additional information about the batch is needed, use the TCS Batch Results web service to determine if it was successfully processed and its individual transactions were successfully submitted.

The services completeOnlineCollectionWithDetails and getDetails request messages return transaction details. Optionally, if additional information is needed including real-time settlement information for a transaction, use TCS Single Item Query or the TCS Multiple Item Query web services.

7.3.1 Minimum and Maximum Amount Limits

Agency cash flow applications using the TCS Single Web Service can be configured to accept only transactions whose amounts fall into a minimum to maximum range. The range can be specified during initial setup in Pay.gov or by modifying the configuration later. Contact your Pay.gov Agency Implementation Liaison for more information.

7.3.2 Duplicate Batch Detection

Agencies have the option to enable duplicate batch detection for the TCS Batch Web Service. When the option is enabled, Pay.gov compares the newly submitted batch with previously submitted batches. If the new batch exactly matches a previous batch, it is flagged as a potential duplicate, the transactions in it are not processed, and Pay.gov contacts a designated approver at the agency to accept or reject the batch. Approved batches are reprocessed and their transactions are completed. Pay.gov fails batches rejected by the approver.

The new batch is compared to batches submitted during a number of previous calendar days (up to 365). This look back period is determined by the agency in the cash flow application’s configuration.

Approvers have seven calendar days to approve or reject a potentially duplicate batch. If no action is taken, Pay.gov fails the batch and its transactions are not processed.

7.3.3 Duplicate Transaction Detection

Agencies have the option to enable duplicate transaction detection for the TCS Batch Web Service. When the option is enabled, Pay.gov examines a submitted batch to determine if any transactions contained share an Agency Tracking ID or if they share the ID with a previously submitted transaction. If a duplicate ID is detected, the new transaction is rejected by Pay.gov and not processed. All other transactions in the batch are processed.

7.4 TCS Batch Results Web Service

The non-interactive TCS Batch Results web service provides a way to determine:

• Whether or not a particular batch of transactions was successfully processed.

• Whether or not each individual transaction within the batch was successfully submitted for processing..

This service does not provide the current settlement status of any transaction; it only identifies whether or not Pay.gov was able to submit the transaction for collection.

Use the TCS Single Item Query or the TCS Multiple Item Query web services to receive real-time settlement status information.

7.5 Pay.gov Hosted Collection Pages

The Pay.gov Hosted Collection Pages Web Service allows agencies to process transactions without the need to handle customers’ sensitive financial payment data. Transactions start on the agency’s website, are redirected to Pay.gov to make the payment, and return to the agency to complete the transaction.

Hosted Collection Pages transactions use non-interactive web services for agency-Pay.gov interaction

• to associate a customer’s activity on the agency’s site with their activity on Pay.gov

• to complete the transaction.

Interactive web services are used:

• to redirect a customer to Pay.gov to make their payment

• to return the customer to the agency’s site.

Transaction security and customer confidence is enhanced because agencies do not see any customer financial information for the payment. Agencies are only aware of the payment being approved or declined. Agency system overhead is reduced since the agency does not store any payment information.

Use the TCS Single Item Query or the TCS Multiple Item Query web services to receive real-time settlement status information.

7.5.1 Payment Methods Accepted

Depending on how your collection application is configured, payment methods accepted can include:

• ACH Debit payments

• Pay.gov accepted plastic card payments, including ACH debit cards

• Digital Wallet payments

• Amazon

• PayPal (including PayPal credit)

7.5.2 Transactions Not Supported

• Creating recurring transactions.

• Refunding transactions.

• Canceling transactions.

Use the Transaction Search service on the Agency Collections website or another TCS web service to conduct these transactions.

7.5.3 Customizing a Payment Page

Only limited customization is available. You can:

• supply a custom image, such as your agency logo, that will replace the Pay.gov logo on the payment pages (jpg/jpeg, png or gif file no larger than

2MB)

• specify a payment page footer color, to conform with your agency website colors for example

7.6 eBilling Web Services The non-interactive eBilling services are comprised of two separate web services.

Both are required to issue ebills.

7.6.1 The eBillingService is used to

• create single ebills or batches of multiple ebills

• deactivate ebills after the close of a payment window

• cancel pending ebills

• overlay (replace) ebills with a new version of the bill

7.6.2 The AccessCodeService is used to manage access to an ebill

• create an access code that must be used to view an ebill

• designate if the ebill is public or private

• provide the answer to the ebill’s security question

• specify if a customer must log in to Pay.gov to view an ebill

• cancel an access code

• resend an access code

• supply customer email addresses if Pay.gov will send ebilling notices

7.6.3 Features

eBilling Web Services are best used by agencies that issue large numbers of bills regularly or periodically.

• eBills do not list line items, but details can be provided in attachment files.

• Your agency works with Pay.gov to create a custom template for your online ebills. The online ebill can resemble their paper versions, including agency and OMB numbers.

• Agencies can specify issue dates and due dates for individual ebills.

• Agencies can specify deactivation dates for individual ebills. Customers will not be able to pay the ebill after the deactivation date.

• eBill and payment details are available in Pay.gov online reports and activity files.

7.6.4 Types of eBills

Public eBills are available to any customer visiting Pay.gov’s public website, provided they have the required access code and can answer the ebill’s security question. Every time a customer wishes to access a public ebill they must provide the access code and answer the security question.

Hidden Public Bills are available only to customers who have been given the bill’s URL by your agency. The customer must still enter the bill’s access code and answer its security question before they can access it.

Private eBills are available only to customers who log in to Pay.gov’s public website. When they access the ebill for the first time, the customer must provide the required access code and answer the ebill’s security question. The eBill is then added to their Pay.gov account and can be viewed any time they log in. This is the default when creating an ebill’s access code.

After viewing their bills, customers can make payments on associated Pay.gov payment pages.

7.6.5 Automatic Bill Payments (AutoPay)

eBilling Online Web Service cash flow applications can be configured to allow customer bill payers to enroll in Automatic Bill Payment (AutoPay), which allows bill issued to the customer to be automatically paid form a designated account without the customer needing to take any action.

See the Guide to Automatic Bill Payment for further information.

7.6.6 eBilling Notices

An ebilling notice alerts a customer that they have an ebill available for viewing on Pay.gov and provides them with the access code.

During application configuration, you can chose to have Pay.gov send ebilling notices to customers by email on your agency’s behalf, or choose to send out notices on your own.

For notices sent by Pay.gov, an online report lists email that could not be delivered.

7.6.7 Security Question and Answer

Your agency is responsible for creating an ebill’s security question and corresponding answer.

It is also responsible for communicating the question and answer to the billed customer.

7.6.8 Payment Methods Accepted

Depending on how your ebilling application is configured, payment methods accepted can include:

• ACH Debit payments

• Pay.gov accepted plastic card payments, including ACH debit cards

• Digital Wallet payments

• Amazon

• PayPal.

7.6.9 Alternatives to the eBilling Web Services

• The eBilling Online Application

• eBilling Online Web Service

7.7 eBilling Online Application Agencies issuing small numbers of bills, singly or in batches should use the interactive eBilling Online application on Pay.gov’s Agency Collections website.

This is not a web service. Instead, agency users enter information in a web pages to create ebills and access codes in real time. eBills can be created singly or in small batches.

A standard Pay.gov template is used for all online ebills, but allows some customization by your agency. Use the application to add a logo or image, custom header and footer comments, and to add custom billing fields. The logo, header and footer comments created with the application are also made available to the eBilling Online Web Service.

See the Agency Guide to the eBilling Online Application for details.

7.8 eBilling Online Web Service The non-interactive eBilling Online Web Service is separate from the eBilling Web Services and from the eBilling Online Applicattion.

The eBilling Online Web Service enables agencies to create eBills in batches of up to 500 at a time by submitting XML request messages through a system-to-system interface with Pay.gov.

Issuing an ebill requires the use of two services:

The eBillingOnlineService is used to

• create single ebills or batches of multiple ebills

• set bill issue and due dates

• cancel pending ebills

• replace ebills that are past due or whose balance has changed

The AccessCodeService is used to manage access to an ebill

• create an access code that must be used to view an ebill

• designate if the ebill is public or private

• provide the answer to the ebill’s security question

• specify if a customer must sign in to Pay.gov to view an ebill

• cancel an access code

• resend an access code

• supply customer email addresses if Pay.gov will send ebilling notices

7.8.1 Features

The eBilling Online Web Service is optimized for agencies that issue large numbers of bills, who want to offer their customers additional ebill payment options, and who do not need extensive bill customization (such as requiring online ebill to resemble their paper versions).

• Line items in each ebill must be listed individually. Customers can see what is being billed for at a glance.

• Agencies have the option to allow customers to pay line items individually instead of requiring payment for the entire ebill. Pay.gov automatically replaces the ebill with a new one for the remaining balance.

• Agencies can apply payments (partial or full) received outside of Pay.gov to an ebill. Such payments are applied to individual line items and noted on the ebill. For example, a partial payment received by check is applied to one of the line items and is deducted from the bill total due.

• Agencies have the option to allow customers to pay an extra amount in addition to the bill total.

• All online ebills are created using a Pay.gov-maintained template. Only minor customization is available: inserting a logo, header text, and footer text.

• eBill and payment details are available in Pay.gov online reports and activity files.

7.8.2 Types of eBills

Public eBills are available to any customer visiting Pay.gov’s public website, provided they have the required access code and can answer the ebill’s security question. Every time a customer wishes to access a public ebill they must provide the access code and answer the security question. This is a choice when creating the ebill’s access code.

Hidden Public Bills are available only to customers who have been given the bill’s URL by your agency. The customer must still enter the bill’s access code and answer its security question before they can access it.

Private eBills are available only to customers who log in to Pay.gov’s public website. When they access the ebill for the first time, the customer must provide the required access code and answer the ebill’s security question. The eBill is then added to their Pay.gov account and can be viewed any time they log in. This is the default when creating an ebill’s access code.

After viewing their bills, customers can make payments on associated Pay.gov payment pages.

7.8.3 Automatic Bill Payments (AutoPay)

eBilling Online Web Service cash flow applications can be configured to allow customer bill payers to enroll in Automatic Bill Payment (AutoPay), which allows bill issued to the customer to be automatically paid form a designated account without the customer needing to take any action.

See the Guide to Automatic Bill Payment for further information.

7.8.4 eBilling Notices

An ebilling notice alerts a customer that they have an ebill available for viewing on Pay.gov and provides them with the access code.

During application configuration, you can chose to have Pay.gov send ebilling notices to customers by email on your agency’s behalf, or choose to send out notices on your own.

For notices sent by Pay.gov, an online report listing email that could not be delivered is available.

7.8.5 Security Question and Answer

Your agency is responsible for creating an ebill’s security question and corresponding answer.

It is also responsible for communicating the question and answer to the billed customer.

7.8.6 Payment Methods Accepted

Depending on how your ebilling application is configured, payment methods accepted can include:

• ACH Debit payments

• Pay.gov accepted plastic card payments, including ACH debit cards

• Digital Wallet payments

• Amazon

• PayPal.

7.9 Query Web Services

Query web services can be used ad hoc to retrieve details on any collections transaction in Pay.gov, regardless of the service used to create the transaction.

7.9.1 TCS Single Query

The non-interactive TCS Single Query Web Service allows an agency to query Pay.gov on an ad hoc basis for the details and results of a single collections transaction. This could be used as part of an automated reconciliation process where an agency application requests a status update for a previously-submitted transaction.

It is best used for one-time queries.

Agencies needing to repeatedly query large numbers of transactions should investigate Pay.gov’s activity file functionality. See the Agency Guide to the Reporting Service for details.

7.9.2 TCS Multiple Item Query

The non-interactive TCS Multiple Item Query Web Service allows an agency to query Pay.gov on an ad hoc basis for the results of one or more collections transactions that occurred during a specified twenty-four-hour window.

Multiple Item Query is best used for one-time queries. It could be used as part of an automated reconciliation process where an agency application requests a status update on a previously submitted transaction.

Agencies with a need for a daily transaction report should investigate Pay.gov’s activity file functionality. See the Agency Guide to the Reporting Service for details

8 Testing Agencies should:

• test their web service applications for all payment types accepted with all of the interfaces that they will use in production.

• test during application development

• test whenever a new Pay.gov release enhances Pay.gov’s web services

• test any queries or activity file downloads against both completed transactions and declined transactions.

Testing URLs differ according web service. See the Agency Guide to Testing Applications for a list.

9 Customer Support

9.1 Contact Information

Hours: 8:00 am to 7:00 pm Eastern Time

Monday through Friday, closed bank holidays

Phone: (800) 624-1373

Email Address: pay.gov.clev@clev.frb.org mailto:pay.gov.clev@clev.frb.org