robintty / nordigenapiclient Goto Github PK

View Code? Open in Web Editor NEW

4.0 1.0 2.0 5.71 MB

A .NET client for https://gocardless.com/bank-account-data (formerly Nordigen API)

Home Page: https://robintty.github.io/NordigenApiClient/

License: MIT License

C# 100.00%

api client-library csharp dotnet nordigen banking

nordigenapiclient's Introduction

NordigenApiClient

This library provides a .NET client for the GoCardless Bank Account Data API (formerly Nordigen API). The following API endpoints are supported:

Token
Institutions
Agreements
Requisitions
Accounts

You can get started with the Quickstart Guide below or take a look at the full documentation. You can find the nuget package here.

Quickstart Guide

To get started install the package via the package manager:
```
Install-Package RobinTTY.NordigenApiClient
```

Next you need to create a new instance of the client:

using var httpClient = new HttpClient();
var credentials = new NordigenClientCredentials("my-secret-id", "my-secret-key");
var client = new NordigenClient(httpClient, credentials);

Then we need the list of banking institutions in your country (e.g. United Kingdom)

var institutionsResponse = await client.InstitutionsEndpoint.GetInstitutions(SupportedCountry.UnitedKingdom);
if (institutionsResponse.IsSuccess)
    institutionsResponse.Result.ForEach(institution =>
    {
        Console.WriteLine($"Institution: {institution.Name}, Id: {institution.Id}");
    });
else
    Console.WriteLine($"Couldn't retrieve institutions, error: {institutionsResponse.Error.Summary}");

Choose the institution your bank account is registered with and create a requisition for it:

// Use the id of the bank you want to connect to here (we acquired it in the last step)
var institution = "BANK_OF_SCOTLAND_BOFSGBS1";
var redirect = new Uri("https://where-nordigen-will-redirect-after-authentication.com");
var requisitionResponse = await client.RequisitionsEndpoint.CreateRequisition(institution, redirect);

if (requisitionResponse.IsSuccess)
{
    Console.WriteLine($"Requisition id: {requisitionResponse.Result.Id}");
    Console.WriteLine($"Start authentication: {requisitionResponse.Result.AuthenticationLink}");
}

else
    Console.WriteLine($"Requisition couldn't be created: {requisitionResponse.Error.Summary}");

You will now need to accept the end user agreement by following the authentication link you got in the last step. The authentication flow will roughly look like this:

Now that you have accepted the agreement we once again need to retrieve the requisition we created in step 4. This time the response will include the accounts you are now able to access.

var requisitionId = "your-requisition-id";
var accountsResponse = await client.RequisitionsEndpoint.GetRequisition(requisitionId);
if (accountsResponse.IsSuccess)
    accountsResponse.Result.Accounts.ForEach(accountId =>
    {
        Console.WriteLine($"Account id: {accountId}");
    });
else
    Console.WriteLine($"Accounts couldn't be retrieved: {accountsResponse.Error.Summary}");

Now you can retrieve details about your bank account and the balances/transactions using the account ID(s) we just acquired:

var accountId = "your-account-id";
var bankAccountDetailsResponse = await client.AccountsEndpoint.GetAccountDetails(accountId);
if (bankAccountDetailsResponse.IsSuccess)
{
    Console.WriteLine($"IBAN: {bankAccountDetailsResponse.Result.Iban}");
    Console.WriteLine($"Account name: {bankAccountDetailsResponse.Result.Name}");
}

var balancesResponse = await client.AccountsEndpoint.GetBalances(accountId);
if (balancesResponse.IsSuccess)
    balancesResponse.Result.ForEach(balance =>
    {
        var balanceAmount = balance.BalanceAmount;
        Console.WriteLine($"Type: {balance.BalanceType}");
        Console.WriteLine($"Balance: {balanceAmount.Amount} {balanceAmount.Currency}");
    });

var transactionsResponse = await client.AccountsEndpoint.GetTransactions(accountId);
if (transactionsResponse.IsSuccess)
    transactionsResponse.Result.BookedTransactions.ForEach(transaction =>
    {
        var transactionAmount = transaction.TransactionAmount;
        Console.WriteLine($"Remittance: {transaction.RemittanceInformationUnstructured}");
        Console.WriteLine($"Booking date:{transaction.ValueDate}");
        Console.WriteLine($"Amount: {transactionAmount.Amount} {transactionAmount.Currency}");
    });

That's it! You are now able to retrieve the account details, balances and transactions of your bank account. If you wanna learn more about this library please refer to the full documentation.

nordigenapiclient's People

Contributors

Stargazers

Watchers

Forkers

whippet71 gritse

nordigenapiclient's Issues

Improve compliance of CreateAgreement with API spec

Currently the class CreateAgreementRequest, which is used as a payload to create an end user agreement, has the required properties MaxHistoricalDays, AccessValidForDays, AccessScope and InstitutionId. The GoCardless documentation mentions that MaxHistoricalDays, AccessValidForDays and AccessScope are optional when sending the request. The class should be changed to respect the API spec and tests added to see if the actual behavior is as described in the documentation.

