truelayer / truelayer-dotnet

The official TrueLayer .NET library provides convenient access to TrueLayer APIs from applications built with .NET.

TrueLayer.NET

The official TrueLayer .NET client provides convenient access to TrueLayer APIs from applications built with .NET.

The library currently supports .NET Standard 2.1, .NET 5.0 and .NET 6.0.

Installation

Using the .NET Core command-line interface (CLI) tools:

dotnet add package TrueLayer.Client

Using the NuGet Command Line Interface (CLI)

nuget install TrueLayer.Client

Using the Package Manager Console:

Install-Package TrueLayer.Client

From within Visual Studio:

1. Open the Solution Explorer.
2. Right-click on a project within your solution.
3. Click on Manage NuGet Packages...
4. Click on the Browse tab and search for "TrueLayer".
5. Click on the TrueLayer package, select the appropriate version in the right-tab and click Install.

Pre-release Packages

Pre-release packages can be downloaded from GitHub Packages.

dotnet add package TrueLayer.Client --prerelease --source https://nuget.pkg.github.com/TrueLayer/index.json

More information on using GitHub packages with .NET.

Documentation

For a comprehensive list of examples, check out the API documentation.

Usage

Prerequisites

First sign up for a developer account. Follow the instructions to set up a new application and obtain your Client ID and Secret. Once the application has been created you must add your application redirected URIs in order to test your integration end-to-end.

Next, generate a signing key pair used to sign API requests.

To generate a private key, run:

docker run --rm -v ${PWD}:/out -w /out -it alpine/openssl ecparam -genkey -name secp521r1 -noout -out ec512-private-key.pem

To obtain the public key, run:

docker run --rm -v ${PWD}:/out -w /out -it alpine/openssl ec -in ec512-private-key.pem -pubout -out ec512-public-key.pem

Navigate to the Payments settings section of the TrueLayer console and upload your public key. Obtain the Key Id.

Configure Settings

Add your Client ID, Secret and Signing Key ID to appsettings.json or any other supported configuration provider.

{
  "TrueLayer": {
    "ClientId": "your id",
    "ClientSecret": "your secret",
    "UseSandbox": true,
    "Payments": {
      "SigningKey": {
        "KeyId": "85eeb2da-702c-4f4b-bf9a-e98af5fd47c3"
      }
    }
  }
}

Initialize TrueLayer.NET

Register the TrueLayer client in Startup.cs or Program.cs (.NET 6.0):

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)
{
    services.AddTrueLayer(configuration, options =>
    {
        if (options.Payments?.SigningKey != null)
        {
            // For demo purposes only. Private key should be stored securely
            options.Payments.SigningKey.PrivateKey = File.ReadAllText("ec512-private-key.pem");
        }
    });
}

Alternatively you can create a class that implements IConfigureOptions<TrueLayerOptions> if you have more complex configuration requirements.

Make a payment

Inject ITrueLayerClient into your classes:

public class MyService
{
    private readonly ITrueLayerClient _client;

    public MyService(ITrueLayerClient client)
    {
        _client = client;
    }

    public async Task<ActionResult> MakePayment()
    {
        var paymentRequest = new CreatePaymentRequest(
            amountInMinor: amount.ToMinorCurrencyUnit(2),
            currency: Currencies.GBP,
            paymentMethod: new PaymentMethod.BankTransfer(
                new Provider.UserSelected
                {
                    Filter = new ProviderFilter
                    {
                        ProviderIds = new[] { "mock-payments-gb-redirect" }
                    }
                },
                new Beneficiary.ExternalAccount(
                    "TrueLayer",
                    "truelayer-dotnet",
                    new AccountIdentifier.SortCodeAccountNumber("567890", "12345678")
                )
            ),
            user: new PaymentUserRequest("Jane Doe", "[email protected]", "0123456789")
        );

        var apiResponse = await _client.Payments.CreatePayment(
            paymentRequest,
            idempotencyKey: Guid.NewGuid().ToString()
        );

        if (!apiResponse.IsSuccessful)
        {
            return HandleFailure(
                apiResponse.StatusCode,
                // Includes details of any errors
                apiResponse.Problem
            )
        }

        // Pass the ResourceToken to the TrueLayer Web or Mobile SDK

        // or, redirect to the TrueLayer Hosted Payment Page
        string hostedPaymentPageUrl = _client.Payments.CreateHostedPaymentPageLink(
            apiResponse.Data!.Id,
            apiResponse.Data!.ResourceToken,
            new Uri("https://redirect.yourdomain.com"));

        return Redirect(hostedPaymentPageUrl);
    }
}

