ASA Open API

User Guide
Version 0.6 ● 16 November 2022

ASA Technologies Inc. – [email protected] - ASA.Financial

© 2022 ASA Technologies or an ASA Technologies affiliate company. All rights reserved.

ASA.Financial

Trademarks

Login with ASA are registered trademarks of ASA Financial. All other trademarks or registered
trademarks are the property of their respective owners.

Disclaimer

The information provided in this document is provided "as is" without warranty of any kind. ASA
Technologies disclaims all warranties, either express or implied, including the warranties of
merchantability and fitness for a particular purpose. In no event shall ASA Technologies be liable for
any damages whatsoever including direct, indirect, incidental, consequential, loss of business profits
or special damages, even if ASA Technologies or its suppliers have been advised of the possibility of
such damages.

Document Lifetime

ASA Technologies may occasionally update online documentation between releases of the related
software. Consequently, if this document was not downloaded recently, it may not contain the most
up-to-date information. Please refer to ASA.Financial for the most current information.

From the Web site, you may also download and refresh this document if it has been updated, as
indicated by a change in this date: September 28, 2022.

Where to get help

ASA Technologies support, product, and licensing information can be obtained as follows.

Product information — Documentation, release notes, software updates, and information about ASA
Technologies products, licensing, and service, are at ASA Technologies website at:

ASA.Financial

Technical API specifications are located at:

https://app.swaggerhub.com/apis/ASA-Financial/ASAOpenAPI/

Technical support — Go to ASA.Financial and select Support, or email [email protected].

Note: Please provide your company or entity name when you create the support request
ASA Technologies ASA Open API Version 0.6

Contents
1 INTRODUCTION ............................................................................................................................................. 6

1.1 OPENID OVERVIEW ...........................................................................................................................................6

1.2 HOW IT WORKS IN ASA ......................................................................................................................................6
1.2.1 ASA Vault App ..........................................................................................................................................6
1.2.2 ASA Connect API.......................................................................................................................................7
1.2.3 ASA Identify Server ...................................................................................................................................7
1.2.4 ASA OpenID Service ..................................................................................................................................7
1.2.5 FinTech .....................................................................................................................................................7

2 API ENDPOINT DEFINITION ............................................................................................................................ 8

2.1 COMMON HEADERS AND PARAMETERS ..................................................................................................................8

2.2 STANDARD RESPONSE ........................................................................................................................................9
2.3 AUTHENTICATION............................................................................................................................................10
2.3.1 POST /Authentication/Authorization .....................................................................................................10
2.3.1.1 Expected headers .......................................................................................................................................... 10
2.3.1.2 Expected QueryString parameters ................................................................................................................ 10
2.3.1.3 Expected Body object parameters ................................................................................................................ 10
2.3.1.4 Result Body fields .......................................................................................................................................... 10
2.3.1.5 Sample UAT Request ..................................................................................................................................... 11
2.3.1.6 Sample UAT Response .................................................................................................................................. 11
2.3.2 POST /Authentication/LoginWithASA ....................................................................................................13
2.3.2.1 Expected headers .......................................................................................................................................... 13
2.3.2.2 Expected QueryString parameters ................................................................................................................ 13
2.3.2.3 Expected Body object parameters ................................................................................................................ 13
2.3.2.4 Result Body fields .......................................................................................................................................... 13
2.3.2.5 Sample UAT Request ..................................................................................................................................... 14
2.3.2.6 Sample UAT Response .................................................................................................................................. 14
2.3.3 POST /Authentication/LogOff ................................................................................................................16
2.3.4 POST /Authentication/RefreshToken .....................................................................................................17
2.3.4.1 Expected headers .......................................................................................................................................... 17
2.3.4.2 Expected QueryString parameters ................................................................................................................ 17
2.3.4.3 Expected Body object parameters ................................................................................................................ 17
2.3.4.4 Result Body fields .......................................................................................................................................... 17
2.3.4.5 Sample UAT Request ..................................................................................................................................... 17
2.3.4.6 Sample UAT Response .................................................................................................................................. 18
2.3.5 POST /Authentication/ForgotPassword .................................................................................................19
2.3.5.1 Expected headers .......................................................................................................................................... 19
2.3.5.2 Expected QueryString parameters ................................................................................................................ 19
2.3.5.3 Expected Body object parameters ................................................................................................................ 19
2.3.5.4 Result Body fields .......................................................................................................................................... 19
2.3.5.5 Sample UAT Request ..................................................................................................................................... 19
2.3.5.6 Sample UAT Response .................................................................................................................................. 19

© ASA Technologies 2022. All rights reserved. Page 3 of 54

ASA Technologies ASA Open API Version 0.6

2.3.6 POST /Authentication/ChangePassword ...............................................................................................21

2.3.6.1 Expected headers .......................................................................................................................................... 21
2.3.6.2 Expected QueryString parameters ................................................................................................................ 21
2.3.6.3 Expected Body object parameters ................................................................................................................ 21
2.3.6.4 Result Body fields .......................................................................................................................................... 21
2.3.6.5 Sample UAT Request ..................................................................................................................................... 21
2.3.6.6 Sample UAT Response .................................................................................................................................. 22
2.4 BALANCE .......................................................................................................................................................23
2.4.1 GET /Balance/Accounts .........................................................................................................................23
2.4.1.1 Expected headers .......................................................................................................................................... 23
2.4.1.2 Expected QueryString parameters ................................................................................................................ 23
2.4.1.3 Expected Body object parameters ................................................................................................................ 23
2.4.1.4 Result Body fields .......................................................................................................................................... 23
2.4.1.5 Sample UAT Request ..................................................................................................................................... 24
2.4.1.6 Sample UAT Response .................................................................................................................................. 24
2.4.2 GET /Balance/Details .............................................................................................................................26
2.4.2.1 Expected headers (see 2.1 for clarification) .................................................................................................. 26
2.4.2.2 Expected QueryString parameters ................................................................................................................ 26
2.4.2.3 Expected Body object parameters ................................................................................................................ 26
2.4.2.4 Result Body fields .......................................................................................................................................... 26
2.4.2.5 Sample UAT Request ..................................................................................................................................... 27
2.4.2.6 Sample UAT Response .................................................................................................................................. 27
2.5 CALLBACKS ....................................................................................................................................................29
2.6 DYNAMIC LINKS ..............................................................................................................................................30
2.6.1 GET /DynamicLink ..................................................................................................................................30
2.6.1.1 Expected headers .......................................................................................................................................... 30
2.6.1.2 Expected QueryString parameters ................................................................................................................ 30
2.6.1.3 Expected Body object parameters ................................................................................................................ 30
2.6.1.4 Result Body fields .......................................................................................................................................... 30
2.6.1.5 Sample UAT Request ..................................................................................................................................... 31
2.6.1.6 Sample UAT Response .................................................................................................................................. 31
2.7 INSTITUTION...................................................................................................................................................33
2.8 PRODUCT ......................................................................................................................................................34
2.8.1 GET /Products ........................................................................................................................................34
2.8.1.1 Expected headers .......................................................................................................................................... 34
2.8.1.2 Expected QueryString parameters ................................................................................................................ 34
2.8.1.3 Expected Body object parameters ................................................................................................................ 34
2.8.1.4 Result Body fields .......................................................................................................................................... 34
2.8.1.5 Sample UAT Request ..................................................................................................................................... 34
2.8.1.6 Sample UAT Response .................................................................................................................................. 35
2.9 TRANSACTIONCATEGORY ..................................................................................................................................36
2.9.1 GET /TransactionCategories ..................................................................................................................36
2.9.1.1 Expected headers .......................................................................................................................................... 36
2.9.1.2 Expected QueryString parameters ................................................................................................................ 36
2.9.1.3 Expected Body object parameters ................................................................................................................ 36
2.9.1.4 Result Body fields .......................................................................................................................................... 36

© ASA Technologies 2022. All rights reserved. Page 4 of 54

ASA Technologies ASA Open API Version 0.6

2.9.1.5 Sample UAT Request ..................................................................................................................................... 37

2.9.1.6 Sample UAT Response .................................................................................................................................. 37
2.10 TRANSACTIONS ...............................................................................................................................................39
2.10.1 POST /Transactions ...........................................................................................................................39
2.10.1.1 Expected headers .......................................................................................................................................... 39
2.10.1.2 Expected QueryString parameters ................................................................................................................ 39
2.10.1.3 Expected Body object parameters ................................................................................................................ 39
2.10.1.4 Result Body fields .......................................................................................................................................... 40
2.10.1.5 Sample UAT Request 1 (bare, no filtering) .................................................................................................... 42
2.10.1.6 Sample UAT Request 2 (count, offset, date filtering) .................................................................................... 43
2.10.1.7 Sample UAT Response .................................................................................................................................. 43

