Name and age verification before payment

You can choose not to receive payments in your account if they don't meet certain age or name requirements.

TrueLayer can screen the name or date of birth of payers before a pay-in settles in your merchant account. If the payer's name provided in the user parameter doesn't match the remitter's account details, or they're under 18, the payment is sent back to the user.

This is an optional feature. If you're interested in enabling pre-settlement verification, please contact us or speak with your integration partner.

Before a payment from the user moves into your account, the money settles in a TrueLayer intermediary account. While in the intermediary account, TrueLayer checks the information associated with the user's bank account.

Because the check takes place while the money is in the TrueLayer intermediary account, there is no risk that a fraudulent payment (or a payment from an underage customer) will touch a bank account that you own. This reduces your liability and removes the 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.

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.

🚧

You can only use automatic payment verification for 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 only available for pay-ins to a merchant account, which have 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 requestTypePossible values and result
beneficiary.typeStringautomated: You must provide this value to enable verification for a payment.
beneficiary.remitter_nameBooleantrue: 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_birthBooleantrue: 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 remitter_date_of_birth. This means that the Payments API checks that:

  • 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.
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",
			"verification": {
				"type": "automated"
				"remitter_name": true
				}
			"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"
        }
    }
}
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",
			"verification": {
				"type": "automated"
				"remitter_date_of_birth": true
				}
			"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"
        }
    }
}

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 settled status.
  • 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.

Change the strictness of name-based verification

When you use name verification for a payment, we preprocess the account holder name provided from the remitter's bank for consistency. We then apply a name matching algorithm based on the Levenshtein distance.

You can configure how close a match you want between the name provided and the account holder name from the remitter's bank. Contact us if you want to change the strictness of the name matching algorithm.