Integration with API

Resources

• Doc générale

• Lyzi API documentation

Introduction

To accept a cryptocurrency payment using Lyzi, two methods are available:

A. Link the payment to a “Payment Button”

B. Link the payment to a collector / salespoint.

The philosophy of those two methods is to use:

A. Payment Button for online payments, in e-commerce websites, whereas

B. ”Payment link” is more meant to be used for a in-store payment.

That being said, there is no strict limitation about using one or the other.

	A. Payment Button	B. Collector payment
Ideal for	eShop payments	Payment link for a salespoint
Requires:	A payment button
(from the API)	One salespoint and one collector are configured

Preliminary

To integrate Lyzi payment - in store or online - a “manager” account shall be created and approved by our compliance team (KYB process). Once this process is completed, the manager has full access to his backoffice, under https://admin.lyzi.io/. In there, the manager can create buy buttons, payment links, configure his salespoint, payment collectors and option cashier accounts.

For testing purposes, a sandbox environment is also available and can be explored under https://admin-dev.lyzi.io/. Here are shared credentials to test the integration:

User : [e-mail]

Pass: Lyzi123,

Security

The following authorizations must be added in the header of the requests to Lyzi API:

 'x-api-key': apiKey,
 'x-api-secret': apiSecret,

The key and the secret can be found in the backoffice, in the “developer” section.

Return/callback URL

When integrating Lyzi payments, you need to handle two separate flows: front-end redirection for user experience, and back-end webhook for reliable transaction verification. Correctly distinguishing these ensures smooth UX and secure payment validation.

Front-end (redirection)

• returnUrl and cancelUrl are client-side redirection URLs.

• Lyzi opens the appropriate URL in the user’s browser after the payment completes (success → returnUrl, failure → cancelUrl).

• Use these only for UX changes and client-side confirmation.

• Do not rely on them for final payment validation.

Back-end (webhook)

• webhookUrl is the webhook endpoint. Lyzi sends a server-to-server POST to this URL with the transaction result.

• Your backend must accept and validate POST requests from Lyzi.

Combined behaviour

• If only webhookUrl is provided: Lyzi uses it as the webhook and will open it in the browser as a redirect (acts as return/cancel fallback).

• If returnUrl/cancelUrl are provided: browser redirection uses those URLs. If webhookUrl is also provided Lyzi still sends the webhook POST to webhookUrl.

Always treat the webhook (callbackUrl) as the authoritative notification and validate the transaction via the Check Status endpoint on your server. Do not mark orders as paid based solely on front-end redirection or query parameters. Always confirm final status with the Check Status API.

A. Buy button

As mentioned in the introduction, this approach is recommended for integration in online stores or applications.

1. Create the buy button

Before integrating the Lyzi payment solution on your website or application, you shall create a “Payment Button” from your backoffice.

First, make sure that your account has been created and that the KYB is done and confirmed. If you don’t have an account, go to https://admin.lyzi.io/onboarding and complete all the information of your profile.

Then, let’s create a payment button. Go to the backoffice and find the buy button section:

Fill the information of the button, and create it.

As annoted in the picture, here are the information about the button:

1. Name : The name of the button for you to organize the created buttons. This is not published to the consumer.

2. Website URL : the website URL shown in the payment gate, to indicate to the consumer what website he is performing the payment for.

3. Webhook URL : The website for the redirection of the user after the payment (successfull or failed)

4. Name of the product : The name of the product that is being purchased. This is displayed in the payment gate to the consumer.

Note that most of this information can be and will be edited during the payment initialization, when doing the integration in your application.

Once created, you can select the button that has been created and click on “Display” :

2. Initiate the payment

In your application, we are going to use the buy button created in the previous section, customize its parameters and initiate the payment.

The simplest way to initiate a payment, based on this buy button, is to build the following URL, with the appropriate parameters :

// This is the base URL for the payment using the button
const url = new URL("<https://pay.lyzi.io/buy-button/landing>");

