Integration guide [PayDirect]
Learn each step to integrate the PayDirect API.
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:
- Sign up in the sandbox environment and obtain your
client_id
andclient_secret
. You will need to register at least oneredirect_uri
. - Go to the PayDirect API section of the sandbox Console.
- Select Request access and wait for the email confirmation.
- 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:
- Go to PayDirect API in Console.
- Toggle your environment to Live in the top-right corner.
- Go to App settings.
- Copy the
client_id
. - 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
totruelayer.com
.
Updated 7 months ago