Liqo

Payments

pay() and the payment lifecycle

liqo.pay(params) is the recommended way to accept a payment. It validates your input, creates a hosted checkout session (POST /checkout/sessions), and returns a URL to redirect your customer to.

Basic usage

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

// checkout.checkoutUrl → redirect the customer here
// checkout.session     → the PublicCheckoutSession (token, status, …)

Parameters

See Supported Currencies & Assets for the full fromCurrency/toAsset/targetChain reference.

ParamTypeRequiredNotes
amountnumber✅Amount in fromCurrency, must be > 0
fromCurrencyenum✅NGN GHS ZAR USD EUR GBP
toAssetenum✅USDC USDT XLM ETH BTC SOL
toWalletstring✅Destination wallet; validated against targetChain
payerEmailstring✅Customer email (valid format)
successUrlstring✅Redirect on success (http/https)
cancelUrlstring✅Redirect on cancel (http/https)
targetChainenum–stellar (default inferred) solana ethereum
methodenum–bank_transfer card
sourceCountrystring–ISO country (2–3 chars)
expiresInMinutesnumber–5–1440
metadataobject–Arbitrary key/values echoed back
idempotencyKeystring–Safe retries (see below)

Client-side validation

Before any request is sent, the SDK validates: amount > 0, both assets present, a valid email, valid http(s) URLs, and that toWallet matches targetChain:

  • stellar → G… (56 chars)
  • ethereum → 0x… (40 hex)
  • solana → base58 (32–44 chars)

Invalid input throws a LiqoSdkError without a network call.

Wallet ↔ chain matching

The destination asset also implies a chain (SOL → Solana, ETH → Ethereum, otherwise Stellar). Provide a matching toWallet, or set targetChain explicitly.

Idempotency

Every write sends an Idempotency-Key header. If you don't pass one, the SDK generates a UUID per call. Pass your own (e.g., your order id) so that safe retries don't create duplicate sessions:

await liqo.pay({ /* … */, idempotencyKey: `order_${orderId}` });

What pay() returns

interface PayResponse {
  checkoutUrl: string;          // redirect target
  session: PublicCheckoutSession; // token, status, amount, currency, destinationAsset, targetChain, expiresAt, …
}

pay() is a thin wrapper over checkout.sessions.create() — use either.

Payment lifecycle

pay() → checkout session created (status: active)
      → customer completes payment at checkoutUrl
      → Liqo routes & settles on Stellar
      → transaction reaches 'completed'
      → webhook 'transaction.completed' delivered to your server

Track status via webhooks (recommended) or by polling the transaction.

Notes on deprecated helpers

payAndWait() and payAndConfirm() are not supported for hosted checkout sessions (checkout responses intentionally don't expose internal transaction IDs). They throw a LiqoSdkError. To wait for completion, retrieve the session by token or wait on a transaction id from a webhook.

On this page