Official Links

FAQ

API DOCUMENTATION

How to integrate Lyzi ?

Lyzi Integration

API Universal V.2

E-commerce Plugin

Lyzi Roles

Whitepaper

Introduction

Regulations & Compliance

Tokenomics
Product Suite

Roadmap

Technical vision

Disclaimer

Plugins

Integration with the API

Tutorial and context about Lyzi integration using the API (in english):

Integration with API

General information about the API:

Integration with the SDK

The SDK

Source	Url	Script load example
Stable	https://pay.lyzi.io/assets/buy-button/sdk-v2.js	<script src="https://pay.lyzi.io/assets/buy-button/sdk-v2.js" defer></script>
Dev	https://pay-dev.lyzi.io/assets/buy-button/sdk-v2.js	<script src="https://pay-dev.lyzi.io/assets/buy-button/sdk-v2.js" defer></script>

We recommend to use Stable source even in the development stage, you can still change the button environment in the SDK configuration.

SDK Class / Namespace

function/method	type	params	return type
construct	function	buttonId,buttonName,orderRef,price,goods,callbackUrl,returnUrl, currency, env	object
config	getter	-	object
conversionCode	getter	-	string
paymentState	getter	-	object
buttonUrl	getter	-	string
htmlSnippet	getter	-	string

SDK Method & Prototype

function/method	type	params	return type
init	function	{buttonId,buttonName,orderRef,price,goods,callbackUrl,returnUrl, currency, env}	void

Understanding the Parameters

variable	type	required	note
buttonId	string	yes
buttonName	string	no	*1A
orderRef	string	no	*1B
price	string	no	*1A
goods	object	no	• *1A;
• object refer to https://api-dev.lyzi.fr/docs/#api-Conversions-Request_conversion
callbackUrl	string	no	• 1A; 2A; 2B; 2C; *2D;
• URL that will open after successful/failed payment
returnUrl	string	no	• 2A; 2B; *2C;
• URL that will open after successful payment
cancelUrl	string	no	• 2A; 2B; *2C;
• URL that will open after failed payment
env	enum string	no	available value: ‘local’, ‘develop’, ‘staging’, ‘production’
currency	string	no	*1A;

PS:

1A : If undefined, it will use the value from the data entered when creating the button in the Manager back office
1B : If undefined, our backend will fill this value with random string
2A : If you define only “callbackUrl”, we will use this url as a webhook and a callback. The webhook will be sent via http request with POST method from our backend, and the callback will be executed on the client side by opening the url in a browser tab.
2B : If you define "returnUrl" and "cancelUrl" in the SDK configuration, these will be used as callbacks, which will be called if the payment succeeds/fails by opening the url in a browser tab. On the other hand, we will also send a webhook to the specified “callbackUrl”.
2C : Payment data will be attached in the query strings of the callback url or will be attached in the http request body of the webhook.
2D : Since we encountered some issues such as browser popup blocking, we do not recommend using callbacks as a transaction handler on your end.

Callback and Webhook

Callback

The callback will be executed on the client by opening the url in a browser tab,

The payment data will be attached in your specified url as query strings.

<aside> 💡

callbackUrl is ignored if returnUrl and cancelUrl are defined in SDK configuration.

If returnUrl and cancelUrl are NOT defined, then callbackUrl will be called.

</aside>

Executed callback url example:

