BIAN – PNC Open APIs

for Banking
Capstone Project at Carnegie Mellon University
Mark Grobaker, Arashdeep Kaur, Chaitanya Kommuru
Wenting Tao, Pallavi Thakur

10th May 2017

Contents
Executive Summary 03

Acknowledgements03

Project Objectives 05

Objective 1: Comply with PSD2 05

Objective 2: Demonstrate a solution built on BIAN, IFX, and PNC 05

Project Methodology 07

PSD2 Use Cases 07

BIAN’s Contribution 09

IFX Messages for PSD2 11

Comparing IFX and ISO 15

Interacting with PNC 16

Solution architecture  17

Implementation19

Introduction and file description 19

Choice of HTTP method for RESTful API 20

Code Walkthrough 21

Using our APIs 25

Conclusions and Recommendations 27

Lessons Learned 29

Suggestions for Future Work –

Standards and Frameworks 29

Suggestions for Future Work –

Development Work 31

Appendix32

2
Executive This was a joint project between
masters-level graduate students
Summary at Carnegie Mellon University’s
Heinz College, and stakeholders at
PNC Bank, BIAN (Banking Industry
Architecture Network), and IFX
(International Financial eXchange).

We demonstrate a working proof of concept for

open APIs in banking, in compliance with the
European Commission’s PSD2 financial
regulation document.

Other groups can build on these efforts to

ensure PSD2 compliance at their respective
financial institutions.

Acknowledgements

We would like to thank all those who contributed

to the success of this project. CMU Professor Mike
McCarthy was our adviser, and guided us in our
approach to the problem. Our client teams also
provided valuable information and feedback as
we progressed through the project. Our thanks
go to: Hans Tesselaar and Guy Rackham of BIAN;
Rich Urban of IFX; Chad Ballard, Mike Downs,
Laura Ritz, and Elesha Schulze of PNC; and
Ganeshji Marwaha, Chamindra De Silva, Pubudu
Welagedara, and Chinthaka Dharmasiri of Virtusa
Polaris, consultants to PNC.

03
04
Project Objective 1: Comply with PSD2

Objectives The first goal of the project was to create a

working proof of concept for open APIs for
banking, in compliance with PSD2. PSD2 is a
financial regulation document that applies to banks
and financial institutions in the European Union.
This regulation was published on January 13,
2016, and will go into effect for banks on
January 13, 2018.

The reason PSD2 seeks to have banks create

these APIs is so that third parties can use them
to interact easily with the bank. There are two
primary use cases required by PSD2. Banks
should enable third parties to: (1) submit peer-to-
peer payments to the bank, and (2) check account
balances. Both of these capabilities are to be
enabled via openly accessible APIs.

Per PSD2 requirements, no fees should be

charged to third parties for these services. Further
details on PSD2 can be found in a whitepaper
published by Deutsche Bank 1.

Objective 2: Demonstrate a
solution built on BIAN, IFX,
and PNC

The second goal of the project was to use

principles from BIAN and IFX to build a solution.
This solution was built to interact with PNC, but
could be adapted to any bank.

BIAN provides architectural principles designed

to guide technology implementations at financial
institutions. IFX provides a messaging standard,
again, designed specifically for financial
institutions. BIAN and IFX were interested
in producing a prototype to show how their
standards, designed specifically for financial
applications, could be combined to produce a
functioning product.

1. http://cib.db.com/insights-and-initiatives/flow/Payment_
Services_Directive_2.html

05
PNC is a top ten US bank and a partner with BIAN in several other initiatives. Because
of their interest in furthering the work of BIAN, they offered to make a test environment
accessible to the CMU development team.

We were to use BIAN frameworks at a high level to guide the implementation of a message
exchange. The messages themselves would be structured according to IFX format. We
chose the scenarios we wanted to model based on the requirements of PSD2, which will
be discussed further below.

Figure 1. Left: Sample parties interacting with open APIs. Right: standards used to structure the messages to be
returned from the bank, in this case, PNC Bank.

06
Project We begin by examining the use
cases of PSD2. Per PSD2, banks
Methodology should enable third parties to: (1)
submit peer-to-peer payments to

PSD2 Use Cases the bank, and (2) check account

balances. We produced the below
diagrams to model these use cases.

In figure 2, we model a peer-to-peer payment.

