> For the complete documentation index, see [llms.txt](https://docs.rafflex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rafflex.io/additional-settings/payouts/payouts-truelayer.md). # TrueLayer Connect TrueLayer so customers can verify their bank account and approved withdrawals are paid automatically, instead of you paying each one by hand. {% hint style="warning" %} Automatic payouts are currently in beta. If you would like to use them, or you do not see **Settings**, then **Payouts** in your admin panel, please contact Rafflex support. {% endhint %} This guide sets up **TrueLayer** as your automatic payout provider. If you have not chosen a provider yet, or want to know how automatic payouts work day to day, start on the [Payouts](/additional-settings/payouts.md) overview. *** ## Before you start You will need: 1. **A TrueLayer account.** Sign up with TrueLayer and complete any checks they ask for. Payouts cannot work until your TrueLayer account is approved. 2. **A funded merchant account.** TrueLayer pays your customers from your TrueLayer merchant account, so it must hold enough money to cover the withdrawals you pay. 3. **Your TrueLayer credentials.** You copy these from the [TrueLayer Console](https://console.truelayer.com), TrueLayer's own dashboard. We list exactly which ones below. 4. **A site that trades in pounds (GBP).** Bank verification and automatic payouts work with UK bank accounts only. Sites that use euros carry on paying withdrawals by hand. 5. **A few minutes to test.** Every new setup starts in **Test Mode**, so you can check the connection before any real money moves. *** ## Step 1: Open the Payouts settings 1. Log in to your Rafflex admin panel. 2. In the left menu, click **Settings**. 3. Open **Payouts**. 4. Set **Payout Provider** to **TrueLayer (Automatic)**. The **Provider Credentials** and **Payout Rules** sections appear, showing the TrueLayer fields. When you have finished making changes on this page, always click **Save Settings** at the bottom. *** ## Step 2: Enter your TrueLayer details You get all of these from the TrueLayer Console. All five are required, and Rafflex will not save the page until they are filled in. | Field | What to enter | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Client ID** | Your API client ID. In the TrueLayer Console, open **Settings**. | | **Client Secret** | Your API client secret, also under **Settings** in the Console. Keep this private. | | **Signing Key ID** | The ID of your request signing key. In the Console, open **Settings**, then **Signing Keys**. | | **Signing PEM Key** | Your signing private key, from the same **Signing Keys** area. Paste it in full, including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` lines. | | **Merchant Account ID** | The ID of the TrueLayer merchant account your payouts are paid from. | {% hint style="info" %} **About signing keys.** TrueLayer uses a signing key to confirm that payout requests really come from you. Both the **Signing Key ID** and the key itself relate to the **Signing Keys** area of the TrueLayer Console. The **Signing PEM Key** field needs the **private** key (an EC private key), never the public one. If TrueLayer set up your account for you, or you are not sure which key to use, ask your contact at TrueLayer for the key ID and private key. {% endhint %} Once you save, the **Client Secret** and **Signing PEM Key** are hidden. They show a green **Saved** label, and you can leave them blank on later saves to keep the current values. Only type in them again if you want to replace them. {% hint style="warning" %} **Seeing "Invalid signing PEM key"?** The key you pasted is not in the expected format, so nothing was saved. Copy the whole private key again, from the first `-----BEGIN` line to the last `-----END` line, and paste it in. A missing line or character at either end is the usual cause. {% endhint %} ### Use the right credentials for your mode TrueLayer gives you separate credentials for its sandbox (testing) and for live payments. Use your sandbox credentials while **Test Mode** is on, and swap them for your live credentials when you go live. Mixing them up will make the connection test fail. *** ## Step 3: Choose your payout rules These settings control when payouts run on their own and when you step in. You will find **Enable Automatic Payouts** and **Test Mode** in the **Provider** section, and the rest in **Payout Rules**. | Setting | Default | What it does | | --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Enable Automatic Payouts** | Off | The main on and off switch. While it is off, TrueLayer does nothing and you pay every withdrawal by hand. | | **Test Mode** | On | Uses the TrueLayer sandbox so no real money moves. Switch it off only when you are ready to go live. | | **Auto-Payout Max (GBP)** | 0 | The largest withdrawal that is paid automatically for a verified customer. Anything above it waits for you to approve it. Set it to **0** to approve every payout yourself. | | **Name Match Threshold (%)** | 70 | How closely the name on the customer's bank account must match the name on their Rafflex account for verification to pass. See below. | | **Retry Max Attempts** | 3 | How many times a failed payout can be sent again before it needs settling another way. Choose between 0 and 10. | | **Enable Manual Bank Details Fallback** | On | Lets customers type in their bank details by hand if they cannot verify their account. You then pay those customers the manual way. | {% hint style="info" %} Start with **Auto-Payout Max (GBP)** at **0**, or a small amount, while you get comfortable. You can still send any verified customer's withdrawal through TrueLayer with one click, using the **Process payout via TrueLayer** button on your **Withdrawals** page. {% endhint %} ### Name Match Threshold You do not have to change this. The default of **70** suits most sites, so you can leave it as it is. When a customer verifies their bank, TrueLayer compares the name on the bank account with the name on their Rafflex account and gives a match score. **Name Match Threshold (%)** is the lowest score you will accept. * Choose a number between **50** and **100**. * A higher number is stricter. The note on the page recommends **70 to 85**, depending on how cautious you want to be. * If genuine customers are often told their name does not match, try lowering it a little. If you want tighter checks, raise it. You can see each customer's score in their account, under **Management**, then **Users**, in the **Bank Verification** panel. Each setting is explained in more detail on the [Payouts](/additional-settings/payouts.md#payout-rules) page. *** ## Step 4: Test the connection The connection test only runs when your TrueLayer details are saved **and** **Enable Automatic Payouts** is on. Keep **Test Mode** on while you test. 1. Check that **Test Mode** is on and your **sandbox** credentials are entered. 2. Set **Auto-Payout Max (GBP)** to **0**, so nothing is paid on its own while you test. 3. Switch on **Enable Automatic Payouts**. 4. Click **Save Settings**. 5. Click **Test Provider Connection**, at the bottom of the page. A box appears with the result. It stays on screen until you close it. * The title reads **Connection OK** or **Connection Failed**. * **Mode** shows **Sandbox** while Test Mode is on, or **Production** when you are live. * Each check is listed with a tick or a cross: | Check | What it looks at | | --------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Configuration** | All the required details are filled in and automatic payouts are switched on. | | **PEM Key Format** | Your signing key looks complete. | | **SDK Client** | Rafflex can start a connection with TrueLayer using your details. | | **Merchant Accounts** | Rafflex can see your TrueLayer merchant accounts, and whether the **Merchant Account ID** you entered is one of them. | If anything fails: * **"TrueLayer is not fully configured."** One of the required fields is empty, or **Enable Automatic Payouts** is off. Fill in the missing detail, switch it on, save and test again. * **PEM Key Format** fails. Paste your **Signing PEM Key** again in full, including the first and last lines. * **SDK Client** or **Merchant Accounts** fails. Your credentials were not accepted. Check they all come from the same TrueLayer app, and that they match your mode (sandbox or live). {% hint style="warning" %} **Read the Merchant Accounts message, even when it has a tick.** If it says your configured merchant account was **not found in account list**, the connection works but your **Merchant Account ID** is wrong. Payouts will not work until you correct it. If it says **No merchant accounts found.**, check your TrueLayer account is fully set up. {% endhint %} {% hint style="warning" %} While **Enable Automatic Payouts** is on, your customers are offered **Verify Bank Account** on their **Payouts** page. In Test Mode this connects to the TrueLayer sandbox, not to real banks. Keep your testing short, ideally at a quiet time. If you are not going live straight away, switch **Enable Automatic Payouts** off again and click **Save Settings**. {% endhint %} *** ## Step 5: Go live When your test connection passes and you are happy with your settings: 1. Replace your sandbox credentials with your **live** TrueLayer credentials. 2. Switch **Test Mode** off. 3. Make sure **Enable Automatic Payouts** is on. 4. Choose your **Auto-Payout Max (GBP)**. 5. Make sure your TrueLayer merchant account holds enough funds. 6. Click **Save Settings**. 7. Click **Test Provider Connection** again. **Mode** should now show **Production**. Automatic payouts are now live. Customers can verify their bank on their **Payouts** page, and verified withdrawals at or below your **Auto-Payout Max (GBP)** are paid by TrueLayer. Everything else comes to you on the **Withdrawals** page. {% hint style="success" %} Before you finish, set a **Payout Alert Email** in **Settings**, then **Email**, so you hear about any payout that fails or gets stuck. See [Email Setup](/essential-settings/email-setup.md#payout-alert-email). {% endhint %} *** ## FAQ **Can I switch back to manual later?** Yes. Switch **Enable Automatic Payouts** off, or set **Payout Provider** back to **Manual / Bank Transfer**, and click **Save Settings**. You are then back to paying withdrawals by hand. **Will every withdrawal be paid automatically?** No. Only withdrawals from customers who verified their bank, at or below your **Auto-Payout Max (GBP)**. If you set the max to 0, you approve every payout yourself. **Why did a payout fail?** Open the request on your **Withdrawals** page and look at the **Failure Reason** in the **Payout** section. One possible reason is that your merchant account did not hold enough funds. If so, top it up, then click **Process payout via TrueLayer** to try again. The [Payouts](/additional-settings/payouts.md#a-payout-failed) page explains all your options. **What happens if a customer's bank details cannot be verified?** If you leave **Enable Manual Bank Details Fallback** on, the customer can enter their details by hand and you pay them the manual way. If you turn it off, only customers with a verified bank account can be paid. **Where do I look after payouts once they are running?** On the **Withdrawals** page, under **Management**. The [Payouts](/additional-settings/payouts.md#managing-automatic-payouts-day-to-day) page explains the extra columns, filters and buttons, and what to do if a payout fails or is returned.