Provide user details for single payments

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_birthandaddress.

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 means email 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 the address 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.

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.

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 a failure_reason of verification_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.