Documentation
Console

Integration guide [PayDirect]

Learn each step to integrate the PayDirect API.

Suggest Edits

This page explains the basics of how to integrate the PayDirect API. For more detailed information about signing requests, configuring deposits or withdrawals, and more, see the other pages in this section.

Prerequisites

To authenticate your requests to the PayDirect API, you need your client_id and client_secret for the environment you are using (live or sandbox). You can find these values 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.

Configure PayDirect in Console

Before you can use the PayDirect API, you must complete the following in Console:

  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 API section of the sandbox Console.
  3. Select Request access and wait for the email confirmation.
  4. Configure your webhook_uri and public certificate in Paydirect API > Settings.

Set up API authentication

Requests to the PayDirect API require a client credentials grant, which you can obtain by using a valid bearer access token.

Use this request to get the bearer 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 receive a response as below:

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

Then, use this access token in a request to the authentication server to obtain a client credentials grant. You need to include the grant in the bearer token header in 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 access to different merchant accounts in Console, one for each currency and payment rail we support (for example, euro on SEPA, sterling on Faster Payments, and so on).

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

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 comply with 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 define and select a webhook_uri to Console. Learn more about how to set up 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 certain maximum balance in your accounts. We will move excess funds into a pre-configured IBAN at regular intervals. The sweep target IBAN is validated and configured as part of the KYC onboarding process. Learn more about Automated account sweeping.

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 PayDirect API in Console.
  2. Toggle your environment to Live in the top-right corner.
  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:

  • Ensure that PayDirect is enabled the live environment in Console.
  • Change the endpoint domain from truelayer-sandbox.com to truelayer.com.

Updated 7 months ago