3 TECHNICAL IMPLEMENTATION .................................................................................................................... 46

3.1 FINTECH SETUP WITH ASA ...............................................................................................................................46

3.2 STEPS TO INTEGRATE: LOGIN WITH ASA ..............................................................................................................46

4 APPENDIX A: ACRONYMS, ABBREVIATIONS & DEFINITIONS ........................................................................ 50

5 APPENDIX B: DOCUMENT CHANGELOG ....................................................................................................... 54

© ASA Technologies 2022. All rights reserved. Page 5 of 54

ASA Technologies ASA Open API Version 0.6

1 Introduction
ASA is a secure and reliable Digital Services Network that connects with the banks in the United
States to allow FinTech (Financial Technology companies that use Consumers’ information) to
access the consumers data. The consumer (Account Holder) authenticates the ASA Vault app
with their Bank data and chooses which data to share with a FinTech. This makes the consumers
data accessible to a FinTech. This is a credible service-providing network that places the
consumer in control of the extent of accessibility of his/her data. It also provides information to
the banks regarding FinTech’s chosen by consumer through the ASA Vault App.
When a consumer uses Login with ASA (OpenID), the consumer can decide what information
they want to share with the FinTech. In this way, logging in with ASA facilitates FinTech’s
accessing the required information from the bank while allowing the consumer to exclusively
control what data is shared.

1.1 OpenID Overview

Open ID is an existing technology that provides its users with the facility to sign into several
websites without having to create new logins. The user does not need to create a new password
to log in to a website as OpenID allows secure management of the credentials with the identity
provider, in this case ASA, and the consumer can login to the website he/she wants to use.
OpenID is secure for the consumers since it shares the password only with the identity provider
(ASA) and no other parties can access the user’s information. There is no chance of
compromising the sensitive data as OpenID provides the password only to the user’s credible
identity provider and even the websites the user visits are not allowed to see the password.
In addition, the consumer can decide what information they choose to be shared with the FinTech
that he/she visits, such as email address or name. The consumer can choose to not share
anything with the FinTech other than logging in with ASA. OpenID allows the consumer to
completely control how much information is to be shared with the FinTech that is being accessed.
OAuth 2.0 is used by the FinTech to authorize the consumer to access their site without seeing
the credential details.

1.2 How it works in ASA

The whole process of logging in with ASA has defined steps and components involved in it which
are explained in the following:

1.2.1 ASA Vault App

© ASA Technologies 2022. All rights reserved. Page 6 of 54

ASA Technologies ASA Open API Version 0.6

This is the mobile application that a consumer installs and it connects the consumers account
information, which can be used to allow a FinTech access the account owner's information.
However, ASA Vault does not provide the actual accounts to the FinTech. Rather, it provides
anonymized account information to protect the consumers sensitive financial information.

1.2.2 ASA Connect API

This is the API that the FinTech company integrates to request consumer financial data. This API
enables the FinTech’s to access the data allowed by the consumers (account holders) for any
bank.

1.2.3 ASA Identify Server

ASA provides the identity server to the FinTech’s. This service is called from the FinTech
application and provides identity validation services. The consumer’s identity is confirmed by the
identity server and the identity server provides an identity token to the FinTech. Using the identity
token, the consumer is allowed access to the services (application) offered by FinTech.

1.2.4 ASA OpenID Service

ASA provides FinTech’s and other customers an identification server that they can embed within
their application to provide identity validation services. The consumers can opt to Login with ASA,
and it allows the FinTech to access the data of the users (who already have logged in with ASA)
via ASA Financial.

1.2.5 FinTech
This is the Financial Technologies company that is registered with the ASA platform and intends
to provide services to the consumers and the Financial Institutions.

© ASA Technologies 2022. All rights reserved. Page 7 of 54

ASA Technologies ASA Open API Version 0.6

2 API Endpoint Definition

ASA OpenAPI is currently being transformed and matured as we’re learning more about our
customer’s needs. Our endpoint upgrade strategy ensures that as long as the version number
hasn’t changed, then the same requests will continue to work and the core functionality /
responses will remain the same as expected, however some exceptions may apply (such as when
security requirements are tightened), you may always find the latest version available at Swagger
Hub: https://app.swaggerhub.com/apis/ASA-Financial/ASAOpenAPI/

2.1 Common headers and parameters

The following are some common parameters used by our OpenAPI endpoints in the current 0.0.5
version.
2.1.1 Ocp-Apim-Subscription-Key Header
Subscription key required in all endpoint calls in order for access to be allowed by our API
Management layer.
2.1.2 Authorization Header
Bearer token generated with the /Authentication/LoginWithASA endpoint which serves as claim
that the request which contains it is being made by a certain Fintech on behalf of the Consumer
who has logged-in with their credentials.
2.1.3 RequestId Header
Identification for the current transaction. If provided, the same value will be present in the
Response’s headers, if not, it will be auto-generated by our backend layer. It is recommended
that it is provided by the client. Present in all endpoints except Auth.
2.1.4 X-ASA-ApiVersion Header
Version of the endpoint that’s expected to handle the current request. If not provided, it will be
defaulted to the oldest still-supported version for backwards compatibility. In v0.0.5 it’s also
accepted as ApiVersion.
2.1.5 X-ASA-ConsumerCode Header
ASA-generated Id for the currently authenticated Consumer. Only required by endpoints which
access Consumer’s data. If provided it will be matched against the ConsumerCode associated
with the given bearer token. For backwards compatibility, in v0.0.5 this value is also accepted as
ASAConsumerCode in headers or as a Query String parameter.
2.1.6 X-ASA-FintechCode Header

© ASA Technologies 2022. All rights reserved. Page 8 of 54

ASA Technologies ASA Open API Version 0.6

ASA-generated Id for the currently authenticated Fintech. Only required by endpoints which
access Fintech’s data, or data that a Consumer must have explicitly authorized a certain Fintech
to access. If provided it will be matched against the FintechCode associated with the given bearer
token. For backward compatibility, in v0.0.5 this value is also accepted as ASAFintechCode in
headers or as a Query String parameter.

2.2 Standard Response

Leaving aside Authentication, all endpoints return data with our standard response format, which
is a JSON body containing:
● status: standard HTTP status code
● message: brief description of what has happened during the request and/or what this
response contains in the data object.
● reference: object with requestId and server timeStamp
● version: version number of the endpoint which actually produced this response
● data: details of the processed response, may be a number, string, object or any data type
as required.

© ASA Technologies 2022. All rights reserved. Page 9 of 54

ASA Technologies ASA Open API Version 0.6

2.3 Authentication
The Auth process for ASA’s OpenAPI involves two steps: first, each Fintech must call the
/Authorization endpoint, which generates a short-lived OpenId token embedded in an ASA Core
login URL. Then, either using this URL or through the /LoginWithASA endpoint, a bearer token
can be generated and then used for accessing the Consumer’s data that’s been authorized for
the given Fintech. Further details on this process can be found in our “Login with ASA” document.

2.3.1 POST /Authentication/Authorization

Generates a short-lived OpenId token embedded in an ASA Core login URL, which can also be
used directly with the /LoginWithASA endpoint.

2.3.1.1 Expected headers

● Ocp-Apim-Subscription-Key: Subscription key required in all endpoint calls in order for
access to be allowed by our API Management layer.

2.3.1.2 Expected QueryString parameters

None.

2.3.1.3 Expected Body object parameters

● asaFintechCode: required, ASA-generated id for the Fintech attempting to authenticate
● applicationCode: required, ASA-generated id for the Fintech’s application currently using
the API
● authorizationKey: required, secret key that ensures the login request has actually
originated from the application with the given ApplicationCode
● redirectUrl: required, base URL for redirecting the user after successful login
● redirectFailureUrl: required, base URL for redirecting the user in case of a failed login
● scope: required, the kind of token to be generated by the endpoint, currently only accepts
“openid”
● subscriptionKey: required, secret key which authorizes the Fintech to access the current
environment (may be sandbox or production)
● apiVersion: optional, version of the endpoint that’s expected to handle the current
request. If not provided, it will be defaulted to the oldest still-supported version for
backwards compatibility. In v0.0.5 it’s also accepted as ApiVersion

2.3.1.4 Result Body fields

● status: standard HTTP status code
● message: brief description of what has happened during the request and/or what this
response contains in the data object.

