Accept Your First Payment

This guide walks through taking a payment with hosted checkout — the recommended, lowest-effort integration. Your backend creates a payment session, you send the customer to Lydian's hosted checkout, and you confirm the result.

Prerequisites

• A Publishable Key (pk_...) from the Merchant Portal under Developer » API Keys. See Authentication & Environments.
• Your API base URL. This guide uses sandbox: {API_BASE_URL} = https://api.sandbox.lydian.com.

New here? The Quickstart is the condensed version of this guide.

The flow at a glance

1. POST /session      →  sessionID + qrData
2. Open qrData        →  https://pay.lydian.com/session/{sessionID}
3. Customer selects an asset/network and pays
4. Lydian creates and confirms a Transaction on-chain
5. Confirm result     →  GET /session/{sessionID}  |  GET /transaction/{transactionID}  |  webhook

1. Create a session

Your backend creates a Session for the amount you want to collect, authenticated with your Publishable Key in the X-Publishable-Key header.

curl --location '{API_BASE_URL}/session' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "amount": {AMOUNT_IN_FLOAT},
    "amountCurrency": "{CURRENCY_CODE}",
    "successURL": "{SUCCESS_URL}",
    "cancelURL": "{CANCEL_URL}",
    "failureURL": "{FAILURE_URL}"
}'

The response returns a sessionID and a qrData URL. For the full request and response fields, see the Create Session reference.

2. Open hosted checkout

qrData is the Lydian-hosted checkout link for this session:

https://pay.lydian.com/session/{sessionID}

Redirect the customer to that URL, or render it as a QR code for them to scan. Lydian's hosted checkout guides them through choosing an asset and network (for example USDT on Ethereum) and completing the payment. When they finish, they're redirected to your successURL, cancelURL, or failureURL.

3. A transaction is created

When the customer selects an asset and network, Lydian creates a Transaction and links it to the session. The session then exposes a transactionID you can use to track the payment.

4. Confirm the final status

Confirm the outcome using any of these:

• Poll the session — GET /session/{sessionID} returns the current status and the transactionID.
• Poll the transaction — GET /transaction/{transactionID} returns the transaction's status.
• Receive a webhook — subscribe to payment events so Lydian notifies your endpoint. See Set Up Webhooks and Handle Webhook Events.

A transaction status of 1 means the payment succeeded. For the full set of values, see Payment Lifecycle & Statuses.

Next steps

• Web Checkout — embed checkout on your own site instead of redirecting.
• Set Up Webhooks — get notified instead of polling.
• API Reference: Sessions · Transactions.