Add previously undocumented fields to models

Since the documentation moved to the GoCardless website the Swagger docs now contain the complete response models which contain some fields which aren't covered yet by the library. Like AccountDetails.OwnerAddressStructured or multiple fields in the Balance schema. These missing fields should be added.

RequisitionsEndpoint.GetRequisitions Results.Result is empty

GetRequisitions does not have a good result.

var req = await client.RequisitionsEndpoint.GetRequisitions(0, 100);
foreach (var item in req.Result.Results)
{
}

if you check:
req.Resoult.Count = 3
But
req.Result.Results = 0

I think this is a deserialization issue.

Unknown fields {'payments_enabled'} in payload (https://ob.nordigen.com/api/v2/institutions)

I think nordigen removed the "payments_enabled" in query string.

var query = new KeyValuePair<string, string>[] {new("country", country), new("payments_enabled", paymentsEnabled.ToString())};

We give back an error:

Unknown fields {'payments_enabled'} in payload

Would you remove from the querystring?

InstitutionsEndpoint.GetInstitutions - US is not a valid choice?

Hi - if I call the GetInstitutions with Country = US I get an error below.

according to this page https://bankaccountdata.gocardless.com/api/docs#/institutions/retrieve%20all%20supported%20Institutions%20in%20a%20given%20country United States of America should be country code US.

System.Runtime.Serialization.SerializationException
HResult=0x8013150C
Message=Deserialization failed, please report this issue to the library author: https://github.com/RobinTTY/NordigenApiClient/issues
The following JSON content caused the problem: {"country":{"summary":"Invalid country choice.","detail":"US is not a valid choice."},"status_code":400}
Source=RobinTTY.NordigenApiClient
StackTrace:
at RobinTTY.NordigenApiClient.Models.Responses.NordigenApiResponse2.<FromHttpResponse>d__13.MoveNext() at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task) at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task) at System.Runtime.CompilerServices.TaskAwaiter.ValidateEnd(Task task) at RobinTTY.NordigenApiClient.NordigenClient.<MakeRequest>d__262.MoveNext()
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at RobinTTY.NordigenApiClient.Endpoints.InstitutionsEndpoint.d__2.MoveNext()
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at System.Runtime.CompilerServices.TaskAwaiter`1.GetResult()

This exception was originally thrown at this call stack:
System.Text.Json.ThrowHelper.ThrowJsonException_DeserializeUnableToConvertValue(System.Type)
System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(System.Threading.Tasks.Task)
System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(System.Threading.Tasks.Task)
System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(System.Threading.Tasks.Task)
System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(System.Threading.Tasks.Task)

Inner Exception 1:
JsonException: The JSON value could not be converted to System.Collections.Generic.List`1[System.String]. Path: $.country | LineNumber: 0 | BytePositionInLine: 12.

Add unit tests for unsuccessful responses.

I should add unit tests that check for successful deserialization of error responses.

Integrate ability to check API rate limits

GoCardless is introducing API rate limits for account details, transactions, and balances. There should be an option to check for these limits.

See: https://bankaccountdata.zendesk.com/hc/en-gb/articles/11529584398236-Bank-API-Rate-Limits-and-Rate-Limit-Headers

Further CurrencyExchange issues

Further to issue #6 it appears that the CurrencyExchange can be returned as either an array or a single object! Using the latest version failed as my request for account transactions included the following JSON:
"currencyExchange": { "instructedAmount": { "amount": "3.35", "currency": "EUR" }, "sourceCurrency": "EUR", "exchangeRate": "1.1552", "unitCurrency": "GBP", "targetCurrency": "GBP" },

Furthermore, it also contained an InstructedAmount section which appears to be new. I will submit a pull request later

Error with CurrencyExchange deserialization

I'm using the AccountsEndpoint.GetTransactions(string id) function but it throws an exception:

System.Runtime.Serialization.SerializationException: Deserialization failed, please report this issue to the library author: https://github.com/RobinTTY/NordigenApiClient/issues
The following JSON content caused the problem:  [json]

System.Text.Json.JsonException: The JSON value could not be converted to RobinTTY.NordigenApiClient.Models.Responses.CurrencyExchange. Path: $.transactions.booked[2].currencyExchange | LineNumber: 0 | BytePositionInLine: 1084.

I don't want to post the whole json here since it contains all my bank transactions but I think this might be the part of the json that causes it:

"currencyExchange":[{"sourceCurrency":"USD","exchangeRate":"10.3373000","unitCurrency":"USD","targetCurrency":"SEK"}]

Unable to mock response classes

I'm currently trying to write some unit tests for a project that uses this library. I'd like to be able to mock the NordigenApiResponse<T1,T2> class, and check that my code responds to various response objects appropriately. However I can't do this as the class doesn't have an interface or public constructor/setters.

If this class could have an interface that would be great, although I'm open to other suggestions as to how this could be achieved.