Conversions

Payment / conversion lifecycle — request, accept, confirm, cancel, status and history

Request a conversion (create payment order)

post

/confirm_conversion/request

Creates a new payment order. The code returned is used in all subsequent calls (accept, confirm, cancel, status).

Either merchantIdentifier (POS/collector) or websiteUrl (e-commerce) must be provided — at least one is required.

If websiteUrl is set, sessionId is also required.

If alias is set, the order is treated as a payment link (valid for 1 month by default). Without an alias, the order expires after ~5 minutes.

The webhook at webhookUrl will receive a POST request with the full order status on each change.

Roles: SuperAdmin, Association, Manager, SuperManager, SimpleUser, Service, Cashier

Authorizations

AuthorizationstringRequired

JWT token obtained from /auth/login or /auth/login/manager. Include as Authorization: Bearer <token>.

Body

amountanyRequired

Payment amount in the fiat currency specified by fromAsset (minimum 0.10)

Example: 50

fromAssetstring · enumRequired

Fiat currency the merchant receives

Possible values:

toAssetstring · enumOptional

Target settlement asset (currently always settled in USDC)

Default: USDCPossible values:

merchantIdentifierstringOptional

POS / collector identifier (required for in-store payments). Either this or websiteUrl must be set.

websiteUrlstringOptional

E-commerce website URL (required for online payments). Either this or merchantIdentifier must be set.

sessionIdstringOptional

Buy button session ID — required when websiteUrl is provided

webhookUrlstringOptional

URL to receive status update notifications via HTTP POST

cancelUrlstring · max: 256Optional

Redirect URL when customer cancels

returnUrlstring · max: 256Optional

Redirect URL after successful payment

aliasstringOptional

Merchant order reference / alias. If set, the order is a payment link valid for 1 month.

anonymousbooleanOptional

If true, payer identity is not required

expirationDuration_minutesnumberOptional

Custom expiry in minutes (only applies to payment links with alias; minimum 10)

Responses

200

Order created. Display the code to the customer as a QR code pointing to pay.lyzi.io/pay?code=<code>.

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

400

Illegal amount or invalid exchange rate

application/json

401

Unauthorized

application/json

422

Validation error

application/json

post

/confirm_conversion/request

POST /api/next/confirm_conversion/request HTTP/1.1
Host: api.lyzi.fr
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 333

{
  "amount": 29.99,
  "fromAsset": "EUR",
  "toAsset": "USDC",
  "merchantIdentifier": "550e8400-e29b-41d4-a716-446655440000-ACME-MYSHOP-GEN",
  "webhookUrl": "https://myshop.com/webhooks/lyzi",
  "returnUrl": "https://myshop.com/thank-you",
  "cancelUrl": "https://myshop.com/cart",
  "goods": {
    "goodsName": "Blue T-Shirt",
    "goodsType": "01",
    "goodsCategory": "3000"
  }
}

{
  "success": true,
  "status": 1,
  "data": {
    "code": "text",
    "order": {
      "_id": "text",
      "code": "text",
      "shortCode": "text",
      "fromAmount": "text",
      "toAmount": "text",
      "fromAsset": "EUR",
      "toAsset": "USDC",
      "status": "INITIAL",
      "paymentChannel": "binance",
      "webhookUrl": "text",
      "alias": "text",
      "goods": {
        "goodsName": "text",
        "goodsType": "01",
        "goodsCategory": "0000",
        "goodsDetail": "text",
        "goodsQuantity": "text"
      },
      "createdAt": "2026-05-19T19:14:11.434Z",
      "updatedAt": "2026-05-19T19:14:11.434Z"
    }
  }
}

Get conversion status

get

/confirm_conversion/status/{code}

Returns the current status and details of a payment order. This endpoint is public — no authentication required. Polled by the Lyzi payment portal.

Path parameters

codestringRequired

Order code returned by /confirm_conversion/request

Responses

200

Order status

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

404

Order not found

get

/confirm_conversion/status/{code}

