TrueLayer.Client 2.0.0-beta4

TrueLayer.NET

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

The library currently supports .NET 10.0, .NET 9.0 and .NET 8.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.Client".
5. Click on the TrueLayer.Client 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 10.0/.NET 9.0/.NET 8.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");
        }
    },
    // For best performance and reliability we advise to cache the auth token
    authCachingStrategy: AuthCachingStrategy.InMemory)

}

Multiple TrueLayer Clients

Use keyed version of TrueLayer client (.NET 10.0/.NET 9.0/.NET 8.0):

.AddKeyedTrueLayer("TrueLayerGbp",
    configuration,
    options =>
    {
        // For demo purposes only. Private key should be stored securely
        var privateKey = File.ReadAllText("ec512-private-key.pem");
        if (options.Payments?.SigningKey != null)
        {
            options.Payments.SigningKey.PrivateKey = privateKey;
        }
    },
    authTokenCachingStrategy: AuthTokenCachingStrategies.InMemory)
.AddKeyedTrueLayer("TrueLayerEur",
    configuration,
    options =>
    {
        // For demo purposes only. Private key should be stored securely
        var privateKey = File.ReadAllText("ec512-private-key.pem");
        if (options.Payments?.SigningKey != null)
        {
            options.Payments.SigningKey.PrivateKey = privateKey;
        }
    },
    authTokenCachingStrategy: AuthTokenCachingStrategies.InMemory)

Use [FromKeyedServices()] attribute to retrieve keyed client

public GbpController([FromKeyedServices("TrueLayerGbp")]ITrueLayerClient trueLayerClient, ...
public EurController([FromKeyedServices("TrueLayerEur")]ITrueLayerClient trueLayerClient, ...

Or GetRequiredKeyedService

var GbpClient = ServiceProvider.GetRequiredKeyedService<ITrueLayerClient>("TrueLayerGbp");
var EurClient = ServiceProvider.GetRequiredKeyedService<ITrueLayerClient>("TrueLayerEur");

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 CreatePaymentMethod.BankTransfer(
                new CreateProviderSelection.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", "jane.doe@example.com", "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 Ok(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.Payouts.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.

Testing

This project includes two types of tests:

Unit Tests - Run standalone without external dependencies:

dotnet test test/TrueLayer.Tests/

Acceptance Tests - End-to-end integration tests that require TrueLayer sandbox credentials:

# Set credentials via environment variables
TrueLayer__ClientId=your_client_id TrueLayer__ClientSecret=your_client_secret dotnet test

# Or run all tests (will fail without credentials)
dotnet test

The acceptance tests make real HTTP calls to TrueLayer's sandbox APIs to validate the entire SDK against live services. See test/TrueLayer.AcceptanceTests/README.md for credential setup instructions.

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.

Contributing

Contributions are always welcome!

Please adhere to this project's code of conduct.

License

MIT