OFX Banking Specification v2.3
OFX Banking Specification v2.3
OFX Banking Specification v2.3
Specification
Version 2.3
October 2020
A royalty-free, worldwide, and perpetual license is hereby granted to any party to use the Open Financial
Exchange Specification to make, use, and sell products and services that conform to this Specification.
THIS OPEN FINANCIAL EXCHANGE SPECIFICATION IS MADE AVAILABLE “AS IS” WITHOUT
WARRANTY OF ANY KIND. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
PUBLISHERS FURTHER DISCLAIM ALL WARRANTIES, INCLUDING WITHOUT LIMITATION
ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT, ALL OF WHICH ARE HEREBY DISCLAIMED. THE
ENTIRE RISK ARISING OUT OF THE USE OF THIS SPECIFICATION REMAINS WITH
RECIPIENT. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT
SHALL THE PUBLISHERS OF THIS SPECIFICATION BE LIABLE FOR ANY CONSEQUENTIAL,
INCIDENTAL, DIRECT, INDIRECT, SPECIAL, PUNITIVE, OR OTHER DAMAGES WHATSOEVER
(INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS,
BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY
LOSS) ARISING OUT OF ANY USE TO WHICH THIS SPECIFICATION IS PUT, EVEN IF THE
PUBLISHERS HEREOF HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Revision History
Refer to Appendix C “Change History” for a complete document revision history.
ii
TABLE OF CONTENTS
Chapter 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.1.1 Design Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.2 Open Financial Exchange at a Glance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.2.1 Data Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.2.2 Request and Response Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.2.3 HTTP Form Request and Response Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
1.3 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.3.1 User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.3.2 Financial Institution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.3.3 Service Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.3.4 Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.3.5 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.3.6 Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.3.7 Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.3.8 Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.3.9 Aggregate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.3.10 Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.3.11 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.3.12 Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.3.13 Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.3.14 Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.3.15 Message Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
1.4 OFX Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
1.5 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Chapter 2 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.1 HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.2 Open Financial Exchange File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
2.2.1 OFXHEADER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.2.2 VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.2.3 SECURITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.2.4 OLDFILEUID and NEWFILEUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.3 XML Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.3.1 Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
1.1 Introduction
Open Financial Exchange is a broad-based framework for exchanging financial data and instructions
between customers and their financial institutions. It allows institutions to connect directly to their
customers without requiring an intermediary.
Open Financial Exchange is an open specification that anyone can implement: any financial institution,
transaction processor, software developer, or other party. It uses widely accepted open standards for data
formatting (such as XML), connectivity (such as TCP/IP and HTTP), and transport-level security.
Open Financial Exchange defines the request and response messages used by each financial service as well
as the common framework and infrastructure to support the communication of those messages. This
specification does not describe any specific product implementation.
18 1.1 Introduction
based—to perform financial activities. For example, a customer can track personal finances at home
with a desktop application and occasionally pay bills while at work with a Web-based application. The
use of data synchronization to support multiple clients is a key innovation in Open Financial Exchange.
• Robust – Open Financial Exchange will be used for executing important financial transactions and for
communicating important financial information. Assuring users that transactions are executed and
information is correct is crucial. Open Financial Exchange provides robust protocols for error recovery.
• Secure – Open Financial Exchange provides a framework for building secure online financial
services. In Open Financial Exchange, security encompasses authentication of the parties involved, as
well as secrecy and integrity of the information being exchanged including various MFA solutions.
• Batch & Interactive – The design of request and response messages in Open Financial Exchange is
for use in either batch or interactive style of communication. Open Financial Exchange provides for
applying a single authentication context to multiple requests in order to reduce the overhead of user
authentication.
• International Support – Open Financial Exchange is designed to supply financial services
throughout the world. It supports multiple currencies, country-specific extensions, and different forms
of encoding such as UNICODE.
• Platform Independent –Open Financial Exchange can be implemented on a wide variety of front-
end client devices. It also supports a wide variety of Web-based environments and messaging
frameworks, including those using SOAP, HTML, Java, JavaScript, or ActiveX. Similarly on the back-
end, Open Financial Exchange can be implemented on a wide variety of server systems, including those
running UNIX, Windows NT, or OS/2.
• Transport Independent – Open Financial Exchange is independent of the data communication
protocol used to transport the messages between the client and server computers. Open Financial
Exchange 2.2 uses HTTP.
Open Financial Exchange uses the Internet Protocol (IP) suite to provide the communication channel
between a client and a server. IP protocols are the foundation of the public Internet and a private network
can also use them.
To communicate by means of Open Financial Exchange over the Internet, the client must establish an
Internet connection. This connection can be a dial-up Point-to-Point Protocol (PPP) connection to an
Internet Service Provider (ISP) or a connection over a local area network that has a gateway to the Internet.
Clients use the HTTP POST command to send a request to the previously acquired Uniform Resource
Locator (URL) for the desired financial institution. The URL presumably identifies a Common Gateway
Interface (CGI) or other process on an FI server that can accept Open Financial Exchange requests and
produce a response.
<!--XML declaration-->
<?xml version="1.0"?>
<!--OFX declaration-->
<?OFX OFXHEADER="200" VERSION="220" SECURITY="NONE" OLDFILEUID="NONE"
NEWFILEUID="NONE"?>
<!--OFX request-->
<OFX>
... Open Financial Exchange requests ...
</OFX>
A blank line defines the separation between the HTTP headers and the start of the Open Financial
Exchange headers.
The structure of a response is similar to the request, with the first line containing the standard HTTP result,
as shown next. The content length is given in bytes.
<!--XML declaration-->
<?xml version="1.0"?>
<!--OFX declaration-->
<?OFX OFXHEADER="200" VERSION="220" SECURITY="NONE" OLDFILEUID="NONE"
NEWFILEUID="NONE"?>
<!--OFX response-->
... Open Financial Exchange responses ...
</OFX>
Here is a simplified example of an Open Financial Exchange request file. (This example does not show the
Open Financial Exchange headers and the indentation is only for readability.) For complete details, see the
more complete examples throughout this specification.
<BANKMSGSRQV1>
<STMTTRNRQ> <!-- First request in file -->
<TRNUID>1001</TRNUID>
<STMTRQ> <!-- Begin statement request -->
<BANKACCTFROM> <!-- Identify the account -->
<BANKID>121099999</BANKID> <!-- Routing transit or other FI
ID -->
<ACCTID>999988</ACCTID> <!-- Account number -->
<ACCTTYPE>CHECKING</ACCTTYPE><!-- Account type -->
</BANKACCTFROM> <!-- End of account ID -->
<INCTRAN> <!-- Begin include transaction --
>
<INCLUDE>Y</INCLUDE> <!-- Include transactions -->
The response format follows a similar structure. Although a response, such as a statement response,
contains all of the details of each transaction, each individual detail of the statement is identified using
tags.
The key rule of Open Financial Exchange syntax is that each tag is either an element or an aggregate. Data
follows its element tag. An aggregate tag begins a compound tag sequence, which must end with a
matching tag; for example, <AGGREGATE> ... </AGGREGATE>.
The file sent by Open Financial Exchange does not require any white space between tags.
White space following a tag delimiter (>), following an element value, or preceding a tag delimiter (<)
should be ignored. White space within an element value (i.e. not preceding, not following) is significant. If
white space is desired preceding or following an element value, this is achieved using the CDATA
wrapper. If more than one white space element is needed, then multiple   macros should be utilized.
See section 2.3.1.1.
Having authenticated the request, the web site responds with an OFX download, just as if the customer had
manually entered the OFX request at the site.
<OFX>
... Open Financial Exchange response following the OFX specification...
</OFX>
1.3.1 User
User refers to the person or entity interfacing with the OFX client to cause it to generate OFX requests.
1.3.4 Client
An OFX client is the software that generates OFX requests, receives responses and processes them. This
may be a personal finance manager, a web browser running locally interactive code (such as with a Java
applet or ActiveX control), a Web server, a proxy, or one of many other possibilities.
1.3.5 Server
An OFX server is the software that receives OFX requests, processes them, and generates OFX responses.
1.3.6 Service
A service is a collection of related transactions. For example, the BANKSVC service encompasses
banking transactions such as requesting bank statements, initiating stop checks, initiating wire transfers,
etc.
In OFX 1.x and 2.x, services are used directly only when describing or changing the general options
available to a particular customer. Other collections of transactions instead use the concept of Message
Sets as described in section 1.3.15.
<FOO>
The end tag for the same aggregate looks like this:
</FOO>
1.3.8 Element
An OFX document contains one or more elements. An element is some data bounded by a leading start tag
and a trailing end tag. For example, an element named BAZ, containing data “bar,” looks like this:
An OFX element must contain data (not just white space) and may not contain other elements. This is a
refinement to the XML definition of an element which is more generic. An XML element containing other
elements is defined in OFX as an aggregate. OFX specifically disallows empty elements and elements
with mixed content.
1.3.9 Aggregate
An aggregate is a collection of elements and/or other aggregates. An aggregate may not contain any data
itself, but rather contains elements containing data, and/or recursively contains aggregates.
OFX includes very few empty aggregates and clients and servers should not send an aggregate without
content. In general, the entire aggregate should be left out of a request or response file when its (optional)
content is missing. The few exceptions to these rules (such as <SECLISTRS>, described in section
13.8.3.3) are called out in the relevant sections of this document.
26 1.3 Definitions
1.3.10 Request
A request is information sent by the client. An OFX request file is the entire XML file sent by the client,
including the OFX declaration. An individual request generally is an aggregate whose name ends in RQ.
1.3.11 Response
A response is information sent by the server. An OFX response file is the entire XML file sent by the
server, including the OFX declaration. An individual response generally is an aggregate whose name ends
in RS.
When elements and aggregates from the request also appear in the corresponding response they are
generally intended to echo the values from a request in the response (this enables client matching with the
request, for example). While the server should not modify data in individual elements when echoing,
elements not found in a particular request may be added in the response. These situations (such as adding a
<PAYEELSTID> when creating a <PMTRQ> response) are described as they arise. OFX also includes a
few specific situations requiring different information to be sent and returned in corresponding elements of
a request/response pair. Again, these exceptions (such as the <TOKEN> element in a sync request and
response) are described as they arise.
1.3.12 Message
A message is the unit of work in OFX. It refers to a request and response pair. For example, the message to
download a bank statement consists of the request <STMTRQ> and the response <STMTRS>.
1.3.13 Transaction
A transaction consists of a message and its associated transaction wrappers. The transaction request
wrapper contains a unique transaction identifier used to prevent ambiguity in matching a particular
response to its associated request, and the request aggregate. The transaction response wrapper contains a
status aggregate, the transaction identifier sent in the request, and (if the transaction was successful) the
response aggregate. For details on the use of transaction wrappers, see section 2.4.6.
1.3.14 Synchronization
For messages subject to synchronization (see Chapter 6, "Data Synchronization"), an added layer of
aggregates is also part of a message definition: a synchronization request and response. These add a token
and, in some cases, other information. Synchronization requests may encapsulate embedded transactions
that execute only when certain conditions are true at the server (either the containing synchronization
request completed without error or the request had no errors and the client was up to date).
Please refer to section 2.4.5 , "Message Sets and Version Control" for additional information about
message sets.
Version 1.0.2 supports any or all version 1 message sets except Bill Presentment. These message sets are
defined by the OFX 1.0.2 Document Type Definition (DTD), which is used for parsing. Applications that
conform to this version are referred to as 1.0.2 clients and 1.0.2 servers.
Version 1.5.1 supports all version 2 message sets, Bill Presentment, and all version 1 message sets.
Because it supports all message sets, the OFX 1.5.1 DTD can be used to create and support OFX 1.0.2 and/
or OFX 1.5.1 clients and servers.
Version 1.6 DTD supports all message sets available in the OFX 1.5.1 DTD. It adds specific enhancements
to some of the aggregates. All of those enhancements are optional and should not be used by a client unless
the server indicates support in its FI Profile. Applications that conform to this version are referred to as 1.6
clients and 1.6 servers. The OFX 1.6 DTD fully incorporates the OFX 1.0.2 and 1.5.1 message sets, so it
can be used to support both 1.0.2 and 1.5.1 applications.
Version 2.0 supports all V1 message sets available in the OFX 1.6 DTD. It adds support for 401(k)
investment statement download. The Tax OFX addendum to OFX 2.0 adds support for 1099 and W2
download. An important change for 2.0 is that it adds the requirement of XML compliance to OFX 2.0
clients and servers. See chapter 2 for more information.
Version 2.0.2 adds clarification to 2.0.1 as well as fixes some minor documentation bugs.
Version 2.0.3, an extension of 2.0.2, adds Multi-Factor Authentication (MFA) to the Signon Message Set
and changes to the Profile Message Set to support MFA.
Version 2.1 extends 2.0.2 by adding support for loans, as well as image download for banking, credit
cards, investments and loans. Automatic 1-Way OFX is also new; see in Chapter 16 for details. Appendix
C.4 contains a full description of changes made for OFX 2.1.
Version 2.1.1 adds Multi-Factor Authentication (MFA) to the Signon Message Set and changes to the
Profile Message Set to support MFA. These are virtually the same MFA changes that are added to versions
1.0.3 and 2.0.3.
Version 2.2.0 extends 2.1.1 by providing additional security options, multiple new data elements and
aggregates to make OFX more viable for aggregation, and multiple new implementation methods for
existing features to reduce complexity and coordination between providers and developers. Additionally
the main OFX Schema and the OFX Tax Schema, which have diverged since the 2.1.1 release, were
reconciled in the 2.2 release (up to the 2015 tax year). Appendix C.6 contains a full description of the
changes made for OFX 2.2.
In Version 2.3 Tax was removed so it is no longer necessary to update the main OFX spec with tax changes
every year. Appendix C.7 and C.8 contain a full description of changes made for OFX 2.2.1 and OFX 2.3.
Note: n refers to the number of characters in the resultant string. Each multi-byte or encoded
character counts as a single character. UTF-8 encodes “high” Latin-1 characters (decimal 128-
255) using two bytes, and double-byte characters using three bytes. In addition, XML encodes
ampersands, less-than symbols, greater-than symbols, and spaces (where required) using multi-
character escape strings (see section 2.3.1.1). Therefore, an element of type A-40 may require
more than 40 bytes in a UTF-8-encoded XML stream.
• N-n identifies an element of numeric type where n is the maximum number of characters in the value.
Values of this type are generally whole numbers, but the data type allows negative numbers. OFX
includes a few fixed-position numeric values (such as <APPVER>, see section 2.5.1.5) called out in the
text. In all cases, elements of this type may contain only the characters 0 through 9 and - (hyphen, the
negative sign indicator). So an element of type “N-6” may take values from -99999 to 999999. The
value “0000000” would be illegal for an N-6 element. White space is not allowed within the numeric
value. Leading zeros are allowed, but discouraged except where noted in the text. For example, a
<MIN> element containing zero might be sent as “<MIN>0”, “<MIN>00”, “<MIN> 0", but not
“<MIN>0 0".
• Common value types, such as a dollar amount, are referenced by name. Chapter 3, "Common
Aggregates, Elements, and Data Types" lists value types that are referenced by name.
• Explanatory information is in italics
Tag Description
30 1.5 Conventions
Tag Description
Open Financial Exchange data consists of a declaration plus one Open Financial Exchange data block.
This block consists of a signon message and zero or more additional messages. When sent over the Internet
using HTTP, standard HTTP and (optionally) multipart MIME headers and formats surround the Open
Financial Exchange data. A simple file that contained only Open Financial Exchange data would have the
following form:
HTTP headers
MIME type application/x-ofx
XML declaration
Open Financial Exchange declaration
Open Financial Exchange XML block
A more complex file that contained additional Open Financial Exchange data would have this form:
HTTP headers
MIME type multipart/x-mixed-replace; boundary =XYZZY24x7
--XYZZY24x7
MIME type application/x-ofx
XML declaration
Open Financial Exchange declaration
Open Financial Exchange XML block
--XYZZY24x7
MIME type image/jpeg
FI logo
--XYZZY24x7--
Version 1.0.2 of the Open Financial Exchange specification did not specify how to properly separate the
various components of an OFX request. In particular, separation of the HTTP headers, the MIME
attachments, the OFX declaration, the OFX header elements, and the OFX SGML block.
OFX 1.0.2 clients used a mix of LF and CRLF constructs and OFX 1.0.2 servers handled either linefeed
(LF) or carriage return/line feed (CRLF), but not often both. In the future, it is expected that 1.0.2 servers
will be upgraded to handle both CRLF and LF.
OFX 2.2 clients and servers are expected to follow standard XML 1.0 conventions regarding the use of CR
and LF. XML 1.0 is an accepted World Wide Web Consortium (W3C) recommendation.
200 OK The request was processed and a valid Open Financial Exchange result is
returned.
400s Bad request The request was invalid and was not processed. Clients will report an internal
error to the user. Invalid requests include: general HTTP transport errors, XML
formatting errors, invalid OFX syntax, and invalid data values. This error should
not appear for request files the server is able to parse.
500s Server error The server is unavailable. Clients should advise the user to retry shortly.
Note: The server must return a code in the 400s for any problem that prevents it from
processing the request file. Processing problems include failures relating to security,
communication, parsing, or the Open Financial Exchange declaration (for example, the client
requested an unsupported language). For content errors such as wrong USERPASS or invalid
account, the server must return a valid Open Financial Exchange response along with code 200.
If a communication time-out error occurs while an OFX server and a back-end server are
communicating to fill a request, then the server MUST return a code in the 500s.
When responding with multipart MIME (likely only if the request included a <GETMIMERQ> request),
the main type will be multipart/x-mixed-replace; one of the parts will use application/x-ofx.
Note: White space requirements are not imposed by this specification beyond the standard
XML 1.0 conventions; therefore, the white space formatting shown in these examples is not
required.
The encoding and standalone attributes are shown below for completeness and may be omitted.
See XML 1.0 for a description of the default handling for these attributes.
The OFX declaration must come next in the file. This PI identifies the contents as an Open Financial
Exchange file and provides the version number of the Open Financial Exchange declaration itself (not the
version number of the contents). The Open Financial Exchange PI contains the following attributes:
OFXHEADER
VERSION
SECURITY
OLDFILEUID
NEWFILEUID
All these attributes are required. "NONE" should be returned if client or server does not make use of an
individual attribute, e.g., OLDFILEUID="NONE".
2.2.1 OFXHEADER
OFXHEADER specifies the version number of the Open Financial Exchange declaration.
The OFXHEADER value changes its major number only if an existing client is unable to process the new
header. This can occur because of a complete syntax change in a header, or a significant change in the
semantics of an existing header element.
Because OFX 2.2 uses an XML compliant header which significantly differs from the 1.x header, the value
of OFXHEADER is now 2.0 (OFXHEADER="200").
2.2.2 VERSION
VERSION specifies the version number of the following OFX data block.
2.2.3 SECURITY
SECURITY defines the type of application-level security, if any, that is used for the <OFX> block. The
values for SECURITY can be NONE or TYPE1.
OLDFILEUID is used together with NEWFILEUID only when the client and server support file-based
error recovery. OLDFILEUID identifies the last request and response that was received and processed by
the client.
2.3.1 Compliance
XML is the basis for Open Financial Exchange 2.0 and later. To enable OFX clients and servers to use off-
the-shelf XML parsers, OFX 2.2 is fully XML compliant. Therefore, in contrast to the guidelines for OFX
1.6 and below, unrecognized tags may not be present. If clients and servers wish to extend OFX with
private tags and true DTD validation is necessary, a modified OFX DTD which contains those new tags
must be passed along with the OFX document.
Special characters in OFX 2.2 are handled according to the XML standard. Characters such as ’<’, ’>’,
’&’, ’’’, and ’"’ are predefined in XML. Other character strings with many special characters should be
enclosed in a CDATA section.
Note: The space macro ( ) should be used if leading or trailing blanks are meant to be
preserved as part of a data element’s value. Alternatively, a CDATA block may be used to force
the handling of leading or trailing spaces. No special formatting of space characters in the
middle of an element’s text value is needed.
2.4.1 Overview
Open Financial Exchange hierarchically organizes request and response blocks:
<STATUS>
<CODE>2000</CODE>
Tag Description
<OFX> Opening tag
<SONRQ> or Required signon request or response. See section 2.5.1.
<SONRS>
... Open Financial 0 or more transaction requests and responses inside appropriate message set
Exchange requests or aggregates
responses ...
2.4.4 Messages
A message is the unit of work in Open Financial Exchange. It refers to a request and response pair, and the
status codes associated with that response. For example, the message to download a bank statement
consists of the request <STMTRQ> and the response <STMTRS>.
OFX uses several common message types to perform specific functions. Within OFX, the following
naming conventions are used, where the general xxx messages may be:
• Basic (or Add) request <xxxRQ> and response <xxxRS>
• Modify request <xxxMODRQ> and response <xxxMODRS>
• Delete request <xxxDELRQ> and response <xxxDELRS>
• Cancel request <xxxCANRQ> and response <xxxCANRS> (these pairs may also be named
<xxxCANCRQ> and <xxxCANCRS)
The basic OFX message has a name structure of <xxxRQ>/<xxxRS>. It is used for read actions of a
specific object (such as a bank statement using <STMTENDRQ>). It is encapsulated in a transaction
wrapper <xxxTRNRQ> or <xxxTRNRS> (therefore, <STMTENDTRNRQ> and <STMTENDTRNRS> in
the example above).
The add OFX message, like the Basic message, has a name structure of <xxxRQ>/<xxxRS>. It is used to
create a new instance of object xxx (such as creating a new payment using <PMTRQ>). It is encapsulated
in a transaction wrapper <xxxTRNRQ> or <xxxTRNRS> (therefore, <PMTTRNRQ> and <PMTTRNRS>
in the example above).
The modify OFX message has a name structure of <xxxMODRQ>/<xxxMODRS>. It is used to modify an
existing instance of object xxx (such as modifying an existing payment using <PMTMODRQ>). It is
encapsulated in a transaction wrapper <xxxTRNRQ> or <xxxTRNRS> (therefore, <PMTTRNRQ> and
<PMTTRNRS> in the example above).
The <xxxMODRQ> request contains the complete replacement data for an existing object xxx. Therefore,
both changed and unchanged elements must be included in the request.
The delete and cancel OFX messages have a name structure of <xxxDELRQ>/<xxxDELRS> and
<xxxCANRQ>/<xxxCANRS> or <xxxCANCRQ>/<xxxCANCRS>, respectively. They are used to delete
an existing instance of object xxx (such as deleting a payee from a payee list using <PAYEEDELRQ>), or
to cancel an existing scheduled object (such as canceling a pending payment using <PMTCANCRQ>).
They are encapsulated in a transaction wrapper <xxxTRNRQ> or <xxxTRNRS> (therefore,
<PAYEETRNRQ> and <PMTTRNRQ> in the examples above).
The inquiry OFX message sometimes has a name structure of <xxxINQRQ>/<xxxINQRS>. It is used to
search for and/or gain information about (an) existing object(s) xxx (such as finding one or more existing
payments using <PMTINQRQ>). It is encapsulated in a transaction wrapper <xxxINQTRNRQ> or
<xxxINQTRNRS> (therefore, <PMTINQTRNRQ>and <PMTINQTRNRS> in the example above).
Inquiry messages limit the response set to records matching the selection criteria used in the request.
Selection criterion elements in the request are generally repeating elements. Where more than one value is
given for a particular element, the query ORs those values. Where multiple different elements (matches for
different fields of the objects) are provided, the query ANDs those values. Where an element is absent
from the request, the query is not filtering on that element. If an element has a history associated with it,
only the most recent value is intended by the inquiry.
Note: Many inquiry messages do not presently follow the naming conventions detailed above.
They may be named <xxxINFORQ>/<xxxINFORS> (<ACCTINFORQ> and
<ACCTINFORS> for example) or without reference to an obvious convention
(<PRESLISTRQ> and <PRESLISTRS> for example).
Within the OFX block, OFX organizes messages by message set. Message sets follow these rules:
• A request file may include at most one message set wrapper of each type.
• All messages within any message set must be from the same version of that message set.
• Servers must respond using the same message sets and versions as sent in the request file. For example,
if <SIGNUPMSGSRQV1> appears in the request file, <SIGNUPMSGSRSV1> must appear in the
response file. There is one exception to this rule: servers may return the <SECLISTMSGSRSV1>
wrapper (see 13.7.2 and 13.8.4) in response to an investment statement download request that may or
may not include <SECLISTMSGSRQV1>.
For each message set of xxx and version n, there are two aggregates, one for requests <xxxMSGSRQVn>)
and one for responses <xxxMSGSRSVn>. All of the messages from that message set must be enclosed in
the appropriate message set aggregate. In the following example, the Open Financial Exchange block
contains a signon request inside the signon message set, and two statement requests and a transfer request
inside the bank message set.
<OFX>
<SIGNONMSGSRQV1> <!-- Signon message set -->
<SONRQ> <!-- Signon message -->
...
</SONRQ>
</SIGNONMSGSRQV1>
Note: Image download is an exception to the above. An OFX file containing the Image
message set includes only the Signon message set. No other message sets may be present in the
file. See Chapter 15, "Image Download", for details.
The definition of each message set can further prescribe an order of its messages within that message set.
The following table lists each message set, along with its aggregate name and the DTD/XML Schema
versions that support it.
Note: Starting with OFX 2.0, a DTD is no longer maintained. Instead, an XML Schema is
maintained.
Credit Card Statements <CREDITCARDMSGSETV1 1.0.2, 1.0.3, 1.5.1, 1.6, 2.0, 2.0.1,
> 2.0.2, 2.0.3, 2.1, 2.1.1, 2.2
Interbank Funds Transfers <INTERXFERMSGSETV1> 1.0.2, 1.0.3, 1.5.1, 1.6, 2.0, 2.0.1,
2.0.2, 2.0.3, 2.1, 2.1.1, 2.2
Wire Funds Transfers <WIREXFERMSGSETV1> 1.0.2, 1.0.3, 1.5.1, 1.6, 2.0, 2.0.1,
2.0.2, 2.0.3, 2.1, 2.1.1, 2.2
Investment security list <SECLISTMSGSETV1> 1.0.2, 1.0.3, 1.5.1, 1.6, 2.0, 2.0.1,
2.0.2, 2.0.3, 2.1, 2.1.1, 2.2
Note: For each message set that it is supporting, a financial institution must indicate which
version numbers of that message set it supports. The financial institution includes the message
2.4.6 Transactions
Other than the signon message, each request is made as a transaction. Transactions contain a client-
assigned globally-unique ID, optional client-supplied pass-back data, and the request aggregate. A
transaction similarly wraps each response. The response transaction returns the client ID sent in the
request, along with a status message, the pass-back data if present, and the response aggregate. This
technique allows a client to track responses against requests. Section 3.1.2 provides more information
about the format of information exchanged by the client and server.
The <STATUS> aggregate, defined in Chapter 3, "Common Aggregates, Elements, and Data Types,"
provides feedback on the processing of the request. If the <SEVERITY> of the status is ERROR, the
server provides the transaction response without the nested response aggregate. Otherwise, the response
must be complete even though a warning might have occurred.
Clients can send additional information in <CLTCOOKIE> that servers will return in the response. This
allows clients that do not maintain state, and thus do not save <TRNUID>s, to cause some additional
descriptive information to be present in the response. For example, a client might identify a request as
relating to a user or a spouse.
<CLTCOOKIE> must only be returned by the server in the initial response to the client (and any crash
recovery from that response). The <CLTCOOKIE> should not be present in a sync response, except for
those transactions whose requests were wrapped in the sync request.
In some countries, some banks may require that a customer-supplied authorization number be included to
authenticate certain kinds of individual transactions such as payment requests. For those banks, the
<TAN> element passes this information to servers.
Note that if a <CLTCOOKIE> is given to an OFX server in a request, the OFX server is required to return
it. This return of the <CLTCOOKIE> will necessitate server-side storage of <CLTCOOKIE> data. In the
case of an OFX client getting a <CLTCOOKIE> that it didn’t send in a request, the default behavior is to
ignore it.
With the exception of the <SONRQ>/<SONRS> message, each message has a corresponding transaction
wrapper. For requests, the transaction wrapper adds a transaction unique ID <TRNUID>. For responses,
the transaction wrapper adds the same transaction unique ID <TRNUID> (an echo of that found in the
request), plus a <STATUS> aggregate.
The transaction wrapper has a name structure of <xxxTRNRQ>/<xxxTRNRS>. A transaction wrapper pair
encapsulates a single message (<xxxRQ>/<xxxRS>, <xxxMODRQ>/<xxxMODRS>, etc.).
Note: Some requests and responses (generally, Add, Modify, and Delete/Cancel types) share a
transaction wrapper and synchronization wrapper. In these cases, the names of the transaction
and synchronization wrappers reflect the Add message.
Tag Description
<xxxTRNRQ> Transaction-request aggregate
<TRNUID> Client-assigned globally-unique ID for this transaction, trnuid
<CLTCOOKIE> Data to be echoed in the transaction response, A-32
<TAN> Transaction authorization number; used in some countries with some types of
transactions. The FI Profile defines messages that require a <TAN>, A-80
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
Tag Description
<xxxTRNRS> Transaction-response aggregate
<TRNUID> Client-assigned globally-unique ID for this transaction, trnuid
<STATUS> Status aggregate
</STATUS>
Value Meaning
0 Success (INFO)
When embedded transactions are not present, the synchronization request contains no transaction
wrappers. If the client is up to date when the server processes such a request, the synchronization response
also contains no transaction wrappers.
Note: The OFX Extension aggregate, see Section 2.7.2 for more information, has been added
to all synchronization messages prior to any embedded transactions in both request and
response synchronization wrappers.
The request and response message set wrappers have a name structure of <xxxMSGSRQVn> and
<xxxMSGSRSVn> respectively. For OFX 2.2, “n” must be “1”. This number indicates the version of the
message set used by the contained messages.
If the server returns any signon error, it must respond to all other requests in the same <OFX> block with
status code 15500. For example, if the server returns status code 15502 to the <SONRQ> request, it must
return status code 15500 to all other requests in the same <OFX> block. The server must return status code
15500 for all requests; it cannot simply ignore the requests. In addition, any sync responses must indicate
an error with <TOKEN>-1</TOKEN>, <LOSTSYNC>N </LOSTSYNC>(<LOSTSYNC> is an optional
element). Responses for any transactions embedded in the sync request should contain the same
<STATUS><CODE>15500</CODE></STATUS>. Otherwise, they must be omitted from the sync
response wrapper. (See section 6.2 for data synchronization specifics.)
The client returns <SESSCOOKIE> if the server sent one in a previous <SONRS>. Servers can use the
value of <SESSCOOKIE> to track client usage but cannot assume that all requests come from a single
client, nor can they deny service if they did not expect the returned cookie. Use of a backup file, for
example, could lead to an unexpected <SESSCOOKIE> value that nevertheless should not stop a user
from connecting.
OFX 2.2 contains 3 distinct methods in the <SONRQ> for "user credentials" or "user identification" to be
provided to the server for authentication. These methods are mutually exclusive within the schema via an
XOR relationship - only one method may be used within any individual <SONRQ>.
Since FIs assign user IDs for the customer, any OFX client must not make any assumptions about the
syntax of the ID, add check-digits, or do similar processing. To ensure security and help prevent identity fraud,
Financial Institutions are discouraged from using Social Security Number for Customer ID or PIN/Password.
If passwords are specific to individual services or accounts, a separate Open Financial Exchange request
must be made for each user ID or password required. This will not necessarily be in a manner visible to the
user. Note that some situations, such as joint accounts or business accounts, will have multiple user IDs
and multiple passwords that can access the same account.
2.5.1.2.2 <USERKEY>
To improve server efficiency in handling a series of Open Financial Exchange request files sent over a
short period of time, clients can request that a server return a <USERKEY> in the signon response. If the
server provides a user key, clients will send the <USERKEY> instead of the user ID and password in
subsequent sessions, until the <USERKEY> expires. This allows servers to authenticate subsequent
requests more quickly. Servers must accept a <GENUSERKEY> element in a <SONRQ>. However, a
2.5.1.2.3 <ACCESSTOKEN>
Servers may require the use of an <ACCESSTOKEN> in place of <USERID> and <USERPASS> for
authentication. The server can specify this requirement using the <ACCESSTOKENREQ> tag in the
applicable <SIGNONINFO> section of the profile response. The use and format of <ACCESSTOKEN>
must be arranged out-of-band between the client and the OFX Server provider.
Keeping the specific use and format of <ACCESSTOKEN> out of band allows OFX to support numerous
methods of token generation such as OAUTH 1.0, OAUTH 2.0, JSON Tokens, and so on. Essentially any
agreed upon token format and methodology may be used between the client and server.
The intent of <ACCESSTOKEN> is to leverage an out of band mechanism which will fully replace all
other types of authentication within OFX for all types of accounts and requests. As such,
<ACCESSTOKEN> interaction with other <SONRQ> mechanisms and features should be avoided. Of
particular note:
• While it would be permissible under the specification to have multiple signon realms with a mixture of
<ACCESSTOKEN> and <USERID>/<USERPASS> used between those realms this is STRONGLY
DISCOURAGED due to the client side complexity which would be created.
• While it would be permissible under the specification to use other OFX MFA mechanisms or requests
(such as <CHALLENGERQ>) this is STRONGLY DISCOURAGED due to the client side complexity
which would be created.
• When <ACCESSTOKEN> is required by a server and indicated within the signon realm, servers
should set <PINCH> and <CHGPINFIRST> to N to indicate that OFX pin change functionality is not
supported. All other pin characteristics should be set to some default value as they are not used with this
authentication method. Additionally servers should NEVER use <CODE>15000 to request a client side
pin change. Lastly, clients should NEVER, even if a server indicates that pin change is supported, send
a <PINCHRQ> message to a signon realm on a server whose profile indicates that <ACCESSTOKEN>
is required.
2.5.1.2.4 <APPKEY>
Servers may require, or clients may choose to provide, an <APPKEY> in addition to <APPVER> and
<APPID> in order to further confirm the identity of the sending client software or host system.
<APPKEY> may be used with any of the three "user identification" methods described above.
In the OFX ecosystem "ghosting", where a client or host system impersonates another client or host system
by using their <APPID> and <APPVER> values, is not uncommon. While a server may inspect and
restrict the <APPID> and <APPVER> values which are allowed to connect, the generally public nature of
<APPID> and <APPVER> values effectively negates this capability.
Usage of <APPKEY> needs to be coordinated out of band between client/host system and OFX server.
Some possible implementation methods include:
Note: While static values may be used if the value is compromised it eliminates the benefits of
the <APPKEY> implementation. If they are used both sides of the connection should use
appropriate information handling protocols. A defined process and update interval for regular
updates to the static value would also be recommended.
<APPKEY> is one of multiple techniques that may be used to confirm the identity of the client/host
system which originated the request. Client/server developers should determine the appropriate techniques
to use on their specific implementations. Additional techniques could include approaches such as:
• IP White-listing
• Client-side certificates
• Private VPN connections
A client may use an anonymous form of <USERID> and <USERPASS> on those rare occasions when a
server need not authenticate the <SONRQ>. The only present situations in this class are first-time
<PROFRQ>, <FINDBILLERRQ>, and all <ENROLLRQ> transactions. Any request sent by the client
after a successful <ENROLLRQ> response (or out of band enrollment) for the service must provide the
user’s <USERID> and <USERPASS>. The anonymous <USERID> or <USERPASS> value is left aligned
and padded with 0 to a length of 32 characters: anonymous00000000000000000000000
Note: This anonymous password length may exceed the <MAX> value for the profile server
(in the corresponding <SIGNONINFO> aggregate). Nonetheless, servers supporting
anonymous signon must not reject this password due to its length.
An OFX 2.2 server has the option of allowing or disallowing “empty” signon transactions. In the context
of signon, “empty” means a simple signon without any other transaction (a sync, statement download,
etc.). If the OFX 2.2 server does not support empty signon, it should return error 15506. If the OFX 2.2
server does support empty signon, it should process the signon and return the appropriate error or success
code.
Servers can request that a consumer change his or her password by returning status code 15000. Servers
should keep in mind that only one status code can be returned. If the current signon response status should
be 15500 (invalid ID or password), the request to change the password must wait until an otherwise
successful signon is achieved.
OFX 2.2 supports all previous specification version methods for multi-factor authentication.
OFX servers can require OFX clients to include a client ID in each signon request. This client ID should be
unique to the installation of the client software, but the method that the ID is generated is left up to the
client. The server can specify that this field is required using the <CLIENTUIDREQ> tag in the applicable
<SIGNONINFO> section of the profile. Servers should expect that users may connect via OFX from
multiple locations and may need to associate more than one <CLIENTUID> value with their <USERID>.
The client may make this value user discoverable, so that the user can register the client ID with financial
institutions.
The signon request contains two new user credential ID fields, <USERCRED1> and <USERCRED2>.
Servers use the applicable <SIGNONINFO> aggregate in the profile to specify if one or both of these
fields are required. The presence of <USERCRED1LABEL> and <USERCRED2LABEL> in
<SIGNONINFO> specifies that these tags are required and also gives labels for these fields. OFX clients
should use these labels to prompt the user for necessary signon information. For instance, a server may
require <USERCRED1> and would specify its label as “Mother’s maiden name.”
Servers should assume that profile requests are made very infrequently. If the user credential ID or label is
expected to change frequently, the MFACHALLENGE message is the most appropriate method to use.
Use of <USERCRED1> and <USERCRED2> should be reserved for questions/prompts that will change
rarely, if at all.
This authentication token is intended to be used in conjunction with the client ID functionality described in
Section 2.5.1.4.1 although this is not required. By providing the user with this one-time value out of band
and then requiring (and validating) it on either the initial (for first time setup) or next session (for existing
users) an institution may establish the client ID received in the session as a “known” client ID value that is
directly associated with the user.
The signon request contains an additional field, <AUTHTOKEN>. Servers use the Signon Realm’s
<AUTHTOKENFIRST> tag to specify that the client is required to send this credential during the initial
signon session. A server may also indicate that this credential is required on the next session by returning a
15512 error code in a signon response. If this credential is required by the OFX server under either of the
above conditions then the server must also use the Signon Realm’s profile tags to specify a label for this
value (<AUTHTOKENLABEL>) as well as a standard URL (<AUTHTOKENINFOURL>) where the one
time authentication token is either directly provided to the user (e.g. they login to the institution’s standard
web banking system and request a credential) or information on how to acquire the credential is given (e.g.
they are instructed to contact customer support).
This authentication token mechanism is intended for use on an infrequent basis and in conjunction with
client ID functionality. If additional authentication would be required on a regular basis then the
MFACHALLENGE messages would be a more appropriate implementation.
If the client and server support the MFACHALLENGE request/response and/or the authentication token
functionality, the signon request may include the <ACCESSKEY> tag. When provided by the server, the
client will send the last value of the <ACCESSKEY> it has received.
Unlike other requests, the signon request <SONRQ> does not appear within a transaction wrapper.
Tag Description
<SONRQ> Signon-request aggregate
<DTCLIENT> Date and time of the request from the client computer, datetime
This value should reflect the time (according to the client machine) when the request
file is sent to the server, not the (original) creation time of the request file. While not
required for existing software, OFX 2.2 clients must comply with this rule. This
clarification is particularly important in error recovery situations in which the request
file may be sent to the server after its initial creation.
Note: The maximum clear text length of USERPASS is 32 characters: a client must
not send a longer password. However, when using Type 1 security, the encrypted value
may extend to 171 characters.
Note: The client will determine out-of-band whether a FI aggregate should be used
and if so, the appropriate values for it. If the FI aggregate is to be used, then the client
should send it in every request, and the server should return it in every response.
</FI>
<SESSCOOKIE> Session cookie value received in previous <SONRS>, not sent if first login or if none
sent by FI, A-1000
<APPID> ID of client application, A-5
<APPVER> Version of client application, (6.00 encoded as 0600), N-4
<APPKEY> Application key/identifier; arranged out of band between server and client. See section
2.5.1.2.4, A-10000
<CLIENTUID> Unique ID identifying OFX user, A-36
<USERCRED1> Additional user credential required by server, A-171
Note: the effective size of USERCRED1 is A-32. However, if Type 1 security is used,
then the actual field length is A-171.
<USERCRED2> Additional user credential required by server, A-171
Note: the effective size of USERCRED2 is A-32. However, if Type 1 security is used,
then the actual field length is A-171.
<AUTHTOKEN> Authentication token required for this signon session only. Credential is provided to the
user out of band, A-171
Note: the effective size of AUTHTOKEN is A-32. However, if Type 1 security is used,
then the actual field length is A-171.
<ACCESSKEY> Access key value received in prevous <SONRS>, not sent if first login or none sent by
FI, A-1000
<MFACHALLENGEANS MFA challenge question/answer aggregates (0 or more). See section 2.5.4.5
WER>
</MFACHALLENGEAN
SWER>
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</SONRQ>
Unlike other responses, the signon response <SONRS> does not appear within a transaction wrapper.
Note: A client should use <DTPROFUP> and <DTACCTUP> only when the service provider
that originated <SONRS> is the same provider that is specified by <SPNAME> in the profile
message set. A client can determine if the service provider is the same by comparing the value
of <SPNAME> in the appropriate message set with the value for <SPNAME> in the profile
message set.
Tag Description
<SONRS> Record-response aggregate
<STATUS> Status aggregate, see section 3.1.5. See list of possible code values in section 2.5.1.7
</STATUS>
Note: The client will determine out-of-band whether an FI aggregate should be used
and, if so, the appropriate values for it. If the FI aggregate is to be used, then the client
should send it in every request, and the server should return it in every response.
</FI>
<SESSCOOKIE> Session cookie that the client should return on the next <SONRQ>,A-1000
<ACCESSKEY> Access key that the client should send in the next <SONRQ>, A-1000
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
Value Meaning
0 Success (INFO)
3000 User credentials are correct, but further authentication required (ERROR)
This notifies client to send <MFACHALLENGERQ>.
15512 OFX server requires AUTHTOKEN in signon during the next session
(ERROR)
Some service providers support multiple FIs, and assign each FI an ID. The signon allows clients to pass
this information along, so that providers know to which FI the user is signing on.
If a server does not require an FI aggregate in a request but receives one anyway, it should echo the FI
aggregate back. This is compliant with the general rule that the server should echo elements and aggregates
in the response if they are received and understood in the request.
If a server requires the <FI> aggregate in <SONRQ> requests and it contains incorrect information there
are several different specification compliant ways to respond. These are given in the order of preference:
• Return a 2000 error with appropriate text message – since the FI aggregate information is incorrect the
user’s information (<USERID> and <USERPASS>) cannot be verified. Returning a 15500 might cause
clients to display messages to the user that the attempt to communicate with the server failed. A client
would probably suggest that the user verify their <USERID> and <USERPASS> values.
• Return a 15500 error – since the FI aggregate information is incorrect or unknown the server cannot
verify the <USERID>, <USERPASS>, etc.
• Return an http 400 error – this is the least desirable option since it will provide no useful feedback to
the client communicating with the server, however it is legal.
Tag Description
<FI> FI-record aggregate
<ORG> Organization defining this FI name space, A-32
<FID> Financial Institution ID (unique within <ORG>), A-32
</FI>
Password changes pose a special problem for error recovery. If the client does not receive a response, it
cannot know whether or not the password change was successful. OFX recommends that servers accept
either the old password or the new password on the connection following the one containing a password
change. When file-based error recovery is in use, the server must reject the old password except when
received with NEWFILEUID/OLDFILEUID headers indicating an error recovery attempt.
Also, if the client does not receive a response that has a status code of 15000 from a server, it cannot know
that a password change is required. In this case, the server should not expect a pin change request in the
signon when the NEWFILEUID/OLDFILEUID headers indicate an error recovery attempt.
Servers that do not support file-based error recovery (or, when interacting with a client that does not utilize
file-based error recovery) must not complete a <PINCHRQ> until after the next request file arrives. If that
request file uses the new password, the new password must be permanently associated with the
<USERID>. Otherwise, the old password may authenticate the user. (For security, servers may return a
signon error if the next request file uses the old password but does not include a <PINCHRQ>.)
Conforming clients should re-send request files (unchanged beyond the <SONRQ>) after a failure whether
or not file-based error recovery is in use.
2.5.2.1 <PINCHRQ>
A USERPASS change request changes the customer’s password for the specific realm associated with the
messages contained in the OFX block. Based on the properties of an OFX profile, defined in Chapter 7,
"FI Profile," a single OFX block contains instructions related to a single realm. The USERPASS change
request thus changes the USERPASS for all message sets associated with one realm. For more information
about signon realms, see section 7.2.2.
Tag Description
<PINCHRQ> USERPASS-change-request aggregate
<USERID> User identification string, A-32
Tag Description
<PINCHRS> USERPASS-change-response aggregate
<USERID> User identification string, A-32
<DTCHANGED> Date and time the password was changed, datetime
</PINCHRS>
Value Meaning
0 Success (INFO)
The challenge message is part of the signon message set and is not subject to data synchronization.
2.5.3.1 <CHALLENGERQ>
The client includes <FICERTID> in the request if it already has the server’s certificate. If that is included
and matches the server’s current certificate, the server may omit the actual certificate from the response.
Tag Description
<CHALLENGERQ> Opening tag for the challenge request.
<USERID> User identification string, A-32
<FICERTID> Optional server certificate ID. A-64
</CHALLENGERQ> Closing tag for challenge request.
2.5.3.2 <CHALLENGERS>
Tag Description
<CHALLENGERS> Opening tag for the challenge response.
<USERID> User identification string, A-32
<NONCE> Server-generated random data. A-16
<FICERTID> ID of server certificate used to encrypt. A-64
</CHALLENGERS> Closing tag for challenge response.
When generating the <NONCE>, make sure the data is as unpredictable as possible. See RFC 1750 for
recommendations.
The server includes <FICERTID> in the response to identify the certificate in a separate MIME part. Even
if the certificate itself is not attached, <FICERTID> is still included in the response.
Status code values for the <CODE> element (contained within the <STATUS> aggregate):
Value Meaning
0 Success (INFO)
Following receipt of the 3000 error code, the client should request a list of challenge questions with an
<MFACHALLEGERQ>. The server will then respond to this request with a <MFACHALLENGERS>,
which includes the list of authentication questions, specified by ID and label. If for some reason the server
cannot respond with a <MFACHALLENGERS> response, it should respond with an HTTP 400 error.
Note that some of these challenge questions may require user interaction and some may not (if the client
already has access to the necessary information). It is up to the client to determine which questions require
user interaction.
Note: If the profile response contains <MFACHALLENGEFIRST>Y, the client must send an
<MFACHALLENGERQ> request in the first connection with the server, before sending any
other requests.
Once the client has retrieved the answers to the challenge questions (either from the user or another
location), it will then include them within the signon request included as part of the next request message.
If these answers are correct, the server will process the request file. If they are incorrect, the server will
return an error code of 3001.
The client should not need to store the answers to the challenge questions. To prevent servers from needing
to verify the user with each OFX request, the server may respond to a correct set of challenge answers with
the <ACCESSKEY> element on the signon response. The server determines the contents of this optional
element. On each subsequent signon request, the client will send the last value of the <ACCESSKEY> it
has received, even after the end of the current session. The server has the option to respond to any
The challenge message is part of the signon message set and is not subject to data synchronization.
2.5.4.1 <MFACHALLENGERQ>
<MFACHALLENGERQ> is a request for the server to send a list of challenge questions that must be
correctly answered before the OFX client may proceed with further OFX requests. The
<MFACHALLENGERQ> request should be sent in response to an error code of 3000 or on a first request
to the server if the profile contains <MFACHALLENGEFIRST>Y.
Tag Description
<MFACHALLENGERQ> MFA challenge request aggregate
<DTCLIENT> Date and time of the request from the client computer, datetime
</MFACHALLENGERS>
2.5.4.2 <MFACHALLENGERS>
The <MFACHALLENGERS> response contains the list of questions that must be correctly answered in
the next OFX request. These questions may or may not require user interaction. See the table in Section
2.5.4.4 for more details.
While this specification imposes no upper limit on the number of challenge questions a server sends,
financial institutions and servers should be aware that there may be a limit to the number of questions a
client is able to collect.
Tag Description
<MFACHALLENGERS> MFA challenge response aggregate
<MFACHALLENGE> Challenge question aggregate (1 or more)
<MFAPHRASEID> Identifier for the challenge question. It should be unique for this challenge question
but not unique for the user, session, etc. A-32. See section 2.5.4.4
<MFAPHRASELABEL> The textual challenge question. This should be as appropriate as possible for
display to the user. A-64
</MFACHALLENGERS>
Value Meaning
0 Success (INFO)
2.5.4.4 <MFAPHRASEID>
The <MFAPHRASEID> tag uniquely identifies a challenge question. In addition to providing a way to
correlate the answers to challenge questions with the questions themselves, it also provides the OFX client
additional options for collecting the answer from the user.
The following table details the list of reserved values for <MFAPHRASEID>s. Servers should use these
values only when the question they are asking matches the associated question in the table below. Note that
servers are never required to use the reserved values for the phrase ID, even when the challenge question
the servers require does match the question in the table below, but they should be aware that using the
reserved IDs when appropriate may result in a better customer experience.
MFAPHRASEID values above MFA100 are reserved for questions that the server expects the client to
answer. These do not require customer responses. All other enumerated IDs as well as server specific IDs
expect customer responses.
Clients may need to identify out of band which of the IDs above MFA100 they support.
Value Meaning
MFA1 City of birth
MFA2 Date of birth, formatted MM/DD/YYYY
MFA3 Debit card number
MFA4 Father’s middle name
MFA5 Favorite color
MFA6 First pet’s name
MFA7 Five digit ZIP code
MFA25
MFA26
MFA27
MFA28
MFA29
MFA30
MFA109
MFA110
Tag Description
<MFACHALLENGEANSWER> MFA challenge question/answer aggregate
<MFAPHRASEID> Identifier for the challenge question. If should be unique for this challenge question,
but not unique for the user, session, etc. A-32. See section 2.5.4.4
<MFAPHRASEA> User’s answer to the challenge question, A-64
</MFACHALLENGEANSWER>
The information that is part of the <MSGSETCORE> aggregate (for example, the URL and security level)
is used only when no other message sets are used. Otherwise, the other message sets override the signon
message set for the purposes of batching and routing. For example, if bill payments are sent to a URL that
is different from the one used for signon, the client uses the URL specified in the bill payment message set
<BILLPAYMSGSET>. For more information about how clients batch and route messages, refer to section
7.1.3.
Tag Description
<SIGNONMSGSET> Signon-message-set-profile-information aggregate
<SIGNONMSGSETV1> Opening tag for V1 of the message set profile information
<MSGSETCORE> Common message set information, defined in Chapter 7, "FI Profile"
</MSGSETCORE>
</SIGNONMSGSETV1>
</SIGNONMSGSET>
<PINCHTRNRQ>
<TRNUID>888</TRNUID>
<PINCHRQ>
<USERID>12345</USERID>
<NEWUSERPASS>5321</NEWUSERPASS>
</PINCHRQ>
</PINCHTRNRQ>
<PINCHTRNRS>
<TRNUID>888</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<PINCHRS>
<USERID>12345</USERID>
</PINCHRS>
</PINCHTRNRS>
-----------------------------------------------------------------
Signon in OFX 2.2 which includes CLIENTUID and both additional credential tags:
<OFX>
<SIGNONMSGSRQV1>
<SONRQ>
<DTCLIENT>20060321083010</DTCLIENT>
<USERID>12345</USERID>
<USERPASS>MyPassword</USERPASS>
<LANGUAGE>ENG</LANGUAGE>
<FI>
<ORG>ABC</ORG>
<FID>000111222</FID>
</FI>
<APPID>MyApp</APPID>
<APPVER>1600</APPVER>
<CLIENTUID>22576921-8E39-4A82-9E3E-EDDB121ADDEE</CLIENTUID>
-----------------------------------------------------------------
The following series shows the OFX 2.2 exchanges that occur when a server requires the client to
collect a one time authentication token.
Note: This could also be requested in profile, but this example is a case where user is an existing
OFX consumer.
<OFX>
<SIGNONMSGSRQV1>
<SONRQ>
<DTCLIENT>20060321083010</DTCLIENT>
<USERID>12345</USERID>
<USERPASS>MyPassword</USERPASS>
<LANGUAGE>ENG</LANGUAGE>
<FI>
<ORG>ABC</ORG>
<FID>000111222</FID>
</FI>
<APPID>MyApp</APPID>
<APPVER>1600</APPVER>
<CLIENTUID>22576921-8E39-4A82-9E3E-EDDB121ADDEE</CLIENTUID>
</SONRQ>
</SIGNONMSGSRQV1>
…. <!--Other message sets-->
</OFX>
<OFX>
<SIGNONMSGSRSV1>
<SONRS>
<STATUS>
Client collects the answers and returns them to server along with the original request.
<OFX>
<SIGNONMSGSRQV1>
<SONRQ>
<DTCLIENT>20060321083415</DTCLIENT>
<USERID>12345</USERID>
<USERPASS>MyPassword</USERPASS>
<LANGUAGE>ENG</LANGUAGE>
<FI>
<ORG>ABC</ORG>
<FID>000111222</FID>
</FI>
<APPID>MyApp</APPID>
<APPVER>1600</APPVER>
<CLIENTUID>22576921-8E39-4A82-9E3E-EDDB121ADDEE</CLIENTUID>
<AUTHTOKEN>1234567890</AUTHTOKEN><!—Authentication token
provided to user out of band-->
</SONRQ>
</SIGNONMSGSRQV1>
…. <!--Other message sets-->
</OFX>
<OFX>
<SIGNONMSGSRSV1>
<SONRS>
-----------------------------------------------------------------
The following series shows the OFX 2.2 exchanges that occur when a server requires the client to
collect answers to MFA Challenge questions.
<OFX>
<SIGNONMSGSRQV1>
<SONRQ>
<DTCLIENT>20060321083010</DTCLIENT>
<USERID>12345</USERID>
<USERPASS>MyPassword</USERPASS>
<LANGUAGE>ENG</LANGUAGE>
<FI>
<ORG>ABC</ORG>
<FID>000111222</FID>
</FI>
<APPID>MyApp</APPID>
<APPVER>1600</APPVER>
<CLIENTUID>22576921-8E39-4A82-9E3E-EDDB121ADDEE</CLIENTUID>
</SONRQ>
</SIGNONMSGSRQV1>
<OFX>
<SIGNONMSGSRSV1>
<SONRS>
<STATUS>
<CODE>3000</CODE>
<SEVERITY>ERROR</SEVERITY>
<MESSAGE>Further information required</MESSAGE>
</STATUS>
<DTSERVER>20060321083015</DTSERVER>
<LANGUAGE>ENG</LANGUAGE>
<FI>
<ORG>ABC</ORG>
<FID>000111222</FID>
</FI>
</SONRS>
</SIGNONMSGSRSV1>
--- <!--All other transaction responses return <CODE>15500</CODE>-->
</OFX>
<OFX>
<SIGNONMSGSRQV1>
<SONRQ>
<DTCLIENT>20060321083020</DTCLIENT>
<USERID>12345</USERID>
<USERPASS>MyPassword</USERPASS>
<LANGUAGE>ENG</LANGUAGE>
<FI>
<ORG>ABC</ORG>
<FID>000111222</FID>
</FI>
<APPID>MyApp</APPID>
<APPVER>1600</APPVER>
<CLIENTUID>22576921-8E39-4A82-9E3E-EDDB121ADDEE</CLIENTUID>
</SONRQ>
-----------------------------------------------------------------
• Custom question.
<OFX>
<SIGNONMSGSRSV1>
<SONRS>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<DTSERVER>20060321083025</DTSERVER>
<LANGUAGE>ENG</LANGUAGE>
<FI>
<ORG>ABC</ORG>
<FID>000111222</FID>
</FI>
</SONRS>
<MFACHALLENGETRNRS><!--MFA Challenge Transaction aggregate-->
<TRNUID>66D3749F-5B3B-4DC3-87A3-8F795EA59EDB</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
<MESSAGE>SUCCESS</MESSAGE>
</STATUS>
<MFACHALLENGERS><!--MFA Challenge aggregate-->
<MFACHALLENGE>
<MFAPHRASEID>MFA13</MFAPHRASEID>
Client collects the answers and returns them to server along with the original request.
<OFX>
<SIGNONMSGSRQV1>
<SONRQ>
<DTCLIENT>20060321083415</DTCLIENT>
<USERID>12345</USERID>
<USERPASS>MyPassword</USERPASS>
<LANGUAGE>ENG</LANGUAGE>
<FI>
<ORG>ABC</ORG>
<FID>000111222</FID>
</FI>
<APPID>MyApp</APPID>
<APPVER>1600</APPVER>
<CLIENTUID>22576921-8E39-4A82-9E3E-EDDB121ADDEE</CLIENTUID>
<MFACHALLENGEANSWER><!--MFA Challenge answer-->
<MFAPHRASEID>MFA13</MFAPHRASEID
<MFAPHRASEA>1234</MFAPHRASEA>
</MFACHALLENGEANSWER>
<MFACHALLENGEANSWER><!--MFA Challenge answer-->
<MFAPHRASEID>MFA107</MFAPHRASEID>
<MFAPHRASEA>ClientUserAgent</MFAPHRASEA>
</MFACHALLENGEANSWER>
<MFACHALLENGEANSWER><!--MFA Challenge answer-->
<GETMIMERS>
<URL>https://www.fi.com/xxx/yyy/zzz.jpg</URL>
</GETMIMERS>
If the file includes the same response using multipart MIME, clients must have the local file, zzz.jpg.
The extensions are not considered proprietary. An organization is free to publish their extensions and
encourage client and server implementors to support them.
All tag names that do not contain a period (.) are reserved for use in future versions of the Open Financial
Exchange specification.
Note: Because OFX 2.2 forces XML compliance, unrecognized tags (per the DTD) are no
longer allowed in OFX documents. If a client or server wishes to send an OFX document with
tags or elements not found in the official OFX DTD, a modified DTD must be sent with the
OFX document containing the new content so that validating parsers will not fail on parsing the
new tags or elements.
The requirement to send a modified DTD with the document itself can be relaxed for clients
and servers which do not use validating parsers. However, clients and servers using extensions
to OFX must still conform to a mutually agreed upon DTD.
Tag Description
<OFXEXTENSION> OFX Extension wrapper aggreate; optional in all cases
<OFXELEMENT> Custom element wrapper; 1 or more
<TAGNAME> Custom element name, A-32
<NAME> User-friendly display name for the custom element, A-32
<TAGTYPE> Any defined OFX type (date, amount, etc.) or standard format for defining an
alpha or numeric field (e.g. such as A-x, N-x), A-20
<TAGVALUE> Custom element data value, A-10000
</OFXELEMENT>
</OFXTENSION>
It is STRONGLY recommended that all parties using the <OFXEXTENSION> mechanism follow the
guidelines from Section 2.7.1 about registering a prefix and using that prefix in <TAGNAME> in order to
avoid collisions.
For example, if an organization registered "ABC" as a prefix they would return an <OFXELEMENT>
aggregate containing <TAGNAME>ABC.SOMETHING</TAGNAME>. A user-friendly display name
for the element may be returned in the optional <NAME> tag within the aggregate.
<OFXEXTENSION>
<OFXELEMENT>
<TAGNAME>ABC.LASTBRANCHVISIT</TAGNAME>
<NAME>Date of last visit</NAME>
<TAGTYPE>DATE</TAGTYPE>
<TAGVALUE>20140203</TAGVALUE>
</OFXELEMENT>
</OFXEXTENSION>
OFXHEADER:100
DATA:OFXSGML
VERSION:102
SECURITY:NONE
ENCODING:USASCII
CHARSET:NONE
COMPRESSION:NONE
OLDFILEUID:NONE
NEWFILEUID:NONE
The user-supplied values under consideration here fall into three broad groups:
• Values provided for security reasons
• Values of critical ID fields
• Values of non-critical fields
This group pertains to values provided for security reasons such as <USERID> and <USERPASS>
elements. These values must never be manipulated by a client; they are sent without change to the server.
This group pertains to critical ID fields, generally account numbers, routing numbers and the like. These
values also should never be manipulated by a client unless the server has supplied the client with a
This third group of values relates to certain non-critical fields such as postal codes, addresses and
telephone numbers. Such values should not be manipulated by the client unless there is information that
the client has, which the user may not be aware of, for example, the four additional digits in a U.S. zip
code. In the case where such manipulated data is sent to the server (as opposed to simply displaying it
differently in the application) the client should inform the user that this change will be made, thereby
allowing the user to prevent the change if desired. An example of this would be the substitution of the
name of a township for the name of the larger city encompassing it, based on the postal code value.
When matching user-supplied text against stored information, servers are free to ignore all supplied
punctuation characters. For example, a server might remove all punctuation from an <ACCTID> before
performing validation. This temporary modification affects neither how the data would be returned, nor its
storage format. Such transformations should not occur with values provided for security reasons such as
<USERID> and <USERPASS> elements.
Servers are permitted to add or remove punctuation or otherwise modify client-supplied information, while
storing the data after processing a (successful) <xxxRQ> or <xxxMODRQ> request. For example, a server
might store only the first five digits of a US <POSTALCODE> value, abbreviate common address
components (storing "St." when the request specified "Street"), or use a special address for well-known
payees. If a server does make such modifications, it must return the client-supplied values verbatim in the
initial response, and treat the modification as a server-initiated action. Therefore, a subsequent
synchronization should include a <xxxMODRS> with the server-stored values and <TRNUID>0 (zero) to
indicate that the server modified the client-supplied values.
This last requirement does not distinguish between insignificant changes (case or abbreviations) and
semantic differences (use of a completely different address for well-known payees). Although it is
recommended that clients be notified of all insignificant storage discrepancies and modifications, it is
required that clients be informed of all other such modifications.
In summary, if, for security reasons, a server will not accept a value that is punctuated differently than
expected, it must force compliance as described in section 3.1.2.1. In some cases where this is not possible,
sending a <xxxMODRS> to force a change on the client side might also be in order. (Note that a
PAYEEMODRS will not affect pending payments so a server may also have to send out-of-band payment
modifications, if applicable.)
Any intermediate software should avoid any modifications to these values, thus avoiding the need to
resolve this issue out-of-band.
Tag Description
<BAL> Balance-response aggregate
<NAME> Balance name, A-32
<DESC> Balance description, A-80
<BALTYPE> Balance type.
DOLLAR = dollar (value formatted DDDD.cc)
PERCENT = percentage (value formatted XXXX.YYYY)
NUMBER = number (value formatted as is)
<VALUE> Balance value.
Interpretation depends on <BALTYPE> field, amount
<DTASOF> Effective date of the given balance, datetime
<CURRENCY> If dollar formatting, can optionally include currency, see section 5.2
</CURRENCY>
</BAL>
Note: Historically, <BAL> aggregates and the enclosing <BALLIST>, have had limited
adoption by OFX Servers and clients. Out-of-band coordination is typically required in order to
ensure appropriate usage and display. Due to this, OFX 2.2 added multiple new tags and
aggregates to statement download which could, alternatively, be mapped into <BAL>, in order
Clients should assume the burden of checking the profile and not sending a transaction which the server
does not support. If the client goes ahead and sends such a transaction, the server may either return an
HTTP 400 syntax error, or ignore unsupported elements and aggregates. In the latter case, assuming no
other problems occur in processing that request, servers may return warning code 2028 (Request element
unknown). The response file should not contain the unsupported elements or aggregates.
The last 200 error codes in each assigned range of 1000 are reserved for server-specific status codes. For
example, of the general status codes, 2800-2999 are reserved for status codes defined by the server. Of the
banking status codes, codes 10800-10999 are reserved for the server. If a client receives a server-specific
status code of <SEVERITY> ERROR that it does not know, it must handle it as a general error 2000.
Tag Description
<MESSAGE> A textual explanation from the FI. Note that clients will generally have messages of their
own for each error ID. Use this element only to provide more details or for the general
errors. A-255
</STATUS>
Code Meaning
0 Success (INFO)
Note: Servers should provide a more specific error whenever possible. Error 2000
should be reserved for cases in which a more specific code is not available.
Note: Clients will generally have error messages that are based on <CODE>. Therefore, do not
use <MESSAGE> to replace that text. Use <MESSAGE> only to explain an error not well
described by one of the defined codes, or to provide some additional information.
<MESSAGE> should be returned whenever the <CODE> can be refined. For example,
<CODE>2000 should always be accompanied with a <MESSAGE> explaining the problem.
Several OFX request and response pairs allow clients to request, and FIs to send, instructions for accessing
images. These instructions contain image retrieval information but not the actual images themselves. This
information is returned in the <IMAGEDATA> aggregate, and is used by the client to retrieve the actual
images, as described in Chapter 15, “Image Download”.
Tag Description
<IMAGEDATA> Image information
<IMAGETYPE> Type of image. Use one of the following:
STATEMENT: the image is a statement image
TRANSACTION: the image is a transaction image (e.g. a check image)
TAX: the image is a tax image
Account-from options.
Choose either
<IMAGEDELAY> or
<DTIMGAVAIL>.
<IMAGEDELAY> Number of calendar days from <DTSERVER> (for statement images) or
<DTPOSTED> (for transaction images) when image will become available, N-5
-or-
Each image corresponds to one <IMAGEDATA> aggregate. The number of <IMAGEDATA> aggregates
returned in a statement download or closing response depends upon the type of response. A closing
statement will be contained in one image. A check image, however, will be contained in one or two
images, depending on whether the front and back are concatenated. Therefore, only one <IMAGEDATA>
aggregate will be returned in the various <xxxSTMTENDRS> responses and one or two <IMAGEDATA>
aggregates will be returned in the <xxxSTMTTRN> responses since the latter correspond to individual
transactions (e.g. checks).
Value Description
URL The image is accessed directly via the URL provided. The image
cannot be retrieved via an OFX image request. The expectation is
that the client will not provide authentication and will simply
follow the URL provided. See section 15.2.2 for more information.
FORMURL The image is accessed directly via an encoded URL. The image
cannot be retrieved via an OFX image request. The expectation is
that the client will send authentication to the server. See section
15.2.3 for more information.
The following aggregate may appear in various profile responses and will be referred to in those profile
sections where appropriate.
Tag Description
</IMAGEPROF>
Open Financial Exchange uses <TRNUID>s to identify transactions within transaction wrappers
(<xxxTRNRQ>, </xxxTRNRQ>).
In most cases, clients originate <TRNUID>s. When a client originates a <TRNUID>, the value of the
<TRNUID> is always set to a unique identifier. The server must return the same <TRNUID> in the
corresponding response and any later synchronization responses that include this response. Clients may
use this <TRNUID> to match up requests and responses or to recognize synchronized responses for
transactions they did not initiate. Servers can use <TRNUID>s to reject duplicate requests. Because
multiple clients might be generating requests to the same server, transaction IDs must be unique across
clients. Thus, <TRNUID> must be a globally unique ID.
In some cases, servers can originate a transaction that was not specifically requested by a client. For
instance, a client might set up a recurring payment model. Although the client originates the payment
model, the server originates the individual payments. Whenever the server originates a transaction, the
value of the <TRNUID> must be set to zero. Lite synchronization servers (see Chapter 6, "Data
Synchronization") must respond to synchronization requests with information about all changes of this
type.
The Open Software Foundation Distributed Computing Environment standards specify a 36-character
hexadecimal encoding of a 128-bit number and an algorithm to generate it. Clients are free to use their own
algorithm, to use smaller <TRNUID>s, or to relax the uniqueness requirements. However, it is
RECOMMENDED that clients allow for the full 36 characters in responses to work better with other
clients.
For example: A client creates a new recurring payment using <RECPMTRQ> in a <RECPMTTRNRQ>
with <TRNUID>123. Later, the same client might cancel the model using <RECPMTCANRQ> in a
<RECPMTTRNRQ> with <TRNUID>456. The server would inform the client of any spawned payments
using <PMTRS> responses with <TRNUID>0 in later payment synchronization responses
(<PMTSYNCRS>).
A <SRVRTID> is not unique across FI’s or Service Providers, and clients might need to use FI +
<SPNAME> + <SRVRTID> when a unique key is necessary.
A <SRVRTID> must be unique across users for joint accounts. Therefore, it is not sufficient to just keep
the <SRVRTID> unique to an account if it is shared by more than one user.
Where the context allows, a server may use the same value for a given server object for both <SRVRTID>
and <FITID>, but the client will not know this. In this case, the server must assign <SRVRTID> and
<FITID> values that are more unique than otherwise required. Because of the differing uniqueness
constraints on the individual elements, such a reused value must be unique throughout the FI.
For example: The server creates the new recurring model from the example in section 3.2.1 with
<RECSRVRTID>1234:5687. The server uses this identifier in the initial <RECPMTRS> and any
synchronization responses that reference this model. The client references the same <RECSRVRTID> in
the later <RECPMTCANCRQ>.
If any payments are spawned from this model before it is cancelled, they would each have their own
<SRVRTID> value (for example, <SRVRTID>8765:4321 and <SRVRTID>8765:4322). The <SRVRTID>
value for one of the spawned payments may match the <RECSRVRTID> of the model. Such a match is not
required for any spawned payment. To guarantee uniqueness of the payment identifiers, no more than one
spawned payment may use the <RECSRVRTID> value of its model.
An FI (or its Service Provider) assigns an <FITID> to uniquely identify a financial transaction that can
appear in an account statement. Its primary purpose is to allow a client to detect duplicate responses. Open
Financial Exchange intends <FITID> for use in statement download applications, where every transaction
(not just those that are client-originated or server-originated) requires a unique ID.
An <FITID> also uniquely identifies the closing statement in <CLOSINGRS> and <CCCLOSINGRS>.
Again, the OFX client should detect repeated closing statements (duplicate downloads) using these
identifiers.
FITIDs must be unique within the scope of an account but need not be sequential or even increasing.
Clients should be aware that FITIDs are not unique across FIs. If a client performs the same type of request
within the same scope at two different FIs, clients will need to use FI + <ACCTID> + <FITID> as a
Note: Although the specification allows FITIDs of up to 255 characters, client performance
may significantly improve if servers use fewer characters. It is recommended that servers use
32 characters or fewer.
For example: The two spawned payments mentioned in section 3.2.1 are processed and later downloaded
in a <STMTRS>. The first payment’s <STMTTRN> would list <SRVRTID>8765:4321,
<RECSRVRTID>1234:5678, and <FITID>9999:8888:7777. The second payment would be described in a
<STMTTRN> containing <SRVRTID>8765:4322, <RECSRVRTID>1234:5678, and
<FITID>6666:5555:4444.
Open Financial Exchange uses <TOKEN> as part of data synchronization requests to identify the point in
history that the client has already received data, and in responses to identify the server’s current end of
history. See Chapter 6, “Data Synchronization,” for more information.
<TOKEN> is unique within an FI and the scope of the synchronization request. For example, if the
synchronization request includes an account ID, the <TOKEN> needs to be unique only within an account.
Servers are free to use a <TOKEN> that is unique across the entire FI. Clients must save separate
<TOKEN>s for each account, FI, and type of synchronization request.
Open Financial Exchange uses <TRNAMT> in any request or response that reports the total amount of an
individual transaction.
Usage: Bank statement download, transfers, payments, investment statement download, bill presentment
tables
Clients use these elements in requests to indicate the range of response that is desired. Servers use these
elements in responses to let clients know what the FI was able to produce.
Usage: Bank statement download, investment statement download, 401(k) summary, bill presentment list
request
There is one format for representing dates, times, and time zones. The complete form is:
MM 1 - 12
DD 1 - 31
HH 0 - 23
MM 0 - 59
SS 0 - 60
60 is only used in the case of the leap second
Elements specified as type date or datetime and generally starting with the letters “DT” accept a fully
formatted date-time-timezone string. For example, “19961005132200.124[-5:EST]” represents October 5,
1996, at 1:22 and 124 milliseconds p.m., in Eastern Standard Time. This is the same as 6:22 p.m.
Greenwich Mean Time (GMT).
Date and datetime also accept values with fields omitted from the right. They assume the following
defaults if a field is missing:
YYYYMMDDHHMMSS GMT
YYYYMMDDHHMMSS.XXX GMT
Note that times zones are specified by an offset and optionally, a time zone name. The offset defines the
time zone. Valid offset values are in the range from –12 to +12 for whole number offsets. Formatting is
+12.00 to -12.00 for fractional offsets, plus sign may be omitted.
Take care when specifying an ending date without a time. For example, if the last transaction returned for
a bank statement download was Jan 5 1996 10:46 am and if the <DTEND> was given as just Jan 6, the
next statement download request would have a <DTSTART> of just Jan 6, causing any transactions posted
Note: Open Financial Exchange does not require servers or clients to use the full precision
specified. However, they are REQUIRED to accept any of these forms without complaint.
Some services extend the general notion of a date by adding special values, such as “TODAY.” These
special values are called “smart dates.” Specific requests indicate when to use these extra values, and list
the element as having a special data type.
Elements specified as type time and generally ending with the letters “TM” accept times in the following
format:
The milliseconds and time zone are still optional, and default to GMT.
Several issues arise when a customer and FI are not in the same time zone, or when a customer moves a
computer into new time zones. In addition, it is generally unsafe to assume that computer users have
correctly set their time or time zone.
Although most transactions are not sensitive to the exact time, they often are sensitive to the date. In some
cases, time zone errors lead to actions occurring on a different date than intended by the customer. For this
reason, servers should always use a complete local time plus GMT offset in any datetime values in a
response. If a customer’s request is for 5 p.m. EST, and a server in Europe responds with 1 a.m. MET the
next day, a smart client can choose to warn the customer about the date shift.
Clients that maintain local state, especially of long-lived server objects, should be careful how they store
datetime values. If a customer initiates a repeating transaction for 5 p.m. EST, then moves to a new time
zone, the customer might have intended that the transaction remain 5 p.m. in the new local time, requiring
a change request to be sent to the server. If, however, the customer intended it to remain fixed in server
time, this would require a change in the local time stored in the client.
Client software that doesn’t know the current local time zone for the user, or client proxies that don’t know
the current local time zone of their end users, should maintain and display the datetime value in the time
zone indicated by the originator of the value and explicitly marked with that time zone. As an example,
consider <DTPMTDUE> in section 11.5.4.2. If the biller gave a due date of 23:59pm EST on Dec. 29,
1997, this is best displayed as 23:59pm EST rather than rendered in local time if there is any doubt at all as
to the current local time zone of the end user looking at the due date.
Note: Developers should consider the possibility of a date change due to timezone conversion.
A datetime value in the GMT timezone with a time of 12:00:00 (noon) would be converted to
another time on the same date in every timezone. For example, 199812251200 remains
Christmas Day in every timezone.
Format: A-32
This section describes the format of numerical values used for amounts, prices, and quantities. In all cases,
a numerical value that does not contain a decimal point has an implied decimal point at the end of the
value. For example, a numerical value of “550” is equivalent to “550.” Trailing and leading spaces should
be stripped. Number format uses a leading sign. Negative number format uses a minus sign (-). Positive
number format uses a plus sign (+). The plus sign is implied for all amounts and can be omitted.
The following types are defined to have a maximum of 32 characters, including alphabetic characters,
digits and punctuation. However, clients and servers may have specific limits for the maximum number of
digits to the left or right of a decimal point. If a server cannot support a client request due to the size or
precision of a number, the server should return status code 2012.
Amount: Amounts that do not represent whole numbers (for example, 540.32), must include a decimal
point or comma to indicate the start of the fractional amount. Amounts should not include any punctuation
separating thousands, millions, and so forth. The maximum value accepted depends on the client.
Unitprice: Use decimal notation. Unless specifically noted, prices should always be positive.
Rate: Use decimal notation, with the rate specified out of 100%. For example, 5.2 is 5.2%. Rates can be
greater than 100 and can be negative.
Some services define special values, such as INFLATION, which you can use instead of a designated
value. Open Financial Exchange refers to these as “smart types,” and identifies them in the specification.
Most OFX transaction aggregates describe the flow of funds. Amounts in transactions which clearly
describe the flow of funds should normally be positive. For example, bank transfers (<INTRARQ>), bill
payments (<PMTRQ>) and investment buys/sells (<BUYSTOCK>, <SELLSTOCK>) should all have
positive amounts.
Balances in statement download and closing aggregates will typically be signed based on their effect on
the user’s net worth. For example, a credit card balance is typically negative indicating charges on the
account decreasing their net worth, a checking account is typically positive indicating it has funding and
increases the user’s net worth. An exception to this rule applies to summary information aggregates (such
as <LOANDETAIL>) which contain summary or informational balance information (such as
<LOANINITBAL>, <PRINCIPALBAL>) as well as similar summary fields throughout the specification -
these balance tags should always be signed positive.
An exception to the above rules are signage of the amount in statement download transactions, wrapped
within <STMTTRN></STMTTRN> tags. The amounts in these transactions should be signed on the basis
of how the account is affected, e.g. a <TRNTYPE>DEBIT should have a negative <TRNAMT> value.
Servers should sign amounts from the perspective of the user in cases where the flow of funds cannot be
determined from the transaction aggregate alone. For example, interest amounts can be either positive or
negative, depending on whether the interest is earned or paid.
3.2.10 Language
Language identifies the human-readable language used for such things as status messages and e-mail.
Language is specified as a three-letter code based on ISO-639.
currsymbol: A three-letter code that identifies the currency used for a request or response. The currency
codes are based on ISO-4217. For more information about currencies, refer to section 5.2.
URL: String form of a World Wide Web Uniform Resource Location. It should be fully qualified including
protocol, host, and path. A-255
4.1.1 Architecture
OFX security applies to the communication paths between a client and the profile server, a client and the
Web server, and, when the OFX server is separate from the Web server, a client and the OFX server. The
diagram below illustrates the initial order in which these communications occur, assuming that the client
already has the URL for the FI profile server.
F I Id e n tifie r
P R O FIL E
F I P ro file SER VER
in c lu d in g
W e b S e rv e r U R L
C L IE N T
Fin a n c ia l In stitu tio n o r 3 rd P a rty
O F X R e q u e st
W EB O FX
SER VER SER VER
O F X R e sp o n se
OFX specifies the minimum security required for Internet transactions. Through its choice of security
techniques and related options, an FI can achieve privacy, authentication, and integrity with varying
degrees of assurance. For example, there are many kinds of encryption algorithms, most of which can be
strengthened or weakened by changing the key size.
A certificate is a digitally signed document that binds a public key to an identity. It contains a public key
that identifies information such as the name of the person or organization to whom the key belongs, an
expiration date, a unique serial number, and additional descriptive information.
A certificate is useful for authentication because it is signed by a trusted third-party. This assures the
verifier that the certificate has not been changed since it was signed. The entity which signs certificates is
called a certification authority, or CA. A CA acts somewhat like a notary public: the reader of a document
stamped by a notary public knows that the notary has checked the identity of the person who originated the
document. By digitally signing someone’s identity and public key, the CA affirms that the two go together.
Certificates are used in Type 1 security, as well as channel-level security through an appropriate encryption
method. The format for these is defined by X.509 version 3. For more information, refer to ITU-T Rec.
X.509, ISO/IEC 9594-8.
4.1.3.2 PKCS #1
The acronym, PKCS, stands for “Public Key Cryptography Standards,” a set of standards developed by a
consortium and hosted by RSA. PKCS #1 is the RSA Encryption Standard, the rules for using RSA public
4.1.4 FI Responsibilities
OFX is designed with the understanding that there must be a security policy in place at each supporting
financial institution. That policy must clearly delineate how customer data is secured, and how transactions
are managed such that all parties to the transaction are protected according to accepted and recognized best
common practices.
The decision regarding which users may perform a given operation on a given account must be determined
by the financial institution. For example, is the specified user authorized to perform a transfer from the
specified account? The financial institution must also determine whether the user has exceeded allowed
limits on withdrawals, whether the activity on this account is unusual given past history, and other context-
sensitive issues.
Although OFX provides many security options, an FI must support a minimal level of security. To ensure
the proper security configuration, an FI must follow the steps outlined below.
1. Obtain a certificate, rooted in an acceptable CA, for the OFX Profile server. Establish appropriate
safeguards for this certificate and its private key.
2. Obtain a certificate, rooted in an acceptable CA, for each OFX server. Establish appropriate
safeguards for this certificate and its private key.
3. Decide whether to use Type 1 application-level security for any message sets. For each message set to
be secured by Type 1, obtain a certificate.
Type 1 security can be used on any message set, except for the Profile message set.
There are a number of other security issues beyond OFX proper, especially those relating to the Internet
and network engineering. These issues are beyond the scope of this document. FIs are advised to conduct a
complete security review of all servers associated with OFX.
The following diagram illustrates how channel-level and application-level security relate. The diagram
shows the path of a request from the client to the server when application-level encryption is used.
Channel-level security is sufficient for most message sets, provided that the network architecture at the
destination is adequately secure; however, application-level password encryption can allow a more flexible
back-end architecture with a high level of security.
For each message set listed in the FI profile response, the <MSGSETCORE> aggregate describes the
channel-level security required for that message set.
The <TRANSPSEC> element defines whether or not channel-level security is required. It can have one of
the following values:
Tag Description
Setting the <TRANSPSEC> element to Y means that the client must use transport-level security.
While previous versions of the specification referred to specific transport-level security protocols and
cyphers the dynamic/changing nature of security threats and vulnerabilities render any section quickly out-
of-date. Security standards should be evaluated at the time of implementation and coordinated
appropriately between client and server developers out of band.
For each message set listed in the FI profile response, the <MSGSETCORE> aggregate describes the
security required for that message set.
The <OFXSEC> element defines the type of application-level security required for the message set.
<OFXSEC> can have one of the following values, which also are used in the SECURITY element of the
OFX headers:
Tag Description
While Application Level security is specified for each Message Set in the profile, one of the goals of the
Type 1 protocol in the SignOn Message Set is to protect the user password all the way to the destination
OFX server. In the absence of client certificates, this password is the primary vehicle for client
authentication and is therefore worthy of special consideration.
Type 1 requires channel-level security. Though the password is well protected by transport-level security
alone in the client to Web server connection, the server-side network architecture may render the password
less secure while it is in transit between the Web and OFX servers. With Type 1, the user password is not
decrypted until the request reaches the OFX server.
Type 1 applies only to the request part of a message; the server response is unaffected.
A simple approach would be to deliver the server’s Type 1 certificate in the profile and use it to encrypt the
password, but that would permit a replay attack. An attacker could capture a transaction, including
encrypted password, and replay it to the server. It wouldn’t matter that the password remained unknown.
To prevent the replay attack, the server introduces some random data to the process, data which is
unpredictably different for each transmission. The client asks for the random data with a challenge request.
The server sends it, along with its Type 1 certificate, in the challenge response. The client then uses that
random data in the encryption process, thereby assuring the server that the client response is associated
with this and only this interaction.
Challenge response
w/ random data
WEB OFX
CLIENT SERVER SERVER
OFX request w/
encrypted password
OFX response
In this section, the expression, C = EA (M), means that plain text M is encrypted either symmetrically or
asymmetrically with key A into ciphertext C. The expression, M = DA(C) signifies the inverse operation
(decryption), in which ciphertext C is decrypted into plain text M using key A. If C was encrypted
asymmetrically, then A in the latter case is understood to be the private component of the key. The
expression, A || B, indicates that B is concatenated to A.
Type 1 application-level security provides additional password secrecy. These are the steps for conducting
a Type 1 transaction (unless otherwise noted, the term “Server” in this section refers to the Financial
Institution Server):
1. Client obtains the Server’s profile from the Profile Server (see Chapter 7, "FI Profile")
2. Client establishes a secure (transport-level) connection with the Server (see section 4.2.1)
3. Client sends <CHALLENGERQ> to Server (see section 4.2.2.4.1)
4. Server sends <CHALLENGERS> which contains a nonce and the Server’s Type 1 certificate (see
section 4.2.2.4.2)
5. Client builds a transaction request and sends it to the Server (see section 4.2.2.4.3)
6. Server parses the request, verifying the user password, and either rejects or processes the transaction
(see section 4.2.2.4.4)
CT1 octet string, length 128 Ciphertext: the PKCS #1 RSA encryption of EB with KS.
CT1 = EKS(EB)
CT2 printable ASCII, length 171 Encoded Ciphertext: the RADIX-64 encoding of CT1 (see
RFC 1113, §4.3.2.4 and §4.3.2.5).
CT2 = RADIX64(CT1)
EB octet string, length 128 Encryption Block: the formatted plain text block, ready for
encryption.
EB = 0x00 || BT || PS || 0x00 || D
KS RSA key, modulus length 1,024 bits Server’s Type 1 RSA key
NC octet string, length 16 Client Nonce: string of random octets generated by the
Client
NS octet string, length 16 Server Nonce: string of random octets generated by the
Server
P printable ASCII, null-padded, length 32 Password: shared by the Client and Financial Institution,
null-padded on the right
PS octet string, length 57 Padding String: each octet is pseudo-random and non-zero
Server sends a <CHALLENGERS> to the client. This response contains the Server’s Type 1 certificate and
NS.
In <PINCHRQ>, the steps are identical, except that in step 2, P is set to <NEWUSERPASS> and in step
10, CT2 is copied to the <NEWUSERPASS> field of the <PINCHRQ>.
Legend NS P NC
16 bytes 32 bytes 16 bytes
SHA-1
| concatenation
0x00 BT PS 0x00 D
1 byte 1 byte 57 bytes 1 byte 68 bytes
EB CT1 CT2
E R64
128 bytes 128 bytes 171 bytes
In <PINCHRQ>, the steps are identical except that in step 2, CT2 is obtained from the
<NEWUSERPASS> field of the <PINCHRQ> and in step 5, the server does not look up the extracted new
password in a database.
The encoding declaration of the standard XML declaration specifies the character set being used. Servers
should respond to clients using the same encoding as was sent in the client’s request.
Clients identify the language in the signon request. OFX specifies languages by three-letter codes as
defined in ISO-639. Servers report their supported languages in the profile (see Chapter 7, "FI Profile"). If
a server cannot support the language requested by the client, it must return an error and not process the rest
of the transactions.
Within each transaction, specific parts of the response might need to report a different currency. Where
appropriate, aggregates include an optional <CURRENCY> aggregate. The scope of a <CURRENCY>
aggregate is everything within the same aggregate that the <CURRENCY> aggregate appears in, including
nested aggregates, unless overridden by a nested <CURRENCY> aggregate. For example, specifying a
<CURRENCY> aggregate in an investment statement detail means that the unit price, transaction total,
commission, and all other amounts are in terms of the given currency, not the default currency.
Note that there is no way for two or more individual elements that represent amounts—and are directly
part of the same aggregate—to have different currencies. For example, there is no way in a statement
download to have a different currency for the <LEDGERBAL> and the <AVAILBAL>, because they are
both directly members of <STMTRS>. In most cases, you can use the optional <BAL> aggregates to
overcome this limitation, since <BAL> aggregates accept individual <CURRENCY> aggregates.
The default currency for a request is the currency of the source account. For example, the currency for
<BANKACCTFROM>.
The <CURRATE> should be the one in effect throughout the scope of the <CURRENCY> aggregate. It is
not necessarily the current rate. Note that the <CURRATE> needs to take into account the choice of the FI
for formatting of amounts (that is, where the decimal is) in both default and overriding currency, so that a
Tag Description
<CURRENCY> or Currency aggregate
<ORIGCURRENCY>
In some cases, OFX defines transaction responses so that amounts have been converted to the home
currency. However, OFX allows FIs to optionally report the original amount and the original (foreign)
currency. In these cases, transactions include a specific aggregate for the original amount, and then an
<ORIGCURRENCY> aggregate to report the details of the foreign currency.
Again, <CURRENCY> means that OFX has not converted amounts. Whereas, <ORIGCURRENCY>
means that OFX has already converted amounts.
In some cases, an element value represents a fundamental way of identifying something, yet there does not
exist a world-wide standard for such identification. Examples include bank accounts and securities. In
these cases, OFX must define a single, extensible approach for identification. For example, CUSIPs are
used within the U.S., but not in other countries. However, CUSIPs are fundamental to relating investment
securities, holdings, and transactions. Thus, a security ID consists of a two-part aggregate: one to identify
the naming scheme, and one to provide a value. OFX will define valid naming schemes as necessary for
each country.
6.1 Overview
Currently, some systems provide only limited support for error recovery and no support for backup files or
multiple clients. This chapter defines OFX’s powerful means of data synchronization between clients and
servers.
This chapter first provides a brief introduction to synchronization problems and then presents the strategy
used in OFX to ensure data integrity. Additional details about synchronization requests and responses may
be found in the relevant sections of this document. The final section in this chapter discusses alternatives to
full synchronization and summarizes the options for each.
6.2 Background
When a connection between the client and the server does not successfully complete, there are two main
areas of concern:
• Unconfirmed requests
If a client does not receive a response to work it initiates, it has no way of knowing whether the server
processed the request. It also does not have any server-supplied information about the request, such as a
server ID number.
• Unsolicited data
Some message sets allow a server to send data to the client without first receiving a request. OFX
assumes that the first client to connect after the unsolicited data is available receives it. If the
connection fails, this information could be forever lost to the client. Examples of unsolicited data
include updates to the status of a bill payment and e-mail messages.
Unsolicited data presents problems beyond error recovery. Because the first client that connects to a server
is the only one to receive unsolicited data, this situation precludes use of multiple clients without a data
synchronization method. For example, if a user has a computer at work and one at home, and wants to
perform online banking from both computers, a bank server could send unsolicited data to one but not the
other.
An even greater problem occurs when a user resorts to an outdated backup copy of the client data file. This
backup file may be missing recent unsolicited data with no way to retrieve it from the server again.
To ensure a consistent state after a failure (for example, dropped client connections or a client crash before
updating its database), the client must store all data returned in a sync response before updating the saved
token for that account and object type. After a failure, the next sync attempt using the old token might
download information already reflected in the client database. But, re-integration of that data is much
preferred over losing all changes between the old and new token values.
If a user switches to an outdated backup file, then the most recent endpoint known to the client will be
older than the most recent endpoint known to the server.
If multiple clients are in use, each will send requests based on its own current endpoint, so that both clients
will obtain complete information from the server. This is one reason why OFX responses carry enough
information from the request to enable them to be processed independent from the requests. The diagram
below shows the interaction between clients and servers.
Note: OFX does not require servers to store responses based on individual connections. Also,
not all requests are subject to synchronization. For example, OFX does not require servers to
store statement-download responses separately for data synchronization.
Each OFX service identifies the objects that are subject to data synchronization. For example, a bank-
statement download is a read-only operation from the server. A client can request it again; consequently,
there is no data synchronization for this type of response.
6.4.1 Tokens
The basis for synchronization is a token as defined by the <TOKEN> element. The server can create a
token in any way it wishes. The client simply holds the token for possible use in a future synchronization
request.
In all other cases, the server can use different types of tokens for different types of responses, if suitable for
the server.
Tokens can contain up to 10 characters in V1 message sets; see Chapter 3, "Common Aggregates,
Elements, and Data Types." Tokens must be unique only with respect to the type of synchronization
request and the additional information in that request. For example, a bill payment synchronization request
takes an account number; therefore, a token needs to be unique only within payments for the account. In
sync requests which do not include an account number, token values are scoped to the current user. For
example, a token in a payee synchronization request needs to be unique only within payees for the signed
on user.
The server can use different types of tokens for different types of responses, if suitable for the server.
Servers will not have infinite history available, so synchronization responses can optionally include a
<LOSTSYNC>Y (yes) if the old token in the synchronization request was older than the earliest available
history. This element allows clients to alert users that some responses have been lost.
Note: Tokens are unrelated to <TRNUID>s, <SRVRTID>s, and <FITID>s, each of which
serves a specific purpose and has its own scope and lifetime.
A <SRVRTID> is not appropriate as a <TOKEN> for bill payment. A single payment has a single
<SRVRTID>, but it can undergo several state changes over its life and thus have several entries in the
token history.
Each request and response that requires data synchronization will define a synchronization aggregate. The
aggregate tells the server which kind of data it should synchronize. By convention, these aggregates
always have SYNC as part of their names, for example, <PMTSYNCRQ>. These aggregates can be used
on their own to perform explicit synchronization, or as wrappers around one or more new transactions. For
example, <PMTSYNCRQ> aggregates request synchronization and may include new work.
Some clients can choose to perform an explicit synchronization before sending any new requests. This
practice allows clients to be up-to-date before sending any new requests. Other clients can simply send
new requests as part of the synchronization request.
If a client synchronizes in one file, then sends new work inside a synchronization request in a second file,
there is a small chance that additional responses became available between the two connections. There is
an even smaller chance that these would be conflicting requests, such as modifications to the same object.
However, some clients and some requests might require absolute control, so that the user can be certain
that they are changing known data. To support this, synchronization requests can optionally specify
<REJECTIFMISSING> element. The element tells a server that it should reject all enclosed requests if the
supplied <TOKEN> is out of date before considering the new requests. That is, if any new responses
became available, whether related to the incoming requests or not (but in scope of the synchronization
request), the server should immediately reject the requests. It should still return the new responses. A client
can then try again until it finds a stable window to submit the work. See section 6.5 for more information
about conflict detection and resolution.
• Embedded requests are completely ignored – they are not included in the response.
• Embedded requests are returned with a 2000 (or 6502 for recent servers) error. This is the preferred
approach.
The password change request and response present a special problem. See section 2.5.2 for further
information.
Note that tokens are not ordered, that is, a client should not assume that they are either incremented or
decremented in succeeding updates. The server determines how the tokens are updated/changed based on
its own algorithm.
If a request(s) is sent which is subject to synchronization but the request(s) is not "wrapped" in a
synchronization request, the server must still generate a new token internally to represent the activity that
occurred. This token is returned in the next synchronization response.
Some OFX transactions are not associated with tokens and no synchronization history is kept for them. An
example is bank statement download (STMTRQ/STMTRS). A statement download is a read-only
operation from the server. A client can request it again; consequently, there is no data synchronization for
this type of response.
In other cases, one OFX transaction is associated exclusively with a particular synchronization response.
That is, synchronization is associated with only one OFX request/response pair. An example of this is
PMTMAILR[Q/S]. PMTMAILRS is the only type of OFX response that will appear in the payment mail
synchronization response (PMTMAILSYNCRS).
Finally, there are several OFX transactions that will cause activity to be saved for later synchronization
under the umbrella of one synchronization response. An example of this is payment synchronization,
where payment responses (PMTRS), payment modification responses (PMTMODRS) and payment delete
responses (PMTCANCRS) can all appear in a payment synchronization response (PMTSYNCRS).
Tokens are generated, maintained and recognized only within the scope of the synchronization request/
response pair. For instance a <TOKEN>50511 sent in a payee synchronization request is unrelated to a
<TOKEN>50522 sent in a payment synchronization request because the tokens are associated with
different synchronization transactions (PAYEESYNC versus PMTSYNC). While clients must keep track
of the most up-to-date token within each synchronization type, servers must also keep a history of tokens
and associated activity within each type.
Note that server-initiated activity will also appear in a synchronization response, in addition to user/client-
initiated activity. In a token-based sync, this activity is identified by a response containing a <TRNUID>0.
(In a refresh, all TRNUID values are 0.) A payment spawned by a model and appearing in the payment
synchronization response is an example of such activity. In this case, the server will update the payment
synchronization token (associated with PMTSYNCR[Q/S] but not the recurring payment synchronization
A careful client always synchronizes before sending any new requests. If any responses come back that
could affect a user’s pending requests, the client can ask the user whether it should still send those pending
requests. Because there is a small chance for additional server actions to occur between the initial
synchronization request and sending the user’s pending requests, extremely careful clients can use the
<REJECTIFMISSING> element. Clients can iterate sending pending requests inside a synchronization
request with <REJECTIFMISSING> and testing the responses to see if they conflict with pending
requests. A client can continue to do this until a window of time exists wherein the client is the only agent
trying to modify the server. In reality, this will almost always succeed on the first try.
Note: OFX does not require a client to refresh just because it has lost synchronization.
Clients will mainly want to refresh lists of long-lived objects on the server; generally objects with a
<SRVRTID>. A brand new client, or a client that lost synchronization, might want to learn about in-
progress payments by doing a synchronization refresh of the payment requests. It would almost certainly
want to do a synchronization refresh of the recurring payment models, because those often live for months
or years.
A client may request a refresh by using <REFRESH>Y instead of the <TOKEN> element. Servers must
send responses that emulate a client creating or adding each of the objects governed by the particular
synchronization request.
When responding to a <REFRESH>Y sync request, servers must send <TRNUID>0 in each contained
transaction wrapper, the standard value for server-generated responses (except responses for embedded
transactions).
Due to the large volume of data which might be included in the response, clients should not perform
<MAILSYNCRQ> (or, one of the service-specific equivalents such as <BANKMAILSYNCRQ>) with
<REFRESH>Y.
A client that wants only the current token, without refresh or synchronization, makes requests with
<TOKENONLY>Y.
In all cases, servers should send the current ending <TOKEN> for the synchronization request in refresh
responses. This allows a client to perform regular synchronization requests in the future.
Tag Description
Client synchronization
option; <TOKEN>,
<TOKENONLY>, or
<REFRESH>
<TOKEN> Previous value of <TOKEN> received for this type of synchronization request
from server; 0 for first-time requests; token
<TOKENONLY> Request for just the current <TOKEN> without the history, Boolean
<REFRESH> Request for refresh of current state, Boolean
<REJECTIFMISSING> If Y, do not process requests if client <TOKEN> is out of date, Boolean
Note: Compliant clients should not send synchronization requests matching those listed
below. Nonetheless, servers should handle such requests and respond as described.
• <TOKENONLY>N has no useful meaning and clients should not send such a request. Servers may
interpret <TOKENONLY>N in the sync request the same as <TOKENONLY>Y.
• <REFRESH>N has no useful meaning and clients should not send such a request. Servers may
interpret <REFRESH>N in the sync request the same as <REFRESH>Y.
• If a client embeds transaction requests in a <REFRESH> or <TOKENONLY> sync request, the
server should respond in such a way that the <REFRESH> data or returned <TOKEN> reflects a
specific state, after the transactions have processed. Since servers are not required to reduce the data
about any particular object to a single addition response, embedded transactions may be processed
before or after the <REFRESH> data is retrieved. As with all synchronization responses, the
returned <TOKEN> must reflect the actions of all embedded transactions.
If the synchronization request included a bad account number or BANKID, or signon failed, or an account
was closed, etc. the response should include <TOKEN>–1, optionally <LOSTSYNC>N, and no history.
The simplest approach is to create a history database separate from the existing server. This history could
consist of the actual OFX transaction responses (<xxxTRNRS> aggregates) that are available to a
synchronization request, or simply the information required to re-create the responses upon request from
the client. The history database could index records by token, response type, and any other identifying
information for that type, such as account number. Clearly, this database must include all <TRNUID>s for
all transactions it contains. OFX recommends that <TRNUID>s be stored for as long as possible so that
they may be used to detect duplicate client requests even after the original requests have been purged from
the synch database.
The diagram below shows a high-level model of the OFX architecture for a financial institution. Notice
that the diagram shows the presence of a history journal.
Teller
Services
OFX
INTERNET Server
Transaction
Manager
Bank Server
Synchronization
Request/Response
-----------------------
-----------------------
-----------
Account
Records
History Journal
The server adds responses to the history journal for any action that takes place on the existing server. This
is true whether the OFX requests initiate the action or, in the case of recurring payments, it happens
automatically on the server. Once added to the history journal, the server can forget them.
The areas of the OFX server that process synchronization requests need only search this history database
for matching responses that are more recent than the incoming token.
For a refresh request, an OFX server would access the actual bank server to obtain the current state rather
than recent history.
Periodically the bank server would purge the history server of older entries.
More sophisticated implementations can save even more space. The history database could save responses
in a coded binary form that is more compact than the full OFX response format. Some FIs might have
much or all of the necessary data already in their servers; consequently, they would not require new data.
An FI could regenerate synchronization responses rather than recall them from a database.
No
Yes
In addition, some clients might prefer to use file-based error recovery with all servers, even if the client
and some servers support full synchronization. This section first describes file-based error recovery and
lite synchronization, and then explains the rules that clients and servers use to decide how to communicate.
Lite synchronizing servers may support both file-based error recovery and <REFRESH>Y. This type of
server is called a Refresh-capable Lite Synchronizing Server.
For information on how these types of synchronization are profiled, see section 7.2.1.
The format of these is the same as used with <TRNUID> as documented in section 2.4.6.
Note: If NEWFILEUID matches a previous request file then the request file identified by the
NEWFILEUID must contain exactly the same set of transactions as the previous request file.
Servers can reject the file if it contains new or modified transactions. In particular, clients
should disallow new <PINCHRQ> transactions during error recovery. For more information
about <PINCHRQ> and synchronization, see section 2.5.2.
• If NEWFILEUID is not set to NONE and does not match a previous request file, the client is preparing
for error recovery. The server should save the response file in case the data does not reach the client.
• If OLDFILEUID is set to NONE, the server may ignore the presence of this header. The server should
not search for a response file to delete. Clients should initiate file-based error recovery by sending
OLDFILEUID set to NONE and NEWFILEUID set to a unique value.
• If OLDFILEUID matches a file saved on the server, then OLDFILEUID is a file that the client has
successfully processed and the server can delete it.
• If OLDFILEUID is not set to NONE and does not match a previous request file, the server should
ignore the presence of this header. Either the server has purged the associated request file without
explicit request from the client or the client is requesting error recovery with identical headers to the
initial request attempt (NEWFILEUID should match a previous request file in this case).
Note: While it may indicate a client error for OLDFILEUID and NEWFILEUID to hold
identical values other than NONE, the server should ignore this OLDFILEUID header. Earlier
rules in this list detail how the server should handle the request file (based solely upon the
NEWFILEUID value).
A server should not save a response file when it is useless to do so. Specifically, the server should not save
a response file when the request fails parsing or when the request was rejected due to a <SONRQ>
problem (e.g. invalid <USERID>).
If all accounts are shared between two (or more) users (for example, husband and wife have separate
online access to the same list of joint accounts and none others), some identifiers may differ and should be
maintained separately by the client. Thus, clients should initiate error recovery and maintain/generate
xxxFILEUID values on a per-user basis.
There are two aspects of error recovery authentication which must be considered, request validation and
password validation.
When error recovery is being attempted the server should first perform signon authentication on the
request file. Once this is done, it should validate that the rest of the transactions in the request file received
match those of the request file that was archived for the corresponding response file which was also
archived. Recommended matching is defined at two levels:
• Minimal—Verify that the transactions correspond to the archived file
• Recommended—Verify the current request and archived request files exactly match. It is
recommended that checksums for all characters after the </SONRQ> be used to verify an exact match.
(The signon request itself may change between attempts.)
In all cases, the server must not store response files for the purposes of file-based error recovery when the
<SONRQ> has failed. A saved response file matching the OLDFILEUID header (if any) must not be
deleted when this occurs.In error recovery situations, the possibility exists that the user will have entered
the correct password when a request was originally sent, but will mistype the password when prompted for
it again during the recovery attempt. The server should respond as it would whenever sign on fails: It
should return 15500 errors in all transaction response aggregates. The server should return synchronization
Basic lite synchronization servers do not support <REFRESH>Y. Refresh-capable lite synchronizing
servers, however, do support <REFRESH>Y. That, in fact, is the only difference in function between a
Basic Lite Synch server and a Refresh-capable Lite Synch Server. The purpose of the distinction is to
allow a server to provide refresh capability without the burden of supporting full synchronization. (See
Section 6.10.2.1 for a discussion of refresh lite synch and older servers.)
Basic lite synchronization servers (including all servers that support versions of OFX prior to 1.6) do not
support <REFRESH>Y. Such servers may interpret <TOKEN>0 requests, however, as if they were refresh
requests, and respond with the exact refresh information a refresh capable lite synch server would respond
with. Newer servers should always support <REFRESH>Y if that functionality is provided, by specifying
<REFRESHSUPT>Y in the profile response. This does not preclude, however, providing backward-
compatible refresh support for older clients sending <TOKEN>0.
<PMTSYNCRQ>
<TOKEN>123</TOKEN>
<REJECTIFMISSING>N</REJECTIFMISSING>
<BANKACCTFROM>
<BANKID>121000248</BANKID>
<ACCTID>123456789</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
</PMTSYNCRQ>
<PMTSYNCRS>
<TOKEN>125</TOKEN>
<LOSTSYNC>N</LOSTSYNC>
<BANKACCTFROM>
<BANKID>121000248</BANKID>
<ACCTID>123456789</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<PMTTRNRS>
<TRNUID>123</TRNUID>
<STATUS>
... status details
</STATUS>
<PMTRS>
... details on a payment response
</PMTRS>
</PMTTRNRS>
<PMTTRNRS>
<TRNUID>546</TRNUID>
<STATUS>
... status details
</STATUS>
Client A was missing two payment responses, which the server provides. At this point, client A is
synchronized with the server. Client A now makes a new payment request, and includes a synchronization
update as part of the request. This update avoids having to re-synchronize the expected response at a later
time.
<PMTSYNCRQ>
<TOKEN>125</TOKEN>
<REJECTIFMISSING>N</REJECTIFMISSING>
<BANKACCTFROM>
<BANKID>121000248</BANKID>
<ACCTID>123456789</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<PMTTRNRQ>
<TRNUID>12345</TRNUID>
<PMTRQ>
... details of a new payment request
</PMTRQ>
</PMTTRNRQ>
</PMTSYNCRQ>
<PMTSYNCRS>
<TOKEN>126</TOKEN>
<LOSTSYNC>N</LOSTSYNC>
<BANKACCTFROM>
<BANKID>121000248</BANKID>
<ACCTID>123456789</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<PMTTRNRS>
... details on a payment response to the new request
</PMTTRNRS>
</PMTSYNCRS>
The client now knows that the server has processed the payment request it just made, and that nothing else
has happened on the server since it last synchronized with the server.
7.1 Overview
OFX clients use the profile to learn the capabilities of an OFX server. This information includes general
properties such as account types supported, user password requirements, specific messages supported, and
how the client should batch requests and where to send the requests. A client obtains a portion of the
profile when a user first selects an FI. The client obtains the remaining information prior to sending any
actual requests to that FI. The server uses a time stamp to indicate whether the server has updated the
profile, and the client checks periodically to see if it should obtain a new profile.
In more detail, a profile response contains the following sections, which a client can request
independently:
• Message Sets – list of services and any general attributes of those services. Message sets are collections
of messages that are related functionally. They are generally subsets of what users see as a service.
• Signon realms – FIs can require different signons (user ID and/or password) for different message sets.
Because there can only be one signon per <OFX> block, a client needs to know which signon the server
requires and then provide the right signon for the right batch of messages.
The profile message is itself a message set. In files, OFX uses the <PROFMSGSETV1> aggregate to
identify this profile message set.
Clients and servers generally use message sets as the granularity to decide what functionality they will
support. A “banking” server can choose to support the statement download and intrabank transfer message
sets, but not the wire transfer message set. Attributes are available in many cases to further define how
OFX supports a message set.
The profile applies only to the requests a client might expect the server to honor. That is, clients should not
send requests to servers unless support is indicated. However, the server may send unsupported responses
in a sync response as information is entered out of band. A client is required to at least parse such a file.
Clients should assume the burden of checking the profile and not sending a transaction which the server
does not support. If the client goes ahead and sends such a transaction, the server may either return an
HTTP 400 syntax error, or ignore unsupported elements and aggregates. In the latter case, assuming no
Each portion of the OFX specification that defines messages also defines the message set to which those
messages belong. This includes what additional attributes are available for those messages and whether
OFX requires the message set or it is optional.
Clients may request images in statement download and/or closing requests in various message sets. Prior
to requesting these images, clients must verify that support exists on the server for image download. This is
indicated by the presence of the <IMAGEMSGSET> aggregate in the profile response, as well as the
<IMAGEPROF> aggregate in the profile response for the specific message set in question. For instance, if
a client wishes to request transaction images in the banking statement download request, the client must
verify the presence of <IMAGEMSGSET> in the profile as well as transaction image support in the
<IMAGEPROF> aggregate in the <BANKMSGSET> in the profile. Image download requests are allowed
in OFX 2.2 in the Banking, Credit Card, Loan and Investments message sets.
If banking version 1 is at one URL (A) and billpay version 1 is at another URL (B), both may need version
1 of signon to be used. In that case, <MSGSETCORE> inside <BANKMSGSETV1> would refer to
<URL>A and <MSGSETCORE> inside <BILLPAYMSGSETV1> would refer to <URL>B, but
<MSGSETCORE> inside <SIGNONMSGSETV1>may refer to either URL or to some other. As
mentioned in Section 2.5.4, the <URL> included in <SIGNONMSGSETV1> does not restrict where the
<SIGNONMSGSRQV1> wrapper may be sent.
Note: Signon messages can be sent with all other message sets even if the
<SIGNONMSGSET> contains incompatible settings for the URL, security level, or signon
realm. The message set information for signon messages is used only if the signon message is
sent by itself. Otherwise, the settings are inherited from the accompanying service message set.
The same message set may be supported by multiple servers. In this case, each server that supports a
particular message set must have a unique URL.
Note: Since elements cannot be set to a blank value, <USERID> and/or <USERPASS> may
be set to lower case “anonymous” followed by 23 zeroes.
Once the user has enrolled and received his or her user ID and password, the client must request the profile
again, even if the profile is not yet out-of-date. Once it has received a successful <PROFRS> (with or
without a profile download) while signed on as the user, the client must not log in anonymously when
sending any later <PROFRQ> to this server.
At this point, the server can respond with a profile response that indicates that the profile is up-to-date or
return a new FI profile in response. If the FI wants to return a customer-specific profile, the FI must use the
second approach. Servers must handle <PROFRQ> without an error whether or not a request arrives with
an anonymous <SONRQ>.
Note: OFX 1.0.2 business rules violate these restrictions, which were added in later versions.
Clients interacting with 2.2 servers based on 1.0.2 business rules should gracefully handle
<PROFRS> errors in their first per-user attempt, reverting to anonymous requests for
subsequent requests (until the next response with <STATUS><CODE>0, when they should
once again make a per-user attempt to retrieve the profile). Servers interacting with 2.2 clients
based on 1.0.2 business rules should not require support for customer-specific profiles. Servers
Tag Description
<PROFRQ> Profile-request aggregate
<CLIENTROUTING> Identifies client routing capabilities, see table below
<DTPROFUP> Date and time client last received a profile update, datetime
</PROFRQ>
Tag Description
NONE Client cannot perform any routing. All URLs must be the same. All message sets share a
single signon realm.
SERVICE Client can perform limited routing. See details below.
MSGSET Client can route at the message-set level. Each message set can have a different URL and/
or signon realm.
The SERVICE option supports clients that can route bill payment messages to a separate URL from the
rest of the messages. Because the exact mapping of message sets to the general concept of bill payment can
vary by client and by locale, this specification does not provide precise rules for the SERVICE option.
Each client will define its requirements.
If the client has the latest version of the FIs profile, the server returns status code 1 in the <STATUS>
aggregate of the profile-transaction aggregate <PROFTRNRS>. The server does not return a profile-
response aggregate <PROFRS>.
Note: Not sending a response aggregate in this case is an exception to rules outlined in
sections 2.4.6 and 3.1.5.
If the client does not have the latest version of the FI profile, the server responds with the profile-response
aggregate <PROFRS> in the profile-transaction aggregate <PROFTRNRS>. The response includes
message set descriptions, signon information, and general contact information.
Tag Description
<PROFRS> Profile-response aggregate
<MSGSETLIST> Beginning list of message set information
<xxxMSGSET> One or more message set aggregates
</xxxMSGSET>
</MSGSETLIST>
</SIGNONINFOLIST>
Tag Description
<xxxMSGSET> Service aggregate
<xxxMSGSETVn> Version-of-message-set aggregate, <xxxMSGSETV1> is required. As mentioned in
Sections 14.7.2 and 14.7.3, <PRESDIRMSGSETV1> and <PRESDLVMSGSETV1>
may appear one or more times.
</xxxMSGSETVn>
</xxxMSGSET>
Tag Description
<xxxMSGSETVn> Message-set-version aggregate
<MSGSETCORE> Common message set information aggregate.
</MSGSETCORE>
Message-set Zero or more attributes specific to this version of this message set, as defined by each
specific message set
</xxxMSGSETVn>
Tag Description
<MSGSETCORE> Common-message-set-information aggregate
<VER> Version number of the message set, (for example, <VER>1 for version 1 of the
message set), N-5
Because this information is already provided by the surrounding <xxxMSGSETVn>
wrapper, <VER> should be ignored by OFX clients. Nonetheless, servers should use
the supported value (<VER>1) consistent with that wrapper.
<URL> URL where messages in this set are to be sent, URL
<OFXSEC> Security level required for this message set; see Chapter 4, "OFX Security." NONE or
TYPE 1.
<TRANSPSEC> Y if transport-level security must be used, N if not used; see Chapter 4, "OFX
Security." Boolean
<SIGNONREALM> Signon realm to use with this message set, A-32
<LANGUAGE> 1 or more.
Language supported, language.
If more than one language is supported, multiple <LANGUAGE> elements can be
sent.
<SYNCMODE> FULL for full synchronization capability
LITE for lite synchronization capability
See Chapter 6, "Data Synchronization," for more information.
<REFRESHSUPT> Y if server supports <REFRESH>Y within synchronizations. This option is irrelevant
for full synchronization servers. Clients must ignore <REFRESHSUPT> (or its
absence) if the profile also specifies <SYNCMODE>FULL. For lite synchronization,
the default is N. Without <REFRESHSUPT>Y, lite synchronization servers are not
required to support <REFRESH>Y requests, Boolean
<RESPFILEER> Y if server supports file-based error recovery, Boolean
See Chapter 6, "Data Synchronization," for more information.
<SPNAME> Service provider name, A-32
Some financial institutions out-source their OFX servers to a service provider. In such
cases, the SPNAME element should be included in the MSGSETCORE.
<OFXEXTENSION> OFX Extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</MSGSETCORE>
Note: For all message sets currently defined in OFX, <TRANSPSEC>Y must be specified.
Note: Within a message set, there can be more than one <MSGSETCORE> aggregate with the
same value for <VER>, or the same value for <URL>, but not the same value for both. The pair
must be unique for each instance of <MSGSETCORE> within a message set. Multiple
<MSGSETCORE>s with the same value for <VER> are used in instances such as signon or
registration, which may have the same version sent to multiple URLs for different services.
Tag Description
<SIGNONINFO> Signon-information aggregate
<SIGNONREALM> Identifies this realm, A-32
<MIN> Minimum number of password characters, N-2
<MAX> Maximum number of password characters, N-2
<CHARTYPE> Type of characters allowed in password:
ALPHAONLY Password may not contain
numeric characters. The server
would allow “abbc”, but not
“1223” or “a122”.
NUMERICONLY Password may not contain
alphabetic characters. The server
would allow “1223”, but not
“abbc” or “a122”.
ALPHAORNUMERIC Password may contain alphabetic
or numeric characters (or both).
The server would allow “abbc”,
“1223”, or “a122”.
ALPHAANDNUMERIC Password must contain both
alphabetic and numeric
characters. The server would
allow “a122”, but not “abbc” or
“1223”.
<CASESEN> Y if password is case-sensitive, Boolean
Value Meaning
0 Success (INFO)
1 Client is up-to-date (INFO)
2000 General error (ERROR)
Tag Description
<PROFMSGSET> Message-set-profile-information aggregate
<PROFMSGSETV1> Opening tag for V1 of the message set profile information
<MSGSETCORE> Common message set information
</MSGSETCORE>
</PROFMSGSETV1>
</PROFMSGSET>
8.1 Overview
The Signup message set defines three messages to help users get setup with their FI:
• Enrollment – informs FI that a user wants to use OFX and requests that a password be returned
• Accounts – asks the FI to return a list of accounts and the services supported for each account
• Activation – allows a client to tell the FI which services a user wants on each account
Clients use the account information request on a regular basis to look for changes in a user’s account
information. A time stamp is part of the request so that a server has to report only new changes. Account
activation requests are subject to data synchronization, and will allow multiple clients to learn how the
other clients have been enabled.
In OFX request files, the <SIGNUPMSGSRQV1> aggregate identifies the Signup messages.
Checking 2 should be available to either spouse, and the spouse holding Checking 1 should be able to see
both Checking 1 and 2.
OFX expects FIs to give each user their own user ID and password. Each user will go through the
enrollment step separately. A given account need only be activated once for a service; not once for each
user. Clients will use the account information and activation messages to combine information about
jointly held accounts.
If an FI prefers to have a single user ID and password per household or per master account, it will have to
make this clear to users through the enrollment process. It is up to the FI to assign a single user ID and
password that can access all three of the checking accounts described above.
Note: The client may not know the user ID and password when it sends the enrollment
request, in such a case the <USERID> and/or <USERPASS> may be set to lower case
“anonymous” followed by 23 zeroes.
Enrollment requests are not subject to synchronization. If the client does not receive a response, it will
simply re-request the enrollment. If a user successfully enrolls from another client before the first client
obtains a response, the server should respond to subsequent requests from the first client with status code:
UserIDs are assigned in various ways. Some FIs have existing user IDs that they use for other online
activities that they want to use for OFX as well. Others might create new IDs specifically for OFX. Finally,
some FIs might assign IDs while others might allow users to create them. To ensure security and help prevent
identity fraud, Financial Institutions are discouraged from using Social Security Number for Customer ID or PIN/
Password.
Because users do not usually know either their OFX sign-on user ID or their password at time of
enrollment, the enrollment response is designed to return both. The enrollment request allows users to
optionally provide a user ID, which an FI can interpret as their existing online ID or a suggestion for what
their new user ID should be. Ideally, the enrollment process should explain ID syntax to users.
FIs might require that an account number be entered as part of the identification process. However, this is
discouraged since the account information request is designed to automatically obtain all account
information, avoiding the effort and potential mistakes of a user-supplied account number.
It is RECOMMENDED that FIs provide detailed specifications for user IDs and passwords along with
information about the services available when a user is choosing an FI.
Tag Description
<ENROLLRQ> Enrollment-request aggregate
<FIRSTNAME> First name of user, A-32
<MIDDLENAME> Middle name of user, A-32
<LASTNAME> Last name of user, A-32
<ADDR1> Address line 1, A-32
<ADDR2> Address line 2, A-32
<ADDR3> Address line 3. Use of <ADDR3> requires the presence of <ADDR2>, A-32
<CITY> City, A-32
<STATE> State or province, A-5
<POSTALCODE> Postal code, A-11
<COUNTRY> 3-letter country code from ISO/DIS-3166, A-3
<DAYPHONE> Daytime telephone number, A-32
<EVEPHONE> Evening telephone number, A-32
<EMAIL> Electronic e-mail address, A-80
<USERID> Actual user ID if already known, or preferred user ID if user can choose, A-32
<TAXID> ID used for tax purposes (such as SSN), may be same as user ID, A-32
<SECURITYNAME> Mother’s maiden name or equivalent, A-32
<DATEBIRTH> Date of birth, date
<xxxACCTFROM> An account description aggregate for an existing account at the FI, for
identification purposes only. For example, <BANKACCTFROM> or
<INVACCTFROM>.
</xxxACCTFROM>
</ENROLLRQ>
This enrollment request is intended for use only by individuals. Business enrollment will be defined in a
later release.
Tag Description
<ENROLLRS> Enrollment-response aggregate
<TEMPPASS> Temporary password, A-32
<USERID> User ID, A-32
<DTEXPIRE> Time the temporary password expires (if <TEMPPASS> included), datetime
</ENROLLRS>
Code Meaning
0 Success (INFO)
<ENROLLTRNRQ>
<TRNUID>12345</TRNUID>
<ENROLLRQ>
<FIRSTNAME>Joe</FIRSTNAME>
<MIDDLENAME>Lee</MIDDLENAME>
<LASTNAME>Smith</LASTNAME>
<ADDR1>21 Main St.</ADDR1>
<CITY>Anytown</CITY>
<STATE>TX</STATE>
<POSTALCODE>87321</POSTALCODE>
<COUNTRY>USA</COUNTRY>
<DAYPHONE>123-456-7890</DAYPHONE>
<EVEPHONE>987-654-3210</EVEPHONE>
<EMAIL>[email protected]</EMAIL>
<USERID>jls</USERID>
<TAXID>123-456-1234</TAXID>
<SECURITYNAME>jbmam</SECURITYNAME>
<DATEBIRTH>19530202</DATEBIRTH>
</ENROLLRQ>
</ENROLLTRNRQ>
<ENROLLTRNRS>
<TRNUID>12345</TRUNID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<ENROLLRS>
<TEMPPASS>changeme</TEMPPASS>
<USERID>jls</USERID>
<DTEXPIRE>20060305</DTEXPIRE
</ENROLLRS>
</ENROLLTRNRS>
Some service providers do not have prior knowledge of user account information. The profile allows these
servers to report this, and clients then know to ask users for account information rather than reading it from
the server.
Clients can perform several tasks for users with this account information. First, the information helps a
client set up a user for online services by giving it a precise list of its account information and available
services for each. Clients can set up their own internal state as well as prepare service activation requests
with no further typing by users. This can eliminate data entry mistakes in account numbers, routing transit
numbers, and so forth.
Second, FIs can provide limited information on accounts that would not ordinarily be suitable to OFX
services. For example, a balance-only statement download would be useful for certificates of deposits even
though a customer or an FI might not want or allow CDs to be used for full statement download.
For each account, there is one <ACCTINFO> aggregate returned. The aggregate includes one service-
specific account information aggregate for each service available to that account. That, in turn, provides
the service-specific account identification. Common to each service-specific account information
aggregate is the <SVCSTATUS> element, which indicates the status of this service on this account.
A server should return joint accounts (accounts for which more than one user ID can be used to access the
account) for either user.
Requests and responses include a <DTACCTUP> element. Responses contain the last time a server
updated the information. If a user sets up all available accounts returned in an <ACCTINFORS>, clients
are REQUIRED to send the most recent <DTACCTUP> in a subsequent request, and servers are
REQUIRED to compare this to the current modification time and only send information if it is more
recent. If a user does not set up all available accounts returned in an <ACCTINFORS>, it is permissable
for a client to send the old <DTACCTUP> in order to receive active account information that may have
already been returned. Note that this account information may be different than what was returned
previously if some accounts have been added or removed from the active list since the last response. The
server sends the entire account information response if the client’s time is older; there is no attempt to
incrementally update specific account information. <ACCTINFORS> should not be sent when the client is
up-to-date.
Note: Not sending a response aggregate in the case of <ACCTINFORS> is an exception to the
rules outlined in 2.4.6 and 3.1.5.
OFX 2.2 introduces changes which clients and servers that support OFX 2.2 can use to improve account
number security and ensure clients receive user-friendly information about their accounts.
The <NAME> element has been added as an optional tag in the <ACCTINFO> response. When it is
present it indicates several things:
• A server MAY be obfuscating account numbers. This could range from a simple mask to a tokenization
or reference ID approach
• OFX 2.2 clients ARE REQUIRED, when <NAME> is present in the <ACCTINFO> response, to
display it to the user instead of the account number
• OFX 2.2 servers ARE REQUIRED to be able to properly identify user accounts for financial
operations using whatever value they returned to the client in the <ACCTINFO> response
<xxxACCTID> tags irrespective of any obfuscation scheme they implement
For example, a server may choose to completely replace account numbers in the OFX channel with some
type of reference ID and they signal the client this some type of obfuscation is occurring by returning
<NAME> elements in the <ACCTINFO> aggregates. A user who has 2 checking accounts at that
institution may receive <ACCTINFO> aggregates containing <ACCTID>1 for the first account, and
<ACCTID>2 for the second account. The client, per normal OFX rules, will send these values in
transaction requests for those accounts; the server must be able to properly interpret and "resolve"
whatever <ACCTID> value it returned back to the correct account for the user in order to process requests.
Note: <xxxACCTID> values are considered critical ID fields. Moving to a new obfuscation
model or changing <xxxACCTID> values could have significant impacts on client software
that has previously connected to the OFX Server. Financial Institutions should coordinate with
appropriate client software companies out-of-band when changing any critical ID fields.
Note: Servers that support shared account access via OFX (the same account under 2 or more
user credentials/accounts) *MUST* ensure that any obfuscation methodology they use results
in the same account having the same <xxxACCTID> for all users to avoid issues within client
software.
Tag Description
<ACCTINFORQ> Account-information-request aggregate
<DTACCTUP> Last <DTACCTUP> received in a response, datetime
</ACCTINFORQ>
Tag Description
<ACCTINFORS> Account-information-response aggregate
<DTACCTUP> Date and time of last update to this information on the server, datetime
<ACCTINFO> Zero or more account information aggregates
Left out of the response when nothing is found for the current user.
Tag Description
<ACCTINFO> Account-information-record aggregate
<NAME> Name/User defined nickname for the account, A-32. If present indicates
the server may be obfuscating account numbers per Section 8.5.1.
<DESC> Description of the account, A-80
<PHONE> Telephone number for the account, A-32. Deprecated if present in
<CONTACTPROF> or <CONTACTPROFENC>
<HOLDERINFO> Deprecated in OFX 2.2.1
<PRIMARYHOLDER> Primary account holder information opening tag; see Section 8.5.4.1.
</PRIMARYHOLDER>
</HOLDERINFO>
<OTHERACCTINFO> Service-specific account identifiers available for use in out of band (non-
OFX) real-world transaction systems; see Section 8.5.4.4
</OTHERACCTINFO>
</ACCTINFO>
Tag Description
<xxxHOLDER> Account holder information aggregate (<PRIMARYHOLDER> or
<SECONDARYHOLDER>
<FIRSTNAME> First name of user, A-32
<MIDDLENAME> Middle name of user, A-32
<LASTNAME> Last name of user, A-32
<ADDR1> Address line 1, A-32
<ADDR2> Address line 2, A-32
<ADDR3> Address line 3. Use of <ADDR3> requires the presence of <ADDR2>, A-
32
<CITY> City, A-32
<STATE> State or province, A-5
<POSTALCODE> Postal code, A-11
<COUNTRY> 3-letter country code from ISO/DIS-3166, A-3
<DAYPHONE> Daytime telephone number, A-32
<EVEPHONE> Evening telephone number, A-32
<EMAIL> Electronic e-mail address, A-80
<HOLDERTYPE> Type of account holder; see section 8.5.4.2
</xxxHOLDER>
Type Description
Tag Description
<CONTACTPROF> Unencrypted content
...or...
<CONTACTPROFENC>
Encrypted content
<ENCRYPTION> 10k encryption key. May only be present in <CONTACTPROFENC>. The
<ENCRYPTION> tag contains whatever agreed-upon information is
necessary for receiving parties to decrypt the encrypted tags. If no data is
necessary due to other out-of-band conventions or agreements, this tag can
be omitted.
<CONTACTNAMES> If present in <USERINFORS>, once only. If present in <ACCTINFO>, 1
or more
<CONTACTNAME> See Section 8.5.4.3.1; 1 or more required.
</CONTACTNAMES>
Tag Description
<CONTACTNAME>
Either:
OTHERACCTINFO supports the concept of “Virtual Account Numbers”. In essence these are another
obfuscated value for the real account number BUT they can actually be used in the ACH network and be
used to transfer/transact. The purpose is to prevent the real account number from ever being exposed and if
a virtual account number is ever compromised, it can easily be regenerated by the partner. Another use, for
example, is where an investment account has some behind-the-scenes (to OFX) bank-level account used
for moving money in to or out of that investment account. This feature might allow for that 'adjunct' related
bank account identifiers to be provided for these other purposes (ACH) when the account identifiers in
INVACCTFROM are entirely of a different class (very unlike bank-related ACH ids).
Tag Description
<OTHERACCTINFO>
Code Meaning
0 Success (INFO)
<ACCTINFOTRNRQ>
<TRNUID>12345</TRNUID>
<ACCTINFORQ>
<DTACCTUP>20050101</DTACCTUP>
</ACCTINFORQ>
</ACCTINFOTRNRQ>
And a response for a user with access to one account, supporting banking:
<ACCTINFOTRNRS>
<TRNUID>12345</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<ACCTINFORS>
<DTACCTUP>20050301</DTACCTUP>
<ACCTINFO>
<DESC>Power Checking</DESC>
<PHONE>8002223333</PHONE>
<BANKACCTINFO>
<BANKACCTFROM>
<BANKID>123456789</BANKID>
<ACCTID>00001234</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<SUPTXDL>Y</SUPTXDL>
<XFERSRC>Y</XFERSRC>
<XFERDEST>Y</XFERDEST>
<SVCSTATUS>ACTIVE</SVCSTATUS>
</BANKACCTINFO>
</ACCTINFO>
</ACCTINFORS>
</ACCTINFOTRNRS>
<ACCTINFOTRNRQ>
<TRNUID>12345</TRNUID>
<ACCTINFORQ>
<DTACCTUP>20050101</DTACCTUP>
</ACCTINFORQ>
</ACCTINFOTRNRQ>
And a response for a user with access to one account, supporting banking:
<ACCTINFOTRNRS>
<TRNUID>12345</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<ACCTINFORS>
<DTACCTUP>20050301</DTACCTUP>
<ACCTINFO>
<NAME>Main Account</NAME> // Account nickname set by user
<DESC>Power Checking</DESC>
<PHONE>8002223333</PHONE>
<BANKACCTINFO>
<BANKACCTFROM>
<BANKID>123456789</BANKID>
<ACCTID>1</ACCTID> // Server reference ID
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<SUPTXDL>Y</SUPTXDL>
<XFERSRC>Y</XFERSRC>
<XFERDEST>Y</XFERDEST>
<SVCSTATUS>ACTIVE</SVCSTATUS>
</BANKACCTINFO>
</ACCTINFO>
</ACCTINFORS>
</ACCTINFOTRNRS>
Clients use these records during the initial user sign-up process. Once a client learns about the available
accounts and services (by using the account information request above, or by having a user directly enter
the required information), it sends a series of service ADD requests.
If a user changes any of the identifying information about an account, the client sends a service activation
request containing both the old and the new account information. Servers should interpret this as a change
in the account, not a request to transfer the service between two existing accounts, and all account-based
information such as synchronization tokens should continue. If a user or FI is reporting that a service
should be moved between two existing accounts, service must be terminated for the old account and
started for the new account. The new account will have reset token histories, as with any new service.
Each service to be added, changed, or removed is contained in its own request because the same real-world
account might require different <xxxACCTFROM> aggregates depending on the type of service.
Tag Description
<ACCTRQ> Account-service-request aggregate
When a client sends a <SVCADD> to a financial institution routing particular messages to another service
provider, it is up to the financial institution to determine whether or not an <ENROLLRQ> needs to be sent
to the service provider along with the <SVCADD>. The FI may choose to always send an <ENROLLRQ>
and ignore the 13550 error message responses, though this would only be reliable if <xxxACCTFROM> is
included in the <ENROLLRQ>. The FI may also choose to keep a database of enrolled services, so as to
send an <ENROLLRQ> only when the client is sending a <SVCADD> for a new service. The FI also has
the option of sending <ENROLLRQ>s to all service providers when the client sends the initial
<ENROLLRQ> to the FI.
Tag Description
<SVCADD> Service-addition aggregate
<xxxACCTTO> Service-specific-account-identification aggregate (for example,
<BANKACCTTO> or <INVACCTTO>)
</xxxACCTTO>
</SVCADD>
Tag Description
<SVCCHG> Service-change aggregate
<xxxACCTFROM> Service-specific-account-identification aggregate (for example,
<BANKACCTFROM> or <INVACCTFROM>)
</xxxACCTFROM>
</SVCCHG>
Tag Description
<SVCDEL> Service-deletion aggregate
</SVCDEL>
Tag Description
<ACCTRS> Account-service-response aggregate
Code Meaning
0 Success (INFO)
Tag Description
<ACCTSYNCRQ> Activation synchronization request aggregate
Client synchronization
option; <TOKEN>,
<TOKENONLY>, or
<REFRESH>
<TOKEN> Previous value of <TOKEN> received for this type of synchronization request
from server; 0 for first-time requests; token
<TOKENONLY> Request for just the current <TOKEN> without the history, Boolean
<REFRESH> Request for refresh of current state, Boolean
<REJECTIFMISSING> If Y, do not process requests if client <TOKEN> is out of date, Boolean
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</ACCTSYNCRQ>
Tag Description
<ACCTSYNCRS> Payee-list-request aggregate
<TOKEN> New synchronization token, token
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
<ACCTTRNRQ>
<TRNUID>12345</TRNUID>
<ACCTRQ>
<SVCADD>
<BANKACCTTO>
<BANKID>123456789</BANKID>
<ACCTID>12345</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTTO>
</SVCADD>
<SVC>BPSVC
</ACCTRQ>
</ACCTTRNRQ>
A response:
<ACCTTRNRS>
<TRNUID>12345</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<ACCTRS>
<SVCADD>
<BANKACCTTO>
<BANKID>123456789</BANKID>
<ACCTID>12345</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTTO>
</SVCADD>
<SVC>BPSVC</SVC>
<SVCSTATUS>ACTIVE</SVCSTATUS>
</ACCTRS>
</ACCTTRNRS>
Tag Description
<CHGUSERINFORQ> Change-user-information-request aggregate
<FIRSTNAME> First name of user, A-32
<MIDDLENAME> Middle name of user, A-32
<LASTNAME> Last name of user, A-32
<ADDR1> Address line 1, A-32
<ADDR2> Address line 2. Use of <ADDR2> requires the presence of <ADDR1>, A-32
<ADDR3> Address line 3. Use of <ADDR3> requires the presence of <ADDR2>, A-32
<CITY> City, A-32
<STATE> State or province, A-5
<POSTALCODE> Postal code, A-11
<COUNTRY> 3-letter country code from ISO/DIS-3166, A-3
<DAYPHONE> Daytime telephone number, A-32
<EVEPHONE> Evening telephone number, A-32
<EMAIL> Electronic e-mail address, A-80
</CHGUSERINFORQ>
Tag Description
<CHGUSERINFORS> Change-user-information-request aggregate
<FIRSTNAME> First name of user, A-32
<MIDDLENAME> Middle name of user, A-32
<LASTNAME> Last name of user, A-32
<ADDR1> Address line 1, A-32
<ADDR2> Address line 2. Use of <ADDR2> requires the presence of <ADDR1>, A-32
<ADDR3> Address line 3. Use of <ADDR3> requires the presence of <ADDR2>, A-32
<CITY> City, A-32
<STATE> State or province, A-5
<POSTALCODE> Postal code, A-11
<COUNTRY> 3=letter country code from ISO/DIS-3166, A-3
<DAYPHONE> Daytime telephone number, A-32
<EVEPHONE> Evening telephone number, A-32
<EMAIL> Electronic e-mail address, A-80
<DTINFOCHG> Date and time of update datetime
</CHGUSERINFORS>
Code Meaning
0 Success (INFO)
Tag Description
<CHGUSERINFOSYNCRQ> Activation synchronization request aggregate
</CHGUSERINFOSYNCRQ>
Tag Description
<CHGUSERINFOSYNCRS> Payee-list-request aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry
in the server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a
token in the server’s history table. Boolean
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</CHGUSERINFOSYNCRS>
Tag Description
<USERINFORQ>
Tag Description
<USERINFORS>
<CONTACTPROFENC>
Encrypted content
</USERINFORS>
The server can return <CODE>1 in the STATUS aggregate if the client is up-to-date.
Code Meaning
0 Success (INFO)
1 Client up to date
13506 Cannot get user information (server does not support USERINFORQ/S)
15508 Transaction not authorized (user did not grant access to this information)
Tag Description
<SIGNUPMSGSET> Signup-message-set-profile-information aggregate
<SIGNUPMSGSETV1> Opening tag for V1 of the message set profile information
<MSGSETCORE> Common message set information, defined in Chapter 7, "FI Profile"
</MSGSETCORE>
The model creates each transaction some time before its due date, usually thirty days. This allows the user
to retrieve the transactions in advance of posting. This also gives the user the opportunity to modify or
cancel individual transactions without changing the recurring model itself.
When a model is created, it can generate several transactions immediately. The model does not
automatically return responses for the newly created transactions. It returns a response only to the request
that was made to create the model. For this reason, clients should send a synchronization request along
with the request to create a model. This allows the server to return the newly created transaction responses,
as well as the response to the request to set up a new model.
Tag Description
<RECURRINST> Recurring-Instructions aggregate
<NINSTS> Number of instructions
If this element is absent, the schedule is open-ended, N-3
<FREQ> Frequency, see section 9.2.1
</RECURRINST>
Value Description
WEEKLY Weekly
BIWEEKLY Biweekly
MONTHLY Monthly
BIMONTHLY Bimonthly
QUARTERLY Quarterly
SEMIANNUALLY Semiannually
ANNUALLY Annually
Rules for calculating recurring dates of WEEKLY, BIWEEKLY, and TWICEMONTHLY are as follows:
• WEEKLY = starting date for first transaction, starting date + 7 days for the second
• TWICEMONTHLY = starting date for first, starting date + 15 days for the second
• BIWEEKLY = starting date for first, starting date + 14 days for the second
Note that servers are free to adjust the payment date of a spawned payment to accommodate weekends and
holidays. For instance, if August 1 falls on a Saturday, a MONTHLY model generating payments on the
1st of each month might change the due date of its August 1 payment to July 31.
9.2.2 Examples
The following example illustrates the creation of a repeating payment. The payment repeats on a monthly
basis for 12 months. All payments are for $395.
The request:
.
.
.
<RECPMTRQ>
<RECURRINST>
<NINSTS>12</NINSTS>
<FREQ>MONTHLY</FREQ>
</RECURRINST>
<PMTINFO>
<BANKACCTFROM>
<BANKID>555432180</BANKID>
<ACCTID>763984</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<TRNAMT>395.00</TRNAMT>
<PAYEEID>77810</PAYEEID>
<PAYACCT>444-78-97572</PAYACCT>
<DTDUE>20051115</DTDUE>
<MEMO>Auto loan payment</MEMO>
</PMTINFO>
</RECPMTRQ>
.
.
.
.
.
.
<RECPMTRS>
<RECSRVRTID>387687138</RECSRVRTID>
<RECURRINST>
<NINSTS>12</NINSTS>
<FREQ>MONTHLY</FREQ>
</RECURRINST>
<PMTINFO>
<BANKACCTFROM>
<BANKID>555432180</BANKID>
<ACCTID>763984</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<TRNAMT>395.00</TRNAMT>
<PAYEEID>77810</PAYEEID>
<PAYACCT>444-78-97572</PAYACCT>
<DTDUE>20051115</DTDUE>
<MEMO>Auto loan payment</MEMO>
</PMTINFO>
</RECPMTRS>
.
.
.
The client has two purposes for synchronizing state with the server with respect to recurring models:
• Retrieve any added, modified, or canceled recurring models
• Retrieve any added, modified, or canceled transactions generated by any models
The client must be able to synchronize with the state of any models at the server, as well as the state of any
transactions generated by the server.
A recurring payments refresh should cause the current, not original, state of the model to be sent. The
remaining number of instances (<NINSTS>) and the date due (<DTDUE>) of the next payment to be
spawned should be returned. This assures that another client who may not know about payment history
relevant to the state of the model (such as payment cancellations) can know the current state of the model.
If a client indicates that the modification or cancellation of a model should also affect its pending
transactions, those individual modifications/cancellations must appear in the appropriate synchronization
response the next time a synchronization request is made. For example, a recurring payment cancellation
request that affects pending payments should cause payment cancellation responses to show up in the
payment synchronization response for all pending payments belonging to the model.
9.5.1 Examples
Canceling a recurring payment model requires the client to pass the <RECSRVRTID> of the model. The
client requests that pending payments also be canceled. The server cancels the model immediately and
notifies the client that the model was canceled.
The request:
.
.
.
<RECPMTCANCRQ>
<RECSRVRTID>387687138</RECSRVRTID>
<CANPENDING>Y</CANPENDING>
</RECPMTCANCRQ>
.
.
.
The response:
.
.
.
<RECPMTCANCRS>
<RECSRVRTID>387687138</RECSRVRTID>
<CANPENDING>Y</CANPENDING>
</RECPMTCANCRS>
.
.
The server also cancels any payments that have been generated but not executed. In the example shown
above, the client would not learn of this immediately. To receive notification that all pending payments
were canceled, the client would need to send a synchronization request in the file. The following example
illustrates this.
.
.
.
<PMTSYNCRQ>
<TOKEN>12345</TOKEN>
<REJECTIFMISSING>N</REJECTIFMISSING>
<BANKACCTFROM>
<BANKID>123432123</BANKID>
<ACCTID>516273</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
</PMTSYNCRQ>
.
.
.
The response file contains one response (assuming one payment was pending).
.
.
.
<PMTSYNCRS>
<TOKEN>123456</TOKEN>
<BANKACCTFROM>
<BANKID>123432123</BANKID>
<ACCTID>516273</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<PMTTRNRS>
<TRNUID>0</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<PMTCANCRS>
<SRVRTID>1030155</SRVRTID>
</PMTCANCRS>
</PMTTRNRS>
</PMTSYNCRS>
.
.
Models should show up in synchronization responses even after they have expired (at least for a time),
since the RECSRVRTID will be in payment synchronization responses and a client needs to find the
corresponding model. Servers may safely remove this information shortly after the final payment or
transfer has posted to the source account.
A user or an FI can originate a message. E-mail messages are subject to data synchronization so that a
server can send a response again if it is lost or if multiple clients use it.
Because e-mail messages cannot be replied to immediately, the response should just echo back the original
message (so that data synchronization will get this original e-mail message to other clients). When the FI is
ready to reply, it should generate an unsolicited response (<TRNUID>0) and the client will pick this up
during synchronization.
Account information
From, To
Subject
Message
Account information
From, To
Subject
Message
Type
When users want to send messages about service-specific problems, service-specific messages are best.
However, when service-specific mail transactions are not available, general mail is acceptable.
Tag Description
<MAIL> Core e-mail aggregate
<USERID> User identification, A-32
<DTCREATED> When message was created, datetime
<FROM> Who the message is from, A-32
<TO> Who the message should be delivered to, A-32
<SUBJECT> Subject of message (plain text, not HTML), A-60
<MSGBODY> Body of message, HTML-encoded or plain text depending on <USEHTML>,
HTML-encoded text - A-10000
Plain text - A-2000
<INCIMAGES> Include images in the message body. Boolean
<USEHTML> Y for HTML-formatted text. N for plain text. See section 10.2.2.2 for more information.
Boolean
</MAIL>
The meaning of the <INCIMAGES> element depends on whether the element appears in a request or
response.
When used in a request, <INCIMAGES> indicates whether the client accepts mail that includes images in
the message body.
When used in a response, <INCIMAGES> indicates whether the server included images in the message
body.
10.2.2.2 <USEHTML>
The meaning of the <USEHTML> element depends on whether the element appears in a request or
response.
When used in a request, <USEHTML> indicates whether the client sends and accepts HTML-formatted
text in the message body. If a server receives a <xxxMAILSYNCRQ> request with <USEHTML>Y set,
the server should process the request whether or not it supports HTML mail. If a server does not support
HTML mail, it should simply set the <USEHTML> flag to N in any transactions which are returned in the
sync response.
Note: When using HTML for the message body, clients and servers are REQUIRED to
enclose the HTML in a CDATA section to protect the HTML markup: <![CDATA[ ... html ...
]]>. For an example, see section 10.2.5.
Tag Description
<MAILRQ> E-mail-message-request aggregate
<MAIL> Core e-mail aggregate
</MAIL>
</MAILRQ>
In a response, the <TRNUID> is zero if this is an unsolicited message or an out-of-band reply to a prior
email request. Immediate responses (acknowledgments) to a request should contain the <TRNUID> of the
user’s original message. It is RECOMMENDED that servers include the <MESSAGE> of the user’s
message as part of the reply <MESSAGE>. The <MESSAGE> contents can include carriage returns to
identify desired line breaks.
Tag Description
<MAILRS> E-mail-message-response aggregate
<MAIL> Core e-mail aggregate
</MAIL>
</MAILRS>
Code Meaning
0 Success (INFO)
Note that this synchronization action expects only the basic <MAILRS> responses. Specialized e-mail is
received by means of their own synchronization requests.
Tag Description
<MAILSYNCRQ> E-mail-synchronization-request aggregate
Client synchronization
option; <TOKEN>,
<TOKENONLY>, or
<REFRESH>
<TOKEN> Previous value of <TOKEN> received for this type of synchronization request
from server; 0 for first-time requests; token
<TOKENONLY> Request for just the current <TOKEN> without the history, Boolean
<REFRESH> Request for refresh of current state, Boolean
<REJECTIFMISSING> If Y, do not process requests if client <TOKEN> is out of date, Boolean
<INCIMAGES> Y if the client accepts mail with images in the message body, N if the client does
not accept mail with images in the message body, Boolean
<USEHTML> Y if client wants an HTML response, N if client wants plain text, Boolean
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</MAILSYNCRQ>
</MAILSYNCRS>
The client receives the real response at a later time following a mail synchronization request. For an
example of the mail synchronization request and response, see section 10.2.5.1.
Note: This example omits the <OFX> top level and the signon <SONRQ>. Since this example
uses HTML for the message body, it must protect the HTML content in an CDATA-marked
section.
The request:
<MAILTRNRQ>
<TRNUID>54321</TRNUID>
<MAILRQ>
<MAIL>
<USERID>123456789</USERID>
<FROM>James Hackleman</FROM>
<TO>Noelani Federal Savings</TO>
<SUBJECT>What do I need to earn interest?</SUBJECT>
<DTCREATED>20050305</DTCREATED>
<MSGBODY><![CDATA[<HTML><BODY>I didn’t earn any interest this
month. Can you please tell me what I need to do to earn interest on this
account?</BODY></HTML>
]]></MSGBODY>
<MAILTRNRS>
<TRNUID>54321</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<MAILRS>
<MAIL>
<USERID>123456789</USERID>
<FROM>James Hackleman</FROM>
<TO>Noelani Federal Savings</TO>
<SUBJECT>What do I need to earn interest?</SUBJECT>
<DTCREATED>20050305</DTCREATED>
<MSGBODY><![CDATA[<HTML><BODY>I didn’t earn any interest this
month. Can you please tell me what I need to do to earn interest on this
account?</BODY></HTML>]]></MSGBODY>
<INCIMAGES>N</INCIMAGES>
<USEHTML>Y</USEHTML>
</MAIL>
</MAILRS>
</MAILTRNRS>
In the following example, the client has not yet received the reply to the e-mail sent in the previous
example, so its <TOKEN> is one less than the server’s. The server replies by giving the current
<TOKEN> and the missed response.
<MAILSYNCRQ>
<TOKEN>101</TOKEN>
<REJECTIFMISSING>N</REJECTIFMISSING>
<INCIMAGES>N</INCIMAGES>
<USEHTML>Y</USEHTML>
</MAILSYNCRQ>
<MAILSYNCRS>
Original message:
I didn’t earn any interest this month. Can you please tell me what I
need to do to earn interest on this account?</BODY></HTML>]]></MSGBODY>
<INCIMAGES>N</INCIMAGES>
<USEHTML>Y</USEHTML>
</MAIL>
</MAILRS>
</MAILTRNRS>
</MAILSYNCRS>
When a <GETMIMERQ> request appears in a request file and no error occurs in processing, the server
must return a response file containing multiple entities (defined in the MIME protocol to include the
MIME headers and content for one part of the transmission). Such a response file has content type
“multipart/x-mixed-replace”, as discussed in section 2.1. One entity contains the OFX response. Other
entities contain the content of individual retrievals corresponding to each <GETMIMERS> in the OFX
entity.
Tag Description
<GETMIMERQ> Get-MIME-request aggregate
<URL> URL, URL
</GETMIMERQ>
The response simply echoes the URL. The actual response, whether HTML, an image, or some other type,
is always sent as a separate part of the file using multipart MIME.
Tag Description
<GETMIMERS> Get-MIME-response aggregate
<URL> URL, URL
</GETMIMERS>
Code Meaning
0 Success (INFO)
<GETMIMETRNRQ>
<TRNUID>54321</TRNUID>
<GETMIMERQ>
<URL>http://www.fi.com/apage.html</URL>
</GETMIMERQ>
</GETMIMETRNRQ>
A response – the full file is shown here to illustrate the use of multipart MIME:
--XYZZY24x7
Content-Type: application/x-ofx
Content-Length: 8732
<?xml version="1.0"?>
<OFX>
<!-- signon not shown
message set wrappers not shown -->
<GETMIMETRNRS>
<TRNUID>54321</TRNUID>
<STATUS>
<CODE>0</CODE>
--XYZZY24x7
Content-Type: text/html
<HTML>
<!-- standard HTML page -->
</HTML>
--XYZZY24x7--
MAILTRNRQ
MAILRQ
GETMIMETRNRQ
GETMIMERQ
MAILSYNCRQ
</EMAILMSGSRQV1>
MAILTRNRS
MAILRS
GETMIMETRNRS
GETMIMERS
MAILSYNCRS
</EMAILMSGSRSV1>
Tag Description
<EMAILMSGSET> E-mail-message-set-profile-information aggregate
<EMAILMSGSETV1> Opening tag for V1 of the message set profile information
<MSGSETCORE> Common message set information, defined in Chapter 7, "FI Profile"
</MSGSETCORE>
</EMAILMSGSET>
Using customer notification, an FI can notify customers of important events regarding their accounts, such
as returned checks or deposits.
Older OFX servers commonly implemented loans by mapping them into the existing banking download
aggregates via the CREDITLINE account type. While this provided extremely limited, and incomplete,
information about the loan it was the only implementation option prior to OFX 2.1.
In order to reduce the complexity of upgrading an older (pre 2.1) server who implemented loans as
CREDITLINE accounts, OFX 2.2 includes changes to extend this mapping into a limited implementation.
The limited implementation is intended only for existing 1.x or 2.0.x servers that are upgrading to OFX 2.2
or later and that chose to map loan accounts, or at least some set of loan accounts, into the CREDITLINE
account in their original implementation.
Note: The full loan implementation using dedicated request/response aggregates provides
more comprehensive information and capabilities.
Tag Description
<BANKACCTFROM> Bank-account-from aggregate
<BANKID> Bank identifier, A-9
Use of this field by country:
COUNTRY Interpretation
BEL Bank code
CAN Routing and transit number
CHE Clearing number
DEU Bankleitzahl
ESP Entidad
FRA Banque
GBR Sort code
ITA ABI
NLD Not used (field contents ignored)
USA Routing and transit number
<BRANCHID> Branch identifier. May be required for some non-US banks, A-22
Use of this field by country:
COUNTRY Interpretation
BEL Not present
CAN Not present
CHE Not present
DEU Not present
ESP Oficina
FRA Agence
GBR Not present
ITA CAB
NLD Not present
USA Not present
<ACCTID> Account number, A-22
COUNTRY Interpretation
BEL Check digits
CAN Not present
CHE Not present
DEU Not present
ESP D.C.
FRA Clé
GBR Not present
ITA CIN
NLD Not present
USA Not present
</BANKACCTFROM>
COUNTRY Interpretation
BEL Bank code
CAN Routing and transit number
CHE Clearing number
DEU Bankleitzahl
ESP Entidad
FRA Banque
GBR Sort code
ITA ABI
NLD Not used (field contents ignored)
USA Routing and transit number
<BRANCHID> Branch identifier. May be required for some banks, A-22
Use of this field by country:
COUNTRY Interpretation
BEL Not present
CAN Not present
CHE Not present
DEU Not present
ESP Oficina
FRA Agence
GBR Not present
ITA CAB
NLD Not present
USA Not present
<ACCTID> Account number, A-22
<ACCTTYPE> Type of account, see section 11.3.1.1
<ACCTKEY> Checksum, A-22
Use of this field by country:
Type Description
CHECKING Checking
SAVINGS Savings
CD Certificate of Deposit
Tag Description
<CCACCTFROM> Credit-card-account-from aggregate
<ACCTID> Account number, A-22
<ACCTKEY> Checksum for international banks, A-22
</CCACCTFROM>
Tag Description
<BANKACCTINFO> Bank-account-information aggregate
<BANKACCTFROM> Bank-account-from aggregate
</BANKACCTFROM>
Type Description
Tag Description
<CCACCTINFO> Credit-card-account-information aggregate
<CCACCTFROM> Credit-card-account-from aggregate
</CCACCTFROM>
<PARENTACCTID> Parent Account ID. Use “N/A” if parent card’s ACCTID is unknown. A-22
<SUPTXDL> Y if account supports transaction detail downloads, N if it is balance-only,
Boolean
<XFERSRC> Y if account is enabled as a source for an intrabank or interbank transfer, Boolean
<XFERDEST> Y if account is enabled as a destination for an intrabank or interbank transfer,
Boolean
<ACCTCLASSIFICATION> Account classification; see section 11.3.3.1
<SVCSTATUS> Status of the account
AVAIL = Available, but not yet requested
PEND = Requested, but not yet available
ACTIVE = In use
</CCACCTINFO>
The <DTDUE> in a response may have been adjusted by a server. For example, the server may adjust
<DTDUE> to comply with non-processing days. If a client sends a request to make a transfer on July 4 and
July 4 happens to be a non-processing day, the <DTDUE> in the response may be July 4 (because the
server hasn’t adjusted it yet), July 5 (because this server rolls dates forward), or some other date. For this
reason, a client should pay attention to the <DTDUE> in the response.
Account-from options.
Choose either
<BANKACCTFROM> or
<CCACCTFROM> or
<LOANACCTFROM>
<BANKACCTFROM> Bank account-from aggregate, see section 11.3.1
</BANKACCTFROM>
-or-
-or-
-or-
-or-
<DTDUE> Date that the transfer is to be sent. If the client does not specify <DTDUE>, the
transfer occurs as soon as possible. <DTDUE> is required for scheduled or
repeating transfers, datetime
If the server has the breakdown available at the time of the transfer, <XFERINFO> should include the
<LOANTRNAMT> aggregate in <INTRATRNRS>. Otherwise, the breakdown of the loan payment may
be returned in <LOANSTMTTRN>.
Tag Description
<XFERPRCSTS> Transfer processing status aggregate
<XFERPRCCODE> See section 11.3.6.1
<DTXFERPRC> Transfer processing date; value depends on <XFERPRCCODE>
</XFERPRCSTS>
Value Description
Tag Description
<LOANACCTFROM> Transfer processing status aggregate
<LOANACCTID> Account number, A-22
<LOANACCTTYPE> Loan account type, see section 11.3.7.1
</LOANACCTFROM>
Value Description
Tag Description
<LOANACCTINFO>
<BALLOONAMT> Not included or zero for regular loans, otherwise Balloon amount, amount
<LOANINT> Loan Interest aggregate, see section 11.3.8.3
</LOANINT>
Value Description
WEEKLY Weekly
BIWEEKLY Biweekly
MONTHLY Monthly
BIMONTHLY Bimonthly
QUARTERLY Quarterly
SEMIANNUALLY Semiannually
ANNUALLY Annually
Refer to section 10.2.1for rules for calculating recurring dates of WEEKLY, BIWEEKLY, and
TWICEMONTHLY.
Tag Description
<PRINBAL> Loan Principal Balance aggregate
<BALAMT> Current loan principal balance, amount
<PRINYTD> Total principal paid year to date, amount
<PRINLTD> Total principal paid loan to date, amount
<DTASOF> Date and time of the current loan balance. datetime
</PRINBAL>
Tag Description
<LOANINT>
Tag Description
<LOANIRATE>
Tag Description
<LOANPMT>
Tag Description
<LOANTRNAMT>
Tag Description
<ESCRWAMT>
Tag Description
<LASTPMTINFO>
In addition to the above, OFX 2.2 adds a new mechanism allowing servers to explicitly indicate they
support the download of pending transactions as well as specific mechanisms for a client to request such
transactions if they are available.
Clients typically allow customers to view these transactions and guide customers through a process of
updating their account registers based on the downloaded transactions. By using transaction IDs supplied
by financial institutions, OFX makes it possible for clients to ensure that a server downloads each
transaction only once. The request also contains starting and ending dates to limit the amount of
downloaded data. Clients can remember the last date they received data and use it as the starting date in the
next request.
The messages in this chapter are appropriate for checking, savings, money market, credit card, CD, and
line of credit accounts. Investment statement download is a superset of bank statement download.
Chapter 13, "Investments," describes the messages specific to investment statement download.
Statement download requires the client to designate an account for the download, and to indicate if the
server should download transactions and/or balances. If the client wishes to download transactions, it can
specify a date range that the transactions fall within.
The server returns transactions that match the date range (if the client specifies one), and balance
information for the account.
Account information
Include transactions?
Include pending?
Date range
Transactions
Pending Transactions
Cycle-ending information
This is further exacerbated by the increasing presence of web and mobile clients, along with increasing
numbers of aggregation services and providers.
OFX 2.2 defines new mechanisms for the download of pending transactions via a parallel set of aggregates
that clearly delineate between posted and pending transactions. In this model pending transactions are
downloaded as a "snapshot" of the instant in time when the download occurred. While clients generally
should not store these transactions as they may change when they are settled (or completely disappear such
as a hold on a credit card) they enable new client side use cases such as (but not limited to):
• Account balance forecasting for better money management advice to the end-user
• Account alerts based on pending transactions
• Reconciliation or explanation to the user of their current available balance
These new mechanisms for pending transactions apply ONLY to banking and credit card statement
download. They are NOT supported within investment or loan statement download.
If a server supports pending transactions and file-based error recovery there is the potential for ambiguity
in the freshness of the pending transactions. Per rules for file-based error recovery, the server will have
created and stored a response to later be returned to the client. Per the rules for pending transactions, the
server should be returning a "snapshot" of transactions at the instant in time of the download.
This ambiguity is resolved by the <DTASOF> tag within the <BANKTRANLISTP> aggregate. In normal
operation this tag would be populated with the same (or nearly the same) value as the <DTSERVER> from
the <SONRS>. In a situation where file-based error recovery is supported the client can use this value, by
comparing it to the <DTSERVER>, to determine when the snapshot of pending transactions was generated
and determine if they should be displayed to the user, if the user should be informed they need to do
another download, or whatever action the client deems appropriate based on its design.
This also provides an option for the server developer to include special file-based error recovery logic to
always generate a fresh set of pending transactions however this is not required.
If a statement download request does not contain <DTSTART> or <DTEND> elements but does request
transactions and if no transactions are found on the server, the response may or may not include a
<BANKTRANLIST>. If the <BANKTRANLIST> is included, the server should leave out the empty
<STMTTRN> aggregate(s).
If pending transactions are supported and are requested, the response may or may not include a
<BANKTRANLISTP> aggregate containing <STMTTRNP> aggregates for each pending transaction.
You can use the <STMTRQ> … <STMTRS> request and response pair to download transactions and
balances for checking, savings, money market, CD, and line of credit accounts. Section 11.4.3 describes
download for credit card accounts.
Clients and servers should interpret <DTSTART> and <DTEND> as described in Chapter 3, "Common
Aggregates, Elements, and Data Types."
Note: Pending transactions are *NOT* bound by the <DTSTART> or <DTEND> elements in
the request or response. They are a snapshot of whatever pending transactions exist at the time
of the download on the account and may change over the course of a single day across different
downloads.
Tag Description
<STMTRQ> Statement-request aggregate
<BANKACCTFROM> Bank-account-from aggregate, see section 11.3.1
</BANKACCTFROM>
A statement response comprises elements supplying various balances, plus zero or more <STMTTRN>
and <STMTTRNP> aggregates, each describing one statement transaction.
The response can contain a <BALLIST> aggregate that allows an FI to send any number of <BAL>
aggregates (see Chapter 3, “Common Aggregates, Elements, and Data Types”) to the user, complete with
description and Help text.
See Chapter 3, "Common Aggregates, Elements, and Data Types," for size and type information for
common elements (such as currency values).
Tag Description
<STMTRS> Statement-response aggregate
<CURDEF> Default currency for the statement, currsymbol
<BANKACCTFROM> Account-from aggregate, see section 11.3.1
</BANKACCTFROM>
<CASHADVBALAMT> Only applies to CREDITLINE accounts. Current balance amount for cash
advances at the time of the download, amount
<INTRATE> Current interest rate in effect at the time of download, rate
<BALLIST> List of miscellaneous other balances
<BAL> Balance aggregates (0 or more), see section 3.1.4
See Appendix B, "Suggested Name Values for the Banking <BALLIST>," for a
list of suggested common values for use with the <NAME> and <DESC> tags
in these <BAL> aggregates.
Note: Should the balance type not map to any of those shown in B.2, any value
for the <NAME> and <DESC> fields may be used.
</BAL>
</BALLIST>
Code Meaning
0 Success
All notes and conditions from 11.4.2 , "Bank Statement Download" apply to credit card downloads
including pending transactions.
Tag Description
<CCSTMTRQ> Credit-card-download-request aggregate
<CCACCTFROM> Credit-card-account-from aggregate
<ACCTID> Account number, A-22
<ACCTKEY> Checksum for international banks, A-22
</CCACCTFROM>
Tag Description
<CCSTMTRS> Credit-card-download-response aggregate
<CURDEF> Default currency for the statement, currsymbol
<CCACCTFROM> Account from aggregate, see section 11.3.2
</CCACCTFROM>
<CASHADVBALAMT> Current balance amount for cash advances at the time of the download, amount
<CASHADVAVAILAMT> Cash advance available amount, amount
<INTRATEPURCH> Current interest rate for purchases in effect at time of download, rate
<INTRATECASH> Current interest rate for cash advances in effect at time of download, rate
<INTRATEXFER> Current interest rate for balance transfers in effect at time of download, rate
<REWARDINFO> Opening aggregate for reward/points program current information
Note: In CCSTMTRS this aggregate is used to return the current values and
YTD points earned for the program at the time of the download.
<NAME> Name of the reward program, A-32
<REWARDBAL> Current rewards balance as of the time of the download, amount
<REWARDEARNED> Reward amount earned YTD as of the time of download, amount
</REWARDINFO>
</BALLIST>
Code Meaning
0 Success
<STMTTRN> is used exclusively for posted (settled) transactions which are finalized and reflected in the
<LEDGERBAL> balance. It is returned within the <BANKTRANLIST> aggregate and
<INVBANKTRAN> aggregates.
<STMTTRNP> is used exclusively for pending transactions which are not fully settled and may change or
be removed from the account entirely and are reflected in the <AVAILBAL> balance. It is returned
exclusively within the <BANKTRANLISTP> aggregate.
11.4.4.1 <STMTTRN>
A <STMTTRN> aggregate describes a single transaction. It identifies the type of the transaction and the
date it was posted. The aggregate can also provide additional information to help the customer recognize
the transaction: check number, payee name, and memo. The transaction can have a Standard Industrial
Code that a client can use to categorize the transaction.
Each <STMTTRN> contains an <FITID> that the client uses to detect whether the server has previously
downloaded the transaction.
Transaction amounts are signed from the perspective of the customer. For example, a credit card payment
is positive while a credit card purchase is negative.
-or-
<CCACCTTO>
</CCACCTTO>
</ORIGCURRENCY>
A <STMTTRNP> aggregate describes a single pending transaction. It identifies the type of the transaction
and the date it was initiated. The aggregate can also provide additional information to help the customer
recognize the transaction: check number, payee name, and memo.
If the <TRNTYPE> for the transaction is HOLD then the DTEXPIRE tag can be used to indicate when the
hold on the transaction is currently scheduled to end.
Note: Unlike <STMTTRN>, <STMTTRNP> does not contain the <FITID> tag. Clients may
display pending transactions to the user and may use it in various internal calculations or
forecasting; however pending transactions should NEVER be stored or used for reconciliation
purposes against <LEDGERBAL>. When, and if, the transaction fully settles it will be
available in a future download in <STMTTRN> like all other posted transactions.
Transaction amounts are signed from the perspective of the customer. For example, a credit card payment
is positive while a credit card purchase is negative.
</ORIGCURRENCY>
</STMTTRNP>
The user has a $250 authorization hold placed on their credit card by an auto rental agency. The
hold will expire in 3 days. <TRNAMT> is positive on this HOLD transaction as it is a charge to a
credit card which increases the balance owed
<STMTTRNP>
<TRNTYPE>HOLD</TRNTYPE>
<DTTRAN>20140507</DTTRAN>
<DTEXPIRE>20140510</DTEXPIRE>
<TRNAMT>250</TRNAMT>
<NAME>ABC Auto Rentals</NAME>
</STMTTRNP>
<STMTTRNP>
<TRNTYPE>DEP</TRNTYPE>
<DTTRAN>20140507</DTTRAN>
<TRNAMT>500</TRNAMT>
<NAME>Counter Deposit</NAME>
<MEMO>Immediate credit to account</MEMO>
</STMTTRNP>
<STMTTRNP>
<TRNTYPE>HOLD</TRNTYPE>
<DTTRAN>20140507</DTTRAN>
<DTEXPIRE>20140512</DTEXPIRE>
<TRNAMT>4500</TRNAMT>
<NAME>Counter Deposit</NAME>
<MEMO>Funds held for clearing</MEMO>
</STMTTRNP>
Transfers generated from a model are treated identically to individually requested transfers by OFX.
Therefore, they should have the transaction types listed below once they are processed. Transfers initiated
out of band with respect to OFX should also be handled in this fashion when they appear in a statement
download.
Type Description
DIV Dividend
FEE FI fee
DEP Deposit
XFER Transfer
CHECK Check
OTHER Other
Tag Description
<LOANSTMTRQ> Loan-download-request aggregate
<LOANACCTFROM> Loan-account-from aggregate, see section 11.3.7
<LOANACCTFROM>
The loan download response is semantically similar to the bank and credit card statement download
request with the addition of new tags relating to interest rates, and various balances. However, the
<LOANSTMTTRNRS> aggregate contains the loan response, not the <STMTRS> or <CCSTMTRS>
aggregate.
Tag Description
<LOANSTMTRS> Loan-download-request aggregate
Code Meaning
0 Success
Transaction amounts are signed from the perspective of the customer. For example, a loan payment is
positive while a loan advance is negative.
If the server has available the breakdown of payment into principal, interest and escrow,
<LOANSTMTTRN> should include <LOANTRNAMT> When provided, the sum of the
<LOANTRNAMT> aggregate should equal <TRNAMT>.
Tag Description
<LOANSTMTTRN> Loan-statement-transaction aggregate
<LOANTRNTYPE> Transaction type, see section 11.4.6.1 for possible values
<DTPOSTED> Date transaction was posted to account, datetime
<DTUSER> Date user initiated transaction, if known, datetime
<TRNAMT> Amount of transaction, amount
<LOANTRNAMT> Loan transaction amount aggregate, see section 11.3.9
</LOANTRNAMT>
-or-
<LOANACCTTO> If this was a transfer to another loan account (a roll over) and the account
infrmation is available, see section 11.3.7
</LOANACCTTO>
-or-
<ORIGCURRENCY>
</ORIGCURRENCY>
</LOANSTMTTRN>
Tag Description
OTHER Other
If the server is unable to compute an amortization schedule adjusted based upon past or projected payment
history, the server should indicate <AMRTTYPE>ORIGINAL.
Tag Description
<AMRTSTMTRQ> Amortization statement request aggregate
<LOANACCTFROM> Account from aggregate, see section 11.3.7
</LOANACCTFROM>
Tag Description
<AMRTSTMTRS> Amortization statement response aggregate
<CURDEF> Default currency for the statement, currsymbol
<LOANACCTFROM> Account from aggregate, see section 11.3.7
</LOANACCTFROM>
<AMRTTRANLIST>
</AMRTTRANLIST>
Code Meaning
0 Success
Tag Description
<AMRTSTMTTRN> Amortization transaction aggregate
<PMTNUMBER> Loan payment number, N-3
<LOANINITBAL> Beginning balance before payment, amount
<PRINBAL> Principal Balance aggregate - see section 11.3.8.2
Ending balance after payment, includes date of payment
</PRINBAL>
To request statement information, the client is REQUIRED to designate an account for the download. The
client can also specify a date range to limit the number of closing information aggregates that the server
returns. If the client does not specify a date range, the server returns as many closing information
aggregates as it can.
Account Information
Date range
Tag Description
<STMTENDRQ> Closing-statement-request aggregate
<BANKACCTFROM> Bank-account-from aggregate
</BANKACCTFROM>
Tag Description
<STMTENDRS> Closing-statement-response aggregate
<CURDEF> Default currency used for closing information, currsymbol
<BANKACCTFROM> Account from aggregate, see section 11.3.1
</BANKACCTFROM>
</STMTENDRS>
Code Meaning
0 Success
The <FITID> provides a way for the client to distinguish one closing statement from another.
For each <CLOSING> aggregate returned, clients can retrieve corresponding transactions by using
<DTPOSTSTART> and <DTPOSTEND> as <DTSTART> and <DTEND> in a <STMTRQ> request.
Tag Description
<CLOSING> Non-credit-card-account-types aggregate
<FITID> Unique identifier for this statement, FITID
<DTOPEN> Opening statement date, date
<DTCLOSE> Closing statement date, date
<DTNEXT> Closing date of next statement, date
<BALOPEN> Opening statement balance, amount
<BALCLOSE> Closing statement balance, amount
<BALMIN> Minimum balance in statement period, amount
<DEPANDCREDIT> Total of deposits and credits, including interest, amount
<CHKANDDEB> Total of checks and debits, including fees, amount
<TOTALFEES> Total of all fees, amount
<LOANDETAIL> Loan details aggregate. Only returned if loan accounts were mapped to
<ACCTTYPE>CREDITLINE during implementation. See section 11.5.2.1
</LOANDETAIL>
</CREDITLINEINFO>
<ORIGCURRENCY>
</ORIGCURRENCY>
</CLOSING>
11.5.2.1 <LOANDETAIL>
The <LOANDETAIL> aggregate should only be returned for traditional loan accounts (e.g. mortgage,
automobile, etc.) which were mapped to <ACCTTYPE>CREDITLINE during implementation. The
aggregate contains a subset of key information about the loan account.
Tag Description
<LOANDETAIL>
Tag Description
<CCSTMTENDRQ> Credit-card-closing-statement-request aggregate
<CCACCTFROM> Credit-card-account-from aggregate
</CCACCTFROM>
Tag Description
<CCSTMTENDRS> Credit-card-closing-statement-response aggregate
<CURDEF> Default currency for closing information, currsymbol
<CCACCTFROM> Account from aggregate, see section 11.3.2
</CCACCTFROM>
</CCSTMTENDRS>
Code Meaning
0 Success
A credit card account uses the <CCCLOSING> aggregate to describe statement closing information.
The <FITID> provides a way for the client to distinguish one closing statement from another.
Tag Description
<CCCLOSING> Credit-card-statement-information aggregate
<FITID> Unique identifier for this statement, FITID
<DTOPEN> Opening statement date, date
<DTCLOSE> Closing statement date, date
<DTNEXT> Closing date of next statement, date
<BALOPEN> Opening statement balance, amount
<BALCLOSE> Closing statement balance, amount
<INTYTD> Year-to-date interest paid on the account, amount
<DTPMTDUE> Payment due date, date
<MINPMTDUE> Minimum amount due, amount
<PASTDUEAMT> Amount of <MINPMTDUE>, if any, which reflects a past due amount, amount
<LATEFEEAMT> Amount of <MINPMTDUE>, if any, which reflects a late fee, amount
<FINCHG> Finance charges, amount
<INTRATEPURCH> Effective interest rate for purchases, taking into account any changes in rates
which applied during this statement period, rate
<INTRATECASH> Effective interest rate for cash advances, taking into account any changes in
rates which applied during this statement period, rate
<INTRATEXFER> Effective interest rate for balance transfers, taking into account any changes in
rates which applied during this statement period, rate
<PAYANDCREDIT> Total of payments and credits, amount
<PURANDADV> Total of purchases and cash advances, amount
<DEBADJ> Debit adjustments, amount
<CREDITLIMIT> Current credit limit, amount
<CASHADVBALAMT> Cash advance balance amount, amount
<CASHADVAVAILAMT> Cash advance available amount, amount
<CASHADVCREDITLIMIT> Current cash advance credit limit, amount
<DTPOSTSTART> Start date of transaction data for this statement, date
A client should be able to use this date in a <CCSTMTRQ> to request
transactions that match this statement.
Note: In CCCLOSING this aggregate is used to return the balance and points
earned specific to the enclosing CCSTMTENDRS’ period
<NAME> Name of the reward program, A-32
<REWARDBAL> Reward balance at the end of the statement period, amount
<REWARDEARNED> Reward amount earned/added during this statement period, amount
</REWARDINFO>
<ORIGCURRENCY>
</ORIGCURRENCY>
</CCCLOSING>
The loan statement closing request is semantically identical to the bank and credit card statement
closing requests. However, the <LOANSTMTENDTRNRQ> aggregate contains the loan request,
not the <STMTENDRQ> or <CCSTMTENRQ> aggregate.
Tag Description
<LOANSTMTENDRQ> Loan-dosing-statement-request aggregate
<LOANACCTFROM> Loan-account-from aggregate, see section 11.3.7
</LOANACCTFROM>
Tag Description
<LOANSTMTENDRS> Loan-closing-statement-response aggregate
<CURDEF> Default currency for closing
<LOANACCTFROM> Loan-account-from aggregate, see section 11.3.7
</LOANACCTFROM>
</LOANSTMTENDRS>
Code Meaning
0 Success
For each <LOANCLOSING> returned, clients should be able to retrieve corresponding transactions by
using <DTPOSTSTART> and <DTPOSTEND> as <DTSTART> and <DTEND> in a <LOANSTMTRQ>
request.
Tag Description
<LOANCLOSING> Loan-statement-information aggregate
<FITID> Unique identifier for this statement, FITID
<DTOPEN> Opening statement date, date
<DTCLOSE> Closing statement date, date
<DTNEXT> Closing date of next statement, date
<BALOPEN> Opening statement principal balance, amount
<PRINBAL> Current Principal Balance aggregate - see 11.3.8.2
</PRINBAL>
<BALLOONAMT> Not included or zero for regular loans, otherwise balloon payment amount,
amount
<LOANPMT> Loan Payment aggregate - see section 11.3.8.5
</LOANPMT>
</BALLIST>
-or-
<ORIGCURRENCY>
</ORIGCURRENCY>
</LOANCLOSING>
Tag Description
<ESTPAYOFF>
Tag Description
<ESCRWBAL>
When stopping a single check, the client can provide a payee name and optionally an amount instead of a
check number to describe the check to stop. Not all servers can support this behavior.
Examples:
Stop check 22 – one request
Stop check to “Acme Lighting” – one request
Stop checks 200-224 – one request
Stop checks 275-280, 283 – two requests (first stops 275-280, the next stops 283)
Account information
-or-
Check description
Tag Description
<STPCHKRQ> Stop-check-request aggregate
<BANKACCTFROM> Account-from aggregate, see section 11.3.1
</BANKACCTFROM>
-or-
</STPCHKRQ>
Tag Description
<CHKRANGE> Check-range aggregate
<CHKNUMSTART> Start check number to cancel, A-12
<CHKNUMEND> Ending check number to cancel; omit if only one check is to be stopped, A-
12
</CHKRANGE>
A check description must include a payee name or description. It can also include a check number, the date
the user wrote the check, and a transaction amount.
Tag Description
<CHKDESC> Check description aggregate
<NAME> Payee name or description, A-32
<CHECKNUM> Check number, A-12
<DTUSER> Date on check, datetime
<TRNAMT> Amount, amount
</CHKDESC>
Consistent with all responses, the stop check response contains a global status that describes whether the
response could be delivered. If the server provides a response, it returns a <STPCHKNUM> aggregate for
each check for which the client requested a stop payment. Status code 10000 should be returned if the stop
check request is in process; a subsequent synchronization should obtain an updated response with a final
status.
Tag Description
<STPCHKRS> Stop-check-response aggregate
<CURDEF> Default currency for stop check response, currsymbol
<BANKACCTFROM> Account-from aggregate, see section 11.3.1
</BANKACCTFROM>
This aggregate contains a status code that indicates whether or not a specific check was canceled.
Tag Description
<STPCHKNUM> Stopped-check-item aggregate
<CHECKNUM> Check number, A-12
<NAME> Payee name or description, A-32
<DTUSER> Date on check, datetime
<TRNAMT> Amount, amount
<CHKSTATUS> Status code for individual stop check request
0 = OK
1 = rejected
100 = check not found
101 = check already posted
<CHKERROR> Further textual explanation, A-255
<ORIGCURRENCY>
</ORIGCURRENCY>
</STPCHKNUM>
Code Meaning
0 Success
In general, an OFX server may not choose which transactions to support unless the profile can be used to
indicate to the client that a transaction is not supported. However, immediate intrabank funds transfers
usually cannot be modified or canceled, so a server that does not support scheduled transfers may return an
error code on any request for cancel or modify. A preferred approach would be to return status code 2016,
which means the transfer may not be modified or canceled because it is already committed. (An immediate
transfer may not actually commit until the end of the business day. For more information, see the
discussion on the support of INTRASYNCRQ in section 11.12.2.)
After a transfer has executed, the server can either issue a transfer modification response in the sync or it
can do nothing. In the latter case, it would be up to the client to get status from a statement download. If a
transfer fails, it is recommended, but not required, that a transfer modification response with the
appropriate XFERPRCCODE be sent in the sync.
In general, all Intrabank Funds Transfer requests are subject to synchronization. The only exception occurs
when the request is for an immediate transfer and the server is able to successfully perform the transfer in
real time. In that case, the server may choose whether or not the transfer affects the sync history. After
receiving an immediate response indicating that a transfer took place in real time, the client must not
expect the relevant token to change or to receive information about that transfer in a later sync response.
Servers choosing to ignore real time immediate transfers in the sync history force additional clients to wait
until the transfer appears in a statement download for information about the transfer. Note that a server that
does not implement file-based error recovery should include immediate transfers in the sync history since
error recovery attempts will be token-based rather than file based.
Note: If a server batches up immediate transfers, to be processed that night or possibly the next day, it
should return a <WILLPROCESSON> status in the immediate transfer response. At that point it is up to
the server whether or not to send the <INTRARS> in the sync before the transfer actually occurs. It should
be noted that servers that don’t sync such "batched, but not yet transferred" responses prevent other clients
accessing the same account from getting accurate balance information during this time. After the transfer,
the up-to-date balance information can be obtained from either the sync (if the server supports this) or the
statement downloaded.
Source account
Destination account
Amount
Source account
Destination account
Amount
Tag Description
<INTRARQ> Intrabank-transfer-request aggregate
<XFERINFO> Transfer information aggregate, see section 11.3.5
</XFERINFO>
</INTRARQ>
A server cannot, in all cases, provide complete confirmation for the transfer. The server can confirm only
that it received the transfer instruction; and possibly whether it validated the accounts, amount, and date
specified in the transfer. For any transfer where the client does not know the status at the time of the
response, a server should confirm that it accepted the instruction and indicate the expected posting date of
the transfer. A client can pick up the confirmation at a later date through a synchronization request. Servers
should inform clients of any errors found while processing this transaction using the <STATUS>
aggregate. A response containing <STATUS><CODE>0 and
If the request is for an immediate transfer and the server can perform the transfer in real time, the server
should indicate whether the transfer succeeded and should return the date of the transfer in
<DTPOSTED>. In this case, synchronization is not required.
Tag Description
<INTRARS> Intrabank-transfer-response aggregate
<CURDEF> Default currency for the intrabank transfer response, currsymbol
<SRVRTID> Server ID for this transfer, SRVRTID
<XFERINFO> Transfer information aggregate, see section 11.3.5
</XFERINFO>
Transfer-date options.
Choose either
<DTXFERPRJ> or
<DTPOSTED>
<DTXFERPRJ> Projected date of the transfer; response can contain either a <DTXFERPRJ> or a
<DTPOSTED> but not both; datetime
-or-
</INTRARS>
Note: The server can deliver this response to a client immediately after the request is made
(for an immediate or one-time scheduled transfer). The server should also return this response
for any transfers that were generated by a model.
Code Meaning
0 Success (INFO)
Tag Description
<INTRAMODRQ> Modification-request aggregate
<SRVRTID> ID assigned by the server to the transfer being modified, SRVRTID
<XFERINFO> Transfer information aggregate, see section 11.3.5
</XFERINFO>
</INTRAMODRQ>
This response normally just echoes the values passed by the client. However, if the status of a scheduled
transfer changes in any way, clients may expect to receive modification responses when they synchronize
with the server. For example, when a server completes a transfer, the status of the transfer goes from
pending to posted. Servers may notify clients of this status change if they wish.
Tag Description
<INTRAMODRS> Modification-response aggregate
<SRVRTID> ID assigned by the server to the transfer being modified, SRVRTID
<XFERINFO> Transfer information aggregate, see section 11.3.5
</XFERINFO>
</INTRAMODRS>
Code Meaning
0 Success (INFO)
Tag Description
<INTRACANRQ> Transfer-cancellation-request aggregate
<SRVRTID> ID of the transfer the user wants to cancel. The server must have previously
assigned this ID to a transfer. SRVRTID
</INTRACANRQ>
Tag Description
<INTRACANRS> Transfer-cancellation-response aggregate
<SRVRTID> ID of the transfer the user wants to cancel. The server must have previously
assigned this ID to a transfer. SRVRTID
</INTRACANRS>
Code Meaning
0 Success (INFO)
The following is a list of what might be returned in an immediate mode transfer response. The
interpretation of each response is provided. All responses referenced in this section are immediate and
describe success conditions. That is, we are not attempting to describe the INTRARS aggregates that may
be returned within a INTRASYNCRS response. Further, successful INTRARS aggregates for immediate
transfers are not expected to appear in lite synchronization INTRASYNCRS responses.
• DTDUE and INTRARQ
DTDUE should not be present if the client is requesting an immediate mode transfer. If it is, then this is a client
error, and will be treated by the server as if the client were attempting to create a scheduled transfer.
• DTDUE, DTPOSTED, and DTXFERPRJ NOT returned in INTRARS
The client should interpret this from the server as indicating that the immediate transfer request was processed in
real-time.
• DTDUE only returned
DTDUE should not be present in the response to a request for an immediate transfer. If it were present, the
XFERINFO aggregate would not match that found in the request.
• DTPOSTED only returned
If this is not equal to today’s date and an earlier time than “now”, then this is a server error. Otherwise, the client
should interpret this as confirmation from the server that the request was processed in real-time.
• DTXFERPRJ only returned
The client should interpret this as indication that the transfer request will be completed by the specified date. The
client may receive an INTRAMODRS or INTRARS with updated information about this transfer when it is
actually processed. That future INTRARS or INTRAMODRS will contain the DTPOSTED to reflect when the
transfer occurred. This response is not required for successful transfers processed at the originally specified
projected date and time.
Use the ACH system to implement the Interbank Funds Transfer, which is subject to the rules and
regulations governing the ACH network.
In all other respects, interbank funds transfers function like intrabank funds transfers. The user can
schedule them for a future date or request an immediate transfer. The user can modify or cancel scheduled
transfers, but not immediate transfers. Scheduled transfers can recur at regular intervals.
Source account
Destination account
Amount
Source account
Destination account
Amount
Expected/actual posting
date
Tag Description
<INTERRQ> Interbank-transfer-request aggregate
<XFERINFO> Transfer information aggregate, see section 11.3.5
</XFERINFO>
</INTERRQ>
The server cannot provide complete confirmation for interbank transfer. It can confirm only that the FI
received the transfer instruction and possibly validated the source account, amount, and date specified in
the transfer. Since the client does not know the status of the transfer at the time of the response, the server
should confirm that it accepted the instruction and indicate the expected posting date of the transfer. The
client can pick up the confirmation at a later date through a synchronization request. Servers should inform
clients of any errors found while processing this transaction using the <STATUS> aggregate. A response
containing <STATUS><CODE>0 and <XFERPRCSTS><XFERPRCCODE>FAILEDON should be
avoided for problems such as an invalid account or amount.
Tag Description
<INTERRS> Interbank-transfer-response aggregate
<CURDEF> Currency used in transfer, currsymbol
<SRVRTID> Server ID for this transfer, SRVRTID
<XFERINFO> Transfer information aggregate, see section 11.3.5
</XFERINFO>
Transfer-date options.
Choose either
<DTXFERPRJ> or
<DTPOSTED>
<DTXFERPRJ> Projected date of the transfer; response can contain either a <DTXFERPRJ> or a
<DTPOSTED> but not both; datetime
-or-
</INTERRS>
Note: A server can deliver this response to a client immediately after the client makes the
request (for an immediate or one-time scheduled transfer). In response to a synchronization
request by a client, the server should provide a second response containing complete status
regarding the transfer. It should also return any transfers that it generates by a model.
Code Meaning
0 Success (INFO)
Tag Description
<INTERMODRQ> Modification-request aggregate
<SRVRTID> ID assigned by the server to the transfer being modified, SRVRTID
<XFERINFO> Transfer information aggregate, see section 11.3.5
</XFERINFO>
</INTERMODRQ>
Tag Description
<INTERMODRS> Modification-response aggregate
<SRVRTID> ID assigned by the server to the transfer being modified, SRVRTID
<XFERINFO> Transfer information aggregate; server returns if client provided an <XFERINFO>
in the request, see section 11.3.5
</XFERINFO>
</INTERMODRS>
Code Meaning
0 Success (INFO)
Tag Description
<INTERCANRQ> Transfer-cancellation-request aggregate
<SRVRTID> ID of the transfer to cancel. The server must have previously assigned
this ID to a transfer. SRVRTID
</INTERCANRQ>
Tag Description
<INTERCANRS> Transfer-cancellation-response aggregate
<SRVRTID> ID of the transfer to cancel. The server must have previously assigned
this ID to a transfer. SRVRTID
</INTERCANRS>
Code Meaning
0 Success (INFO)
The FI must know the originator of the transfer. The beneficiary of the transfer might be an established
customer at the same institution.
OFX implements wire funds transfers using the FedWire system, and is subject to its rules and regulations.
In almost all respects, wire funds transfers work like interbank funds transfers. A user can schedule and
cancel them. Unlike interbank funds transfers, a user cannot modify Wire funds transfers once they have
been set up. A user cannot set up wire funds transfers to recur at regular intervals.
Source account
Originator
Receiver
Amount
Originator
Receiver
Amount
Expected/actual posting
date
The client prepares a <BANKACCTFROM> aggregate to describe the source account. The
<WIREBENEFICIARY> aggregate specifies the destination account. The <WIREDESTBANK>
aggregate describes the beneficiary’s bank.
Tag Description
<WIRERQ> Wire-transfer-request aggregate
<BANKACCTFROM> Source of funds, see section 11.3.1
</BANKACCTFROM>
</WIREDESTBANK>
Tag Description
<WIREBENEFICIARY> Wire-beneficiary aggregate
<NAME> Name of beneficiary, A-32
<BANKACCTTO> Bank details for beneficiary, see section 11.3.1
</BANKACCTTO>
Tag Description
<EXTBANKDESC> Extended-bank-description aggregate
<NAME> Abbreviated name of bank, A-32
<BANKID> Routing: ABA number or S.W.I.F.T. number, A-9
<ADDR1> Bank’s address line 1, A-32
<ADDR2> Bank’s address line 2, A-32
<ADDR3> Bank’s address line 3. Use of <ADDR3> requires the presence of <ADDR2>, A-
32
<CITY> Bank’s city, A-32
<STATE> Bank’s state or province, A-5
<POSTALCODE> Bank’s postal code, A-11
<COUNTRY> Bank’s country; 3-letter country code from ISO/DIS-3166, A-3
<PHONE> Bank’s phone number, A-32
</EXTBANKDESC>
The server cannot provide complete confirmation for the transfer. It can confirm only that the server
received the transfer instruction and possibly that it validated the source account, amount, and date
specified in the transfer. For any transfer where the client does not know the status at the time of the
response, the server should confirm that it accepted the instruction and indicate the expected posting date
of the transfer. The client can pick up the confirmation at a later date through a synchronization request.
The server can indicate the fee assessed for the transfer by using the <FEE> element in the response. The
server can also include a confirmation message in the response.
The <DTDUE> in a response may have been adjusted by a server. For example, the server may adjust
<DTDUE> to comply with non-processing days. If a client sends a request to make a transfer on July 4 and
July 4 happens to be a non-processing day, the <DTDUE> in the response may be July 4 (because the
server hasn’t adjusted it yet), July 5 (because this server rolls dates forward), or some other date. For this
reason, a client should pay attention to the <DTDUE> in the response.
Tag Description
<WIRERS> Wire-transfer-response aggregate
<CURDEF> Currency used in transfer, currsymbol
<SRVRTID> Server ID for this transfer, SRVRTID
<BANKACCTFROM> Source of funds, see section 11.3.1
</BANKACCTFROM>
</WIREDESTBANK>
Code Meaning
0 Success (INFO)
Tag Description
<WIRECANRQ> Wire-transfer-cancellation-request aggregate
<SRVRTID> ID of the transfer to cancel; server must have previously assigned
this ID to a transfer, SRVRTID
</WIRECANRQ>
Tag Description
<WIRECANRS> Wire-transfer-cancellation-response aggregate
<SRVRTID> ID of the transfer to cancel; server must have previously assigned this ID to a
transfer, SRVRTID
</WIRECANRS>
Code Meaning
0 Success (INFO)
A user can create recurring funds transfer models to generate two types of scheduled transfers: interbank
and intrabank. You cannot set up recurring wire funds transfers.
Source account
Destination account
Amount
Frequency
Duration
Source account
Destination account
Amount
Frequency
Duration
Tag Description
<RECINTRARQ> Recurring-transfer-request aggregate
<RECURRINST> Recurring-instructions aggregate, see section
</RECURRINST>
</RECINTRARQ>
For version 1 of the message set, the <SRVRTID> included in the <INTRARS> should be set to the same
value as the <RECSRVRTID>.
Note: This is the response to the recurring model only. Servers must still generate an
INTRARS for each instance of the recurring transfer.
Tag Description
<RECINTRARS> Recurring-transfer-response aggregate
<RECSRVRTID> Server-assigned ID for this model, SRVRTID
<RECURRINST> Recurring-instructions aggregate
</RECURRINST>
</RECINTRARS>
Code Meaning
0 Success (INFO)
<RECSRVRTID> identifies the model. The client can indicate whether the changes should apply to
pending transfers.
Tag Description
<RECINTRAMODRQ> Recurring-modification-request aggregate
<RECSRVRTID> ID assigned by the server to the model being modified, SRVRTID
<RECURRINST> Recurring-instructions aggregate
</RECURRINST>
Tag Description
<RECINTRAMODRS> Recurring-transfer-modification-request aggregate
<RECSRVRTID> ID assigned by the server to the model being modified, SRVRTID
<RECURRINST> Recurring-instructions aggregate
</RECURRINST>
<MODPENDING> Y if client requested that the server modify pending and future transfers. N if the
client did not request that the server modify pending and future transfers. Boolean
</RECINTRAMODRS>
Code Meaning
0 Success (INFO)
<RECSRVRTID> identifies the model the user wants to cancel. The client can indicate whether the cancel
should apply to pending transfers.
Tag Description
<RECINTRACANRQ> Recurring-transfer-cancellation-request aggregate
<RECSRVRTID> ID assigned by the server to the model being canceled, SRVRTID
<CANPENDING> Cancel pending flag, Boolean
If Y, server should cancel all pending and unspawned transfers. If N, server should
cancel only the model (and unspawned transfers).
</RECINTRACANRQ>
Tag Description
<RECINTRACANRS> Recurring-transfer-cancellation-response aggregate
<RECSRVRTID> ID assigned by the server to the model being canceled, SRVRTID
<CANPENDING> Cancel pending flag, Boolean
Y if the client requested that the server cancel all pending and unspawned transfers. N
if the client requested that the server cancel only unspawned transfers.
</RECINTRACANRS>
Code Meaning
0 Success (INFO)
Tag Description
<RECINTERRQ> Recurring-transfer-request aggregate
<RECURRINST> Recurring-instructions aggregate
</RECURRINST>
</RECINTERRQ>
For version 1 of the message set, the <SRVRTID> included in the <INTERRS> should be set to the same
value as the <RECSRVRTID>.
Note: This is the response to the recurring model only. Servers must still generate an
<INTERRS> for each instance of the recurring transfer.
Tag Description
<RECINTERRS> Recurring-transfer-response aggregate
<RECSRVRTID> Server-assigned ID for this model, SRVRTID
<RECURRINST> Recurring-instructions aggregate, see section 9.2
</RECURRINST>
</RECINTERRS>
Code Meaning
0 Success (INFO)
<RECSRVRTID> identifies the model. The client can indicate whether the changes should apply to
pending transfers.
Tag Description
<RECINTERMODRQ> Recurring-modification-request aggregate
<RECSRVRTID> ID assigned by the server to the model being modified, SRVRTID
<RECURRINST> Recurring-instructions aggregate
</RECURRINST>
Tag Description
<RECINTERMODRS> Recurring-transfer-modification-response aggregate
<RECSRVRTID> ID assigned by the server to the model being modified, SRVRTID
<RECURRINST> Recurring-instructions aggregate
</RECURRINST>
Code Meaning
0 Success (INFO)
<RECSRVRTID> identifies the model the client wants to cancel. The client can indicate whether the
cancel should apply to pending transfers.
Tag Description
<RECINTERCANRQ> Recurring-transfer-cancellation-request aggregate
<RECSRVRTID> ID assigned by the server to the model being canceled, SRVRTID
<CANPENDING> Cancel pending flag, Boolean
If Y, server should cancel all pending and unspawned transfers. If N, server should
cancel only the model (and unspawned transfers).
</RECINTERCANRQ>
Tag Description
<RECINTERCANRS> Recurring-transfer-cancellation-response aggregate
<RECSRVRTID> ID assigned by the server to the model being canceled, SRVRTID
<CANPENDING> Cancel pending flag, Boolean
Y if the client requested that the server cancel all pending and unspawned transfers. N
if the client requested that the server cancel only unspawned transfers.
</RECINTERCANRS>
Code Meaning
0 Success (INFO)
Addressed message
Acknowledgment
Synchronization request
Response to customer
The client must identify to which bank account the customer query is related.
Tag Description
<BANKMAILRQ> Bank-e-mail-request aggregate
-or-
</BANKMAILRQ>
Tag Description
<BANKMAILRS> Bank-e-mail-response aggregate
-or-
</BANKMAILRS>
Code Meaning
0 Success (INFO)
You can implement banking notifications through e-mail and synchronization. The client provides a
<TOKEN> representing its current state with regard to banking notification. (See section 3.2.4.) The
server can respond by returning a new token and one or more notification e-mail responses.
Synchronization request
with current token
New token
Bank e-mail
The server returns this response (when a check has been returned), if it receives a banking e-mail
synchronization message.
Tag Description
<CHKMAILRS> Notification-message-response aggregate
<BANKACCTFROM> Account-from aggregate, see section 11.3.1
</BANKACCTFROM>
The server returns this response (when a deposit has been returned), if it receives a banking e-mail
synchronization message.
Tag Description
<DEPMAILRS> Notification-message-response aggregate
<BANKACCTFROM> Account-from aggregate, see section 11.3.1
</BANKACCTFROM>
Loan mail request is semantically identical to bank mail request. However, the <LOANMAILRQ>
includes loan account information, not <BANKACCTFROM> or <CCACCTFROM>.
Tag Description
<LOANMAILRQ> Loan e-mail request aggregate
<LOANACCTFROM> Loan-account-from aggregate, see section 11.3.7
</LOANACCTFROM>
</LOANMAILRQ>
Tag Description
<LOANMAILRS> Loan e-mail request aggregate
<LOANACCTFROM> Loan-account-from aggregate, see section 11.3.7
</LOANACCTFROM>
</LOANMAILRS>
Code Meaning
0 Success (INFO)
To accomplish these actions, the client uses a synchronization scheme to ensure that it has an accurate copy
of the server data that is relevant to the client application.
Banking requires synchronization in the following areas: Stop Check, IntraBank Transfers, InterBank
Transfers, Wire Transfers, and Banking Notifications.
Tag Description
<STPCHKSYNCRQ> Synchronization-request aggregate
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</STPCHKSYNCRQ>
Tag Description
<STPCHKSYNCRS> Synchronization-response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry in the
server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a token in the
server’s history table. Boolean
<BANKACCTFROM> Bank account of interest; token must be interpreted in terms of this account, see
section 11.3.1
</BANKACCTFROM>
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</STPCHKSYNCRS>
Transfers into an account do not show up in the sync for the recipient account. Only transfers out of an
account show up in the sync for that account.
Tag Description
<INTRASYNCRQ> Synchronization-request aggregate
-or-
-or-
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</INTRASYNCRQ>
Tag Description
<INTRASYNCRS> Synchronization-response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry in
the server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a
token in the server’s history table. Boolean
-or-
-or-
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</INTRASYNCRS>
The <INTRASYNCRS> responses contain only intrabank transfers where the <xxxACCTFROM>
matches that submitted in the sync request. In other words, only transfer-from accounts are synchronized.
Tag Description
<INTERSYNCRQ> Synchronization-request aggregate
-or-
-or-
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</INTERSYNCRQ>
Tag Description
<INTERSYNCRS> Synchronization-response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry in
the server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a
token in the server’s history table. Boolean
-or-
-or-
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</INTERSYNCRS>
The <INTERSYNCRS> responses contain only intrabank transfers where the <xxxACCTFROM>
matches that submitted in the sync request. In other words, only transfer-from accounts are synchronized
Tag Description
<WIRESYNCRQ> Synchronization-request aggregate
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</WIRESYNCRQ>
Tag Description
<WIRESYNCRS> Synchronization-response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry
in the server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a
token in the server’s history table. Boolean
<BANKACCTFROM> Bank account of interest; token must be interpreted in terms of this account
</BANKACCTFROM>
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</WIRESYNCRS>
This request will synchronize the client with the server in relation to recurring intrabank transfer models.
To synchronize individual transfers that were created by the model (and perhaps canceled by another
client), the client must also issue an <INTRASYNCRQ>.
Tag Description
<RECINTRASYNCRQ> Synchronization request
-or-
-or-
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</RECINTRASYNCRQ>
Tag Description
<RECINTRASYNCRS> Synchronization-response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry in
the server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a
token in the server’s history table. Boolean
-or-
-or-
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</RECINTRASYNCRS>
The <RECINTRASYNCRS> responses contain only intrabank transfer models where the
<xxxACCTFROM> matches that submitted in the sync request.
This request will synchronize the client with the server in relation to recurring interbank transfer models.
To synchronize individual funds transfers that were created by the model (and perhaps canceled by another
client), the client must also issue an <INTERSYNCRQ>.
Tag Description
<RECINTERSYNCRQ> Synchronization-request aggregate
-or-
-or-
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</RECINTERSYNCRQ>
Tag Description
<RECINTERSYNCRS> Synchronization-response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry in
the server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a
token in the server’s history table. Boolean
-or-
-or-
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</RECINTERSYNCRS>
Tag Description
<BANKMAILSYNCRQ> Synchronization-request aggregate
-or-
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</BANKMAILSYNCRQ>
Tag Description
<BANKMAILSYNCRS> Synchronization-response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry in
the server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a
token in the server’s history table. Boolean
-or-
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</BANKMAILSYNCRS>
Tag Description
<LOANMAILSYNCRQ> Synchronization-request aggregate
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</LOANMAILSYNCRQ>
Tag Description
<LOANMAILSYNCRS> Synchronization-response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry in
the server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a
token in the server’s history table. Boolean
<LOANACCTFROM> Loan-account-from aggregate, see section 11.3.7
</LOANACCTFROM>
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</LOANMAILSYNCRS>
Each message set contains options and attributes that allow an FI to customize its use of OFX. For
example, an institution can support the Interbank Funds Transfer Message Set
(INTERXFERMSGSETV1), but it can choose not to support the recurring form of these transfers.
The profile defines the options and attributes as part of each message-set definition. Each set of options
and attributes appears within an aggregate that is specific to a message set. For example,
<WIREXFERMSGSETV1> contains all of the options and attributes that pertain to wire transfers.
STMTTRNRQ
STMTRQ
STMTENDTRNRQ
STMTENDRQ
STPCHKTRNRQ
STPCHKRQ
INTRATRNRQ
INTRARQ
INTRAMODRQ
INTRACANRQ
RECINTRATRNRQ
RECINTRARQ
RECINTRAMODRQ
RECINTRACANRQ
BANKMAILTRNRQ
BANKMAILRQ
STPCHKSYNCRQ
INTRASYNCRQ
RECINTRASYNCRQ
BANKMAILSYNCRQ
</BANKMSGSRQV1>
STMTTRNRS
STMTRS
STMTENDTRNRS
STMTENDRS
STPCHKTRNRS
STPCHKRS
INTRATRNRS
INTRARS
INTRAMODRS
INTRACANRS
RECINTRATRNRS
RECINTRARS
RECINTRAMODRS
RECINTRACANRS
BANKMAILTRNRS
BANKMAILRS
CHKMAILRS
DEPMAILRS
STPCHKSYNCRS
INTRASYNCRS
RECINTRASYNCRS
BANKMAILSYNCRS
</BANKMSGSRSV1>
CCSTMTTRNRQ
CCSTMTRQ
CCSTMTENDTRNRQ
CCSTMTENDRQ
</CREDITCARDMSGSRQV1>
CCSTMTTRNRS
CCSTMTRS
CCSTMTENDTRNRS
CCSTMTENDRS
</CREDITCARDMSGSRSV1>
INTERTRNRQ
INTERRQ
INTERMODRQ
INTERCANRQ
RECINTERTRNRQ
RECINTERRQ
RECINTERMODRQ
RECINTERCANRQ
INTERSYNCRQ
RECINTERSYNCRQ
</INTERXFERMSGSRQV1>
INTERTRNRS
INTERRS
INTERMODRS
INTERCANRS
RECINTERTRNRS
RECINTERRS
RECINTERMODRS
RECINTERCANRS
INTERSYNCRS
RECINTERSYNCRS
</INTERXFERMSGSRSV1>
WIRETRNRQ
WIRERQ
WIRECANRQ
WIRESYNCRQ
</WIREXFERMSGSRQV1>
WIRETRNRS
WIRERS
WIRECANRS
WIRESYNCRS
</WIREXFERMSGSRSV1>
LOANSTMTTRNRQ
LOANSTMTRQ
AMRTSTMTTRNRQ
AMRTSTMTRQ
LOANSTMTENDTRNRQ
LOANSTMTENDRQ
LOANMAILTRNRQ
LOANMAILRQ
LOANMAILSYNCRQ
</LOANMSGSRQV1>
LOANSTMTTRNRS
LOANSTMTRS
AMRTSTMTTRNRS
AMRTSTMTRS
LOANSTMTENDTRNRS
LOANSTMTENDRS
LOANMAILTRNRS
LOANMAILRS
LOANMAILSYNCRS
</LOANMSGSRSV1>
Tag Description
<BANKMSGSET> Message set for banking
<BANKMSGSETV1> Version 1 of message set
<MSGSETCORE> Common message-set core
</MSGSETCORE>
Tag Description
<XFERPROF> Intrabank transfer profile (if supported)
<PROCDAYSOFF> Days of week that no processing occurs: MONDAY, TUESDAY,
WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, or SUNDAY. 0 or more
<PROCDAYSOFF> can be sent.
<PROCENDTM> Time of day that day’s processing ends, time
<CANSCHED> Supports scheduled transfers, Boolean
<CANRECUR> Supports recurring transfers, Boolean. Requires <CANSCHED>
<CANLOAN> Supports loan transfers. <CANLOAN>Y must be present for transfers to
involve loans, Boolean
<CANSCHEDLOAN> Supports scheduled transfers of loans (requires <CANLOAN>Y), Boolean
<CANRECURLOAN> Supports recurring transfers of loans (requires <CANSCHEDLOAN>Y),
Boolean
<CANMODXFERS> Permit modifications to transfers, i.e. <INTRAMODRQ>, Boolean
<CANMODMDLS> Permit modifications to models, i.e. <RECINTRAMODRQ>, Boolean
<MODELWND> Model window; the number of days before a recurring transaction is scheduled
to be processed that it is instantiated on the system, N-3
<DAYSWITH> Number of days before processing date that funds are withdrawn, N-3
<DFLTDAYSTOPAY> Default number of days to pay, N-3
</XFERPROF>
Tag Description
<STPCHKPROF> Stop check profile (if supported)
<PROCDAYSOFF> Days of week that no processing occurs: MONDAY, TUESDAY,
WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, or SUNDAY. 0
or more <PROCDAYSOFF> can be sent.
<PROCENDTM> Time of day that day’s processing ends, time
<CANUSERANGE> Can stop a range of checks, Boolean.
<CANUSEDESC> Can stop by description, Boolean.
<STPCHKFEE> Default stop check free Amount
</STPCHKPROF>
Tag Description
<EMAILPROF> E-mail profile
<CANEMAIL> Supports generalized banking e-mail, Boolean
<CANNOTIFY> Server may return DEPMAILRS or CHKMAILRS in synchronization
responses. See section 11.11.3 , Boolean
</EMAILPROF>
Tag Description
<CREDITCARDMSGSET> Beginning tag for credit card message set
<CREDITCARDMSGSETV1> Version 1 of message set
<MSGSETCORE> Common message-set core
</MSGSETCORE>
Tag Description
<INTERXFERMSGSET> Beginning tag for interbank transfers message set
<INTERXFERMSGSETV1> Version 1 of message set
<MSGSETCORE> Common message-set core
</MSGSETCORE>
Tag Description
<WIREXFERMSGSET> Core message set for wire transfers
<WIREXFERMSGSETV1> Version 1 of message set
<MSGSETCORE> Common message-set core
</MSGSETCORE>
Tag Description
<LOANMSGSET> Core message set for Loans
<LOANMSGSETV1> Version 1 of message set
<MSGSETCORE> Common message-set core
</MSGSETCORE>
<BANKMSGSRQV1>
<STMTTRNRQ> <!-- Begin request -->
<TRNUID>1001</TRNUID>
<STMTRQ> <!-- Begin statement request -->
<BANKACCTFROM> <!-- Identify the account -->
<BANKID>121099999</BANKID><!-- Routing transit or other
FI ID -->
<ACCTID>999988</ACCTID><!-- Account number -->
<ACCTTYPE>CHECKING</ACCTTYPE><!-- Account type -->
</BANKACCTFROM> <!-- End of account ID -->
<INCTRAN> <!-- Begin include transaction -->
<INCLUDE>Y</INCLUDE> <!-- Include transactions -->
</INCTRAN> <!-- End of include transaction -->
</STMTRQ> <!-- End of statement request -->
</STMTTRNRQ> <!-- End request -->
<BANKMSGSRSV1>
<STMTTRNRS> <!-- Begin response -->
<TRNUID>1001</TRNUID> <!-- Client ID sent in request -->
<STATUS> <!-- Start status aggregate -->
<CODE>0</CODE> <!-- OK -->
<SEVERITY>INFO</SEVERITY>
</STATUS>
<STMTRS> <!-- Begin statement response -->
<CURDEF>USD</CURDEF>
<BANKACCTFROM> <!-- Identify the account -->
<BANKID>121099999</BANKID><!-- Routing transit or other
FI ID -->
<ACCTID>999988</ACCTID><!-- Account number -->
<ACCTTYPE>CHECKING</ACCTTYPE><!-- Account type -->
</BANKACCTFROM> <!-- End of account ID -->
<BANKTRANLIST> <!-- Begin list of statement
trans. -->
<DTSTART>20051001</DTSTART><!-- Start date: Oct. 1, 2005 -->
<BANKMSGSRQV1>
<INTRATRNRQ> <!-- Begin request -->
<TRNUID>1001</TRNUID> <!-- Client's ID for this request -->
<INTRARQ> <!-- Begin transfer request -->
<XFERINFO> <!-- Begin transfer aggregate -->
<BANKACCTFROM> <!-- Identify the account -->
<BANKID>121099999</BANKID><!-- Routing transit or other
FI ID -->
<ACCTID>999988</ACCTID><!-- Account number -->
<ACCTTYPE>CHECKING</ACCTTYPE><!-- Account type -->
</BANKACCTFROM> <!-- End of account ID -->
<BANKACCTTO> <!-- Identify the account -->
<BANKID>121099999</BANKID><!-- Routing transit or other
FI ID -->
<ACCTID>999977</ACCTID><!-- Account number -->
<ACCTTYPE>SAVINGS</ACCTTYPE><!-- Account type -->
</BANKACCTTO> <!-- End of account ID -->
<TRNAMT>200.00</TRNAMT><!-- Amount of transfer -->
</XFERINFO> <!-- End of transfer aggregate -->
</INTRARQ> <!-- End of transfer request -->
</INTRATRNRQ> <!-- End request -->
</BANKMSGSRQV1>
</OFX> <!-- End of request data -->
<BANKMSGSRSV1>
<INTRATRNRS> <!-- Begin response -->
<TRNUID>1001</TRNUID> <!-- Client ID sent in request -->
<BANKMSGSRSV1>
<STPCHKTRNRS> <!-- Begin response -->
<TRNUID>1001</TRNUID> <!-- Client ID sent in request -->
<STATUS> <!-- Begin status aggregate -->
<CODE>0<CODE> <!-- OK -->
<SEVERITY>INFO</SEVERITY>
</STATUS> <!-- End of status aggregate -->
<STPCHKRS> <!-- Begin stop check response -->
<CURDEF>USD</CURDEF>
<BANKACCTFROM> <!-- Identify the account -->
<BANKID>121099999</BANKID><!-- Routing transit or other
FI ID -->
<ACCTID>999988</ACCTID><!-- Account number -->
<ACCTTYPE>CHECKING</ACCTTYPE><!-- Account type -->
The model is added on November 1 and scheduled to start on November 15. The model creates transfers of
$1000 from a checking to a savings account. The schedule is open-ended.
Because requests within a message set are not guaranteed to be executed in order, the client initially sends
two request files: one to create the model and another to collect any transfers generated by the model. The
second request file contains a simple transfer synchronization request.
<BANKMSGSRQV1>
<RECINTRATRNRQ> <!-- Begin request -->
<TRNUID>1001</TRNUID> <!-- Client's ID for this request -->
<RECINTRARQ> <!-- Begin request -->
<RECURRINST> <!-- Begin recurring aggregate -->
<FREQ>MONTHLY</FREQ> <!-- Monthly schedule -->
</RECURRINST> <!-- End recur aggregate -->
<INTRARQ>
<XFERINFO> <!-- Begin transfer aggregate -->
<BANKACCTFROM> <!-- Identify the account -->
<BANKID>121099999</BANKID><!-- Routing transit or other
FI ID -->
<ACCTID>999988</ACCTID><!-- Account number -->
<ACCTTYPE>CHECKING</ACCTYPE><!-- Account type -->
</BANKACCTFROM> <!-- End account ID -->
<BANKACCTTO> <!-- Identify the account -->
<BANKID>121099999</BANKID><!-- Routing transit or other
FI ID -->
<ACCTID>999977</ACCTID><!-- Account number -->
<ACCTTYPE>SAVINGS</ACCTTYPE><!-- Account type -->
</BANKACCTTO> <!-- End of account ID -->
<TRNAMT>1000.00</TRNAMT><!-- Amount of transfer-->
The response file shows that the model has been successfully created:
<BANKMSGSRSV1>
<RECINTRATRNRS> <!-- Begin response -->
<TRNUID>1001</TRNUID> <!-- Client ID sent in request -->
<STATUS> <!-- Start of status aggregate -->
<CODE>0</CODE> <!-- OK -->
<SEVERITY>INFO</SEVERITY>
</STATUS>
<RECINTRARS> <!-- Begin response -->
<RECSRVRTID>20000</RECSRVRTID><!-- Server assigned ID -->
<RECURRINST> <!-- Begin recurring aggregate -->
<FREQ>MONTHLY</FREQ> <!-- Monthly schedule -->
</RECURRINST> <!-- End of recurring aggregate -->
<INTRARS>
<CURDEF>USD</CURDEF?
<SRVRTID>20000</SRVRTID>
<XFERINFO> <!-- Begin transfer aggregate -->
<BANKACCTFROM> <!-- Identify the account -->
<BANKID>121099999</BANKID><!-- Routing transit or other
FI ID -->
<ACCTID>999988</ACCTID><!-- Account number -->
<ACCTTYPE>CHECKING</ACCTTYPE><!-- Account type -->
</BANKACCTFROM> <!-- End of account ID -->
<BANKACCTTO> <!-- Identify the account -->
<BANKID>121099999</BANKID><!-- Routing transit or other
FI ID -->
<ACCTID>999977</ACCTID><!-- Account number -->
Assuming that the server creates transfers 30 days prior to posting, the server returns status for one
pending transfer. This response comes back since the first transfer is scheduled to occur on November 15
and this date falls within 30 days of our session. Had the starting date been more than 30 days from our
signon date, the response would not have contained any pending transfers since the model would not have
generated any yet.
Suppose the customer does not attempt to connect between November 16 and January 1. When the
customer does attempt to connect, it is to cancel the recurring transfer model. The client also sets the
<CANPENDING> flag, causing any pending transfers to be immediately cancelled as well. In order to get
all synchronization information (since requests are not guaranteed to be executed in order), the client sends
two request files, the first to cancel the model and the next to retrieve all transfer activity. This time, the
recurring request is wrapped in synchronization wrappers. It should be assumed that the token below was
received in a previous RECPMTSYNCRS. (The use of synchronization wrappers in requests is entirely up
to the client. Both ways are shown here for explanatory purposes.)
<BANKMSGSRQV1>
<RECINTRASYNCRQ> <!-- Sync recurring transfers -->
<TOKEN>324789987</TOKEN> <!-- Token held by the client -->
<REJECTIFMISSING>Y</REJECTIFMISSING><!-- Cancel only if up to
date -->
<BANKACCTFROM>
<BANKID>121099999</BANKID>
<ACCTID>99998</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<RECINTRATRNRQ> <!-- Begin request -->
<TRNUID>1005</TRNUID> <!-- Client's ID for this request -->
<RECINTRACANRQ> <!-- Begin recur transfer cancel -->
<RECSRVRTID>20000</RECSRVRTID><!-- ID of the model -->
<CANPENDING>Y</CANPENDING><!-- Cancel pending transfers -->
</RECINTRACANRQ> <!-- End request -->
</RECINTRATRNRQ> <!-- End request -->
</RECINTRASYNCRQ> <!-- End of sync request -->
</BANKMSGSRQV1>
</OFX> <!-- End of request data -->
<BANKMSGSRSV1>
<RECINTRASYNCRS> <!-- Sync response -->
<TOKEN>324789988</TOKEN <!-- New token -->
11.14.5 Loans
The following are OFX fragments; the missing OFX is covered in other request/response examples.
• LOAN ACCOUNT INFORMATION
<LOANACCTINFO>
<LOANACCTFROM>
<LOANACCTID>123456789</LOANACCTID>
<LOANACCTTYPE>CONSUMER</LOANACCTTYPE>
</LOANACCTFROM>
<LOANTYPE>FIXED</LOANTYPE>
<LOANINITNUMPMTS>6</LOANINITNUMPMTS>
<LOANSMTTRNRQ>
<TRNUID>ABCDEF-12345-54321-FEDGBA</TRNUID>
<LOANSMTRQ>
<LOANACCTFROM>
<LOANACCTID>123456789</LOANACCTID>
<LOANACCTTYPE>CONSUMER</LOANACCTTYPE>
<LOANSMTTRNRS>
<TRNUID>ABCDEF-12345-54321-FEDGBA</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<LOANSMTRS>
<CURDEF>USD</CURDEF>
<LOANACCTFROM>
<LOANACCTID>123456789</LOANACCTID>
<LOANACCTTYPE>CONSUMER</LOANACCTTYPE>
</LOANACCTFROM>
<LOANTRANLIST>
<DTSTART>20050101120000</DTSTART>
<DTEND>20050325120000</DTEND>
<LOANSMTTRN>
<LOANTRNTYPE>PAYMENT</LOANTRNTYPE>
<DTPOSTED>20050208120000</DTPOSTED>
<TRNAMT>887.89</TRNAMT>
<LOANTRNAMT>
<PRINAMT>818.92</PRINAMT>
<INTAMT>33.97</INTAMT>
<INSURANCE>35.00</INSURANCE>
</LOANTRNAMT>
<FITID>A45GC86565
</LOANSMTTRN>
<LOANSMTTRN>
<LOANTRNTYPE>INT</LOANTRNTYPE>
<DTPOSTED>20050208120000</DTPOSTED>
<TRNAMT>33.97</TRNAMT>
<FITID>A45GE86565
</LOANSMTTRN>
<LOANSMTTRN>
<AMRTSMTTRNRQ>
<TRNUID>ABCDEF-12345-54321-FEDCBA</TRNUID>
<AMRTSMTTRNRS>
<TRNUID>ABCDEF-12345-54321-FEDCBA</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<AMRTSMTRS>
<CURDEF>USD</CURDEF>
<LOANACCTFROM>
<LOANACCTID>123456789</LOANACCTID>
<LOANACCTTYPE>CONSUMER</LOANACCTTYPE>
</LOANACCTFROM>
<DTSTART>20050101120000</DTSTART>
<DTEND>20050704120000</DTEND>
<AMRTSMTTRN>
<PMTNUMBER>1</PMTNUMBER>
<LOANINITBAL>5000.00</LOANINITBAL>
<PRINBAL>
<BALAMT>4181.08</BALAMT>
<DTASOF>20050208120000</DTASOF>
</PRINBAL>
<LOANTRNAMT>
<PRINAMT>818.92</PRINAMT>
<INTAMT>33.97</INTAMT>
<INSURANCE>35.00</INSURANCE>
</LOANTRNAMT>
<LOANIRATE>
<LOANINTRATE>8</LOANINTRATE>
<RATETYPE>FLOATING</RATETYPE>
<DTASOF>20050101120000</DTASOF>
</LOANIRATE>
<AMRTTYPE>ADJUSTED</AMRTTYPE>
<LOANSTMTENDTRNRQ>
<TRNUID>ABCDEF-12345-54321-FEDCCBA</TRNUID>
<STATUS>
<CODE>0</CODE>
<LOANSTMTENDTRNRS>
<TRNUID>ABCDEF-12345-54321-FEDCCBA</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<LOANSTMTENDRS>
<CURDEF>USD</CURDEF>
<LOANACCTFROM>
<LOANACCTID>123456789</LOANACCTID>
<LOANACCTTYPE>CONSUMER</LOANACCTTYPE>
</LOANACCTFROM>
<LOANCLOSING>
<FITID>1234</FITID>
<DTOPEN>20050104120000</DTOPEN>
<DTCLOSE>20050207120000</DTCLOSE>
<DTNEXT>20050304120000</DTNEXT>
<BALOPEN>5000.00</BALOPEN>
<PRINBAL>
<BALAMT>4181.08</BALAMT>
<PRINYTD>818.92</PRINYTD>
<PRINLTD>818.92</PRINLTD>
<DTASOF>20050208120000</DTASOF>
</PRINBAL>
<LOANINT>
<LOANINTYTD>33.97</LOANINTYTD>
<LOANINTLTD>33.97</LOANINTLTD>
<LOANINTPRJ>116.04</LOANINTPRJ>
Clients use payment requests to schedule payments and to modify or delete payments if necessary. OFX
also supports business payments, as described in section 12.1.
The recurring payments function allows the client to schedule automatic generation of a series of recurring
payments by means of a single request. As with individual payments, the client can modify or delete these
requests.
The payments function incorporates the synchronization features of OFX, allowing multiple client
applications to synchronize with the server to obtain the current status of all payment transactions known
to the server.
In many international environments, payments are performed using interbank funds transfers. OFX
Payments supports this by allowing a payee to be designated as a destination bank account. Servers can
implement these messages as transfers where appropriate.
OFX requires payee identifiers to have a one-to-one relationship with the corresponding <PAYEE>
information. In other words, different payee IDs must also differ in their corresponding payee billing
description or payee name <NAME>. Similarly, a payee ID must be independent of a user’s account
number with the payee. However, the payment system is free to use the user’s account number in
combination with the payee ID to determine the routing of a payment. These rules are intended to simplify
the payee model for the user, insuring that different payee IDs will have discernibly different descriptions
associated with them. They also insure that the user will not be required to maintain multiple payee entries
for a payee with which the user holds multiple accounts.
OFX includes an element for indicating the scope of a payee ID returned from the server. This allows
clients to adapt by expanding or restricting their functionality depending on the scope of payee IDs it
encounters.
A payee list for each user, maintained on the server, allows the server to manage the identifiers assigned to
a user’s payees. This functionality is described in section 12.2.2.
Some payment systems require a first time setup before using a payee. This can occur externally to the
client and server software, for example by filling out a paper form or telephoning the bank. In this case,
payee list synchronization provides a way for the payee to become accessible to the client software when
the FI completes the setup.
The list can contain payees with or without payee IDs. An important function of the payee list is to
communicate payee changes from the server to the client. This includes changes in processing date
parameters and conversion of a payee to a standard payee.
Once added to the list, the payment system makes payments by the payee list ID. This makes it clear to a
client when the user is adding to a payee list, and when he or she modifies an existing payee on the list.
Although the messages make it clear whether a client is trying to add a new payee, a careful server will
check for exact matches on payee adds and not create new payee list entries unnecessarily.
Each payee entry in the list can also include a list of the user’s accounts with that payee. This further
reduces the data entry required by a user to make a payment, and facilitates the implementation of
lightweight clients.
For a single account, it is important that references to a payee by <PAYEELSTID> do not resolve to
different physical payees if the account is being used by more than one user. The same <PAYEELSTID>
must map to the same corresponding payee billing description and payee name <NAME>. For example,
<PAYEELSTID>12345 may be used for ABC Rentals for one user of a single account. If the same account
is used for a second user, <PAYEELSTID>12345 cannot be used for XYZ Supplies. Conversely, if two or
more users share an account, any duplicated payees in each payee list must map to the same
<PAYEELSTID>. Servers must ensure the integrity of the payee list for shared accounts, either by issuing
a different userid for such accounts or by issuing payee and payment deletes followed by payee and
payment adds to correct the payee list and update the payment history when two payee lists are merged. In
the latter case, payees added by each user must be reconciled with the shared payee list on an ongoing
basis.
When a payment system includes a standard payee list, it might be desirable to present the list to the user,
who can then select payees he or she wants to pay. Unfortunately, it is cumbersome to provide this
functionality in the client software due to the potential size of this list, which makes it problematic to keep
updated and to present to the user. While the list can contain thousands of payee entries, a user will
typically need less than ten or twenty entries from the list. It can also be difficult for a user to choose the
correct payee entry when the list contains a number of similarly named payees.
Therefore, OFX does not provide a mechanism for delivering these lists to the client. However, there are
several ways that an external presentation of such a list can be integrated into the client or server. For
example, a payment provider’s Web site could present a search engine that assists the user to locate the
correct payee. Once identified, the payees can either be imported into the client, or inserted into the user’s
payee list on the server. In the latter case, synchronizing the payee list will make the newly added payees
visible to the client.
Note: Duplicate payee list entries can occur if clients are not careful to send the payee list ID
in subsequent requests.
• Standard payee ID <PAYEEID> for any payee that has been assigned a standard payee ID. This could
happen before a closed system makes any payments, or anytime after the server has notified the client
that a payee has a standard payee ID. If a <PAYEELSTID> also exists for the payee, it is required in the
request and response, in addition to the <PAYEEID>.
Note: Servers must always assign <PAYEELSTID>s to payees. Once <PAYEELSTID>s have
been assigned, clients must always send the <PAYEELSTID>, even if a payee has both a
<PAYEEID> and a <PAYEELSTID>.
Payees are modified either implicitly or explicitly. Explicit changes occur by executing a
<PAYEEMODRQ>. Implicit payee changes occur with the execution of a <PMTRQ>, <PMTMODRQ>,
<RECPMTRQ>, or <RECPMTMODRQ>, if the payee list ID is sent along with the payee aggregate. In
<BILLPAYMSGSETV1>, a <PAYEE> aggregate must accompany these requests. In such cases, since the
<PAYEELSTID> is present, a server may check to see if the payee information has changed, and only if
so, process an implicit payee modification. An implicit payee change must cause the server to create and
store a <PAYEEMODRS>, to be returned to the client in subsequent payee synchronization responses.
Since the change was not generated by an explicit request, the <TRNUID> in these responses will be zero.
In addition to the above, a payee change (implicit or otherwise) may also affect models and their future
(though not pending) payments. Thus, for any model that is affected by an explicit or implicit payee
modification, the server must create and store a <RECPMTMODRS>, to be returned to the client in
subsequent recurring payment synchronization responses. The <TRNUID> in this response will be zero.
The client-to-request messages assign the Transaction Universal Identifier <TRNUID>. Its purpose is to
allow the client to easily match responses from the server to their corresponding requests. A given
transaction ID is used only for a client request and the corresponding server response.
The Server Identifier, <SRVRTID> or <RECSRVRTID>, is assigned by the server to a payment “object,”
which can either be a payment or a recurring payment model (in which case it is named
<RECSRVRTID>). Both the client and server use the ID thereafter to refer to the payment or model in any
transactions that operate on them. For example, the <SRVRTID> is used to identify a payment in a request
to modify or cancel it. The <SRVRTID> is valid for the life span of the payment within the payment
system. Similarly the <RECSRVRTID> is valid as long as the associated model exists, that is until the
model generates all payments, or the model is canceled. Once a server processes a payment or a model
generates all its required payments, the associated <SRVRTID> (or <RECSRVRTID>) is no longer known
to the server. Note that the payment system might continue to maintain knowledge of a payment
<SRVRTID> or model <RECSRVRTID> for some specified period after it completes processing. This
allows clients to access the “completed” status of these operations.
The Payee List Identifier <PAYEELSTID> is assigned by the server to each entry in a user’s server-hosted
payee list. The need for this identifier is to support the variety of payee models employed in various
payment systems. As discussed above, some payment systems assign a payee identifier <PAYEEID> to
every payee (this is particularly the case with pay-some systems); others assign <PAYEEID>s only to
standard payees. There are also systems that cannot map a payee billing address to a <PAYEEID> in real
time. Also, there are systems that can convert a payee from a standard payee with an assigned <PAYEEID>
to one that is identified only by billing address. Therefore, systems employ the <PAYEELSTID> to insure
that, in systems where payees will not always have a <PAYEEID>, there is another identifier that can be
used to reference every payee. This insures that a client can correctly link payments to their payees. The
<PAYEELSTID> must be valid as long as the user’s payee list includes the payee it identifies, even if the
server subsequently assigns a <PAYEEID> to the payee. In order to ensure that <PAYEELSTID>s are
unambiguous to the client, <PAYEELSTID> must be unique for all classes of a particular <SPNAME> and
<USERID>. Therefore, a given payment provider may use <PAYEELSTID>12345 to refer to ABC
Rentals for one <USERID>, and XYZ Cable for a different <USERID>. Likewise, a client cannot assume
that <PAYEELSTID>54321 at payment provider 1 will refer to the same payee as <PAYEELSTID>54321
at payment provider 2.
Note: If a service provider allows the sharing of accounts between users, the scope of
<PAYEELSTID> must be stricter than that described above. For a single account it is important
that references to a payee by <PAYEELSTID> do not resolve to more than one physical payee.
The same <PAYEELSTID> must map to the same corresponding payee billing description and
payee name <NAME>. For example, <PAYEELSTID>12345 may be used for ABC Rentals for
one user of an account. If the same account is used for a second user, <PAYEELSTID>12345
cannot be used for XYZ Supplies. Conversely, if two or more users share an account, any
duplicated payees in each payee list must map to the same <PAYEELSTID>. Servers must
ensure the integrity of the payee list for shared accounts, either by issuing a different userid for
such accounts or by issuing payee and payment deletes followed by payee and payment adds to
correct the payee list and update the payment history when two payee lists are merged. In the
latter case, payees added by each user must be reconciled with the shared payee list on an
ongoing basis
The server will look up the payee in the user’s payee list. If it is not already in the table, the server will add
it and issue a payee list identifier <PAYEELSTID>. This form of payment request performs an implicit
Payee Request <PAYEERQ>, which is equivalent to explicitly adding the payee (by means of a
<PAYEERQ>), prior to issuing the <PMTRQ>. It has the advantage of being atomic. If the payment
request fails, the payee is not added to the user’s payee list. Conversely the payment request will fail if the
payee information is invalid.
The server responds to the <PMTRQ> with a Payment Response <PMTRS>. Some servers will not be able
to immediately return a payee ID at this point, or might not issue payee IDs for all payees. Therefore the
<PAYEELSTID> contained in the response functions as the linkage between the payee and the payment.
Payment systems use the <SRVRTID> returned in the <PMTRS> to identify the payment for the length of
its instantiation on the payment system.
Note: Servers should generate explicit responses to implicit requests. In other words, implicit
payee additions or modifications resulting from a new or changed payment should generate
explicit payee add or payee change responses from the server. Such explicit responses are only
returned to the client in a SYNC response. If the payment transactions containing implicit
payee additions or modifications fail, then the payee actions are not executed, since such a
compound payment transaction represents a single unit of work (comprised of both payee and
payment actions).
Full-featured servers will use <PMTMODRS> messages, conveyed to the client during synchronization
<PMTSYNCRS>, to inform the client about changes in the state of the client that occur due to server
processing. This would include reporting the date the server actually processed a payment, or it failed due
to insufficient funds. Servers that are unable to generate <PMTMODRS> responses for this purpose must
support the <PMTINQRQ> message described below.
When a payment system cancels a payment, servers can generate a <PMTCANCRS>. This might occur if
the user requests payment cancellation by way of a telephone call to customer support or through an e-mail
message. The client will receive this response when performing a payment synchronization
<PMTSYNCRQ>/<PMTSYNCRS>.
Tag Description
<BPACCTINFO> Payments-account-information aggregate
<BANKACCTFROM> Bank-account-from aggregate, see section 11.3.1
</BANKACCTFROM>
In the case of an implicit add, the returned <PMTINFO> aggregate found in <PMTRS> and
<RECPMTRS> must include the generated <PAYEELSTID>. This aggregate may also include
<EXTDPMT> information.
The <DTDUE> in a response may have been adjusted by a server. For example, the server may adjust
<DTDUE> to comply with non-processing days. If a client sends a request to make a transfer on July 4 and
July 4 happens to be a non-processing day, the <DTDUE> in the response may be July 4 (because the
server hasn’t adjusted it yet), July 5 (because this server rolls dates forward), or some other date.
Tag Description
<PMTINFO>
Note: If the client user interface has a single field that can contain either free-
form memo text or a structured reference number, then the contents of that field
should be passed in the <MEMO> element rather than the <BILLREFINFO>
element.
<BILLPUBINFO> Bill publisher information aggregate for the payment
<BILLPUB> Name of the bill publisher associated with this payee for this payment at the service
provider, A-32
<BILLID> ID of the bill assigned by the bill presentment service provider to which this
payment is being applied, A-32
</BILLPUBINFO>
</PMTINFO>
Tag Description
<PAYEE>
The Extended Payment aggregate provides the payee with information for applying a payment across
multiple invoices. It is structured to allow for electronic processing of the invoice data, and allows multiple
invoices, as well as multiple line items per invoice, to be specified.
In this case, <EXTDPMT> can specify a block of free text to be transmitted with the payment, by using the
<EXTDPMTDSC> instead of the <EXTDPMTINV> element.
Tag Description
<EXTDPMT> Extended Payment aggregate
<EXTDPMTFOR> INDIVIDUAL or BUSINESS. Indicates whether the payment is for an individual
or business account. This allows the payment processor to remit payments to the
appropriate address for consumers or businesses.
<EXTDPMTCHK> Check number to use for this payment. Overrides “next check in range.” N-10
</EXTDPMTINV>
</EXTDPMT>
Tag Description
<INVOICE> Start tag for the invoice aggregate. There can be one or more invoices per
payment request.
<INVNO> Invoice number associated with the payment. A-32
<INVTOTALAMT> This value represents the total invoice amount, amount
This amount should be specified as a positive number
<INVPAIDAMT> This value represents the amount of the invoice being paid, amount
This amount should be specified as a positive number
<INVDATE> Date to apply the invoice, datetime
<INVDESC> Invoice description, A-80
<DISCOUNT> Discount aggregate; only one discount aggregate per invoice
<DSCRATE> Discount rate, rate
<DSCAMT> Discount amount, amount
This amount should be specified as a positive number
<DSCDATE> Date to apply the discount, datetime
<DSCDESC> Discount description, A-80
</DISCOUNT>
<ADJUSTMENT> Adjustment aggregate; only one adjustment aggregate per invoice, see 12.5.2.4
</ADJUSTMENT>
<LINEITEM> Line item aggregate; there can be multiple line items per invoice, see 12.5.2.5
</LINEITEM>
</INVOICE>
Tag Description
<ADJUSTMENT>
12.5.2.5 <LINEITEM>
Tag Description
<LINEITEM> Line item aggregate; there can be multiple line items per invoice
<LITMAMT> Amount of the line item, amount
This amount should be signed + or -, as appropriate. A positive line item amount
is an addition to the payment amount, and a negative line item is a discount or
reduction in the payment amount.
<LITMDESC> Line item description, A-80
</LINEITEM>
The Extended Payee aggregate communicates a payee identifier to the client. It also contains the
processing day parameters for a payee. It can be sent to the client for any payee whose processing day
parameters are different from the processor’s default values, even for payees with no <PAYEEID>.
Tag Description
<EXTDPAYEE> Extended-payee aggregate
<PAYEEID> Server-assigned payee ID, A-12
If <PAYEEID> is present, <IDSCOPE> and <NAME> are required. Should not be
included unless the payee is a standard payee.
<IDSCOPE> Scope of the payee ID; one of (GLOBAL, USER), where
GLOBAL = payee ID valid across the entire payment system
USER = payee ID valid with all FI accounts set up for the user’s payments account
Required if <PAYEEID> is present.
<NAME> Standard payee name, A-32
Required if <PAYEEID> is present.
<DAYSTOPAY> Minimum number of business days needed to process, N-3
</EXTDPAYEE>
The Payment Processing Status aggregate contains the current processing status for a payment. This
aggregate is intended to describe status changes to the associated payment after creation. The interpretation
of the date value depends on the value of <PMTPRCCODE>.
Tag Description
<PMTPRCSTS>
Account information
Payment date
Amount
Payment status
Check number
Server-assigned ID
From the time the client issues a Payment Request until it is paid, the client can modify the transaction
through the Payment Modification Request, <PMTMODRQ>; see section 12.4.2. This request allows
payment parameters such as the payment date and payment amount to be changed.
Account information
Server-assigned ID
Information to change:
Payment date,
Amount,...
Acknowledgment or Error
The client can cancel a Payment Request with a Payment Cancellation Request, <PMTCANCRQ>; see
section 12.4.4.
Account information
Server-assigned ID
Acknowledgment or Error
Tag Description
<PMTRQ> Payment-request aggregate
<PMTINFO> Payment Information aggregate, see section 12.5.2
</PMTINFO>
</PMTRQ>
Note: If the <PMTRQ> created a new payee or modified an existing one, the server must
create and store a payee response that would be available for subsequent payee synchronization
requests. In addition, the server should be aware of the fact that implicit payee modifications
may affect models. Such changes to models must also appear in subsequent recurring
synchronization responses. In all cases, the server need only send the <PMTRS> as a response
to the <PMTRQ>, but any implicit payee and recurring changes must be made by the server,
and be returned in later synchronization responses. See section 12.2.5 for further discussion of
implicit payee adds and modifications.
The server sends a Payment Response in response to a Payment Request. The processing status code for a
new payment is normally WILLPROCESSON, but in the case of synchronization it can return other status
codes. Servers should inform clients of any errors found while processing this transaction using the
<STATUS> aggregate. A response containing <STATUS><CODE>0 and
<PMTPRCSTS><PMTPRCCODE>FAILEDON should be avoided for problems such as an invalid
account or amount.
Note: When processing a <PMTRQ> request that does not contain a <PAYEEID> or
<PAYEELSTID>, a server may check the payee against the user's current payee list and return
the found <PAYEELSTID> and <PAYEEID> (if any). If the server does this, it should only
find a match when all <PAYEE> data, including all <PAYACCT> elements, match exactly. If
the <PAYACCT> or any other element is different, the server must perform an implicit payee
addition. If a server doesn’t check for duplicate payees, a client could show duplicate entries in
the payee list.
Tag Description
<PMTRS> Payment-response aggregate
<SRVRTID> ID assigned by the server to the payment being created, SRVRTID
<PAYEELSTID> Server-assigned payee list record ID for this payee, A-12
Note: This identifier must match that found (and required) in the
returned <PMTINFO>.
<CURDEF> Default currency for the Recurring Payment Response, currsymbol
<PMTINFO> Payment Information aggregate, see section 12.5.2
</PMTINFO>
Code Meaning
0 Success (INFO)
Once the server has assigned a payee identifier <PAYEEID> to the payee, it includes the <EXTDPAYEE>
in any <PMTRS> for that transaction. If the <EXTDPAYEE> aggregate is present in the Payment
Response <PMTRS>, the client records the standard payee information for use in future payments to the
same payee.
When a payment is made using the <PAYEE> aggregate, and no <PAYEELSTID> is present, the payee is
implicitly added to the payee list. This is therefore equivalent to first transmitting a <PAYEERQ> for the
payee. For payment systems that can immediately return payee IDs, it is preferable to use the single
<PMTRQ> message to both add the payee and create the payment. If either operation fails, the server will
not complete the other.
The <PMTRS> response will include the <EXTDPAYEE> aggregate if the processor has assigned a payee
ID to the payee specified in the payment. It will also appear in the response when the payee has no
assigned ID, but has processing day parameters that different from the processor’s defaults for these
values. This might occur, for instance, if the processor notes that the postal code of the payee indicates a
certain proximity to the payer, and therefore wishes to offer a shorter <DAYSTOPAY> value.
Value Description
The client sends a Payment Modification Request to request modification of a payment. The client must
provide the full <PMTINFO> including both changed and unchanged values.
The client may modify any data in <PMTINFO> except the recipient or funding account. In particular,
payee list ID <PAYEELSTID>, payee ID <PAYEEID>, funding bank account <BANKACCTFROM>, and
the <NAME> element of <PAYEE> must match that returned in the original <PMTRS>. Implicit payee
modifications (changes in address information for example) are allowed.
If the <PMTMODRQ> caused a payee modification to an existing payee, the server must create and store
a <PAYEEMODRS> to be returned in subsequent payee synchronization responses. If the
<PMTMODRQ> created a new payee (possible only if the payment were originally created outside of the
OFX protocol), the server must, similarly, create and store a <PAYEERS> for later payee synchronization
responses. In addition, the server should be aware of the fact that implicit payee modifications may affect
models. Such changes to models must also appear in subsequent recurring synchronization responses. In
all cases, the server need only send the <PMTMODRS> as a response to the <PMTMODRQ>, but any
implicit payee and recurring changes must be made by the server, and be returned in later synchronization
responses. See section 12.2.5 for further discussion of implicit payee adds and modifications.
Tag Description
<PMTMODRQ> Modification-request this references
<SRVRTID> ID assigned by the server to the payment being modified, SRVRTID
<PMTINFO> Payment Information aggregate, see section 12.5.2
</PMTINFO>
</PMTMODRQ>
The server sends a Payment Modification Response in response to a Payment Modification Request.
Tag Description
<PMTMODRS> Payment-modification-response this references
<SRVRTID> ID assigned by the server to the payment being modified, SRVRTID
<PMTINFO> Payment Information aggregate, see section 12.5.2
</PMTINFO>
</PMTMODRS>
Code Meaning
0 Success (INFO)
2000 General error (ERROR)
2002 General account error (ERROR)
2006 Source account not found (ERROR)
2007 Source account closed (ERROR)
2008 Source account not authorized (ERROR)
2009 Destination account not found (ERROR)
2010 Destination account closed (ERROR)
2011 Destination account not authorized (ERROR)
2012 Invalid amount (ERROR)
2014 Date too soon (ERROR)
2015 Date too far in future (ERROR)
2016 Transaction already committed (ERROR)
2017 Already canceled (ERROR)
2018 Unknown server ID (ERROR)
2019 Duplicate request (ERROR)
6502 Unable to process embedded transaction due to out-of-date <TOKEN> (ERROR)
10501 Invalid payee (ERROR)
10502 Invalid payee address (ERROR)
10503 Invalid payee account number (ERROR)
10505 Cannot modify element (ERROR)
10510 Invalid payee ID (ERROR)
10511 Invalid payee city (ERROR)
10512 Invalid payee state (ERROR)
10513 Invalid payee postal code (ERROR)
10514 Transaction already processed (ERROR)
10517 Invalid payee name (ERROR)
10519 Invalid payee list ID (ERROR)
Servers can initiate <PMTMODRS> messages to communicate changes in the processing status of a
payment as it moves through the payment system. This mechanism allows a client to capture the updated
status of payments every time it synchronizes.
Implicit payee changes contained in a payment modification transaction do not affect any other existing
pending payments. The changes are propagated to the server’s payee list and affect payments to that payee
as subsequently initiated by the client after the change, or as subsequently spawned from a recurring
model. Explicit payee changes are not propagated to payments pending for the changed payee at the time
of the change.
Servers cannot initiate <PMTCANCRS> when communicating status changes. This response should be
used only when a payment was actually cancelled (by an OFX client or at users request via the phone).
When conveying information about a failure in payment processing (such as insufficient funds), a
<PMTMODRS> (with the updated <PMTPRCSTS>) should be added to the next <PMTSYNCRS>
download.
Tag Description
<PMTCANCRQ> Cancellation-request this references
<SRVRTID> ID assigned by the server to the payment being cancelled, SRVRTID
</PMTCANCRQ>
The server sends a Payment Cancellation Response in response to a Payment Cancellation Request.
Tag Description
<PMTCANCRS> Cancellation-response this references
<SRVRTID> ID assigned by the server to the payment being canceled, SRVRTID
</PMTCANCRS>
Code Meaning
0 Success (INFO)
The client sends a Payment Status Inquiry Request to obtain the current processing status of a payment.
Tag Description
<PMTINQRQ> Payment-status-inquiry-request aggregate
<SRVRTID> ID assigned by the server to the payment being queried, SRVRTID
</PMTINQRQ>
The server sends a Payment Status Inquiry Response in response to a Payment Status Inquiry Request.
Tag Description
<PMTINQRS> Payment-status-inquiry-response aggregate
<SRVRTID> ID assigned by the server to the payment being queried, SRVRTID
<PMTPRCSTS> Payment processing status
</PMTPRCSTS>
Code Meaning
0 Success (INFO)
Note: As with individual payments, if the recurring payment request adds a payee or changes
payee information, the server must create and store a payee response, to be returned in
subsequent payee synchronization responses. Furthermore, implicit payee modifications may
affect other models (but not their pending payments). The server must also create and store
recurring modification responses for these models, to be returned in subsequent recurring
synchronization responses. See section 12.2.5 for further discussion of implicit payee adds and
changes.
Note: The <MODELWND> profile value indicates when the server spawns a payment. If
<MODELWND>0 is specified, the server only spawns one payment at a time for each model.
In other words, there is always one pending payment per model, unless the model has expired.
If <MODELWND> is greater than 0, its value is the number of days before a payment is due to
be paid that it is spawned from the model. In this case, it is possible to have zero or more
pending payments instantiated at a time.
Account information
Payment frequency
Number of payments
Payment date
Amount
Server-assigned ID
The table below lists the functional elements for modifying a recurring payment:
Account information
Server-assigned ID
Information to change:
Payment frequency,
Number of payments,
Payment date,
Amount,...
Acknowledgment or Error
The table below lists the functional elements for canceling a recurring payment:
Account information
Server-assigned ID
Acknowledgment or Error
Tag Description
<RECPMTRQ> Recurring-payment-request aggregate
<RECURRINST> Recurring Instructions aggregate, see section 9.2.
</RECURRINST>
<INITIALAMT> Amount of the initial payment, if different than the following payments, amount
This amount should be specified as a positive number
<FINALAMT> Amount of the final payment, if different than the preceding payments, amount
This amount should be specified as a positive number
</RECPMTRQ>
The server sends a Recurring Payment Response upon receipt of a Recurring Payment Request.
Tag Description
<RECPMTRS> Recurring-payment-response aggregate
<RECSRVRTID> Server-assigned ID for this transaction, SRVRTID
<PAYEELSTID> Server-assigned record ID for this payee record, A-12
Note: This identifier must match that found (and required) in the returned
<PMTINFO>.
<CURDEF> Default currency for the Recurring Payment Response, currsymbol
<RECURRINST> Recurring-instructions aggregate, see section 9.2.
</RECURRINST>
<INITIALAMT> Amount of the initial payment, if different than the following payments, amount
This amount should be specified as a positive number
<FINALAMT> Amount of the final payment, if different than the preceding payments, amount
This amount should be specified as a positive number
<EXTDPAYEE> Extended payee information, see section 12.5.2.6.
</EXTDPAYEE>
</RECPMTRS>
Code Meaning
0 Success (INFO)
The <DTDUE> element of <PMTINFO> specifies payment due date or the date by which the first
payment must be received by payee (see section 12.5.2).
The <DTDUE> in a response may have been adjusted by a server. For example, the server may adjust
<DTDUE> to comply with non-processing days. If a client sends a request to make a transfer on July 4 and
July 4 happens to be a non-processing day, the <DTDUE> in the response may be July 4 (because the
server hasn’t adjusted it yet), July 5 (because this server rolls dates forward), or some other date. For this
reason, a client should pay attention to the <DTDUE> in the response.
The client sends a Recurring Payment Modification Request to request changes to a recurring payment
model.
The client may modify any data in <PMTINFO> except the recipient or funding account. In particular,
payee list ID <PAYEELSTID>, payee ID <PAYEEID>, funding bank account <BANKACCTFROM>, and
the <NAME> element of <PAYEE> must match that returned in the original <RECPMTRS>. Implicit
payee modifications (changes in address information for example) are allowed. Clients can modify both
elements in the <RECURRINST> aggregate (i.e. <NINSTS> and <FREQ>). Client should send the
original number of payments scheduled if there is no change. If there is a change in the number of
payments scheduled, clients should send the new number of payments.
A <RECPMTMODRQ> that modifies pending payments via the <MODPENDING> flag is a compound
transaction and the server should create and store <PMTMODRS>s, which are returned to the client in
subsequent payment synchronization responses. For example, a change to the <TRNAMT> element would
cause the server to create and store a <PMTMODRS> for each pending payment, to be returned in a
subsequent payment synchronization response. Changes to payment information apply to all future
payments.
Tag Description
<RECPMTMODRQ> Modification-request aggregate
<RECSRVRTID> ID assigned by the server to the payment being modified, SRVRTID
<RECURRINST> Recurring Instructions aggregate, see section 9.2
</RECURRINST>
<INITIALAMT> Amount of the initial payment, if different than the following payments, amount
This amount should be specified as a positive number
<FINALAMT> Amount of the final payment, if different than the preceding payments, amount
This amount should be specified as a positive number
<MODPENDING> Modify pending flag
If the client sets this flag, the server must modify pending and future payments, Boolean
</RECPMTMODRQ>
The server sends a Recurring Payment Modification Response in response to a Recurring Payment
Modification Request.
Tag Description
<RECPMTMODRS> Modification-response aggregate
<RECSRVRTID> ID assigned by the server to the payment being modified, SRVRTID
<RECURRINST> Recurring-Instructions aggregate, see section 9.2
</RECURRINST>
<INITIALAMT> Amount of the initial payment, if different than the following payments, amount
This amount should be specified as a positive number
<FINALAMT> Amount of the final payment, if different than the preceding payments, amount
This amount should be specified as a positive number
<MODPENDING> Y if the client requested that the server modify pending and future payments. N if the
client did not request that the server modify pending and future payments., Boolean
</RECPMTMODRS>
Code Meaning
0 Success (INFO)
2000 General error (ERROR)
2002 General account error (ERROR)
2006 Source account not found (ERROR)
2007 Source account closed (ERROR)
2008 Source account not authorized (ERROR)
2009 Destination account not found (ERROR)
2010 Destination account closed (ERROR)
2011 Destination account not authorized (ERROR)
2012 Invalid amount (ERROR)
2014 Date too soon (ERROR)
Tag Description
<RECPMTCANCRQ> Cancellation-request aggregate
<RECSRVRTID> ID assigned by the server to the payment being canceled, SRVRTID
<CANPENDING> Cancel pending flag, Boolean
If Y, server should cancel all pending and unspawned payments. If N, server should
cancel only the model (and unspawned payments).
</RECPMTCANCRQ>
The server sends a Recurring Payment Cancellation Response in response to a Recurring Payment
Cancellation Request.
Tag Description
<RECPMTCANCRS> Modification-request aggregate
<RECSRVRTID> ID assigned by the server to the payment being modified, SRVRTID
<CANPENDING> Cancel pending flag, Boolean
Y if the client requested that the server cancel all pending and unspawned payments. N
if the client requested that the server cancel only unspawned payments.
</RECPMTCANCRS>
Code Meaning
0 Success (INFO)
Note: There is no way to indicate non-support of payment e-mail in the profile. A server that
doesn’t support <PMTMAILSYNCRQ> should return an “empty” payment mail sync response
rather than just ignore the request. This empty sync response includes <TOKEN>0 and no
history.
The <PMTMAILRQ> allows a client to issue an e-mail to the payments processor. If the message refers to
a specific payment, then both <SRVRTID> and <PMTINFO> are required to identify the payment to the
processor.
Tag Description
<PMTMAILRQ> Payment e-mail-request aggregate
<MAIL> General e-mail aggregate
</MAIL>
<SRVRTID> Transaction ID of the payment that is the subject of the correspondence, SRVRTID
<PMTINFO> Payment Information aggregate, see section 12.5.2
</PMTINFO>
</PMTMAILRQ>
Tag Description
<PMTMAILRS> Payment e-mail-response aggregate
<MAIL> General e-mail aggregate, see Chapter 10, "Customer to FI Communication."
</MAIL>
<SRVRTID> Transaction ID of the payment that is the subject of the correspondence, SRVRTID
<PMTINFO> Payment Information aggregate, see section 12.5.2
</PMTINFO>
</PMTMAILRS>
Code Meaning
0 Success (INFO)
Tag Description
<PMTMAILSYNCRQ> Synchronization-request aggregate
</PMTMAILSYNCRQ>
Tag Description
<PMTMAILSYNCRS> Synchronization-response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry in the
server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a token in the
server’s history table. Boolean
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</PMTMAILSYNCRS>
A server-assigned payee list-entry ID identifies entries in the payee list. The following set of messages
allows clients to obtain this list of payees. Users can add, modify, and delete individual entries in the list.
The user-defined Payee list is subject to synchronization, so that multiple clients can use the list.
Creating a payee:
Server-assigned payee
identifier, or payee billing
address
Payee address
Server-assigned payee
identifier
Information to change:
payee name
address
city
state
postal code
phone number
Acknowledgment or Error
Deleting a payee:
Server-assigned payee
identifier
User’s account number
with the payee
Acknowledgment or Error
The <PAYEERQ> requests the addition of a payee entry to the server’s payee list. Note that the user can
use a <PMTRQ> to simultaneously set up a payee. OFX does not require the client to send a <PAYEERQ>
before making an initial <PMTRQ> to a payee.
Tag Description
<PAYEERQ> Payee-request aggregate
<BANKACCTTO> The destination bank account (see section 11.3.1), specified in countries that pay using
transfers. The <PAYEE> (above) must also be specified.
</BANKACCTTO>
The server sends the Payee Response in response to a Payee Request. It contains the full billing
information for the payee if it is not a standard payee. Otherwise, it contains the standard payee
information, including lead time and payee name. If the server identifies the payee as having an assigned
payee ID, then the server will include the <EXTDPAYEE> aggregate in the response.
If the response indicates that the payee does not have an assigned <PAYEEID>, the client should specify
the full billing address <PAYEE> information in subsequent payment requests to that payee or when that
payee is being modified. Otherwise the <PAYEEID> is used in lieu of the <PAYEE> aggregate.
If the response indicates that the payee does have a <PAYEEID>, then the client should use the
<PAYEEID> for making payments to that payee.
Tag Description
<PAYEERS> Payee-response aggregate
<PAYEELSTID> Server-assigned record ID for this payee record, A-12
<PAYEE> Complete payee billing information, see section 12.5.2.1.
</PAYEE>
<BANKACCTTO> The destination bank account (see section 11.3.1), specified in countries that pay using
transfers. The <PAYEE> (above) must also be specified.
</BANKACCTTO>
Code Meaning
0 Success (INFO)
The client sends the Payee Modification Request to request changes to an existing payee list entry. The
<PAYEE> aggregate must specify the changed and unchanged payee information. Absence of a
<PAYACCT> in a <PAYEEMODRQ> could be interpreted as an implicit disassociation of the
<PAYACCT> with the payee. Presence or absence of a <PAYACCT> does not imply selective <PAYEE>
aggregate changes for the same <PAYEELSTID> as referenced by more than one <PAYACCT>. The
<PAYEEMODRQ> request must appear within a <PAYEETRNRQ> transaction wrapper.
Tag Description
<PAYEEMODRQ> Modification-request aggregate
<PAYEELSTID> Server-assigned record ID for this payee record, A-12
<PAYEE> Payee information to modify
</PAYEE>
<BANKACCTTO> Destination account (see section 11.3.1) for countries that pay using transfers
(<PAYEE> required)
</BANKACCTTO>
The server returns a Payee Modification Response in reply to a Payee Modification Request.
When a server-initiated change occurs to the extended payee information for a payee (for example a
change in the payee’s lead-time), the server can include this information in the <EXTDPAYEE> of the
response.
If a server-initiated response indicates either that a payee now has a payee ID, or no longer has one, then
the client should use the appropriate form of designating the payee in any future payment requests
<PMTRQ> to that payee.
Tag Description
<PAYEEMODRS> Modification-response aggregate
<PAYEELSTID> Server-assigned record ID for this payee record, A-12
<PAYEE> Payee information that was modified, see section 12.5.2.1
</PAYEE>
<BANKACCTTO> Destination account (see section 11.3.1) for countries that pay bills using transfers
(<PAYEE> required as well)
</BANKACCTTO>
</PAYEEMODRS>
Code Meaning
0 Success (INFO)
The Payee delete request does not cancel payments that are pending at the time of the payee’s deletion.
References to pending payments subsequent to a payee’s deletion pose issues regarding <PAYEELSTID>
assignment at both the client and server levels. Therefore, it is suggested that the client disallow payee
deletes if there are pending payments/models.
Tag Description
<PAYEEDELRQ> Deletion-request aggregate
<PAYEELSTID> Server-assigned record ID for this payee record, A-12
</PAYEEDELRQ>
The server sends the Payee Deletion Response <PAYEEDELRS> in response to a Payee Deletion Request
<PAYEEDELRQ>.
Tag Description
<PAYEEDELRS> Deletion-response aggregate
<PAYEELSTID> Server-assigned record ID for this payee record, A-12
</PAYEEDELRS>
Code Meaning
0 Success (INFO)
Tag Description
<PAYEESYNCRQ> Payee-list request aggregate
Client synchronization
option; <TOKEN>,
<TOKENONLY>, or
<REFRESH>
<TOKEN> Previous value of <TOKEN> received for this type of synchronization request
from server; 0 for first-time requests; token
<TOKENONLY> Request for just the current <TOKEN> without the history, Boolean
<REFRESH> Request for refresh of current state, Boolean
<REJECTIFMISSING> If Y, do not process requests if client <TOKEN> is out of date, Boolean
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</PAYEESYNCRQ>
Tag Description
<PAYEESYNCRS> Payee-list response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry in the
server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a token in the
server’s history table. Boolean
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</PAYEESYNCRS>
In order to accomplish these tasks, the client uses a synchronization scheme to insure that it has an accurate
copy of the server data that is relevant to the client application. The intent of this scheme is to address three
scenarios in which the client might lose synchronization with the server:
• A transaction has changed its state based on processing actions on the server. For example, a scheduled
payment has passed its due date and has been paid or rejected.
• Transactions relevant to the client’s application state have been added, deleted, or modified by a second
client. For example, a user might enter or change transactions from more than one PC or application.
• A communications session between the client and server was interrupted or completed abnormally. As
a result the client does not have responses from the server indicating that all the transactions were
received and processed.
Note: Except for the <REFRESH>Y sync response, no payee information in any particular
response in a sync should have changed from that in the response when it was originally sent.
In other words, if a <PMTMODRS> caused a change to that payment’s payee address, the
original <PMTRS> in the sync should have the old address in it. The <PMTMODRS>,
appearing later in the sync, would cause the client to update the payment appropriately.
Tag Description
<PMTSYNCRQ> Synchronization-request aggregate
Client synchronization
option; <TOKEN>,
<TOKENONLY>, or
<REFRESH>
<TOKEN> Previous value of <TOKEN> received for this type of synchronization request
from server; 0 for first-time requests; token
<TOKENONLY> Request for just the current <TOKEN> without the history, Boolean
<REFRESH> Request for refresh of current state, Boolean
<REJECTIFMISSING> If Y, do not process requests if client <TOKEN> is out of date, Boolean
<BANKACCTFROM> Opening tag for account from aggregate, see section 11.3.1
</BANKACCTFROM>
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</PMTSYNCRQ>
Tag Description
<PMTSYNCRS> Synchronization-response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry in the
server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a token in
the server’s history table. Boolean
<BANKACCTFROM> Opening tag for account from aggregate, see section 11.3.1
</BANKACCTFROM>
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</PMTSYNCRS>
Tag Description
<RECPMTSYNCRQ> Synchronization-request aggregate
Client synchronization
option; <TOKEN>,
<TOKENONLY>, or
<REFRESH>
<TOKEN> Previous value of <TOKEN> received for this type of synchronization request
from server; 0 for first-time requests; token
<TOKENONLY> Request for just the current <TOKEN> without the history, Boolean
<REFRESH> Request for refresh of current state, Boolean
<REJECTIFMISSING> If Y, do not process requests if client <TOKEN> is out of date, Boolean
<BANKACCTFROM> Opening tag for account from aggregate, see section 11.3.1
</BANKACCTFROM>
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</RECPMTSYNCRQ>
Tag Description
<RECPMTSYNCRS> Synchronization-response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry in the
server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a token in the
server’s history table. Boolean
<BANKACCTFROM> Opening tag for account from aggregate, see section 11.3.1
</BANKACCTFROM>
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</RECPMTSYNCRS>
When the client has requested the server to add a transaction, a response that contains a <TRNUID>
matching a transaction originally sent by the client—for which the client has not recorded an associated
<SRVRTID>—is the normal scenario. This scenario could also occur if the server response did not reach
the client in the previous session. In either case, the client should add these server IDs to their associated
transactions at this point.
If the client previously recorded the <SRVRTID>, this response is a change in status or in the contents of
the transaction. The request might have originated from this client, another client, or might be the result of
server processing.
If the <TRNUID> does not match any transaction known to the client, a second client initiated this
transaction. In rarer cases the response might be a transaction initially requested by this client, for which
the client has lost its record; for example, the client has reverted to a backup.
No
Yes
After receiving the synchronization responses from the server, the client scans its database of transactions
to verify that they have all been assigned a <SRVRTID>. Any transactions missing this identifier were
never received by the server and should be resent (using the originally assigned <TRNUID> to avoid
duplicate requests). Additionally, the client should record the <TOKEN> received in the response.
The message set contains options and attributes that allow a financial institution to customize its use of
OFX. The options and attributes are defined in the profile as part of the message set definition. Each set of
options and attributes appears within an aggregate that is specific to a message set. Specifically, all of the
options and attributes that pertain to payments are contained within <BILLPAYMSGSETV1>.
Clients should not send an empty <BILLPAYMSGSRQV1> (although allowed by the DTD, such a
message is meaningless). Although the DTD imposes a certain transaction order (payee transactions and
sync requests go first), the transactions in <BILLPAYMSGSRQV1> may be executed in any order.
PMTTRNRQ
PMTRQ
PMTMODRQ
PMTCANCRQ
RECPMTTRNRQ
RECPMTRQ
RECPMTMODRQ
RECPMTCANCRQ
PAYEETRNRQ
PAYEERQ
PAYEEMODRQ
PAYEEDELRQ
PMTINQTRNRQ
PMTINQRQ
PMTMAILTRNRQ
PMTMAILRQ
PMTSYNCRQ
RECPMTSYNCRQ
PAYEESYNCRQ
PMTMAILSYNCRQ
</BILLPAYMSGSRQV1>
PMTTRNRS
PMTRS
PMTMODRS
PMTCANCRS
RECPMTTRNRS
RECPMTRS
RECPMTMODRS
RECPMTCANCRS
PAYEETRNRS
PAYEERS
PAYEEMODRS
PAYEEDELRS
PMTINQTRNRS
PMTINQRS
PMTMAILTRNRS
PMTMAILRS
PMTSYNCRS
RECPMTSYNCRS
PAYEESYNCRS
PMTMAILSYNCRS
</BILLPAYMSGSRSV1>
Tag Description
<BILLPAYMSGSET>
</MSGSETCORE>
</BILLPAYMSGSET>
<OFX>
<SIGNONMSGSRSV1>
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<BILLPAYMSGSRSV1>
<PMTTRNRS>
<TRNUID>1001</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<PMTRS>
<SRVRTID>1030155</SRVRTID>
<PAYEELSTID>123214<PAYEELSTID>
<CURDEF>USD</CURDEF>
<PMTINFO>
<BANKACCTFROM>
<BANKID>123432123</BANKID>
<ACCTID>516273</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<TRNAMT>123.45</TRNAMT>
<PAYEE>
<NAME>J. C. Counts</NAME>
<ADDR1>100 Main St.</ADDR1>
<CITY>Turlock</CITY>
<STATE>CA</STATE>
<POSTALCODE>90101</POSTALCODE>
<PHONE>415.987.6543</PHONE>
</PAYEE>
<PAYEELSTID>123214</PAYEELSTID>
<PAYACCT>10101</PAYACCT>
<DTDUE>20051001</DTDUE>
<MEMO>payment #3</MEMO>
</PMTINFO>
<EXTDPAYEE>
<PAYEEID>9076</PAYEEID>
Create a second payment to the payee, using the payee ID returned in the previous example:
<OFX>
<SIGNONMSGSRQV1>
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<BILLPAYMSGSRQV1>
<PMTTRNRQ>
<TRNUID>1002</TRNUID>
<PMTRQ>
<PMTINFO>
<BANKACCTFROM>
<BANKID>123432123</BANKID>
<ACCTID>516273</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<TRNAMT>123.45</TRNAMT>
<PAYEEID>9076</PAYEEID>
<PAYEELSTID>123214</PAYEELSTID>
<PAYACCT>10101</PAYACCT>
<DTDUE>20051101</DTDUE>
<MEMO>Payment #4</MEMO>
</PMTINFO>
</PMTRQ>
</PMTTRNRQ>
The server responds, indicating that it will make the payment on the date requested:
<OFX>
<SIGNONMSGSRSV1>
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<BILLPAYMSGSRSV1>
<PMTTRNRS>
<TRNUID>1002</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<PMTRS>
<SRVRTID>1068405<SRVRTID>
<PAYEELSTID>123214</PAYEELSTID>
<CURDEF>USD</CURDEF>
<PMTINFO>
<BANKACCTFROM>
<BANKID>123432123</BANKID>
<ACCTID>516273</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<TRNAMT>123.45</TRNAMT>
<PAYEEID>9076</PAYEEID>
<PAYEELSTID>123214</PAYEELSTID>
<PAYACCT>10101</PAYACCT>
<DTDUE>20051101</DTDUE>
<MEMO>payment #4</MEMO>
</PMTINFO>
<EXTDPAYEE>
<PAYEEID>9076</PAYEEID>
<IDSCOPE>USER</IDSCOPE>
<NAME>J. C. Counts</NAME>
<DAYSTOPAY>3</DAYSTOPAY>
</EXTDPAYEE>
<PMTPRCSTS>
<OFX>
<SIGNONMSGSRQV1>
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<BILLPAYMSGSRQV1>
<PMTTRNRQ>
<TRNUID>1021</TRNUID>
<PMTMODRQ>
<SRVRTID>1030155</SRVRTID>
<PMTINFO>
<BANKACCTFROM>
<BANKID>123432123</BANKID>
<ACCTID>516273</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<TRNAMT>125.99</TRNAMT><!-- changed amount -->
<PAYEEID>9076</PAYEEID>
<PAYEELSTID>123214</PAYEELSTID>
<PAYACCT>10101</PAYACCT>
<DTDUE>20051001</DTDUE>
<MEMO>payment #3</MEMO>
</PMTINFO>
</PMTMODRQ>
</PMTTRNRQ>
</BILLPAYMSGSRQV1>
</OFX>
<OFX>
<SIGNONMSGSRSV1>
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<BILLPAYMSGSRSV1>
<PMTTRNRS>
<TRNUID>1021</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<PMTMODRS>
<SRVRTID>1030155</SRVRTID>
<PMTINFO>
<BANKACCTFROM>
<BANKID>123432123</BANKID>
<ACCTID>516273</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<TRNAMT>125.99</TRNAMT><!-- changed amount -->
<PAYEEID>9076</PAYEEID>
<PAYEELSTID>123214</PAYEELSTID>
<PAYACCT>10101</PAYACCT>
<DTDUE>20051001</DTDUE>
<MEMO>payment #3</MEMO>
</PMTINFO>
<PMTPRCSTS>
<PMTPRCCODE>WILLPROCESSON</PMTPRCCODE>
<DTPMTPRC>20050928</DTPMTPRC>
</PMTPRCSTS>
</PMTMODRS>
</PMTTRNRS>
</BILLPAYMSGSRSV1>
</OFX>
<OFX>
<OFX>
<SIGNONMSGSRSV1>
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<BILLPAYMSGSRSV1>
<PMTTRNRS>
<TRNUID>32456</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</INFO>
<OFX>
<SIGNONMSGSRQV1>
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<BILLPAYMSGSRQV1>
<PMTTRNRQ>
<TRNUID>54601</TRNUID>
<PMTCANCRQ>
<SRVRTID>1030155</SRVRTID>
</PMTCANCRQ>
</PMTTRNRQ>
<OFX>
<SIGNONMSGSRSV1>
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<BILLPAYMSGSRSV1>
<PMTTRNRS>
<TRNUID>54601</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<PMTCANCRS>
<SRVRTID>1030155</SRVRTID>
</PMTCANCRS>
</PMTTRNRS>
</BILLPAYMSGSRSV1>
</OFX>
<OFX>
<SIGNONMSGSRQV1>
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<BILLPAYMSGSRQV1>
<PMTINQTRNRQ>
<TRNUID>7865</TRNUID>
<PMTINQRQ>
<SRVRTID>565321</SRVRTID>
</PMTINQRQ>
</PMTINQTRNRQ>
<OFX>
<SIGNONMSGSRSV1>
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<BILLPAYMSGSRSV1>
<PMTINQTRNRS>
<TRNUID>7865</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<PMTINQRS>
<SRVRTID>565321</SRVRTID>
<PMTPRCSTS>
<PMTPRCCODE>PROCESSEDON</PMTPRCCODE>
<DTPMTPRC>20050201</DTPMTPRC>
</PMTPRCSTS>
<CHECKNUM>6017</CHECKNUM>
</PMTINQRS>
</PMTINQTRNRS>
</BILLPAYMSGSRSV1>
</OFX>
<OFX>
<SIGNONMSGSRQV1>
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<BILLPAYMSGSRQV1>
<OFX>
<SIGNONMSGSRSV1>
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<BILLPAYMSGSRSV1>
<RECPMTTRNRS>
<TRNUID>12345</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</INFO>
</STATUS>
<RECPMTRS>
<RECSRVRTID>387687138</RECSRVRTID>
<OFX>
<SIGNONMSGSRQV1>
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<BILLPAYMSGSRQV1>
<RECPMTTRNRQ>
<OFX>
<SIGNONMSGSRSV1>
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<BILLPAYMSGSRSV1>
<RECPMTTRNRS>
<TRNUID>98765</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<RECPMTMODRS>
<OFX>
<SIGNONMSGSRQV1>
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<BILLPAYMSGSRQV1>
<RECPMTTRNRQ>
<TRNUID>11122</TRNUID>
<RECPMTCANCRQ>
<RECSRVRTID>387687138</RECSRVRTID>
<CANPENDING>Y</CANPENDING>
</RECPMTCANCRQ>
</RECPMTTRNRQ>
</BILLPAYMSGSRQV1>
</OFX>
<OFX>
<SIGNONMSGSRSV1>
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<BILLPAYMSGSRSV1>
<RECPMTTRNRS>
<TRNUID>11122</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<RECPMTCANCRS>
<RECSRVRTID>387687138</RECSRVRTID>
<OFX>
<SIGNONMSGSRQV1>
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<BILLPAYMSGSRQV1>
<PAYEETRNRQ>
<TRNUID>127677</TRNUID>
<PAYEERQ>
<PAYEE>
<NAME>ACME Rocket Works</NAME>
<ADDR1>101 Spring St.</ADDR1>
<ADDR2>Suite 503</ADDR2>
<CITY>Watkins Glen</CITY>
<STATE>NY</STATE>
<POSTALCODE>12345-6789</POSTALCODE>
<PHONE>888.555.1212</PHONE>
</PAYEE>
<PAYACCT>1001-99-8876</PAYACCT>
</PAYEERQ>
</PAYEETRNRQ>
</BILLPAYMSGSRQV1>
</OFX>
<OFX>
<SIGNONMSGSRSV1>
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<BILLPAYMSGSRSV1>
<PAYEETRNRS>
<TRNUID>127677</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<PAYEERS>
<PAYEELSTID>78096786</PAYEELSTID>
<PAYEE>
<NAME>ACME Rocket Works</NAME>
<ADDR1>101 Spring St.</ADDR1>
<ADDR2>Suite 503</ADDR2>
<CITY>Watkins Glen</CITY>
<STATE>NY</STATE>
<POSTALCODE>12345-6789</POSTALCODE>
<PHONE>888.555.1212</PHONE>
</PAYEE>
<EXTDPAYEE>
<PAYEEID>88878</PAYEEID>
<IDSCOPE>GLOBAL</IDSCOPE>
<NAME>ACME Rocket Works, Inc.</NAME>
<DAYSTOPAY>2</DAYSTOPAY>
</EXTDPAYEE>
<PAYACCT>1001-99-8876</PAYACCT>
</PAYEERS>
</PAYEETRNRS>
</BILLPAYMSGSRSV1>
</OFX>
<OFX>
<SIGNONMSGSRQV1>
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<BILLPAYMSGSRQV1>
<PMTSYNCRQ>
<REFRESH>Y</REFRESH>
<REJECTIFMISSING>N</REJECTIFMISSING>
<BANKACCTFROM>
<BANKID>123432123</BANKID>
<ACCTID>516273</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
</PMTSYNCRQ>
</BILLPAYMSGSRQV1>
</OFX>
Assuming the only activity on this account has been the two payments created above, the server responds
with one payment since the other payment was cancelled. The server also includes the current <TOKEN>
value.
Note: If the one outstanding payment had a modification to it, the modification should have
been integrated into the one <PMTRS> since this is a refresh, not a sync of all history. In that
case, <TRNUID>0 must be returned in the response transaction (no client initiated an exact
matching transaction).
<OFX>
<SIGNONMSGSRSV1>
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<BILLPAYMSGSRSV1>
<PMTSYNCRS>
<TOKEN>3247989384</TOKEN>
<BANKACCTFROM>
<BANKID>123432123</BANKID>
Account identifier
Account identifier
Investment transactions
Banking transactions
Open orders
Positions
Account balances
Short Balance
Margin Balance
Buying power
Marketing message
List of securities
Note: This release of OFX does not support trading or tax lots.
13.2 Sub-Accounts
Many FIs distinguish between activity and positions in cash, margin, and short accounts, with some FIs
having many other types of “sub-accounts.” OFX defines four standard types of sub-accounts: Cash,
Margin, Short, Other. Position, Transaction, and Open Order records identify the sub-account.
13.3.1 Units
The units for security units and unit price are those commonly used on brokerage statements, and differ for
each type of security.
• Stocks and Other – use number of shares for units and dollar value for unit price.
• Mutual Funds – in most cases shares are used, but in some cases the dollar value is used. The unit type
is specified in cases in which it can be either.
• Bonds – use face value for units and percentage of par for unit price. For example, a $25,000 bond
trading at $88 would use 25000 as the units and 88 as the unit price.
13.3.2 Precision
OFX does not specify the precision of fields since the precision is client-dependent. However, it is
recommended that clients and servers follow these rules:
• Clients and servers should send as much precision as they have
• Clients and servers should use a precision equal to or better than 1/256 of a share
13.3.3 Signs
Chapter 3, "Common Aggregates, Elements, and Data Types," describes how to use positive and negative
numbers. Briefly, quantities and total values should be signed from the perspective of the user. In a stock
buy, the total value is negative, the unit price is always positive, and the number of units is positive.
In a transaction, the signage of UNITS and TOTALs is determined by the transaction's effect on the
underlying cash balance (an investment sell would contain a positive TOTAL and negative UNITS
whereas an investment buy would contain a negative TOTAL and positive UNITS). All other Investment
transaction amounts are always positively signed. In other words UNITPRICE, COMMISSION, FEES,
TAXES, PENALTY, WITHHOLDING, STATEWITHHOLDING, LOAD, MARKUP and MARKDOWN
are always positive numbers.
FIs need to use the correct transaction record, bank or investment, for each real-world transaction. Use the
following guidelines:
• Checks, electronic funds transfers, and ATM transactions associated with CMA or money market
sweep accounts are always represented with a bank transaction record.
• Investment actions that involve securities (buy, sell, stock split, reinvest, etc.) are always represented
with an investment record. Actions that are cash-only but are directly associated with a security are also
investment actions (for example, dividends).
• Other cash-only actions require careful analysis by the FI. Those that affect investment performance
analysis should be sent using the appropriate investment action (investment income - miscellaneous,
investment expense). Those that are completely unrelated to investment should be sent as a bank
record.
Tag Description
<INVACCTFROM> Account-from aggregate
<BROKERID> Unique identifier for the FI, A-22
<ACCTID> Account number at FI, A-22
</INVACCTFROM>
Brokers should use the domain name of their company’s URL as the BROKERID, e.g.,
If URL=www.broker.com
then BROKERID=broker.com
Tag Description
<INVACCTINFO> Investment-account-information-record aggregate
<INVACCTFROM> Account at FI, see 13.6.1
</INVACCTFROM>
If an investment account has payments functionality, the analogous PMTINFO aggregate (see 12.5.2)
should also be sent in the ACCTINFO for the account. Payment information will be sent using the message
sets described in the 12.5.2 , "Payment Information <PMTINFO>."
<USPRODUCTTYPE> classifies accounts according to their account type. Valid values are:
Note: Server should return 401K as the value for <USPRODUCTTYPE> in the
<INVACCTINFO> aggregate for 401(k) accounts.
The <USPRODUCTTYPE> element is intended for use by FIs in the United States. OFX will be expanded
to provide equivalent elements to support the needs for other countries.
In order for clients to properly show the user the state of an investment account (especially 401(k)
accounts), it is important that position and transaction detail information be downloaded. This allows the
reporting of account performance down to the level of the individual securities.
Note: For investment accounts, even though OFX does not require the downloading of the
<INVPOSLIST> in the response when the <INCPOS> flag is set in the request, it is highly
recommended that servers return this information. Similarly, even though OFX does not
require the downloading of the <INVTRANLIST> in the response when the <INCTRAN> flag
is set in the request, it is highly recommended that servers return this information as well.
Each message set contains options that allow a financial institution to customize its use of OFX. For
example, an institution can support the Investment Statement Download Set (INVSTMTMSGSETV1), but
it can choose not to support the download of open orders.
The options and attributes are defined in the profile as part of each message set definition. Each set of
options and attributes appears within an aggregate that is specific to a message set. For example,
<INVSTMTMSGSETV1> contains all the options and attributes that pertain to investment statement
download.
The investment statement message set profile aggregate <INVSTMTMSGSET> is used in the response to
a financial institution profile request (see Chapter 7, "FI Profile") to specify which activities it supports.
Tag Description
<INVSTMTMSGSET> Investment-statement-message-set-profile aggregate
<INVSTMTMSGSETV1> Version 1 message set
<MSGSETCORE> Common message set information, see Chapter 7, "FI Profile"
</MSGSETCORE>
</INVSTMTMSGSETV1>
</INVSTMTMSGSET>
The following tables show the OFX transactions and their corresponding transaction wrappers for requests
and responses.
Tag Description
<INVSTMTMSGSRQV1> INVSTMTTRNRQ
INVSTMTTRQ
INVMAILTRNRQ
INVMAILRQ
INVMAILSYNCRQ
INVSTMTENDTRNRQ
INVSTMTENDRQ
</INVSTMTMSGSRQV1>
Tag Description
<INVSTMTMSGSRSV1> INVSTMTTRNRS
INVSTMTRS
INVMAILTRNRS
INVMAILRS
INVMAILSYNCRS
INVSTMTENDTRNRS
INVSTMTENDRS
</INVSTMTMSGSRSV1>
The security list message set profile aggregate <SECLISTMSGSET> is used in the response to an FI
profile request (see Chapter 7, “FI Profile”) to specify which activities it supports.
Tag Description
<SECLISTMSGSET> Security-information-message-set-profile aggregate
<SECLISTMSGSETV1> Version 1 message set
<MSGSETCORE> Common message set information, see Chapter 7, "FI Profile"
</MSGSETCORE>
</SECLISTMSGSET>
Tag Description
<SECLISTMSGSRQV1> SECLISTTRNRQ
SECLISTRQ
</SECLISTMSGSRQV1>
Tag Description
<SECLISTMSGSRSV1> SECLISTTRNRS
SECLISTRS
SECLIST
</SECLISTMSGSRSV1>
Tag Description
<SECID> Security-identifier aggregate
<UNIQUEID> Unique identifier for the security. CUSIP for US FIs. A-32
<UNIQUEIDTYPE> Name of standard used to identify the security i.e., “CUSIP” for FIs in the United
States, A-10
</SECID>
Non-US financial institutions that do not have access to CUSIP numbers must supply a unique identifier
for each security in the UNIQUEID field of this aggregate. OFX will be expanded to include other security
identifying standards.
Tag Description
<SECLISTTRNRQ> Transaction-request aggregate
<TRNUID> Client-assigned globally unique ID for this transaction trnuid
<CLTCOOKIE> Data to be echoed in the transaction response, A-32
<TAN> Transaction authorization number; used in some countries with some types of
transactions. Country-specific documentation will define messages that require a
<TAN>, A-80
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
<SECLISTRQ> Aggregate for the security list request (see section 13.8.2.2)
</SECLISTRQ>
</SECLISTTRNRQ>
For the security list request, securities must be specified with either a SECID aggregate, a ticker symbol, or
an FI assigned identifier.
Tag Description
<SECLISTRQ> Security-list-request aggregate
<SECRQ> Security request (one or more)
Security identification.
Specify either
<SECID>,
<TICKER>, or
<FIID>.
<SECID> Security identifier aggregate
</SECID>
-or-
</SECLISTRQ>
Tag Description
<SECLISTTRNRS> Transaction-response aggregate
<TRNUID> Client-assigned globally unique ID for this transaction trnuid
<STATUS> Status aggregate
</STATUS>
</SECLISTTRNRS>
Code Meaning
0 Success (INFO)
The security list response aggregate, the only empty aggregate in OFX, is used to respond to the
<SECLISTRQ>. It is used to signify that the security list is generated as a result of a security list request.
The actual security information should be included in the <SECLIST> aggregate.
Tag Description
<SECLISTRS> Security-list-response (the only empty aggregate in OFX).
</SECLISTRS>
• When the response file contains an investment statement download that has positions, transactions, or
open orders. The <SECLIST> should contain information about each security referenced in the
investment statement download. Clients are completely dependent on the security list to provide
descriptive information for the securities referenced in positions, transactions, and open orders.
Tag Description
<SECLIST> Security-list-request aggregate
<xxxINFO> Security information aggregates (zero or more): <DEBTINFO>, <MFINFO>,
<OPTINFO>, <OTHERINFO>, or <STOCKINFO>.
While allowed by the DTD, servers should not send an empty <SECLIST> aggregate.
</xxxINFO>
</SECLIST>
The <SECINFO> aggregate contains fields that are common to all security types. This aggregate is used in
the security type specific aggregates in the following sections.
Tag Description
<SECINFO> Security-information aggregate
<SECID> Security-identifier aggregate
</SECID>
<MEMO> Memo
</SECINFO>
Tag Description
<DEBTINFO> Opening tag for debt information aggregate
<SECINFO> Security information aggregate
</SECINFO>
Tag Description
<MFINFO> Mutual-fund-information aggregate
<SECINFO> Security-information aggregate
</SECINFO>
</MFASSETCLASS>
</FIMFASSETCLASS>
</MFINFO>
Tag Description
<OPTINFO> Option-information aggregate
<SECINFO> Security-information aggregate
</SECINFO>
Use this aggregate for security types other than debts, mutual funds, options, and stocks.
Tag Description
<OTHERINFO> Other aggregate.
<SECINFO> Security information aggregate
</SECINFO>
Tag Description
<STOCKINFO> Stock-information aggregate
<SECINFO> Security-information aggregate
</SECINFO>
DOMESTICBOND The Domestic Bonds asset class consists of government or corporate bonds issued in
the United States.
INTLBOND The International Bonds asset class consists of government or corporate bonds
issued in foreign countries or the United States.
LARGESTOCK The Large Cap Stocks asset class consists of stocks for U.S. companies with market
capitalizations of $2 billion or more.
SMALLSTOCK The Small Cap Stocks asset class consists of stocks for U.S. companies with market
capitalizations of approximately $100 million to $2 billion.
INTLSTOCK The International Stocks asset class consists of publicly-traded stocks for companies
based in foreign countries.
MONEYMRKT The Money Market asset class consists of stable, short-term investments which
provide income that rises and falls with short-term interest rates.
OTHER The Other asset class consists of investments which do not fit in any of the other
asset classes.
Clients usually allow customers to view investment transactions and guide customers through a process of
updating their account registers based on the downloaded transactions. By using <FITID> values supplied
by FIs, OFX makes it possible for clients to insure that each transaction is downloaded only once. The
request also contains starting and ending dates to limit the amount of downloaded data. Clients can
remember the last date they receive a download, and use that date as the starting date in the next request.
Investment statement download requires the client to designate an account for the download, and to
indicate what type of data should be downloaded. If the client wishes to download transactions, it can
specify a date range that the transactions fall within. The server returns transactions that match the date
range, if one is specified. If a date range is not specified, the server returns all available transactions for the
account.
Tag Description
<INVSTMTTRNRQ> Transaction-request aggregate
<TRNUID> Client-assigned globally unique ID for this transaction, trnuid
<CLTCOOKIE> Data to be echoed in the transaction response, A-32
<TAN> Transaction authorization number; used in some countries with some types of
transactions. Country-specific documentation will define messages that require a
<TAN>, A-80
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
<INVSTMTRQ> Aggregate for the investment statement download request (see section 13.9.1.2)
</INVSTMTRQ>
</INVSTMTTRNRQ>
The following table shows the Investment Statement Request record. It is similar to a bank statement
request, except that there are extra elements to indicate which pieces the user desires. Note that because
transaction and position requests require date information, they use aggregates, whereas the other requests
are elemental of type Boolean.
Clients and servers should interpret <DTSTART> and <DTEND> as described in Chapter 3, "Common
Aggregates, Elements, and Data Types." If an investment statement download request does not contain
<DTSTART> or <DTEND> elements but does request transactions and if no transactions are found on the
server, the response may or may not include an <INVTRANLIST>. If the <INVTRANLIST> is included,
the server should leave out the empty <INVBANKTRAN> aggregate(s).
If <DTASOF> is not included with the <INCPOS> aggregate, the server should return the most current
position information available.
If the profile indicates that 401(k) investment information is available, the <INC401K> and
<INC401KBAL> can be used.
If <INCTRANIMG>Y is included in the request, the client is asking for any and all images available for
the transactions returned. The image information will be returned in the <STMTTRN> aggregate
associated with each banking transaction in the response.
Tag Description
<INVSTMTTRNRS> Transaction-response aggregate
<TRNUID> Client-assigned globally unique ID for this transaction, trnuid
<STATUS> Status aggregate
</STATUS>
<INVSTMTRS> Aggregate for the investment statement download response (see section 13.9.2.2)
</INVSTMTRS>
</INVSTMTTRNRS>
The response can contain transaction, position, open order, and/or balance detail records; each in its own
aggregate. The transaction list aggregate can contain a mixture of bank statement records and investment
transactions, as specified below.
For 401(k) accounts, both the <INV401KBAL> and the <INVBAL> aggregates can be returned if asked
for specifically. In other words, for 401(k) accounts the <INV401KBAL> aggregate is returned if asked for
by the client with the <INC401KBAL> flag, and the <INVBAL> aggregate is returned if <INCBAL> is Y.
Tag Description
<INVSTMTRS> Investment-response aggregate
<DTASOF> As of date & time for the statement download, datetime
<CURDEF> Default currency for the statement, currsymbol
<INVACCTFROM> Which account at FI, see 13.6.1
</INVACCTFROM>
The various sections of the investment statement download are returned only if requested.
For investment statement download, margin call information should be included in the balances section.
Margin call information should be contained in a <BAL> aggregate and included in the balance list
<BALLIST>.
Use the INVBANKTRAN aggregate to download bank transactions in an investment statement download.
Tag Description
<INVBANKTRAN> Banking related transactions for the investment account
<STMTTRN> Bank (cash) transaction aggregates
</STMTTRN> (See Chapter 11, "Banking")
<SUBACCTFUND> The sub-account associated with the funds for the transaction; see section 13.9.2.4.2
</INVBANKTRAN>
Note that the following types of investment actions found on statements should not be sent in OFX:
• Transaction-specific miscellaneous/fees—fees or other amounts that affect the basis of the transaction
should be incorporated into the <COMMISSION>, <FEES>, <LOAD>, <PENALTY>,
<WITHHOLDING>, <STATEWITHHOLDING> or <TAXES> amounts.
• Settlement actions.
• Sweeps, unless handled as any other investment position.
For transactions that involve securities, the client can create transactions based on the formula
total = (units * (unitprice +/- markup/markdown)) +/- (commission + fees + load + taxes + penalty +
withholding + statewithholding)
(after adjusting quantity and unitprice to standard units based on the type of security.)
Thus, it is important the FIs incorporate all other transactional fees into the commission field. Clients can
account for bond accrued interest and withholding using separate client transactions.
The <INVTRAN> aggregate contains fields common to many of the investment transactions. It is
referenced within the transaction aggregates in the following sections.
Each <INVTRAN> contains an <FITID> that the client uses to detect whether the server previously
downloaded the transaction.
Tag Description
<INVTRAN> Investment-transaction-response aggregate
<FITID> Unique FI-assigned transaction ID.
This ID is used to detect duplicate downloads. FITID
<SRVRTID> Server assigned transaction ID, SRVRTID
<DTTRADE> Trade date; for stock splits, day of record, datetime
<DTSETTLE> Settlement date; for stock splits, execution date, datetime
<REVERSALFITID> For a reversal transaction, the FITID of the transaction that is being reversed.
See section 13.9.2.4.1.1 for details, FITID
<MEMO> Other information about transaction (at most one), memo
</INVTRAN>
Reversals may be accomplished using two different mechanisms, depending on the support for
<REVERSALFITID> at the client.
Older clients that do not support <REVERSALFITID> will have transactions reversed using the opposite
transaction type when appropriate, e.g., a correction to a buy is returned as a sell. Because investment
transactions cannot include negative amounts, certain transaction components such as commissions and
fees can be reversed by sending an <INVBANKTRAN>.
Newer clients that do support <REVERSALFITID> will have transactions reversed using the same
transaction type as was originally sent. The <REVERSALFITID> must contain the <FITID> of the
transaction that is being reversed. The client will reverse all components of the original transaction
including commissions and fees. Partial corrections are not allowed when transactions are reversed by use
of the <REVERSALFITID> tag. The <FITID> of the new reversal transaction shall be new and unique
(not the same as the <REVERSALFITID>).
The following elements are referenced within of the following investment transaction aggregates.
Tag Description
<ACCRDINT> For debt purchases, accrued interest, amount
<AVGCOSTBASIS> Average cost basis, amount
<BUYTYPE> Type of purchase: BUY, BUYTOCOVER
<COMMISSION> Transaction commission. amount
<DENOMINATOR> For stock splits, split ratio denominator, quantity
<DTPAYROLL> For 401(k)accounts, date the funds for this transaction was obtained via payroll
deduction, datetime
<DTPURCHASE> The security’s original purchase date, date
<GAIN> For sales, total gain, amount
<FEES> Fees applied to trade, amount
<FRACCASH> Cash for fractional units., (used for stock splits), amount
<INCOMETYPE> Type of investment income: CGLONG (capital gains-long term), CGSHORT
(capital gains-short term), DIV (dividend), INTEREST, MISC
<INV401KSOURCE> For 401(k) accounts, source of money used for this security. Must be one of the
following:
PRETAX
AFTERTAX
MATCH
PROFITSHARING
ROLLOVER
OTHERVEST
OTHERNONVEST
Default if not present is OTHERNONVEST. The following cash source types
are subject to vesting: MATCH, PROFITSHARING, and OTHERVEST.
<LOAD> Load on the transaction, amount
<LOANID> For 401(k) accounts only. Indicates that the transaction was due to a loan or a
loan repayment, and which loan it was. A-32
<LOANINTEREST> For 401(k) accounts only. Indicates how much of the loan repayment was
interest. Amount
<LOANPRINCIPAL> For 401(k) accounts only. Indicates how much of the loan repayment was
principal. Amount
<MARKDOWN> Portion of the unit price that is attributed to the dealer markdown, unitprice
Note: For 401(k) accounts, securities can be sold to fund loans or other withdrawals. Loans
and loan repayments, and penalties are shown as part of the Buy and Sell transactions, rather
than directly on any associated Deposit or Withdrawal bank transactions (see section 11.4.3.1)
because some 401(k) providers might not report these bank transactions.
Also, for 401(k) accounts, as loans are repaid the funds are disbursed into the 401(k) sources of
money from where they were originally withdrawn. To accurately reflect the disbursement of
repaid funds into each source, a separate Buy transaction will be issued with the
<INV401KSOURCE> tag set to indicate the source of money. Each of these transactions will
include the amount of principal and/or interest paid to the source.
<SUBACCTSEC>
<SUBACCTFUND>
<LOANID> See section 13.9.2.4.2
<STATEWITHHOLDING> See section 13.9.2.4.2
<PENALTY> See section 13.9.2.4.2
<INV401KSOURCE> Source of money for this
transaction. See section 13.9.2.4.2
<UNITS>
TOTAL and UNITS are signed as for an
<UNITPRICE> investment buy. Corrections to a REINVEST are
<COMMISSION> signed as for an investment sell.
<TAXES>
<FEES>
<LOAD>
<TAXEXEMPT>
<CURRENCY> aggregate
<ORIGCURRENCY> aggregate Though the DTD allows <CURRENCY> and
<ORIGCURRENCY> together in this aggregate,
servers should return neither or one of the two,
but not both.
<INV401KSOURCE> Source of money for this transaction. See section
13.9.2.4.2.
BUYDEBT ×
BUYMF ×
BUYOPT ×
BUYOTHER ×
BUYSTOCK ×
CLOSUREOPT ×
INCOME × × × ×
INVEXPENSE × × × × ×
JRNLFUND
JRNLSEC × × × × ×
MARGININTEREST
REINVEST × × × ×
RETOFCAP × × × × ×
SELLDEBT ×
SELLMF ×
SELLOPT ×
SELLOTHER ×
SELLSTOCK ×
SPLIT × ×
TRANSFER × × × × ×
Since JRNLFUND and MARGININTEREST do not refer to securities, there are no checks in any of the
security columns for these transactions.
In investment statement download, two transactions are needed to reflect mutual fund exchanges. A
SELLMF should be generated for the mutual fund being switched from and a BUYMF should be
generated for the mutual fund being switched to. You can use the RELFITID element to link these two
transactions to each other. You should use the MEMO element of the individual transactions to explain
that a mutual fund exchange occurred.
Since corporate actions can often be very complicated, it is difficult to define a single action aggregate that
encompasses all possible scenarios. Instead, you should describe corporate actions using one or more of
the provided basic action types. You should use the memo field of the individual transactions to link
transactions to an encompassing corporate action.
When the underlying security for an option splits, a new security is generated for the option since the strike
price changes. In investment statement download, you need two transactions to reflect this activity. There
should be a TRANSFER transaction to show that the old option security is removed from the account and
another TRANSFER transaction to show that the new option security is moved into the account.
The <OO> aggregate contains fields common to all open orders. Use this aggregate to define the open
order aggregates as show in the following section.
Tag Description
<OO> General-open-order aggregate
<FITID> Unique FI-assigned transaction ID, FITID
<SRVRTID> Unique server-assigned transaction ID, SRVRTID
<SECID> Security identified aggregate
</SECID>
<INV401KSOURCE> For 401(k) accounts, source of money for this order. See section 13.9.2.4.2.
</OO>
Note: An open order is assumed to be a market order if no limit price or stop price is specified.
Open Order
Aggregates Elements Description of Elements
<OOBUYDEBT> <OO> aggregate
<AUCTION> Whether the debt should be purchased at the auction, Boolean
<DTAUCTION> Date of the auction, date
<OOBUYMF> <OO> aggregate
<BUYTYPE> Type of purchase: BUY, BUYTOCOVER.
<UNITTYPE> What the units represent: SHARES, CURRENCY
<OOBUYOPT> <OO> aggregate
<OPTBUYTYPE> Type of purchase: BUYTOOPEN, BUYTOCLOSE
<OOBUYOTHER> <OO> aggregate
<UNITTYPE> What the units represent: SHARES, CURRENCY
<OOBUYSTOCK> <OO> aggregate
<BUYTYPE> Type of purchase: BUY, BUYTOCOVER
<OOSELLDEBT> <OO> aggregate
<OOSELLMF> <OO> aggregate
<SELLTYPE> Type of sale: SELL, SELLSHORT
<UNITTYPE> What the units represent: SHARES, CURRENCY.
<SELLALL> Sell entire holding, Boolean
<OOSELLOPT> <OO> aggregate
<OPTSELLTYPE> Type of sale: SELLTOOPEN, SELLTOCLOSE
<OOSELLOTHER> <OO> aggregate
<UNITTYPE> What the units represent: SHARES, CURRENCY
<OOSELLSTOCK> <OO> aggregate
<SELLTYPE> Type of sale: SELL, SELLSHORT
<SWITCHMF> <OO> aggregate
<SECID> aggregate Security ID of the mutual fund to switch to or purchase
<UNITTYPE>
What the units represent: SHARES, CURRENCY
<SWITCHALL>
Switch entire holding, Boolean
Position records represent a user’s current positions, regardless of the transactional history. Prices and
values should be the most recent available, even if different from a transaction price on the same day.
In position records, securities are identified as being either short or long. Because each FI has different
rules regarding which sub-accounts can be used for short compared to long activity, FIs must explicitly
indicate the type of position in addition to specifying the sub-account where the position takes place.
For options, position type SHORT is equivalent to WRITING an option, and position type LONG is
equivalent to HOLDING an option. For security types where there is only one type (for example, bonds),
use LONG.
For 401(k) accounts, securities can be purchased with any of the 401(k) cash sources. Any securities
purchased from more than one cash source will appear as a separate position for each.
The INVPOS aggregate contains fields relevant to all investment position types. It is included in the
position aggregates as shown in the following sections.
Tag Description
<INVPOS> General-position aggregate
<SECID> Security identifier
</SECID>
Investment
Position
Aggregates Elements Description of Elements
<POSDEBT> <INVPOS> aggregate
<POSMF> <INVPOS> aggregate
<UNITSSTREET> Units in the FI’s street name, positive quantity
<UNITSUSER> Units in the user’s name directly, positive quantity
<REINVDIV> Reinvest dividends, Boolean
<REINVCG> Reinvest capital gains, Boolean
<POSOPT> <INVPOS> aggregate
<SECURED> How the option is secured. NAKED, COVERED.
<POSOTHER> <INVPOS> aggregate
<POSSTOCK> <INVPOS> aggregate
<UNITSSTREET> Units in the FI’s street name, positive quantity
<UNITSUSER> Units in the user’s name directly, positive quantity
<REINVDIV> Reinvest dividends, Boolean
The <INVBAL> aggregate contains five specified balances. It can also contain a <BALLIST> aggregate
that contains one or more <BAL> aggregates. The <BAL> aggregate (see Chapter 3, “Common
Aggregates, Elements, and Data Types”) allows an FI to send any number of balances to the user, complete
with description and Help text. The intent is to capture the same type of balance information present on the
first page of many FI brokerage statements. You can also use the <BAL> aggregate to send margin call
information.
Tag Description
<INVBAL> Balances aggregate
<AVAILCASH> Cash balance across all sub-accounts. Should include sweep funds. Amount
<MARGINBALANCE> Margin balance. A positive balance indicates a positive cash balance, while a
negative balance indicates the customer has borrowed funds. Amount
<SHORTBALANCE> Market value of all short positions. This is a positive balance, Amount
<BUYPOWER> Buying power, amount
<BALLIST> Beginning of Investment balance list (at most one)
<BAL> Balance aggregates (0 or more)
</BAL> See Chapter 3, "Common Aggregates, Elements, and Data Types"
</BALLIST>
</INVBAL>
Code Meaning
0 Success (INFO)
The <INV401KBAL> aggregate contains an optional cash balance. It also contains the balances of the
standard 401(k) sub-accounts. The date of these balances is taken from the <DTASOF> element of the
<INVSTMTRS>aggregate.
Tag Description
<PRETAX> Current value of all securities purchased with Before Tax Employee
contributions, amount
<AFTERTAX> Current value of all securities purchased with After Tax Employee contributions,
amount
<MATCH> Current value of all securities purchased with Employer Match contributions,
amount
<PROFITSHARING> Current value of all securities purchased with Employer Profit Sharing
contributions, amount
<ROLLOVER> Current value of all securities purchased with Rollover contributions, amount
<OTHERVEST> Current value of all securities purchased with Other (vesting) Employer
contributions, amount
<OTHERNONVEST> Current value of all securities purchased with Other (non-vesting) Employer
contributions, amount
<TOTAL> Current value of all securities purchased with all contributions, amount
</BAL>
</BALLIST>
</INV401KBAL>
Code Meaning
0 Success (INFO)
Tag Description
<INV401K> 401(k) Summary aggregate
<EMPLOYERNAME> Name of the employer, A-32
<PLANID> Plan number, A-32
<PLANJOINDATE> Date the employee joined the plan, date
<EMPLOYERCONTACTINFO> Name of contact person at employer, plus any available contact
information, such as phone number, A-255
<BROKERCONTACTINFO> Name of contact person at broker, plus any available contact
information, such as phone number, A-255
</CONTRIBINFO>
<CONTRIBUTIONS> 401 (k) contribution aggregate (at most one) (See section
13.9.3.1)
</CONTRIBUTIONS>
<EARNINGS> 401(k) earnings aggregate (at most one) (See section 13.9.3.3)
</EARNINGS>
</YEARTODATE>
<EARNINGS> 401(k) earnings aggregate (at most one) (See section 13.9.3.3)
</EARNINGS>
</INCEPTODATE>
<PERIODTODATE>
<EARNINGS> 401(k) earnings aggregate (at most one) (See section 13.9.3.3)
</EARNINGS>
</PERIODTODATE>
</INV401KSUMMARY>
</INV401K>
The following table shows the new 401(k) contribution aggregate and its tags.
Tag Description
<CONTRIBUTIONS> 401(k) contribution aggregate. Note: this includes loan payments.
<PRETAX> Pretax contribution. amount
<AFTERTAX> After tax contribution. amount
<MATCH> Employer matching contribution. amount
<PROFITSHARING> Profit sharing contribution. amount
<ROLLOVER> Rollover contribution. amount
<OTHERVEST> Other vesting contributions. amount
<OTHERNONVEST> Other non-vesting contributions. amount
<TOTAL> Sum of contributions from all fund sources. amount
</CONTRIBUTIONS>
Tag Description
<WITHDRAWALS> 401(k) withdrawals aggregate. Note: this includes loan withdrawals.
<PRETAX> Pretax withdrawals. amount
<AFTERTAX> After tax withdrawals. amount
<MATCH> Employer matching withdrawals. amount
<PROFITSHARING> Profit sharing withdrawals. amount
<ROLLOVER> Rollover withdrawals. amount
<OTHERVEST> Other vesting withdrawals. amount
<OTHERNONVEST> Other non-vesting withdrawals. amount
<TOTAL> Sum of withdrawals from all fund sources. amount
</WITHDRAWALS>
Tag Description
<EARNINGS> 401(k) earnings aggregate. This is the market value change. It includes dividends/
interest, and capital gains - realized and unrealized.
<PRETAX> Pretax earnings. amount
<AFTERTAX> After tax earnings. amount
<MATCH> Employer matching earnings. amount
<PROFITSHARING> Profit sharing earnings. amount
<ROLLOVER> Rollover earnings. amount
<OTHERVEST> Other vesting earnings. amount
<OTHERNONVEST> Other non-vesting earnings. amount
<TOTAL> Sum of earnings from all fund sources. amount
</EARNINGS>
Tag Description
<INVSTMTENDRQ> Closing-statement-request aggregate
<INVACCTFROM> Investment-account-from aggregate
</INVACCTFROM>
Tag Description
<INVSTMTENDRS> Closing-statement-response aggregate
<CURDEF> Default currency used for closing information, currsymbol
<INVACCTFROM> Account from aggregate
</INVACCTFROM>
</INVSTMTENDRS>
Code Meaning
0 Success
Tag Description
<INVCLOSING> Closing-statement-response aggregate
<FITID> Unique identifier for this statement, FITID
<IMAGEDATA> Image data aggregate, see section 3.1.6.1
</IMAGEDATA>
</INVCLOSING>
Addressed message
Acknowledgment
Synchronization request
Response to customer
The client must identify to which investment account the customer query is related.
Tag Description
<INVMAILRQ> Investment-e-mail-request aggregate
<INVACCTFROM> Account-from aggregate, see 13.6.1
</INVACCTFROM>
</INVMAILRQ>
Tag Description
<INVMAILRS> Investment-e-mail-response aggregate
<INVACCTFROM> Account-from aggregate, see 13.6.1
</INVACCTFROM>
</INVMAILRS>
Code Meaning
0 Success (INFO)
Tag Description
<INVMAILSYNCRQ> Synchronization-request aggregate
</INVMAILSYNCRQ>
Tag Description
<INVMAILSYNCRS> Synchronization-response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest
entry in the server’s history table. In this case, some responses have
been lost.
N if the token in the synchronization request is newer than or matches a
token in the server’s history table. Boolean
<INVACCTFROM> Investment account of interest; token must be interpreted in terms of
this account, see 13.6.1
</INVACCTFROM>
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</INVMAILSYNCRS>
This user has one investment transaction, one bank transaction, one open order, two position entries, and
one balance entry. The user deposits some money and buys shares in Acme. The user has an open limit
order to buy 100 shares of Hackson Unlimited at $50/share. The holdings show the user already had 100
shares of Acme and now has 200 shares. The user also has one option contract to sell Lucky Airlines
shares, bought before this download.
This user is paying back a loan from the 401(k) account and then contributing pretax dollars. A transaction
is shown paying principal to Rollover and another paying interest to Rollover. Following that is a pretax
contribution transaction. This is then followed by the list of the 401(k) balances and finally the 401(k)
account information including a year-to-date summary.
14.1 Overview
Bill Presentment (PRES) is the electronic delivery of a bill from a biller to a customer.
Although some billers may provide Bill Presentment service themselves, many will choose to work with a
bill publisher that provides Bill Presentment service on behalf of many billers. For this reason, Bill
Presentment focuses on connecting customers to bill publishers.
For additional information about the message sets defined for Bill Presentment, see section 14.7.
<FINDBILLERRQ> and <FINDBILLERRS> are part of the Biller Directory message set
<PRESDIRMSGSETV1>. The message set tags are <PRESDIRMSGSRQV1> and
<PRESDIRMSGSRSV1>.
The Biller directory timestamp in the <FINDBILLERRQ> (<DTUPDATE>) selection criterion allows the
client to request all directory entries that have been added or changed since a point in time. Clients that
want to receive an updated list of billers and bill publishers can use <DTUPDATE> to avoid receiving a
response if nothing has changed. <DTUPDATE> is returned by servers in responses to indicate the date
and time of the newest or most recently changed entry, whether or not it was included in the response.
Clients performing narrow searches cannot use <DTUPDATE> unless they save the value for each query,
and send the corresponding value in future requests. Servers can return information using case-insensitive
matching, but this is not required.
Tag Description
<FINDBILLERRQ>
<DTUPDATE> Date and time of last change to any biller entry as reported by the server on
previous query, datetime.
If present, <FINDBILLERRS> will include only Billers whose information has
changed or been added since this time.
<BILLERID> ID of this biller at this bill publisher, A-32
<NAME> Biller’s name, A-32
<ADDR1> Biller’s address line 1, A-32
<ADDR2> Biller’s address line 2, A-32
<ADDR3> Biller’s address line 3, A-32
<CITY> Biller’s city, A-32
<STATE> Biller’s state, A-5
<POSTALCODE> Biller’s postal code, A-11
<COUNTRY> ISO/DIS-3166 3-letter country code standard, A-3
<SIC> Standard Industry Code, N-6
<CONSUPOSTALCODE> Postal code of customer, to allow server to filter out billers that do not do
business in the customer’s area, A-11
<INCIMAGES> Y if the client wants images (logos) returned, Boolean
</FINDBILLERRQ>
Note: Future versions of OFX will require <ADDR1> if <ADDR2> is specified and
<ADDR2> if <ADDR3> is specified.
Tag Description
<FINDBILLERRS>
<DTUPDATE> Date and time of last addition or modification to the entries in the directory, whether
part of this response or not, datetime
<BILLERINFO> Zero or more <BILLERINFO> aggregates
</BILLERINFO>
</FINDBILLERRS>
Besides basic name and address information, <BILLERINFO> includes the <BILLPUB> and
<BILLERID> elements. These elements will be used with the customer’s account number to identify the
customer’s account with the biller. For more information about the account-identification aggregates, refer
to <PRESACCTFROM> and <PRESACCTTO> in section 14.3.2.2.
<BILLERINFO> can optionally include elements that specify the format of valid account numbers.
<ACCTFORMAT> and <ACCTEDITMASK> provide information to the client. <HELPMESSAGE>
provides a text message that the client can display to the customer.
To avoid the complications caused by invalid account numbers, <BILLERINFO> can also include a
<VALIDATE>URL element that the client application can use to validate the customer’s account number.
See section 14.2.7 for more detail on this.
Tag Description
<BILLERINFO>
<ACCTFORMAT> Regular expression describing the account number format. For example,
^[0-9]{8,10}$ means the account number must be numbers only, and the
length must be 8 to 10 numbers. A-255
<ACCTEDITMASK> An alternative string describing the account number format. See below for
details. The client can use the edit mask to assist the user in entering the
account number. A-255
<HELPMESSAGE> Human-readable message that the client can display to assist the customer
in entering his or her account number. For example: “Enter in the last 10
digits of your account number without any spaces or dashes.” This is
defined by the biller during the implementation phase. A-255
<RESTRICT> Human-readable description of any restrictions on who may sign up with
this biller. For example: “Please be sure to enter each account number
separately if you have more than one account with us. Your mail bill will
be turned off only after another paper billing cycle has passed. Please note
that this program is initially available for account numbers beginning with
X Y and Z only.” This is defined by the biller during the implementation
phase. A-255
<LOGO> URL of the biller’s logo. If the client requested images, the logo should be
included via multipart MIME in this response. URL
<VALIDATE> URL for validation. The client application may use this to validate the
customer’s account number, see section 14.2.7. URL
<BILLERINFOURL> URL of human-readable description of additional information the biller
would like the customer to have with regard to signing up. URL
</BILLERINFO>
Note: Future versions of OFX will require <ADDR1> if <ADDR2> is specified and
<ADDR2> if <ADDR3> is specified.
Usage examples:
################
A 16-digit account number, separated by hyphens into 4-digit chunks. First four characters must be 4128:
4128-####-####-####
@@@@-#-#####
10-digit account number that must begin with 153AG, and whose final 5 characters are numbers:
153AG#####
Code Meaning
0 Success (INFO)
Example:
<VALIDATE> = http://testit.com/validate.cgi
Client application uses HTTP GET with “http://testit.com/validate.cgi?billerid=5454&accountnumber=123-456-
7890&customerpostalcode=12345”
In some cases, a biller may have arranged for a certain party to act as its payment concentrator. This means
that the biller expects to receive good funds and remit advice in a pre-arranged format from these
concentrators. Such a biller will want to have customers direct their payments to the payment concentrator.
In the <PAYMENTINSTRUMENTS> aggregate, billers list which payment instruments they accept.
Tag Description
<PAYMENTINSTRUMENTS> Opening tag for payment instruments
<PAYMENTINSTRUMENT> One or more payment instrument aggregates, see section 14.2.8.2
</PAYMENTINSTRUMENT>
Each payment instrument is described by <PMTINSTRUMENTTYPE> and <BRAND>. If the server does
not specify <BRAND>, the client assumes that all brands of the given <PMTINSTRUMENTTYPE> are
acceptable.
Tag Description
<PAYMENTINSTRUMENT> Opening tag for payment instrument aggregate
<PMTINSTRUMENTTYPE> Payment type, see section 14.2.8.3
<BRAND> Accepted brand for given payment type, A-32
</PAYMENTINSTRUMENT> Closing tag for payment instrument aggregate
Type Description
CONCENTRATOR Organization that has a business agreement with the biller to send the biller funds
and remittance advice.
<PAYMENTINSTRUMENT>
<PMTINSTRUMENTTYPE>CHECKINGACCOUNT</PMTINSTRUMENTTYPE>
</PAYMENTINSTRUMENT>
Bill Presentment uses the standard OFX Signup message set. This section discusses only those portions of
signup that differ for Bill Presentment. For more information about the Signup message set, refer to
Chapter 8, "Activation & Account Information."
The <ACCTINFORS> response returns a <PRESACCTINFO> aggregate for each of the customer’s
accounts with the billers at that bill publisher. Typically, the response will list only those accounts that
have been activated for Bill Presentment service, not all available accounts.
Unlike a financial institution, bill publishers generally won’t have information about all the accounts of its
supported billers. Billers that also serve as their own bill publishers may be able return available accounts
as well as activated accounts. The bill publisher can use the <AVAILACCTS> element in the profile for
the Signup message set to indicate whether the server can return available account information.
If the server cannot return information about all available accounts, the client must ask customers for
account information prior to requesting service activation for one or more accounts.
Tag Description
<PRESACCTINFO> Opening tag for bill presentment account information
<PRESACCTFROM> Bill presentment account identification, see section 14.3.2.2
</PRESACCTFROM>
<SVCSTATUS> Status of the Bill Presentment service for this account– AVAIL, PEND, ACTIVE,
or REJECTED
<REASON> Relevant only if <SVCSTATUS>REJECTED is specified, A-255
</PRESACCTINFO> Closing tag for bill presentment account information
The <PRESACCTFROM> aggregate uniquely identifies a customer’s account with a biller by the
combination of bill publisher, biller ID, and account number. Biller IDs must be unique within a bill
publisher.
Clients can optionally include a <USERID> in <PRESACCTFROM/TO> that is different from the one
used in the <SONRQ>. This <USERID> supports account activation by a third party on behalf of a user.
Based on access rights granted to the <SONRQ>, it is up to the server whether to honor such a request.
More than one <SVCADD> can be present in a a single <OFX> request file on behalf of multiple
<USERID>s.
The <USERID> element is disallowed for single-customer OFX request files. When sent by or returned to
a client proxy (or, other group context), any <PRESACCTFROM/TO> aggregates must include the
USERID element. A client proxy would include (and receive) this element when initiating an OFX
session. But, customer-specific clients initiating a session with the same server would never use or see this
information.
Note: <USERID> is not intended to identify individual users of joint accounts. If a transaction
might include two different USERIDs within otherwise identical <PRESACCTFROM>
aggregates, servers should deliver two separate bills (download the same bill twice in
<PRESLISTRS>), allow either to update the bill status (in <PRESNOTIFYRQ> or
<BILLSTATUSMODRQ>), or deliver two separate <PRESACCTINFO> aggregates in
<PRESGRPACCTINFOTRNRS>. It is up to the server to keep track of activity on joint
accounts.
The Bill Publisher would not normally know the <PAYEEID> and <PAYEELSTID> (or their <SPNAME>
context) information relevant to a particular client or user. But, after setting up (or changing) Biller as a
payee with some Payment provider, a client may execute a <SVCCHG> <ACCTRQ> request that updates
the corresponding <PRESACCTFROM> at the Bill Publisher. This request could pass payment identifiers
Tag Description
<PRESACCTFROM>
Tag Description
<PRESNAMEADDRESS> Customer name and address information
<NAMEACCTHELD> Customer’s name as it appears on the account, A-96
<BUSNAMEACCTHELD> Optional “Does Business As” name associated with this account, A-96
<ADDR1> Customer’s address line 1, A-32
<ADDR2> Customer’s address line 2, A-32
<ADDR3> Customer’s address line 3, A-32
<CITY> Customer’s city, A-32
<STATE> Customer’s state, A-5
<POSTALCODE> Customer’s postal code, A-11
<COUNTRY> Customer’s country; 3-letter country code from ISO/DIS-3166, A-3
<DAYPHONE> Customer’s telephone number, A-32
<EVEPHONE> Customer’s telephone number, A-32
</PRESNAMEADDRESS>
Note: Future versions of OFX will require <ADDR1> if <ADDR2> is specified and
<ADDR2> if <ADDR3> is specified.
The account service request aggregate <ACCTRQ> accepts action-specific aggregates for service
additions, changes, and deletions. To add Bill Presentment service to an account, the client sends an
<ACCTRQ> with an <SVCADD> for the service <SVC>PRESSVC.
When requesting service activation using <SVCADD>, <PRESACCTTO> is used to specify the
customer’s account with a specific biller. <PRESACCTTO> includes the optional
<PRESNAMEADDRESS> aggregate to identify the customer’s name and address as it is registered at the
biller. In most cases however, the address specified in the <ENROLLRQ> or most recent
<CHGUSERINFORQ> is used to provide the <PRESNAMEADDRESS> when activating an account.
Clients need only include <PRESNAMEADDRESS> if a special billing address is specified for the
In cases where <PRESACCTTO> is forwarded to other servers but enrollment information was used rather
than a client-provided <PRESNAMEADDRESS> aggregate, the <PRESNAMEADDRESS> information
is neither stored at the server nor returned to the originating client with the <PRESACCTTO> aggregate.
That is, clients which do not include the <PRESNAMEADDRESS> aggregate in their requests should
never see it in a later response from the server.
The server’s profile indicates support for storing <PRESNAMEADDRESS> information by including
<CANUPDATEPRESNAMEADDRESS>Y. In this case, <SVCCHG> requests may be used to update or
delete the <PRESNAMEADDRESS> information stored by the server. <CHGUSERINFORQ> requests
have no effect upon this information. Furthermore, no server-initiated transactions change the stored
address data. Servers must always return <PRESNAMEADDRESS> data exactly as the client sent it. The
presentment server may however forward a customer’s change of address entered via <SVCCHG> to the
proper biller.
For servers that support storing <PRESNAMEADDRESS>, the <PRESNAMEADDRESS> data can also
be used to support users who receive bills at multiple locations.
This section describes a method of checking for status changes on behalf of a group of customers within
the Bill Presentation service. This method is designed to be used by customer service representatives and
client proxy systems. This method applies only where <SVC> is PRESSVC. To check status for a single
customer, use the standard signup messages. For more information, see Chapter 8, "Activation & Account
Information."
The client uses <ACCTINFORQ> to request information about accounts whose status has changed since
the last time the request was made. This request is typically used to retrieve a list of accounts whose status
has changed from <SVCSTATUS>PEND to <SVCSTATUS>ACTIVE.
For use in the Bill Presentation message set, the <ACCTINFORQ> request must appear within a
<PRESGRPACCTINFOTRNRQ> transaction wrapper. This transaction wrapper includes the identifier for
the requested group. The <ACCTINFORQ> request may also appear in the <ACCTINFOTRNRQ>
wrapper described in Chapter 8, "Activation & Account Information."
Tag Description
<ACCTINFORQ> Opening tag for billing account information request
<DTACCTUP> Last <DTACCTUP> received in a response, datetime
<SVC> Zero or more. Services to be included in <ACCTINFORS>. If absent, all supported
services are being requested.
BANKSVC = Banking service
BPSVC = Payment service
INVSVC = Investments
PRESSVC = Bill Presentment service
The <ACCTINFORS> aggregate contains zero or more <ACCTINFO> aggregates, which provide the
updated account information.
For use in this message set, the <ACCTINFORS> response must appear within a
<PRESGRPACCTINFOTRNRS> transaction wrapper.
Tag Description
<ACCTINFORS> Opening tag for billing account information response
<DTACCTUP> Date and time of last update to account information on the server, datetime
<ACCTINFO> Zero or more account information aggregates, see section 8.5.4. Each
<ACCTINFO> aggregate contains at most one <PRESACCTINFO> aggregate,
consistent with section 8.5.4.
Left out of the response when no <SVC>PRESSVC accounts for the specified
<USERID> or <GROUPID> or current user are found.
Note: When <DTACCTUP> indicates the client is up-to-date, server should not
return surrounding <ACCTINFORS>.
</ACCTINFO>
If the client specifies <GROUPID>, the client is requesting updated account information for a group of
users. The server returns an <ACCTINFORS> response with a <PRESACCTINFO> aggregate for each
account whose status has changed.
Standard signup messages are the preferred method for checking the status of a single customer, however
<PRESGRPACCTINFOTRNRQ> may also be used for a single customer. (Standard signup messages are
described in Chapter 8, "Activation & Account Information." )
Tag Description
<PRESGRPACCTINFOTRNRQ> Opening tag for the transaction request
<TRNUID> Client-assigned globally unique ID for this transaction, trnuid
<CLTCOOKIE> Data to be echoed in the transaction response, A-32
<TAN> Transaction authorization number, A-80
Specify either <USERID> or
<GROUPID>
<USERID> Requests account information for the specified user, A-32
- or -
Note: Not sending a response aggregate in this case is an exception to rules outlined in
sections 2.4.6 and 3.1.5. And, sending a partial response (not every <ACCTINFO> aggregate
for the user or group, just changed information) differs from the normal processing of
<ACCTINFORQ> (see section 8.5). Within the Signup message set, the <ACCTINFORS>
contains all account information if any portion is out of date.
The server includes information for only those USERIDs for which the requester has access rights.
Note: <USERID> is not intended to identify individual users of joint accounts. If a transaction
might include two different USERIDs within otherwise identical <PRESACCTFROM>
aggregates, servers should deliver two separate copies of the account information (download
almost the same account information twice). It is up to the server to keep track of activity on
Tag Description
<PRESGRPACCTINFOTRNRS> Opening tag for the transaction response
<TRNUID> Client-assigned globally unique ID for this transaction, trnuid
<STATUS>
</STATUS>
Code Meaning
0 Success (INFO)
The aggregate for a bill list request is <PRESLISTRQ>. This request must be wrapped inside
<PRESLISTTRNRQ>. There is no synchronization wrapper for bill list requests, since clients that require
a list of bills can send another <PRESLISTRQ>.
The transaction wrapper <PRESLISTTRNRQ> contains optional elements that allow bills for one or more
customers to be accessed by customer service representatives or client proxy systems. It is up to the server
to decide who can access bills other than their own; it is recommended that all such access be logged in an
audit trail.
The client requests bills from a bill publisher by date range. To specify the date range, clients use
<DTSTART> and <DTEND>, as described in section 3.2.7. The date range includes all bills that were
added or modified within the date range.
The bill publisher returns information sufficient to identify the biller and provide the amount due, due date,
and remittance information so that a payment can be made to the biller. The bill publisher does not provide
a viewable form of the bill, but returns a URL to an HTML rendering of the bill. Billing detail, such as
individual purchases or transactions, can be included in the original response or obtained from a
subsequent <PRESDETAILRQ>.
Tag Description
<PRESLISTRQ> Opening tag for bill list request
<BILLPUB> Official standard name of bill publisher, A-32
<DTSTART> If present, indicates earliest date for which to include bills, datetime
<DTEND> If present, indicates latest date for which to include bills, datetime
<DTDUEBY> If present, indicates that the customer is requesting bills due on or before the
date/time specified in <DTDUEBY>. datetime
<BILLERID> Biller Identifier, If present, restricts the response to the given Biller, A-32
<BILLID> If present, restrict response to given statement identifier, A-32
<BILLTYPE> 0 or more. If present, indicates which types of bills the customer is
requesting. Possible values are:
BILL = Invoice of an amount due to the biller that is payable.
STATEMENT = History of activity on an account with the biller that is not
payable.
NOTICE = Generic letter from either the biller or the bill publisher that is
not payable.
<BILLSTATUSCODE> 0 or more. If present indicates which bill statuses the customer is requesting.
Possible values are:
NEW = The server has not sent the bill to either the client or client proxy.
This is the initial status code of a bill.
DELIVERED = The server has sent the bill to either a client or client proxy.
VIEWED = The customer has seen the bill. Implies previous status of
DELIVERED.
RETIRED = The customer no longer wishes to see this bill. Implies
previous status of DELIVERED.
WITHDRAWN = The biller or publisher no longer wishes this bill to be
displayed.
UNDELIVERABLE = Attempts to deliver this bill to the consumer in a
timely fashion have failed. This status is not generally used when presenting
a bill to a consumer. However, notifications using this status cover many
useful cases.
The <PRESLISTRS> response can contain zero or more bill summaries, with optional detail. Each bill
summary corresponds to a (usually monthly) bill. When a server has no bills to return, it should return
<STATUS><CODE>0 and leave out the <PRESLIST> within the <PRESLISTRS>.
When multiple selection criteria are used they are ANDed (as described in section 2.4.4.4). When counts
are requested in the <PRESLISTRQ> (<INCLUDECOUNTS>), the server should include counts of each
status requested where the bill’s <BILLSTATUSCODE> matches one of those specified in the
<PRESLISTRQ>, and the bill's <BILLPMTSTATUSCODE> matches one of those specified in the
<PRESLISTRQ>. Thus, a request containing <BILLSTATUSCODE>NEW,
<BILLSTATUSCODE>DELIVERED, <BILLSTATUSCODE>WITHDRAWN>,
<BILLPMTSTATUSCODE>NONE, and <BILLPMTSTATUSCODE>CANCELLED>, will return three
<BILLSTATUSCODE> counts and two <BILLPMTSTATUSCODE> counts. The sum of
<BILLSTATUSCODE> counts will be equal to the sum of the <BILLPMTSTATUSCODE> counts. No
inference can be drawn as to which bills have a combination of a specific <BILLSTATUSCODE> value
and a specific <BILLPMTSTATUSCODE> value.
Tag Description
<PRESLISTRS> Opening tag for bill list response
<BILLPUB> Official standard name of bill publisher, A-32
<USERID> User whose bill data is being returned. Must match <USERID>
provided in <PRESLISTTRNRQ> (if specified),
“anonymous00000000000000000000000” (if <GROUPID> was
specified in the <PRESLISTTRNRQ>), or the <USERID> for the
authenticated user (otherwise), A-32
<DTSTART> Start date of bills returned, datetime
<DTEND> Date to present as start date for next request, datetime
<PRESLIST> Bill summary list, see section 14.4.2.2.1
</PRESLIST>
<BILLPMTSTATUSCOUNTS> Bill Payment Status Counts, zero or more. The count(s) of all bills
matching the given selection criteria, having a particular payment
status(es). If <BILLPMTSTATUSCODE> is not included in the
request with <INCLUDECOUNTS>Y, counts are returned for every
payment status with a non-zero count.
<BILLPMTSTATUSCODE> Bill Payment Status Code, see section 14.4.2.2.4
<COUNT> Count of Bills with the given Bill Payment Status Code, Integer
</BILLPMTSTATUSSCOUNTS>
</PRESCOUNTS>
The bill list aggregate <PRESLIST> contains a list of zero or more <PRESBILLINFO> aggregates.
Tag Description
<PRESLIST> Opening tag for bill list
<PRESBILLINFO> Bill information aggregate (zero or more that meet the selection criteria)
While supported by the syntax of OFX, an empty <PRESLIST> aggregate should
not be transmitted.
</PRESBILLINFO>
The bill information aggregate <PRESBILLINFO> provides information about a single bill, including the
amount due, date due, and pointers to more information.
If the client requested bill detail in the <PRESLISTRQ>, the bill publisher provides the detail in zero or
more <BILLDETAILTABLE> aggregates. If the client did not request bill detail, the server should use the
<DETAILAVAILABLE> flag to indicate whether the client can request bill detail at a later time using the
<PRESDETAILRQ> aggregate.
The bill identifier <BILLID> must uniquely identify the bill with the bill publisher (not merely with the
biller). The <BILLPUB> and <BILLID> combination must be globally unique, not the <FI> and
<BILLID> combination.
Tag Description
<PRESBILLINFO> Opening tag for bill information
<BILLID> Identifier for this bill within the bill publisher, A-32
<PRESACCTFROM> Biller account information (see section 14.3.2.2)
</PRESACCTFROM>
<PAYEEID> Payee identifier. Specify only if the bill publisher is also provides Bill
Payment service. See section 14.5.2. SRVRTID
<BILLREFINFO> Biller-defined text to include with the payment, for the biller’s Accounts
Receivable reconciliation. Sections 14.5, 14.5.2. A-80
<AMTDUE> Full payment amount due, amount
<MINAMTDUE> Minimum payment amount due, amount
<DTPMTDUE> Payment due date, datetime
<DTBILL> Bill date, datetime
<DTOPEN> Opening statement date, datetime
<DTCLOSE> Closing statement date, datetime
<PREVBAL> Balance of the account as of the previous period, amount
<ACTIVITY> Net inflows and outflows for the account since the last period, amount
<ACCTBAL> Balance of the account at the end of the current period, amount
<INVOICE> Optional invoice data that the biller would like to receive with a payment (See
12.5.2.3). Client applications should allow the user to edit the amounts before
returning this in a payment
</INVOICE>
<NOTIFYDESIRED> Indicator that a delivery notification (see section 14.4.5) is desired, Boolean
<BILLTYPE> Bill Type. Possible values are:
BILL = Invoice of an amount due to the biller that is payable.
STATEMENT = History of activity on an account with the biller that is not
payable.
NOTICE = Generic letter from either biller or the bill publisher that is not
payable.
<BILLSTATUS> Zero or more bill status aggregates. See section 14.4.2.2.3.
</BILLSTATUS>
<BILLPMTSTATUS> Zero or more bill payment status aggregates. See section 14.4.2.2.4.
Choose DETAILAVAILABLE or
BILLDETAILTABLE, but not
both
<DETAILAVAILABLE> Indicator that structured detail is available, Boolean
-or-
If <PREVBAL>, <ACTIVITY>, and <ACCTBAL> are all present, then <PREVBAL> and <ACTIVITY>
must add up to <ACCTBAL>.
Note: This means payments from the consumer received by the biller are counted as negative
activity.
Tag Description
<BILLSTATUS>
Tag Description
<BILLPMTSTATUS> Zero or more bill payment status aggregates
<SRVRTID> The server transaction ID of the payment against this bill (see section 3.2.2),
A-36
<BILLPMTSTATUSCODE> Bill payment status code. Possible values are:
NONE = There is neither a payment scheduled, nor has one been made
against this bill.
SCHEDULED = A payment has been scheduled, but not yet processed
against this bill.
PROCESSED = The payment has been processed against this bill, and can
no longer be cancelled.
POSTED = The biller has posted the payment against this bill.
PAIDOUTOFBAND = A Payment has been initiated for this bill via a
mechanism that does not report status via OFX. This status is intended to
indicate the customer has paid the biller directly with cash or a check or has
initiated an electronic payment through a mechanism that does not report
payment status through OFX.
AUTOPAY = The Biller or Service Provider will initiate the payment based
on a pre-authorization by the customer, typically a “good until cancelled”
instruction with no defined end date. In the US this is often implemented
using a recurring pre-authorized ACH debit, though some Billers offer pre-
authorized automatic payment through credit card. Examples include
monthly deductions to cover a mortgage, regular payments from a checking
account to a credit card, and the Automatic Payment Service (APS) offered
by many utilities. Like NONE, this may be the initial payment status of the
bill.
CANCELLED = The customer cancelled the payment that was previously
scheduled.
UNPAYABLE = None of the Payment Instruments allowed for this bill are
supported by the Payment Provider. This is intended to be used where the
bill restricts payment to a subset of the Payment Instruments allowed in the
Biller Directory entry. This could occur if the Payment Provider or the
Biller changed their supported payment instrument types after enrollment
and account activation.
<DTEFF> Date/Time at which the status became effective (for example, the date and
time a bill is created in the initial status description for a bill). datetime
The <STMNTIMAGE> aggregate provides one or more URLs that point to a fully rendered image of the
bill, in HTML.
<IMAGEURL> accesses the complete bill image. This URL may contain navigation to other sites, or to
other pages of bill images at the same site.
To support off-line viewing of the bill, the server may provide one or more additional URLs. Each
<PREFETCHURL> points to a local Web page.
Each URL associated with <IMAGEURL> and <PREFETCHURL> must include an authentication token
at the end (for example, ?authtoken=randomString). These embedded tokens guarantee that only the
customer can access the Web page. Accessing the statement image requires transport-level security. The
bill publisher might include an expiration date for the authentication token, and hence for the URLs. The
expiration date could be quite short (for example, 1 hour) or quite long (for example, 1 month). After the
expiration date, the client can obtain a new authentication token only by sending a new <PRESLISTRQ>
request.
Tag Description
<STMNTIMAGE> Opening tag for statement image
<IMAGEURL> URL address for retrieving an image of the complete bill encoded as HTML. This
can be cached by the client for later display, or it can be viewed live directly from
the Web. URL
<PREFETCHURL> Advice in support of off-line viewing. Zero or more. URL
<DTEXPIRE> Date after which embedded authentication token expires, datetime
</STMNTIMAGE> Closing tag for statement image
As the transaction wrapper for <PRESLISTRQ>, this aggregate specifies whether the client is requesting
bills for a single user or a group of users. The optional <USERID> and <GROUPID> elements support the
following scenarios:
• A customer requests his or her own bills from the bill publisher: In this case, the client can
optionally specify the customer’s <USERID> in the <PRESLISTTRNRQ>. If the client does not
specify <USERID>, the bill publisher uses the <USERID> in the signon request <SONRQ>.
• A customer service representative requests a bill on behalf of a user: The client sends the
representative’s <USERID> in the signon request <SONRQ>. To specify the user for which the
representative is retrieving bills, the client sends the customer’s <USERID> in the
<PRESLISTTRNRQ>. The bill publisher must ultimately decide whether the customer service
representative can access the requested bills. In its response, the bill publisher includes only those bills
for which the requester has access privileges.
• A client proxy system fetches bills on behalf of a group of users: Instead of sending a <USERID>,
the client sends the <GROUPID> that identifies the group of users. Within the <PRESLISTTRNRS>,
the bill publisher returns a single <PRESLISTRS> containing zero or more <PRESBILLINFO>
aggregates for each user in the named group. Individual customers are distinguished using the
<USERID> element of each <PRESACCTFROM> in the <PRESBILLINFO> aggregates. Again, the
bill publisher decides whether access should be granted. Bill publishers that support usage of
<GROUPID> must maintain knowledge of which users are in which named group. The OFX
specification does not provide a way to track membership in a named group. Any such management
must happen out-of-band.
Note: <USERID> is not intended to identify individual users of joint accounts. If a transaction
might include two different USERIDs within otherwise identical <PRESACCTFROM>
aggregates, servers should deliver two separate bills (download the same bill twice). It is up to
the server to keep track of activity on joint accounts.
<GROUPID> If present, the bill request is on behalf of all users in the named group. If both
<USERID> and <GROUPID> are absent, the <USERID> in the <SONRQ> is
implied. A-32
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
Tag Description
<PRESLISTTRNRS> Opening tag for bill list transaction response
<TRNUID> Client-assigned globally unique ID for this transaction trnuid
<STATUS> Status aggregate
</STATUS>
Code Meaning
0 Success (INFO)
Tag Description
<PRESDETAILRQ> Opening tag for bill detail request
<BILLID> Statement identifier from <PRESBILLINFO>, A-32
<BILLDETAILTABLETYPE If present, filters response to just tables of this type (See table 14.4.3.2.3), A-
> 32.
</PRESDETAILRQ> Closing tag for bill detail request
Tag Description
<PRESDETAILRS> Opening tag for bill detail response
<PRESDETAIL> Zero or more bill detail aggregates
<BILLID> Statement identifier from <PRESBILLINFO>, A-32
<PRESACCTFROM> Identifies biller account, see section 14.3.2.2. Must be included if in response
to an <PRESDETAILRQ>, is redundant inside <PRESBILLINFO>
</PRESACCTFROM>
<BILLDETAILTABLE> Zero or more bill detail table aggregates. See section 14.4.3.2.1.
</BILLDETAILTABLE>
The bill detail table allows billers to send tabular data to the customer in a flexible way. The table might
contain phone calls from a telephone bill, or electrical meter readings for a utility bill.
A table consists of one or more rows, each having one or more columns. Within a table, all rows must have
identical structures. The <BILLDETAILTABLETYPE> determines the “shape” or schema of the table.
The <TABLENAME> gives a name to this table, and should be unique within an <PRESDETAILRS>
Note: The bill detail table may be redesigned in the future. Please consider this area “under
construction.”.
Tag Description
<BILLDETAILTABLE> Opening tag for bill detail table
<TABLENAME> Name of bill detail table, A-32
<BILLDETAILTABLETYPE> Type of bill detail table (See section 14.4.3.2.3), A-32.
<BILLDETAILROW> Zero or more bill detail row aggregates, see section 14.4.3.2.2
</BILLDETAILROW>
A <BILLDETAILROW> contains zero or more columns <C>, whose meanings are specific to the type of
table <BILLDETAILTABLETYPE> in which they occur. For the purpose of the DTD parser, all columns
<C> are consider to be Format: A-255.
OFX requires all elements return data. If bill publishers do not use specific columns, they can return null
columns, represented by the element <N>. All columns <N> are considered to be Format: A-1.
Note: Bill publishers must include one character of data in a null column. Bill publishers can
omit blank columns at the end of a <BILLDETAILROW>, tag and all. DTD should not enforce
ordering, i.e. it should look like this:
Tag Description
<BILLDETAILROW> Opening tag for bill detail row
<C> Zero or more column data elements, A-255
<N> Zero or more column data elements, A-1
</BILLDETAILROW> Closing tag for bill detail row
OFX defines some common table types. Individual billers can define their own table types, and hence their
own table structures, but must honor the custom tag naming convention outlined in section 2.7.
Value Description
The TransactionList table type is a subset of the <STMTTRN> aggregate in section 11.4.4.1.
6 CorrectBillId If present, unique identifier of previously sent transaction that is corrected by this
record, A-32
Code Meaning
0 Success (INFO)
Clients need only request the structure of tables it does not already know about. For instance, the client
might request the structure of a biller-specific table that starts with the x- prefix. Knowing the structure of
a table allows the client to display the data more clearly or store the data in a more compact form, such as a
database table.
To identify the table, the client includes the type of table <BILLDETAILTABLETYPE> and unique
identifier <BILLID> for the table. Although <BILLDETAILTABLETYPE> uniquely identifies the table,
OFX requires the <BILLID> as well to allow various server implementations.
Tag Description
<BILLTBLSTRUCTRQ> Opening tag for the table structure request
<BILLID> Statement Identifier, A-32
<BILLDETAILTABLETYPE> Table type for which the structure is requested (See table 14.4.3.2.3), A-32.
</BILLTBLSTRUCTRQ> Closing tag for the table structure request
The table structure response contains one or more column type definitions, which correspond positionally
with the <C> aggregates in a <BILLDETAILROW> in a <BILLDETAILTABLE> of the corresponding
<TABLETYPE>.
Tag Description
<BILLTBLSTRUCTRS> Opening tag for table structure response
<BILLID> Table identifier, A-32
<BILLDETAILTABLETYPE> Table type (See table 14.4.3.2.3), A-32.
<COLDEF> Zero or more column definition aggregates (see section 14.4.4.2.1)
</COLDEF>
A column definition <COLDEF> associates a name and a data type with a column.
Tag Description
<COLDEF> Opening tag for column definition
<COLNAME> Column name, A-32
<COLTYPE> Column type, valid values are (choose one): (A-255, D, N-6), A-8. Specifying D
in this field means the column type is datetime.
</COLDEF> Closing tag for column definition
Code Meaning
0 Success (INFO)
The bill publisher can request delivery notification through the <NOTIFYDESIRED> flag in the
<PRESBILLINFO> aggregate (see section 14.4.2.2.2). The bill publisher will expect to receive the
delivery notification only if the <PRESLISTRQ> had the <NOTIFYWILLING> flag set.
The delivery notification request tells the bill publisher that the client has presented the specified bills to
the customer. This is a stronger statement than acknowledging that the bills have been received by the
client, specifically when the client software implements the pre-fetching or (push) model. Delivery
notification should be sent only once for any given bill, and it should be sent the first time that the Bill
Summary is displayed. Receipt of a delivery notification by the bill publisher has no legal significance.
OFX does not define the maximum elapsed time between the presentation of the bill and the delivery
notification.
In OFX 1.6, a new Bill Status Modify request, <BILLSTATUSMODRQ>, was added. This new request
(see section 14.4.6.1) should be used instead of <PRESNOTIFYRQ>.
Tag Description
<PRESNOTIFYRQ> Opening tag for delivery notification request
<PRESDELIVERYID> A bill delivery ID aggregate (see section 14.4.5.1.1)
</PRESDELIVERYID>
This aggregate identifies a bill delivery instance and suggests when the bill was “seen.”
<DTSEEN> is the date and time at which the client displayed the bill to the customer. There is no legal
significance to this bill delivery identification.
Tag Description
<PRESDELIVERYID> Opening tag for the bill delivery identification
<PRESACCTFROM> Biller account information, see section 14.3.2.2
</PRESACCTFROM>
In OFX 1.6, a new Bill Status Modify request, <BILLSTATUSMODRS>, was added. This new request
(see section 14.4.6.2) should be used instead of <PRESNOTIFYRS>.
The delivery notification response lets the client know that the delivery notification request was received
by the bill publisher.
Tag Description
<PRESNOTIFYRS> Opening tag for Delivery Notification Response
<PRESDELIVERYID> A bill delivery ID aggregate (See section 14.4.5.1.1)
</PRESDELIVERYID>
Code Meaning
0 Success (INFO)
Tag Description
<BILLSTATUSMODRQ>
</BILLSTATUSMODRQ>
Tag Description
<BILLSTATUSMODRS>
<BILLPMTSTATUS> Bill payment status aggregate. Echoed from the request. See section 14.4.2.2.4.
</BILLPMTSTATUS>
</BILLSTATUSMODRS>
Code Meaning
0 Success (INFO)
If the same company provides Bill Presentment and Bill Payment services, the client can use the
<PAYEEID> included in the <PRESBILLINFO> aggregate.
If the Bill Payment provider is a different company, the client must use information from the
<PRESACCTINFO> to construct the <PAYEE> information.
The server acknowledges receipt of the message. The bill publisher then prepares a response that the client
picks up when it synchronizes with the server. E-mail is subject to synchronization, using
<PRESMAILSYNCRQ> (defined in section 14.6.4) and <PRESMAILSYNCRS> (defined in section
14.6.5.)
Addressed message
PRES account
information
Acknowledgment
Synchronization request
Response to customer
Tag Description
<PRESMAILRQ> PRES-e-mail-request aggregate
<PRESACCTFROM> Account-from aggregate, see section 14.3.2.2
</PRESACCTFROM>
</PRESMAILRQ>
Tag Description
<PRESMAILRS> PRES-e-mail-response aggregate
<PRESACCTFROM> Account-from aggregate, see section 14.3.2.2
</PRESACCTFROM>
</PRESMAILRS>
Code Meaning
0 Success (INFO)
Tag Description
<PRESMAILSYNCRQ> Synchronization request aggregate
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</PRESMAILSYNCRQ>
Tag Description
<PRESMAILSYNCRS> Synchronization response aggregate
<TOKEN> New synchronization token, token
<LOSTSYNC> Y if the token in the synchronization request is older than the earliest entry in
the server’s history table. In this case, some responses have been lost.
N if the token in the synchronization request is newer than or matches a token
in the server’s history table. Boolean
<PRESACCTFROM> Account-from aggregate, see section 14.3.2.2
</PRESACCTFROM>
<OFXEXTENSION> OFX extension aggregate; see Section 2.7.2 for more information
</OFXEXTENSION>
</PRESMAILSYNCRS>
This section defines the message sets supported by Bill Presentment. It then describes the corresponding
message set profile aggregates that can be provided in the profile response <PROFRS>. The message set
profile aggregates for the <PROFRS> allow a bill publisher or other server provider to customize its use of
OFX. For example, a server might support the Bill Delivery message set <PRESDLVMSGSET>, but not
the Group Account Information message set <PRESDIRMSGSET>.
The following tables show the OFX transactions and their corresponding transaction wrappers for a
particular message set.
<PRESDIRMSGSETV1>
<PRESDIRMSGSRQV1> FINDBILLERTRNRQ
FINDBILLERRQ
</PRESDIRMSGSRQV1>
</PRESDIRMSGSETV1>
</PRESDIRMSGSET>
<PRESDIRMSGSETV1>
<PRESDIRMSGSRSV1> FINDBILLERTRNRS
FINDBILLERRS
</PRESDIRMSGSRSV1>
</PRESDIRMSGSETV1>
</PRESDIRMSGSET>
PRESLISTRQ
PRESDETAILTRNRQ
PRESDETAILRQ
BILLTBLSTRUCTTRNRQ
BILLTBLSTRUCTRQ
BILLSTATUSMODTRNRQ
BILLSTATUSMODRQ
PRESNOTIFYTRNRQ
PRESNOTIFYRQ
PRESGRPACCTINFOTRNRQ
ACCTINFORQ
PRESMAILTRNRQ
PRESMAILRQ
PRESMAILSYNCRQ
</PRESDLVMSGSRQV1>
PRESLISTRS
PRESDETAILTRNRS
PRESDETAILRS
BILLTBLSTRUCTTRNRS
BILLTBLSTRUCTRS
BILLSTATUSMODTRNRS
BILLSTATUSMODRS
PRESNOTIFYTRNRS
PRESNOTIFYRS
PRESGRPACCTINFOTRNRS
ACCTINFORS
PRESMAILTRNRS
PRESMAILRS
PRESMAILSYNCRS
</PRESDLVMSGSRSV1>
</PRESDIRMSGSETV1>
</PRESDIRMSGSET> Closing tag for the Biller Directory message set profile
Tag Description
<PRESDLVMSGSET> Opening tag for the Bill Delivery message set profile
<PRESDLVMSGSETV1> Version 1 of Bill Delivery message set, one or more
<MSGSETCORE> Common message-set core
</MSGSETCORE>
</PRESDLVMSGSETV1>
</PRESDLVMSGSET> Closing tag for the Bill Delivery message set profile
The client sends a <FINDBILLERRQ> request, as shown in the following example, to retrieve all
available billers.
Note: These examples show the customer signing on anonymously. But, they may have
enrolled in the past and choose to use their actual <USERID> and <USERPASS>. Anonymous
signon is not required for use of the Biller Directory service (see section 14.2.1).
In the following example, the client requests only those billers that are located in Ohio.
Note: These examples show the customer signing on anonymously. But, they may have
enrolled in the past and choose to use their actual <USERID> and <USERPASS>. Anonymous
signon is not required for use of the Biller Directory service (see section 14.2.1).
</STATUS>
<FINDBILLERRS>
<DTUPDATE>20050415092000</DTUPDATE>
<!--Date last update 04/15/99 9:20am-->
<BILLERINFO>
<BILLPUB>Wepubbills</BILLPUB><!--Name of Bill Publisher-->
<BILLERID>123456789</BILLERID><!--Biller ID at Wepubbills-->
<NAME>RealBig Credit Co.</NAME>
<!--Name of biller-->
<OFX>
<SIGNONMSGSRQV1> <!--Signon Request-->
<SONRQ>
<DTCLIENT>20050307022243</DTCLIENT><!--Timestamp, 3/07/99,
2:22:43am-->
<USERID>anonymous00000000000000000000000</USERID>
<USERPASS>anonymous00000000000000000000000</USERPASS>
<LANGUAGE>ENG</LANGUAGE>
<APPID>OFXAPP</APPID>
<APPVER>0201</APPVER>
</SONRQ>
</SIGNONMSGSRQV1>
<SIGNUPMSGSRQV1> <!--Enrollment Request-->
<ENROLLTRNRQ>
<TRNUID>10001</TRNUID>
<ENROLLRQ>
<FIRSTNAME>Cindy</FIRSTNAME>
<MIDDLENAME>P</MIDDLENAME>
<LASTNAME>Williams</LASTNAME>
<ADDR1>123 Oak St</ADDR1>
<CITY>San Jose</CITY>
<STATE>CA</STATE>
<POSTALCODE>94111<POSTALCODE>
<COUNTRY>USA</COUNTRY>
<DAYPHONE>415-555-0123</DAYPHONE>
<EVEPHONE>408-555-2323</EVEPHONE>
<EMAIL>[email protected]</EMAIL>
<USERID>cindyid</USERID>
<TAXID>111-33-5555</TAXID>
<SECURITYNAME>wynona</SECURITYNAME>
<DATEBIRTH>19650402</DATEBIRTH>
</ENROLLRQ>
</ENROLLTRNRQ>
</SIGNUPMSGSRQV1>
</OFX>
For this example, the server responds with immediate acceptance. In practice, many servers would send an
enrollment status code of 13000 and send the user ID and password in a welcome letter.
<OFX>
<SIGNONMSGSRSV1> <!--Signon response->
<SONRS>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<DTSERVER>20050307081437</DTSERVER><!--Timestamp, 3/07/05,
8:14:37am-->
<LANGUAGE>ENG</LANGUAGE>
<DTPROFUP>19990301070000</DTPROFUP><!--Timestamp, 3/01/99,
7:00:00am-->
<DTACCTUP>19990301070000</DTACCTUP><!--Timestamp, 3/01/99,
7:00:00am-->
</SONRS>
</SIGNONMSGSRSV1>
<SIGNUPMSGSRSV1> <!--Enrollment response-->
<ENROLLTRNRS>
<TRNUID>10001</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<ENROLLRS>
<TEMPPASS>y12345</TEMPPASS>
<USERID>cindyid</USERID>
<DTEXPIRE>20050407</DTEXPIRE><!--When Temp Password Expires-->
</ENROLLRS>
</ENROLLTRNRS>
</SIGNUPMSGSRSV1>
</OFX>
<OFX>
<SIGNONMSGSRQV1> <!--Signon Request-->
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<SIGNUPMSGSRQV1> <!--Activation Request-->
<ACCTTRNRQ>
<TRNUID>10002</TRNUID>
<ACCTRQ> <!—-Activate biller acct -->
<SVCADD>
<PRESACCTTO>
<BILLPUB>Publisher, Inc.</BILLPUB>
<BILLERID>415-552-9923</BILLERID>
<ACCTID>4128 9343 2324 2314</ACCTID>
<PRESNAMEADDRESS>
<NAMEACCTHELD>Cindy P Williams</NAMEACCTHELD><!--Name as
on biller’s statement-->
<ADDR1>123 Oak St</ADDR1><!--Address as on statement-->
<CITY>San Jose</CITY>
<STATE>CA</STATE>
<POSTALCODE>94111</POSTALCODE>
<COUNTRY>USA</COUNTRY>
<DAYPHONE>408-555-2323</DAYPHONE>
</PRESNAMEADDRESS>
<USERID>cindyid</USERID>
</PRESACCTTO>
</SVCADD>
<SVC>PRESSVC</SVC>
</ACCTRQ>
</ACCTTRNRQ>
</SIGNUPMSGSRQV1>
</OFX>
<OFX>
<SIGNONMSGSRSV1> <!--Signon Response->
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<SIGNUPMSGSRSV1> <!--Enrollment Response-->
<ACCTTRNRS> <!--Service Activation Response-->
<TRNUID>10002</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<ACCTRS>
<SVCADD>
<PRESACCTTO>
<BILLPUB>Publisher, Inc.</BILLPUB>
<BILLERID>415-552-9923</BILLERID>
<ACCTID>4128 9343 2324 2314</ACCTID>
<PRESNAMEADDRESS>
<NAMEACCTHELD>Cindy P Williams</NAMEACCTHELD>
<ADDR1>123 Oak St</ADDR1>
<CITY>San Jose</CITY>
<STATE>CA</STATE>
<POSTALCODE>94111</POSTALCODE>
<COUNTRY>USA</COUNTRY>
<DAYPHONE>408-555-2323</DAYPHONE>
</PRESNAMEADDRESS>
<USERID>cindyid</USERID>
</PRESACCTTO>
</SVCADD>
<SVC>PRESSVC</SVC>
</ACCTRS>
</ACCTTRNRS>
</SIGNUPMSGSRSV1>
</OFX>
The customer, Dan North, wants to see his bills since 3/1/99, which is the last time he asked to see his bills.
<OFX>
<SIGNONMSGSRQV1>
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<PRESDLVMSGSRQV1>
<PRESLISTTRNRQ>
<TRNUID>12345</TRNUID>
<PRESLISTRQ>
<BILLPUB> ABillPublisher</BILLPUB>
<DTSTART>20050301000000</DTSTART><!--Get Dan's bills since 3/
1/05-->
<NOTIFYWILLING>Y</NOTIFYWILLING>
<INCLUDEDETAIL>Y</INCLUDEDETAIL>
</PRESLISTRQ>
</PRESLISTTRNRQ>
</PRESDLVMSGSRQV1>
</OFX>
<OFX>
<SIGNONMSGSRSV1>
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<PRESDLVMSGSRSV1>
<PRESLISTTRNRS>
<TRNUID>12345</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY
</STATUS>
This example assumes that Dan North calls Power Inc with a question about his power bill. Power's
customer service representative, Maria Smith, uses a similar application and a similar OFX request to see
the same bill that Dan sees.
<OFX>
<SIGNONMSGSRQV1>
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<PRESDLVMSGSRQV1>
<PRESLISTTRNRQ>
<TRNUID>23456/<TRNUID>
<USERID>MyUserID</USERID><!--Asks for Dan North’s bills -->
<PRESLISTRQ>
<BILLPUB> ABillPublisher</BILLPUB>
<DTSTART>20050330</DTSTART><!--Approximate date -->
<DTEND>2005040410</DTSTART><!--Approximate date -->
<NOTIFYWILLING>N</NOTIFYWILLING>
<INCLUDEDETAIL>Y</INDLUDEDETAIL>
</PRESLISTRQ>
</PRESLISTTRNRQ>
</PRESDLVMSGSRQV1>
</OFX>
The response from the server includes the Power Incorporated bill, but not the FluteRental bill. This is
because the server decides that Maria Smith’s credentials are good enough to see Dan North’s Power Inc
bill, but not good enough to see anything else.
In this example, Realtors Company downloads the phone bills for the employees’ office phones by asking
the bill publisher to see the bills for the group RealtorsEmployees. The composition of the group
RealtorsEmployees has been agreed upon between Realtors Company and the bill publisher; moreover, the
bill publisher has agreed to grant Realtors Company access rights to the RealtorsEmployees group. All this
took place outside of OFX.
<OFX>
<SIGNONMSGSRQV1>
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<PRESDLVMSGSRQV1>
<PRESLISTTRNRQ>
<TRNUID>34567<TRNUID>
<GROUPID>RealtorsEmployees</GROUPID><!--Asks for Employee’s
phone bills-->
<PRESLISTRQ>
<BILLPUB> ABillPublisher</BILLPUB>
<DTSTART>20050430</DTSTART><!--since 4/30/2005-->
<NOTIFYWILLING>N</NOTIFYWILLING>
<INCLUDEDETAIL>Y</INCLUDEDETAIL>
</PRESLISTRQ>
</PRESLISTTRNRQ>
</PRESDLVMSGSRQV1>
</OFX>
The response, not shown here, will include several bills each marked with its own <USERID>. The only
bills returned will be the employees’ phone bills for their office phones, since those bills are the only ones
to which Realtor Company has access rights.
This is an example of a client proxy system that is tracking changes to the accounts of a group of users.
<OFX>
<SIGNONMSGSRQV1> <!--Signon Request->
<SONRQ> <!-- ...Sign on request. For a
complete example, see section
11.14.1-->
</SONRQ>
</SIGNONMSGSRQV1>
<PRESDLVMSGSRQV1> <!--Group Account Info Request-->
<PRESGRPACCTINFOTRNRQ>
<TRNUID>10001</TRNUID>
<GROUPID>AClientProxysCustomers</GROUPID>
<!--Predefined group of customers-->
<ACCTINFORQ>
<DTACCTUP>19990104</DTACCTUP><!--Last DTACCTUP received for
group-->
</ACCTINFORQ>
</PRESGRPACCTINFOTRNRQ>
</PRESDLVMSGSRQV1>
</OFX>
<OFX>
<SIGNONMSGSRSV1> <!--Signon Response->
<SONRS> <!-- ...Sign on response. For a
complete example, see section
11.14.1-->
</SONRS>
</SIGNONMSGSRSV1>
<PRESDLVMSGSRSV1> <!--Group Account Info Response-->
<PRESGRPACCTINFOTRNRS>
<TRNUID>10001</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<ACCTINFORS>
<DTACCTUP>19990122092431</DTACCTUP>
<ACCTINFO>
15.1 Overview
As more financial services companies offer users access to information over the internet, paper statements
are being replaced with electronic statement images. Additionally, with the passing of federal law "Check
21", financial institutions now have an ability to truncate checks and convert them to images at the
originating institutions. Consequently, users may no longer receive cancelled checks, deposit tickets, and
monthly statements via regular mail.
OFX addresses a growing need for communicating images information in an electronic format by allowing
clients to request transaction and statement images as part of the statement and closing statement requests,
respectively. The server has several options available to support image download requests (see sections
15.2.1 through 15.2.3).
The client requests image identifier data by sending an OFX statement download or closing request with
the tags <INCTRANIMG>Y or <INCSTMTIMG>Y, respectively. (The statement download and/or
closing requests are among those found in the Banking, Credit Card, Investments and/or Loan message
sets.) If an image is available, the server sends back one or more <IMAGEDATA> aggregates in the
response. (More than one <IMAGEDATA> aggregate might be returned for check images.) The
<IMAGEDATA> aggregate contains data necessary for retrieving the actual image. Each image is
represented by one <IMAGEDATA> aggregate. (See section 3.1.6.1 for a description of the
<IMAGEDATA> aggregate.)
The retrieval method used to get the actual image is dependent on the value of <IMAGEREFTYPE> in the
<IMAGEDATA> aggregate. These values are OPAQUE, URL or FORMURL and the corresponding
methods are described in sections 15.2.1, 15.2.2 and 15.2.3, below.
<IMAGEREFTYPE>OPAQUE
The OPAQUE moniker requires the client to send an OFX request to access an image. This request will be
in the form of a normal OFX request (complete with Signon) and includes an <IMAGERQ> request as
described in section 15.2.1.1. However, whereas the request file contains typical OFX syntax, the
successful response returned is in the form of raw bytes. If a failure condition occurs, the response should
be as described in Section 15.2.1.3.
The client sends a single <IMAGERQ> request corresponding to each <IMAGEDATA> aggregate
associated with the OPAQUE moniker. Each <IMAGERQ> request must be sent in its own OFX request
file. Only one image is returned for each <IMAGERQ>, that is, for each OFX request file.
The <IMAGERQ> request must appear within the <IMAGETRNRQ> transaction wrapper.
Tag Description
<IMAGERQ> Image request aggregate
<IMAGEREF> Image identifier from <IMAGEDATA> aggregate, see section 3.1.6.1, A-1024
</IMAGERQ> End of image request aggregate
The successful response to an OFX <IMAGERQ> request is a complete HTTP response followed by a
series of raw bytes. The HTTP response contains content-type set to a supported image type, e.g. image/
jpeg. The allowed types in the response are shown in the table below.
Type Description
image/jpeg JPEG images
image/tiff TIFF images
Application/pdf PDF documents
image/png PNG images
Code Meaning
<IMAGEREFTYPE>URL
The URL moniker does not require the client to send an OFX request to access an image. Instead, the client
issues an HTTP request to the URL specified as the value of the <IMAGEREF> tag in the
<IMAGEDATA> aggregate. The client will then authenticate. Once this authentication takes place, the
image can be displayed.
<IMAGEREFTYPE>FORMURL
The FORMURL moniker does not require the client to send an OFX request to access an image. Instead,
the client issues an HTTP request, with encoded data specified in the URL retrieved from the
<IMAGEREF> tag in the <IMAGEDATA> aggregate. The image can then be displayed. See Section
15.2.3.1, below, for more information about the HTTP POST request.
Clients use the HTTP POST command to send a request to the previously acquired URL for the desired
financial institution. The URL identifies a service on an FI server that can accept an image request and
produce a response.
The POST identifies the data as being of content-type application/x-www-form-urlencoded. The OFX
client will send a request using HTTP POST (over ) formatted as an HTML FORM. The form may include
financial institution identification, client application identification, user ID, password, and image reference
fields as shown in the table below.
<form name
="RequestOFXImages"
method="post"> Description
<input name="APPID"> ID of client application, A-5
<input name="APPVER"> Version of client application (6.00 encoded as 0600), N-4
<input name="ORG"> Organization defining this FI namespace, A-32
<input name="FID"> ID of the financial institution, A-32
<input name="USERID"> User website identification string, String–255
<input name="USERPASS"> User password on website, String-255
<input name="CRED2"> Secondary user website identification string, if required, String-255
<input name="CRED3"> Tertiary user website identification string, if required, String-255
<input name="IMAGEREF"> Unique identifier for the image, A-1024
Some web sites require more than the standard <USERID> <USERPASS> provided by OFX. This
specification includes optional secondary credentials <CRED2> and <CRED3> for financial institution
websites that require them. Special characters and spaces within the user ID or password will be encoded
using standard URL encoding.
IMAGETRNRQ
IMAGERQ
</IMAGEMSGSRQV1>
Tag Description
<IMAGEMSGSET> Message set for images
<IMAGEMSGSETV1> Version 1 of message set.
<MSGSETCORE> Common message set core
</MSGSETCORE>
<DFLTIMAGEDELAY> Default number of calendar days from <DTSERVER> (for statement images) or
<DTPOSTED> (for transaction images) when image will become available. If
not present, the value is presumed to be 0, N-5
Can be overridden, for each image, by either <IMAGEDELAY> or
<DTIMAGEAVAIL> in the <IMAGEDATA> aggregate.
<DFLTIMAGETTL> Number of calendar days the image will remain available on the host once the
image becomes available. If not present, the value is presumed to be indefinitely,
N-5
Can be overridden, for each image, by <IMAGETTL> in the <IMAGEDATA>
aggregate.
</IMAGEMSGSET>
The request includes a request for transaction images. The response contains an updated balance for the
account, two transactions and image information for one of the transactions.
<OFX>
<SIGNONMSGSRQV1>
<SONRQ>
...
<OFX>
<SIGNONMSGSRQV1>
<SONRQ>
...
</SONRQ>
</SIGNONMSGSRQV1>
<IMAGEMSGSRQV1>
<IMAGETRNRQ>
<TRNUID>99887</TRNUID>
<IMAGERQ>
<IMAGEREF>4448444</IMAGEREF>
</IMAGERQ>
</IMAGETRNRQ>
Successful response:
The response is a complete HTTP response.
The following are OFX fragments; the missing OFX is covered in other request/response examples. (For
readability, the end tags for element tags are not shown.)
Request:
<PROFMSGSRQV1>
<PROFTRNRQ>
<TRNUID>974495445
<PROFRQ>
<CLIENTROUTING>MSGSET
<DTPROFUP>20021107103100.000[-5:EST]
</PROFRQ>
</PROFTRNRQ>
</PROFMSGSRQV1>
Response:
<PROFMSGSRSV1>
<PROFTRNRS>
<TRNUID>974495445
<STATUS>
<CODE>0
<SEVERITY>INFO
</STATUS>
<PROFRS>
<MSGSETLIST>
<SIGNONMSGSET><SIGNONMSGSETV1>
<MSGSETCORE>...</MSGSETCORE>
</SIGNONMSGSETV1></SIGNONMSGSET>
<BANKMSGSET><BANKMSGSETV1>
<MSGSETCORE>...</MSGSETCORE>
<CLOSINGAVAIL>Y
<XFERPROF>
...
</XFERPROF>
<EMAILPROF>
...
</EMAILPROF>
<form name
="RequestOFX"
method="post"> Description
<input name="APPID"> ID of client application, A-5
<input name="APPVER"> Version of client application (6.00 encoded as 0600), N-4
<input name="ORG"> Organization defining this FI namespace, A-32
<input name="FID"> ID of the financial institution, A-32
<input name="USERID"> User website identification string, String–255
<input name="USERPASS"> User password on website, String-255
<input name="CRED2"> Secondary user website identification string, if required, String-255
<input name="CRED3"> Tertiary user website identification string, if required, String-255
<CLIENTUID> Unique ID identifying OFX client, A-36
<MFA_XXX> 0 or more MFA Challenge Question answers. The tag name must correspond to
the MFAPHRASEID in the last received MFACHALLENGERS.
<input name="DTSTART"> Start date of statement requested using ISO 8601 standard YYYY-MM-DD, e.g.
2005-07-16
<input name="DTEND"> End date of statement requested using ISO 8601 standard YYYY-MM-DD, e.g.
2005-07-16
<input name="INCTRAN"> Include-transaction aggregate
If value = Y, website should include the following in the OFX formatted file
when available:
<BANKTRANLIST> in <STMTRS>
<BANKTRANLIST> in <CCSTMTRS>
<INVTRANLIST> in <INVSTMTRS>
<LOANTRANLIST> in <LOANSTMTRS>
<AMRTTRANLIST> in <AMRSTMTRS>
Additionally, some web sites require a <CLIENTUID> tag. This tag should be a value unique to the client
installation.
The form request sends the date without any time value. The website should interpret the date as it applies
on their website.
Upon receipt of a request for a statement for an invalid account, the website should respond to the request
with an "OFX-STATUS=2003" in the HTTP response.
The website should ignore this value if it does not coincide with the account type on record, if possible.
Otherwise, it may respond to the request with an "OFX-STATUS = 2003" in the HTTP response. Refer to
section 16.2.2.
200 OK The request was processed and a valid Open Financial Exchange result is
returned.
400s Bad request The request was invalid and was not processed. Clients will report an internal
error to the user.
500s Server error The server is unavailable. Clients should advise the user to retry shortly.
Open Financial Exchange requires the following HTTP standard headers in the response returned
by the website:
Content- length Length (given in bytes) of the data after removing HTTP headers
length
Having authenticated the request, the website responds with an OFX download, just as if the customer had
manually entered the request on the site.
<OFX>
... Open Financial Exchange response following the OFX specification...
</OFX>
Code Meaning
To support such solutions, Automatic 1-way OFX clients need to handle redirection and cookies just like a
generic web browser would.
It is up to the FI, however, to include the details of the 1-way OFX request together with the proof of
authentication token to the application site where the request is processed and the response is generated.
The client only knows about the initial URL where the authentication happens. If the processing needs to
be done on a different URL, the client does support redirection and cookies but it does not post the request
details again to the redirect target URL.
Clients use the HTTP POST command to send a request to the previously acquired URL for the desired
financial institution. The URL presumably identifies a Common Gateway Interface (CGI) or other process
on an FI server that can accept an Automatic 1-Way OFX request and produce a response.
The POST identifies the data as being of type application/x-www-form-urlencoded. The OFX client will
send a request using HTTP POST (over ) formatted as an HTML FORM. The form includes client
application identification, user ID, password, date range, and account ID fields. When sending the request,
the client should omit fields with NULL values.
The following are examples of request and response pairs using this new format. For simplicity, the HTTP
Headers are left out of these examples. Responses are indented for readability.
16.5.1.1 Request
APPID=MyOFXApp&APPVER=0600&USERID=MyID&USERPASS=My$ecretPwd&INCTRAN=Y
16.5.1.2 Response
OFX-STATUS=15509
16.5.2.1 Request
APPID=MyOFXApp&APPVER=0600&USERID=MyID&USERPASS=My$ecretPwd&INCTRAN=Y
16.5.2.2 Response
<?OFX OFXHEADER="200" VERSION="220" SECURITY="NONE" OLDFILEUID="NONE"
NEWFILEUID="NONE"?>
<OFX>
<SIGNONMSGSRSV1>
<SONRS>
<STATUS>
<CODE>3000</CODE>
<SEVERITY>ERROR</SEVERITY>
</STATUS>
<DTSERVER>20050831165153.000[-8:PST]</DTSERVER>
<LANGUAGE>ENG</LANGUAGE>
</SONRS>
<MFACHALLENGETRNRS>
<MFACHALLENGERS>
<MFACHALLENGE>
<MFAPHRASEID>MFA_4</MFAPHRASEID>
16.5.2.3 Request 2
APPID=MyOFXApp&APPVER=0600&USERID=MyID&USERPASS=My$ecretPwd&DTSTART=200
4-08-01&DTEND=2004-08-31&INCTRAN=Y&MFA_4=William&MFA_12=1234&MFA_18=Acme
16.5.2.4 Response 2
OFX-Status=0
16.5.3.1 Request
APPID=MyOFXApp&APPVER=0600&USERID=MyID&USERPASS=My$ecretPwd&DTSTART=20
05-08-01&DTEND=2005-08-31&INCTRAN=Y
16.5.3.2 Response
<?xml version="1.0" encoding="USASCII"?>
<?OFX OFXHEADER="200" VERSION="220" SECURITY="NONE" OLDFILEUID="NONE"
NEWFILEUID="NONE"?>
16.5.3.3 Request 2
16.5.3.4 Response 2
<?xml version="1.0" encoding="US-ASCII"?>
<?OFX OFXHEADER="200" VERSION="220" SECURITY="NONE" OLDFILEUID="NONE"
NEWFILEUID="NONE"?>
<OFX>
<SIGNONMSGSRSV1>
<SONRS>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<DTSERVER>20050831165153.000[-8:PST]</DTSERVER>
<LANGUAGE>ENG</LANGUAGE>
</SONRS>
</SIGNONMSGSRSV1>
<BANKMSGSRSV1>
<STMTTRNRS>
<TRNUID>0</TRNUID>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<STMTRS>
<CURDEF>USD</CURDEF>
<BANKACCTFROM>
<BANKID>000000123</BANKID>
<ACCTID>123456</ACCTID>
<ACCTTYPE>CHECKING</ACCTTYPE>
</BANKACCTFROM>
<BANKTRANLIST>
<DTSTART>20040801</DTSTART>
<DTEND>20050831165153.000[-8:PST]</DTEND>
<STMTTRN>
<TRNTYPE>POS</TRNTYPE>
<DTPOSTED>20050824080000</DTPOSTED>
<TRNAMT>-80</TRNAMT>
<FITID>219378</FITID>
<NAME>FrogKick Scuba Gear</NAME>
The user has both a checking and a savings account. The financial institution website only provides
statements for the last 30 days, but does return empty statements. The response is shown in OFX 1.0.2
format.
16.5.4.1 Request
APPID=MyOFXApp&APPVER=0600&USERID=MyID&USERPASS=Dog44%26Cat22&DTSTART=
2005-01-01&INCTRAN=Y
16.5.4.2 Response
OFXHEADER:100
DATA:OFXSGML
VERSION:102
SECURITY:NONE
ENCODING:USASCII
CHARSET:1252
COMPRESSION:NONE
OLDFILEUID:NONE
NEWFILEUID:NONE
<OFX>
<SIGNONMSGSRSV1>
<SONRS>
<STATUS>
<CODE>0
<SEVERITY>INFO
</STATUS>
<DTSERVER>20050831165056.000[-8:PST]
<LANGUAGE>ENG
16.5.5.1 Request
APPID=MyOFXApp&APPVER=0600&USERID=MyID&USERPASS=My$ecretPwd&ACCTID=123
456-90
16.5.5.2 Response
<?xml version="1.0" encoding="USASCII"?>
<?OFX OFXHEADER="200" VERSION="220" SECURITY="NONE" OLDFILEUID="NONE"
NEWFILEUID="NONE"?>
<OFX>
<SIGNONMSGSRSV1>
<SONRS>
<STATUS>
<CODE>0</CODE>
<SEVERITY>INFO</SEVERITY>
</STATUS>
<DTSERVER>20050831165153.000[-8:PST]</DTSERVER>
<LANGUAGE>ENG</LANGUAGE>
16.5.6.1 Request
APPID=MyOFXApp&APPVER=0600&USERID=MyID&USERPASS=My$ecretPwd&CRED2=125673
4&DTSTART=20050801&DTEND=20050831&INCTRAN=Y&INCPOS=Y&INCBAL=Y&ACCTID=1
256734
16.5.6.2 Response
OFXHEADER:100
DATA:OFXSGML
VERSION:102
SECURITY:NONE
ENCODING:USASCII
CHARSET:1252
COMPRESSION:NONE
OLDFILEUID:NONE
NEWFILEUID:NONE
<OFX>
<SIGNONMSGSRSV1>
<SONRS>
<STATUS>
<CODE>0
<SEVERITY>INFO
</STATUS>
<DTSERVER>20050831165324.000[-8:PST]
<LANGUAGE>ENG
</SONRS>
</SIGNONMSGSRSV1>
<INVSTMTMSGSRSV1>
<INVSTMTTRNRS>
<TRNUID>0
<STATUS>
<CODE>0
<SEVERITY>INFO
</STATUS>
<INVSTMTRS>
This is a request for positions and balances only for an investment account. For clarify, the client specifies
that this is a retirement account. The response is returned in OFX 2.2 format.
16.5.6.4 Request
APPID=MyOFXApp&APPVER=0600&USERID=MyID&USERPASS=My$ecretPwd&INCPOS=Y&
INCBAL=Y&ACCTID=12679356&ACCTTYPE=RETIREMENT
16.5.6.5 Response
<?xml version="1.0" encoding="USASCII"?>
<?OFX OFXHEADER="200" VERSION="220" SECURITY="NONE" OLDFILEUID="NONE"
<OFX>
<SIGNONMSGSRSV1>
<SONRS>
<STATUS>
<CODE>0
<SEVERITY>INFO
</STATUS>
<DTSERVER>20050831165324.000[-8:PST]
<LANGUAGE>ENG
</SONRS>
</SIGNONMSGSRSV1>
<INVSTMTMSGSRSV1>
<INVSTMTTRNRS>
<TRNUID>0
<STATUS>
<CODE>0
<SEVERITY>INFO
</STATUS>
<INVSTMTRS>
<DTASOF>20050831165324.000[-8:PST]
<CURDEF>USD
<INVACCTFROM>
<BROKERID>Broker Site
<ACCTID>1256734
</INVACCTFROM>
<INVTRANLIST>
<DTSTART>20050101
<DTEND>20050831165324.000[-8:PST]
<BUYMF>
<INVBUY>
<INVTRAN>
<FITID>40025098199608029240
<DTTRADE>20030802
<MEMO>MONEY MARKET FUND
</INVTRAN>
<SECID>
<UNIQUEID>808515100
<UNIQUEIDTYPE>CUSIP
</SECID>
<UNITS>120.00
Note: If a server must send an unsupported message to an earlier client, it should include a
<MESSAGE> element describing the general error.
1 Client is up-to-date (INFO) Based on the client timestamp, the client has
the latest information. The response does not
supply any additional information.
2000 General error (ERROR) Error other than those specified by the
remaining error codes.
2002 General account error (ERROR) Account error not specified by the remaining
error codes.
2003 Account not found (ERROR) The specified account number does not
correspond to one of the user’s accounts.
2005 Account not authorized The user is not authorized to perform this
(ERROR) action on the account, or the server does not
allow this type of action to be performed on
the account.
2006 Source account not found The specified account number does not
(ERROR) correspond to one of the user’s accounts.
2007 Source account closed (ERROR) The specified account number corresponds to
an account that has been closed.
2008 Source account not authorized The user is not authorized to perform this
(ERROR) action on the account, or the server does not
allow this type of action to be performed on
the account.
2009 Destination account not found The specified account number does not
(ERROR) correspond to one of the user’s accounts.
2011 Destination account not The user is not authorized to perform this
authorized (ERROR) action on the account, or the server does not
allow this type of action to be performed on
the account.
2012 Invalid amount (ERROR) The specified amount is not valid for this
action; for example, the user specified a
negative payment amount.
2014 Date too soon (ERROR) The server cannot process the requested
action by the date specified by the user.
2015 Date too far in future (ERROR) The server cannot accept requests for an
action that far in the future.
2016 Transaction already committed Transaction has entered the processing loop
(ERROR) and cannot be modified/cancelled using
OFX. The transaction may still be cancelled
or modified using other means (for example,
a phone call to Customer Service).
2018 Unknown server ID (ERROR) The specified server ID does not exist or no
longer exists.
2019 Duplicate request (ERROR) A request with this <TRNUID> has already
been received and processed.
2021 Unsupported version (ERROR) The server does not support the requested
version. The version of the message set
specified by the client is not supported by this
server.
2022 Invalid TAN (ERROR) The server was unable to validate the TAN
sent in the request.
624
Code Meaning Condition
2023 Unknown FITID (ERROR) The specified FITID/BILLID does not exist
[BILLID not found (ERROR) in or no longer exists.
the billing message sets]
2026 Bank name doesn’t match bank The value of <BANKNAME> in the
ID (ERROR) <EXTBANKACCTTO> aggregate is
inconsistent with the value of <BANKID> in
the <BANKACCTTO> aggregate.
2027 Invalid date range (ERROR) Response for non-overlapping dates, date
ranges in the future, et cetera.
2028 Requested element unknown One or more elements of the request were not
(WARNING) recognized by the server or the server (as
noted in the FI Profile) does not support the
elements. The server executed the element
transactions it understood and supported. For
example, the request file included private
tags in a <PMTRQ> but the server was able
to execute the rest of the request.
3000 MFA Challenge authentication User credentials are correct, but further
required (ERROR) authentication required. Client should send
<MFACHALLENGERQ>.
10501 Invalid payee (ERROR) Payee error not specified by the remaining
error codes.
10502 Invalid payee address (ERROR) Some portion of the payee’s address is
incorrect or unknown.
10503 Invalid payee account number The account number <PAYACCT> of the
(ERROR) requested payee is invalid.
10504 Insufficient funds (ERROR) The server cannot process the request
because the specified account does not have
enough funds.
10505 Cannot modify element The server does not allow modifications to
(ERROR) one or more values in a modification request.
10508 Invalid frequency (ERROR) The specified frequency <FREQ> does not
match one of the accepted frequencies for
recurring transactions.
10509 Model already canceled The server has already canceled the specified
(ERROR) recurring model.
10510 Invalid payee ID (ERROR) The specified payee ID does not exist or no
longer exists.
10511 Invalid payee city (ERROR) The specified city is incorrect or unknown.
10512 Invalid payee state (ERROR) The specified state is incorrect or unknown.
10513 Invalid payee postal code The specified postal code is incorrect or
(ERROR) unknown.
10514 Transaction already processed Transaction has already been sent or date due
(ERROR) is past
10515 Payee not modifiable by client The server does not allow clients to change
(ERROR) payee information.
626
Code Meaning Condition
10516 Wire beneficiary invalid The specified wire beneficiary does not exist
(ERROR) or no longer exists.
10517 Invalid payee name (ERROR) The server does not recognize the specified
payee name.
10518 Unknown model ID (ERROR) The specified model ID does not exist or no
longer exists.
10519 Invalid payee list ID (ERROR) The specified payee list ID does not exist or
no longer exists.
10600 Table type not found (ERROR) The specified table type is not recognized or
does not exist.
12251 Investment position download The server does not support investment
not supported (WARN) position download.
12252 Investment positions for The server does not support investment
specified date not available positions for the specified date.
(WARN)
12253 Investment open order download The server does not support open order
not supported (WARN) download.
12254 Investment balances download The server does not support investment
not supported (WARN) balances download.
12255 401(k) not available for this 401(k) information requested from a non-
account (ERROR) 401(k) account.
12500 One or more securities not found The server could not find the requested
(ERROR) securities.
13000 User ID & password will be sent The server will send the user ID and
out-of-band (INFO) password via postal mail, e-mail, or another
means. The accompanying message will
provide details.
13500 Unable to enroll user (ERROR) The server could not enroll the user.
13501 User already enrolled (ERROR) The server has already enrolled the user.
13502 Invalid service (ERROR) The server does not support the service
<SVC> specified in the service-activation
request.
13503 Cannot change user information The server does not support the
(ERROR) <CHGUSERINFORQ> request.
13504 <FI> Missing or Invalid in The FI requires the client to provide the <FI>
<SONRQ> (ERROR) aggregate in the <SONRQ> request, but
either none was provided, or the one provided
was invalid.
14500 1099 forms not available 1099 forms are not yet available for the tax
(ERROR) year requested.
14501 1099 forms not available for user This user does not have any 1099 forms
ID (ERROR) available.
14600 W2 forms not available W2 forms are not yet available for the tax
(ERROR) year requested.
14601 W2 forms not available for user The user does not have any W2 forms
ID (ERROR) available.
14700 1098 forms not available 1098 forms are not yet available for the tax
(ERROR) year requested.
14701 1098 forms not available for user The user does not have any 1098 forms
ID (ERROR) available.
15000 Must change USERPASS The user must change his or her
(INFO) <USERPASS> number as part of the next
OFX request.
15500 Signon invalid (ERROR) The user cannot signon because he or she
entered an invalid user ID or password.
15501 Customer account already in use The server allows only one connection at a
(ERROR) time, and another user is already signed on.
Please try again later.
15502 USERPASS lockout (ERROR) The server has received too many failed
signon attempts for this user. Please call the
FI’s technical support number.
15503 Could not change USERPASS The server does not support the <PINCHRQ>
(ERROR) request.
15504 Could not provide random data The server could not generate random data as
(ERROR) requested by the <CHALLENGERQ>.
15505 Country system not supported The server does not support the country
(ERROR) specified in the <COUNTRY> field of the
<SONRQ> aggregate.
15506 Empty signon not supported The server does not support signons not
(ERROR) accompanied by some other transaction.
628
Code Meaning Condition
15507 Signon invalid without The OFX block associated with the signon
supporting pin change request does not contain a pin change request and
(ERROR) should.
15508 Transaction not authorized. Current user is not authorized to perform this
(ERROR) action on behalf of the <USERID>.
15509 Multiple accounts not supported 1-Way server does not support returning
(ERROR) multiple accounts in response.
15510 CLIENT UID invalid (ERROR) CLIENTUID error. User must register the
Client UID.
15511 User contact required (ERROR) User should contact financial institution
16500 HTML not allowed (ERROR) The server does not accept HTML formatting
in the request.
16501 Unknown mail To: (ERROR) The server was unable to send mail to the
specified Internet address.
16502 Invalid URL (ERROR) The server could not parse the URL.
16503 Unable to get URL (ERROR) The server was unable to retrieve the
information at this URL (e.g., an HTTP 400
or 500 series error).
16510 Image not available yet The image is not available yet; try again later.
(ERROR)
16511 Image Expired (ERROR) The image was available, but is no longer
available (has expired).
16513 Image server not available Image server is not available; try again later
(ERROR)
Account
Type Abbreviation
Credit Card CC
Checking CH
Savings SA
Loan / LMC
Mortgage /
Credit Line
TD / CD TD
Amount Deposited This Month Amount Deposited This Month CH, SA, LMC, CD
Amount Withdrawn This Month Amount Withdrawn This Month CH, SA, LMC
Interest Paid Year To Date Interest Paid Year To Date CH, SA, TD
Total Amount Due Now Total Amount Due Now CC, LMC
1) The Data Formatting standard has changed from that of SGML to XML.
4) A new Tax OFX Addendum which adds support for 1099 and W2 download has been added and is
available separately bound from this document.
Note that some detailed changes are not shown below if they are part of one of the changes above and thus
are identified that way. 401(k) changes have been itemized in full, however.
Global SGML->XML Change The Data Formatting standard has changed from
that of SGML to XML.
Global End tags required Change Ends tags are now required. All examples were
changed as well as textual references to end tags.
Global Header changed Change The OFX header has changed from that of an
SGML-type header to a standard XML declaration
syntax. Examples were changed as appropriate.
Global V2 eliminated Change V2 tags and message sets have been eliminated.
<SRVRTID2>, <TOKEN2>, <MESSAGE2> and
<URL2> are among those tags that have been
deleted.
Global "1.6 add" tags eliminated Change All "1.6 add" tags were eliminated except those in
the bill presentment message set and
<REFRESHSUPT> in <MSGSETCORE>
2.3 Special character handling Change Special characters are predefined in XML.
3.1.2.1 Handling of user values Clarification This section was rewritten to clarify rules for
handling user values by a client or server.
6.4 Token and Addition New section added to clarify rules for token and
Synchronization Summary synchronization handling.
11.7 Immediate Transfers Clarification Clarified handling of immediate transfers which are
batched and done that night or next day.
13.6.3.2 New section on download Addition Entitled, "Note on Downloading Positions and
detail Transaction Detail for Investment Accounts"
13.8.4 SECLIST return info Clarification better description of when to return <SECLIST>
13.9.2.4.2 WITHHOLDING Change Indicates that this element is for federal taxes only.
description changed
13.9.2.4.3 401(k) verbiage added Addition Describes funding loans or other withdrawals
13.9.2.4.3 Some elements added Change New elements added to INVBUY and INVSELL
13.9.2.7 </BAL> no longer bolded Correction Corrected mismatch between beginning/ending tags
13.9.2.9 Status code added to table Addition Error status code 12255 added
Appendix Status code 12254 Addition Investment Balances Download not supported
A (WARN)
Appendix Status code 14500 Addition 1099 forms not available (ERROR)
A
Appendix Status code 14501 Addition 1099 forms not available for user ID (ERROR)
A
Appendix Status code 14601 Addition W2 forms not available for user ID (ERROR)
A
Change
Section Subject Type Change
2.5.2 pin change and error recovery Clarification Paragraph 3 (regarding status code
15000) clarified
6.10.2.1 Lite Synch and Older Clients/ Clarification Reworded because confusing
Servers
8.8 Signup profile information Clarification Slight change to clarify what is required
in the Signup profile response.
10.3.1 models and sync behavior Addition New section clarifying proper behavior
for models
11.7.2.2 <INTRAMODRS> introduction Correction Servers may, but are not required to,
notify clients of changes in transfer
status.
11.13.1 Message Sets and Messages Clarification Fixed format of tables to be clearer.
12.11.1 Message Sets and Messages Clarification Fixed format of table to be clearer.
12.12 bill pay examples Corrections fixed some bugs in bill pay examples
13.7.1.2 Message Sets and Messages Clarification Fixed format of table to be clearer.
13.7.2.2 Message Sets and Messages Clarification Fixed format of table to be clearer.
13.9.2.6.1 <DTPRICEASOF> clarification Correction Removed text that said this datetime
value could be zero if unknown.
14.7.1.2 Message Sets and Messages Clarification Fixed format of table to be clearer.
Appendix A Added error codes Addition 14700 and 14701 (for 1098 tax)
Appendix Added <CCACCTFROM> change Correction In OFX 2.0, CCACCTFROM was added
C, "Diff. to all transfer sync RQ/RS’s but this was
Between mistakenly left out of the 1.6 -> 2.0
OFX 1.6 change appendix.
and 2.0"
Change
Section Subject Type Change
3.2.8.1 Timezone name not required Clarification Clarification that timezone name is not
required in a timezone
12.7.3.3 Addition to Status Code Table Addition 2017 ("Already Cancelled") added to
<RECPMTCANCRS> table
13.6.3.2 Note on downloading positions and Correction The Note in this section was changed to
transaction detail refer to all accounts, not just 401K
accounts
13.11 Signage of <TOTAL> in examples Correction Changed the signage of <TOTAL> from
positive to negative for <BUYSTOCK>
and <BUYMF> aggregates
13.11 Closing tag fixed in example Correction A closing tag for <DTSTART> was
changed to </DTSTART>
2) ANUALLY was changed to ANNUAL and SEMIANNUALLY was changed to SEMIANNUAL in the
COUPONFREQ enumeration type.
3) The ordering of tags INV401KDNLDand CANEMAIL was reversed; CANEMAIL should come first.
1) The addition of Loan statement, closing, and amortization schedule download plus loan email
2) The addition of image download in banking, credit card, investment and loan message sets (new
chapter).
Global Using Social Security Change Removed references to SSN from examples
Number as UserID and text to discourage use of SSNs for
identification purposes.
Global Dates in examples Change An attempt was made to update examples with
more recent dates (specifically, year 2005).
1.1.1 Added references to loans, Addition Added 3 bullets under Broad Range of
images and 1-Way OFX Financial Activities
1.2.3 Automatic 1-Way OFX Addition New section to discuss 1-Way OFX
2.4.5.2, New Message sets Addition Added references to Loan and Image message
2.4.5.3, sets
2.8.4
2.5.1, Using SSNs for UserID/ Addition Added verbiage to discourage Financial
2.5.1.1 Password Institutions from using Social Security
Number for Customer ID or PIN/Password.
8.4.1 Using SSNs for UserID/ Addition Verbiage added to discourage Financial
password Institutions from using Social Security
Number for Customer ID or PIN/Password.
11.4.1 Added verbiage about image Addition Paragraph added at end of section
download of transactions
11.4.3 New tag and aggregate in Addition Added <EXTDNAME> and <IMAGEDATA>
<STMTTRN> to <STMTTRN>
11.5 Added verbiage about image Addition Paragraph added at end of section
download of statements
11.5.5 - New sections for Loan Stmt Addition <LOANSTMTENDRQ> and related
11.5.8 Closing aggregates added
11.11.4 New section for Loan e-mail Addition <LOANMAILRQ> and related aggregates
11.12.2 What transfers to Clarification Clariified note after table about synchronizing
11.12.3.2 synchronize only on <xxxACCTFROM> account
11.12.5.2
11.13 Loan support verbiage Addition Added bullet describing new loan support
11.13.1.5 Loan RQ/RS tables added Addition New tables showing loan requests/responses
13.9.1 Added verbiage about image Addition Paragraph added at end of section
download of statements
13.9.1.2 Added verbiage for images Addition Paragraph added just before table
13.10 New Closing rq/rsp Addition New section for investment closing
15 New Images Chapter Addition New chapter describing Image Message Set
Appendi Status code 15509 for 1-Way Addition Multiple accounts not supported (ERROR)
xA
Appendi Status code 16510 for Images Addition Image not available yet; try again later
xA (ERROR)
Appendi Status code 16511 for Images Addition Image has expired; not longer available
xA (ERROR)
Appendi Status code 16512 for Images Addition Image Reference Identifier not found
xA (ERROR)
Appendi Status code 16513 for Images Addition Image server is not available; try again later
xA (ERROR)
2.5.1 Preventing identity fraud Change Added verbiage discouraging use of SSN for
USERID or USERPASS.
2.5.1.2 New tags in <SONRQ> for Addition New tags added to Signon Request
MFA <SONRQ>: CLIENTUID, USERCRED1,
USERCRED2, AUTHTOKEN, ACCESSKEY,
MFACHALLENGEA
2.5.1.3 New tag in <SONRS> for Addition New tag added to Signon Response
MFA <SONRS>: ACCESSKEY
2.5.1.4 New error codes Addition New MFA error codes added to <SONRS>
Status Code table
2.5.4 New OFX request/response Addition New section added for MFA request/response
<MFACHALLENGERQ>,
<MFACHALLENGERS>
3.1.5 New entries in status code Addition Added some error codes for MFA to
table <SONRS> status code table
7.2.2 <CHGPINFIRST> Change Text was added to state that if the profile tag
description MFACHALLENGEFIRST is ’Y’ the pin
change request should be sent immediately
after the session containing
MFACHALLNEGE authentication.
10.2.1 Adjusting due date of a Clarification Models are free to adjust the due date of a
payment payment if this date falls on a non-processing
day.
16.1 Added tags to Auto 1-Way Addition Added CLIENTUID and MFA_XXX tags
Request for MFA
16.1.2 New section for MFA Addition New section "Challenge Question Answers"
16.2.2 Status code table Addition New status codes for MFA
16.5.2 Example for MFA Addition Added example showing use of MFA
challenge questions/answers
Appendi New Status code 3000 Addition User credentials are correct, but further
xA authentication required. Client should send
MFACHALLENGERQ (ERROR)
Appendi New Status code 15510 Addition CLIENTUID error. User must register the
xA Client UID (ERROR)
Appendi New Status code 15511 Addition User should contact financial institution
xA (ERROR)
Appendi New Status code 15512 Addition User needs to contact financial institution to
xA obtain AUTHTOKEN. Client should send it in
the next request (ERROR)
1) Authentication changes allowing user credentials to be fully replaced with an access token
2) A new method for extending OFX which avoids schema coordination for validating parsers
3) A new mechanism for pending transactions for banking and credit card download
4) Multiple new data elements for banking and credit card download (interest rates, credit card payment
information)
8) Reconciled schema between OFX 2.2 and Tax (as of 2015 tax year)
Global " " vs " " sentence breaks Change Changed all " " to " " between sentences.
Document contained mixture (1 space
between sentences is now the standard in
the document)
Global Add OFXEXTENSION into all Addition Added <OFXEXTENSION> into all
xxxSYNCRQ/RS and all aggregate definition tables for
xxxTRNRQ/RS tables synchronization and transaction
wrappers, profile responses, and selected
RQ/RS aggregates not subject to
transaction wrappers.
1.1.1 Design Principles Change Added 1095 and 1098 reference and
reworded addendum reference
1.4 OFX Version History Change Added OFX 2.2 overview including
reference to Tax Schema reconciliation
2.4.5.3 Message Set Version Numbers Change Added 2.2 to all message sets
2.5.1 to Complete restructuring and Change/New Section 2.5.1 included multiple topics in
2.5.1.3.3 expansion of 2.5.1 a disorganized manner. Multiple levels of
subsections created to clarify and present
information in organized fashion
2.5.1.5 New tags in <SONRQ> Addition New tags added to Signon Request
<ACCESSTOKEN> and <APPKEY>
2.7, 2.7.1, <OFXEXTENSION> addition Change Rewrote Section 2.7 splitting out private
2.7.2, 2.7.3 to OFX extensions tags and adding <OFXEXTENSION>
New
definition and example into the section
11.4 Downloading Transactions and Addition Added reference to OFX 2.2 new
Balances mechanism for pending transaction
download
Added reference to CD accounts
11.4.2 Bank Statement Download Change Added references to OFX 2.2 pending
transaction model and new aggregates/
tags
Added reference to CD accounts
11.4.3 Credit Card Statement Change Cleaned up reference back to 11.4.2 and
Download expanded the reference
11.13.3 Credit Card Message set profile Addition Added <PENDINGAVAIL> flag
Appendix New Status Code 13505 Addition Server undergoing maintenance; try again
A later (ERROR)
1) Personally Identifiable Information (PII) retrievable at the user or account level, including a new OFX
request/response, <USERINFORQ> and <USERINFORS>
2) New cash advance tags for credit cards. A new tag, <CASHADVAVAILAMT>, has been added in
OFX 2.2.1. For consistency, all 3 tags <CASHADVBALAMT>, <CASHADVAVAILAMT>, and
<CASHADVCREDITLIMIT> have been added to <CCSTMTRS> and CCSTMTENDRS>.
Previously, the client could not determine these values, or had to calculate the values when possible
given available tags. Tags in CCSTMTRS represent current or “real-time” values and tags in
CCCLOSING represent values at the time of the statement closing.
5) Deprecation of <HOLDERINFO>
1.2.1 HTTP Version Change Added (or more recent HTTP 1.x)
1.4 OFX Tax Specification Change Noted the removal of the OFX Tax
Specification from this document
8.5.4.3 User contact information Addition Added user contact information with new
<CONTACTPROF>/ table of <CONTACTPROF> and
<CONTACTPROFENC> <CONTACTPROFENC> tags
16.2.1 HTTP Version Change Added (or more recent HTTP 1.x)
The cover page was updated with FDX graphics and the document version number was changed from
2.2.1 to 2.3 throughout.
652
BILLPMTSTATUSCODE 524, 526, 527, 531 CANMODPMTS 407
BILLPMTSTATUSCOUNTS 527 CANMODSTATUS 557
BILLPUB 353, 507, 507, 515, 523, 526, 527, CANMODXFERS 584
559, 560, 561, 563, 567, 568, 569, 570, CANNOTIFY 323, 557
571, 572, 573, 575, 577 CANPENDING 180, 280, 280, 287, 339, 340,
BILLPUBCONTEXT 407 379, 380, 422, 423
BILLPUBINFO 353 CANRECUR 322, 584
BILLREFINFO 353, 353, 528, 546, 570, 571, CANRECURLOAN 322
573 CANSCHED 322, 322, 325, 326
BILLSTATUS 528, 530, 545 CANSCHEDLOAN 322
BILLSTATUSCODE 523, 526, 530 CANSUPPORTGROUPID 556
BILLSTATUSCOUNTS 526 CANSUPPORTIMAGES 556, 557
BILLSTATUSMODRQ 543, 545, 545, 557 CANUPDATEPRESNAMEADDRESS 517, 557
BILLSTATUSMODRS 544, 545, 545 CANUSEDESC 322
BILLSTATUSMODTRNRQ 545 CANUSERANGE 322
BILLTBLSTRUCTRQ 540, 541, 541 CASESEN 136
BILLTBLSTRUCTRS 541, 541, 542 CASHADVAVAILAMT 212, 237
BILLTBLSTRUCTTRNRQ 541 CASHADVBALAMT 209, 212, 237
BILLTBLSTRUCTTRNRS 541 CASHADVCREDITLIMIT 213, 237
BILLTYPE 523, 528 CASHBAL 477
BODY 167, 168, 169 CCACCTFROM 74, 81, 187, 191, 191, 194,
BPACCTINFO 351, 351 195, 203, 210, 212, 221, 222, 224, 235,
BRANCHID 187, 189, 625 239, 243, 253, 262, 290, 291, 299, 300,
BRAND 512, 512, 560, 562, 564 301, 302, 305, 306, 307, 308, 309, 310
BROKERCONTACTINFO 478 CCACCTINFO 194
BROKERID 431, 491, 492, 497, 498 CCACCTTO 191, 191, 195, 216, 225
BUSNAME 151, 152 CCCLOSING 235, 236, 236, 237
BUSNAMEACCTHELD 516 CCSTMTENDRQ 203, 235, 235, 239
BUYDEBT 463 CCSTMTENDRS 235, 235
BUYMF 463 CCSTMTENDTRNRQ 235
BUYOPT 463 CCSTMTENDTRNRS 235
BUYOTHER 431, 463 CCSTMTRQ 210, 210, 210, 224, 237, 238
BUYPOWER 475 CCSTMTRS 212, 212
BUYSTOCK 463, 492 CCSTMTTRNRQ 210
BUYTYPE 458, 463, 471, 493, 495 CCSTMTTRNRS 212
CHALLENGERQ 59, 59, 99, 101, 628
CHALLENGERS 59, 59, 99, 101
C CHALLENGETRNRQ 59
CHALLENGETRNRS 59
C 538, 538, 541, 570, 571, 574 CHARTYPE 136
CALLPRICE 447 CHECKING 432
CALLTYPE 447 CHECKNUM 215, 224, 246, 247, 293, 329,
CANADDPAYEE 407 333, 361, 369, 417
CANBILLPAY 324 CHECKSUP 81, 588
CANCELWND 324 CHGPINFIRST 137
CANEMAIL 323, 326, 435, 557 CHGUSERINFO 170
CANLOAN 322 CHGUSERINFORQ 165, 165, 516, 517, 627
CANMODMDLS 322, 407 CHGUSERINFORS 166
654
DFLTIMAGETTL 584 DTPOSTED 215, 218, 224, 251, 260, 271, 329,
DIFFFIRSTPMT 407 493
DIFFLASTPMT 407 DTPOSTEND 232, 233, 237, 238, 242
DISCOUNT 356, 356 DTPOSTSTART 232, 233, 237, 242
DOMXFERFEE 324, 325, 326 DTPRICEASOF 473, 494
DSCAMT 356, 356 DTPROFUP 53, 132, 133, 328, 559, 563, 566
DSCDATE 356, 356 DTPURCHASE 458, 467
DSCDESC 356, 356 DTSEEN 543, 543
DSCRATE 356, 356 DTSERVER 53, 328, 559, 563, 566
DTACCTUP 53, 145, 147, 147, 153, 154, 328, DTSETTLE 457, 492
518, 519, 520, 559, 563, 566, 576, 577, DTSTART 87, 87, 203, 206, 208, 210, 212, 221,
580 222, 227, 231, 232, 235, 237, 239, 327,
DTASOF 77, 201, 202, 208, 209, 212, 222, 243, 328, 452, 453, 454, 485, 491, 492, 497,
329, 446, 452, 453, 454, 492, 494, 498 522, 523, 526, 569, 570, 572, 573, 575,
DTAUCTION 471 599
DTAVAIL 215 DTTRADE 457, 492
DTBILL 528, 528, 570, 571, 573 DTTRAN 218, 218, 219
DTCALL 447 DTUPDATE 505, 506, 507, 559, 563
DTCHANGED 58 DTUSER 215, 218, 224, 246, 247, 293, 294,
DTCLIENT 22, 51, 327, 558, 562, 565 329, 493
DTCLOSE 232, 237, 241, 528 DTUSERUP 53
DTCOUPON 447 DTXFERPRC 197, 197, 198, 201, 202, 342, 343
DTCREATED 162, 167, 168, 169 DTXFERPRJ 251, 251, 251, 260, 271, 331, 344
DTDUE 177, 178, 195, 195, 268, 271, 335, DTYIELDASOF 448, 450
336, 353, 375, 406, 408, 409, 410, 411, DURATION 470, 495
412, 413, 414, 415, 418, 419, 420, 421,
426
DTDUEBY 523, 523 E
DTEFF 530, 531
DTEND 87, 87, 203, 206, 207, 208, 210, 212, EARNINGS 482, 484
222, 227, 231, 232, 235, 237, 239, 327, EMAIL 134, 142, 144, 149, 165, 166, 565
329, 452, 453, 454, 485, 492, 522, 523, EMAILMSGSET 173, 174
526, 570, 572, 573, 599 EMAILMSGSETV1 42, 174
DTEXPIRE 143, 144, 218, 218, 219, 449, 496, EMAILPROF 321, 323, 323, 557
533, 566, 570, 571, 573 EMPLOYERCONTACTINFO 478
DTIMAGEAVAIL 81 EMPLOYERNAME 478, 500
DTINFOCHG 166 ENROLLRQ 49, 141, 142, 144, 159, 165, 513,
DTLOANMATURITY 199, 234 516, 565
DTLOANSTART 199, 234 ENROLLRS 142, 143, 144, 513, 566
DTMAT 447 ENROLLTRNRQ 142, 144, 565
DTNEXT 232, 237, 241 ENROLLTRNRS 143, 144, 566
DTOPEN 232, 237, 241, 528 ESCROWBAL 234
DTPAYROLL 461, 499 ESCRWAMT 202, 203, 203, 215
DTPLACED 470, 495 ESCRWBAL 243
DTPMTDUE 91, 202, 233, 237, 528, 570, 571, ESCRWFEES 203
573 ESCRWFEESBAL 243
DTPMTPRC 358, 364, 410, 412, 413, 415, 417, ESCRWINS 203
426 ESCRWINSBAL 243
656
INCIMAGES 162, 163, 163, 166, 168, 169, INTRATEPURCH 213, 237
309, 311, 384, 489, 506, 550, 558, 563 INTRATEXFER 213, 237
INCLUDE 22, 206, 207, 210, 221, 327, 453, INTRATRNRQ 41, 250, 253, 256, 299, 330
491, 497 INTRATRNRS 251, 254, 256, 300, 330, 341,
INCLUDEBILLPMTSTATUS 524, 524, 525 342
INCLUDEBILLSTATUS 524, 524, 525 INTYTD 233, 237
INCLUDECOUNTS 525, 526 INV401K 455, 478, 500
INCLUDEDETAIL 524, 525, 569, 572, 575 INV401KBAL 455, 477, 500
INCLUDEPENDING 206, 207, 211 INV401KDNLD 435
INCLUDESTATUSHIST 524, 525 INV401KSOURCE 458, 461, 462, 464, 465,
INCLUDESUMMARY 525, 525 466, 467, 470, 473, 499
INCOME 464 INV401KSUMMARY 481, 501
INCOMETYPE 458, 464, 465 INVACCTFROM 142, 159, 160, 431, 431, 431,
INCOO 453, 491 432, 453, 454, 467, 485, 487, 488, 489,
INCPOS 452, 453, 491, 497, 600 490, 491, 492, 497, 498
INCSTMTIMG 231, 235, 239, 485, 590 INVACCTINFO 431, 432, 432
INCTRAN 22, 206, 206, 210, 221, 222, 224, INVACCTTO 159, 431
327, 453, 491, 497 INVACCTTYPE 432
INCTRANIMG 207, 211, 221, 453, 586 INVALIDACCTTYPE 321
INITIALAMT 372, 373, 376, 377 INVBAL 455, 475, 475, 494
INITIALLOANBAL 481 INVBANKTRAN 214, 455, 456, 456, 493
INSURANCE 203, 215 INVBUY 460, 463, 492
INTAMT 203, 215, 233 INVCLOSING 485, 486
INTERCANRQ 265, 265 INVDATE 356, 356
INTERCANRS 265, 265 INVDESC 356, 356
INTERMODRQ 262, 262 INVEXPENSE 464
INTERMODRS 263, 263 INVMAILRQ 487, 487, 550
INTERRQ 259, 259, 282, 284 INVMAILRS 488, 488, 551
INTERRS 260, 260, 282, 285 INVMAILSYNCRQ 114, 487, 489, 489
INTERSYNCRQ 114, 301, 301, 307 INVMAILSYNCRS 114, 487, 490, 490
INTERSYNCRS 114, 302, 302 INVMAILTRNRQ 489
INTERTRNRQ 259, 262, 265, 301 INVMAILTRNRS 490
INTERTRNRS 260, 263, 265, 302 INVNO 356, 356
INTERXFERMSGSET 324 INVOICE 355, 356, 356, 528
INTERXFERMSGSETV1 42, 324 INVOOLIST 455, 495
INTERXFERMSGSRQV1 317 INVPAIDAMT 356, 356
INTERXFERMSGSRSV1 318 INVPOS 473, 473, 474, 493, 494
INTLXFERFEE 324, 325, 326 INVPOSLIST 431, 455, 493
INTRACANRQ 256, 256 INVSELL 460, 466
INTRACANRS 256, 256 INVSTMTENDRQ 485
INTRAMODRQ 253, 253 INVSTMTENDRS 485
INTRAMODRS 254, 254, 341, 343 INVSTMTMSGSET 435, 435
INTRARQ 250, 250, 275, 277, 330, 334 INVSTMTMSGSETV1 42, 434
INTRARS 250, 251, 275, 278, 331, 335, 343 INVSTMTMSGSRQV1 436, 491, 497
INTRASYNCRQ 114, 299, 299, 305 INVSTMTMSGSRSV1 437, 492, 498
INTRASYNCRS 114, 300, 300, 302 INVSTMTRQ 452, 452, 452, 491, 497
INTRATE 209, 233 INVSTMTRS 454, 454, 454, 492, 498
INTRATECASH 213, 237 INVSTMTTRNRQ 452, 452, 491, 497
658
MAILRQ 164, 164, 167, 174 MKTVAL 473, 494
MAILRS 164, 164, 166, 168, 169 MODELWND 322, 370, 406
MAILSUP 174 MODPENDING 277, 278, 284, 285, 375, 376,
MAILSYNCRQ 114, 164, 166, 166, 168, 174 377, 420, 421
MAILSYNCRS 114, 164, 166, 167, 168 MSGBODY 162, 167, 168, 169
MAILTRNRQ 164, 166, 167 MSGSETCORE 43, 64, 97, 98, 130, 134, 135,
MAILTRNRS 164, 167, 168, 169 135, 136, 138, 170, 174, 321, 323, 324,
MARGINBALANCE 475, 494 325, 326, 406, 435, 438, 556
MARGININTEREST 465 MSGSETLIST 64, 133, 138, 170, 173
MARKDOWN 458, 462
MARKUP 459, 461
MATCH 477, 483, 484, 502 N
MATCHCONTRIBAMT 480
MATCHCONTRIBPCT 480 N 538, 538
MATCHINFO 479, 500 NAME 74, 77, 80, 146, 148, 213, 216, 218,
MATCHPCT 479, 500 224, 238, 246, 247, 269, 344, 354, 358,
MATURITYAMT 192 364, 375, 408, 409, 410, 411, 423, 424,
MATURITYDATE 192 426, 493, 494, 506, 507, 515, 559, 560,
MAX 49, 136 561, 563
MAXMATCHAMT 479 NAMEACCTHELD 516, 567, 568
MAXMATCHPCT 479 NEWUNITS 459, 467
MEMO 86, 86, 177, 178, 216, 218, 225, 269, NEWUSERPASS 57, 65, 101, 103
353, 408, 409, 410, 411, 412, 413, 414, NINSTS 176, 177, 178, 375, 418, 419, 420, 421
415, 418, 419, 420, 421, 426, 446, 457, NONCE 59, 59
470, 473, 493, 494 NOTIFYDESIRED 528, 542, 570, 571, 573
MEMO2 86 NOTIFYWILLING 524, 542, 569, 572, 575
MESSAGE 37, 38, 79, 80, 143, 170, 164 NUMERATOR 467
MFA_XXX 599
MFACHALLENGE 61
MFACHALLENGEANSWER 52, 64, 71 O
MFACHALLENGEFIRST 137
MFACHALLENGERQ 61, 61 OFX 21, 22, 36, 37, 38, 38, 40, 129, 167, 171,
MFACHALLENGERS 61 327, 328, 329, 330, 331, 332, 334, 335,
MFACHALLENGESUPT 137 339, 340, 408, 409, 410, 411, 412, 413,
MFAPHRASEA 64 414, 415, 416, 417, 418, 419, 420, 422,
MFAPHRASEID 61, 62, 64 423, 424, 425, 491, 492, 497, 498, 514,
MFAPHRASELABEL 61 558, 559, 562, 563, 565, 566, 567, 568,
MFASSETCLASS 448 569, 572, 573, 575, 576
MFINFO 445, 448, 448 OFXELEMENT 74, 75
MFTYPE 448 OFXEXTENSION 45, 74, 75, 135, 162, 168,
MIDDLENAME 142, 144, 149, 165, 166, 565 166, 167, 297, 298, 299, 300, 301, 302,
MIN 30, 136 303, 305, 306, 307, 308, 309, 310, 311,
MINAMTDUE 528 312, 384, 385, 395, 396, 398, 399, 400,
MINBALREQ 192 401, 442, 444, 452, 454, 489, 490, 520,
MINPMTDUE 233, 237 521, 535, 550, 551
MINUNITS 470 OFXSEC 98, 98, 135
MKTGINFO 209, 213, 222, 227, 233, 238, 242, OLDUNITS 459, 467
455 OO 470, 470, 471, 495
660
PMTINFO 177, 178, 352, 352, 360, 361, 363, POSTYPE 459, 467, 473, 493, 494
364, 365, 372, 373, 375, 376, 377, 381, PREFETCHURL 533, 533
382, 408, 409, 410, 411, 412, 413, 414, PRESACCTFROM 507, 514, 514, 514, 515,
415, 418, 419, 420, 421, 426, 546 516, 528, 534, 537, 543, 548, 550, 551,
PMTINQRQ 39, 349, 350, 369, 369, 416 570, 571, 573, 577
PMTINQRS 369, 369, 417 PRESACCTINFO 513, 514, 514, 515, 519, 520,
PMTINQTRNRQ 39, 369, 416 546, 577
PMTINQTRNRS 369, 417 PRESACCTTO 507, 514, 514, 516, 517, 567,
PMTINSTRUMENTTYPE 512, 512, 512, 560, 568
561, 562, 564 PRESBILLINFO 515, 525, 527, 527, 527, 528,
PMTMAILRQ 381, 381 534, 536, 537, 542, 546, 570, 571, 573
PMTMAILRS 382, 382 PRESCOUNTS 525, 526
PMTMAILSYNCRQ 114, 381, 384, 384, 548 PRESDELIVERYID 543, 543, 543, 544
PMTMAILSYNCRS 114, 385, 385 PRESDETAIL 537
PMTMAILTRNRQ 381, 384 PRESDETAILRQ 522, 527, 536, 536, 536, 537
PMTMAILTRNRS 382, 385 PRESDETAILRS 537, 537
PMTMODRQ 39, 343, 346, 347, 349, 359, 364, PRESDETAILTRNRQ 536
364, 365, 412, 414 PRESDETAILTRNRS 537, 540
PMTMODRS 349, 350, 364, 365, 365, 367, PRESDIRMSGSET 552, 553, 556
375, 397, 413, 415 PRESDIRMSGSETV1 42, 504, 552, 553, 556
PMTNUMBER 229 PRESDIRMSGSRQV1 504, 552, 558, 563
PMTPRCCODE 358, 360, 364, 410, 412, 413, PRESDIRMSGSRSV1 504, 553, 559, 563
415, 417, 426 PRESDIRPROF 556
PMTPRCSTS 358, 358, 360, 361, 365, 367, PRESDLVMSGSET 552, 556
369, 410, 411, 413, 415, 417, 426 PRESDLVMSGSETV1 42, 504, 522, 556
PMTRQ 39, 127, 346, 347, 349, 350, 360, 360, PRESDLVMSGSRQV1 522, 554, 569, 572, 575,
363, 367, 387, 388, 391, 408, 410 576
PMTRS 126, 127, 349, 350, 352, 360, 360, 360, PRESDLVMSGSRSV1 522, 555, 569, 573, 576,
361, 363, 364, 397, 409, 411, 425, 426 625
PMTSYNCRQ 113, 114, 126, 127, 182, 350, PRESDLVPROF 556
398, 398, 402, 425 PRESGRPACCTINFOTRNRQ 518, 519, 519,
PMTSYNCRS 114, 126, 127, 182, 349, 350, 520, 576
367, 399, 399, 402, 425 PRESGRPACCTINFOTRNRS 519, 520, 520,
PMTTRNRQ 39, 127, 360, 365, 367, 398, 408, 521, 576
410, 412, 414, 415 PRESLIST 526, 527, 527, 570, 573
PMTTRNRS 126, 127, 182, 360, 365, 368, 399, PRESLISTRQ 522, 522, 523, 526, 527, 533,
409, 411, 413, 414, 416, 426 534, 535, 542, 546, 569, 572, 575
PORTION 448 PRESLISTRS 522, 526, 526, 534, 535, 570, 573
POSDEBT 474 PRESLISTTRNRQ 522, 523, 526, 534, 534,
POSDNLD 435 535, 569, 572, 575
POSMF 474 PRESLISTTRNRS 526, 534, 535, 535, 536,
POSOPT 474, 494 569, 573
POSOTHER 431, 474 PRESMAILRQ 548, 548
POSSTOCK 474, 493 PRESMAILRS 548, 548
POSTALCODE 133, 142, 144, 149, 165, 166, PRESMAILSYNCRQ 114, 547, 550, 550
269, 354, 408, 409, 423, 424, 506, 508, PRESMAILSYNCRS 114, 547, 551, 551
516, 559, 560, 561, 564, 565, 567, 568 PRESMAILTRNRQ 548, 550
POSTPROCWND 406 PRESMAILTRNRS 548, 549, 551
662
RESTRICT 508, 561 SEVERITY 37, 38, 43, 65, 79, 79, 82, 144, 153,
RESTRICTION 470, 495 154, 164, 182, 168, 169, 172, 328, 331,
RETOFCAP 466 332, 335, 340, 341, 343, 409, 411, 413,
REVERSALFITID 85, 457, 457 414, 416, 417, 418, 420, 422, 424, 426,
REWARDBAL 213, 238 492, 498, 559, 563, 566, 568, 569, 573,
REWARDEARNED 213, 238 576
REWARDINFO 213, 238 SHORTBALANCE 475, 494
ROLLOVER 477, 483, 484, 500 SHPERCTRCT 449, 459, 463, 466, 496
ROLLOVERCONTRIBAMT 480 SIC 216, 506, 508, 559, 560, 561, 564
ROLLOVERCONTRIBPCT 480, 501 SIGNONINFO 49, 133, 136, 137
SIGNONINFOLIST 133
SIGNONMSGSET 64, 64, 131
S SIGNONMSGSETV1 42, 64, 130
SIGNONMSGSRQV1 22, 40, 327, 329, 331,
SECID 441, 441, 442, 442, 445, 446, 449, 461, 334, 336, 337, 339, 340, 408, 410, 412,
462, 463, 464, 465, 466, 467, 470, 471, 414, 415, 416, 417, 419, 422, 423, 425,
473, 493, 494, 495, 496 491, 497, 558, 562, 565, 567, 569, 572,
SECINFO 446, 446, 447, 448, 449, 450, 495, 575, 576
496 SIGNONMSGSRSV1 328, 330, 332, 335, 339,
SECLIST 440, 444, 444, 445, 495 341, 409, 411, 413, 414, 416, 417, 418,
SECLISTMSGSET 438, 438 420, 422, 424, 425, 492, 498, 559, 563,
SECLISTMSGSETV1 42, 438 566, 568, 569, 573, 576
SECLISTMSGSRQV1 40, 439, 440, 445 SIGNONREALM 135, 136
SECLISTMSGSRSV1 40, 440, 445, 495 SIGNUPMSGSET 170
SECLISTRQ 442, 442, 442, 444 SIGNUPMSGSETV1 42, 170
SECLISTRQDNLD 438 SIGNUPMSGSRQV1 40, 139, 565, 567
SECLISTRS 444, 444, 444 SIGNUPMSGSRSV1 40, 566, 568
SECLISTTRNRQ 442, 442, 445 SONRQ 22, 40, 46, 46, 47, 49, 51, 51, 53, 57,
SECLISTTRNRS 444, 444 97, 101, 103, 123, 126, 131, 141, 167,
SECNAME 446, 495, 496 327, 330, 331, 334, 336, 337, 339, 340,
SECONDARYHOLDER 148 408, 410, 412, 414, 415, 416, 417, 419,
SECRQ 442 422, 423, 424, 425, 491, 492, 497, 498,
SECURED 459, 466, 474 504, 514, 520, 534, 535, 558, 562, 565,
SECURITYNAME 142, 144, 565 567, 569, 572, 575, 576, 628
SELLALL 471 SONRS 46, 46, 47, 48, 52, 53, 53, 124, 328,
SELLDEBT 466 330, 332, 335, 339, 341, 409, 411, 413,
SELLMF 466 414, 416, 417, 418, 420, 424, 425, 492,
SELLOPT 466 498, 559, 563, 566, 567, 568, 569, 572,
SELLOTHER 431, 466 573, 575, 576
SELLREASON 459, 466 SPACES 137
SELLSTOCK 466 SPECIAL 137
SELLTYPE 459, 466, 471 SPLIT 467
SESSCOOKIE 47, 52, 53 SPNAME 53, 135, 348, 514, 515
664
TOKEN 80, 86, 86, 110, 111, 112, 113, 116, UNITPRICE 431, 446, 460, 461, 462, 465, 467,
117, 118, 124, 126, 127, 161, 162, 166, 473, 493, 494
168, 182, 165, 166, 167, 168, 168, 168, UNITS 431, 460, 461, 462, 463, 465, 467, 470,
169, 248, 252, 255, 257, 261, 264, 266, 473, 493, 494, 495
272, 273, 276, 279, 281, 283, 286, 288, UNITSSTREET 474, 474
291, 292, 296, 297, 298, 299, 300, 301, UNITSUSER 474, 474
302, 303, 305, 306, 307, 308, 309, 310, UNITTYPE 460, 471
311, 312, 339, 362, 366, 368, 370, 374, URL 72, 130, 134, 135, 136, 170, 170, 171, 172
378, 380, 383, 384, 385, 389, 392, 394, USEHTML 162, 163, 163, 164, 166, 168, 169,
395, 396, 398, 399, 400, 401, 403, 425, 309, 311, 384, 489, 550
488, 489, 490, 625, 626 USERCRED1 50, 52
TOKEN2 86, 162, 550, 551 USERCRED1LABEL 137
TOKENONLY 117, 117, 162, 168, 166, 297, USERCRED2 50, 52
299, 301, 303, 305, 307, 309, 311, 384, USERCRED2LABEL 137
395, 398, 400, 489, 550, 625 USERID 22, 49, 51, 51, 57, 58, 59, 61, 62, 64,
TOTAL 459, 461, 462, 463, 464, 465, 466, 493 65, 131, 140, 142, 143, 144, 162, 167,
TOTALFEES 232 168, 169, 327, 348, 514, 515, 519, 520,
TOTALINT 233 526, 534, 535, 558, 558, 562, 562, 565,
TRANDNLD 326, 435 566, 567, 568, 570, 572, 573, 575, 577,
TRANIMGAVAIL 82, 596 583, 599, 629
TRANSFER 467 USERINFOAVAIL 170
TRANSPSEC 97, 97, 135, 135 USERINFORQ 169
TRNAMT 86, 86, 177, 178, 195, 215, 218, 224, USERINFORS 169
246, 247, 268, 271, 293, 294, 329, 330, USERKEY 47, 48, 51, 52, 53
331, 334, 336, 342, 343, 344, 352, 375, USERPASS 22, 49, 51, 51, 101, 103, 131, 140,
408, 409, 410, 411, 412, 413, 414, 415, 327, 558, 558, 562, 562, 565, 583, 599,
418, 419, 420, 421, 426, 493 628
TRNTYPE 215, 217, 218, 219, 329, 493 USPRODUCTTYPE 107, 432, 433, 433
TRNUID 22, 43, 45, 65, 75, 83, 83, 112, 116,
118, 120, 122, 126, 127, 144, 153, 154,
164, 161, 164, 167, 168, 169, 171, 218, V
219, 327, 328, 330, 332, 334, 335, 339,
340, 341, 342, 347, 402, 403, 408, 409, VALIDATE 507, 508, 510, 562
410, 411, 412, 413, 414, 415, 416, 417, VALUE 77, 494
418, 420, 422, 423, 424, 425, 426, 442, VER 135, 135, 136
444, 452, 454, 491, 492, 497, 498, 520, VESTDATE 480
521, 535, 558, 559, 563, 565, 566, 567, VESTINFO 480
568, 569, 572, 573, 575, 576, 624 VESTPCT 480
TSKEYEXPIRE 53
TSPHONE 134
TYPEDESC 449 W
WEBENROLL 170, 170
U WIREBENEFICIARY 268, 269, 269, 271
WIRECANRQ 272, 272
UNIQUEID 441, 493, 494, 495, 496 WIRECANRS 273, 273
UNIQUEIDTYPE 441, 493, 494, 495, 496 WIREDESTBANK 268, 268, 271
WIRERQ 268, 268
X
XFERDAYSWITH 406
XFERDEST 153, 154, 192, 194, 199, 200, 234
XFERDFLTDAYSTOPAY 406
XFERINFO 194, 194, 195, 250, 251, 253, 254,
258, 259, 260, 262, 263, 330, 331, 334,
335, 341, 343
XFERPRCCODE 197, 197, 198, 198, 201, 202,
251, 260, 342, 343
XFERPRCSTS 197, 197, 198, 201, 202, 251,
254, 260, 263, 342, 343
XFERPROF 321, 322, 322, 324, 584
XFERSRC 153, 154, 192, 194, 199, 234
Y
YEARTODATE 481, 501
YIELD 448, 450, 495, 496
YIELDTOCALL 447
YIELDTOMAT 447
666
OFX 2.3 Specification 10/16/2020 667