In this case, Ben Roethlisberger wants to make
a payment to Amazon. (Since we were working
from Pittsburgh, we made examples involving star
players from the Pittsburgh Steelers!) Ben has an
account at PNC, and Amazon has an account at
Chase. In order to initiate the payment, Ben fills out
a form on his third party provider (TPP) to request
a payment to be sent. In this case, we have
displayed Venmo as an example TPP. Venmo then
sends a message to PNC requesting the transfer.
PNC transfers the money to Chase, and the funds
are now available for Amazon to access.

Payment could just as easily have been from Ben

to another consumer, rather than from Ben to a
business. Either one would qualify for this PSD2
use case of sending a payment.

(As a side note, services like Venmo do not

currently exist in Europe for payments between
EU countries. Even in the US, Venmo works by
using the ACH system, which takes up to 3-5 days
for processing. Using open APIs would enable
instantaneous transfers.)

The area in the red dotted box is the one we

will be focusing on for our prototype; that is, we
developed the messaging between the TPP
and the bank.

07
 Contractual
relationship

Mandated

Financial
Reporting

Mandated
by Payee

Figure 2. Peer-to-peer payment, the first use case specified in PSD2. Ben Roethlisberger sends
payment to Amazon.

Figure 3. Check account balances, second use case specified in PSD2. Antonio Brown gets his
balances from PNC and Bank of America.

The above figure shows a model of checking account balances across multiple banks.
In this case, Antonio Brown requests his TPP, Mint, to monitor balances from his two
accounts, PNC and Bank of America. Mint would automatically generate balance requests
to PNC and Bank of America on a regular basis (daily or more frequently, depending on
the TPP configuration).The banks would then respond to this message by providing their
respective balances to Mint. (Services such as Mint do not currently exist in Europe.)

Again, we wanted to build just the part boxed in red: the communication between the TPP
and the banks.

08
 BIAN’s Contribution

We had a number of calls with Guy Rackham, BIAN Lead

Architect. He explained to us the work that his organization has
done. In particular, he referred us to the BIAN Semantic API
How-To Guide, an architectural document he helped produce.

One of the main components of this document is the Semantic

API Selection Framework, which is shown below. The
framework helps the developer or architect to “ask all right
questions” that need to be asked before developing a solution.
(Full explanations of how to use this framework are available in
the BIAN Semantic API How-To Guide and are not replicated
here.) This framework would prove helpful in structuring our
solution to the needs of PSD2.

Figure 4. BIAN’s Semantic API Selection Framework

After this introduction, Guy provided us with PSD2-specific

guidance, by giving us an overview of the different steps he saw
as necessary to carry out the use cases of PSD2: send payment
and check balance. We took those steps and reformulated them
into the diagram shown below in figure 6.

This sort of guidance showed the kind of value-add that BIAN

can bring. IFX and other messaging standards bodies are more
concerned with the messages themselves, not the business use
cases. A group like BIAN was helping in explaining what all the
different steps needed to be for the use cases. Then we were
able to implement some of these steps using IFX in our solution.

As shown in the steps in the figure below, in the send payment

case, the consumer (PSU, the payment service user) first
registers the TPP (third party provider). Then he requests the
TPP to send a payment. The TPP authenticates itself with the
bank, and finally instructs the bank to make the payment.

09
 PSD2 – Peer to Peer Payment

Registration

Request

Authentication

Execution

Payment initiation Service Provider Account Information Service Provider

Figure 5. PSD2 use cases: peer to peer payment (left), and check balances (right)

In the check balances case, once again the PSU first registers
with the TPP, and then asks the TPP to check balances. After
an authentication step, the TPP retrieves the balances
from the bank

Of these steps, we needed to determine which would be in or

out of scope for our project. The registration would be out of
scope, as that pertains to user registration for the TPP only (your
login credentials for Venmo, Mint, etc). However, the request,
authentication, and execution would all relate to our project and
were potentially in scope. Our work on these steps is discussed
further below.

Furthermore, we mapped all these steps from PSD2 using the

BIAN Semantic API How-To Guide. The results of this exercise
can be found in the appendix of this report.

At this point, we now needed to learn more about the kind of

messages would send, especially in the execution step. We
turned to our partners at IFX to learn more about the messaging
format they could offer...

10
 IFX Messages for PSD2

Rich Urban, president of IFX, provided an

introduction to IFX over a number of phone
calls with the CMU team. In particular, he
indicated the right IFX message formats that
would apply to each of the use cases we had
in mind. For sending a payment, he indicated
that we should use the IFX message called
PmtSendRq, which would be acknowledged
by the PmtSendRs message. For checking
balance, we were to use the BalInqRq, which
was acknowledged by BalInqRs.

All IFX documentation was available online at www.ifxforum.

