The Story Of An API: How We Turned Frankenstein Into A Handsome Boy
What is needed to build an ecosystem of non-banking services, and indeed any such ecosystem? Master data storage and processing system, as well as API. In this post we will examine two versions of the API created by us - the first and successful one - and we’ll dwell in detail on what their important differences are from each other.
To create an ecosystem of non-banking services, the key product of the Sberbank Digital Corporate Bank Division was chosen - the Internet Bank for corporate clients of Sberbank Business Online. Accordingly, the fintech API for the ecosystem of non-banking services was also based on it.
The first version of fintech API was launched in 2016. It was created with an eye on our other APIs of our bank, according to the classic API recipes of large financial organizations. Here are the basic ingredients:
We made this decision and started pilot integrations with several non-classical banking services: the Evotor online store, the Seeneco Business Analytics financial management system, My Delo cloud accounting and others.
The results of the integration were far from desired. From the API of modern non-financial services, the partners waited for something completely different from what is customary in the field of developing classic banking products. We wanted to get something similar to the API of modern Internet giants: Facebook, Google, Yandex.
But in the end, we faced the classic API of the bank - hard, incomprehensible, requiring high and specific qualifications, understanding the subtleties of workflows, the implementation of redundant security requirements ... in general, many things that lead to the violation of all possible integration deadlines.
We analyzed this experience and decided to make a new version of the fintech API from scratch. To get the maximum win-win with third-party non-financial services, the most important requirements outlined in advance:
With this list we went to the implementation and chose solutions for the second version of the fintech API:
To assess the difference between the two versions of the API, let's compare the implementation of its three key components: authorization, the implementation of a ruble payment order and electronic signature.
In the first version of the API, the authorization of the partner required a login and password, a certificate and AccessToken obtained as a result of the OAUTH authentication of the client who applied:
In API 2.0, authorization has become much more compact. To access the services, you need only the AccessToken obtained during OAUTH client authentication:
In API 1.0, work with a ruble payment order was also based on SOAP:
In API 2.0, in the same way, things have become much simpler and clearer:
Electronic signature, we also facilitated. That's how everything was in API 1.0.
It looked like a request
Here the list of attributes
And ready signature
in API 2.0 version via JSON implemented all the easier:
The query itself
signature as a result of
The fintech API 2.0 pilot launches showed that things went much better. The time of integration with partners' products - from the start of work to the time of release into commercial operation - has decreased by more than 3 times. The number of questions of our support service has decreased by an order of magnitude, and most importantly, the complexity of these questions has decreased. Finally, the number of complaints about the complexity and unpredictability of the API work has decreased by as much as two orders. In general, we did it. If you have any questions - welcome to the comments, we are happy to tell you the details.
Material prepared by Andrei Khokhlov, Project Manager of the Digital Corporate Bank Division of Sberbank
To create an ecosystem of non-banking services, the key product of the Sberbank Digital Corporate Bank Division was chosen - the Internet Bank for corporate clients of Sberbank Business Online. Accordingly, the fintech API for the ecosystem of non-banking services was also based on it.
The first version of fintech API was launched in 2016. It was created with an eye on our other APIs of our bank, according to the classic API recipes of large financial organizations. Here are the basic ingredients:
- SOAP protocol for data transfer
- XML format
- Electronic signature of all requests
- Asynchronous mode
- Required hardware-VPN for secure channel organization
- Proprietary authentication and authorization system
- Historical formats for transferring financial information (for example, 1C direct banking)
We made this decision and started pilot integrations with several non-classical banking services: the Evotor online store, the Seeneco Business Analytics financial management system, My Delo cloud accounting and others.
The results of the integration were far from desired. From the API of modern non-financial services, the partners waited for something completely different from what is customary in the field of developing classic banking products. We wanted to get something similar to the API of modern Internet giants: Facebook, Google, Yandex.
But in the end, we faced the classic API of the bank - hard, incomprehensible, requiring high and specific qualifications, understanding the subtleties of workflows, the implementation of redundant security requirements ... in general, many things that lead to the violation of all possible integration deadlines.
We analyzed this experience and decided to make a new version of the fintech API from scratch. To get the maximum win-win with third-party non-financial services, the most important requirements outlined in advance:
- No universal and heavy formats that take into account the slightest nuances. Let's be easier!
- The API should be suitable for the widest possible range of potential partners offering non-financial products to Sberbank customers. Up to the introduction into smart refrigerators - what the hell is not joking.
- The API must be designed using practices and methods that are used when creating visual interfaces. To do this, you need to identify and analyze the UX-schemes of using the API. Follow the classic canons is definitely not worth it.
- We need to get rid of multi-volume descriptions so that developers can achieve quick results. With the help of a sandbox for testing, you need to get the first positive results in an hour.
- We abandon proprietary solutions tied to a specific platform as much as possible. Everything should be cross-platform and not limit the partner in the used infrastructure and development environment.
- Partners should not be hindered by what they don’t do - complex data structures, mechanisms of components of the banking platform, features of our legacy systems. We hide and do not hammer their heads.
With this list we went to the implementation and chose solutions for the second version of the fintech API:
- Authentication based on OAUTH 2.0 protocol
- REST-architecture over HTTP without additional difficulties
- Fully synchronized work
- JSON format
- Optional use of electronic signature where necessary
- Test sandbox with SWAGGER deployed. Using this debugging environment, a partner developer can simulate a business process and get results without writing code.
- Application of Easy Steps Approach Used by Internet Startups to Create API Documentation
- Agile practices for API development - quick results and feedback gathering
What has changed in fact
To assess the difference between the two versions of the API, let's compare the implementation of its three key components: authorization, the implementation of a ruble payment order and electronic signature.
In the first version of the API, the authorization of the partner required a login and password, a certificate and AccessToken obtained as a result of the OAUTH authentication of the client who applied:
<soapenv:Envelopexmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:upg="http://upg.sbns.zzzzz.com/">
<soapenv:Header/>
<soapenv:Body>
<upg:preLogin>
<!--Optional:-->
<upg:userLogin>U1</upg:userLogin>
<!--Optional:-->
<upg:changePassword>!d63NvJ+Sa</upg:changePassword>
</upg:preLogin>
</soapenv:Body></soapenv:Envelope>In API 2.0, authorization has become much more compact. To access the services, you need only the AccessToken obtained during OAUTH client authentication:
{
"access_token": "fdba5482-460c-4535-b829-9fd836fd01f0-1",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "7f545a14-ab7b-45ff-823a-0421e9f3b42e-1",
}In API 1.0, work with a ruble payment order was also based on SOAP:
<soapenv:Envelopexmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:upg="http://upg.sbns.zzzzz.com/">
<soapenv:Header/>
<soapenv:Body>
<upg:sendRequestsSRP>
<!--Zero or more repetitions:-->
<upg:requests><![CDATA[
<Request xmlns='http://zzzzz.com/upg/request'
orgId='84b70f22-703f-bf04-db60-bd110572f40d'
requestId='a81ddc6d-fb92-416d-83f9-6785a59a4b17'
version='1.0'
sender='PARTNER'
clientOrgIdHash='ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5'
clientAccessToken='ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5-1'>
<PayDocRuInvoice docExtId='a81decfd-fb92-416d-83f9-6785a59abb65'
orderNum='62' deadLine='2017-04-10T17:16:03'>
<PersonalAcc>40802810000000000000</PersonalAcc>
<AccDoc docDate='2017-02-15' docSum='777' transKind='01' paytKind='01' priority='1'>
<Purpose>!!!!!НДС 18%</Purpose>
</AccDoc>
</PayDocRuInvoice>
</Request>
]]></upg:requests>
<!--Optional:-->
<upg:sessionId>5a869c00-e979-4280-b11a-6dbbb8a90214</upg:sessionId>
</upg:sendRequestsSRP>
</soapenv:Body></soapenv:Envelope>In API 2.0, in the same way, things have become much simpler and clearer:
{
"amount": 12.01,
"date": "2018-06-22",
"deliveryKind": "электронно",
"expirationDate": "2018-06-23",
"externalId": "1516ec0c-761c-11e8-adc0-fa7ae01bbebc",
"operationCode": "01",
"orderNumber": "1237",
"payeeAccount": "40706810000000000000",
"paymentNumber": "1",
"priority": "5",
"purpose": "Оплата заказа №1237. НДС не облагается.",
"urgencyCode": "NORMAL",
"vat": {
"amount": 100.01,
"rate": "7",
"type": "NO_VAT"
}Electronic signature, we also facilitated. That's how everything was in API 1.0.
It looked like a request
Here the list of attributes
And ready signature
in API 2.0 version via JSON implemented all the easier:
The query itself
signature as a result of
Results
The fintech API 2.0 pilot launches showed that things went much better. The time of integration with partners' products - from the start of work to the time of release into commercial operation - has decreased by more than 3 times. The number of questions of our support service has decreased by an order of magnitude, and most importantly, the complexity of these questions has decreased. Finally, the number of complaints about the complexity and unpredictability of the API work has decreased by as much as two orders. In general, we did it. If you have any questions - welcome to the comments, we are happy to tell you the details.
Material prepared by Andrei Khokhlov, Project Manager of the Digital Corporate Bank Division of Sberbank