For more examples see the API documentation. Advanced customization options and documentation for contributors can be found in the Wiki.

Retrieve provider details

Inject ITrueLayerClient into your classes:

public class MyService
{
    private readonly ITrueLayerClient _client;

    public MyService(ITrueLayerClient client)
    {
        _client = client;
    }

    public async Task<ActionResult> GetProvider(string id)
    {
        var apiResponse = await _client.PaymentsProviders.GetPaymentsProvider(id);

        if (!apiResponse.IsSuccessful)
        {
            return HandleFailure(
                apiResponse.StatusCode,
                // Includes details of any errors
                apiResponse.Problem
            )
        }

        return OkObjectResult(apiResponse.Data.Id);
    }
}

For more examples see the API documentation. Advanced customization options and documentation for contributors can be found in the Wiki.

Make a payout

Inject ITrueLayerClient into your classes:

public class MyService
{
    private readonly ITrueLayerClient _client;

    public MyService(ITrueLayerClient client)
    {
        _client = client;
    }

    public async Task<ActionResult> MakePayout()
    {
        var payoutRequest = new CreatePayoutRequest(
            merchantAccountId: "VALID_MERCHANT_ID",
            amountInMinor: amount.ToMinorCurrencyUnit(2),
            currency: Currencies.GBP,
            beneficiary: new Beneficiary.ExternalAccount(
                "TrueLayer",
                "truelayer-dotnet",
                new SchemeIdentifier.Iban("VALID_IBAN")
            )
        );

        var apiResponse = await _client.Payments.CreatePayout(
            payoutRequest,
            idempotencyKey: Guid.NewGuid().ToString()
        );

        if (!apiResponse.IsSuccessful)
        {
            return HandleFailure(
                apiResponse.StatusCode,
                // Includes details of any errors
                apiResponse.Problem
            )
        }


        return Accepted(apiResponse.Data.Id);
    }
}

For more examples see the API documentation. Advanced customization options and documentation for contributors can be found in the Wiki.

Building locally

This project uses Cake to build, test and publish packages.

Run build.sh (Mac/Linux) or build.ps1 (Windows) To build and test the project.

This will output NuGet packages and coverage reports in the artifacts directory.

Library Documentation

The library API documentation is built using DocFx. To build and serve the docs locally run:

./build.sh --target ServeDocs

This will serve the docs on http://localhost:8080.

Contributing

Contributions are always welcome!

Please adhere to this project's code of conduct.

License

MIT

truelayer-dotnet's Issues

Set up Build script

https://github.com/benfoster/o9d-guard as an example

Improve account identifier handling

The varying schema per account identifier type is a pain to work with:

        public class AccountIdentifier
        {
            public AccountIdentifier(string type)
            {
                Type = type.NotNullOrWhiteSpace(nameof(type));
            }

            /// <summary>
            /// The type of account identifier
            /// </summary>
            public string Type { get; }
            
            /// <summary>
            /// 6 digit sort code (no spaces or dashes)
            /// </summary>
            public string? SortCode { get; set; }
            
            /// <summary>
            /// 8 digit account number
            /// </summary>
            public string? AccountNumber { get; set; }
            
            /// <summary>
            /// Valid International Bank Account Number (no spaces). 
            /// Consists of a 2 letter country code, followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN).
            /// </summary>
            public string? Iban { get; set; }
            
            /// <summary>
            /// Valid Basic Bank Account Number (no spaces). Consists of up to 30 alphanumeric characters, with a fixed length per country. 
            /// </summary>
            public string? Bban { get; set; }
            
            /// <summary>
            /// Valid Polish NRB (no spaces). Consists of 2 check digits, followed by an 8 digit bank branch number, and then by a 16 digit bank account number. 
            /// Equivalent to a Polish IBAN with the country code removed.
            /// </summary>
            public string? Nrb { get; set; }
        }