© ASA Technologies 2022. All rights reserved. Page 10 of 54

ASA Technologies ASA Open API Version 0.6

● reference: object with requestId and server timeStamp

● version: version number of the endpoint which actually produced this response
● data: object with the following key-value pairs:
○ field: UniqueLoginUrl - descriptor of what is returned
○ message: log-in-URL - the actual URL for calling the
Authentication/LoginWithASA endpoint

2.3.1.5 Sample UAT Request

curl -X 'POST' \
'https://openapiuat.asacore.com/Authentication/Authorization' \
-H 'accept: text/plain' \
-H 'Content-Type: application/json' \
-H 'Ocp-Apim-Subscription-Key: yourApimSubscriptionKeyHere' \
-d '{
"asaFintechCode": "yourFintechCodeHere",
"applicationCode": "yourApplicationCodeHere",
"authorizationKey": "yourAuthorizationKeyHere",
"redirectUrl": "yourAppSuccessPageHere",
"redirectFailureUrl": "yourAppFailurePageHere",
"scope": "openid",
"subscriptionKey": "yourSubscriptionKeyHere",
"apiVersion": "0.05"
}'

2.3.1.6 Sample UAT Response

{
"status": 200,
"message": "Success, Authentication done successfully",
"reference": [
{
"requestId": "99999999999",
"timeStamp": "2022-11-14T19:10:12.0161587+00:00"
}
],
"version": "0.0.5",
"data": {
"field": "UniqueLoginUrl",
"message":
"https://authuat.asacore.com/login?idtoken=yourNewlyGeneratedIdToken&key=yo
urSubscriptionKey&id=99999999999"

© ASA Technologies 2022. All rights reserved. Page 11 of 54

ASA Technologies ASA Open API Version 0.6

}
}

© ASA Technologies 2022. All rights reserved. Page 12 of 54

ASA Technologies ASA Open API Version 0.6

2.3.2 POST /Authentication/LoginWithASA

Generates a bearer token which allows calling all other API endpoints. Using the login box
provided in the UniqueLoginUrl field (which points to auth.asacore.com) in the /Authorization
response internally calls this endpoint and, if successfully logged-in, redirects to the provided
redirect URL.

2.3.2.1 Expected headers

● Ocp-Apim-Subscription-Key: Subscription key required in all endpoint calls in order for
access to be allowed by our API Management layer.

2.3.2.2 Expected QueryString parameters

None.

2.3.2.3 Expected Body object parameters

● userName: required, email of the Consumer attempting to login
● password: required, password of the Consumer attempting to login
● token: required, openId token generated with the Authentication/Authorization endpoint
for the given Fintech’s Application, extracted from its response’s UniqueLoginURL field.
● requestId: optional, identification for the current transaction. If provided, the same value
will be present in the Response’s headers, if not, it will be auto-generated by our backend
layer. It is recommended that it is provided by the client.

2.3.2.4 Result Body fields

● status: standard HTTP status code
● message: brief description of what has happened during the request and/or what this
response contains in the data object.
● reference: object with requestId and server timeStamp
● version: version number of the endpoint which actually produced this response
● data: object with the following key-value pairs:
○ asaFintechCode: yourFintechCode - same FintechCode as provided in the
/Authentication/Authorization endpoint which generated the Id Token used for
this request
○ asaConsumerCode: "theUsersASAConsumerCode" - the ConsumerCode for
the User who has just logged-in
○ scope: bearer - kind of token which has been generated by this endpoint, and
which should be appended prior to it on requests
○ token: yourNewlyGeneratedBearerToken - bearer token string ready to be
used in any request’s Authorization header.

© ASA Technologies 2022. All rights reserved. Page 13 of 54

ASA Technologies ASA Open API Version 0.6

○ tokenExpiryDate: ISO-8601UTCtimestamp - UTC timestamp of when the

returned token will cease to be valid
○ redirectURL:
yourAppSuccessPageHere?asaconsumerCode=theUsersASAConsumerCo
de&bearerToken=yourNewlyGeneratedBearerToken&asaFintechCode=your
FintechCode&expirydatefortoken=ISO-8601UTCtimestamp" - a redirection
URL ready to move the user back into the Fintech’s Application
○ status: success - redundant field which will be removed
○ errorMessage - redundant field which will be removed
○ errorCode - redundant field which will be removed

2.3.2.5 Sample UAT Request

curl -X 'POST' \
'https://openapiuat.asacore.com/Authentication/LoginWithASA' \
-H 'accept: text/plain' \
-H 'Content-Type: application/json' \
-H 'Ocp-Apim-Subscription-Key: yourApimSubscriptionKeyHere' \
-d '{
"userName": "theConsumersEmailAddressHere",
"password": "theConsumersPasswordHere",
"token": "yourIdTokenExtractedFromAuthorizationsUniqueLoginUrlField",
"requestId": "99999999999"
}'

2.3.2.6 Sample UAT Response

{
"status": 200,
"message": "Success",
"reference": [
{
"requestId": "99999999999",
"timeStamp": "2022-11-14T19:19:24.1518911+00:00"
}
],
"version": "0.0.5",
"data": {
"asaFintechCode": "yourFintechCode",
"asaConsumerCode": "theUsersASAConsumerCode",
"scope": "bearer",

© ASA Technologies 2022. All rights reserved. Page 14 of 54

ASA Technologies ASA Open API Version 0.6

"token": "yourNewlyGeneratedBearerToken",
"tokenExpiryDate": "2022-11-16T19:19:24.5271574Z",
"redirectURL":
"https://www.example.org/asaloginsuccess?asaconsumerCode=theUsersASAConsume
rCode&bearerToken=yourNewlyGeneratedBearerToken&asaFintechCode=yourFintechC
ode&expirydatefortoken=2022-11-16T19:19:24.5271574Z",
"status": "success",
"errorMessage": null,
"errorCode": null
}
}

© ASA Technologies 2022. All rights reserved. Page 15 of 54

ASA Technologies ASA Open API Version 0.6

2.3.3 POST /Authentication/LogOff

Not implemented yet, will invalidate the given bearer token.

© ASA Technologies 2022. All rights reserved. Page 16 of 54

ASA Technologies ASA Open API Version 0.6

2.3.4 POST /Authentication/RefreshToken

Generates a bearer token identical to the one provided in the Authorization header, but with an
extended expiration date.

2.3.4.1 Expected headers

● Ocp-Apim-Subscription-Key: subscription key required in all endpoint calls in order for
access to be allowed by our API Management layer.
● Authorization: bearer token generated with the /Authentication/LoginWithASA endpoint
which serves as claim that the request which contains it is being made by a certain Fintech
on behalf of the Consumer who has logged-in with their credentials.

2.3.4.2 Expected QueryString parameters

None.

2.3.4.3 Expected Body object parameters

None.

2.3.4.4 Result Body fields

● status: standard HTTP status code
● message: brief description of what has happened during the request and/or what this
response contains in the data object.
● reference: object with requestId and server timeStamp
● version: version number of the endpoint which actually produced this response
● data: object with the following key-value pairs:
○ token: yourNewlyGeneratedBearerToken - a token with the same auth claims
as the one provided in the request, but with an extended expiration date
○ tokenExpiryDate: ISO-8601UTCtimestamp - UTC timestamp of when the
returned token will cease to be valid

2.3.4.5 Sample UAT Request

curl -X 'POST' \
'https://openapiuat.asacore.com/Authentication/RefreshToken' \
-H 'accept: text/plain' \
-H 'Ocp-Apim-Subscription-Key: yourApimSubscriptionKey' \
-H 'Authorization: bearer
yourBearerTokenFromLoginWithAsaOrRefreshTokenEndpoint' \
-d ''

© ASA Technologies 2022. All rights reserved. Page 17 of 54

ASA Technologies ASA Open API Version 0.6

2.3.4.6 Sample UAT Response

{
"status": 200,
"message": "Success",
"reference": [
{
"requestId": "99999999999",
"timeStamp": "2022-11-14T19:32:28.8143111+00:00"
}
],
"version": "0.0.5",
"data": {
"token": "yourNewlyGeneratedBearerToken",
"tokenExpiryDate": "2022-11-16T19:32:28.8298143+00:00"
}
}

© ASA Technologies 2022. All rights reserved. Page 18 of 54

ASA Technologies ASA Open API Version 0.6

2.3.5 POST /Authentication/ForgotPassword

Resets the Consumer’s password with a new randomly-generated temporary password and
sends it via email.

2.3.5.1 Expected headers