org. The most important part of the site is BMS, which is short
for “business messaging specification”. The BMS section of
the site can be searched for thousands of available message
specifications. In our case, there were only four messages that
we needed to use, as listed above.

We were also able to download the JSON for these messages

from a Swagger utility on the website. There were a number of
optional fields contained in each message, and we chose not
to use them in our implementation. To remove these optional
fields, we had to manually go through the JSON and strip them
out. As a small feedback to IFX, we would recommend enabling
JSON exports that have the optional fields already removed.

We used all (or most all) of the required fields for each of these
messages. To review field level detail at which we implemented
the IFX messages, we recommend reviewing our code.
Screenshots of the message format specifications of the four
messages we selected are included in figures 7-10.

11
12
 Figure 6. PmtAddRq screenshot from IFX BMS website.

Figure 7. PmtAddRs screenshot from IFX BMS website.

13
Figure 8. BalInqRq screenshot from IFX BMS website.

Figure 9. BalInqRs screenshot from IFX BMS website.

14
 Comparing IFX and ISO

As part of the project, we compared

and contrasted IFX and ISO. Both
are standards to be used by financial
institutions for sending messages,
most commonly payments
messages.

ISO’s 20022 standard is currently used worldwide

with prominent contributors like SWIFT and VISA.
ISO 20022 includes eight parts: ISO 20022-1
through ISO 20022-8. These parts describe the
metamodel, UML profile, XML schema etc.
for the messages.

IFX promotes messages that are sent in XML

or JSON. There is also built-in capability to
generate a swagger document for these message
structures. IFX can contain ISO elements, if
desired. Based on our experience in this project,
IFX messages are defined and organized in a way
which is easy to read/understand.

Both these standard bodies promote the idea of

“interoperability” across financial institutions. ISO
is currently in broad use, while IFX has support but
is yet to see broad adoption. Both are acceptable
standards for sending financial messages.

Resources for further reading on IFX and ISO can

be found in the appendix.

15
Interacting with PNC

After working with BIAN and IFX

to understand their frameworks,
standards, and message formats,
we began to collaborate more
closely with PNC. In order to test
out the APIs we were developing,
we needed to be able to simulate
sending and receiving messages to/
from other systems in the bank.

PNC had already set up an environment, called the

API store, which had some open APIs. These open
APIs did not generate IFX compliant messages.
Rather, they returned data in a flat format as part
of a RESTful exchange. For example, a request to

http://apimanager.pncapix.com:8280/
SmartBank-API-Services/V2.0/card/
findByCardNumber/{cardNumber}

Will return details about that card number, if it

exists in the data.

We were able to interact with and test out these

APIs by using the freely available tool “Postman.”
Postman enabled us to create HTTP requests to
APIs in the PNC API store. (Note that the API store
is not used in daily business operations yet at the
PNC Bank. Right now it is a sandbox area where
PNC is exploring how it could deploy open API
solutions in production.)

16
 Solution architecture

As shown earlier, in figures 2 and

3, we wanted to focus our work on
the interaction between the TPP
and the bank. If we “zoom in” on
this relationship, there are a few
steps that need to happen in the
communication.

As shown in this figure, first a third party provider

(TPP) would initiate a payment using the RESTful
API that we have built (“API” in the figure). This
could be a form available at an endpoint such as
www.pnc.com/sendpayment. This should only
be available after logging in to your account.

Once the payment is submitted to the API, the

API first looks up additional data from other PNC
systems (steps 2 and 3). Once that data has been
retrieved, it makes a call to the Bank Payment
System to make the payment.

Finally, the bank payment system returns a

response to the API (step 5). The API, in turn, reads
this message, and uses it to generate a JSON IFX
compliant message (step 6). The message will be
the PmtSendRs or the BalInqRs.

In our implementation, note that we ended up not

using PmtSendRq and BalInqRq. The bank might
want to use these messages when communicating
with internal payment systems. However, as we did
not have that system available to us, we did not
need to send messages to it.

17
However, PmtSendRs and BalInqRs messages are used. The
appropriate message is generated and sent back to the TPP.
What we gain by doing this is that now, the TPP can expect a
consistently formatted response message when it interacts with
any bank. Furthermore, the bank can also choose to archive
these response messages, which may be useful for historical or
reporting purposes.

Figure 10. Message Architecture of TPP, API, and Bank Systems

18
Implementation Introduction and file description

All code is available on Git at this link: https://

github.com/chinthakadd/cmu-bian-starter

We developed and deployed the API

