README.md

TrueLayer Rust

Caution

This project is not officially supported or actively maintained by TrueLayer. Therefore, we strongly advise against using it to integrate the TrueLayer Payments API. For a reliable and up-to-date integration, please refer to our public API reference or our officially supported API client libraries.

Installation

Add the latest version of the library to your project's Cargo.toml.

[dependencies]
truelayer-rust = {git = "https://github.com/TrueLayer/truelayer-rust"}

Alternatively, you can use cargo-edit if you have it already installed:

cargo add truelayer-rust --git https://github.com/TrueLayer/truelayer-rust

Documentation

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

For the full API reference of this crate, go to Docs.rs.

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

Initialize TrueLayerClient

Create a new TrueLayerClient and provide your client ID and client secret.

use truelayer_rust::{TrueLayerClient, apis::auth::Credentials};

let tl = TrueLayerClient::builder(Credentials::ClientCredentials {
    client_id: "some-client-id".into(),
    client_secret: "some-client-secret".into(),
    scope: "payments".into(),
})
.with_signing_key("my-kid", private_key)
.build();

By default, a TrueLayerClient connects to the Live environment. To connect to TrueLayer Sandbox, use .with_environment(Environment::Sandbox).

Create a payment

let res = tl
    .payments
    .create(&CreatePaymentRequest {
        amount_in_minor: 100,
        currency: Currency::Gbp,
        payment_method: PaymentMethod::BankTransfer {
            provider_selection: ProviderSelection::UserSelected { filter: None },
            beneficiary: Beneficiary::MerchantAccount {
                merchant_account_id: "some-merchant-account-id".to_string(),
                account_holder_name: None,
                reference: None,
                statement_reference: None,
            },
        },
        user: User {
            id: Some(Uuid::new_v4().to_string()),
            name: Some("Some One".to_string()),
            email: Some("[email protected]".to_string()),
            phone: None,
        },
    })
    .await?;

println!("Created new payment: {}", res.id);

For more info on all the parameters necessary to create a new payment, please refer to the official TrueLayer docs.

Build a link to our Hosted Payments Page

let res = tl.payments.create(...).await?;

let hpp_link = tl.payments
    .get_hosted_payments_page_link(&res.id, &res.resource_token, "https://my.return.uri")
    .await;

println!("HPP Link: {}", hpp_link);

Listing Merchant Accounts

let merchant_accounts = tl.merchant_accounts.list().await?;
for merchant_account in &merchant_accounts {
    println!(
        "Merchant Account {}: Balance: {:.2} {}",
        merchant_account.id,
        merchant_account.available_balance_in_minor as f32 / 100.0,
        merchant_account.currency
    );
}

More examples

Look into the examples for more example usages of this library.

To run an example, use cargo run like this:

cargo run --example create_payment

Testing

Unit and integration tests

You can use cargo to run the tests locally:

cargo test

Acceptance tests

To execute tests against TrueLayer sandbox environment, you should set the below environment variables:

• ACCEPTANCE_TESTS_CLIENT_ID
• ACCEPTANCE_TESTS_CLIENT_SECRET
• ACCEPTANCE_TESTS_SIGNING_KEY_ID
• ACCEPTANCE_TESTS_SIGNING_PRIVATE_KEY
• ACCEPTANCE_TESTS_MERCHANT_ACCOUNT_ID

and finally run:

cargo test --features acceptance-tests

Acceptance tests are run automatically on every push to main.

Code linting

To enforce coding style guidelines the project uses rustfmt.

Bear in mind that the above checks are enforced at CI time, thus the builds will fail if not compliant.

Contributing

Contributions are always welcome!

Please adhere to this project's code of conduct.

License

MIT