// Set the query parameters
// - The ID of the button that has been created in the previous section
url.searchParams.append('id', buttonId;
// - The price of the payment to perform, as a string
url.searchParams.append('price', amount.toString());
// - The currency of the payment to perform, as a string. Only EUR, CHF and XPF are currently supported (as of 2025 Jan 1st)
url.searchParams.append('currency', "EUR");
// - The callback URL where the payment confirmation request will be POST'ed
url.searchParams.append('callbackUrl', callbackUrl);
// - The return URL, where the use will be redirected when the payment is completed and successfull
url.searchParams.append('returnUrl', returnUrl)
// - The return URL, where the use will be redirected when the payment is failed
url.searchParams.append('cancelUrl', cancelUrl)

// User can now be redirected to this URL, or a QR code can be built and shown to the user
router.push(url.toString())
// This will take the customer to the Lyzi Payment gate for him to perform the payment in cryptocurrencies

And voilà 💫 Just by a couple of lines, the payment url can be built and the user can be redirected to the payment gate to complete the payment.

Alternatively, the SDK can also be used to have more coding tool to intiate the payment:

B. Direct payment

Preliminary

The direct payment is used to link a payment to a collector, which is related to a salespoint. Before initiating the payment, the ID of the collector must be found.

Make sure that a collector has been created. Using the API or the backoffice :

Collector creation using the backoffice

Collector creation using the API:

API calls

To create a collector, a salespoint must exist. Indeed, a collector is linked to a salespoint (you can see it as a cash register in a shop)

Salespoint creation:

const salespoint = await axios.post(`${BASE_URL}/sales-points`,
        {
          name: person.companyName,
          city: person.city,
          country: "France",
          zipCode: person.zipCode,
          city: person.city,
          street: person.street,
          ...(logoUrl && {logoUrl}),
          ...(lat && {lat}),
          ...(lng && {lng}),
        } , {
          headers: {
            'Content-Type': 'application/json',
            'x-api-key': apiKey,
            'x-api-secret': apiSecret,
          },
        },
      );

Collector creation, linked to the salespoint :

function getCollectorInfo(manager, companyId, salespointId) {
  const UUID = companyId;
  const POS_UUID = salespointId;
  const BRANDNAME = manager.name.replace(/\\s/g, '').toUpperCase();
  const COMPANYNAME = manager.companyName.replace(/\\s/g, '').toUpperCase();
  const GEN = Math.floor(10000000 + Math.random() * 90000000);
  return {
    identifier: `${UUID}_${POS_UUID}-${BRANDNAME}-${COMPANYNAME}-${GEN}`,
    uuid: UUID,
    salePoint: salespointId
  };
}

const collector = await axios.post(`${BASE_URL}/collectors/add`, getCollectorInfo(manager, companyId, salespointId),
      {
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': apiKey,
          'x-api-secret': apiSecret,
        },
      });      

The response of this call contains the collector ID that is required to request a payment

Collector ID

Once the collector is created, retrieve its ID :

https://api-dev.lyzi.fr/api/next/collectors/list

The identifierin the response of this request shall be used in the field merchantIdentifier for of the request of the payment below.

Request command:

To initialize a payment using cryptocurrencies, the endpoint request shall be called:

https://api-dev.lyzi.fr/api/confirm_conversion/request

• Full reference : https://api-dev.lyzi.fr/docs/#api-Conversions-Request_conversion

Request body :

{
        amount: Joi.required(),
        fromAsset: Joi.string().valid('EUR', 'CHF', 'XPF').insensitive().required(),
        toAsset: Joi.string().valid('USDT', 'USDC', 'EUR').insensitive().required(),
        webhookUrl: Joi.string().allow(null, ''),
        cancelUrl: Joi.string().allow(null, '').max(256),
        returnUrl: Joi.string().allow(null, '').max(256),
        merchantIdentifier: Joi.string().allow(null, ''),
        anonymous: Joi.boolean(),
        goods: Joi.object({
          goodsName: Joi.string(),
          goodsType: Joi.string().valid('01', '02'),
          goodsCategory: Joi.string().valid('0000', '1000', '2000', '3000', '4000', '5000', '6000', '7000', '8000', '9000', 'A000', 'B000', 'C000', 'D000', 'E000', 'F000', 'Z000'),
          goodsDetail: Joi.string().max(256).allow('', null),
          goodsQuantity: Joi.string().max(256).allow('', null)
        }),
        kycInfo: Joi.object({
          hash: Joi.string().required(),  // The HMAC hash, for security
          origin: Joi.string().required(),  // The origin name (fundora)
          id: Joi.string().required(),  // The session/KYC ID
          status: Joi.string().required(), // "approved" ? :) 
          firstName: Joi.string().required(),
          lastName: Joi.string().required(),
          nidPdfUrl: Joi.string().required(),  // The url where to download the file
          poaPdfUrl: Joi.string().required(),  // The url where to download the file
          kycReportUrl: Joi.string().required(),  // The url where to download the file
          fundOriginPdfUrl: Joi.string().required(),  // The url where to download the file
          approvedAt: Joi.string().required(), // Approval date
          rawData: Joi.object() // any data that can be useful
        })
      }

And voilà 💫 Just by a couple of lines, the payment url (paymentUrl from the response) can be retrieved and the user can be redirected to the payment gate to complete the payment.