on our local machines during the
development phase of the project.
The PNC team’s Virtusa consultants
helped us get set up with the proper
IDE and development environment
to work with the PNC API store.

In this section, we describe the different files in the

Java solution that we developed. All files are listed
in the figure at right, a screenshot from IntelliJ IDE.

Reading from the “controller” folder, we have two

types of controllers – PaymentRequestController,
and Card/Dep/Loan AcctBalanceRequest
Controller. The first controller has the logic for
the send payment operation. The second set of
controllers are very similar to each other, and all
handle for the check balance operation. There
is slightly different logic depending on whether a
card, deposit, or loan is being queried.

You will also notice a number of files listed under

the model section. These are used to structure the
IFX response message. For example, a message
Figure 11. Java files used in our implementation.
might consist of Account, AcctBal, and BankInfo
objects. To create this message, we could create
an object that contains all three of these objects.
These will be described further below.

One advantage of this design is that BankInfo,

for example, can be used consistently in many
different contexts. Several different IFX messages
may contain BankInfo. By having a BankInfo
object, we can enforce that it must contain the
same five fields everywhere it is used. These fields
are shown below. Now, wherever BankInfo is used,
Figure 12. Fields of the BankInfo class.
it must have this consistent definition.

BankInfo and other objects are then converted

into the appropriate JSON structure when they
are used.

19
Choice of HTTP method for RESTful API

For our APIs, we needed to choose the appropriate HTTP method to correspond to the
operation. BIAN’s API How-To Guide was a useful resource for this task. The figure below
shows a mapping between action terms and the corresponding HTTP method. We used
this to perform mappings for the two use cases.

Figure 13. Action term to HTTP verb mapping.

Mapping for PSD2 use cases:

• Send payment: For this, we need to “Create” a message to send a payment, so we use
the HTTPPUT operation.

• Check balance: For this operation, we need to “Request” a balance, so we use the
HTTP GEToperation.

20
 Code Walkthrough

Here, we copy the code and comment on the functionality of a representative

set of the files. First, the PaymentRequestController:

This will take a PUT request,

based on the input in the
RequestBody

Create objects for the

response message

Prepare elements needed to

make call to API Store

Make call and store the

response

21
 Format response into IFX format,
using objects created above

Note that formatting of this

message (eg which objects to
include) is based on IFX message
specification

CardBalanceRequestController:

22
 Responds to a GET request,
and reads in the variables in
the URL path

Create objects for the

response message

Prepare elements needed to

make call to API Store

Make call and store the

response

Format response into IFX

format, using objects created
above.

Note that formatting of this

message (eg which objects
to include) is based on IFX
message specification

23
24
 Using our APIs

In this section we walk through how one can interact with the
APIs. In the screenshots below, we show the APIs running
locally and how to interact with them via the Swagger UI. Our
code automatically generated a Swagger UI, since it was built
with the Spring framework. The user can submit data to each
of these endpoints and examine the response messages.
Of course, a TPP would also be able to send data to these
endpoints without having to use the Swagger UI.

Our API was also deployed to the PNC API store, where the
interface is somewhat different. However, the functionality is the
same. These screenshots can be found in the appendix section.

Figure 14. Swagger UI in our local deployment of the API. As shown, an API to send a payment
is selected. Equivalently, the API can be deployed to the bank’s API store.

25
Figure 15. As shown, we submit data to the API as parameters in the body of the HTTP request.

Figure 16. The API returns data in the IFX-compliant format. (More data could be seen if the
developer were to scroll down.)

26
 In this project, we have shown that
Conclusions and the BIAN and IFX frameworks can
Recommendations be applied successfully to comply
with PSD2 requirements in order
to enable third parties to send
payments and check balances.

As the banking industry will be required to build

new functionality (open APIs) to comply with
PSD2 requirements, now is an ideal time to
coalesce around a standard method for doing so.
Messages with the IFX format are well-suited to
send response messages to the TPP, as well as
messages from one bank to another. When a TPP
submits a send payment request, it could receive
back a standard IFX compliant message from
whichever bank it interacts with. The bank, in turn,
could send an IFX message from the payee bank
to the payer bank to provide details for the
money transfer.

We recommend that industry partners continue

to explore these opportunities by partnering with
BIAN and IFX when developing their solutions.

27
28
 Lessons Learned

This project required us to collect information from different

stakeholders, and determine the type of solution they were
asking for. In a fairly short time, we also had to become
acquainted with much previous work that had been done by
other standards bodies such as BIAN, IFX, and the European
Commission (which produced PSD2).

Suggestions for Future Work –

Standards and Frameworks