<https://preprod.freemiumplay.com/services/payment?_id=65a7c3a920ff3a001d031f2b&goods[_id]=65a7c3a920ff3a001d031f2c&goods[goodsCategory]=Z000&goods[goodsName]=anu&goods[goodsType]=02&goods[referenceGoodsId]=25356565699000117914166585012401173902000010&fromAsset=EUR&toAsset=USDT&fromAmount=0.1&toAmount=0.11199222&exchangeInfo[_id]=65a7c3a920ff3a001d031f2d&exchangeInfo[symbol]=EURUSDT&exchangeInfo[price]=1.08730308&code=25356565699000117914166585012401173902000010&shortCode=EDBX47D6&status=PAID&expireTime=1705493735861&webhookUrl=https%3A%2F%2Fpreprod.freemiumplay.com%2Fservices%2Fpayment%3FextraParams%3Dlyzi%7C65a7c3a464eb1d55bbcb3899&paymentChannel=binance&createdAt=2024-01-17T12%3A10%3A17.212Z&updatedAt=2024-01-17T12%3A10%3A50.534Z&payer[_id]=649421dfa92ff3001d4ed6d8&payer[firstName]=Lyzi&payer[lastName]=Tester&payer[email]=testuser%40lyzi.fr&payer[phoneNumber]=12345678&payer[cashbackBalance]=0&confirm[_id]=65a7c3b720ff3a001d031f8a&confirm[order]=65a7c3a920ff3a001d031f2b&confirm[manager]=62bc1c651a8eda001c72845c&confirm[type]=WEBSITE&confirm[merchant][_id]=65157c845b85c20dd565d211&confirm[merchant][url]=https%3A%2F%2Flyzi.fr&confirm[merchant][user]=62bc1c651a8eda001c72845c&confirm[merchant][__v]=0&confirm[merchant][id]=65157c845b85c20dd565d211&confirm[createdAt]=2024-01-17T12%3A10%3A31.754Z&confirm[updatedAt]=2024-01-17T12%3A10%3A31.754Z&confirm[__v]=0&confirm[id]=65a7c3b720ff3a001d031f8a&id=65a7c3a920ff3a001d031f2b&extraParams=lyzi%7C65a7c3a464eb1d55bbcb3899>

Webhooks

Webhook will be called from our backend via HTTPS request with POST method to the defined webhookUrl, you can retrieve payment data from the request body.

Webhook example through CURL:

curl --location '<https://preprod.freemiumplay.com/services/payment?extraParams=lyzi%7C65a7c24864eb1d55bbcb3860>' \\
--header 'Content-Type: application/json' \\
--data-raw '{"_id":"65a7c24a20ff3a001d031daa","goods":{"_id":"65a7c24a20ff3a001d031dab","goodsCategory":"Z000","goodsName":"anu","goodsType":"02","referenceGoodsId":"25356565699000114981103580012401173902000010"},"fromAsset":"EUR","toAsset":"USDT","fromAmount":"0.1","toAmount":"0.11199428","exchangeInfo":{"_id":"65a7c24a20ff3a001d031dac","symbol":"EURUSDT","price":"1.08732311"},"code":"25356565699000114981103580012401173902000010","shortCode":"8E4G47A3","status":"PAID","expireTime":1705493371640,"paymentChannel":"binance","createdAt":"2024-01-17T12:04:26.084Z","updatedAt":"2024-01-17T12:07:49.418Z","__v":0,"payer":{"_id":"649421dfa92ff3001d4ed6d8","firstName":"Lyzi","lastName":"Tester","email":"[email protected]","phoneNumber":"12345678","cashbackBalance":0},"confirm":{"_id":"65a7c24b20ff3a001d031dd4","order":"65a7c24a20ff3a001d031daa","manager":"62bc1c651a8eda001c72845c","type":"WEBSITE","merchant":{"_id":"65157c845b85c20dd565d211","url":"<https://lyzi.fr>","user":"62bc1c651a8eda001c72845c","__v":0,"id":"65157c845b85c20dd565d211"},"createdAt":"2024-01-17T12:04:27.982Z","updatedAt":"2024-01-17T12:04:27.982Z","__v":0,"pos":null,"id":"65a7c24b20ff3a001d031dd4"},"refund":null,"id":"65a7c24a20ff3a001d031daa"}'

Using the SDK

Implementation Example 1

<script src="<https://pay.lyzi.io/assets/buy-button/sdk-v2.js>"></script>
<div id="lyzi-pay-button"></div>
<script>
var myButton = new lyziBuyButtonSdk();
myButton.init(
	{
		buttonId: "mybuttonid",
		orderRef: "ref-order-20241201-100",
		price: 0.1,
		currency: "EUR",
		callbackUrl:
		"<https://webhook.site/fa5f2664-9f3d-4737-b649-3cc7c4c1a005>",
		returnUrl: "<https://my-site.com/success>",
		cancelUrl: "<https://my-site.com/failed>",
		env: "dev",
		buttonName: "Button Name",
		goods: {
			goodsName: "Gigabyte RX 570",
			goodsCategory: "1000",
			goodsType: "01",
		},
	},
	document.getElementById("lyzi-pay-button")
);
</script>

Implementation Example 2