● Ocp-Apim-Subscription-Key: subscription key required in all endpoint calls in order for
access to be allowed by our API Management layer.

2.3.5.2 Expected QueryString parameters

None.

2.3.5.3 Expected Body object parameters

● emailId: email of the Consumer who has forgotten their password

2.3.5.4 Result Body fields

● status: standard HTTP status code
● message: brief description of what has happened during the request and/or what this
response contains in the data object.
● reference: object with requestId and server timeStamp
● version: version number of the endpoint which actually produced this response
● data: message pointing user to what the server has done so they can decide their next
action

2.3.5.5 Sample UAT Request

curl -X 'POST' \
'https://openapiuat.asacore.com/Authentication/ForgotPassword' \
-H 'accept: text/plain' \
-H 'Ocp-Apim-Subscription-Key: yourApimSubscriptionKey' \
-H 'Authorization: bearer
yourBearerTokenFromLoginWithAsaOrRefreshTokenEndpoint' \
-d '{
"emailId": "theConsumersEmailAddressHere"
}'

2.3.5.6 Sample UAT Response

© ASA Technologies 2022. All rights reserved. Page 19 of 54

ASA Technologies ASA Open API Version 0.6

"status": 200,
"message": "Success",
"reference": [
{
"requestId": "99999999999",
"timeStamp": "2022-11-14T19:38:19.0443175+00:00"
}
],
"version": "0.0.5",
"data": "Temporary Password sent via email."
}

© ASA Technologies 2022. All rights reserved. Page 20 of 54

ASA Technologies ASA Open API Version 0.6

2.3.6 POST /Authentication/ChangePassword

Changes the currently logged-in Consumer’s password to the one given.

2.3.6.1 Expected headers

● Ocp-Apim-Subscription-Key: Subscription key required in all endpoint calls in order for
access to be allowed by our API Management layer.
● Authorization: bearer token generated with the /Authentication/LoginWithASA endpoint
which serves as claim that the request which contains it is being made by a certain Fintech
on behalf of the Consumer who has logged-in with their credentials.

2.3.6.2 Expected QueryString parameters

None.

2.3.6.3 Expected Body object parameters

● oldPassword: password which is currently valid for the Consumer’s login
● newPassword: password which will become the new password for the Consumer’s login

2.3.6.4 Result Body fields

● status: standard HTTP status code
● message: brief description of what has happened during the request and/or what this
response contains in the data object.
● reference: object with requestId and server timeStamp
● version: version number of the endpoint which actually produced this response
● data: message pointing user to what the server has done so they can decide their next
action

2.3.6.5 Sample UAT Request

curl -X 'POST' \
'https://openapiuat.asacore.com/Authentication/ChangePassword \
-H 'accept: text/plain' \
-H 'Ocp-Apim-Subscription-Key: yourApimSubscriptionKeyHere' \
-H 'Authorization: bearer
yourBearerTokenFromLoginWithAsaOrRefreshTokenEndpointHere' \
-d '{
"oldPassword": "theConsumersCurrentlyValidPasswordHere",
"newPassword": "theConsumersNewPasswordHere"
}'

© ASA Technologies 2022. All rights reserved. Page 21 of 54

ASA Technologies ASA Open API Version 0.6

2.3.6.6 Sample UAT Response

{
"status": 200,
"message": "Success.",
"reference": [
{
"requestId": "99999999999",
"timeStamp": "2022-11-14T19:44:35.0214427+00:00"
}
],
"version": "0.0.5",
"data": "Password changed successfully."
}

© ASA Technologies 2022. All rights reserved. Page 22 of 54

ASA Technologies ASA Open API Version 0.6

2.4 Balance
Endpoints for fetching the Consumer’s Accounts, their balances, and detailed information.

2.4.1 GET /Balance/Accounts

Returns all the Consumer Accounts currently authorized to be accessed by the bearer token’s
Fintech along with their Ids and summarized details.

2.4.1.1 Expected headers

● Ocp-Apim-Subscription-Key: Subscription key required in all endpoint calls in order for
access to be allowed by our API Management layer.
● Authorization: bearer token generated with the /Authentication/LoginWithASA endpoint
which serves as claim that the request which contains it is being made by a certain Fintech
on behalf of the Consumer who has logged-in with their credentials.
● RequestId: identification for the current transaction. If provided, the same value will be
present in the Response’s headers, if not, it will be auto-generated by our backend layer.
It is recommended that it is provided by the client.
● X-ASA-ApiVersion: version of the endpoint that’s expected to handle the current request.
If not provided, it will be defaulted to the oldest still-supported version for backwards
compatibility. In v0.0.5 it’s also accepted as ApiVersion.
● X-ASA-ConsumerCode: ASA-generated Id for the currently authenticated Consumer.
For backwards compatibility, in v0.0.5 this value is also accepted as ASAConsumerCode
in headers or as a Query String parameter.
● X-ASA-FintechCode: ASA-generated Id for the currently authenticated Fintech. For
backward compatibility, in v0.0.5 this value is also accepted as ASAFintechCode in
headers or as a Query String parameter.

2.4.1.2 Expected QueryString parameters

None (AsaConsumerCode and AsaFintechCode accepted as header alternative).

2.4.1.3 Expected Body object parameters

None.

2.4.1.4 Result Body fields

● status: standard HTTP status code
● message: brief description of what has happened during the request and/or what this
response contains in the data object.
● reference: object with requestId and server timeStamp
● version: version number of the endpoint which actually produced this response

© ASA Technologies 2022. All rights reserved. Page 23 of 54

ASA Technologies ASA Open API Version 0.6

● data: array with objects which each have the following key-value pairs for every
Consumer account that the Fintech is currently granted access for the given Consumer:
○ asaConsumerCode: theUsersASAConsumerCode - ASAConsumerCode for
the given consumer
○ asaFintechCode: yourFintechCode - ASAFintechCode for the given Fitnech
○ accountNumber: accountNumber - ASA-generated account number
○ name: accountName - name of the account
○ description: accountDescription - description of the account
○ dateOpened: ISO-8601UTCtimestamp - timestamp of when the Account was
created
○ balance: double - numeric value of the account’s current balance
○ currencyCode: USD - ISO Currency code for the account’s currency

2.4.1.5 Sample UAT Request

curl -X 'GET' \
'https://openapiuat.asacore.com/Balance/Accounts' \
-H 'accept: */*' \
-H 'Ocp-Apim-Subscription-Key: yourApimSubscriptionKeyHere' \
-H 'X-ASA-ConsumerCode: theUsersASAConsumerCode' \
-H 'X-ASA-FintechCode: yourFintechCode'\
-H 'RequestId: 99999999' \
-H 'Authorization: bearer
yourBearerTokenFromLoginWithAsaOrRefreshTokenEndpointHere'

2.4.1.6 Sample UAT Response

{
"status": 200,
"message": "Authorized Accounts for : theUsersASAConsumerCode.",
"reference": [
{
"requestId": "123",
"timeStamp": "2022-11-14T19:49:31.6185878+00:00"
}
],
"version": "0.0.5",
"data": [
{
"asaConsumerCode": theUsersASAConsumerCode,
"asaFintechCode": yourFintechCode,

© ASA Technologies 2022. All rights reserved. Page 24 of 54

ASA Technologies ASA Open API Version 0.6

"accountNumber": oneAuthorizedAccountNumber,
"name": "Savings (example)",
"description": "SAVINGS (example)",
"dateOpened": "2006-08-15T00:00:00",
"balance": 9876.54,
"currencyCode": "USD"
},
{
"asaConsumerCode": theUsersASAConsumerCode,
"asaFintechCode": yourFintechCode,
"accountNumber": anotherAuthorizedAccountNumber,
"name": "Checking (example)",
"description": "Checking (example)",
"dateOpened": "2016-08-15T00:00:00",
"balance": 0.00,
"currencyCode": "USD"
}
]
}

© ASA Technologies 2022. All rights reserved. Page 25 of 54

ASA Technologies ASA Open API Version 0.6

2.4.2 GET /Balance/Details

Returns the details for the Account with the given AccountId.

2.4.2.1 Expected headers (see 2.1 for clarification)

