Quickstart

This quickstart takes you from zero to a successful sandbox payment using Lydian hosted checkout — the fastest way to integrate. You'll create a payment session, open the hosted checkout, and confirm the result.

You'll need a Publishable Key to follow along. Find it in the Merchant Portal under Developer » API Keys. Publishable keys are prefixed with pk_. See Authentication & Environments for the difference between key types.

1. Set your environment

Every request below uses the sandbox environment:

2. Create a session

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

POST
/session
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 includes a sessionID and a qrData URL — the hosted checkout link:

response

{
    "sessionID": "009a3809-7328-4b6c-873b-089eff019f98",
    "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98",
    "successURL": "https://your-site.com/checkout/success",
    "cancelURL": "https://your-site.com/checkout/cancel",
    "failureURL": "https://your-site.com/checkout/failure"
}

See the full request and response fields in the Create Session reference.

3. Open hosted checkout

Send your customer to the qrData URL (or render it as a QR code). Lydian's hosted checkout walks 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.

4. Confirm the transaction

Once the customer selects an asset and network, the session references a transactionID. Confirm the outcome by polling Get Session or Get Transaction — a transaction status of 1 means the payment succeeded.

GET
/session/{sessionID}
curl --location '{API_BASE_URL}/session/{sessionID}' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json'

For the full set of status values, see Payment Lifecycle & Statuses. In production you can also receive the result via a webhook instead of polling — see Set Up Webhooks.

What's next?