GET /api/next/confirm_conversion/status/{code} HTTP/1.1
Host: api.lyzi.fr
Accept: */*

{
  "success": true,
  "status": 1,
  "data": {
    "_id": "text",
    "code": "text",
    "shortCode": "text",
    "fromAmount": "text",
    "toAmount": "text",
    "fromAsset": "EUR",
    "toAsset": "USDC",
    "status": "INITIAL",
    "paymentChannel": "binance",
    "webhookUrl": "text",
    "alias": "text",
    "goods": {
      "goodsName": "text",
      "goodsType": "01",
      "goodsCategory": "0000",
      "goodsDetail": "text",
      "goodsQuantity": "text"
    },
    "createdAt": "2026-05-19T19:14:11.434Z",
    "updatedAt": "2026-05-19T19:14:11.434Z"
  }
}

Get conversion status by order reference

get

/confirm_conversion/status/order/{orderRef}

Returns the current status of a payment order using the merchant's own order reference (alias set at creation). This endpoint is public — no authentication required.

Path parameters

orderRefstringRequired

Merchant order reference (alias provided at creation time)

Responses

200

Order status

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

404

Order not found

get

/confirm_conversion/status/order/{orderRef}

GET /api/next/confirm_conversion/status/order/{orderRef} HTTP/1.1
Host: api.lyzi.fr
Accept: */*

{
  "success": true,
  "status": 1,
  "data": {
    "_id": "text",
    "code": "text",
    "shortCode": "text",
    "fromAmount": "text",
    "toAmount": "text",
    "fromAsset": "EUR",
    "toAsset": "USDC",
    "status": "INITIAL",
    "paymentChannel": "binance",
    "webhookUrl": "text",
    "alias": "text",
    "goods": {
      "goodsName": "text",
      "goodsType": "01",
      "goodsCategory": "0000",
      "goodsDetail": "text",
      "goodsQuantity": "text"
    },
    "createdAt": "2026-05-19T19:14:11.434Z",
    "updatedAt": "2026-05-19T19:14:11.434Z"
  }
}

Accept conversion (choose payment channel)

post

/confirm_conversion/accept/{code}

Called by the customer / payer to select a payment channel (Binance Pay, WhiteBIT, etc.) and accept the order. Returns payment instructions specific to the chosen channel.

Roles: SuperAdmin, Manager, Service, Cashier

Authorizations

AuthorizationstringRequired

JWT token obtained from /auth/login or /auth/login/manager. Include as Authorization: Bearer <token>.

Path parameters

codestringRequired

Order code

Body

paymentChannelstring · enumOptional

binance=Binance Pay, whitepay=WhiteBIT, whitepay-non-custody=WhiteBIT Any Wallet, cryptopay=Crypto.com, crypto=Non-Custodial Wallet, gatepay=Gate Pay, coinbase=Coinbase Onramp, kucoinpay=KuCoin Pay

Possible values:

cancelUrlstring · max: 256Optional

returnUrlstring · max: 256Optional

networkintegerOptional

Chain ID for non-custodial wallet payments

payerEmailstring · emailOptional

anonymousbooleanOptional

userAddressstringOptional

Payer's blockchain wallet address

posstringOptional

POS identifier

pastOrdersstring[]Optional

Previous order codes (for recurring payment context)

Responses

200

Conversion accepted. Response contains channel-specific payment instructions. For non-custodial wallet: includes toAddress and tokenAmount. For CEX (Binance, etc.): includes deeplink or QR data.

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

dataobjectOptional

Payment instructions vary by payment channel

401

Unauthorized

application/json

404

Order not found

post

/confirm_conversion/accept/{code}

POST /api/next/confirm_conversion/accept/{code} HTTP/1.1
Host: api.lyzi.fr
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 181

{
  "paymentChannel": "binance",
  "cancelUrl": "text",
  "returnUrl": "text",
  "network": 1,
  "payerEmail": "name@gmail.com",
  "anonymous": true,
  "userAddress": "text",
  "pos": "text",
  "pastOrders": [
    "text"
  ]
}

{
  "success": true,
  "status": 1,
  "data": {}
}

Confirm conversion (merchant confirmation)

post

/confirm_conversion/confirm/{code}

Called by the merchant or cashier to manually confirm receipt of payment, or triggered automatically by the system after on-chain verification.

Roles: SuperAdmin, Association, Manager, SuperManager, Service, Cashier

Authorizations

AuthorizationstringRequired

JWT token obtained from /auth/login or /auth/login/manager. Include as Authorization: Bearer <token>.

Path parameters

codestringRequired

Order code

Responses

200

Conversion confirmed

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

dataanyOptional

Response payload

401

Unauthorized

application/json

404

Order not found

post

/confirm_conversion/confirm/{code}

POST /api/next/confirm_conversion/confirm/{code} HTTP/1.1
Host: api.lyzi.fr
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true,
  "status": 1,
  "data": null
}

