Provide user information for payments

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.

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.

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.

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.

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.

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

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.

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.

Requests for information (RFIs)

Information required for each payment type

Single payments

Pay-ins to your merchant account

📘Pre-payment age or name verification

Payments to an external account

VRPs

Mandates with your merchant account as beneficiary

Mandates with an external account as beneficiary

Payouts

Closed-loop payouts

Open-loop payouts

Refunds

📘
Pre-payment age or name verification