# Lydian Developer Documentation

This file contains the complete Lydian Developer Documentation in navigation order. An index of pages is available at https://developer.lydian.com/llms.txt.

---

# Lydian Developer Documentation

Source: https://developer.lydian.com/
Markdown: https://developer.lydian.com/index.md

Lydian lets you accept cryptocurrency payments at checkout. Your customer pays in a supported asset (for example USDT on Ethereum), Lydian confirms the payment on-chain, and your merchant account is settled — without you handling wallets, gas, or exchange rates yourself.

[Quickstart](https://developer.lydian.com/quickstart.md)

[Choose your integration](https://developer.lydian.com/get-started/choose-integration.md)

## How a payment works

Every Lydian payment follows the same high-level flow:

1. **Create a Session** — your backend opens a payment [Session](https://developer.lydian.com/api/session.md) for a specific amount.
2. **Collect the payment** — the customer completes payment through Lydian checkout (hosted or embedded), choosing their asset and network.
3. **Confirm on-chain** — Lydian creates and tracks a [Transaction](https://developer.lydian.com/api/transaction.md) and confirms it on the blockchain.
4. **Get notified** — you confirm the final status by polling the API or receiving a webhook.

For a deeper look, see [How Lydian Payments Work](https://developer.lydian.com/concepts/how-payments-work.md) and [Sessions & Transactions](https://developer.lydian.com/concepts/sessions-and-transactions.md).

## Ways to integrate

- **Hosted Checkout (recommended)** — your backend creates a Session and sends the customer to the Lydian-hosted checkout URL returned as `qrData`. The least code to get started. See [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md).
- **Embedded Web Checkout** — drop the `<lydian-checkout>` element onto your own page with the Web SDK to keep customers on your site. See [Web Checkout](https://developer.lydian.com/guides/web-checkout.md) and the [Web SDK](https://developer.lydian.com/sdks/web.md).
- **Work directly with the API** — every endpoint, request, and response is documented in the [API Reference](https://developer.lydian.com/api/session.md).

Not sure which to pick? Start with [Choose Your Integration](https://developer.lydian.com/get-started/choose-integration.md).

## Get set up

Create your merchant and generate keys in the [Lydian Merchant Dashboard](https://merchant.lydian.com/), then follow the [Quickstart](https://developer.lydian.com/quickstart.md) to take your first payment in the sandbox. See [Authentication & Environments](https://developer.lydian.com/get-started/authentication.md) for keys and base URLs.

---

# Quickstart

Source: https://developer.lydian.com/quickstart
Markdown: https://developer.lydian.com/quickstart.md

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.

> **Note:** You'll need a **Publishable Key** to follow along. Find it in the Merchant Portal under
> [Developer » API Keys](https://merchant.lydian.com/en/developer/keys). Publishable keys are prefixed
> with `pk_`. See [Authentication & Environments](https://developer.lydian.com/get-started/authentication.md) for the difference between key types.

## 1. Set your environment

Every request below uses the **sandbox** environment:

- API base URL (`{API_BASE_URL}`): `https://api.sandbox.lydian.com`
- Merchant Portal: [merchant.sandbox.lydian.com](https://merchant.sandbox.lydian.com)

## 2. Create a session

Your backend creates a [Session](https://developer.lydian.com/api/session.md) with the amount to collect, authenticated with your Publishable Key in the `X-Publishable-Key` header.

**Endpoint:** `POST /session`

**curl**

```bash
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**

```json
{
    "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](https://developer.lydian.com/api/session.md#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](https://developer.lydian.com/api/session.md#get-session) or [Get Transaction](https://developer.lydian.com/api/transaction.md#get-transaction) — a transaction `status` of `1` means the payment succeeded.

**Endpoint:** `GET /session/{sessionID}`

**curl**

```bash
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](https://developer.lydian.com/concepts/payment-lifecycle.md). In production you can also receive the result via a webhook instead of polling — see [Set Up Webhooks](https://developer.lydian.com/guides/set-up-webhooks.md).

## What's next?

- [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md) — the full hosted-checkout guide
- [Choose Your Integration](https://developer.lydian.com/get-started/choose-integration.md) — hosted checkout vs embedded Web checkout
- [Web Checkout](https://developer.lydian.com/guides/web-checkout.md) — embed the checkout on your own site
- API Reference: [Sessions](https://developer.lydian.com/api/session.md) and [Transactions](https://developer.lydian.com/api/transaction.md)

---

# Choose Your Integration

Source: https://developer.lydian.com/get-started/choose-integration
Markdown: https://developer.lydian.com/get-started/choose-integration.md

Lydian supports two ways to collect a payment. Both start the same way — your backend creates a [Session](https://developer.lydian.com/api/session.md) — and differ only in **where the customer completes payment**.

## Hosted Checkout (recommended)

Your backend creates a Session and redirects the customer to the Lydian-hosted checkout URL returned as `qrData` (for example `https://pay.lydian.com/session/{sessionID}`). Lydian handles asset and network selection, the wallet connection, and on-chain confirmation, then redirects the customer back to your `successURL`, `cancelURL`, or `failureURL`.

- **Best for:** getting live quickly with the least code.
- **Where the code lives:** your backend only — no frontend SDK required.
- **Get started:** [Quickstart](https://developer.lydian.com/quickstart.md) · [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md)

## Embedded Web Checkout

Keep the customer on your own site by embedding the checkout UI with the Web SDK. You add the `<lydian-checkout>` element to your page and initialize it with the session; the SDK renders the checkout inline.

- **Best for:** a fully branded, in-page checkout experience.
- **Where the code lives:** your backend (to create the Session) **and** your frontend (to embed the SDK).
- **Get started:** [Web Checkout](https://developer.lydian.com/guides/web-checkout.md) · [Web SDK](https://developer.lydian.com/sdks/web.md)

## Which should I choose?

|                            | Hosted Checkout         | Embedded Web Checkout               |
| -------------------------- | ----------------------- | ----------------------------------- |
| Customer completes payment | On Lydian's hosted page | On your own site                    |
| Frontend work              | None                    | Add the `<lydian-checkout>` element |
| Effort to integrate        | Lowest                  | Moderate                            |
| Recommended for            | Most integrations       | In-page, branded checkout           |

Both modes create the same Session and produce the same [Transaction](https://developer.lydian.com/api/transaction.md), so you can start with hosted checkout and move to embedded later without changing your backend.

---

# Authentication & Environments

Source: https://developer.lydian.com/get-started/authentication
Markdown: https://developer.lydian.com/get-started/authentication.md

Lydian authenticates every API request with a key you generate in the Merchant Portal. There are two key types for API access, each sent in its own header.

> **Note:** Generate and manage your keys in the Merchant Portal under
> [Developer » API Keys](https://merchant.lydian.com/en/developer/keys).

## API keys

|                    | Publishable Key                                                        | API Key                    |
| ------------------ | ---------------------------------------------------------------------- | -------------------------- |
| Prefix             | `pk_`                                                                  | `ak_`                      |
| Header             | `X-Publishable-Key: pk_...`                                            | `X-Api-Key: ak_...`        |
| Intended use       | Frontend / browser code                                                | Server-to-server only      |
| Merchant selection | Encoded in the key — append `:{EXTERNAL_MID}` to target a sub-merchant | Sent in the `X-MID` header |

- **Publishable Key (`pk_`)** is safe to use from frontend code. Use it to create a [Session](https://developer.lydian.com/api/session.md) or [Transaction](https://developer.lydian.com/api/transaction.md).
- **API Key (`ak_`)** is for server-to-server calls only — keep it secret. Use it for account, merchant, key, refund, reporting, and webhook management. When an API Key acts on a specific merchant (for example creating a session), send that merchant in the `X-MID` header.

For a deeper explanation of when to use each, see [API Key vs Publishable Key](https://developer.lydian.com/concepts/api-keys.md). To create, list, or revoke keys programmatically, see the [Authentication API reference](https://developer.lydian.com/api/authentication.md).

## Environments

Lydian provides separate sandbox and production environments, each with its own keys and dashboard.

| Environment | API base URL (`{API_BASE_URL}`)  | Merchant Portal                                                    |
| ----------- | -------------------------------- | ------------------------------------------------------------------ |
| Sandbox     | `https://api.sandbox.lydian.com` | [merchant.sandbox.lydian.com](https://merchant.sandbox.lydian.com) |
| Production  | `https://api.lydian.com`         | [merchant.lydian.com](https://merchant.lydian.com)                 |

Start in **sandbox** to test your integration end to end, then switch the base URL and keys to **production** to go live. New to the API? Follow the [Quickstart](https://developer.lydian.com/quickstart.md).

---

# Use Lydian Docs with AI Agents

Source: https://developer.lydian.com/get-started/ai-agents
Markdown: https://developer.lydian.com/get-started/ai-agents.md

Lydian publishes AI-readable versions of this developer documentation, so you can give AI coding assistants and agents clean documentation context while you build your integration. They are generated from the same source as the pages you are reading, so they always match the website.

## Documentation index

[`https://developer.lydian.com/llms.txt`](https://developer.lydian.com/llms.txt) is the recommended starting point for an AI agent. It lists every public documentation page, organized the same way as this site, with a short description and a link to the Markdown version of each page.

An agent can read this index to find the documentation relevant to its task and fetch only those pages, instead of loading the entire documentation set.

## Complete documentation

[`https://developer.lydian.com/llms-full.txt`](https://developer.lydian.com/llms-full.txt) contains the complete public Lydian developer documentation in a single AI-readable document, in the same order as the site navigation.

Use it when a tool prefers to receive all of the documentation as context at once.

## Individual Markdown pages

Every public documentation page has a Markdown version at the same URL with `.md` appended. It contains the same documentation content — text, parameters, and code examples — without the website navigation and layout.

| Human-readable                                     | AI-readable                                                                                                  |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `https://developer.lydian.com/api/session`         | [`https://developer.lydian.com/api/session.md`](https://developer.lydian.com/api/session.md)                 |
| `https://developer.lydian.com/api/refund`          | [`https://developer.lydian.com/api/refund.md`](https://developer.lydian.com/api/refund.md)                   |
| `https://developer.lydian.com/api/webhooks/events` | [`https://developer.lydian.com/api/webhooks/events.md`](https://developer.lydian.com/api/webhooks/events.md) |

For the documentation home page, use [`https://developer.lydian.com/index.md`](https://developer.lydian.com/index.md). Links between pages in the Markdown versions point to other Markdown pages, so an agent can keep navigating the documentation.

## Using the docs with an AI agent

1. Give your AI agent the documentation index: `https://developer.lydian.com/llms.txt`.
2. Ask it to read the relevant Lydian documentation before it helps implement your integration.
3. The agent follows the Markdown links to the specific API reference, guide, concept, or SDK pages it needs.

For example:

```txt
Use the Lydian developer documentation at https://developer.lydian.com/llms.txt.
Read the relevant documentation before helping me implement my Lydian integration.
```

If your tool can't fetch URLs, paste or attach the content of `llms-full.txt` or of the individual Markdown pages you need instead.

## Security

- The AI-readable versions contain the same public information as this developer documentation. No account or key is needed to read them.
- Never give an AI tool your secret **API Key** (`ak_`), webhook signing keys, or any other private credentials.
- Develop and test your integration against the Lydian sandbox. See [Authentication & Environments](https://developer.lydian.com/get-started/authentication.md).
- Review AI-generated integration code before using it in production.
- Lydian's developer documentation and actual API behavior are authoritative. If an AI tool's answer disagrees with them, follow the documentation.

---

# Accept Your First Payment

Source: https://developer.lydian.com/guides/accept-a-payment
Markdown: https://developer.lydian.com/guides/accept-a-payment.md

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](https://merchant.lydian.com/en/developer/keys). See [Authentication & Environments](https://developer.lydian.com/get-started/authentication.md).
- Your API base URL. This guide uses sandbox: `{API_BASE_URL}` = `https://api.sandbox.lydian.com`.

New here? The [Quickstart](https://developer.lydian.com/quickstart.md) is the condensed version of this guide.

## The flow at a glance

```text
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](https://developer.lydian.com/api/session.md) for the amount you want to collect, authenticated with your Publishable Key in the `X-Publishable-Key` header.

**Endpoint:** `POST /session`

**curl**

```bash
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](https://developer.lydian.com/api/session.md#create-session) reference.

## 2. Open hosted checkout

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

```text
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](https://developer.lydian.com/api/transaction.md) 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}`](https://developer.lydian.com/api/session.md#get-session) returns the current status and the `transactionID`.
- **Poll the transaction** — [`GET /transaction/{transactionID}`](https://developer.lydian.com/api/transaction.md#get-transaction) returns the transaction's `status`.
- **Receive a webhook** — subscribe to payment events so Lydian notifies your endpoint. See [Set Up Webhooks](https://developer.lydian.com/guides/set-up-webhooks.md) and [Handle Webhook Events](https://developer.lydian.com/guides/handle-webhook-events.md).

A transaction `status` of `1` means the payment succeeded. For the full set of values, see [Payment Lifecycle & Statuses](https://developer.lydian.com/concepts/payment-lifecycle.md).

## Next steps

- [Web Checkout](https://developer.lydian.com/guides/web-checkout.md) — embed checkout on your own site instead of redirecting.
- [Set Up Webhooks](https://developer.lydian.com/guides/set-up-webhooks.md) — get notified instead of polling.
- API Reference: [Sessions](https://developer.lydian.com/api/session.md) · [Transactions](https://developer.lydian.com/api/transaction.md).

---

# Web Checkout

Source: https://developer.lydian.com/guides/web-checkout
Markdown: https://developer.lydian.com/guides/web-checkout.md

Embed the Lydian checkout on your own page with the **Web SDK** (`@lydianpay/sdk-web`). The SDK registers a `<lydian-checkout>` element and a `window.Lydian` API that runs the whole payment inline — the customer never leaves your site.

## Hosted vs embedded — which to use?

- Choose **hosted checkout** for the least code: your backend creates a session and redirects the customer to Lydian's page. Start with [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md).
- Choose **embedded Web checkout** (this guide) to render the checkout inside your own site for a branded, in-page experience. See also [Choose Your Integration](https://developer.lydian.com/get-started/choose-integration.md).

## Prerequisites

- A **Publishable Key** (`pk_...`) — see [Authentication & Environments](https://developer.lydian.com/get-started/authentication.md).
- A **WalletConnect (Reown) project ID**, used to power wallet connections.

## 1. Add the SDK

Load the SDK as an ES module, and pin a version so an upstream release can't change your checkout unexpectedly:

**HTML**

```html
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@lydianpay/sdk-web@3.0.1/dist/lydian.js"
></script>
```

Using a bundler instead? Run `npm install @lydianpay/sdk-web` and `import '@lydianpay/sdk-web'`.

## 2. Place the checkout element

Add the `<lydian-checkout>` element where you want the checkout to appear. It stays hidden until you initialize the SDK.

**HTML**

```html
<lydian-checkout></lydian-checkout>
```

## 3. Initialize the SDK

Call `window.Lydian.init(...)` with your publishable key, WalletConnect project ID, and the payment to collect. Set `isEmbedded: true` to render the checkout inline (rather than as a modal), and provide listeners to react to the outcome.

```js
window.Lydian.init({
  sandbox: true, // sandbox environment; use dev:false + sandbox:false for production
  dev: false,
  isEmbedded: true, // render inline inside <lydian-checkout>
  publishableKey: '{PUBLISHABLE_KEY}',
  walletConnectProjectId: 'your-walletconnect-project-id',
  transaction: {
    amount: 2.45,
    currency: 'USD', // 'USD', 'TRY' or 'PHP'
    descriptor: 'Order #1234',
    referenceNumber: 'your-unique-ref',
  },
  paymentSuccessListener: () => {
    window.location.href = '/thank-you'
  },
  paymentFailedListener: (message) => {
    console.error('Payment failed:', message)
  },
  paymentCanceledListener: () => {
    console.log('Payment canceled')
  },
})
```

Lydian creates and tracks the underlying [Transaction](https://developer.lydian.com/api/transaction.md) for this payment, and your listeners fire when it succeeds, fails, or is canceled. To change the amount before the customer pays, call `window.Lydian.updateTransaction({ ... })`.

## Next steps

- [Web SDK](https://developer.lydian.com/sdks/web.md) — full option reference (`init` options, `Transaction` fields, environments).
- API Reference: [Sessions](https://developer.lydian.com/api/session.md) · [Transactions](https://developer.lydian.com/api/transaction.md).
- Prefer a redirect instead? [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md) (hosted checkout).

---

# Refund a Payment

Source: https://developer.lydian.com/guides/refund-a-payment
Markdown: https://developer.lydian.com/guides/refund-a-payment.md

Refund a payment by refunding its underlying [Transaction](https://developer.lydian.com/api/transaction.md). Lydian recalculates the correct amount of the underlying crypto asset to return, accounting for the current exchange rate and network gas fee.

## Prerequisites

- An **API Key** (`ak_...`) — refunds are a server-to-server operation. See [Authentication & Environments](https://developer.lydian.com/get-started/authentication.md).
- The `X-MID` header identifying the merchant the transaction belongs to.
- A transaction that has **succeeded** (`status` `1`). Only a completed payment can be refunded — see [Payment Lifecycle & Statuses](https://developer.lydian.com/concepts/payment-lifecycle.md).

## How refunds fit the payment lifecycle

A refund reverses the flow of funds after a transaction has been paid. Because crypto amounts and exchange rates move over time, Lydian converts the refund at the **current** rate and reduces the returned amount by the **current gas fee**.

> For example, if a customer paid $100 in TRX two weeks ago, the refund is calculated using today's exchange rate and gas fee before returning the resulting amount in TRX.

Use the optional `gasFeePayer` field (`merchant` or `customer`) to control who absorbs the network fee. When omitted, the refund amount is reduced by the current gas fee.

## Create the refund

Send a refund request against the transaction. See [Create A Refund](https://developer.lydian.com/api/refund.md#create-a-refund) for the full request and response schema.

**Endpoint:** `POST /account/{accountID}/transaction/{transactionID}/refund`

**curl**

```bash
curl --location '{API_BASE_URL}/account/{ACCOUNT_ID}/transaction/{TRANSACTION_ID}/refund' \
--header 'X-Api-Key: {API_KEY}' \
--header 'X-MID: {MERCHANT_UUID_OR_EXTERNAL_MID}' \
--header 'Content-Type: application/json' \
--data '{
    "amount": {AMOUNT_IN_FLOAT},
    "gasFeePayer": "merchant"
}'
```

The response is an array of refund objects, each with a `refundID` and the `assetAmount` returned.

## Check the result

The refund appears in the transaction's `refunds` array — retrieve it with [`GET /transaction/{transactionID}`](https://developer.lydian.com/api/transaction.md#get-transaction). For the exact refund request and response fields, see the [Refunds API reference](https://developer.lydian.com/api/refund.md).

## Related

- API Reference: [Refunds](https://developer.lydian.com/api/refund.md) · [Transactions](https://developer.lydian.com/api/transaction.md).
- [Payment Lifecycle & Statuses](https://developer.lydian.com/concepts/payment-lifecycle.md).

---

# Set Up Webhooks

Source: https://developer.lydian.com/guides/set-up-webhooks
Markdown: https://developer.lydian.com/guides/set-up-webhooks.md

Webhooks let Lydian notify your systems in real time when something happens — most importantly, when a payment succeeds or fails — so you don't have to poll. A webhook is an HTTPS endpoint on your side that Lydian delivers event notifications to.

## Why use webhooks

During checkout you can confirm a payment by polling [Get Session](https://developer.lydian.com/api/session.md#get-session) or [Get Transaction](https://developer.lydian.com/api/transaction.md#get-transaction). Webhooks are the push alternative: register an endpoint once, and Lydian sends a `POST` request whenever a subscribed event occurs — ideal for updating orders or triggering fulfillment without polling.

## 1. Create a webhook

Create a webhook in the Merchant Portal under [Developer » Webhooks](https://merchant.lydian.com/en/developer/webhooks) — provide a name and the target URL that should receive events — or via the API with your API Key.

**Endpoint:** `POST /accounts/{accountUUID}/webhooks`

**curl**

```bash
curl --location '{API_BASE_URL}/accounts/{ACCOUNT_UUID}/webhooks' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "{WEBHOOK_NAME}",
    "url": "{WEBHOOK_URL}",
    "events": ["transaction.success"]
}'
```

See [Create Webhook](https://developer.lydian.com/api/webhooks.md#create-webhook) for the full request and response.

## 2. Choose your endpoint URL

The `url` is where Lydian delivers events. It should be a publicly reachable HTTPS endpoint that accepts a `POST` with a JSON body (`Content-Type: application/json`) and returns quickly.

## 3. Select event types

Use the `events` array to subscribe only to the event types you care about (for example `transaction.success`). A webhook receives only the events it subscribed to. See [Event Payloads](https://developer.lydian.com/api/webhooks/events.md) for the available event types.

## 4. How this fits payment confirmation

Once configured, a completed payment triggers an event (such as `transaction.success`) delivered to your endpoint — a push alternative to the polling shown in [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md). Learn how to consume delivered events in [Handle Webhook Events](https://developer.lydian.com/guides/handle-webhook-events.md).

## Manage webhooks

List, update, and delete webhooks via the [Webhooks API reference](https://developer.lydian.com/api/webhooks.md).

---

# Handle Webhook Events

Source: https://developer.lydian.com/guides/handle-webhook-events
Markdown: https://developer.lydian.com/guides/handle-webhook-events.md

Once you've [set up a webhook](https://developer.lydian.com/guides/set-up-webhooks.md), Lydian delivers events to your endpoint as an HTTP `POST` with a JSON body. This guide covers how to receive and process them.

## The event envelope

Every event is delivered as the same JSON envelope:

**envelope**

```json
{
  "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
  "type": "transaction.success",
  "timestamp": "2025-08-15T10:15:44.762134-04:00",
  "data": { }
}
```

- `accountUUID` — the account the event belongs to.
- `type` — the event type (see below).
- `timestamp` — when the event was emitted.
- `data` — the event-specific payload. For payment events, `data` is the full transaction record — the same shape as the [Get Transaction Response](https://developer.lydian.com/api/transaction.md#get-transaction-response).

## Process an event

1. **Receive the `POST`** at your configured endpoint and read the JSON body.
2. **Inspect `type`** to decide how to handle the event.
3. **Read `data`** for the details — for a payment event, `data.status` of `1` means the transaction succeeded.
4. **Respond quickly** with a `2xx` so Lydian considers delivery successful; do heavier work asynchronously.
5. **Make handlers idempotent.** The same event may be delivered more than once, so key your processing on a stable identifier (such as the `transactionID` in `data`) and ignore duplicates.

> **Note:** For anything that moves money or fulfills an order, confirm the current state against the API — call
> [`GET /transaction/{transactionID}`](https://developer.lydian.com/api/transaction.md#get-transaction) — rather than trusting the payload alone.

## Event types

For the currently documented webhook event types and payloads, see [Event Payloads](https://developer.lydian.com/api/webhooks/events.md).

For the `transaction.success` and `transaction.failed` payment events, `data` is the full transaction object, with `status` reflecting the outcome (for example `1` succeeded, or `-2` cancelled / `-4` forfeited on failure).

## Related

- [Set Up Webhooks](https://developer.lydian.com/guides/set-up-webhooks.md) — register and configure your endpoint.
- API Reference: [Event Payloads](https://developer.lydian.com/api/webhooks/events.md) · [Transactions](https://developer.lydian.com/api/transaction.md).
- [Payment Lifecycle & Statuses](https://developer.lydian.com/concepts/payment-lifecycle.md).

---

# How Lydian Payments Work

Source: https://developer.lydian.com/concepts/how-payments-work
Markdown: https://developer.lydian.com/concepts/how-payments-work.md

Lydian turns a fiat price into a completed crypto payment. Your backend opens a payment context, the customer pays through Lydian checkout, and Lydian confirms the payment on-chain and reports the result. This page describes how the pieces fit together; for a step-by-step walkthrough see [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md).

## The objects involved

```text
Merchant
  │ creates
  ▼
Session  ──▶  Checkout (hosted or embedded)
                    │ customer selects an asset + network and pays
                    ▼
              Transaction  ──▶  processing / on-chain confirmation  ──▶  final state
```

- A **[Merchant](https://developer.lydian.com/concepts/accounts-and-merchants.md)** is who the payment is collected for.
- A **Session** is the payment context — the amount, currency, and settings for one checkout.
- **Checkout** is where the customer actually pays, either Lydian-hosted or embedded on your site.
- A **Transaction** is the real payment: the asset, network, address, and on-chain result.

## How a payment moves

1. **A Session is created first.** Before the customer sees checkout, your backend creates a [Session](https://developer.lydian.com/api/session.md) for the amount to collect. This returns a `sessionID` and a `qrData` checkout URL.
2. **The customer completes checkout.** Checkout can be **hosted** (redirect to the `qrData` URL) or **embedded** (the Web SDK on your own page). Either way, the customer chooses an asset and network (for example USDT on Ethereum) and pays.
3. **A Transaction represents the payment.** When the customer selects payment details, Lydian creates a [Transaction](https://developer.lydian.com/api/transaction.md) associated with the session — this is the actual payment attempt Lydian processes and confirms on-chain.
4. **You observe the final state.** Payment state can be read from the Session and Transaction APIs, or pushed to you via webhooks. See [Payment Lifecycle & Statuses](https://developer.lydian.com/concepts/payment-lifecycle.md).

## Where to go next

- [Sessions & Transactions](https://developer.lydian.com/concepts/sessions-and-transactions.md) — how these two objects differ and relate.
- [Payment Lifecycle & Statuses](https://developer.lydian.com/concepts/payment-lifecycle.md) — the states a payment moves through.
- [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md) — build the hosted flow end to end.
- API Reference: [Sessions](https://developer.lydian.com/api/session.md) · [Transactions](https://developer.lydian.com/api/transaction.md).

---

# Accounts & Merchants

Source: https://developer.lydian.com/concepts/accounts-and-merchants
Markdown: https://developer.lydian.com/concepts/accounts-and-merchants.md

Lydian organizes your integration around two entities: an **Account** and the **Merchants** that operate under it. Understanding the relationship explains where configuration lives and how API calls are scoped to a specific merchant.

## Account

An **Account** is the top-level entity. Account-level configuration holds the defaults every merchant under the account can inherit — such as asset and wallet catalogs, checkout branding, and network confirmation settings — plus the account's billing fee schedule. See the [Accounts API](https://developer.lydian.com/api/account.md).

## Merchant

A **Merchant** operates under an account and is who a given payment is collected for. One merchant is created for the account by default, and an account can have multiple merchants. Merchants inherit the account defaults and can override specific settings through their `inherit` / `canSet` flags. See the [Merchants API](https://developer.lydian.com/api/merchant.md).

In short: an account provides the defaults and billing context; merchants are the entities that actually transact, each able to customize what the account allows.

## Why merchant context matters

Many operations act on behalf of a **specific merchant** — creating a payment, issuing a refund, reading merchant configuration. Lydian therefore needs to know which merchant a request applies to. How that merchant is identified depends on the key you authenticate with:

- **API Key (`ak_`)** — pass the merchant in the `X-MID` header (a merchant UUID or external merchant ID). See [Authentication & Environments](https://developer.lydian.com/get-started/authentication.md).
- **Publishable Key (`pk_`)** — the merchant is encoded in the key itself. To target a sub-merchant, append `:{EXTERNAL_MID}` to the publishable key.

The `externalMID` is an external merchant identifier (for example from a partner platform or point-of-sale system) that can be used to reference a merchant instead of its Lydian UUID.

> **Note:** Sessions and transactions record the `accountID`, `merchantID`, and `externalMID` they belong to, so you can
> always trace a payment back to the account and merchant it was collected for.

## Related

- [Authentication & Environments](https://developer.lydian.com/get-started/authentication.md) · [API Key vs Publishable Key](https://developer.lydian.com/concepts/api-keys.md)
- API Reference: [Accounts](https://developer.lydian.com/api/account.md) · [Merchants](https://developer.lydian.com/api/merchant.md)

---

# Sessions & Transactions

Source: https://developer.lydian.com/concepts/sessions-and-transactions
Markdown: https://developer.lydian.com/concepts/sessions-and-transactions.md

A payment involves two related objects: a **Session** and a **Transaction**. They are easy to confuse, so it's worth being precise about what each represents.

## Session

A **Session** is the checkout context for one payment. Your backend creates it **before** the customer completes checkout, specifying the amount and currency to collect. Creating a session returns:

- a `sessionID` — the identifier for this checkout, and
- a `qrData` URL — the Lydian-hosted checkout link the customer uses to pay.

A session also records which account and merchant it belongs to (`accountID`, `merchantID`, `externalMID`). Its status is intentionally simple:

| `status` | Meaning |
| -------- | ------- |
| `0`      | Pending |
| `1`      | Success |

See the [Sessions API](https://developer.lydian.com/api/session.md) for the full field list.

## Transaction

A **Transaction** is the actual payment. It is created **during checkout**, once the customer selects how they want to pay (their asset and network). The transaction carries the on-chain details — asset, network, address, amounts, and confirmation — and has its own richer status lifecycle (for example pending, succeeded, cancelled, or a fraud/compliance outcome). See [Payment Lifecycle & Statuses](https://developer.lydian.com/concepts/payment-lifecycle.md) for the full set of values and the [Transactions API](https://developer.lydian.com/api/transaction.md) for the fields.

## How they relate

The session is the **context** the customer enters; the transaction is the **payment** that results from it. 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 follow the payment.

So the two objects answer different questions:

- **Session** — "what checkout did I start, and where does the customer pay?"
- **Transaction** — "what actually got paid, and what state is it in?"

Track a payment to completion by polling the session (which surfaces the `transactionID` and overall result) or the transaction directly, or by receiving a webhook.

## Related

- [How Lydian Payments Work](https://developer.lydian.com/concepts/how-payments-work.md) · [Payment Lifecycle & Statuses](https://developer.lydian.com/concepts/payment-lifecycle.md)
- [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md)
- API Reference: [Sessions](https://developer.lydian.com/api/session.md) · [Transactions](https://developer.lydian.com/api/transaction.md)

---

# API Key vs Publishable Key

Source: https://developer.lydian.com/concepts/api-keys
Markdown: https://developer.lydian.com/concepts/api-keys.md

Lydian issues two types of credential for API access: a **Publishable Key** and an **API Key**. They differ in where they are designed to be used and what they are allowed to do. Both are generated in the Merchant Portal — the `pk_` and `ak_` prefixes identify the credential type; they are not values you choose.

## Publishable Key

- **Prefix:** `pk_`
- **Header:** `X-Publishable-Key`
- **Designed for:** client-side, customer-facing payment integrations.
- **Used to:** create a [Session](https://developer.lydian.com/api/session.md) or [Transaction](https://developer.lydian.com/api/transaction.md), and read merchant configuration.
- **Merchant context:** encoded in the key — append `:{EXTERNAL_MID}` to target a sub-merchant.

The publishable key is the credential your checkout uses to start a payment.

## API Key

- **Prefix:** `ak_`
- **Header:** `X-Api-Key`
- **Designed for:** server-to-server calls only — keep it secret and never expose it in client code.
- **Used to:** perform privileged account and merchant operations, including accounts, merchants, key management, refunds, reporting, webhooks, and subscriptions.
- **Merchant context:** pass the merchant in the `X-MID` header when an operation applies to a specific merchant.

## Choosing between them

Use the **publishable key** in code that runs in the customer's browser or on your frontend, and the **API key** only from your backend. Because the publishable key is designed for client-side use, it is scoped to the payment-creation operations above rather than privileged account management — reach for the API key when an operation manages your account, merchants, refunds, reporting, or webhooks.

## Related

- [Authentication & Environments](https://developer.lydian.com/get-started/authentication.md) — headers, environments, and where to generate keys.
- [Accounts & Merchants](https://developer.lydian.com/concepts/accounts-and-merchants.md) — how `X-MID` and `externalMID` select a merchant.
- API Reference: [Authentication](https://developer.lydian.com/api/authentication.md).

---

# Payment Lifecycle & Statuses

Source: https://developer.lydian.com/concepts/payment-lifecycle
Markdown: https://developer.lydian.com/concepts/payment-lifecycle.md

A payment moves through a series of states, reported as a numeric `status`. Your application logic should branch on these **documented numeric status values** — not on any display text, which can change.

## Session status

A [Session](https://developer.lydian.com/concepts/sessions-and-transactions.md) tracks the checkout at a high level, so its status is simple: it stays pending until the payment completes.

| `status` | Meaning                                                                         |
| -------- | ------------------------------------------------------------------------------- |
| `0`      | Pending — the session has been created; the customer has not completed payment. |
| `1`      | Success — the payment associated with the session completed successfully.       |

## Transaction status

A [Transaction](https://developer.lydian.com/api/transaction.md) carries the detailed outcome and has a richer set of states. `0` and `-3` are in progress, and `1` is the single success state. It helps to think of them in groups rather than as a flat list.

**In progress**

| `status` | Meaning                                                                                            |
| -------- | -------------------------------------------------------------------------------------------------- |
| `0`      | Pending — payment initiated, awaiting completion.                                                  |
| `-3`     | KYC Verification Pending — awaiting customer identity verification before the payment can proceed. |

**Successful**

| `status` | Meaning                                      |
| -------- | -------------------------------------------- |
| `1`      | Success — fully paid and confirmed on-chain. |

**Cancelled or timed out**

| `status` | Meaning         |
| -------- | --------------- |
| `-2`     | Cancelled       |
| `-8`     | Payment Timeout |
| `-9`     | API Cancelled   |
| `-4`     | Forfeit         |

**Fraud & compliance**

| `status` | Meaning           |
| -------- | ----------------- |
| `-1`     | Fraud             |
| `-7`     | Fraud Declined    |
| `-6`     | Fraud Refunded    |
| `-5`     | Fraud Refund Held |

> **Note:** The four fraud/compliance states and `-4 Forfeit` are terminal fraud- or compliance-related outcomes. The precise
> trigger that distinguishes each one is not fully specified in the current documentation — treat them as terminal
> "did not complete normally" states and confirm the exact semantics with the API or Lydian support before building
> logic that depends on the specific value.

## Working with statuses

- **Branch on the number, not the label.** Display text may be localized or reworded; the numeric value is the contract.
- **Only `1` means paid.** A [refund](https://developer.lydian.com/guides/refund-a-payment.md) requires a transaction in the success state (`1`).
- **Don't assume every negative value is final.** Negative values include an in-progress state (`-3` KYC Verification Pending) as well as payments that did not complete — cancelled, timed out, or stopped for fraud/compliance reasons.

## Related

- API Reference: [Transactions](https://developer.lydian.com/api/transaction.md) · [Sessions](https://developer.lydian.com/api/session.md)
- [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md) · [Refund a Payment](https://developer.lydian.com/guides/refund-a-payment.md)

---

# Supported Cryptocurrencies & Networks

Source: https://developer.lydian.com/concepts/supported-assets
Markdown: https://developer.lydian.com/concepts/supported-assets.md

Lydian supports the cryptocurrencies and blockchain networks listed below for checkout. This list is generated live , so it always reflects what the platform currently supports.

Assets are grouped by network type. Mainnet networks are used for real payments; testnet networks are for integration testing only. For the machine-readable catalog, call the [List Assets](https://developer.lydian.com/api/reference.md#list-assets) endpoint directly.

The full list of supported cryptocurrencies and networks is generated live from the [List Assets](https://developer.lydian.com/api/reference.md) endpoint (`GET /assets`), which returns the current machine-readable catalog.

## Request Additional Cryptocurrency or Network

Don't see a cryptocurrency or network you need? Submit a request below and the Lydian team will review it. Tell us the asset, the network, and your use case.

To request support for an additional cryptocurrency or network, use the request form on this page or email <crypto-support@lydian.com>.

---

# API Authentication

Source: https://developer.lydian.com/api/authentication
Markdown: https://developer.lydian.com/api/authentication.md

The first step to using Lydian's API suite is to create an API token. This can be done through the merchant portal.

Lydian uses two API key types:

- **API Key** (`ak_`, sent as `X-Api-Key`) — for direct server-to-server communication between your backend and Lydian's backend.
- **Publishable Key** (`pk_`, sent as `X-Publishable-Key`) — for frontend calls, most notably creating transactions.

For when to use each and the security model, see [API Key vs Publishable Key](https://developer.lydian.com/concepts/api-keys.md) and [Authentication & Environments](https://developer.lydian.com/get-started/authentication.md).

> **Note:** Your API keys can be found in the Lydian Merchant Portal under [Developer » API Keys](https://merchant.lydian.com/en/developer/keys).

## Sandbox Configuration

- *Merchant Portal »* <https://merchant.sandbox.lydian.com>
- *API Base URL »* <https://api.sandbox.lydian.com>

## Production Configuration

- *Merchant Portal »* <https://merchant.lydian.com>
- *API Base URL »* <https://api.lydian.com>

---

## API Key Management

API keys can be managed through the Merchant Portal or programmatically using the endpoints below.

### Create API Key

**Endpoint:** `POST /accounts/{accountUUID}/keys`

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/keys' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "keyType": "{KEY_TYPE}",
    "name": "{KEY_NAME}"
}'
```

`keyType` must be one of: `api` or `publishable`. For publishable keys, an optional `merchantUUID`
query parameter scopes the key to a specific merchant (e.g. `?merchantUUID={MERCHANT_UUID}`).

#### Create API Key Response

- `generatedKey` (string): The generated key. API keys are prefixed with `ak_`, publishable keys with `pk_`.
- `privateKey` (string): Base64-encoded private key. Only returned for API keys, empty for publishable keys. Store this securely — it cannot be retrieved again.

**example response**

```json
{
    "generatedKey": "ak_1a2b3c4d5e6f7890",
    "privateKey": "{BASE64_PRIVATE_KEY}"
}
```

### List API Keys

**Endpoint:** `GET /accounts/{accountUUID}/keys`

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/keys' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

#### List API Keys Response

- `keys` (object): Object containing key arrays grouped by type.
  - `api` (array): List of API keys, each with `UUID`, `key`, `status`, `role`, and `name`.
  - `publishable` (array): List of publishable keys, each with `UUID`, `key`, `status`, `name`, and
    `merchantUUID` (set when the key is scoped to a merchant).

**example response**

```json
{
    "keys": {
        "api": [
            {
                "UUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "key": "ak_1a2b3c4d5e6f7890",
                "status": 1,
                "role": "admin",
                "name": "Production API Key"
            }
        ],
        "publishable": [
            {
                "UUID": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
                "key": "pk_9a8b7c6d5e4f3210",
                "status": 1,
                "name": "Checkout Publishable Key",
                "merchantUUID": ""
            }
        ]
    }
}
```

### Revoke API Key

**Endpoint:** `DELETE /accounts/{accountUUID}/keys/{keyUUID}`

```bash
curl --location --request DELETE '{API_BASE_URL}/accounts/{AccountUUID}/keys/{keyUUID}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

Returns `204 No Content` on success.

---

# Account Configuration

Source: https://developer.lydian.com/api/account
Markdown: https://developer.lydian.com/api/account.md

Account-level configuration holds the defaults every merchant under the account can inherit —
asset and wallet catalogs, checkout branding, network confirmation settings — plus the account's
billing fee schedule. Merchant-level overrides are managed via the [Merchant](https://developer.lydian.com/api/merchant.md)
endpoints and their `inherit`/`canSet` flags.

For how accounts and merchants relate, see [Accounts & Merchants](https://developer.lydian.com/concepts/accounts-and-merchants.md).

## Get Account Configuration

**Endpoint:** `GET /accounts/{accountUUID}/config`

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/config' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

### Get Account Configuration Response

Returns the full configuration object — every writable field from
[Update Account Configuration](#update-account-configuration) plus the read-only fields managed
by Lydian: `addressProvider`, `autoRefundConfig` (automatic-refund switches for AML, fraud,
sanction, overpayment, and vendor-status triggers), `defaultRecommendedNetwork`,
`processingFeeConfig`, `settlementAnchor`, `settlementFrequency`,
`subscriptionsEmailCustomerOnPaymentFailed`, and `subscriptionsEmailMerchantOnPaymentAttemptsExceeded`.

- `allowedCrypto` (array): Assets enabled for the account.
- `allowedWalletsConfig` (array): Per-wallet checkout presentation, each with `name`, `isFeatured`, `featuredNote`,
  and `order`.
- `checkoutConfig` (object): Hosted checkout branding — same structure as on the
  [Merchant](https://developer.lydian.com/api/merchant.md#create-merchant) endpoints (`logoURL`, `termNotice`,
  `theme`, `fonts`, `flow`).
- `cryptoNetworkConfigs` (object): Per-network, per-asset settings (`minConfirmsLow`, `minConfirmsHigh`,
  `qrExpirationSeconds`).
- `highThreshold` (number): High-value transaction threshold.
- `refundWindowHours` (number): Window in which transactions can be refunded.
- `fees` (object): Platform fee schedule (`lydian`, `partner`) — same structure as `feeConfig` on
  [Update Merchant](https://developer.lydian.com/api/merchant.md#update-merchant).
- `support` (object): Support contact shown at checkout: `email`, `link`.
- `settlementFrequency` (string): Read-only. One of `hourly`, `six_hourly`, `daily`, `weekly`, `biweekly`, `monthly`.
- `settlementAnchor` (string): Read-only. Timestamp anchoring the settlement schedule.

**example response**

```json
{
    "allowedCrypto": ["USDT", "USDC"],
    "allowedWalletsConfig": [
        {
            "name": "MetaMask",
            "isFeatured": true,
            "featuredNote": "Recommended",
            "order": 1
        }
    ],
    "checkoutConfig": {
        "logoURL": "https://assets.lydian.com/merchants/brimspire/logo.png",
        "termNotice": "",
        "theme": {
            "primaryColor": "#0A0A0A",
            "accentColor": "#3B82F6",
            "backgroundColor": "#FFFFFF",
            "textColor": "#111111"
        },
        "fonts": { "family": "", "familyURL": "" },
        "flow": {
            "hideNoWalletOption": false,
            "showApprovalPage": false,
            "skipConfirmationPage": false
        }
    },
    "cryptoNetworkConfigs": {
        "ethereum": {
            "cryptoAssetConfigs": {
                "USDT": {
                    "minConfirmsLow": 1,
                    "minConfirmsHigh": 6,
                    "qrExpirationSeconds": 900
                }
            }
        }
    },
    "highThreshold": 10000,
    "refundWindowHours": 336,
    "defaultRecommendedNetwork": "ethereum",
    "settlementFrequency": "daily",
    "settlementAnchor": "2025-01-01T00:00:00Z",
    "support": {
        "email": "support@brimspire.com",
        "link": "https://brimspire.com/support"
    },
    "transactionFee": 0,
    "transactionFeeRate": 0.01,
    "settlementFee": 0,
    "subscriptionsEmailCustomerOnPaymentFailed": true,
    "subscriptionsEmailMerchantOnPaymentAttemptsExceeded": true
}
```

## Update Account Configuration

Only the fields present in the request body are updated.

**Endpoint:** `PUT /accounts/{accountUUID}/config`

```bash
curl --location --request PUT '{API_BASE_URL}/accounts/{AccountUUID}/config' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "allowedCrypto": ["{ASSET}"], // OPTIONAL
    "allowedWalletsConfig": [ // OPTIONAL — per-wallet checkout presentation
        {
            "name": "{WALLET_NAME}",
            "isFeatured": {BOOL},
            "featuredNote": "{NOTE_SHOWN_WHEN_FEATURED}",
            "order": {SORT_ORDER}
        }
    ],
    "checkoutConfig": { // OPTIONAL — hosted checkout branding
        "logoURL": "{LOGO_URL}",
        "termNotice": "{TERMS_NOTICE_TEXT}",
        "theme": {
            "primaryColor": "{HEX_COLOR}",
            "accentColor": "{HEX_COLOR}",
            "backgroundColor": "{HEX_COLOR}",
            "textColor": "{HEX_COLOR}"
        },
        "fonts": {
            "family": "{FONT_FAMILY}",
            "familyURL": "{FONT_URL}"
        },
        "flow": {
            "hideNoWalletOption": {BOOL},
            "showApprovalPage": {BOOL},
            "skipConfirmationPage": {BOOL}
        }
    },
    "cryptoNetworkConfigs": { // OPTIONAL
        "{NETWORK_NAME}": {
            "cryptoAssetConfigs": {
                "{ASSET_NAME}": {
                    "minConfirmsLow": {MIN_CONFIRMS_LOW},
                    "minConfirmsHigh": {MIN_CONFIRMS_HIGH},
                    "qrExpirationSeconds": {QR_EXPIRATION_SECONDS}
                }
            }
        }
    },
    "highThreshold": {HIGH_VALUE_THRESHOLD}, // OPTIONAL
    "refundWindowHours": {HOURS}, // OPTIONAL
    "support": { // OPTIONAL — support contact shown at checkout
        "email": "{SUPPORT_EMAIL}",
        "link": "{SUPPORT_URL}"
    },
    "fees": { // OPTIONAL — platform fee schedule
        "lydian": {
            "collection": "{deduct|bill_separately}",
            "perTransaction": { "basisPoints": {BPS}, "flatCents": {CENTS} },
            "perSettlement": { "basisPoints": {BPS}, "flatCents": {CENTS} },
            "split": { "lydianShareBps": {BPS}, "partnerID": "{PARTNER_ID}" }
        },
        "partner": {
            "customer": { "basisPoints": {BPS}, "flatCents": {CENTS} },
            "mdr": { "basisPoints": {BPS}, "flatCents": {CENTS} }
        }
    },
    "transactionFee": {FEE}, // OPTIONAL — billing schedule, see note below
    "transactionFeeRate": {RATE}, // OPTIONAL
    "settlementFee": {FEE}, // OPTIONAL
    "authorizationFee": {FEE}, // OPTIONAL
    "complianceFee": {FEE}, // OPTIONAL
    "annualComplianceFee": {FEE}, // OPTIONAL
    "complianceStartDate": "{DATE}", // OPTIONAL
    "complianceEndDate": "{DATE}", // OPTIONAL
    "oneTimeKYCFee": {FEE}, // OPTIONAL
    "oneTimeEquipmentFee": {FEE}, // OPTIONAL
    "oneTimeTerminationFee": {FEE}, // OPTIONAL
    "oneTimeWeb3SecurityFee": {FEE}, // OPTIONAL
    "monthlyProcessingFee": {FEE}, // OPTIONAL
    "monthlyNonProcessingFee": {FEE}, // OPTIONAL
    "monthlyAPIDataFee": {FEE}, // OPTIONAL
    "monthlyDashboardFee": {FEE}, // OPTIONAL
    "monthlyEquipmentFee": {FEE}, // OPTIONAL
    "monthlyPremiumSupportFee": {FEE}, // OPTIONAL
    "monthlyTerminalRentalFee": {FEE}, // OPTIONAL
    "terminalLeaseFee": {FEE}, // OPTIONAL
    "terminalLeaseStartDate": "{DATE}", // OPTIONAL
    "terminalLeaseEndDate": "{DATE}", // OPTIONAL
    "web3SecurityFee": {FEE}, // OPTIONAL
    "web3SecurityStartDate": "{DATE}", // OPTIONAL
    "web3SecurityEndDate": "{DATE}" // OPTIONAL
}'
```

> **Note:** The fee fields (`transactionFee` through `web3SecurityEndDate`) make up the
> account's billing schedule, normally managed with your Lydian account manager.
> All fields are optional — omit anything you don't want to change.

The response is the updated configuration — same structure as the
[Get Account Configuration Response](#get-account-configuration-response).

---

# Merchant

Source: https://developer.lydian.com/api/merchant
Markdown: https://developer.lydian.com/api/merchant.md

A merchant for the account is created by default. You can also create multiple merchants associated to the same account.

For how accounts and merchants relate, see [Accounts & Merchants](https://developer.lydian.com/concepts/accounts-and-merchants.md).

## The Merchant Object

The merchant endpoints below return a merchant object. The merchant's profile and configuration are nested
inside `unifiedConfig`; `inherit` and `canSet` control which settings come from the parent account and which can
be changed at the merchant level.

- `createdAt` (string): Created at date time of the merchant.
- `updatedAt` (string): Updated at date time of the merchant.
- `UUID` (string): Unique identifier for the merchant.
- `unifiedConfig` (object): The merchant's profile and configuration, including:
  - `name` (string): Name of the merchant.
  - `dba` (string): Doing business as name of the merchant.
  - `descriptor` (string): Descriptor of the merchant.
  - `logoFilename` (string): File name of the merchant's logo.
  - `status` (number): Status of the merchant: `0` under review, `1` enabled, `-1` disabled, `-2` archived.
  - `address1` (string): Street address 1 of the merchant.
  - `address2` (string): Street address 2 of the merchant.
  - `city` (string): City of the merchant.
  - `region` (string): Region or state of the merchant.
  - `country` (string): Country of the merchant.
  - `allowedAssets` (array): Assets the merchant accepts. Each asset has a `code` (for example `USDT`), a `type`
    (`coin` or `token`), and `networks`, an array of network names.
  - `allowedWallets` (array): Names of the wallets allowed at checkout.
  - `allowedWalletsConfig` (array): Per-wallet checkout presentation. Each entry has `name`, `isFeatured`, `featuredNote`,
    and `order`.
  - `cryptoNetworkConfigs` (object): Per-network settings, keyed by network name. Each network has `cryptoAssetConfigs`, keyed
    by asset, with `minConfirmsLow`, `minConfirmsHigh`, and `qrExpirationSeconds`.
  - `defaultRecommendedNetwork` (string): Network recommended to customers by default at checkout.
  - `kycEnabled` (boolean): Whether KYC verification is enabled.
  - `kycThreshold` (number): Amount, in local currency, at which KYC verification is required.
  - `kycThresholdCustodial` (number): KYC threshold applied when paying from a custodial wallet.
  - `travelRulesRegionalThreshold` (object): Travel rule thresholds in local currency, keyed by region.
  - `travelRulesRegionalThresholdCustodial` (object): Travel rule thresholds applied when paying from a custodial wallet, keyed by region.
  - `fees` (object): Platform fee schedule. `lydian` has `perTransaction` and `perSettlement` fees, `collection`
    (`deduct` or `bill_separately`), and, when set, `split` (`lydianShareBps`, `partnerID`).
    `partner` has `mdr`, `customer`, and `markup` fees. Each fee has `basisPoints` and
    `flatCents`.
  - `cancelTransactionEnabled` (boolean): Whether customers may cancel an in-progress transaction.
  - `checkoutConfig` (object): Hosted checkout branding: `logoURL`, `termNotice`, `theme` (`primaryColor`,
    `accentColor`, `backgroundColor`, `textColor`), `fonts` (`family`, `familyURL`), and
    `flow` (`assetFirst`, `showApprovalPage`, `hideNoWalletOption`).
  - `highThreshold` (number): High-value transaction threshold.
  - `merchantDiscountRate` (object): Merchant discount rate applied per transaction: `percentage` (a fraction — 0.025 is
    2.5%), `flatRate` (flat fee in `flatRateCurrency` units), and `flatRateCurrency`
    (ISO 4217).
  - `settlementFrequency` (string): How often the merchant is settled. One of `hourly`, `six_hourly`, `daily`, `weekly`,
    `biweekly`, or `monthly`.
  - `settlementAnchor` (string): Timestamp anchoring the settlement schedule.
  - `refundWindowHours` (number): Number of hours after a payment during which it can be refunded.
- `accountID` (string): Account ID of the merchant.
- `canSet` (object): Boolean flags for which settings may be changed at the merchant level, including
  `canSetCheckoutConfig`, `canSetAllowedWallets`, `canSetAllowedAssets`, `canSetCryptoNetworkConfigs`,
  `canSetDefaultRecommendedNetwork`, `canSetHighThreshold`, `canSetKYCEnabled`, `canSetKYCThreshold`,
  `canSetRefundWindowHours`, `canSetSettlement`, and `canSetTravelRulesRegionalThreshold`.
- `externalMID` (string): External merchant id of the merchant.
- `inherit` (object): Boolean flags for which settings the merchant takes from its parent account: `inheritCheckoutConfig`,
  `inheritAllowedWallets`, `inheritAllowedAssets`, `inheritCryptoNetworkConfigs`,
  `inheritDefaultRecommendedNetwork`, `inheritHighThreshold`, `inheritKYCEnabled`, `inheritKYCThreshold`,
  `inheritRefundWindowHours`, `inheritSettlement`, `inheritTravelRulesRegionalThreshold`,
  `inheritLydianFees`, and `inheritPartnerFees`.

**merchant object**

```json
{
    "createdAt": "2025-08-12T03:20:02.769Z",
    "updatedAt": "2025-08-12T03:20:02.769Z",
    "UUID": "b9280199-ab1b-4545-a625-1728ba354abf",
    "unifiedConfig": {
        "name": "Brimspire",
        "dba": "Brimspire",
        "descriptor": "",
        "logoFilename": "",
        "status": 1,
        "address1": "75831 Marvin Lodge",
        "address2": "",
        "city": "Janyport",
        "region": "VA",
        "country": "US",
        "allowedAssets": [
            {
                "code": "USDT",
                "type": "token",
                "networks": ["ethereum"]
            }
        ],
        "allowedWallets": [],
        "allowedWalletsConfig": [],
        "cryptoNetworkConfigs": {
            "ethereum": {
                "cryptoAssetConfigs": {
                    "USDT": {
                        "minConfirmsLow": 1,
                        "minConfirmsHigh": 3,
                        "qrExpirationSeconds": 900
                    }
                }
            }
        },
        "defaultRecommendedNetwork": "ethereum",
        "kycEnabled": false,
        "kycThreshold": 1000,
        "kycThresholdCustodial": 0,
        "travelRulesRegionalThreshold": {},
        "travelRulesRegionalThresholdCustodial": {},
        "fees": {
            "partner": {
                "mdr": { "basisPoints": 0, "flatCents": 0 },
                "customer": { "basisPoints": 0, "flatCents": 0 },
                "markup": { "basisPoints": 0, "flatCents": 0 }
            },
            "lydian": {
                "perTransaction": { "basisPoints": 100, "flatCents": 0 },
                "perSettlement": { "basisPoints": 0, "flatCents": 0 },
                "collection": "deduct"
            }
        },
        "cancelTransactionEnabled": false,
        "checkoutConfig": {
            "theme": {
                "primaryColor": "#0A0A0A",
                "accentColor": "#3B82F6",
                "backgroundColor": "#FFFFFF",
                "textColor": "#111111"
            },
            "fonts": {
                "family": "",
                "familyURL": ""
            },
            "flow": {
                "assetFirst": false,
                "showApprovalPage": false,
                "hideNoWalletOption": false
            },
            "logoURL": "",
            "termNotice": ""
        },
        "highThreshold": 1000,
        "merchantDiscountRate": {
            "percentage": 0.025,
            "flatRate": 0,
            "flatRateCurrency": ""
        },
        "settlementFrequency": "daily",
        "settlementAnchor": "2025-01-01T00:00:00Z",
        "refundWindowHours": 720
    },
    "accountID": "33c0dadc-bd86-45ae-b4d6-62f149313701",
    "canSet": {
        "canSetCheckoutConfig": true,
        "canSetAllowedWallets": true,
        "canSetAllowedAssets": true,
        "canSetCryptoNetworkConfigs": true,
        "canSetDefaultRecommendedNetwork": true,
        "canSetHighThreshold": true,
        "canSetKYCEnabled": true,
        "canSetKYCThreshold": true,
        "canSetRefundWindowHours": true,
        "canSetSettlement": true,
        "canSetTravelRulesRegionalThreshold": true
    },
    "externalMID": "1ecf316f-0821-46d4-820c-5d9313a5569c",
    "inherit": {
        "inheritCheckoutConfig": true,
        "inheritAllowedWallets": true,
        "inheritAllowedAssets": true,
        "inheritCryptoNetworkConfigs": true,
        "inheritDefaultRecommendedNetwork": true,
        "inheritHighThreshold": true,
        "inheritKYCEnabled": true,
        "inheritKYCThreshold": true,
        "inheritRefundWindowHours": true,
        "inheritSettlement": true,
        "inheritTravelRulesRegionalThreshold": true,
        "inheritLydianFees": true,
        "inheritPartnerFees": true
    }
}
```

## Create Merchant

**Endpoint:** `POST /accounts/{accountUUID}/merchants`

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/merchants' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "{MERCHANT_NAME}",
    "dba": "{DBA_NAME}", // OPTIONAL
    "address1": "{STREET_ADDRESS_1}",
    "address2": "{STREET_ADDRESS_2}", // OPTIONAL
    "city": "{CITY}",
    "region": "{REGION/STATE}",
    "country": "{COUNTRY}",
    "merchantDiscountRate": { // OPTIONAL — percentage and/or flat fee per transaction
        "percentage": {RATE_FRACTION},        // 0.025 = 2.5%
        "flatRate": {FLAT_FEE},               // in flatRateCurrency units
        "flatRateCurrency": "{CURRENCY_CODE}" // ISO 4217
    },
    "externalMID": "{EXTERNAL_MERCHANT_ID}", // OPTIONAL
    "logoFilename": "{LOGO_FILENAME}", // OPTIONAL — usually set via the upload logo endpoint
    "highThreshold": {HIGH_VALUE_THRESHOLD}, // OPTIONAL
    "kycEnabled": {KYC_ENABLED}, // OPTIONAL
    "kycThreshold": {KYC_THRESHOLD}, // OPTIONAL
    "kycThresholdCustodial": {KYC_THRESHOLD}, // OPTIONAL — applied when paying from a custodial wallet
    "refundWindowHours": {HOURS}, // OPTIONAL
    "allowedWallets": ["{WALLET_NAME}"], // OPTIONAL — names of wallets allowed at checkout
    "allowedWalletsConfig": [ // OPTIONAL — per-wallet checkout presentation
        {
            "name": "{WALLET_NAME}",
            "isFeatured": {BOOL},
            "featuredNote": "{NOTE_SHOWN_WHEN_FEATURED}",
            "order": {SORT_ORDER}
        }
    ],
    "cryptoNetworkConfigs": { // OPTIONAL
        "{NETWORK_NAME}": {
            "cryptoAssetConfigs": {
                "{ASSET_NAME}": {
                    "minConfirmsLow": {MIN_CONFIRMS_LOW},
                    "minConfirmsHigh": {MIN_CONFIRMS_HIGH},
                    "qrExpirationSeconds": {QR_EXPIRATION_SECONDS}
                }
            }
        }
    },
    "travelRulesRegionalThreshold": { // OPTIONAL
        "{REGION}": {THRESHOLD_IN_LOCAL_CURRENCY}
    },
    "travelRulesRegionalThresholdCustodial": { // OPTIONAL — applied when paying from a custodial wallet
        "{REGION}": {THRESHOLD_IN_LOCAL_CURRENCY}
    },
    "checkoutConfig": { // OPTIONAL — hosted checkout branding
        "logoURL": "{LOGO_URL}",
        "termNotice": "{TERMS_NOTICE_TEXT}",
        "theme": {
            "primaryColor": "{HEX_COLOR}",
            "accentColor": "{HEX_COLOR}",
            "backgroundColor": "{HEX_COLOR}",
            "textColor": "{HEX_COLOR}"
        },
        "fonts": {
            "family": "{FONT_FAMILY}",
            "familyURL": "{FONT_URL}"
        },
        "flow": {
            "assetFirst": {BOOL},
            "showApprovalPage": {BOOL},
            "hideNoWalletOption": {BOOL}
        }
    },
    "inherit": { // OPTIONAL — take these settings from the parent account
        "inheritCheckoutConfig": {BOOL},
        "inheritAllowedWallets": {BOOL},
        "inheritAllowedAssets": {BOOL},
        "inheritCryptoNetworkConfigs": {BOOL},
        "inheritDefaultRecommendedNetwork": {BOOL},
        "inheritHighThreshold": {BOOL},
        "inheritKYCEnabled": {BOOL},
        "inheritKYCThreshold": {BOOL},
        "inheritRefundWindowHours": {BOOL},
        "inheritSettlement": {BOOL},
        "inheritTravelRulesRegionalThreshold": {BOOL},
        "inheritLydianFees": {BOOL},
        "inheritPartnerFees": {BOOL}
    },
    "canSet": { // OPTIONAL — which settings may be overridden at the merchant level
        "canSetCheckoutConfig": {BOOL},
        "canSetAllowedWallets": {BOOL},
        "canSetAllowedAssets": {BOOL},
        "canSetCryptoNetworkConfigs": {BOOL},
        "canSetDefaultRecommendedNetwork": {BOOL},
        "canSetHighThreshold": {BOOL},
        "canSetKYCEnabled": {BOOL},
        "canSetKYCThreshold": {BOOL},
        "canSetRefundWindowHours": {BOOL},
        "canSetSettlement": {BOOL},
        "canSetTravelRulesRegionalThreshold": {BOOL}
    }
}'
```

### Create Merchant Response

Returns the created merchant as a [merchant object](#the-merchant-object), with the merchant's stored values.

### Create Merchant Errors

When a merchant cannot be created, the API returns one of the responses below.

| HTTP status | `errorCode` | `message`                   | When                                                                                                                                                                     |
| ----------- | ----------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`       | `602`       | `Validation failure: …`     | The request fails validation — a missing or invalid `accountUUID`, a malformed JSON body, or a missing required field (`name`, `address1`, `city`, `region`, `country`). |
| `401`       | —           | `Unauthorized`              | Authentication is missing or invalid.                                                                                                                                    |
| `403`       | —           | `Forbidden`                 | The caller is authenticated but lacks permission to create merchants.                                                                                                    |
| `422`       | `723`       | `Unable to create merchant` | The merchant could not be created — including when the `externalMID` is already used by another merchant in the same account (see below).                                |

Responses that carry an `errorCode` use the JSON object shown below. The `401` and `403` responses are an exception: each returns a plain-text body (`Unauthorized` or `Forbidden`) and no `errorCode`.

- `errorCode` (number): Numeric Lydian error code identifying the failure.
- `message` (string): Human-readable description of the failure.

**error response**

```json
{
    "errorCode": 723,
    "message": "Unable to create merchant"
}
```

> **Note:** A non-empty `externalMID` must be unique among the merchants in the same account — two merchants in one
> account cannot share the same `externalMID`. Reusing one returns HTTP `422` with `errorCode` `723`; the
> response does not distinguish it from other creation failures. The constraint is scoped to the account, so
> different accounts may use the same `externalMID`, and an empty `externalMID` is not subject to it.

## Update Merchant

**Endpoint:** `PUT /accounts/{accountUUID}/merchants/{merchantUUID}`

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/merchants/{merchantUUID}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "{MERCHANT_NAME}",
    "dba": "{DBA_NAME}", // OPTIONAL
    "address1": "{STREET_ADDRESS_1}",
    "address2": "{STREET_ADDRESS_2}", // OPTIONAL
    "city": "{CITY}",
    "region": "{REGION/STATE}",
    "country": "{COUNTRY}",
    "merchantDiscountRate": { // OPTIONAL — percentage and/or flat fee per transaction
        "percentage": {RATE_FRACTION},        // 0.025 = 2.5%
        "flatRate": {FLAT_FEE},               // in flatRateCurrency units
        "flatRateCurrency": "{CURRENCY_CODE}" // ISO 4217
    },
    "allowedAssets": [ // OPTIONAL — assets the merchant accepts
        {
            "code": "{ASSET_CODE}",
            "type": "{coin|token}",
            "networks": ["{NETWORK_NAME}"]
        }
    ],
    "allowedWallets": ["{WALLET_NAME}"], // OPTIONAL — names of wallets allowed at checkout
    "allowedWalletsConfig": [ // OPTIONAL — per-wallet checkout presentation
        {
            "name": "{WALLET_NAME}",
            "isFeatured": {BOOL},
            "featuredNote": "{NOTE_SHOWN_WHEN_FEATURED}",
            "order": {SORT_ORDER}
        }
    ],
    "cancelTransactionEnabled": {CANCEL_TRANSACTION_ENABLED}, // OPTIONAL
    "logoFilename": "{LOGO_FILENAME}", // OPTIONAL — usually set via the upload logo endpoint
    "highThreshold": {HIGH_VALUE_THRESHOLD}, // OPTIONAL
    "kycEnabled": {KYC_ENABLED}, // OPTIONAL
    "kycThreshold": {KYC_THRESHOLD}, // OPTIONAL
    "kycThresholdCustodial": {KYC_THRESHOLD}, // OPTIONAL — applied when paying from a custodial wallet
    "refundWindowHours": {HOURS}, // OPTIONAL
    "cryptoNetworkConfigs": { // OPTIONAL
        "{NETWORK_NAME}": {
            "cryptoAssetConfigs": {
                "{ASSET_NAME}": {
                    "minConfirmsLow": {MIN_CONFIRMS_LOW},
                    "minConfirmsHigh": {MIN_CONFIRMS_HIGH},
                    "qrExpirationSeconds": {QR_EXPIRATION_SECONDS}
                }
            }
        }
    },
    "travelRulesRegionalThreshold": { // OPTIONAL
        "{REGION}": {THRESHOLD_IN_LOCAL_CURRENCY}
    },
    "travelRulesRegionalThresholdCustodial": { // OPTIONAL — applied when paying from a custodial wallet
        "{REGION}": {THRESHOLD_IN_LOCAL_CURRENCY}
    },
    "checkoutConfig": { // OPTIONAL — hosted checkout branding
        "logoURL": "{LOGO_URL}",
        "termNotice": "{TERMS_NOTICE_TEXT}",
        "theme": {
            "primaryColor": "{HEX_COLOR}",
            "accentColor": "{HEX_COLOR}",
            "backgroundColor": "{HEX_COLOR}",
            "textColor": "{HEX_COLOR}"
        },
        "fonts": {
            "family": "{FONT_FAMILY}",
            "familyURL": "{FONT_URL}"
        },
        "flow": {
            "assetFirst": {BOOL},
            "showApprovalPage": {BOOL},
            "hideNoWalletOption": {BOOL}
        }
    },
    "feeConfig": { // OPTIONAL — platform fee schedule
        "lydian": {
            "collection": "{deduct|bill_separately}",
            "perTransaction": { "basisPoints": {BPS}, "flatCents": {CENTS} },
            "perSettlement": { "basisPoints": {BPS}, "flatCents": {CENTS} },
            "split": { "lydianShareBps": {BPS}, "partnerID": "{PARTNER_ID}" }
        },
        "partner": {
            "customer": { "basisPoints": {BPS}, "flatCents": {CENTS} },
            "mdr": { "basisPoints": {BPS}, "flatCents": {CENTS} },
            "markup": { "basisPoints": {BPS}, "flatCents": {CENTS} }
        }
    },
    "inherit": { // OPTIONAL — take these settings from the parent account
        "inheritCheckoutConfig": {BOOL},
        "inheritAllowedWallets": {BOOL},
        "inheritAllowedAssets": {BOOL},
        "inheritCryptoNetworkConfigs": {BOOL},
        "inheritDefaultRecommendedNetwork": {BOOL},
        "inheritHighThreshold": {BOOL},
        "inheritKYCEnabled": {BOOL},
        "inheritKYCThreshold": {BOOL},
        "inheritRefundWindowHours": {BOOL},
        "inheritSettlement": {BOOL},
        "inheritTravelRulesRegionalThreshold": {BOOL},
        "inheritLydianFees": {BOOL},
        "inheritPartnerFees": {BOOL}
    },
    "canSet": { // OPTIONAL — which settings may be overridden at the merchant level
        "canSetCheckoutConfig": {BOOL},
        "canSetAllowedWallets": {BOOL},
        "canSetAllowedAssets": {BOOL},
        "canSetCryptoNetworkConfigs": {BOOL},
        "canSetDefaultRecommendedNetwork": {BOOL},
        "canSetHighThreshold": {BOOL},
        "canSetKYCEnabled": {BOOL},
        "canSetKYCThreshold": {BOOL},
        "canSetRefundWindowHours": {BOOL},
        "canSetSettlement": {BOOL},
        "canSetTravelRulesRegionalThreshold": {BOOL}
    }
}'
```

### Update Merchant Response

Returns the updated merchant as a [merchant object](#the-merchant-object), with the merchant's stored values.

## List Merchants

**Endpoint:** `GET /accounts/{accountUUID}/merchants`

**cURL**

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/merchants?limit={LIMIT}&page={PAGE}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

### List Merchants Response

Each element of `merchants` is a [merchant object](#the-merchant-object) with the merchant's stored values.

- `merchants` (array): List of [merchant objects](#the-merchant-object) associated with this account.
- `metadata` (object): Pagination metadata for the query.

  **Metadata Object**
  - `totalCount` (number): Total number of items available across all pages for the query.
  - `count` (number): Number of items returned in the current page.
  - `page` (number): Current page number (1-based).
  - `pageSize` (number): Maximum number of items per page.

**example response (merchant objects abbreviated)**

```json
{
    "merchants": [
        {
            "createdAt": "2025-08-12T03:20:02.769Z",
            "updatedAt": "2025-08-12T03:20:02.769Z",
            "UUID": "b9280199-ab1b-4545-a625-1728ba354abf",
            "unifiedConfig": {
                "name": "Brimspire",
                "status": 1
            },
            "accountID": "33c0dadc-bd86-45ae-b4d6-62f149313701",
            "externalMID": "1ecf316f-0821-46d4-820c-5d9313a5569c"
        }
    ],
    "metadata": {
        "totalCount": 1,
        "count": 1,
        "page": 1,
        "pageSize": 10
    }
}
```

## Get Merchant

**Endpoint:** `GET /accounts/{accountUUID}/merchants/{MerchantUUID}`

**cURL**

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/merchants/{MerchantUUID}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

### Get Merchant Response

Returns a [merchant object](#the-merchant-object) with inherited settings resolved. For each setting whose
`inherit` flag is `true`, the response contains the parent account's current value for that setting instead of the
merchant's stored value; when the flag is `false`, the merchant's own stored value is returned. Inherited values
replace the merchant's value as a whole and are not merged. This happens only when the merchant is read: the stored
merchant is not changed, and the `inherit` flags are returned as stored.

Create Merchant, Update Merchant, and List Merchants return the merchant's stored values without this resolution.

## Get Merchant by External MID

Look up a merchant in an account by its `externalMID`, the merchant identifier you assigned (for example, your
own merchant or store ID). The lookup is scoped to the account in the path and matches the `externalMID` exactly:
the match is case-sensitive, and partial or prefix matches are not supported. Because a non-empty `externalMID` is
unique within an account, at most one merchant is returned. Different accounts may use the same `externalMID`.

This endpoint requires account-level access with the `merchant:read` permission. When using an API Key, send it in
the `X-Api-Key` header; the `X-MID` header is not required. URL-encode the `externalMID` when placing it in the path.

**Endpoint:** `GET /accounts/{accountUUID}/merchantsbyexternalmid/{externalMID}`

**cURL**

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/merchantsbyexternalmid/{EXTERNAL_MID}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

### Get Merchant by External MID Response

Returns a [merchant object](#the-merchant-object), with inherited settings resolved the same way as
[Get Merchant](#get-merchant).

### Get Merchant by External MID Errors

| HTTP status | `errorCode` | `message`                   | When                                                                     |
| ----------- | ----------- | --------------------------- | ------------------------------------------------------------------------ |
| `403`       | —           | `Forbidden`                 | The caller lacks account-level access or the `merchant:read` permission. |
| `422`       | `724`       | `Unable to locate merchant` | No merchant in the account has exactly this `externalMID`.               |

- `errorCode` (number): Numeric Lydian error code identifying the failure.
- `message` (string): Human-readable description of the failure.

**error response**

```json
{
    "errorCode": 724,
    "message": "Unable to locate merchant"
}
```

## Archive Merchant

**Endpoint:** `DELETE /accounts/{accountUUID}/merchants/{merchantUUID}`

**cURL**

```bash
curl --location --request DELETE '{API_BASE_URL}/accounts/{AccountUUID}/merchants/{merchantUUID}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

Returns `204 No Content` on success.

## Upload Merchant Logo

**Endpoint:** `POST /accounts/{accountUUID}/merchants/{merchantUUID}/uploadlogo`

**cURL**

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/merchants/{merchantUUID}/uploadlogo' \
--header 'X-Api-Key: {API_KEY}' \
--form 'file=@"{PATH_TO_LOGO_FILE}"'
```

Returns `200 OK` with the URL of the uploaded logo:

```json
{
    "url": "{LOGO_URL}"
}
```

## Get Merchant Configuration

Returns the effective checkout configuration for a merchant — what coins/tokens are accepted and
how checkout behaves — as set up in the Lydian Merchant Dashboard. Unlike the endpoints above,
this one authenticates with the merchant's Publishable Key, so frontends can call it directly.

**Endpoint:** `GET /merchant/config`

**cURL**

```bash
curl --location '{API_BASE_URL}/merchant/config' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json'
```

**NodeJS**

```javascript
var request = require('request')
var options = {
  method: 'GET',
  url: '{API_BASE_URL}/merchant/config',
  headers: {
    'X-Publishable-Key': '{PUBLISHABLE_KEY}',
    'Content-Type': 'application/json',
  },
}
request(options, function (error, response) {
  if (error) throw new Error(error)
  console.log(response.body)
})
```

**Go**

```go
    package main

    import (
    "fmt"
    "net/http"
    "io"
    )

    func main() {

    url := "{API_BASE_URL}/merchant/config"
    method := "GET"

    client := &http.Client {
}
    req, err := http.NewRequest(method, url, nil)

    if err != nil {
    fmt.Println(err)
    return
}
    req.Header.Add("X-Publishable-Key", "{PUBLISHABLE_KEY}")
    req.Header.Add("Content-Type", "application/json")

    res, err := client.Do(req)
    if err != nil {
    fmt.Println(err)
    return
}
    defer res.Body.Close()

    body, err := io.ReadAll(res.Body)
    if err != nil {
    fmt.Println(err)
    return
}
    fmt.Println(string(body))
}
```

**PHP**

```php
    <?php

    $curl = curl_init();

    curl_setopt_array($curl, array(
    CURLOPT_URL => '{API_BASE_URL}/merchant/config',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => array(
    'X-Publishable-Key: {PUBLISHABLE_KEY}',
    'Content-Type: application/json'
    ),
    ));

    $response = curl_exec($curl);

    curl_close($curl);
    echo $response;
```

> **Note:** For processors with submerchants, the publishable key for the submerchants is composed by appending\
> `:{YOUR_MERCHANT_IDENTIFIER}` to your primary publishable key.

### Get Merchant Configuration Response

- `allowedAssets` (array): List of asset objects approved for crypto payments.

  **Asset Object**
  - `code` (string): Unique code identifier for the asset (e.g. `USDT`).
  - `type` (string): Asset classification (e.g. `token`, `coin`).
  - `networks` (array): Supported networks for this asset.
- `cancelTransactionEnabled` (boolean): Whether the merchant allows customers to cancel an in-progress transaction.
- `checkoutConfig` (object): Hosted checkout branding for the merchant.
  - `logoURL` (string): Logo shown at checkout.
  - `termNotice` (string): Terms notice text shown at checkout.
  - `theme` (object): Colors: `primaryColor`, `accentColor`, `backgroundColor`, `textColor`.
  - `fonts` (object): Font settings: `family`, `familyURL`.
  - `flow` (object): Checkout flow switches: `hideNoWalletOption`, `showApprovalPage`,
    `assetFirst`.
- `settlementFrequency` (string): How often the merchant is settled. One of `hourly`, `six_hourly`, `daily`, `weekly`,
  `biweekly`, or `monthly`.
- `settlementAnchor` (string): Timestamp anchoring the settlement schedule.
- `support` (object): Merchant support contact details shown during checkout.
  - `email` (string): Support email address.
  - `link` (string): Support URL.

**example response**

```json
{
    "allowedAssets": [
        {
            "code": "USDT",
            "type": "token",
            "networks": [
                "ethereum",
                "polygon"
            ]
        }
    ],
    "cancelTransactionEnabled": true,
    "checkoutConfig": {
        "logoURL": "https://assets.lydian.com/merchants/brimspire/logo.png",
        "termNotice": "",
        "theme": {
            "primaryColor": "#0A0A0A",
            "accentColor": "#3B82F6",
            "backgroundColor": "#FFFFFF",
            "textColor": "#111111"
        },
        "fonts": {
            "family": "",
            "familyURL": ""
        },
        "flow": {
            "hideNoWalletOption": false,
            "showApprovalPage": false,
            "assetFirst": false
        }
    },
    "settlementFrequency": "daily",
    "settlementAnchor": "2025-01-01T00:00:00Z",
    "support": {
        "email": "support@brimspire.com",
        "link": "https://brimspire.com/support"
    }
}
```

> **Note:** Configuration for a merchant can be updated using [Update Merchant](#update-merchant).

---

# Session

Source: https://developer.lydian.com/api/session
Markdown: https://developer.lydian.com/api/session.md

A Session is a short‑lived, single‑purpose container that coordinates a payment from the customer to the merchant. It holds the context needed to complete a checkout - who is paying, how much, which asset and network is used (e.g., USDT on Ethereum), and how the result is reported - so clients and servers can safely move a payment from start to finish.

Session endpoints accept either a **Publishable Key** (`X-Publishable-Key`) or an **API Key** (`X-Api-Key` with `X-MID`). The FX-rate override fields (`fiatFXRate`, `fiatFXRateExpirationSeconds`, `cryptoFXRates`) are honored only with an API Key, for merchants with the *Can set FX rate* permission.

For how sessions and transactions relate, see [Sessions & Transactions](https://developer.lydian.com/concepts/sessions-and-transactions.md). For the end-to-end flow, see [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md). For status values, see [Payment Lifecycle & Statuses](https://developer.lydian.com/concepts/payment-lifecycle.md).

## Create Session

**Endpoint:** `POST /session`

```bash
curl --location '{API_BASE_URL}/session' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "descriptor": "{OPTIONAL_DESCRIPTOR}",
    "referenceNumber": "{OPTIONAL_REFERENCE_NUMBER}",
    "amount": {AMOUNT_IN_FLOAT},
    "amountCurrency": "{CURRENCY_CODE}",
    "successURL": "{SUCCESS_URL}", // OPTIONAL — redirect on success
    "cancelURL": "{CANCEL_URL}",   // OPTIONAL — redirect on cancel
    "failureURL": "{FAILURE_URL}", // OPTIONAL — redirect on failure
    "fiatFXRate": {FX_RATE_IN_FLOAT},          // OPTIONAL (API Key only)
    "fiatFXRateExpirationSeconds": {SECONDS},  // OPTIONAL (API Key only, required with fiatFXRate)
    "cryptoFXRates": { "{ASSET}": {RATE_IN_FLOAT} }, // OPTIONAL (API Key only)
    "customFlatFeePerNetwork": { "{NETWORK}": {FEE} },       // OPTIONAL — mutually exclusive with customFeePercentagePerNetwork
    "customFeePercentagePerNetwork": { "{NETWORK}": {PCT} }, // OPTIONAL — mutually exclusive with customFlatFeePerNetwork
    "recommendedNetwork": "{CRYPTO_NETWORK}", // OPTIONAL — network preselected at checkout
    "quoteID": "{QUOTE_ID}", // OPTIONAL
    "optional": { // OPTIONAL — prefill customer details when KYC is required
        "firstName": "{FIRST_NAME}",
        "lastName": "{LAST_NAME}",
        "email": "{EMAIL}",
        "street1": "{STREET_1}",
        "street2": "{STREET_2}",
        "city": "{CITY}",
        "region": "{REGION}",
        "postalCode": "{POSTAL_CODE}",
        "country": "{COUNTRY_CODE}"
    }
}'
```

> **Note:** The FX-rate overrides (`fiatFXRate`, `fiatFXRateExpirationSeconds`, `cryptoFXRates`) require the
> API Key — see [API Key vs Publishable Key](https://developer.lydian.com/concepts/api-keys.md) — and are only honored for
> merchants with the *Can set FX rate* permission.

### Create Session Response

- `sessionID` (string): Unique identifier for the session.
- `qrData` (string): The data to generate QR code that can be scanned using mobile devices.
- `successURL` (string): Redirect URL used on a successful payment.
- `cancelURL` (string): Redirect URL used when the session is cancelled.
- `failureURL` (string): Redirect URL used on a failed payment.
- `fiatFXRate` (number): The fiat FX rate locked in for the session, when provided.
- `recommendedNetwork` (string): Network recommended to the customer at checkout, when provided.
- `quoteID` (string): Quote identifier associated with the session, when provided.

**example response**

```json
{
    "sessionID": "009a3809-7328-4b6c-873b-089eff019f98",
    "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98",
    "successURL": "https://brimspire.com/checkout/success",
    "cancelURL": "https://brimspire.com/checkout/cancel",
    "failureURL": "https://brimspire.com/checkout/failure",
    "fiatFXRate": 1,
    "recommendedNetwork": "ethereum",
    "quoteID": ""
}
```

## Get Session

It is possible to poll the session to retrieve its current status and the transaction ID once the customer has selected asset and network. The status of the transaction can be received via webhook or can be polled using [Get Transaction](https://developer.lydian.com/api/transaction.md#get-transaction) api call.

**Endpoint:** `GET /session/{sessionID}`

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

### Get Session Response

- `createdAt` (string): Created at date time of the session.
- `updatedAt` (string): Updated at date time of the session.
- `sessionID` (string): Unique identifier for the session.
- `merchantID` (string): Unique identifier for the merchant.
- `accountID` (string): Unique identifier for the account.
- `descriptor` (string): Human‑readable descriptor for the session.
- `externalMID` (string): External merchant ID (e.g., from a partner or POS).
- `referenceNumber` (string): Merchant reference or order number for reconciliation.
- `amount` (number): Payment amount.
- `amountCurrency` (string): Currency code for the amount (ISO 4217, e.g., USD).
- `qrData` (string): QR payload/URL the customer scans to choose asset/network and authorize the amount.
- `status` (string): Current session status: `0` pending, `1` success.
- `expiration` (string): Expiration date/time for the session.
- `transactionID` (string): Associated transaction ID, set after the customer selects an asset and network.
- `successURL` (string): Redirect URL used on a successful payment.
- `cancelURL` (string): Redirect URL used when the session is cancelled.
- `failureURL` (string): Redirect URL used on a failed payment.
- `fxRate` (number): Fiat FX rate locked in for the session, when provided.
- `fxRateExpiration` (string): Expiration date/time of the fiat FX rate.
- `cryptoFXRateExpiration` (string): Expiration date/time of the crypto FX rate.
- `recommendedNetwork` (string): Network recommended to the customer at checkout, when provided.
- `quoteID` (string): Quote identifier associated with the session, when provided.
- `optionalFields` (object): Prefilled customer details supplied when the session was created.

**example response**

```json
{
    "createdAt": "2025-11-18T17:00:24.26Z",
    "updatedAt": "2025-11-18T17:00:24.26Z",
    "sessionID": "009a3809-7328-4b6c-873b-089eff019f98",
    "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
    "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "descriptor": "Brimspire: Test!",
    "externalMID": "",
    "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
    "amount": 0.01,
    "amountCurrency": "USD",
    "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98",
    "status": 0,
    "expiration": "2025-11-18T17:15:24.26Z",
    "transactionID": "",
    "successURL": "https://brimspire.com/checkout/success",
    "cancelURL": "https://brimspire.com/checkout/cancel",
    "failureURL": "https://brimspire.com/checkout/failure",
    "fxRate": 1,
    "fxRateExpiration": "2025-11-18T17:15:24.26Z",
    "cryptoFXRateExpiration": "",
    "recommendedNetwork": "ethereum",
    "quoteID": "",
    "optionalFields": {}
}
```

## Create Session Transaction

Once the customer selects an asset and network, create a Transaction linked to the Session.

**Endpoint:** `POST /session/{sessionID}/transaction`

```bash
curl --location '{API_BASE_URL}/session/{SESSION_ID}/transaction' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "asset": "{ASSET}",
    "network": "{CRYPTO_NETWORK}",
    "wallet": "{CUSTOMER_WALLET_ADDRESS}",
    "cryptoFXRateExpirationSeconds": {SECONDS},  // OPTIONAL
    "transactionExpirationSeconds": {SECONDS},   // OPTIONAL
    "quoteID": "{QUOTE_ID}"                      // OPTIONAL
}'
```

The response is the same structure as the [Create Transaction Response](https://developer.lydian.com/api/transaction.md#create-transaction-response).

## Cancel Session

**Endpoint:** `PATCH /session/{sessionID}/cancel`

```bash
curl --location --request PATCH '{API_BASE_URL}/session/{SESSION_ID}/cancel' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}'
```

Returns `200 OK` on success.

---

# Transactions

Source: https://developer.lydian.com/api/transaction
Markdown: https://developer.lydian.com/api/transaction.md

You'll need to create a transaction to process any payment.

> **Note:** Depending on the merchant’s settings, KYC verification may be required before a transaction can proceed. If KYC is
> required, the API response includes `requiredFields` and `supportedDocumentTypes` and sets the transaction status to
> -3 (KYC Verification Pending). The `requiredFields` and `supportedDocumentTypes` can be submitted using the [Submit
> Customer Verification For Transaction](https://developer.lydian.com/api/transaction.md#submit-customer-verification-for-transaction) endpoint.

## Create Transaction

**Endpoint:** `POST /transaction`

```bash
curl --location '{API_BASE_URL}/transaction' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "descriptor": "{OPTIONAL_DESCRIPTOR}",
    "referenceNumber": "{OPTIONAL_REFERENCE_NUMBER}",
    "amount": {AMOUNT_IN_FLOAT},
    "amountCurrency": "{CURRENCY_CODE}",
    "asset": "{ASSET}",
    "network": "{CRYPTO_NETWORK}",
    "fxRate": {FX_RATE_IN_FLOAT}, // OPTIONAL (API Key only)
    "quoteID": "{QUOTE_ID}",      // OPTIONAL
    "optional": { // OPTIONAL — prefill customer details when KYC is required
        "firstName": "{FIRST_NAME}",
        "lastName": "{LAST_NAME}",
        "email": "{EMAIL}",
        "street1": "{STREET_1}",
        "street2": "{STREET_2}",
        "city": "{CITY}",
        "region": "{REGION}",
        "postalCode": "{POSTAL_CODE}",
        "country": "{COUNTRY_CODE}"
    }
}'
```

> **Note:** fxRate requires the API Key — see [API Key vs Publishable Key](https://developer.lydian.com/concepts/api-keys.md) —
> and is only honored for merchants with the *Can set FX rate* permission.

### Create Transaction Response

> **Note:** Create Transaction returns `transactionId` and `paymentRequestId`. Transaction objects returned by retrieval
> endpoints, such as [Get Transaction](#get-transaction), use `transactionID` and `paymentRequestID`.

- `transactionId` (string): Unique identifier for the transaction.
- `qrData` (string): The data to generate QR code that can be scanned using mobile devices.
- `address` (string): Wallet address to transfer funds to.
- `assetAmount` (string): Asset amount for the transaction.
- `additionalCustomerFee` (float): Any additional customer fees associated with transaction.
- `cryptoFXRate` (number): The crypto-to-USD FX rate locked in for the transaction.
- `paymentRequestId` (string): Identifier of the underlying payment request created for the transaction.
- `quoteID` (string): Quote identifier associated with the transaction, when provided.
- `status` (int): Transaction status. One of `-9` API Cancelled, `-8` Payment Timeout, `-7` Fraud Declined, `-6` Fraud
  Refunded, `-5` Fraud Refund Held, `-4` Forfeit, `-3` KYC Verification Pending, `-2` Cancelled, `-1`
  Fraud, `0` Pending, or `1` Success. See [Payment Lifecycle & Statuses](https://developer.lydian.com/concepts/payment-lifecycle.md).
- `requiredFields` (array): The list of required fields to proceed with KYC verification if the verification is required before
  proceeding with the transaction. List of fields can be any of the followings:
  - `firstName` (string): First name of the customer.
  - `lastName` (string): Last name of the customer.
  - `email` (string): Email of the customer.
  - `address` (string): Physical address of the customer. The complete address is required with the fields `street`,
    `city`, `region`, `postalCode`, and `country`.
- `supportedDocumentTypes` (array): List of supported document types for the KYC verification. It can be any one of the followings:
  - `ID_CARD` (string): Identity (ID) Card
  - `PASSPORT` (string): Passport
  - `RESIDENCE_PERMIT` (string): Residence Permit
  - `DRIVERS` (string): Drivers License

**example response**

```json
{
    "transactionId": "236118b0-b43e-421e-998d-0d0f84b99e5a",
    "qrData": "ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7/transfer?address=0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd\u0026uint256=9340000.000000\u0026amount=9.340000",
    "address": "0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
    "assetAmount": "9.34",
    "additionalCustomerFee": 1.25,
    "cryptoFXRate": 1.0001,
    "paymentRequestId": "a8f2c1e0-1234-4abc-9def-0123456789ab",
    "quoteID": "",
    "status": -3,
    "requiredFields": ["firstName", "lastName", "email", "address"],
    "supportedDocumentTypes": ["ID_CARD", "PASSPORT", "RESIDENCE_PERMIT", "DRIVERS"]
}
```

## Get Transaction

While a webhook will be sent to a specified endpoint when a transaction succeeds, it is possible to poll the transaction
to retrieve its current status.

**Endpoint:** `GET /transaction/{TRANSACTION_ID}`

```bash
curl --location --request GET '{API_BASE_URL}/transaction/{TRANSACTION_ID}' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json'
```

### Get Transaction Response

- `transactionID` (string): Unique identifier for the transaction.
- `accountID` (string): Account the transaction belongs to.
- `merchantID` (string): Merchant the transaction belongs to.
- `externalMID` (string): External merchant ID (e.g. from a partner or POS).
- `descriptor` (string): Human-readable descriptor for the transaction.
- `referenceNumber` (string): Merchant reference or order number.
- `quoteID` (string): Quote identifier associated with the transaction, when provided.
- `status` (number): Status of the transaction. `0` pending, `1` success, `-2` cancelled, `-3` waiting for KYC
  verification, `-4` forfeited.
- `paymentStatus` (number): Aggregate status of the transaction's payment requests.
- `amounts` (object): Monetary breakdown for the transaction.
  - `currency` (string): Local currency code (ISO 4217).
  - `totalLocal` (number): Total amount in local currency.
  - `totalUSD` (number): Total amount in USD.
  - `receivedUSD` (number): Amount received so far in USD.
  - `customerFeeUSD` (number): Additional customer fee in USD.
  - `fxRateToUSD` (number): FX rate from local currency to USD.
- `compliance` (object): Compliance state for the transaction.
  - `kycTriggered` (boolean): Whether KYC verification was required.
  - `travelRuleTriggered` (boolean): Whether the travel rule was triggered.
  - `kycDetails` (object): Submitted KYC details, when present.
  - `resolutionLogs` (array): Fraud resolution log entries.
  - `strFilingReference` (string): Suspicious transaction report reference, when filed.
- `payments` (array): Payment requests created for the transaction.

  **Payment Request Object**
  - `paymentRequestID` (string): Unique identifier for the payment request.
  - `cryptoAsset` (string): Asset the customer pays in.
  - `cryptoNetwork` (string): Network the payment is made on.
  - `cryptoRatePerUSD` (number): Crypto-to-USD conversion rate recorded for this payment request at quote time.
  - `address` (string): Destination wallet address.
  - `walletName` (string): The wallet selected by the customer for the payment (for example, `metamask`). Returns an empty string if no wallet was specified.
  - `walletType` (string): Custody type of the customer's wallet. Currently always `non-custodial`.
  - `expectedCrypto` (number): Expected crypto amount.
  - `receivedCrypto` (number): Crypto amount received.
  - `expectedUSD` (number): Expected USD value.
  - `receivedUSD` (number): USD value received.
  - `txnHash` (string): On-chain transaction hash.
  - `fromAddress` (string): On-chain address the payment was sent from (the payer's wallet).
  - `confirmationCount` (number): Number of on-chain confirmations.
  - `completedAt` (string): Timestamp of the on-chain transfer that fulfilled the payment.
  - `gasFee` (number): Network gas fee.
  - `gasFeeUnits` (string): Unit the `gasFee` is denominated in — the chain's native coin (for example `ETH`).
  - `status` (number): Status of the payment request.
  - `qrData` (string): QR payload for this payment request.
  - `expiration` (string): Expiration of the payment request.
- `refunds` (array): Refunds issued against the transaction.

  **Refund Object**
  - `refundID` (string): Unique identifier for the refund.
  - `referenceNumber` (string): Merchant reference or order number of the refunded transaction.
  - `cryptoAsset` (string): Asset the refund is paid in.
  - `cryptoNetwork` (string): Network the refund is paid on.
  - `cryptoAmount` (number): Refunded crypto amount.
  - `fiatAmount` (number): Refund amount in fiat.
  - `fiatCurrency` (string): Fiat currency code.
  - `gasFee` (number): Network gas fee for the refund.
  - `gasFeePayer` (string): Who absorbed the gas fee (`merchant` or `customer`).
  - `receiverAddress` (string): Address the refund was sent to.
  - `status` (number): Status of the refund.
  - `reason` (string): Reason for the refund.
- `remainingLocal` (number): Amount still owed in local currency.
- `remainingUSD` (number): Amount still owed in USD.
- `cancellationReason` (string): Reason the transaction was cancelled, when applicable.
- `createdAt` (string): Created at date time of the transaction.
- `updatedAt` (string): Updated at date time of the transaction.
- `expiration` (string): Expiration of the transaction.

**example response**

```json
{
    "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
    "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
    "externalMID": "",
    "descriptor": "Order #1234",
    "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
    "quoteID": "",
    "status": 0,
    "paymentStatus": 0,
    "amounts": {
        "currency": "USD",
        "totalLocal": 9.34,
        "totalUSD": 9.34,
        "receivedUSD": 0,
        "customerFeeUSD": 1.25,
        "fxRateToUSD": 1
    },
    "compliance": {
        "kycTriggered": false,
        "travelRuleTriggered": false
    },
    "payments": [
        {
            "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab",
            "cryptoAsset": "USDT",
            "cryptoNetwork": "ethereum",
            "cryptoRatePerUSD": 1,
            "address": "0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
            "walletName": "metamask",
            "walletType": "non-custodial",
            "expectedCrypto": 9.34,
            "receivedCrypto": 0,
            "expectedUSD": 9.34,
            "receivedUSD": 0,
            "txnHash": "",
            "fromAddress": "",
            "confirmationCount": 0,
            "completedAt": "0001-01-01T00:00:00Z",
            "gasFee": 0,
            "gasFeeUnits": "",
            "status": 0,
            "qrData": "ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7/transfer?address=0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
            "expiration": "2025-08-12T03:35:02.769Z"
        }
    ],
    "refunds": [],
    "remainingLocal": 9.34,
    "remainingUSD": 9.34,
    "cancellationReason": "",
    "createdAt": "2025-08-12T03:20:02.769Z",
    "updatedAt": "2025-08-12T03:20:02.769Z",
    "expiration": "2025-08-12T03:35:02.769Z"
}
```

## Submit Customer Verification For Transaction

**Endpoint:** `POST /transaction/{TRANSACTION_ID}/verification`

```bash
curl --location '{API_BASE_URL}/transaction/{TRANSACTION_ID}/verification' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--form 'asset="{ASSET}"' \
--form 'network="{NETWORK}"' \
--form 'documentType="{DOCUMENT_TYPE}"' \
--form 'firstName="{FIRST_NAME}"' \
--form 'lastName="{LAST_NAME}"' \
--form 'email="{EMAIL}"' \
--form 'street="{STREET_ADDRESS}"' \
--form 'city="{CITY}"' \
--form 'region="{REGION}"' \
--form 'postalCode="{POSTAL_CODE}"' \
--form 'country="{COUNTRY_CODE}"' \
--form 'storeKYC="true"' \
--form 'documentFiles=@"{DOCUMENT_FILE_FRONT}"' \
--form 'documentFiles=@"{DOCUMENT_FILE_REAR}"'
```

`storeKYC` is optional (`true`/`false`). When `true`, the verified customer details are stored as a
customer record so returning customers can restore them via email OTP on future transactions.

## Submit Customer Verification For Transaction Response

This endpoint returns the same response structure as the create-transaction endpoint.

> **Note:** Alternatively, you can create or retrieve a transaction by sending the X-Api-Key (backend API key) and X-MID
> (merchant UUID or external merchant ID) headers instead of X-Publishable-Key, as shown below.

## Create Transaction With API Key

**Endpoint:** `POST /transaction`

```bash
curl --location '{API_BASE_URL}/transaction' \
--header 'X-Api-Key: {API_KEY}' \
--header 'X-MID: {MERCHANT_UUID_OR_EXTERNAL_MERCHANT_ID}' \
--header 'Content-Type: application/json' \
--data '{
    "descriptor": "{OPTIONAL_DESCRIPTOR}",
    "referenceNumber": "{OPTIONAL_REFERENCE_NUMBER}",
    "amount": {AMOUNT_IN_FLOAT},
    "amountCurrency": "{CURRENCY_CODE}",
    "asset": "{ASSET}",
    "network": "{CRYPTO_NETWORK}"
}'
```

## Get Transaction With API Key

**Endpoint:** `GET /transaction/{TRANSACTION_ID}`

```bash
curl --location --request GET '{API_BASE_URL}/transaction/{TRANSACTION_ID}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'X-MID: {MERCHANT_UUID_OR_EXTERNAL_MERCHANT_ID}' \
--header 'Content-Type: application/json'
```

## Create Payment Request

Generate a fresh payment (address and QR) for an existing transaction once the customer selects an asset and network.

**Endpoint:** `POST /transaction/{transactionID}/payment`

```bash
curl --location '{API_BASE_URL}/transaction/{TRANSACTION_ID}/payment' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "asset": "{ASSET}",
    "network": "{CRYPTO_NETWORK}",
    "wallet": "{CUSTOMER_WALLET_ADDRESS}" // OPTIONAL
}'
```

The response is the same structure as the [Create Transaction Response](#create-transaction-response).

## Cancel Transaction

**Endpoint:** `PATCH /transaction/{transactionID}/cancel`

```bash
curl --location --request PATCH '{API_BASE_URL}/transaction/{TRANSACTION_ID}/cancel' \
--header 'X-Api-Key: {API_KEY}' \
--header 'X-MID: {MERCHANT_UUID_OR_EXTERNAL_MERCHANT_ID}' \
--header 'Content-Type: application/json' \
--data '{
    "reason": "{REASON}", // OPTIONAL
    "forfeit": {FORFEIT}  // OPTIONAL boolean
}'
```

Set `forfeit` to `true` to forfeit any funds already received rather than cancelling cleanly. Returns the full transaction object (same structure as the [Get Transaction Response](#get-transaction-response)).

## List Transactions

Retrieve transactions across an account and its sub-merchants.

**Endpoint:** `GET /transactions`

```bash
curl --location '{API_BASE_URL}/transactions?limit={LIMIT}&page={PAGE}' \
--header 'X-Account-Id: {ACCOUNT_ID}' \
--header 'Content-Type: application/json'
```

`limit` and `page` are required. Optional query parameters: `status` (comma-separated status values, e.g. `0,1,-1`), `subMerchantId`, `referenceNumber`, `startTime`, `endTime`.

For account-level reporting views with richer filters, see [Reporting](https://developer.lydian.com/api/reporting.md).

### List Transactions Response

- `transactions` (array): List of transactions, each with the same structure as the [Get Transaction Response](#get-transaction-response).
- `metadata` (object): Pagination metadata.
  - `totalCount` (number): Total number of items available across all pages.
  - `count` (number): Number of items in the current page.
  - `page` (number): Current page number (1-based).
  - `pageSize` (number): Maximum number of items per page.

**example response**

```json
{
    "transactions": [
        {
            "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
            "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
            "descriptor": "Order #1234",
            "status": 1
        }
    ],
    "metadata": {
        "totalCount": 1,
        "count": 1,
        "page": 1,
        "pageSize": 10
    }
}
```

---

# Refunds

Source: https://developer.lydian.com/api/refund
Markdown: https://developer.lydian.com/api/refund.md

Refund a succeeded transaction. Lydian recalculates the amount of the underlying asset to return using the current exchange rate and reduces it by the current gas fee (unless `gasFeePayer` overrides who pays). A transaction must have succeeded (`status` `1`) to be refunded.

For the end-to-end refund workflow, see [Refund a Payment](https://developer.lydian.com/guides/refund-a-payment.md).

## Create A Refund

**Endpoint:** `POST /account/{accountID}/transaction/{transactionID}/refund`

```bash
curl --location '{API_BASE_URL}/account/{ACCOUNT_ID}/transaction/{TRANSACTION_ID}/refund' \
--header 'X-Api-Key: {API_KEY}' \
--header 'X-MID: {MERCHANT_UUID_OR_EXTERNAL_MERCHANT_ID}' \
--header 'Content-Type: application/json' \
--data '{
"amount": {AMOUNT_IN_FLOAT},
"reason": "{REASON}", // OPTIONAL
"gasFeePayer": "{GAS_FEE_PAYER}", // OPTIONAL
"receiverAddress": "{WALLET_ADDRESS}" // OPTIONAL
}'
```

`gasFeePayer` must be one of: `merchant` or `customer`. It determines who absorbs the network gas fee for the refund. When omitted, the refund amount is reduced by the current gas fee.

`receiverAddress` is an optional destination wallet address for the refund.
When provided, it must not be blank.

### Create Refund Response

The response is an array of refund objects — one per refund leg created for the request.

- `refundID` (string): Unique identifier for the refund.
- `assetAmount` (string): Asset amount for the refund.

**example response**

```json
[
    {
        "refundID": "acd09ac7-612f-4011-ac74-a5e1f4753648",
        "assetAmount": "9.34"
    }
]
```

---

# Subscription

Source: https://developer.lydian.com/api/subscription
Markdown: https://developer.lydian.com/api/subscription.md

Lydian supports recurring billing through subscription plans. Create plans with defined billing intervals, subscribe customers, and manage the subscription lifecycle.

---

## Subscription Plans

### Create Subscription Plan

**Endpoint:** `POST /subscriptionplans`

```bash
curl --location '{API_BASE_URL}/subscriptionplans' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "accountId": "{ACCOUNT_ID}",
    "merchantId": "{MERCHANT_ID}", // OPTIONAL
    "planName": "{PLAN_NAME}", // OPTIONAL
    "description": "{DESCRIPTION}", // OPTIONAL
    "amount": "{AMOUNT}",
    "billingInterval": "{BILLING_INTERVAL}"
}'
```

`billingInterval` must be one of: `MONTHLY`, `YEARLY`.

#### Create Subscription Plan Response

- `id` (string): Unique identifier for the subscription plan.
- `accountId` (string): Account ID the plan belongs to.
- `merchantId` (string): Merchant ID the plan belongs to.
- `planName` (string): Name of the subscription plan.
- `description` (string): Description of the subscription plan.
- `billingInterval` (string): Billing interval for the plan. Either `MONTHLY` or `YEARLY`.
- `amount` (string): Amount to charge per billing interval.

**example response**

```json
{
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "accountId": "33c0dadc-bd86-45ae-b4d6-62f149313701",
    "merchantId": "b9280199-ab1b-4545-a625-1728ba354abf",
    "planName": "Pro Monthly",
    "description": "Pro plan billed monthly",
    "billingInterval": "MONTHLY",
    "amount": "29.99"
}
```

### List Subscription Plans

**Endpoint:** `GET /subscriptionplans`

```bash
curl --location '{API_BASE_URL}/subscriptionplans?limit={LIMIT}&page={PAGE}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

Optional query parameters: `accountId`, `merchantId`.

#### List Subscription Plans Response

- `plans` (array): List of subscription plans.
- `metadata` (object): Pagination metadata.
  - `totalCount` (number): Total number of items available.
  - `count` (number): Number of items in the current page.
  - `page` (number): Current page number.
  - `pageSize` (number): Maximum items per page.

**example response**

```json
{
    "plans": [
        {
            "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "accountId": "33c0dadc-bd86-45ae-b4d6-62f149313701",
            "merchantId": "b9280199-ab1b-4545-a625-1728ba354abf",
            "planName": "Pro Monthly",
            "description": "Pro plan billed monthly",
            "billingInterval": "MONTHLY",
            "amount": "29.99"
        }
    ],
    "metadata": {
        "totalCount": 1,
        "count": 1,
        "page": 1,
        "pageSize": 10
    }
}
```

### Get Subscription Plan

**Endpoint:** `GET /subscriptionplans/{planId}`

```bash
curl --location '{API_BASE_URL}/subscriptionplans/{planId}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

The response is the same structure as the [Create Subscription Plan Response](#create-subscription-plan-response).

---

## Subscriptions

### Create Subscription

**Endpoint:** `POST /subscriptions`

```bash
curl --location '{API_BASE_URL}/subscriptions' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "planId": "{PLAN_ID}",
    "customerEmail": "{CUSTOMER_EMAIL}",
    "walletAddress": "{WALLET_ADDRESS}",
    "asset": "{ASSET}",
    "network": "{CRYPTO_NETWORK}",
    "billingInterval": "{BILLING_INTERVAL}"
}'
```

#### Create Subscription Response

- `id` (string): Unique identifier for the subscription.
- `accountId` (string): Account ID the subscription belongs to.
- `merchantId` (string): Merchant ID the subscription belongs to.
- `planId` (string): Plan ID the subscription is based on.
- `planName` (string): Name of the associated plan.
- `customerEmail` (string): Email address of the subscribed customer.
- `walletAddress` (string): Crypto wallet address of the customer.
- `asset` (string): Asset the subscription is billed in.
- `network` (string): Network the subscription is billed on.
- `status` (string): Current status of the subscription. One of `CREATED`, `ACTIVE`, `PAUSED`, `PAYMENT_FAILED`, or `CANCELED`.
- `billingInterval` (string): Billing interval. Either `MONTHLY` or `YEARLY`.
- `lastBillingAt` (string): Timestamp of the last billing event.
- `nextBillingAt` (string): Timestamp of the next scheduled billing.

**example response**

```json
{
    "id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
    "accountId": "33c0dadc-bd86-45ae-b4d6-62f149313701",
    "merchantId": "b9280199-ab1b-4545-a625-1728ba354abf",
    "planId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "planName": "Pro Monthly",
    "customerEmail": "customer@example.com",
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "asset": "USDT",
    "network": "ethereum",
    "status": "ACTIVE",
    "billingInterval": "MONTHLY",
    "lastBillingAt": "2025-09-01T00:00:00.000Z",
    "nextBillingAt": "2025-10-01T00:00:00.000Z"
}
```

### List Subscriptions

**Endpoint:** `GET /subscriptions`

```bash
curl --location '{API_BASE_URL}/subscriptions?limit={LIMIT}&page={PAGE}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

Optional query parameters: `accountId`, `merchantId`, `planId`, `customerEmail`, `walletAddress`, `status`.

#### List Subscriptions Response

- `subscriptions` (array): List of subscriptions.
- `metadata` (object): Pagination metadata with `totalCount`, `count`, `page`, and `pageSize`.

**example response**

```json
{
    "subscriptions": [
        {
            "id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
            "accountId": "33c0dadc-bd86-45ae-b4d6-62f149313701",
            "merchantId": "b9280199-ab1b-4545-a625-1728ba354abf",
            "planId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "planName": "Pro Monthly",
            "customerEmail": "customer@example.com",
            "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
            "asset": "USDT",
            "network": "ethereum",
            "status": "ACTIVE",
            "billingInterval": "MONTHLY",
            "lastBillingAt": "2025-09-01T00:00:00.000Z",
            "nextBillingAt": "2025-10-01T00:00:00.000Z"
        }
    ],
    "metadata": {
        "totalCount": 1,
        "count": 1,
        "page": 1,
        "pageSize": 10
    }
}
```

### Get Subscription

**Endpoint:** `GET /subscriptions/{subscriptionId}`

```bash
curl --location '{API_BASE_URL}/subscriptions/{subscriptionId}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

The response is the same structure as the [Create Subscription Response](#create-subscription-response).

### Pause Subscription

**Endpoint:** `PUT /subscriptions/{subscriptionId}/pause`

```bash
curl --location --request PUT '{API_BASE_URL}/subscriptions/{subscriptionId}/pause' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "reason": "{REASON}"
}'
```

#### Pause/Resume/Cancel Response

- `id` (string): Unique identifier for the subscription.
- `status` (string): Updated status of the subscription.

**example response**

```json
{
    "id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
    "status": "PAUSED"
}
```

### Resume Subscription

**Endpoint:** `PUT /subscriptions/{subscriptionId}/resume`

```bash
curl --location --request PUT '{API_BASE_URL}/subscriptions/{subscriptionId}/resume' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "reason": "{REASON}"
}'
```

The response is the same structure as the [Pause/Resume/Cancel Response](#pauseresumecancel-response).

### Cancel Subscription

**Endpoint:** `DELETE /subscriptions/{subscriptionId}`

```bash
curl --location --request DELETE '{API_BASE_URL}/subscriptions/{subscriptionId}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "reason": "{REASON}"
}'
```

The response is the same structure as the [Pause/Resume/Cancel Response](#pauseresumecancel-response).

### List Subscription Events

**Endpoint:** `GET /subscriptions/{subscriptionId}/events`

```bash
curl --location '{API_BASE_URL}/subscriptions/{subscriptionId}/events' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

#### List Subscription Events Response

- `events` (array): List of events for this subscription.

  **Event Object**
  - `timestamp` (string): Timestamp of the event.
  - `type` (string): Event type. One of `CREATED`, `PAUSED`, `RESUMED`, `CANCELED`, or `PAYMENT_FAILED`.
  - `data` (object): Event data containing an optional `reason` string.
- `metadata` (object): Pagination metadata with `totalCount`, `count`, `page`, and `pageSize`.

**example response**

```json
{
    "events": [
        {
            "timestamp": "2025-09-01T00:00:00.000Z",
            "type": "CREATED",
            "data": {
                "reason": ""
            }
        },
        {
            "timestamp": "2025-09-15T12:00:00.000Z",
            "type": "PAUSED",
            "data": {
                "reason": "Customer requested pause"
            }
        }
    ],
    "metadata": {
        "totalCount": 2,
        "count": 2,
        "page": 1,
        "pageSize": 10
    }
}
```

---

## Subscription Payments

### Create Subscription Payment

**Endpoint:** `POST /subscriptionpayments`

```bash
curl --location '{API_BASE_URL}/subscriptionpayments' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "subscriptionId": "{SUBSCRIPTION_ID}"
}'
```

#### Create Subscription Payment Response

- `id` (string): Unique identifier for the subscription payment.
- `subscriptionId` (string): Subscription this payment belongs to.
- `planId` (string): Plan associated with the payment.
- `accountId` (string): Account ID for the payment.
- `merchantId` (string): Merchant ID for the payment.
- `items` (array): Line items for the payment, each with `id`, `type`, and `amount`.
- `payments` (array): Payment attempts, each with `id`, `result`, `network`, `assetSymbol`, `address`, `txnHash`, `amount`, `startedAt`, `completedAt`, and `failureReason`.
- `total` (string): Total amount for the payment.
- `status` (string): Payment status. One of `PAID`, `PENDING`, `PARTIALLY_PAID`, or `FAILED`.

**example response**

```json
{
    "id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "subscriptionId": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
    "planId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "accountId": "33c0dadc-bd86-45ae-b4d6-62f149313701",
    "merchantId": "b9280199-ab1b-4545-a625-1728ba354abf",
    "items": [
        {
            "id": "item-001",
            "type": "subscription",
            "amount": "29.99"
        }
    ],
    "payments": [],
    "total": "29.99",
    "status": "PENDING"
}
```

### List Subscription Payments

**Endpoint:** `GET /subscriptionpayments`

```bash
curl --location '{API_BASE_URL}/subscriptionpayments?limit={LIMIT}&page={PAGE}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

Optional query parameters: `accountId`, `merchantId`, `planId`, `subscriptionId`, `status`, `from`, `to`.

The `status` filter accepts: `PAID`, `PENDING`, `PARTIALLY_PAID`, `FAILED`. The `from` and `to` parameters are unix timestamps for filtering by creation date range.

#### List Subscription Payments Response

- `payments` (array): List of subscription payments.
- `metadata` (object): Pagination metadata with `totalCount`, `count`, `page`, and `pageSize`.

**example response**

```json
{
    "payments": [
        {
            "id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
            "subscriptionId": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
            "planId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "accountId": "33c0dadc-bd86-45ae-b4d6-62f149313701",
            "merchantId": "b9280199-ab1b-4545-a625-1728ba354abf",
            "total": "29.99",
            "status": "PAID"
        }
    ],
    "metadata": {
        "totalCount": 1,
        "count": 1,
        "page": 1,
        "pageSize": 10
    }
}
```

### Get Subscription Payment

**Endpoint:** `GET /subscriptionpayments/{paymentId}`

```bash
curl --location '{API_BASE_URL}/subscriptionpayments/{paymentId}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

The response is the same structure as the [Create Subscription Payment Response](#create-subscription-payment-response).

### Retry Subscription Payment

**Endpoint:** `PUT /subscriptionpayments/{subscriptionId}/retry`

```bash
curl --location --request PUT '{API_BASE_URL}/subscriptionpayments/{subscriptionId}/retry' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

Returns `204 No Content` on success.

---

# Reporting

Source: https://developer.lydian.com/api/reporting
Markdown: https://developer.lydian.com/api/reporting.md

Reporting endpoints return read-optimized views of your account's activity, served from the
reporting store rather than live transaction state. Use them for dashboards, reconciliation,
and exports; use [Get Transaction](https://developer.lydian.com/api/transaction.md#get-transaction) to track an in-flight
payment.

## Get Account Summary

**Endpoint:** `GET /accounts/{accountUUID}/reporting/summary`

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/reporting/summary?fromDate={FROM_DATE}&toDate={TO_DATE}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

All query parameters are optional: `merchantID`, `fromDate`, `toDate`.

### Get Account Summary Response

- `totalVolumeUSD` (number): Total transaction volume in USD for the period.
- `totalFeesUSD` (number): Total fees charged in USD for the period.
- `pendingPayoutsUSD` (number): Amount awaiting payout in USD.

**example response**

```json
{
    "totalVolumeUSD": 15230.5,
    "totalFeesUSD": 152.31,
    "pendingPayoutsUSD": 4200
}
```

## List Account Transactions

Retrieve transactions across your account, optionally filtered by merchant.

**Endpoint:** `GET /accounts/{accountUUID}/transactions`

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/transactions?merchantID={MERCHANT_UUID}&limit={LIMIT}&offset={OFFSET}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

All query parameters are optional: `merchantID`, `referenceNumber`, `statuses`, `paymentStatuses`,
`currency`, `fromDate`, `toDate`, `limit`, `offset`. `statuses` and `paymentStatuses` accept
repeated values (e.g. `statuses=0&statuses=1`). `statuses` uses the transaction status values — see [Payment Lifecycle & Statuses](https://developer.lydian.com/concepts/payment-lifecycle.md).

### List Account Transactions Response

- `total` (number): Total number of transactions matching the filters.
- `transactions` (array): Transaction report rows.

  **Transaction Report Row**
  - `transactionID` (string): Unique identifier for the transaction.
  - `accountID` (string): Account the transaction belongs to.
  - `merchantID` (string): Merchant the transaction belongs to.
  - `externalMID` (string): External merchant ID, when set.
  - `descriptor` (string): Human-readable descriptor.
  - `referenceNumber` (string): Merchant reference or order number.
  - `status` (number): Transaction status.
  - `paymentStatus` (number): Aggregate status of the transaction's payments.
  - `currency` (string): Local currency code (ISO 4217).
  - `totalLocal` (number): Total amount in local currency.
  - `totalUSD` (number): Total amount in USD.
  - `receivedUSD` (number): Amount received in USD.
  - `customerFeeUSD` (number): Additional customer fee in USD.
  - `fxRateToUSD` (number): FX rate from local currency to USD.
  - `payments` (array): Payment summaries, each with `paymentRequestID`, `cryptoAsset`, `cryptoNetwork`,
    `address`, `fromAddress`, `expectedUSD`, `receivedCrypto`, `gasFee`, `gasFeeUnits`,
    `txnHash`, `status`, `fraudPass`, and `createdAt`.
  - `cancellationReason` (string): Reason the transaction was cancelled, when applicable.
  - `expiration` (string): Expiration of the transaction.
  - `sourceCreatedAt` (string): When the transaction was created.
  - `sourceUpdatedAt` (string): When the transaction was last updated.

**example response**

```json
{
    "total": 1,
    "transactions": [
        {
            "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
            "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
            "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
            "externalMID": "",
            "descriptor": "Order #1234",
            "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
            "status": 1,
            "paymentStatus": 1,
            "currency": "USD",
            "totalLocal": 9.34,
            "totalUSD": 9.34,
            "receivedUSD": 9.34,
            "customerFeeUSD": 1.25,
            "fxRateToUSD": 1,
            "payments": [],
            "cancellationReason": "",
            "expiration": "2025-08-12T03:35:02.769Z",
            "sourceCreatedAt": "2025-08-12T03:20:02.769Z",
            "sourceUpdatedAt": "2025-08-12T03:21:14.101Z"
        }
    ]
}
```

## Get Account Transaction

**Endpoint:** `GET /accounts/{accountUUID}/transactions/{transactionID}`

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/transactions/{TRANSACTION_ID}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

### Get Account Transaction Response

Returns a `transaction` object with the same fields as the
[Transaction Report Row](#list-account-transactions-response), plus a `compliance` object
(`kycTriggered`, `travelRuleTriggered`) and full payment detail on each entry in `payments`
(adds `expectedCrypto`, `receivedUSD`, `confirmationCount`, `cryptoRatePerUSD`, `walletName`,
`completedAt`, `expiration`, `sourceCreatedAt`, `sourceUpdatedAt`).

---

# Webhooks

Source: https://developer.lydian.com/api/webhooks
Markdown: https://developer.lydian.com/api/webhooks.md

Manage the webhook endpoints Lydian delivers event notifications to. A webhook has a name, a target URL, and a list of subscribed event types; when a subscribed event occurs, Lydian sends an HTTP `POST` with a `Content-Type: application/json` body to the URL.

For setup instructions, see [Set Up Webhooks](https://developer.lydian.com/guides/set-up-webhooks.md). For the event payloads, see [Event Payloads](https://developer.lydian.com/api/webhooks/events.md).

## Create Webhook

**Endpoint:** `POST /accounts/{accountUUID}/webhooks`

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/webhooks' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "{WEBHOOK_NAME}",
    "url": "{WEBHOOK_URL}",
    "events": ["transaction.success"]
}'
```

### Create Webhook Response

- `uuid` (string): Unique identifier for the webhook.
- `signingKey` (string): Signing key returned when the webhook is created. Store it securely — it is only returned in full at
  creation time.
- `name` (string): Name of the webhook.
- `url` (string): URL that receives webhook events.
- `status` (integer): Status of the webhook. `1` means enabled and `-1` means disabled.
- `createdAt` (string): RFC 3339 timestamp of when the webhook was created.

**example response**

```json
{
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "signingKey": "9c1d8f7e6b5a4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d",
    "name": "Order Notifications",
    "url": "https://example.com/webhooks/lydian",
    "status": 1,
    "createdAt": "2025-08-12T03:20:02.769Z"
}
```

## List Webhooks

**Endpoint:** `GET /accounts/{accountUUID}/webhooks`

```bash
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/webhooks' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

### List Webhooks Response

- `webhooks` (array): List of webhooks associated with this account.

  **Webhook Object**
  - `uuid` (string): Unique identifier for the webhook.
  - `name` (string): Name of the webhook.
  - `url` (string): URL that receives webhook events.
  - `status` (integer): Status of the webhook. `1` means enabled and `-1` means disabled.
  - `events` (array): Event types this webhook is subscribed to (e.g. `["transaction.success"]`).
  - `signingKey` (string): Signing key associated with this webhook.
  - `accountID` (string): UUID of the account the webhook belongs to.
  - `createdAt` (string): RFC 3339 timestamp of when the webhook was created.

**example response**

```json
{
    "webhooks": [
        {
            "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "Order Notifications",
            "url": "https://example.com/webhooks/lydian",
            "status": 1,
            "events": ["transaction.success"],
            "signingKey": "9c1d8f7e6b5a4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d",
            "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
            "createdAt": "2025-08-12T03:20:02.769Z"
        }
    ]
}
```

## Update Webhook

**Endpoint:** `PUT /accounts/{accountUUID}/webhooks/{webhookUUID}`

```bash
curl --location --request PUT '{API_BASE_URL}/accounts/{AccountUUID}/webhooks/{webhookUUID}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "name": "{WEBHOOK_NAME}", // OPTIONAL
    "url": "{WEBHOOK_URL}", // OPTIONAL
    "status": {STATUS}, // OPTIONAL — 1 to enable, -1 to disable
    "events": ["transaction.success"] // OPTIONAL
}'
```

Returns `204 No Content` on success.

## Delete Webhook

**Endpoint:** `DELETE /accounts/{accountUUID}/webhooks/{webhookUUID}`

```bash
curl --location --request DELETE '{API_BASE_URL}/accounts/{AccountUUID}/webhooks/{webhookUUID}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'
```

Returns `204 No Content` on success.

---

# Webhook Events

Source: https://developer.lydian.com/api/webhooks/events
Markdown: https://developer.lydian.com/api/webhooks/events.md

This page describes the payloads Lydian delivers to your webhook endpoints. To register an endpoint, see [Webhooks](https://developer.lydian.com/api/webhooks.md). For guidance on receiving and processing events, see [Handle Webhook Events](https://developer.lydian.com/guides/handle-webhook-events.md).

## The Event Envelope

Every webhook — regardless of type — is delivered as the same JSON envelope over an HTTP `POST` with `Content-Type: application/json`. The envelope identifies the event and the account it belongs to, while the event-specific details live in the `data` object.

- `accountUUID` (string): UUID of the account the event belongs to.
- `type` (string): The event type — see [Event Types](#event-types) below.
- `timestamp` (string): RFC 3339 timestamp of when the event was emitted.
- `data` (object): The event payload. Its structure depends on `type`.

**envelope**

```json
{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "transaction.success",
    "timestamp": "2025-08-15T10:15:44.762134-04:00",
    "data": { }
}
```

> **Note:** Timestamps in webhook payloads are RFC 3339 strings. Some use UTC (`Z`) and others a numeric offset such as
> `-04:00`, so parse the offset rather than assuming every timestamp ends in `Z`.

## Event Types

A webhook only receives the event types it subscribed to when it was created (the `events` array — see [Create Webhook](https://developer.lydian.com/api/webhooks.md#create-webhook)). The event types currently documented are listed below; treat this as the currently documented set rather than a guaranteed-exhaustive catalog:

| `type`                            | Sent when                                                                    |
| --------------------------------- | ---------------------------------------------------------------------------- |
| `transaction.success`             | A transaction is fully paid and confirmed on-chain.                          |
| `transaction.failed`              | A transaction fails or is cancelled before it completes.                     |
| `refund.success`                  | A refund has completed successfully.                                         |
| `refund.failed`                   | A refund has failed.                                                         |
| `session.promoted`                | A session has been promoted and a transaction is being created.              |
| `session.canceled`                | A session has been canceled and is no longer active.                         |
| `session.timedout`                | A session has timed out and is no longer active.                             |
| `settlement.closed`               | A settlement period has ended and the net amount owed to you is final.       |
| `settlement.paid`                 | The settlement's funds have been sent to your registered payout destination. |
| `reconciliation_report.generated` | A daily reconciliation report has been generated for your account.           |

## transaction.success

Sent when a transaction has been fully paid and confirmed. The `data` object is the complete transaction record — identical in structure to the [Get Transaction Response](https://developer.lydian.com/api/transaction.md#get-transaction-response). A successful transaction has `status` `1` and no remaining balance.

- `data` (object): The full transaction object. See the [Get Transaction Response](https://developer.lydian.com/api/transaction.md#get-transaction-response)
  for the complete field list.

**transaction.success**

```json
{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "transaction.success",
    "timestamp": "2025-08-15T10:15:44.762134-04:00",
    "data": {
        "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
        "externalMID": "",
        "descriptor": "Order #1234",
        "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
        "status": 1,
        "paymentStatus": 1,
        "amounts": {
            "currency": "USD",
            "totalLocal": 9.34,
            "totalUSD": 9.34,
            "receivedUSD": 9.34,
            "customerFeeUSD": 1.25,
            "fxRateToUSD": 1
        },
        "compliance": {
            "kycTriggered": false,
            "travelRuleTriggered": false
        },
        "payments": [
            {
                "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab",
                "cryptoAsset": "USDT",
                "cryptoNetwork": "ethereum",
                "cryptoRatePerUSD": 1,
                "address": "0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
                "walletName": "metamask",
                "walletType": "non-custodial",
                "expectedCrypto": 9.34,
                "receivedCrypto": 9.34,
                "expectedUSD": 9.34,
                "receivedUSD": 9.34,
                "txnHash": "0x9f2c...c4dd",
                "fromAddress": "0x3a1f9c8b7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b",
                "confirmationCount": 12,
                "completedAt": "2025-08-12T03:21:40.512Z",
                "gasFee": 0.42,
                "gasFeeUnits": "ETH",
                "status": 1,
                "qrData": "ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7/transfer?address=0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
                "expiration": "2025-08-12T03:35:02.769Z"
            }
        ],
        "refunds": [],
        "remainingLocal": 0,
        "remainingUSD": 0,
        "cancellationReason": "",
        "createdAt": "2025-08-12T03:20:02.769Z",
        "updatedAt": "2025-08-12T03:21:44.762Z",
        "expiration": "2025-08-12T03:35:02.769Z"
    }
}
```

## transaction.failed

Sent when a transaction fails or is cancelled before it completes. The `data` object has the same structure as [`transaction.success`](#transaction-success) — the [Get Transaction Response](https://developer.lydian.com/api/transaction.md#get-transaction-response) — with the transaction's `status` reflecting the failure (for example `-2` cancelled or `-4` forfeited) and `cancellationReason` set where applicable.

- `data` (object): The full transaction object, with `status` reflecting the failure. See the
  [Get Transaction Response](https://developer.lydian.com/api/transaction.md#get-transaction-response) for the complete field list and the
  full set of status values.

**transaction.failed**

```json
{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "transaction.failed",
    "timestamp": "2025-08-15T10:22:03.114902-04:00",
    "data": {
        "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
        "descriptor": "Order #1234",
        "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
        "status": -2,
        "paymentStatus": 0,
        "amounts": {
            "currency": "USD",
            "totalLocal": 9.34,
            "totalUSD": 9.34,
            "receivedUSD": 0,
            "customerFeeUSD": 1.25,
            "fxRateToUSD": 1
        },
        "payments": [
            {
                "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab",
                "cryptoAsset": "USDT",
                "cryptoNetwork": "ethereum",
                "cryptoRatePerUSD": 1,
                "address": "0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
                "walletName": "metamask",
                "walletType": "non-custodial",
                "expectedCrypto": 9.34,
                "receivedCrypto": 0,
                "expectedUSD": 9.34,
                "receivedUSD": 0,
                "txnHash": "",
                "fromAddress": "",
                "confirmationCount": 0,
                "completedAt": "0001-01-01T00:00:00Z",
                "gasFee": 0,
                "gasFeeUnits": "",
                "status": 0,
                "qrData": "ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7/transfer?address=0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
                "expiration": "2025-08-12T03:35:02.769Z"
            }
        ],
        "remainingLocal": 9.34,
        "remainingUSD": 9.34,
        "cancellationReason": "Payment window expired",
        "createdAt": "2025-08-12T03:20:02.769Z",
        "updatedAt": "2025-08-12T03:35:02.769Z",
        "expiration": "2025-08-12T03:35:02.769Z"
    }
}
```

## refund.success

Sent when a refund completes successfully. The `data` object is the refund payload; a successful refund has `status` `1`.

- `createdAt` (string): Timestamp when the refund record was created.
- `updatedAt` (string): Timestamp when the refund was last updated.
- `refundID` (string): Unique identifier for the refund.
- `transactionID` (string): Identifier of the transaction associated with the refund.
- `paymentRequestID` (string): Identifier of the payment request associated with the refund.
- `accountID` (string): Identifier of the account associated with the refund.
- `merchantID` (string): Identifier of the merchant associated with the refund.
- `referenceNumber` (string): Merchant reference or order number of the refunded transaction. May be an empty string.
- `origin` (string): What initiated the refund. One of `merchant`, `fraud`, or `cancellation`.
- `reason` (string): Reason for the refund. May be an empty string.
- `status` (integer): Refund status: `-1` failed, `0` pending, `1` success.
- `stage` (string): Current stage of the refund. One of `queued`, `sending`, `swapping`, `confirming`, or `done`.
- `route` (string): Refund processing route. One of `direct`, `swap`, or `custody`.
- `custody` (string): Custody provider, when applicable. One of `bitgo` or `maya`. Optional.
- `custodyRef` (string): Custody provider reference, when applicable. Optional.
- `failureReason` (string): Details about a failure, when present. May be an empty string.
- `fiatCurrency` (string): Fiat currency of the refund (for example `USD`).
- `fiatAmount` (number): Fiat amount refunded.
- `gasFeePayer` (string): Who absorbs the network gas fee. One of `merchant` or `customer`.
- `receiverAddress` (string): Destination wallet address for the refund. May be an empty string.
- `cryptoAsset` (string): Crypto asset returned (for example `USDT`).
- `cryptoNetwork` (string): Network the refund is delivered on (for example `arbitrum`).
- `fiatFXRate` (number): Fiat-to-USD exchange rate for the refund.
- `usdAmount` (number): USD value of the refund.
- `sourceFXRate` (number): Source exchange rate stored for the refund.
- `sourceAmount` (number): Source amount stored for the refund.
- `sourceUSD` (number): Source-side USD value for the refund.
- `sourceTxHash` (string): Source transaction hash. May be an empty string.
- `swapID` (string): Swap identifier, when present. Optional.
- `swapPayinAddress` (string): Swap pay-in address, when present. Optional.
- `swapQuotedAmount` (number): Quoted swap amount.
- `cryptoAmount` (number): Crypto amount returned.
- `deliveryTxHash` (string): Delivery transaction hash. May be an empty string.
- `initiatedAt` (string): Timestamp when the refund was initiated.
- `executedAt` (string): Timestamp when the refund was executed.

**refund.success**

```json
{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "refund.success",
    "timestamp": "2025-08-15T10:22:14.512402-04:00",
    "data": {
        "createdAt": "2025-08-15T10:20:02.769Z",
        "updatedAt": "2025-08-15T10:22:14.512Z",
        "refundID": "acd09ac7-612f-4011-ac74-a5e1f4753648",
        "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
        "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
        "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
        "origin": "merchant",
        "reason": "Customer requested a refund",
        "status": 1,
        "stage": "done",
        "route": "direct",
        "failureReason": "",
        "fiatCurrency": "USD",
        "fiatAmount": 9.34,
        "gasFeePayer": "customer",
        "receiverAddress": "",
        "cryptoAsset": "USDT",
        "cryptoNetwork": "arbitrum",
        "fiatFXRate": 1,
        "usdAmount": 9.34,
        "sourceFXRate": 0,
        "sourceAmount": 0,
        "sourceUSD": 0,
        "sourceTxHash": "",
        "swapQuotedAmount": 0,
        "cryptoAmount": 9.34,
        "deliveryTxHash": "0x9f2c...c4dd",
        "initiatedAt": "2025-08-15T10:20:03.114Z",
        "executedAt": "2025-08-15T10:22:14.500Z"
    }
}
```

## refund.failed

Sent when a refund fails. The `data` object has the same structure as [`refund.success`](#refund-success), with `status` `-1` and `failureReason` set when a reason is available.

- `data` (object): The refund object, with `status` `-1`. See [`refund.success`](#refund-success) for the complete field list.

**refund.failed**

```json
{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "refund.failed",
    "timestamp": "2025-08-15T10:23:41.882013-04:00",
    "data": {
        "createdAt": "2025-08-15T10:20:02.769Z",
        "updatedAt": "2025-08-15T10:23:41.880Z",
        "refundID": "acd09ac7-612f-4011-ac74-a5e1f4753648",
        "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
        "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
        "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
        "origin": "merchant",
        "reason": "Customer requested a refund",
        "status": -1,
        "stage": "done",
        "route": "direct",
        "failureReason": "destination wallet rejected the transfer",
        "fiatCurrency": "USD",
        "fiatAmount": 9.34,
        "gasFeePayer": "customer",
        "receiverAddress": "",
        "cryptoAsset": "USDT",
        "cryptoNetwork": "arbitrum",
        "fiatFXRate": 1,
        "usdAmount": 9.34,
        "sourceFXRate": 0,
        "sourceAmount": 0,
        "sourceUSD": 0,
        "sourceTxHash": "",
        "swapQuotedAmount": 0,
        "cryptoAmount": 9.34,
        "deliveryTxHash": "0x9f2c...c4dd",
        "initiatedAt": "2025-08-15T10:20:03.114Z",
        "executedAt": "2025-08-15T10:22:14.500Z"
    }
}
```

## session.canceled

Sent when a session has been canceled. The `data` object is the session's [Create Session](https://developer.lydian.com/api/session.md#create-session) response.

- `sessionID` (string): Unique identifier for the session.
- `qrData` (string): The data to generate a QR code that can be scanned using mobile devices.
- `cancelURL` (string): Redirect URL used when the session is cancelled.
- `successURL` (string): Redirect URL used on a successful payment.
- `failureURL` (string): Redirect URL used on a failed payment.
- `fiatFXRate` (number): The fiat FX rate locked in for the session when provided; `null` otherwise.
- `recommendedNetwork` (string): Network recommended to the customer at checkout, when provided.
- `quoteID` (string): Quote identifier associated with the session, when provided.
- `merchantName` (string): Name of the merchant the session belongs to.
- `referenceNumber` (string): Merchant reference or order number for the session. Optional; omitted when not set.

**session.canceled**

```json
{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "session.canceled",
    "timestamp": "2025-08-15T10:15:44.762134-04:00",
    "data": {
        "sessionID": "009a3809-7328-4b6c-873b-089eff019f98",
        "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98",
        "cancelURL": "https://brimspire.com/checkout/cancel",
        "successURL": "https://brimspire.com/checkout/success",
        "failureURL": "https://brimspire.com/checkout/failure",
        "fiatFXRate": 1,
        "recommendedNetwork": "ethereum",
        "quoteID": "",
        "merchantName": "Brimspire"
    }
}
```

## session.promoted

Sent when a session has been promoted. The `data` object has the same structure as [`session.canceled`](#session-canceled).

- `data` (object): The session object. See [`session.canceled`](#session-canceled) for the complete field list.

**session.promoted**

```json
{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "session.promoted",
    "timestamp": "2025-08-15T10:15:44.762134-04:00",
    "data": {
        "sessionID": "009a3809-7328-4b6c-873b-089eff019f98",
        "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98",
        "cancelURL": "https://brimspire.com/checkout/cancel",
        "successURL": "https://brimspire.com/checkout/success",
        "failureURL": "https://brimspire.com/checkout/failure",
        "fiatFXRate": 1,
        "recommendedNetwork": "ethereum",
        "quoteID": "",
        "merchantName": "Brimspire"
    }
}
```

## session.timedout

Sent when a session has timed out. The `data` object has the same structure as [`session.canceled`](#session-canceled).

- `data` (object): The session object. See [`session.canceled`](#session-canceled) for the complete field list.

**session.timedout**

```json
{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "session.timedout",
    "timestamp": "2025-08-15T10:15:44.762134-04:00",
    "data": {
        "sessionID": "009a3809-7328-4b6c-873b-089eff019f98",
        "qrData": "https://pay.lydian.com/session/009a3809-7328-4b6c-873b-089eff019f98",
        "cancelURL": "https://brimspire.com/checkout/cancel",
        "successURL": "https://brimspire.com/checkout/success",
        "failureURL": "https://brimspire.com/checkout/failure",
        "fiatFXRate": 1,
        "recommendedNetwork": "ethereum",
        "quoteID": "",
        "merchantName": "Brimspire"
    }
}
```

## settlement.closed

Sent when a settlement period ends. The `data` object is the settlement record: the period it covers, its
`status` (`1` = closed), and `netUSD`, the amount owed to you for that period after fees. `merchantID` is present
when the settlement is for a single merchant rather than the whole account. There is no `payout` yet.

- `settlementID` (string): Unique identifier for the settlement.
- `accountID` (string): UUID of the account being settled.
- `merchantID` (string): UUID of the merchant being settled. Omitted when the settlement covers the whole account.
- `status` (integer): Settlement status. `1` means closed and `3` means paid.
- `frequency` (string): Settlement schedule: `hourly`, `six_hourly`, `daily`, `weekly`, `biweekly`, or `monthly`.
- `periodStart` (string): RFC 3339 start of the settled period (inclusive).
- `periodEnd` (string): RFC 3339 end of the settled period (exclusive).
- `netUSD` (number): Amount owed to you for the period, in USD, after fees.
- `payout` (object): Present once funds have been sent. See settlement.paid below.

**settlement.closed**

```json
{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "settlement.closed",
    "timestamp": "2026-09-07T00:00:04.118273Z",
    "data": {
        "settlementID": "3f0c9a4e-7d1b-4c2a-9e58-1b6f0d2a7c11",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
        "status": 1,
        "frequency": "daily",
        "periodStart": "2026-09-06T00:00:00Z",
        "periodEnd": "2026-09-07T00:00:00Z",
        "netUSD": 97.5
    }
}
```

## settlement.paid

Sent when the settlement's funds have been sent to your registered payout destination and, for crypto
destinations, confirmed on-chain. The `data` object has the same structure as
[`settlement.closed`](#settlement-closed) with `status` `3` and a `payout` object describing the transfer.

- `payout` (object): The transfer that paid this settlement.

  **Payout Object**
  - `type` (string): Destination type: `crypto_wallet` or `bank_account`.
  - `initiatedAt` (string): RFC 3339 timestamp of when the transfer was initiated.
  - `confirmedAt` (string): RFC 3339 timestamp of when the transfer was confirmed.
  - `cryptoWallet` (object): Present for crypto destinations: `network`, `asset`, `destinationAddress`, and the
    on-chain `txnHash`.

**settlement.paid**

```json
{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "settlement.paid",
    "timestamp": "2026-09-07T01:05:12.331901Z",
    "data": {
        "settlementID": "3f0c9a4e-7d1b-4c2a-9e58-1b6f0d2a7c11",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
        "status": 3,
        "frequency": "daily",
        "periodStart": "2026-09-06T00:00:00Z",
        "periodEnd": "2026-09-07T00:00:00Z",
        "netUSD": 97.5,
        "payout": {
            "type": "crypto_wallet",
            "initiatedAt": "2026-09-07T01:00:03.502Z",
            "confirmedAt": "2026-09-07T01:05:12.117Z",
            "cryptoWallet": {
                "network": "arbitrum",
                "asset": "USDT",
                "destinationAddress": "0x1c9a3b7f2e5d4c6b8a0f9e8d7c6b5a4f3e2d1c0b",
                "txnHash": "0x9f2c...c4dd"
            }
        }
    }
}
```

## reconciliation\_report.generated

Sent when Lydian generates a daily reconciliation report for your account. Each report covers one calendar day in
your account's local time zone (UTC if none is set) and lists the confirmed payments of transactions settled during
that day. Reports are generated about an hour after the day ends, including for days with no payments (`rowCount`
`0`). The `data` object describes the generated report file.

- `reportID` (string): Unique identifier for the report.
- `type` (string): Report type. Currently always `daily`.
- `accountID` (string): UUID of the account the report covers.
- `periodStart` (string): RFC 3339 start of the reported day (inclusive).
- `periodEnd` (string): RFC 3339 end of the reported day (exclusive).
- `fileName` (string): File name of the generated CSV report.
- `sizeBytes` (integer): Size of the report file, in bytes.
- `checksum` (string): SHA-256 hash of the report file's contents, hex-encoded.
- `rowCount` (integer): Number of payment rows in the report, excluding header lines. Can be `0`.
- `generatedAt` (string): RFC 3339 timestamp of when the report was generated.

**reconciliation\_report.generated**

```json
{
    "accountUUID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "type": "reconciliation_report.generated",
    "timestamp": "2026-09-07T01:00:04.902117Z",
    "data": {
        "reportID": "8c4e2f1a-6b3d-4a9e-b7c5-2d1f0e9a8b76",
        "type": "daily",
        "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
        "periodStart": "2026-09-06T00:00:00Z",
        "periodEnd": "2026-09-07T00:00:00Z",
        "fileName": "8c4e2f1a-6b3d-4a9e-b7c5-2d1f0e9a8b76-daily.csv",
        "sizeBytes": 2148,
        "checksum": "ad9c12c8986f4d21226f07a06e406c21ccd93e7b93a2b47053f5ec28e590c7bf",
        "rowCount": 6,
        "generatedAt": "2026-09-07T01:00:03.418Z"
    }
}
```

> **Note:** For guidance on receiving and processing these events, see [Handle Webhook Events](https://developer.lydian.com/guides/handle-webhook-events.md).

---

# Reference

Source: https://developer.lydian.com/api/reference
Markdown: https://developer.lydian.com/api/reference.md

Public lookup endpoints for what the platform supports. These require no authentication.

## List Assets

Returns every asset enabled across supported networks.

**Endpoint:** `GET /assets`

```bash
curl --location '{API_BASE_URL}/assets' \
--header 'Content-Type: application/json'
```

### List Assets Response

- `code` (string): Unique code identifier for the asset (e.g. `USDT`).
- `type` (string): Asset classification (e.g. `token`, `coin`).
- `networks` (array): Networks on which the asset is supported.

**example response**

```json
[
    {
        "code": "USDT",
        "type": "token",
        "networks": ["ethereum", "polygon", "tron"]
    },
    {
        "code": "ETH",
        "type": "coin",
        "networks": ["ethereum"]
    }
]
```

## List Supported Countries

Look up the countries Lydian supports.

**Endpoint:** `GET /config/countries`

```bash
curl --location '{API_BASE_URL}/config/countries' \
--header 'Content-Type: application/json'
```

### List Supported Countries Response

Returns an array of ISO 3166-1 alpha-2 country codes.

**example response**

```json
["US", "GB", "TR", "DE"]
```

---

# Lydian SDKs

Source: https://developer.lydian.com/sdks
Markdown: https://developer.lydian.com/sdks.md

Lydian currently offers one official SDK: the **Web SDK** (`@lydianpay/sdk-web`), which embeds Lydian checkout directly in the browser. See the [Web SDK](https://developer.lydian.com/sdks/web.md) reference to get started.

---

# Web SDK

Source: https://developer.lydian.com/sdks/web
Markdown: https://developer.lydian.com/sdks/web.md

The Lydian **Web SDK** (`@lydianpay/sdk-web`) is a drop-in checkout for the browser. It registers a `<lydian-checkout>` custom element and a global `window.Lydian` API that walks your customer through paying with a connected wallet or QR code.

This page is the library reference. For a step-by-step walkthrough, see [Web Checkout](https://developer.lydian.com/guides/web-checkout.md); to decide between hosted and embedded checkout, see [Choose Your Integration](https://developer.lydian.com/get-started/choose-integration.md).

## Installation

Install from npm, or load the pinned build from a CDN. Pin a version so an upstream release can't change your checkout unexpectedly.

**npm**

```bash
npm install @lydianpay/sdk-web
```

**CDN**

```html
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@lydianpay/sdk-web@3.0.1/dist/lydian.js"
></script>
```

With a bundler, import the package once to register the element and the global:

```js
import '@lydianpay/sdk-web'
```

The SDK ships as ES modules, so a script-tag include must use `type="module"`.

## Add the checkout element

Place the `<lydian-checkout>` element where the checkout should render. It stays hidden until you initialize the SDK.

```html
<lydian-checkout></lydian-checkout>
```

## Initialize the SDK

Call `window.Lydian.init(options)` to render the checkout and start a payment.

```js
window.Lydian.init({
  sandbox: true,
  dev: false,
  isEmbedded: true,
  publishableKey: '{PUBLISHABLE_KEY}',
  walletConnectProjectId: 'your-walletconnect-project-id',
  transaction: {
    amount: 2.45,
    currency: 'USD',
    descriptor: 'Order #1234',
    referenceNumber: 'your-unique-ref',
  },
  paymentSuccessListener: () => {},
  paymentFailedListener: (message) => {},
  paymentCanceledListener: () => {},
})
```

### `init` options

| Option                    | Type                        | Required | Description                                                                                                |
| ------------------------- | --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `publishableKey`          | `string`                    | yes      | Your Lydian publishable key (`pk_...`).                                                                    |
| `walletConnectProjectId`  | `string`                    | yes      | Your WalletConnect (Reown) project ID, used to power wallet connections.                                   |
| `transaction`             | `Transaction`               | yes      | The payment to collect (see below).                                                                        |
| `dev`                     | `boolean`                   | yes      | Target the development environment.                                                                        |
| `sandbox`                 | `boolean`                   | yes      | Target sandbox. With both `dev` and `sandbox` `false`, the SDK uses production.                            |
| `paymentSuccessListener`  | `() => void`                | yes      | Called when the payment completes.                                                                         |
| `paymentFailedListener`   | `(message: string) => void` | yes      | Called on failure, with a message.                                                                         |
| `paymentCanceledListener` | `() => void`                | yes      | Called when the customer cancels.                                                                          |
| `isEmbedded`              | `boolean`                   | no       | Render the checkout inline (embedded) instead of as a modal.                                               |
| `flow`                    | `InitFlowOptions`           | no       | Per-embed flow overrides, e.g. `{ walletConnect: true }` to offer wallet connection alongside the QR code. |

### `Transaction`

| Field             | Type                      | Required | Description                                       |
| ----------------- | ------------------------- | -------- | ------------------------------------------------- |
| `amount`          | `number`                  | yes      | Amount to charge.                                 |
| `currency`        | `'USD' \| 'TRY' \| 'PHP'` | yes      | Fiat currency the amount is denominated in.       |
| `referenceNumber` | `string`                  | yes      | Your unique reference for this payment.           |
| `descriptor`      | `string`                  | no       | Human-readable description shown to the customer. |

### Environments

| Environment | Flags                        |
| ----------- | ---------------------------- |
| Production  | `dev: false, sandbox: false` |
| Sandbox     | `sandbox: true`              |
| Development | `dev: true`                  |

## Updating the transaction

Before the customer pays, update the amount or currency. This also resets the checkout UI to its initial state.

```js
window.Lydian.updateTransaction({
  amount: 1.45,
  currency: 'USD',
  descriptor: 'Order #1234',
  referenceNumber: 'your-unique-ref',
})
```

## Listeners

Provide these callbacks in `init` to react to the payment outcome:

- `paymentSuccessListener()` — the payment completed.
- `paymentFailedListener(message)` — the payment failed; `message` describes why.
- `paymentCanceledListener()` — the customer cancelled.

## Supported assets & networks

Which assets appear at checkout is controlled by your Lydian account configuration; the SDK renders whatever your account has enabled across the supported networks.

## Related documentation

- [Web Checkout](https://developer.lydian.com/guides/web-checkout.md) — step-by-step embedding guide.
- [Accept Your First Payment](https://developer.lydian.com/guides/accept-a-payment.md) — the hosted-checkout alternative.
- API Reference: [Sessions](https://developer.lydian.com/api/session.md) · [Transactions](https://developer.lydian.com/api/transaction.md).