● Ocp-Apim-Subscription-Key: Subscription key required in all endpoint calls in order for
access to be allowed by our API Management layer.
● Authorization: bearer token generated with the /Authentication/LoginWithASA endpoint
which serves as claim that the request which contains it is being made by a certain Fintech
on behalf of the Consumer who has logged-in with their credentials.
● RequestId: identification for the current transaction. If provided, the same value will be
present in the Response’s headers, if not, it will be auto-generated by our backend layer.
It is recommended that it is provided by the client.
● X-ASA-ApiVersion: version of the endpoint that’s expected to handle the current request.
If not provided, it will be defaulted to the oldest still-supported version for backwards
compatibility. In v0.0.5 it’s also accepted as ApiVersion.
● X-ASA-ConsumerCode: ASA-generated Id for the currently authenticated Consumer.
For backwards compatibility, in v0.0.5 this value is also accepted as ASAConsumerCode
in headers or as a Query String parameter.
● X-ASA-FintechCode: ASA-generated Id for the currently authenticated Fintech. For
backward compatibility, in v0.0.5 this value is also accepted as ASAFintechCode in
headers or as a Query String parameter.
● AccountNumber: ASA-generated Account Id

2.4.2.2 Expected QueryString parameters

None (AsaConsumerCode and AsaFintechCode accepted as header alternative).

2.4.2.3 Expected Body object parameters

None.

2.4.2.4 Result Body fields

● status: standard HTTP status code
● message: brief description of what has happened during the request and/or what this
response contains in the data object.
● reference: object with requestId and server timeStamp
● version: version number of the endpoint which actually produced this response
● data: object with key-value pairs which entail details for the Consumer’s account
currently being accessed:
○ accountNumber: accountNumber - ASA-generated account number
○ name: accountName - name of the account

© ASA Technologies 2022. All rights reserved. Page 26 of 54

ASA Technologies ASA Open API Version 0.6

○ available: double - numeric value of the account’s currently available amount

○ current: double - numeric value of the account’s currently available amount
○ limit: double - numeric value of the account’s limit
○ isoCurrencyCode: USD - ISO Currency code for the account’s currency
○ unofficialCurrencyCode: USD - informal currency code for the account’s
currency

2.4.2.5 Sample UAT Request

curl -X 'GET' \
'https://openapiuat.asacore.com/Balance/Details' \
-H 'accept: */*' \
-H 'Ocp-Apim-Subscription-Key: yourApimSubscriptionKeyHere' \
-H 'X-ASA-ConsumerCode: theUsersASAConsumerCode' \
-H 'X-ASA-FintechCode: yourFintechCode'\
-H 'AccountNumber: someAuthorizedAccountNumber' \
-H 'RequestId: 99999999' \
-H 'Authorization: bearer
yourBearerTokenFromLoginWithAsaOrRefreshTokenEndpointHere'

2.4.2.6 Sample UAT Response

