Provide user information for payments
Learn what details you must provide with your payments to help prevent crime.
If you don't have your own PISP license, TrueLayer provides payment initiation services (PIS) on your behalf. For this to happen, you must provide certain user details with each payment you create with the Payments API. These details are used as part of anti-money-laundering (AML) measures.
The user information that you need to provide, and the method you use to provide it, varies based on the type of payment. You need to include user information with every payment request: this includes supplying the same details if a user makes a payment twice.
This page contains:
- an explanation of RFIs and why user information is necessary
- a table containing an overview of what information is required for each payment type
- a more detailed explanation of the information required for each payment type, with examples
We provide an overview of the information required on this page. There's more detailed guidance in the documentation for each payment type.
Requests for information (RFIs)
As a regulated financial/payment institution, TrueLayer has a regulatory requirement to screen transactions to or from TrueLayer merchant accounts against sanctions lists. The requirement applies to all transactions by clients who are not fully regulated and authorised to provide financial services in the UK or EU.
TrueLayer double-checks transactions made by end users whose name matches an individual on a sanction list. This prevents transactions that could be related to money laundering or sanctioned individuals.
If a transaction is flagged for a sanction or AML issue, TrueLayer makes an RFI to collect the additional information needed for us to investigate.
Where sanction screening applies (every transaction to or from a TrueLayer merchant account), you should provide the following extra information on the end users:
- Date of birth
- Address
Information required for each payment type
The information that you need to provide in your payment requests change depending on the payment type. As a general rule, you need to include the user's name, and one of either their email address and phone number.
However, for some payment types, we recommend that you also include the user's address and date of birth to reduce the possibility that we contact you to request additional information.
| Payment type | Mandatory user information | Recommended user information to reduce number of RFIs |
|---|---|---|
| Merchant account pay-in | - Name At least one of: - Email address - Phone number | - Date of birth - Address |
| External account payment | - Name At least one of: - Email address - Phone number | |
| VRP mandate (merchant account beneficiary) | - Name At least one of: - Email address - Phone number | - Date of birth - Address |
| VRP mandate (external account beneficiary) | - Name At least one of: - Email address - Phone number | |
| Closed-loop payout | None | |
| Open-loop payout | None (already collected by default) | - Date of birth - Address |
| Refunds | None |
Single payments
When you create a single payment with the Payments API, provide user information as part of the user object in the payment creation request.
The available fields in the user parameter are the user's id, name, email, phone, date_of_birth and address.
Single payments can be made to:
Pay-ins to your merchant account
In a pay-in to your merchant account, you must provide the user's name and at least one of their email and phone. We also recommend you include their date_of_birth and address.
Click to see an example of a pay-in to a merchant account with user information
In this example, the user's name Jonathan Sandbridge is provided, along with their email address and phone number. Their date of birth and address are also included to reduce the chance of an RFI being raised.
POST /v3/payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: {RANDOM_UUID}
Tl-Signature: {SIGNATURE}
Authorization: Bearer {ACCESS_TOKEN}
Host: api.truelayer-sandbox.com
{
"amount_in_minor": 30000,
"currency": "GBP",
"payment_method": {
"provider_selection": {
"type": "preselected",
"scheme_selection": {
"type": "user_selected",
"allow_remitter_fee": false
},
"provider_id": "mock-payments-gb-redirect",
"remitter": {
"account_holder_name": "John Sandbridge",
"account_identifier": {
"type": "sort_code_account_number",
"sort_code": "040668",
"account_number": "00000871"
}
}
},
"type": "bank_transfer",
"beneficiary": {
"type": "merchant_account",
"merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
}
},
"user":
{
"id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
"name": "Jonathan Sandbridge",
"email": "[email protected]",
"phone": "+447809123456",
"date_of_birth": "1992-11-28",
"address":
{
"address_line1": "40 Finsbury Square",
"city": "London",
"state": "London",
"zip": "EC2a 1PX",
"country_code": "GB"
}
}
}
Pre-payment age or name verification
If your application requires it (for example, if you sell age-restricted products), TrueLayer can check the name or date of birth of a payer before a payment settles.
This means a payment from sanctioned parties never settle in your account in the first place, as opposed to being initiated and immediately returned. Learn how to enable name or age verification.
Payments to an external account
In a payment to an external account, you must provide the user's name and at least one of their email and phone.
Click to see an example of a payment to an external account with user information
In this example, the user's name Jonathan Sandbridge is provided, along with their email address and phone number.
POST /v3/payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: {RANDOM_UUID}
Tl-Signature: {SIGNATURE}
Authorization: Bearer {ACCESS_TOKEN}
Host: api.truelayer-sandbox.com
{
"amount_in_minor": 1,
"currency": "GBP",
"payment_method": {
"provider_selection": {
"filter": {
"countries": [
"GB"
],
"release_channel": "general_availability",
"customer_segments": [
"retail"
],
"provider_ids": [
"mock-payments-gb-redirect"
],
"excludes": {
"provider_ids": [
"ob-exclude-this-bank"
]
}
},
"type": "user_selected"
},
"type": "bank_transfer",
"beneficiary": {
"type": "external_account",
"account_holder_name": "Beneficiary Name",
"reference": "RefTest",
"account_identifier": {
"type": "sort_code_account_number",
"sort_code": "123456",
"account_number": "12345678"
}
}
},
"user":
{
"id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
"name": "Jonathan Sandbridge",
"email": "[email protected]",
"phone": "+44123456789"
}
}
VRPs
When you create a mandate with Payments v3, you provide user information as part of the user parameter in the payment creation request. Like in single payments, the available fields for the user object are a user id, name, email, phone, date_of_birth and address.
Mandates can be made to pay either your TrueLayer merchant account, or another external account.
Mandates with your merchant account as beneficiary
In mandate creation with your merchant account as the beneficiary, you must provide the user's name and at least one of their email and phone. We also recommend you include their date_of_birth and address.
Click to see the creation request for a mandate to a merchant account with user information
In this example, the user's name Jonathan Sandbridge is provided, along with their email address and phone number. Their date of birth and address are also included to reduce the chance of an RFI being raised.
This request also includes the user's name in the optional remitter object, which simplifies the user flow for authorising a mandate.
POST /v3/mandates HTTP/1.1
Content-Type: application/json
Idempotency-Key: {RANDOM_UUID}
Tl-Signature: {SIGNATURE}
Authorization: Bearer {ACCESS_TOKEN}
Host: api.truelayer-sandbox.com
{
"mandate": {
"type": "sweeping",
"provider_filter": {
"countries": [
"GB"
],
"release_channel": "general_availability"
},
"provider_selection": {
"type": "preselected",
"provider_id": "ob-natwest-vrp-sandbox",
"remitter": {
"account_identifier": {
"type": "sort_code_account_number",
"account_number": "12345601",
"sort_code": "500000"
},
"account_holder_name": "Jonathan Sandbridge"
}
},
"beneficiary": {
"type": "merchant_account",
"merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57",
"account_holder_name": "Test merchant account"
}
},
"currency": "GBP",
"user": {
"id": "8e62184f-e800-47e9-aef0-224b8fa52769",
"name": "Jonathan Sandbridge",
"email": "[email protected]",
"phone": "+441234567890",
"date_of_birth":"1992-11-28",
"address":
{
"address_line1": "40 Finsbury Square",
"city": "London",
"state": "London",
"zip": "EC2a 1PX",
"country_code": "GB"
}
},
"constraints": {
"valid_from": "2024-02-26T17:47:07.443Z",
"valid_to": "2025-01-01T00:00:00.000Z",
"maximum_individual_amount": 50,
"periodic_limits": {
"day": {
"maximum_amount": 100,
"period_alignment": "calendar"
},
"month": {
"maximum_amount": 1000,
"period_alignment": "calendar"
}
}
}
}
Mandates with an external account as beneficiary
In mandate creation with an external account as the beneficiary, you must provide the user's name and at least one of their email and phone.
Click to see the creation request for a mandate to an external account with user information
In this example, the user's name Jonathan Sandbridge is provided, along with their email address and phone number.
POST /v3/mandates HTTP/1.1
Content-Type: application/json
Idempotency-Key: {RANDOM_UUID}
Tl-Signature: {SIGNATURE}
Authorization: Bearer {ACCESS_TOKEN}
Host: api.truelayer-sandbox.com
{
"mandate": {
"type": "sweeping",
"provider_filter": {
"countries": [
"GB"
],
"release_channel": "general_availability"
},
"provider_selection": {
"type": "user_selected"
},
"beneficiary": {
"type": "external_account",
"account_holder_name": "Beneficiary Name",
"account_identifier": {
"type": "sort_code_account_number",
"sort_code": "123456",
"account_number": "12345678"
}
}
},
"currency": "GBP",
"user": {
"id": "8d060765-6d00-470e-9fd7-ff87388b4768",
"name": "Jonathan Sandbridge",
"email": "[email protected]",
"phone": "+441234567890"
},
"constraints": {
"valid_from": "2024-02-27T10:12:52.929Z",
"valid_to": "2025-01-01T00:00:00.000Z",
"maximum_individual_amount": 50,
"periodic_limits": {
"day": {
"maximum_amount": 100,
"period_alignment": "calendar"
},
"month": {
"maximum_amount": 1000,
"period_alignment": "calendar"
}
}
}
}
Payments over a mandate
When you create a payment over a mandate, you don't need to provide user information, as you collected this when you created the mandate and the user authorised it. This applies to both pay-ins to a merchant account and payments to an external account, given they're made over a mandate.
Payouts
Payouts are payments that are made from your account to a user's account. There are two types of payout:
- closed-loop, which is made to the account of someone who has already paid you
- open-loop, which is made to an account that is unknown to you
In addition, you can also make refunds to the account of someone who has already paid you.
Closed-loop payouts
A closed-loop payout is a payout made back to the account of someone who has paid you before. In the payout request, the account that made the original payment is identified using the payment_source value.
As user details were already collected in the initial single payment, you do not need to collect user details for a closed-loop payout.
Open-loop payouts
When you create an open-loop payout, beneficiary.account_holder_name and beneficiary.account_identifier are mandatory parameters. This means that you are already providing some user information by default to create the payout.
However, to comply with sanction screening obligations, and to minimise the number of RFIs raised, you should also include user details for the additional beneficiary.date_of_birth and beneficiary.address fields in your open-loop payout API requests.
Click to an open-loop payout creation request with user information in the beneficiary object
In this example, an open-loop payout is made to Jonathan Sandbridge, as specified in beneficiary.account_holder_name. Their address and date of birth are provided in the appropriate parameters within the beneficiary parameter.
POST /v3/payouts HTTP/1.1
Content-Type: application/json
Idempotency-Key: {RANDOM_UUID}
Tl-Signature:{SIGNATURE}
Authorization: Bearer {ACCESS_TOKEN}
Host: api.truelayer-sandbox.com
{
"merchant_account_id": "2a485b0a-a29c-4aa2-bcef-b34d0f6f8d51",
"amount_in_minor": 1,
"currency": "GBP",
"beneficiary": {
"type": "external_account",
"account_holder_name": "Jonathan Sandbridge",
"account_identifier": {
"type": "sort_code_account_number",
"sort_code": "040668",
"account_number": "00000871"
},
"reference": "TestCo-627364",
"address": {
"address_line1": "40 Finsbury Square",
"state": "London",
"city": "London",
"country_code": "GB",
"zip": "EC2A 1AE"
},
"date_of_birth": "1990-01-31"
}
}
Refunds
A refund is a payment made back to an account based on the payment_source of an initial single payment.
As user details were already collected in the initial single payment, there's no requirement to collect user details for a refund.
Updated 5 months ago