Provide end user information for payments
Include information about your remitter to comply with regulations and unlock new features.
When you create any payment or mandate, you need to include certain information about your user. Do this by filling out the user object inside a payment initiation request. Not every field is required, but we recommend supplying as many fields as you know for a customer.
The available fields to fill out in the user object are:
| Field | Description |
|---|---|
id | A unique ID associated with that remitter. On a first payment, you are unlikely to know this value. |
name | The remitter's name. |
email | The remitter's email address. |
phone | The remitter's phone number, including country code. |
address | An object that contains the remitter's living address. Includes fields for: - address_line1- address_line2- city- state (fill out with the same value as city if not applicable)- zip (or postcode)- country_code (2-letter country code: for the UK, this is GB) |
date_of_birth | The remitter's date of birth, in the format YYYY-MM-DD. |
political_exposure | Whether a user is politically exposed. Can be current (if they are) or none (if they aren't).If you leave this field blank or don't include it, this parameter defaults to none. |
This is an example of a user object with all fields included:
"user": {
"address": {
"address_line1": "40 Finsbury Square",
"address_line2": "The Gilbert",
"city": "London",
"state": "London",
"zip": "EC2A 1PX",
"country_code": "GB"
},
"id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c",
"name": "Remi Terr",
"email": "[email protected]",
"phone": "+447777777777",
"date_of_birth": "1990-01-31",
"political_exposure": "none"
}
}
Which fields are required?
To make a payment with the Payments API, you always need to pass a value for the name field and one of either email or phone inside the user object. However, we recommend that you pass values for every optional field inside user, including date_of_birth and address.
If a transaction is flagged for a sanction or AML issue, we may receive an RFI. This requires us to collect additional information needed for us to investigate. If you supply as much information as possible inside the user object (such as a date of birth and living address), we’re less likely to need to contact you to obtain this additional information.
Supply the id and political_exposure if you know them.
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.
Click to see a mandate creation request 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"
}
}
}
}
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.
Payouts
If you don't have a payment_source to use for a payout, you need to supply the account holder name and bank account details for the account that is receiving the payout.
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.
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"
}
}
Signup+ payments
If you are using Signup+, you collect bank-verified data about your user when they make their first payment. Because of this, you do not need to supply real user information for a first Signup+ payment.
Instead, we strongly recommend that you pass this placeholder data in the user object for Signup+ payments:
"user": {
"name": "signup",
"email": "[email protected]",
"phone": "+447777777777"
For more about creating a Signup+ payment, see our Signup+ integration guides for the UK and Finland.
Returning users
If you are using the web SDK, filling in the user object enables specific features for returning users that improve UX.
For returning users, Web SDK shows the last used saved account on the Pay button, with the option to switch to other saved accounts from a dropdown menu.
Updated about 1 month ago