{
"status": 200,
"message": "Account balance detail for account:
someAuthorizedAccountNumber.",
"reference": [
{
"requestId": "9999999999",
"timeStamp": "2022-11-14T20:10:42.8833218+00:00"
}
],
"version": "0.0.5",
"data": {
"accountNumber": someAuthorizedAccountNumber,
"accountName": "Savings (example)",
"available": 9876.54,
"current": 9876.54,
"limit": 0,
"isoCurrencyCode": "USD",
"unofficialCurrencyCode": "USD"
}

© ASA Technologies 2022. All rights reserved. Page 27 of 54

ASA Technologies ASA Open API Version 0.6

© ASA Technologies 2022. All rights reserved. Page 28 of 54

ASA Technologies ASA Open API Version 0.6

2.5 Callbacks
Placeholder for not yet implemented endpoints:
● GET /Register
● GET /UnRegister
● GET /ActivityList
● GET /FailedRequests

© ASA Technologies 2022. All rights reserved. Page 29 of 54

ASA Technologies ASA Open API Version 0.6

2.6 Dynamic Links

Endpoints for managing Dynamic Links to ASA Vault.

2.6.1 GET /DynamicLink

Returns a URL for accessing ASA Vault for the given Consumer as the authenticated Fintech.

2.6.1.1 Expected headers

● Ocp-Apim-Subscription-Key: Subscription key required in all endpoint calls in order for
access to be allowed by our API Management layer.
● Authorization: bearer token generated with the /Authentication/LoginWithASA endpoint
which serves as claim that the request which contains it is being made by a certain Fintech
on behalf of the Consumer who has logged-in with their credentials.
● RequestId: identification for the current transaction. If provided, the same value will be
present in the Response’s headers, if not, it will be auto-generated by our backend layer.
It is recommended that it is provided by the client.
● X-ASA-ApiVersion: version of the endpoint that’s expected to handle the current request.
If not provided, it will be defaulted to the oldest still-supported version for backwards
compatibility. In v0.0.5 it’s also accepted as ApiVersion.
● X-ASA-ConsumerCode: ASA-generated Id for the currently authenticated Consumer.
For backwards compatibility, in v0.0.5 this value is also accepted as ASAConsumerCode
in headers or as a Query String parameter.
● X-ASA-FintechCode: ASA-generated Id for the currently authenticated Fintech. For
backward compatibility, in v0.0.5 this value is also accepted as ASAFintechCode in
headers or as a Query String parameter.
● FirstName: first name of the person who’ll receive the generated link
● LastName: last name of the person who’ll receive the generated link
● BearerToken: bearer token which will be embedded in the generated link

2.6.1.2 Expected QueryString parameters

None (AsaConsumerCode and AsaFintechCode accepted as header alternative).

2.6.1.3 Expected Body object parameters

None.

2.6.1.4 Result Body fields

● status: standard HTTP status code
● message: brief description of what has happened during the request and/or what this
response contains in the data object.
● reference: object with requestId and server timeStamp

© ASA Technologies 2022. All rights reserved. Page 30 of 54

ASA Technologies ASA Open API Version 0.6

● version: version number of the endpoint which actually produced this response
● data: object with a “dynamicLinkInfo” key, which in turn contains the following key-value
pairs:
○ domainUriPrefix: baseURL - the domain to which the generated link will point to
○ link: fullURL - URL for accessing ASA vault directly to the given Fintech and
Consumer
○ androidInfo: object - contains a key-value pair with:
■ androidPackageName: com.asa.vault
○ iosInfo: object - contains a key-value pair with:
■ iosBundleId: com.asa.vault

2.6.1.5 Sample UAT Request

curl -X 'GET' \
'https://openapiuat.asacore.com/DynamicLink' \
-H 'accept: text/plain' \
-H 'Ocp-Apim-Subscription-Key: yourApimSubscriptionKeyHere' \
-H 'X-ASA-ConsumerCode: theUsersASAConsumerCode' \
-H 'X-ASA-FintechCode: yourFintechCode' \
-H 'FirstName: recepientsFirstName' \
-H 'LastName: recipientsLastName' \
-H 'BearerToken: bearerTokenForLinkHere' \
-H 'RequestId: 99999999999' \
-H 'Authorization: bearer
yourBearerTokenFromLoginWithAsaOrRefreshTokenEndpointHere'

2.6.1.6 Sample UAT Response

{
"status": 200,
"message": "Account balance detail for account:
someAuthorizedAccountNumber.",
"reference": [
{
"requestId": "9999999999",
"timeStamp": "2022-11-14T20:10:42.8833218+00:00"
}
],
"version": "0.0.5",
"data": {
"dynamicLinkInfo": {

© ASA Technologies 2022. All rights reserved. Page 31 of 54

ASA Technologies ASA Open API Version 0.6

"domainUriPrefix": "https://asacore.com",
"link":
"https://asacore.com/asavault?consumercode=theUsersASAConsumerCode&firstnam
e=recepientsFirstName&lastname=recepientsLastName&bearerToken=bearerTokenFo
rLink&asaFintechCode=yourFintechCode",
"androidInfo": {
"androidPackageName": "com.asa.vault"
},
"iosInfo": {
"iosBundleId": "com.asa.vault"
}
}
}
}

© ASA Technologies 2022. All rights reserved. Page 32 of 54

ASA Technologies ASA Open API Version 0.6

2.7 Institution
Placeholder for not yet implemented endpoints:
● GET /List

© ASA Technologies 2022. All rights reserved. Page 33 of 54

ASA Technologies ASA Open API Version 0.6

2.8 Product
Endpoints for fetching the currently supported Products.

2.8.1 GET /Products

Returns a list of the names of all the currently supported products..

2.8.1.1 Expected headers

● Ocp-Apim-Subscription-Key: Subscription key required in all endpoint calls in order for
access to be allowed by our API Management layer.
● Authorization: bearer token generated with the /Authentication/LoginWithASA endpoint
which serves as claim that the request which contains it is being made by a certain Fintech
on behalf of the Consumer who has logged-in with their credentials.
● RequestId: identification for the current transaction. If provided, the same value will be
present in the Response’s headers, if not, it will be auto-generated by our backend layer.
It is recommended that it is provided by the client.
● X-ASA-ApiVersion: version of the endpoint that’s expected to handle the current request.
If not provided, it will be defaulted to the oldest still-supported version for backwards
compatibility. In v0.0.5 it’s also accepted as ApiVersion.

2.8.1.2 Expected QueryString parameters

None.

2.8.1.3 Expected Body object parameters

None.

2.8.1.4 Result Body fields

● status: standard HTTP status code
● message: brief description of what has happened during the request and/or what this
response contains in the data object.
● reference: object with requestId and server timeStamp
● version: version number of the endpoint which actually produced this response
● data: array containing the list of currently-supported Product names

2.8.1.5 Sample UAT Request

curl -X 'GET' \
'https://openapiuat.asacore.com/Products \
-H 'accept: */*' \
-H 'Ocp-Apim-Subscription-Key: yourApimSubscriptionKeyHere' \

© ASA Technologies 2022. All rights reserved. Page 34 of 54

ASA Technologies ASA Open API Version 0.6

-H 'RequestId: 99999999' \
-H 'Authorization: bearer
yourBearerTokenFromLoginWithAsaOrRefreshTokenEndpointHere'

2.8.1.6 Sample UAT Response

{
"status": 200,
"message": null,
"reference": [
{
"requestId": "99999",
"timeStamp": "2022-11-14T20:51:36.2066059+00:00"
}
],
"version": "0.0.5",
"data": [
"assets",
"auth",
"balance",
"identity",
"investments",
"liabilities",
"payment_initiation",
"identity_verification",
"transactions",
"credit_details",
"income",
"income_verification",
"deposit_switch",
"standing_orders",
"transfer",
"employment",
"recurring_transactions"
]
}

© ASA Technologies 2022. All rights reserved. Page 35 of 54

ASA Technologies ASA Open API Version 0.6

2.9 TransactionCategory
Endpoints for fetching the currently supported Transaction Categories.

2.9.1 GET /TransactionCategories

Returns a list of the names of the currently active Transaction Categories together with their ids
and details such as hierarchical structure.

2.9.1.1 Expected headers

● Ocp-Apim-Subscription-Key: Subscription key required in all endpoint calls in order for
access to be allowed by our API Management layer.
● Authorization: bearer token generated with the /Authentication/LoginWithASA endpoint
which serves as claim that the request which contains it is being made by a certain Fintech
on behalf of the Consumer who has logged-in with their credentials.
● RequestId: identification for the current transaction. If provided, the same value will be
present in the Response’s headers, if not, it will be auto-generated by our backend layer.
It is recommended that it is provided by the client.
● X-ASA-ApiVersion: version of the endpoint that’s expected to handle the current request.
If not provided, it will be defaulted to the oldest still-supported version for backwards
compatibility. In v0.0.5 it’s also accepted as ApiVersion.

2.9.1.2 Expected QueryString parameters

None.

2.9.1.3 Expected Body object parameters

None.

2.9.1.4 Result Body fields

● status: standard HTTP status code
● message: brief description of what has happened during the request and/or what this
response contains in the data object.
● reference: object with requestId and server timeStamp
● version: version number of the endpoint which actually produced this response
● data: array containing the list of currently active Transaction Categories, and for each an
object with the following key-value pairs:
○ category_id: integer - internal numeric ID for identifying this transaction
category
○ name: categoryName - human-readable name for this category
○ group: parentName - if this category has a parent, it’s name will be here,
otherwise an empty string

© ASA Technologies 2022. All rights reserved. Page 36 of 54

ASA Technologies ASA Open API Version 0.6

○ sub_categories: list - list with the names of all the children-categories of that
have this category as their parent, otherwise an empty list
○ hierarchy: list - if this category has any siblings (if other categories with the
same parent as this one exist), then a list of their names, otherwise null

2.9.1.5 Sample UAT Request

curl -X 'GET' \
'https://openapiuat.asacore.com/TransactionCategories \
-H 'accept: */*' \
-H 'Ocp-Apim-Subscription-Key: yourApimSubscriptionKeyHere' \
-H 'RequestId: 99999999' \
-H 'Authorization: bearer
yourBearerTokenFromLoginWithAsaOrRefreshTokenEndpointHere'

2.9.1.6 Sample UAT Response

{
"status": 200,
"message": null,
"reference": [
{
"requestId": "99999999",
"timeStamp": "2022-11-14T21:06:48.8848546+00:00"
}
],
"version": "0.0.5",
"data": [
{
"category_id": 1,
"name": "Bank Fees",
"group": "",
"sub_categories": [],
"hierarchy": null
},
{
"category_id": 2,
"name": "Donation",
"group": "",
"sub_categories": [],
"hierarchy": null
},

© ASA Technologies 2022. All rights reserved. Page 37 of 54

ASA Technologies ASA Open API Version 0.6

{
"category_id": 3,
"name": "Entertainment",
"group": "",
"sub_categories": [],
"hierarchy": null
},
...
]
}

© ASA Technologies 2022. All rights reserved. Page 38 of 54

ASA Technologies ASA Open API Version 0.6

2.10 Transactions
Endpoints for fetching the Transactions associated with the current Consumer’s accounts.

2.10.1 POST /Transactions

Searches the DB and related services for Transactions which comply with the given search
parameters in the request’s body.

2.10.1.1 Expected headers

● Ocp-Apim-Subscription-Key: Subscription key required in all endpoint calls in order for
access to be allowed by our API Management layer.
● Authorization: bearer token generated with the /Authentication/LoginWithASA endpoint
which serves as claim that the request which contains it is being made by a certain Fintech
on behalf of the Consumer who has logged-in with their credentials.
● RequestId: identification for the current transaction. If provided, the same value will be
present in the Response’s headers, if not, it will be auto-generated by our backend layer.
It is recommended that it is provided by the client.
● X-ASA-ApiVersion: version of the endpoint that’s expected to handle the current request.
If not provided, it will be defaulted to the oldest still-supported version for backwards
compatibility. In v0.0.5 it’s also accepted as ApiVersion.
● X-ASA-ConsumerCode: ASA-generated Id for the currently authenticated Consumer.
For backwards compatibility, in v0.0.5 this value is also accepted as ASAConsumerCode
in headers or as a Query String parameter.
● X-ASA-FintechCode: ASA-generated Id for the currently authenticated Fintech. For
backward compatibility, in v0.0.5 this value is also accepted as ASAFintechCode in
headers or as a Query String parameter.

2.10.1.2 Expected QueryString parameters

None (AsaConsumerCode and AsaFintechCode accepted as header alternative).

2.10.1.3 Expected Body object parameters

● options: optional, if defined it may contain:
○ account_ids: optional, if present it shall not be empty, list of ASA Account Ids to
limit search results
○ count: required if offset is defined, Page Size or the number of records per page
per account. If options is not defined, it defaults to 100.
○ offset: required if count is defined, Page Number (1-indexed) for paginating the
transactions returned per account. If options is not defined, it defaults to 1.
● client_id: optional, if defined it should match with the X-ASA-FintechCode
● access_token: optional, if defined it should match the X-ASA-ConsumerCode

© ASA Technologies 2022. All rights reserved. Page 39 of 54

ASA Technologies ASA Open API Version 0.6

● start_date: optional, the earliest date for which data should be returned (starting at
0:00:00 for the given date, time portion is discarded if defined)
● end_date: the latest date for which data should be returned (including whole date, time
portion is discarded if defined)
● categoryId: optional, Id of the Transaction Category to restrict the search results to,
CategoryIds can be obtained from the /TransactionCategories endpoint.
● transactionStatus: optional, Status Id to restrict the search. Accepted Values: 1-Pending,
2-Posted
● transactionType: optional, Type Id to restrict the search. Accepted Values: 1-Debit, 2-
Credit
● includeIgnoredTransactions: optional, whether to include Transactions marked as
“Ignored” in the DB, or not. If not provided, defaults to false.

2.10.1.4 Result Body fields

● status: standard HTTP status code
● message: brief description of what has happened during the request and/or what this
response contains in the data object.
● reference: object with requestId and server timeStamp
● version: version number of the endpoint which actually produced this response
● data: array containing a list of objects, one per requested account (or all accounts if
none where specified in filters), each of them contains the following key-value pairs:
○ request_id: number - same as reference’s requestId
○ account: object - contains the following account details:
■ account_id: accountNumber - ASA-generated account id
■ balances: object - abridged account balance response containing:
● available: double - numeric value of the account’s currently
available amount
● current: double - numeric value of the account’s currently
available amount
● limit: double - numeric value of the account’s limit
● isoCurrencyCode: USD - ISO Currency code for the account’s
currency
● unofficialCurrencyCode: USD - informal currency code for the
account’s currency
■ mask: integer - The last 2-4 alphanumeric characters of an account's
official account number. Note that the mask may be non-unique between an
Item's accounts, and it may also not match the mask that the bank displays to
the user.
■ name: accountName - name of the account
■ official_name: string - The official name of the account provided by the
financial institution

© ASA Technologies 2022. All rights reserved. Page 40 of 54

ASA Technologies ASA Open API Version 0.6

■ type: string - Possible values: Bank, Investment, Vehicle, Credit, Real

Estate, Stocks/Bonds, Jewelry or Other.
■ subtype: string - Possible values: Savings, Checking, IRA, 401k, Roth,
Cash, Other, Residential, Commercial, Land, Other, Auto, Boat, Plane, RV,
Motorcycle, ATV, Stocks, Bonds, Gold, Silver, Bullion, Coin, Watch, Ring,
Necklace, Line of Credit or Credit Card
■ verification_status: string - Verification status can be ‘Pending
Authentication’, ‘Authenticated’ or ‘Re-authenticate’
■ transactions: list - actual list of transaction objects (may be empty),
each of which being an object with the following key-value pairs:
● transaction_type: string - may be “Credit” or “Debit” currently
● transaction_id: string - ASA-generated id for each transaction,
comprised of numbers and hyphens
● account_owner: string - Consumer’s name
● pending_transaction_id: string - The ID of a posted transaction's
associated pending transaction, where applicable
● pending: bool - flag indicating whether this transaction is still
pending or not
● payment_channel: string - The channel used to make a payment.
○ online: transactions that took place online.
○ in store: transactions that were made at a physical
location.
○ other: transactions that relate to banks, e.g. fees or
deposits.
● payment_meta: string - Transaction information specific to inter-
bank transfers. If the transaction was not an inter-bank transfer, all
fields will be null.
● If the transactions object was returned by a Transactions endpoint
such as /transactions/get, the payment_meta key will always
appear, but no data elements are guaranteed. If the transactions
object was returned by an Assets endpoint such as
/asset_report/get/ or /asset_report/pdf/get, this field will
only appear in an Asset Report with Insights.
● name: string - The merchant name or could be the transaction
description
● merchant_name: string - Should be the merchant name
● location: string - The location of where a transaction occurred
● authorized_date: ISO-8601-date - date-only value for when this
transaction was authorized, if it already has
● authorized_datetime: ISO-8601timestamp - full timestamp for
when this transaction was authorized, if it already has

© ASA Technologies 2022. All rights reserved. Page 41 of 54

ASA Technologies ASA Open API Version 0.6

● date: ISO-8601-date - date-only value for when this transaction

was posted, aka “TransactionPostDate”
● datetime: ISO-8601timestamp - full timestamp for when this
transaction was posted, aka “TransactionPostDateTime”
● category_id: integer - id for this transaction’s Category as
matching with the values returned by the /TransactionCategories
endpoint, may be null
● category: string - name for this Transaction’s Category, defaults
to “General” if missing
● isoCurrencyCode: USD - ISO Currency code for the account’s
currency
● unofficialCurrencyCode: USD - informal currency code for the
account’s currency
● amount: double - numeric amount of this transaction. may be 0
● account_id: accountNumber - ASA-generated account id
● transaction_code: string - Transaction Type as defined by third
parties. Possible values: adjustment, atm, bank charge, bill
payment, cash, cashback, cheque, direct debit, interest, purchase,
standing order, transfer, null
● check_number: string - The check number of the transaction if a
check is processed
● personal_finance_category: TBD - Future Use
■ total_transactions: integer - count of all transactions that are ready to
be retrieved with the given filtering parameters in the Request body by
altering the count and or offset parameters
■ item: object - contains the following key-value pairs:
● item_id: TBD - Unique ID
● institution_id: integer - Institution ID associated with the Item
● webhook: string - The client URL designated to receive webhooks
● error: TBD - Any errors associated with the item
● available_products: TBD - TBD
● billed_products: TBD - TBD
● consent_expiration_time: TBD - TBD
● update_type: TBD - TBD

2.10.1.5 Sample UAT Request 1 (bare, no filtering)

curl -X 'GET' \
'https://openapiuat.asacore.com/Transactions' \

© ASA Technologies 2022. All rights reserved. Page 42 of 54

ASA Technologies ASA Open API Version 0.6

-H 'accept: */*' \
-H 'Ocp-Apim-Subscription-Key: yourApimSubscriptionKeyHere' \
-H 'X-ASA-ConsumerCode: theUsersASAConsumerCode' \
-H 'X-ASA-FintechCode: yourFintechCode' \
-H 'RequestId: 99999999' \
-H 'Authorization: bearer
yourBearerTokenFromLoginWithAsaOrRefreshTokenEndpointHere' \
-d '{}'

2.10.1.6 Sample UAT Request 2 (count, offset, date filtering)

curl -X 'GET' \
'https://openapiuat.asacore.com/Transactions' \
-H 'accept: */*' \
-H 'Ocp-Apim-Subscription-Key: yourApimSubscriptionKeyHere' \
-H 'X-ASA-ConsumerCode: theUsersASAConsumerCode' \
-H 'X-ASA-FintechCode: yourFintechCode' \
-H 'RequestId: 99999999' \
-H 'Authorization: bearer
yourBearerTokenFromLoginWithAsaOrRefreshTokenEndpointHere' \
-d '{
"options": {
"count": 1,
"offset": 1
},
"start_date": "2009-03-01T00:00:00.000Z",
"end_date": "2022-10-29T17:52:11.030Z",
"includeIgnoredTransactions": true
}'

2.10.1.7 Sample UAT Response

{
"status": 200,
"message": "Success",
"reference": [
{
"requestId": "99999999",
"timeStamp": "2022-10-14T16:36:37.7546127+00:00"
}
],

© ASA Technologies 2022. All rights reserved. Page 43 of 54

ASA Technologies ASA Open API Version 0.6

"version": "0.0.5",
"data": [
{
"request_id": "99999999",
"account": {
"account_id": "someAuthorizedAccountNumber",
"balances": {
"available": 4878.45,
"current": 4878.45,
"limit": 0,
"iso_currency_code": "USD",
"unofficial_currency_code": "USD"
},
"mask": null,
"name": " - SAVINGS",
"official_name": null,
"type": null,
"subtype": null,
"verification_status": null
},
"transactions": [
{
"transaction_type": "Credit (example)",
"transaction_id": "1234-5678-901234-56789-01234",
"account_owner": "theConsumersName",
"pending_transaction_id": null,
"pending": false,
"payment_channel": null,
"payment_meta": null,
"name": "Deposit Dividend 1.000%",
"merchant_name": "Deposit Dividend 1.000%",
"location": null,
"authorized_date": "2010-03-31",
"authorized_datetime": "2010-03-31T13:13:0.0+00:00",
"date": "2010-03-31",
"datetime": "2010-03-31T13:13:0.0+00:00",
"category_id": null,
"category": "General (example)",
"unofficail_currency_code": "USD",
"iso_currency_code": "USD",
"amount": 4.14,
"account_id": "someAuthorizedAccountNumber",
"transaction_code": "",

© ASA Technologies 2022. All rights reserved. Page 44 of 54

ASA Technologies ASA Open API Version 0.6

"check_number": null,
"personal_finance_category": null
},
...
],
"total_transactions": totalTransactionsInDataBase,
"item": {
"item_id": null,
"institution_id": null,
"webhook": null,
"error": null,
"available_products": null,
"billed_products": null,
"consent_expiration_time": null,
"update_type": null
}
},
...
]
}

© ASA Technologies 2022. All rights reserved. Page 45 of 54

ASA Technologies ASA Open API Version 0.6

3 Technical Implementation
This section provides a step-by-step guide for a FinTech to integrate with ASA OpenID
Authentication referred to as Login with ASA

3.1 FinTech Setup with ASA

The setup of a FinTech occurs during the discussion and contract phase with ASA. The items
below will all be addressed as part of the initial on-boarding of the FinTech Business to the ASA
Platform.
1. Register FinTech with ASA Financial.
2. Once the FinTech is registered with ASA,
a. ASA will provide a Subscription Key to the FinTech that is required for the FinTech
system to communicate with the ASA APIs.
i. The Subscription Key can be passed in the header as Ocp-Apim-
Subscription-Key
Or
ii. The Subscription Key can be passed as a parameter named subscription-
key
b. ASA will provide a FinTech Code
c. ASA will provide an Authorization Key for each FinTech application you want to
integrate to the ASA Platform
d. ASA provides a core ASA Authentication API URL specific for the Sandbox or
Production environments – see below

SANDBOX: https://openapiuat.asacore.com/Authentication

PRODUCTION: https://openapi.asacore.com/Authentication

3.2 Steps to Integrate: Login with ASA

1. The FinTech needs to integrate their application to the Login with ASA OpenID
Authentication. The FinTech will need to provide a Login with ASA Button Option within
their application to allow Consumers to select this as a login method.

Authorization Endpoint = {Base URL}/Authorization

2. The FinTech will initiate a Rest API call to the Authorization endpoint and include the
following parameters:

© ASA Technologies 2022. All rights reserved. Page 46 of 54

ASA Technologies ASA Open API Version 0.6

a. ASAFintechCode: Provided by ASA. This is the same as the Client ID within an Open ID
implementation.
b. AuthorizationKey: Provided by ASA. This is the same as the Client Secret within an Open
ID implementation.
c. ApplicationId: [Reserved]
d. RedirectURL: URL where the consumer shall be redirected to after successful
authentication. Fintech to provide this URL.
e. RedirectFailureURL: URL where the consumer shall be redirected to after failure of
authentication. Fintech to provide this URL.
f. Scope: provide “openid” as a value.
g. APIVersion: This is [Optional]. Defines which version of ASA OpenAPI you want to
connect to.
3. Once the request is authorized successfully, the user will be presented with the following
screen:

4. The user provides their username and password for log in

5. Once the login is successful, the user will be redirected back to the URL (RedirectURL) provided
by the FinTech
6. Response Parameters will be appended to the Redirect URL that can be used to enhance the
user experience with the FinTech
a. ASAConsumerCode – to be used within the FinTech app and also required to access any
financial data for the consumer
b. ASAFintechCode – Necessary to pass in request to ASA Connect or Open API
c. Bearer Token – to authorize the users session within the FinTech app
d. Token Expiry Date for the Bearer Token
7. If the login fails, the response will include the following and the user will be redirected to the
RedirectFailureURL

© ASA Technologies 2022. All rights reserved. Page 47 of 54

ASA Technologies ASA Open API Version 0.6

a. The Error Message filed will be updated

8. Once the user is logged in successfully, the bearer token is valid for 24hrs. You can refresh the
token using the refresh token API while the token is still valid. If the token has expired, then the
user will be requested to login again.

Refresh Token Endpoint = {Base URL}/RefreshToken

© ASA Technologies 2022. All rights reserved. Page 48 of 54

ASA Technologies ASA Open API Version 0.6

© ASA Technologies 2022. All rights reserved. Page 49 of 54

ASA Technologies ASA Open API Version 0.6

4 Appendix A: Acronyms, Abbreviations

& Definitions
Provide details of terms, acronyms, and abbreviations required to properly interpret this
document. This information may be provided by reference to the project’s Glossary

© ASA Technologies 2022. All rights reserved. Page 50 of 54

ASA Technologies ASA Open API Version 0.6

Term Meaning

Application Programming Interface, a way for two or more computer

API programs to communicate with each other. It is a type of software
interface, offering a service to other pieces of software.

Azure’s API Management layer which is comprised of: a Gateway to

APIM handle auth., routing, usage quotas, etc; a Portal for internal
management; and a Developer portal with technical details.

As endpoints mature over time, their changes may maintain backwards-

compatibility (i.e. a request which was working on it will continue to do
so after an update, and it will continue to reply with a compatible
Response as the one which was expected), meaning it doesn’t break
any implementation which currently depends on it. However sometimes
API Version a new version must be released that instead of replacing the currently-
supported version quietly, requires developers of products which use it
to increase the version number and adjust their application’s logic to fit
the new request and responses for this new version of the endpoint.
Older versions of endpoints may be maintained while still in use, but
should eventually be deprecated.

A software package meant to be installed on devices and run by users

Application
to fulfill a goal.

ASA-generated Id to identify an Application developed by a Fintech

ApplicationCode
which currently uses our OpenAPI services.

ASA Technologies
The company name on file that is doing business as ASA Financial
Inc

Process through which a system validates the identity of the person or

Authentication
system performing requests to it.

Process through which a system validates that the identified person or

Authorization system performing a request has been previously given enough
permissions to do so.

A Request Header expecting two values separated by a space: the first

Authorization
is the type of token that’s going to be provided (eg, “Bearer”) and the
Header
second is the actual token (eg: bearer tokens usually start with “ey…”)

© ASA Technologies 2022. All rights reserved. Page 51 of 54

ASA Technologies ASA Open API Version 0.6

Body Portion of a Request or Response which may contain complex data.

User that is accessing the FinTech Application and is also known as the
Consumer
Financial Institution Account Owner

ASA-generated Id for each Consumer which hides their identity to

ConsumerCode Fintech’s instead of showing them the user’s actual Id’s on an external
platform.

Financial Institution – A Bank, Credit Union, Financial Service Provider

FI
etc.

A company who utilizes ASA’s OpenAPI platform in order to access

Fintech
Consumer’s data.

FintechCode ASA-generated Id for a given Fintech.

Portion of a Request or Response which should contain a single key-

Header
value pair.

In the same way as an “ID” is an Identification Document which usually

has an unique number which identifies a person within a given context
Id
(eg, a Country), an “Id” (pronounced “ID”) is any code which uniquely
identifies an entity within a given context.

ISO Standard for formatting dates as string values as a year, followed

ISO-8601 by month, then day, then time with arbitrary precision and optionally UTC
timezone (e.g. 2022-10-14T16:58:37.7546127+03:00).

Protocol that allows a user to grant a third-party web site or application

access to the user's protected resources, without necessarily revealing
OAuth 2.0 their long-term credentials or even their identity.
Simply put - Provides the FinTech a way to authorize a consumer to
access the FinTech software

Open Compute Project, an initiative with the mission of applying the

OCP benefits of open source and open collaboration to hardware and rapidly
increase the pace of innovation in, near and around the data center

Ocp-Apim- Subscription key required in all endpoint calls in order for access to be
Subscription-Key allowed by our API Management layer.

© ASA Technologies 2022. All rights reserved. Page 52 of 54

ASA Technologies ASA Open API Version 0.6

A specification for machine-readable interface files for describing,

producing, consuming and visualizing RESTful web services. ASA’s
OpenAPI
OpenAPI project described in this document uses this standard format
to expose functionality to Fintechs.

Final portion of a Request’s URL which may contain parameters passed

Query String
as concatenated strings.

A “call” to a Service (which may be running in a physical Server or on a

Cloud) at a given URL; it’s usually sent alongside data packets known
Request as Headers, QueryStrings and Bodies which give further information to
the Service regarding how to interpret the Request and what is expected
from the caller.

Identification for the current transaction. If provided, the same value will
RequestId Header be present in the Response’s headers, if not, it will be auto-generated
by our backend layer. It is recommended that it is provided by the client.

The end product of a Request after it has finished, it may be as simple

as an HTTP Status code (eg, 200 for Success, 401 for Unauthorized
Error, 404 for Not Found) just indicating if the process that got triggered
Response
by the request was completed successfully or not, or it may contain
complex data as a result, oftenly shown to the User of an application in
some way.

A data object containing “claims” (eg, identification codes for the

Consumer and the Fintech operating on their behalf), which is encoded
Token as a long string of text usually starting with “ey” and then signed to
ensure who issued it, and/or encrypted to hide it’s contents to third
parties.

Uniform Resource Locator, is a string of characters which define where

URL to find and how to access a certain resource over the internet. They
begin with the protocol (eg HTTP, HTTPS, FTP…) and then an address.

We’re marking our custom, non-standard, headers with “X-ASA-” to

X-ASA-... prefixed
make a distinction and not to cause confusion with similarly-named
headers
headers which may already exist in the ecosystem.

© ASA Technologies 2022. All rights reserved. Page 53 of 54

ASA Technologies ASA Open API Version 0.6

5 Appendix B: Document changelog

Provide a brief summary of what has changed the since the last time this document was
updated

Term Meaning

Amending Transaction Type Code in the Transactions endpoint after

v0.6.1
bugfixes.

Added explanations and working examples for all currently implemented

v0.6
endpoint’s Request and Responses.

Updated list of available endpoints and added descriptions for every

v0.5
Request field.

© ASA Technologies 2022. All rights reserved. Page 54 of 54