We could provide a factory method to map a generic number parameter to the correct property based on the type

Fix TrueLayer casing

We still have a bunch of file names with True_l_ayer

Benchmark Deserialize/SerializeAsync from/to stream

Remove `Functionality` from ApiClient

ApiClient is designed to be as agnostic as possible to the underlying APIs it calls. We currently pass a Functionality enum to support URI selection. This should be moved to the corresponding Client class so that we avoid having to change ApiClient every time we extend the SDK.

Test record and enum deserialization

Increase our test coverage around the testing of records (nullable fields) and enums (snake case, unmatched values etc.)

Implement auth token caching

We can implement token caching to avoid obtaining a token for every API call (which will also give Auth API a breather)

Register a dedicated Sandbox account for testing the SDK

Add Code of Conduct

Handle dynamic Payment request objects

A number of the payment request fields can be of differing types each with a unique set of fields. We can either adopt pseudo union types (class with every possible field) where this complexity leaks to the client of create static helpers / factories that leverage generic to handle the differing schemas.

I'd lean towards the latter as it's a better experience for the developer.

Review configuration against other APIs

We need to review whether the configuration is flexible enough to support all of TrueLayer's APIs. I know Payments and Data share the same Client ID/Secret but is it possible that these will conflict with other APIs (Pay Direct?).

It may be beneficial to model the configuration based on the feature:

{
    "TrueLayer": {
        "UseSandbox": true,
        "Payments": {
            "ClientId": "xxx"
        }
    }
}

Use constructor fields for required parameters

To avoid unintentional bad requests, we should use constructor parameters for any required fields on API Requests

Developer Guide

Target .NET Standard 2.1 and Net 5.0

Get Merchant Account

https://pay-api-specs.t7r.dev/mvp/#operation/get-operating-account

Add Currency helper/constants

ISO 4217

All internal types to be sealed

See https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-6/#peanut-butter

Use Shorthand project naming and namespacing rules

Sdk and Sdk.Tests. We can then set the root namespace to TrueLayer in the csproj.

Namespacing should then follow the functional area e.g. TrueLayer.Payments

Build and deploy DocFx docs

Current version requires mono to be installed

Complete remaining PayDirect features

• Full Deposit details schema (currently missing a few fields)
• Providers endpoint (see if we can leverage model from payments)
• Query transactions
• Webhook Payloads
• Set up or update automated account sweeping
• Get automated account sweeping details
• Disable automated account sweeping

SDK design guidelines

Covering:

• Use of records
  • Classes for request objects, or anything that is mutable
  • Records for response objects, or anything that is immutable
• When fields should be nullable, init, use of constructors
  • Constructors for any mandatory API fields (use acceptance tests to validate compatibility)
  • Fields should be null if they can be null / are optional
  • Use of nullable
  • Init should be used in cases for response objects where the field should be set on construction but we are using public setters (may not be necessary if we use shorthand record initialisers)
• When multiple types per file are allowed and impact on user experience
  • Multiple types per file can be used when the types are nested
  • Nested types can be used when the type is only ever used within the context of the parent type
  • To avoid naming conflicts when nesting types with properties e.g. you can use the Request or Response suffix for example, public AccountRequest Account {get;set;} equally a Details or Summary suffix may be fair.
  • In cases, where nested types are used within nested types, choose the depth that makes sense to preserve the heirarchy
  • If the type should be shared outside of the context of the top level type, it should be moved but note that this is a breaking change

• Naming conventions