<script src="<https://pay.lyzi.io/assets/buy-button/sdk-v2.js>"></script>
<div id="lyzi-pay-button"></div>
<script>
 window.lyziBuyButton.init(
   {
     buttonId: "mybuttonid",
     orderRef: "ref-order-20241201-100",
     price: 0.1,
     callbackUrl:
       "<https://webhook.site/fa5f2664-9f3d-4737-b649-3cc7c4c1a005>",
     returnUrl: "<https://my-site.com/success>",
     cancelUrl: "<https://my-site.com/failed>",
     env: "dev",
   },
   document.getElementById("lyzi-pay-button")
 );
</script>

Implementation Example 3

<script src="<https://pay.lyzi.io/assets/buy-button/sdk-v2.js>"></script>
<a id="lyzi-pay-button">Pay with lyzi</a>
<script>
 var myButton = new lyziBuyButtonSdk();
 myButton.init({
     buttonId: "mybuttonid",
     orderRef: "ref-order-20241201-100",
     price: 0.1,
     callbackUrl:
       "<https://webhook.site/fa5f2664-9f3d-4737-b649-3cc7c4c1a005>",
     returnUrl: "<https://my-site.com/success>",
     cancelUrl: "<https://my-site.com/failed>",
     env: "dev",
   });
 document.getElementById("lyzi-pay-button").href = myButton.buttonUrl;
</script>

Implementation Example 4

<script src="<https://pay.lyzi.io/assets/buy-button/sdk-v2.js>"></script>
<a id="lyzi-pay-button">Pay with lyzi</a>
<script>
 var myButton = new lyziBuyButtonSdk(
   "mybuttonid",
   "Button Name",
   "ref-order-20241201-100",
   "0.1",
   {
     "goodsName": "Gigabyte RX 570",
     "goodsCategory": "1000",
     "goodsType": "01",
   },
   "<https://webhook.site/fa5f2664-9f3d-4737-b649-3cc7c4c1a005>",
   "<https://my-site.com/success>",
   "<https://my-site.com/failed>",
   "EUR",
   "dev"
 );
 document.getElementById("lyzi-pay-button").href = myButton.buttonUrl;
</script>

Implementation Example 5

<script src="<https://pay.lyzi.io/assets/buy-button/sdk-v2.js>"></script>
<div id="lyzi-pay-button"></div>
<script>
 var myButton = new lyziBuyButtonSdk(
   "mybuttonid",
   "Button Name",
   "ref-order-20241201-100",
   "0.1",
   null,
   "<https://webhook.site/fa5f2664-9f3d-4737-b649-3cc7c4c1a005>",
   "<https://my-site.com/success>",
   "<https://my-site.com/failed>",
   "EUR",
   "dev"
 );
 var myButtonSnippet = document.createRange().createContextualFragment(myButton.htmlSnippet);
 document.getElementById("lyzi-pay-button").append(myButtonSnippet);
</script>

Implementation Example 6

<script src="<https://pay.lyzi.io/assets/buy-button/sdk-v2.js>"></script>
<div id="lyzi-pay-button"></div>
<script>
 var myButton = new lyziBuyButtonSdk();
 myButton.init(
   {
     buttonId: "mybuttonid",
     orderRef: "ref-order-20241201-100",
     price: 0.1,
     callbackUrl:
       "<https://webhook.site/fa5f2664-9f3d-4737-b649-3cc7c4c1a005>",
     returnUrl: "<https://my-site.com/success>",
     cancelUrl: "<https://my-site.com/failed>",
     env: "dev",
   },
   document.getElementById("lyzi-pay-button")
 );

 setInterval(() => {
   console.log('conversion code', myButton.conversionCode)
   console.log('payment state', myButton.paymentState)
 }, 2000);
</script>

Known Issues

I can’t get the correct data from query params!

We have decoded the url before we hit this, somehow at some point the web browser encodes this url again.

You can try to decode the url twice to fix this issue, e.g:

decodeURIComponent(decodeURIComponent(url));

I didn't receive a callback and the transaction wasn't updated on my end!

We remind you again that the callback is executed on the client side by opening the url in a browser tab, at some point the client browser may block the popup or url redirection.

To avoid this, you must set “returnUrl” and “cancelUrl” in the SDK configuration, so these urls will only be used as redirect URLs on successful/failed payments. Then you can handle the status of your transaction using the payment data we send to the specified webhookUrl.

Migrating from V1 SDK

You can easily upgrade to V2 SDK by changing the SDK source

---
<script src="https:/pay.lyzi.io/assets/buy-button/sdk.js"></script>
---

+++
<script src="https:/pay.lyzi.io/assets/buy-button/sdk-v2.js"></script>
+++