Identity verification (KYC)

Depending on the payment, the payer may have to verify their identity before the transaction can be completed. The whole verification journey runs on the Lyzi payment gate: there is nothing to build on your side, and no personal document ever transits through your servers.

This page explains when a verification is triggered, what you can decide yourself, and how to follow the outcome.

When is a verification required?

A verification is triggered based on:

• the amount of the payment,

• the payment method chosen by the payer on the payment gate,

• the compliance profile agreed for your merchant account,

• and the amounts already paid by the same payer on your account over a rolling 24-hour window.

You never have to compute this yourself. The response of the request endpoint tells you, for the payment you have just created, what will be asked for each payment method. See Knowing what will be asked.

Verification levels

Level	Name	What the payer provides
0	Declarative information	First name, last name and postal address. No document.
1	Identity verification	Identity document and liveness check.
2	Full identity verification	Identity document, liveness check and proof of address.
3	Enhanced due diligence	Full verification plus a review of the origin of the funds.

Each additional level adds friction for the payer, and therefore has an impact on your conversion rate. Level 3 also includes a review step that is not instantaneous. Only require the level you actually need.

Knowing what will be asked

The response of the request endpoint contains a paymentChannelsConfig array. Each entry describes one payment method available to the payer, with three flags:

Flag	Meaning
persoInfoRequired	The payer will be asked for their declarative information (level 0).
kycRequired	The payer will have to complete an identity verification.
eddKycRequired	The payer will have to complete an enhanced due diligence verification.

"paymentChannelsConfig": [
    {
        "channelName": "binance",
        "persoInfoRequired": false,
        "kycRequired": false,
        "eddKycRequired": false
    },
    {
        "channelName": "crypto",
        "persoInfoRequired": true,
        "kycRequired": false,
        "eddKycRequired": false
    }
]

The flags may differ from one payment method to another for the same amount: the applicable limits are not the same for every method. The payer picks the method on the payment gate, which is why you get the full list.

Requiring a specific level

You can require a verification level for a given payment, whatever its amount, with the optional enforcedKycLevel field of the request endpoint.

Value	Effect
(omitted)	Default behaviour: the level is determined by the amount and your profile.
0	The payer's declarative information is always collected.
1	An identity verification is always required.
2	A full identity verification, with proof of address, is always required.
3	An enhanced due diligence verification is always required.

Requiring a full identity verification on a payment

const payment = await axios.post(`${BASE_URL}/confirm_conversion/request`,
  {
    amount: 49.90,
    fromAsset: "EUR",
    merchantIdentifier: collectorIdentifier,
    returnUrl,
    cancelUrl,
    webhookUrl,
    // Always ask this payer for a full identity verification,
    // even though the amount alone would not require one.
    enforcedKycLevel: 2,
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
      'x-api-secret': apiSecret,
    },
  },
);

enforcedKycLevel can only raise the requirement, never lower it. If the amount, the payment method or your compliance profile already call for a higher level, that higher level applies. Setting enforcedKycLevel: 1 on a large payment does not turn it into a light verification.

The value is set when the payment is created and applies for its entire lifetime. It is returned in the request and status responses, and it is reflected in the paymentChannelsConfig flags described above.

Typical uses: a category of goods or services for which your own compliance policy requires a verified identity, a first payment from a new customer, or a payer you want to verify before delivering.

Avoiding asking the payer twice

Pre-filling the payer's information

If you already know your customer's identity, send it in payerInformation when creating the payment. It covers the declarative information (level 0), which is then no longer requested on the payment gate. It never replaces an identity verification.

Re-using an existing verification

If your customers have already been verified on your side, an existing verification can be re-used instead of asking them again, through the kycInfo field of the request endpoint. This requires a prior agreement with Lyzi: contact your Lyzi representative to have the integration set up and your account authorised. Verification data sent without such an agreement is rejected with the KYC information is not valid error.

Following the outcome

A payment that is waiting for a verification does not reach the PAID status. It stays in its current status until the payer completes the verification, or until the payment window expires.

• Webhooks: subscribe to the kyc.* events to be notified of the progress and of the decision. See Webhooks.

• Status endpoint: the payment status can be polled at any time, as described in Integration with API.

An enhanced due diligence verification (level 3) includes a review step that may take longer than the payment session. Do not build your flow on the assumption that a payment completes within a few minutes when this level is required, and rely on the webhook or the status endpoint rather than on the payer coming back to your site.