• Record type constructor injection warning - tests should validate mapping
• Naming of request/response objects vs resources e.g. InitiateDepositRequest/Response vs Deposit
• When should an enum be used vs constants (e.g. strings on response - backwards compatibility)

Investigate on non-nullable props not initialized during deserialization.

Test what happens when a non-nullable prop inside a response record is not initialized during deserialization.

Enable nullable

One thing to consider is how we handle response fields that we know will never be null but still need to support deserialization and avoid the issues associated with using constructors.

References

• https://www.meziantou.net/csharp-8-nullable-reference-types.htm

Create Payout

https://pay-api-specs.t7r.dev/mvp/#operation/create-payout

List Merchant Accounts

https://pay-api-specs.t7r.dev/mvp/#operation/list-operating-accounts

Model not Models

This is just a nitpick (I blame MS for this one!) 😄

Add security policy

Naming changes

We've agreed that backend clients will be named "Libraries" rather than "SDKs". Given that Library is overly generic I would suggest the following:

• Assembly: TrueLayerSDK -> TrueLayer.Client

When referring to the library we called it the "TrueLayer .NET Client" or "TrueLayer Client" when the .NET is inferred.

ApiClient should be internal

Drop custom HttpClientFactory

If we're happy to target .NET Core 3.0 onwards we can leverage HttpClientFactory that is included in .NET Standard 2.1

Add Contribution Guidelines

https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors

Use Pascal Case for all Request/Response Properties

We should not be using snake_case properties as this goes against standard .NET Conventions. The JSON serialiser can handle snake case automatically and bind to Pascal Case properties.

Enable Sonar

Requires Java

Consolidate schemas shared by Payments API and PayDirect

• Account Types
• Remitter / Beneficiary
• Statuses
• Provider response

Clients should be lazily initialised

We will also need to move validation outside of the DI wireup as features that require specific options may not be used by the developer e.g. Payout signing key id

Fix Validation exception message generation

Remove Payments v1

Cache loaded signing certificate

For PayDirect we're loading the cert from a string on every signed request. This can be optimised.

Complete payments v2 flow

Missing steps:

• get payment status
• fetch providers list

Add UserAgent

Add the user agent

name: truelayer-sdk-net
version: The assembly version

Get Payout

https://pay-api-specs.t7r.dev/mvp/#operation/get-payout

Do we need separate auth client methods for each resource type?

e.g. GetPaymentToken?

Support Action<TrueLayerOptions>

Generally this provides a nicer developer experience than passing a new object

Abstract obtaining authentication tokens

For APIs leveraging client-credentials authentication, it should be possible to obtain these automatically on behalf of the developer without an explicit call. We can also implement token caching to avoid obtaining a token for every API call (which will also give Auth API a breather)

Resources

• https://identitymodel.readthedocs.io/en/latest/aspnetcore/worker.html
• https://leastprivilege.com/2020/05/18/automatic-token-management-for-asp-net-core-and-worker-services-1-0/

Certificate handling

https://www.scottbrady91.com/C-Sharp/PEM-Loading-in-dotnet-core-and-dotnet

GitHub Actions / CI

Set up build script to run on GitHub actions. Probably worth waiting to move the repo since it will require the setup of secrets etc.

Implement http error handling

We should find a way to handle errors coming from TL apis.
The following code is commented out at the moment. You can find it here.

var content = await httpResponse.Content.ReadAsStringAsync();
if (httpResponse.StatusCode == Unprocessable)
{
    var error = await DeserializeJsonAsync<ErrorResponse>(httpResponse);
    throw new TruelayerValidationException(error, httpResponse.StatusCode, requestId);
}

Build SingleImmediatePaymentInitiationRequest dynamically

V2 payment initiation has request parameters hardcoded. Make it dynamic and test it.

Namespace/assembly name alignment

Namespaces: TrueLayer.X
Assembly: TrueLayerSdk

URLs should be configurable

It should be possible to override URLs, specifically so that we can test the SDK against other environments.