Integration as SuperManager

This document describes how a SuperManager manages the full hierarchy and payment flow, from creating a Manager to initiating a payment session using a Collector.

Role Overview

• SuperManager

  • Creates or owns Managers

  • Creates Sales Points

  • Creates Collectors

  • Initiates Payment Sessions using a Collector ID

• Manager

  • Owns a company

  • Is attached to Sales Points and Collectors

  • Receives funds after KYB approval

More information in the general documentation:

Lyzi Roles

High-Level Flow

Here are the different steps, prefixed with the owner of the Action Item (SM = SuperManager, M = Manager = merchant, Lyzi = Lyzi team)

1. [SM] SuperManager creates (or already has) a Manager

2. [M] Manager’s company completes KYB and gets approved

3. [LYZI] This Manager is rattached to the SuperManager

4. [SM] SuperManager creates a Sales Point under the Manager

5. [SM] SuperManager creates a Collector linked to the Sales Point

6. [SM] SuperManager uses the Collector ID to create a Payment Session

---

1. Create a Manager (Child Company)

A SuperManager must first create or already own a Manager. A Sales Point or Collector cannot exist without a Manager.

Purpose

• The Manager represents a legal company

• Funds are routed to this company

• KYB approval is required before payments

API Call

const childManager = await axios.post(L
  `${BASE_URL}/companies/me/childs`,
  {
    companyName: "childCompany",
    firstName: "Jean",
    lastName: "Mopaz" + randomNumber,
    email: email,
    password: password,
    iban: generateValidIBAN("FR", 27),
    siretNumber: generateSIRET(),
    address: address,
    city: city,
    zipcode: zipcode,
  },
  {
    headers: {
      "Content-Type": "application/json",
      "x-api-key": apiKey,
      "x-api-secret": apiSecret,
    },
  }
);

const managerId = childManager.data.data._id;
const managerCompanyId = childManager.data.data.company._id;

The KYB of the merchant must be performed and validated by Lyzi Compliance team. Once confirmed, the manager is then attached under the SuperManager to allow the SuperManage to perform actions on behalf of him.

The manager ID is to be retrieved by the SM to perform actions on this account

Those steps are usually performed by Lyzi team. Do not hesitate to reach out to request action or follow-ups.

2. Create a Sales Point

A Sales Point represents a physical or logical location where payments occur.

Requirements

• A valid managerId

• The Manager’s company must exist

API Call

const { lat, lng } = await getLatLongFromShopName(
  "Decathlon Cannes",
  "cannes"
);

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

3. Create a Collector

A Collector is the entity that actually collects payments.

It is strictly bound to:

• One Sales Point

• One Manager

• One Company

Exampel of Collector Identifier Generation

function getCollectorInfo(
  name,
  companyName,
  companyId,
  salespointId
) {
  const UUID = companyId;
  const POS_UUID = salespointId;
  const BRANDNAME = name.replace(/\s/g, "").toUpperCase();
  const COMPANYNAME = 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,
  };
}

API Call

const collector = await axios.post(
  `${BASE_URL}/collectors/add`,
  {
    ...getCollectorInfo(
      name,
      companyName,
      managerCompanyId,
      salespoint.data.data._id
    ),
    childManager: managerId,
  },
  {
    headers: {
      "Content-Type": "application/json",
      "x-api-key": apiKey,
      "x-api-secret": apiSecret,
    },
  }
);

const collectorId = collector.data.data._id;

4. Create a Payment Session (Using the identifier)

Once the Collector exists and the company is KYB approved, payments can be initiated.

Key Rule

Payments are always created using a collectorId.

Example Payment Session Creation

const paymentSession = await axios.post(
  `${BASE_URL}/confirm_conversion/request`,
  {
    merchantIdentifier: identifier, 
    amount: Joi.required(),
    fromAsset: Joi.string().valid('EUR', 'CHF', 'XPF').insensitive().required(),
    toAsset: Joi.string().valid('USDC').insensitive().required(),
    webhookUrl: Joi.string().allow(null, ''),
    cancelUrl: Joi.string().allow(null, '').max(256),
    returnUrl: Joi.string().allow(null, '').max(256),
    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)
    }),
  },
  {
    headers: {
      "Content-Type": "application/json",
      "x-api-key": apiKey,
      "x-api-secret": apiSecret,
    },
  }
);

For webhook and return URL information, please refer to :

Return/callback URL