Cancel conversion

post

/confirm_conversion/cancel/{code}

Cancels a pending payment order. Can be called by the merchant, cashier, or the customer.

Roles: SuperAdmin, Association, Manager, SuperManager, SimpleUser, Service, Cashier

Authorizations

AuthorizationstringRequired

JWT token obtained from /auth/login or /auth/login/manager. Include as Authorization: Bearer <token>.

Path parameters

codestringRequired

Order code

Responses

200

Conversion cancelled

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

dataanyOptional

Response payload

401

Unauthorized

application/json

404

Order not found

post

/confirm_conversion/cancel/{code}

POST /api/next/confirm_conversion/cancel/{code} HTTP/1.1
Host: api.lyzi.fr
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true,
  "status": 1,
  "data": null
}

Revert / refund conversion

post

/confirm_conversion/revert/{code}

Initiates a refund for a paid order.

Roles: SuperAdmin, Manager, SuperManager, Cashier

Authorizations

AuthorizationstringRequired

JWT token obtained from /auth/login or /auth/login/manager. Include as Authorization: Bearer <token>.

Path parameters

codestringRequired

Order code

Responses

200

Refund initiated

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

dataanyOptional

Response payload

401

Unauthorized

application/json

404

Order not found

post

/confirm_conversion/revert/{code}

POST /api/next/confirm_conversion/revert/{code} HTTP/1.1
Host: api.lyzi.fr
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true,
  "status": 1,
  "data": null
}

Expire a payment link

post

/confirm_conversion/expire/{code}

Manually expires a payment order / link, preventing further payments.

Roles: SuperAdmin, Manager, SuperManager, Cashier

Authorizations

AuthorizationstringRequired

JWT token obtained from /auth/login or /auth/login/manager. Include as Authorization: Bearer <token>.

Path parameters

codestringRequired

Order code

Responses

200

Link expired

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

dataanyOptional

Response payload

401

Unauthorized

application/json

post

/confirm_conversion/expire/{code}

POST /api/next/confirm_conversion/expire/{code} HTTP/1.1
Host: api.lyzi.fr
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true,
  "status": 1,
  "data": null
}

Get order history

get

/confirm_conversion

Returns a paginated list of orders for the authenticated merchant or user. Supports filtering by status, date range, amount and search query.

Roles: SuperAdmin, Manager, SuperManager, Cashier, Observer, SimpleUser, Service

Authorizations

AuthorizationstringRequired

JWT token obtained from /auth/login or /auth/login/manager. Include as Authorization: Bearer <token>.

Query parameters

statusone ofOptional

Filter by one or more statuses

string · enumOptional

Possible values:

pageintegerOptionalDefault: 1

limitintegerOptionalDefault: 20

startDatestringOptional

endDatestringOptional

searchstringOptional

Search by code, alias, or amount

amountFromstringOptional

amountTostringOptional

sortDirstringOptional

sortBystringOptional

conversionTypestring · enumOptionalPossible values:

managerEmailstringOptional

SuperAdmin/SuperManager: filter by manager email

Responses

200

Paginated list of orders

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

401

Unauthorized

application/json

get

/confirm_conversion

