Provide user details for single payments
Learn what user details you need to provide when you make a payment request.
When you create a single payment into your merchant account, you need to provide some details about your user as part of anti-money-laundering measures. The only exception to this is if you have a PISP license.
User details to collect
When you create a single payment, you provide user details as part of the user
object.
The available fields in the user
object are: id
, name
, email
, phone
, date_of_birth
andaddress
.
If the payment is into a TrueLayer merchant account or external account that you own, you must provide the following information about the payer in the user
object:
- The name of the payer, their given and family name.
- One of:
- The payer's email address.
- The payer's phone number.
Additional user details
If a transaction is flagged for a sanction or AML issue, TrueLayer makes a Request for Information (RFI) to collect the additional information needed for us to investigate.
To comply with sanction screening obligations, and to minimise the number of RFIs raised, you should also include user details for the additional date_of_birth
and address
fields in your single payment creation API requests.
How to provide details
The example request below shows a single payment creation request with the mandatory user detail objects name
and email
completed. You can see the name Remi Terr
and email [email protected]
included as part of the user
object.
This example also includes values for the address
and date_of_birth
objects to decrease the possibility of a RFI.
curl --request POST \
--url https://api.truelayer-sandbox.com/v3/payments \
--header 'Idempotency-Key: ff19fe25-2350-4ed9-a73b-249e58d54f71' \
--header 'accept: application/json; charset=UTF-8' \
--header 'content-type: application/json; charset=UTF-8' \
--data '
{
"payment_method": {
"type": "bank_transfer",
"provider_selection": {
"type": "user_selected",
"filter": {
"release_channel": "general_availability",
"customer_segments": [
"retail"
]
},
"scheme_selection": {
"type": "instant_only",
"allow_remitter_fee": false
}
},
"beneficiary": {
"type": "merchant_account",
"merchant_account_id": "AB8FA060-3F1B-4AE8-9692-4AA3131020D0"
}
},
"user": {
"address": {
"address_line_1": "1 Hardwick Street",
"city": "London",
"state": "London",
"zip": "EC1R 4RB",
"country_code": "GB"
},
"name": "Remi Terr",
"email": "[email protected]"
"date_of_birth": "1990-01-31"
},
"amount_in_minor": 100
}
'
Format of user details
When you include user details as part of your payment, ensure that the information you include in the objects matches the following formats:
email
: The email address must comply with RFC 2822. This meansemail
must be a valid email address composed of US ASCII characters excluding blank spaces,[
,]
, or\
, and must end in a domain.phone
: This should be in the format recommended by ITU. The country code of the number must be included, prefixed by+
.address
: Each of the objects within theaddress
object follow these rules:address_line1
: Description of the street address and house number, between 1 and 50 characters.address_line2
: Further details like building name or apartment number, between 1 and 50 characters.city
: Name of the city or locality, between 1 and 50 characters.state
: Name of the county, province or state, between 1 and 50 characters.zip
: ZIP or postal code, between 1 and 20 characters.country_code
: The two-letter country code.
Uses the ISO 3166-1 alpha-2 format.
Payment verification
TrueLayer can screen the name or date of birth of payers before a single payment settles in your account. If the payer's name doesn't match the account details, or they're under 18, the payment is rejected.
In this case, the payment is held in a suspense account and never reaches your account, so you don't need to manually screen and refund payments.

Payment verification occurs after a payment has been created and authorised by the user. If a payment doesn't pass verification, the funds are returned to the customer account.
If you are interested in enabling pre-settlement verification, please contact us or speak with your integration partner.
You can only use automatic payment verification for either name or date of birth for each payment, not both.
How to add verification to a payment
Before you can enable verification, you need to contact TrueLayer so it can be enabled for your merchant account. If TrueLayer hasn't enabled verification, adding it to a payment has no effect.
Verification is added for each payment as part of the beneficiary
object in the payment creation request. Verification is available only if you provide a value of merchant_account
for the beneficiary.type
object.
This table shows the objects you should complete when you enable verification and their possible values. You should only complete and provide either one of beneficiary.remitter_name
or beneficiary.remitter_date_of_birth
, as you can only verify based on one criterion for each payment.
Object in payment request | Type | Possible values and result |
---|---|---|
beneficiary.type | String | automated : You must provide this value to enable verification for a payment. |
beneficiary.remitter_name | Boolean | true : The Payments API checks that the user.name object matches the name associated with the remitter's payment account.false : The Payments API doesn't perform a name check. |
beneficiary.remitter_date_of_birth | Boolean | true : The Payments API checks the date of birth associated with the remitter's payment account is over 18 years old.false : The Payments API doesn't check the remitter's date of birth. |
In these two example payments, verification is enabled for remitter_name
and then remitter_date_of_birth
. This means that the Payments API checks:
- The remitter's name matches the one associated with the bank account for the first payment.
- The remitter is over 18 years old for the second payment.
curl --request POST \
--url https://api.truelayer-sandbox.com/v3/payments \
--header 'Idempotency-Key: ff19fe25-2350-4ed9-a73b-249e58d54f71' \
--header 'accept: application/json; charset=UTF-8' \
--header 'content-type: application/json; charset=UTF-8' \
--data '
{
"payment_method": {
"type": "bank_transfer",
"provider_selection": {
"type": "user_selected",
"filter": {
"release_channel": "general_availability",
"customer_segments": [
"retail"
]
},
"scheme_selection": {
"type": "instant_only",
"allow_remitter_fee": false
}
},
"beneficiary": {
"type": "merchant_account",
"merchant_account_id": "AB8FA060-3F1B-4AE8-9692-4AA3131020D0"
"verification": {
"type": "automated"
"remitter_name": true
}
}
},
"user": {
"name": "Remi Terr",
"email": "[email protected]"
"phone": "+441234567890"
"date_of_birth":"1990-01-31"
},
"amount_in_minor": 100
}
'
curl --request POST \
--url https://api.truelayer-sandbox.com/v3/payments \
--header 'Idempotency-Key: ff19fe25-2350-4ed9-a73b-249e58d54f71' \
--header 'accept: application/json; charset=UTF-8' \
--header 'content-type: application/json; charset=UTF-8' \
--data '
{
"payment_method": {
"type": "bank_transfer",
"provider_selection": {
"type": "user_selected",
"filter": {
"release_channel": "general_availability",
"customer_segments": [
"retail"
]
},
"scheme_selection": {
"type": "instant_only",
"allow_remitter_fee": false
}
},
"beneficiary": {
"type": "merchant_account",
"merchant_account_id": "AB8FA060-3F1B-4AE8-9692-4AA3131020D0"
"verification": {
"type": "automated"
"remitter_date_of_birth": true
}
}
},
"user": {
"name": "Remi Terr",
"email": "[email protected]"
"phone": "+441234567890"
"date_of_birth":"20-02-1991"
},
"amount_in_minor": 100
}
'
The results of payment verification
Payment verification occurs after the user authorises a payment, and before it reaches your account. This means minimal processing is required by you.
If a payment:
- passes verification, it arrives in your account with the same
settled
status it would have without verification. - fails verification, it fails with a status of
failed
and afailure_reason
ofverification_declined
.
Test payment verification in sandbox
In order to test payment verification in sandbox, you must contact us so we can enable the feature. In sandbox, you can only test remitter name verification, which should match the sandbox user, John sandbridge
.
Updated 17 days ago