PayDirect

Combine one-click registration with instant payments and withdrawals in one app with PayDirect.

❗️

This is a legacy product. The Payments API v3 is the latest version of the Payments API.

If you’re integrating with the Payments product for the first time, you must use v3. Legacy versions will not give you access to the latest product features we’re building, including Signup+.

Learn how to integrate with Payments API v3.

With TrueLayer's PayDirect solution, you can verify account ownership, and offer instant deposits and withdrawals to your users.

PayDirect combines open banking with the fastest payment rails, allowing you to accept open banking payments and to execute payments across the UK and Europe.

You can use PayDirect to:

📘

The PayDirect API is currently in beta. Contact us to learn more about how to integrate with PayDirect.

Supported countries

Check out the list of banks that support PayDirect in different countries.

Before you begin

To authenticate to our API, you will need your client_id and client_secret for the environment You can find these values in the Console.

Get your sandbox client_id in Settings. If you don't have your client_secret, reset it using the instructions in Console.

Follow our guide to setup Insomnia with our Insomnia collection. It contains sample requests so that you can start using the PayDirect API.

Get started

  1. Sign up in the sandbox environment and obtain your client_id and client_secret. You will need to register at least one redirect_uri.
  2. Go to the PayDirect section of the sandbox Console.
  3. Select the request access button and wait for the email confirmation.
  4. Configure your webhook_uri and public certificate in the settings.
  5. Create a client credentials grant to get a token to call the API.
  6. Use the PayDirect API to create deposits and withdrawals, and verify account ownership.

Set up API authentication

You must provide a valid bearer access token when calling the PayDirect API.

Use this request to get an access token:

curl -X POST \
    -d grant_type=client_credentials \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d scope=paydirect \
    https://auth.truelayer-sandbox.com/connect/token

You will receive a response as below:

{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "paydirect payments"
}

Use this token in a request to the authentication server to obtain a client credentials grant. You need to include this grant in the bearer token header when you make future requests.

curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     --data '{...}' \
https://paydirect.truelayer-sandbox.com/v1/users/deposits/create_deposit

Deposit funds into your account

You have different merchant accounts on your Console: one for each currency and payment rail we support (for example, EUR on SEPA, GBP on Faster Payments, and so on).

Accounts are funded by creating a deposit. Once they are settled, funds become available for withdrawal immediately.

Make withdrawals

You need funds in your account to create withdrawals. The PayDirect API supports two types of withdrawal:

Closed-loop withdrawal

With a closed-loop withdrawal, you can send funds to an account that your user has previously made a deposit from. By specifying a user_id and account_id, you can make sure that you are sending funds back to the original account, making it easier to meet any anti-money laundering (AML) obligations.

curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     -H "X-TL-Signature: ${signature}" \
     --data '{
        "user_id": "23608c08-7fad-4d54-8871-b888de1f4ac5",
        "account_id": "<UUID>"
        "transaction_id": "<UUID>",
        "beneficiary_reference": "Withdrawal 204",
        "currency": "GBP",
        "amount_in_minor": 10000
}' \
https://paydirect.truelayer-sandbox.com/v1/users/withdrawals

Open-loop withdrawal

With an open loop withdrawal, you can send funds to any account. This type of withdrawal is useful for sending funds to your bank account, or to a user's account that hasn't previously been used to deposit funds.

curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     -H "X-TL-Signature: ${signature}" \
     --data '{
        "transaction_id": "17feac47-9be9-4817-85f0-9d2a6849f2cd"
        "beneficiary_name": "John Smith",
        "beneficiary_iban": "GB33BUKB20201555555555",
        "beneficiary_reference": "Withdrawal 204",
        "currency": "GBP",
        "amount_in_minor": 10000,
        "context_code": "withdrawal"
}' \
https://paydirect.truelayer-sandbox.com/v1/withdrawals

Learn more about making withdrawals.

Receive webhooks

To receive webhooks, you'll need to add a webhook_uri to your Console. You can learn more in Webhook notifications.

X-TL-Webhook-Timestamp: 2020-05-18T10:17:52Z

{
    "event_type": "deposit_settled",
    "event_id": "61523b95-527a-431d-a1a6-94c5df6c2325",
    "event_schema_version": 1,
    "event_body": {
        "transaction_id": "5675c939-953b-40fc-84c4-b5c514a36927",
        "deposit_id": "84e76e9e-811a-4f02-9624-f808c5925bfb",
        "user_id": "bCc96bf3-788b-4266-92dc-77351b680ac5",
        "account_id": "5356e5af-7bf2-49a4-96b3-7fde5ec8ddfe",
        "settled_at": "2021-03-08T10:30:46Z",
        "amount_in_minor": 1,
        "currency": "GBP",
        "remitter_iban": "GB11CLRB04066200002723",
        "remitter_name": "JANE DOE"
    }
}

Set up automated account sweeping

You can set up automated sweeping to maintain a set maximum balance in your merchant accounts. We will move excess money into a preconfigured IBAN at regular intervals. The sweep target IBAN is validated and configured as part of the KYC onboarding process.

curl -X POST \
  -H "Authorization: Bearer $access_token" \
  -H "X-TL-Signature: $signature" \
  --data '{
    "currency": "GBP",
    "max_amount_in_minor": 100000,
    "frequency": "daily"
  }' \
  https://paydirect.truelayer-sandbox.com/v1/sweep

Instant guarantee

If this is enabled for your client_id, your SEPA Credit deposits settlement will be instantly guaranteed. This is subject to internal checks and capped to a daily amount limit per user.

To allow some flexibility in user experience, we have an endpoint that retrieves a given user’s current limits. This can be used as a soft check to determine whether we’re likely to give an instant guarantee for a payment or not.

When a deposit meets the criteria for an instant guarantee, the is_guaranteed boolean field will be set to true in the deposit_executed webhook payload and in a single deposit_details payload.

Test and go live

To upgrade your account to the live environment:

  1. Go to your Console > PayDirect API.
  2. Select the Go to live env button.
  3. Go to App settings.
  4. Copy the client_id.
  5. Contact our sales team and give them your live client_id.

Before you go live:

  • Make sure that PayDirect is enabled in your live Console.
  • Change the endpoint domain from truelayer-sandbox.com to truelayer.com.