GET /api/next/confirm_conversion HTTP/1.1
Host: api.lyzi.fr
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true,
  "status": 1,
  "data": {
    "orders": [
      {
        "_id": "text",
        "code": "text",
        "shortCode": "text",
        "fromAmount": "text",
        "toAmount": "text",
        "fromAsset": "EUR",
        "toAsset": "USDC",
        "status": "INITIAL",
        "paymentChannel": "binance",
        "webhookUrl": "text",
        "alias": "text",
        "goods": {
          "goodsName": "text",
          "goodsType": "01",
          "goodsCategory": "0000",
          "goodsDetail": "text",
          "goodsQuantity": "text"
        },
        "createdAt": "2026-05-19T19:14:11.434Z",
        "updatedAt": "2026-05-19T19:14:11.434Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 1
  }
}

Download order history (CSV/Excel)

get

/confirm_conversion/download

Downloads order history as a CSV or Excel file. Supports the same date, amount and search filters as the history endpoint.

Roles: SuperAdmin, Manager, SuperManager, Observer, Cashier, SimpleUser

Authorizations

AuthorizationstringRequired

JWT token obtained from /auth/login or /auth/login/manager. Include as Authorization: Bearer <token>.

Query parameters

startDatestringOptional

endDatestringOptional

searchstringOptional

amountFromstringOptional

amountTostringOptional

conversionTypestring · enumOptionalPossible values:

managerEmailstringOptional

Responses

200

File download (CSV or Excel)

No content

401

Unauthorized

application/json

get

/confirm_conversion/download

GET /api/next/confirm_conversion/download HTTP/1.1
Host: api.lyzi.fr
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get payment links

get

/confirm_conversion/links

Returns all active payment links (orders with alias) created by the merchant.

Roles: SuperAdmin, Manager, SuperManager, Cashier

Authorizations

AuthorizationstringRequired

JWT token obtained from /auth/login or /auth/login/manager. Include as Authorization: Bearer <token>.

Responses

200

List of payment links

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

401

Unauthorized

application/json

get

/confirm_conversion/links

GET /api/next/confirm_conversion/links HTTP/1.1
Host: api.lyzi.fr
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true,
  "status": 1,
  "data": [
    {
      "_id": "text",
      "code": "text",
      "shortCode": "text",
      "fromAmount": "text",
      "toAmount": "text",
      "fromAsset": "EUR",
      "toAsset": "USDC",
      "status": "INITIAL",
      "paymentChannel": "binance",
      "webhookUrl": "text",
      "alias": "text",
      "goods": {
        "goodsName": "text",
        "goodsType": "01",
        "goodsCategory": "0000",
        "goodsDetail": "text",
        "goodsQuantity": "text"
      },
      "createdAt": "2026-05-19T19:14:11.434Z",
      "updatedAt": "2026-05-19T19:14:11.434Z"
    }
  ]
}

Save payer information

post

/confirm_conversion/payer-information

Saves KYC-light declarative information about the payer for a given order. Required for orders above the light KYC threshold.

Roles: Authenticated users

Authorizations

AuthorizationstringRequired

JWT token obtained from /auth/login or /auth/login/manager. Include as Authorization: Bearer <token>.

Body

codestringRequired

Order code

Responses

200

Payer information saved

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

dataanyOptional

Response payload

401

Unauthorized

application/json

422

Validation error

application/json

post

/confirm_conversion/payer-information

POST /api/next/confirm_conversion/payer-information HTTP/1.1
Host: api.lyzi.fr
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 302

{
  "code": "text",
  "payerInformation": {
    "firstName": "text",
    "lastName": "text",
    "email": "name@gmail.com",
    "address1": "text",
    "address2": "text",
    "city": "text",
    "state": "text",
    "country": "text",
    "zipCode": "text",
    "postalAddress": "text",
    "userAddress": "text",
    "isCompany": false,
    "companyName": "text",
    "companySiret": "text"
  }
}

{
  "success": true,
  "status": 1,
  "data": null
}

Set payer email

post

/confirm_conversion/email/{code}

Associates an email address with an existing payment order.

Roles: Association, Manager, SuperManager, SimpleUser, SuperAdmin, Service

Authorizations

AuthorizationstringRequired

JWT token obtained from /auth/login or /auth/login/manager. Include as Authorization: Bearer <token>.

Path parameters

codestringRequired

Order code

Body

emailstring · emailRequired

Responses

200

Email set

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

dataanyOptional

Response payload

401

Unauthorized

application/json

422

Validation error

application/json

post

/confirm_conversion/email/{code}

POST /api/next/confirm_conversion/email/{code} HTTP/1.1
Host: api.lyzi.fr
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 26

{
  "email": "name@gmail.com"
}

{
  "success": true,
  "status": 1,
  "data": null
}

Get exchange rate information

get

/confirm_conversion/exchangeInfo

Returns the current exchange rate between two assets. No authentication required.

Query parameters

fromAssetstringRequired

Source asset (e.g. EUR)

toAssetstringRequired

Target asset (e.g. USDC)

Responses

200

Exchange rate data

application/json

successbooleanOptional

Whether the request succeeded

statusintegerOptional

HTTP status code

422

Validation error

application/json

get

/confirm_conversion/exchangeInfo

GET /api/next/confirm_conversion/exchangeInfo?fromAsset=text&toAsset=text HTTP/1.1
Host: api.lyzi.fr
Accept: */*

{
  "success": true,
  "status": 1,
  "data": {
    "price": 1,
    "fromAsset": "text",
    "toAsset": "text"
  }
}

PreviousAuthentication NextCollectors

Last updated 1 month ago