Getting Started

Prerequisites

Node.js 18+
A Liqo API key (start with a sandbox key)

Install

npm install @liqo/sdk

Initialize the client

import { Liqo } from '@liqo/sdk';

const liqo = new Liqo(process.env.LIQO_API_KEY!, {
  environment: 'sandbox', // default
});

Store your key in an environment variable — never hard-code it.

(Optional) Get a quote

const quote = await liqo.quote({
  amount: 15000,
  fromCurrency: 'NGN',
  toAsset: 'USDC',
  targetChain: 'stellar',
});

console.log(`≈ ${quote.estimatedOutput} USDC, fee ${quote.fee}`);

Create a payment

const checkout = await liqo.pay({
  amount: 15000,
  fromCurrency: 'NGN',
  toAsset: 'USDC',
  toWallet: 'G...RECIPIENT',   // a valid Stellar address for targetChain 'stellar'
  payerEmail: 'customer@example.com',
  targetChain: 'stellar',
  successUrl: 'https://yourapp.com/success',
  cancelUrl: 'https://yourapp.com/cancel',
});

// Redirect your customer here to complete payment:
return redirect(checkout.checkoutUrl);

Handle the result via webhook

Liqo notifies your server when the transaction settles. Verify the signature using the raw body:

app.post('/webhooks/liqo', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = liqo.webhooks.verify({ payload: req.body, headers: req.headers });
    if (event.event === 'transaction.completed') {
      // fulfill the order for event.data.transactionId
    }
    res.sendStatus(200);
  } catch {
    res.sendStatus(400);
  }
});

Configure webhookSecret on the client (or pass secret to verify). See Webhooks.

(Optional) Check status directly

const tx = await liqo.transactions.retrieve('tx_123');
console.log(tx.status);

You're done 🎉

Payments — options and lifecycle
Checkout — sessions in depth
Error Handling — robust integrations
Best Practices — going to production
Full runnable apps in examples/

Getting Started

On this page