1. Standardize which IFX fields the TPP should be

required to submit

In our current solution, for simplicity the TPP is required

to submit many of the fields needed to produce the IFX
response message. In reality, a number of these fields can
and should be retrieved from within the bank’s own systems.
(For example – branch name. The TPP would not know this,
but the bank would. However, not all of this data was easily
available from the API Store made available to us.)

We suggest that industry leaders determine which fields

should be required from the TPP, and which fields can be
supplied by the bank. If feasible, this classification could
even be included with the IFX standard itself.

2. Clarify which parties should create an IFX message

(TPP, bank, or both)

Industry leaders should also clarify which parties need to

create an IFX message. Here is our current understanding,
which should be reviewed.

It is currently not clear if the TPP would be required to

submit an IFX-formatted message, or if just the banks should
communicate using this standard. We believe the TPP could
be asked to format its message in a specific way, but there
may also be concern about putting that burden on the TPPs.

Furthermore, the industry should define whether banks

should use IFX for messages to other systems within the
same bank (eg PNC to PNC) and to other banks
(eg PNC to Chase).

29
3. Consider developing context-specific guidelines for
message formats

Consider that there are three distinct messaging contexts:

TPP-bank, intra-bank, and bank-to-bank. To use real names
as examples: Venmo-PNC, PNC-PNC, and PNC-Chase.
As we worked on this project, it became clear that each
of these contexts would have different expectations in
terms of what information would be sent or received. We
recommend incorporating this distinction into either BIAN or
IFX standards as appropriate. “Message context” seems to
be an important topic that a PSD2 solution much take into
account.

4. Review required/optional fields in IFX

In its documentation, IFX has marked fields in the messages

as either required or optional. Based on the needs
discovered during further implementation work, these
required/optional fields should be updated as appropriate.
For example, if a field currently marked as optional is
discovered through discussion and implementation to be
required, then this should be updated in IFX documentation.

5. Clarify the BIAN How-To Guide sections on

deployment environment and service assurance

When reading the BIAN How-To Guide, we were not able to

understand the framework’s guidance around deployment
environment and service assurance. We talked through it on
the phone and were eventually able to understand. However,
perhaps some additional wording in this section would be
helpful to future users of the guide.

30
 Suggestions for Future Work –
Development Work

1. Develop process to lookup necessary fields within

bank

The banks will need to develop a process to look up the

relevant information from within their systems to populate IFX
fields not provided by the TPP.

We also note that, in this project, we would have used other

APIs to communicate within the bank. However, depending
on the implementation, the bank in question may just be able
to look up necessary information from a database table. In
such a case, interaction with an API may not be required
since the data is internally available.

2. Build solution for messages between banks

In this project, we have not worked on the messaging from

one bank to another. However, if there is to be payment
between users of different banks, such a message would be
required. We recommend formatting this message in an IFX
format. The PmtSendRq messagemay be the appropriate
message to use in this case.

Another possibility would be to send data between banks in

the message body of an HTTP PUT or GET (a RESTful API).
However, since banks will likely be familiar with IFX, and also
since this message body may become rather long (longer
than what we would expect from a TPP), it may be preferable
to send messages between banks in IFX formats.

3. Implement authentication step of PSD2 (OAuth)

We also have not implemented the authentication step required

in PSD2. Through our conversations with PNC, we determined
that an OAuth implementation would eventually be necessary to
implement PSD2. As the work required would be fairly intensive,
it was deemed out of scope for our project.

We did create a prototype of what the OAuth interaction might

look like, and we included this as part of the UI shown in our
demo. However, we opted not to include this in our code
submission as it was just for simple demonstration purposes.

31
Appendix

Mapping of PSD2 steps to BIAN’s Semantic API

Selection Framework

Figure 17. PSD2 use case: send payment.

Figure 18. PSD2 use case: check account balances.

32
 Process mapping for API Generation

Figure 19. Business process for building solutions to the different steps of PSD2

API deployed in PNC API store

Figure 20. Home page for the payment execution API in the PNC open API store

33
Process mapping for API Generation

Figure 21. Interface in PNC API store. By clicking in to one of these endpoints you can then send a request with
the appropriate parameters.

Sources and further reading on IFX and ISO comparison

https://www.gtnews.com/articles/adoption-of-iso-20022-messages-by-ifx-
forum/ ]

https://www.iso20022.org/the_iso20022_standard.page

https://en.wikipedia.org/wiki/ISO_20022

https://en.wikipedia.org/wiki/Interactive_Financial_Exchange

34
https://bian.org