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:

• Deposit funds into your account
• Make withdrawals

📘

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 set up 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
• Open-loop

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 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

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

Test and go live

To upgrade your account to the live environment:

1. Go to 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.