Merchant

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.

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.

Name
createdAt
Type
string
Description
Created at date time of the merchant.
Name
updatedAt
Type
string
Description
Updated at date time of the merchant.
Name
UUID
Type
string
Description
Unique identifier for the merchant.
Name
unifiedConfig
Type
object
Description
The merchant's profile and configuration, including:
Name
name
Type
string
Description
Name of the merchant.
Name
dba
Type
string
Description
Doing business as name of the merchant.
Name
descriptor
Type
string
Description
Descriptor of the merchant.
Name
logoFilename
Type
string
Description
File name of the merchant's logo.
Name
status
Type
number
Description
Status of the merchant: 0 under review, 1 enabled, -1 disabled, -2 archived.
Name
address1
Type
string
Description
Street address 1 of the merchant.
Name
address2
Type
string
Description
Street address 2 of the merchant.
Name
city
Type
string
Description
City of the merchant.
Name
region
Type
string
Description
Region or state of the merchant.
Name
country
Type
string
Description
Country of the merchant.
Name
allowedAssets
Type
array
Description
Assets the merchant accepts. Each asset has a code (for example USDT), a type (coin or token), and networks, an array of network names.
Name
allowedWallets
Type
array
Description
Names of the wallets allowed at checkout.
Name
allowedWalletsConfig
Type
array
Description
Per-wallet checkout presentation. Each entry has name, isFeatured, featuredNote, and order.
Name
cryptoNetworkConfigs
Type
object
Description
Per-network settings, keyed by network name. Each network has cryptoAssetConfigs, keyed by asset, with minConfirmsLow, minConfirmsHigh, and qrExpirationSeconds.
Name
defaultRecommendedNetwork
Type
string
Description
Network recommended to customers by default at checkout.
Name
kycEnabled
Type
boolean
Description
Whether KYC verification is enabled.
Name
kycThreshold
Type
number
Description
Amount, in local currency, at which KYC verification is required.
Name
kycThresholdCustodial
Type
number
Description
KYC threshold applied when paying from a custodial wallet.
Name
travelRulesRegionalThreshold
Type
object
Description
Travel rule thresholds in local currency, keyed by region.
Name
travelRulesRegionalThresholdCustodial
Type
object
Description
Travel rule thresholds applied when paying from a custodial wallet, keyed by region.
Name
fees
Type
object
Description
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.
Name
cancelTransactionEnabled
Type
boolean
Description
Whether customers may cancel an in-progress transaction.
Name
checkoutConfig
Type
object
Description
Hosted checkout branding: logoURL, termNotice, theme (primaryColor, accentColor, backgroundColor, textColor), fonts (family, familyURL), and flow (assetFirst, showApprovalPage, hideNoWalletOption).
Name
highThreshold
Type
number
Description
High-value transaction threshold.
Name
merchantDiscountRate
Type
object
Description
Merchant discount rate applied per transaction: percentage (a fraction — 0.025 is 2.5%), flatRate (flat fee in flatRateCurrency units), and flatRateCurrency (ISO 4217).
Name
settlementFrequency
Type
string
Description
How often the merchant is settled. One of hourly, six_hourly, daily, weekly, biweekly, or monthly.
Name
settlementAnchor
Type
string
Description
Timestamp anchoring the settlement schedule.
Name
refundWindowHours
Type
number
Description
Number of hours after a payment during which it can be refunded.
Name
accountID
Type
string
Description
Account ID of the merchant.
Name
canSet
Type
object
Description
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.
Name
externalMID
Type
string
Description
External merchant id of the merchant.
Name
inherit
Type
object
Description
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

{
    "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

POST /accounts/{accountUUID}/merchants

POST

/accounts/{accountUUID}/merchants

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, 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.

Name
errorCode
Type
number
Description
Numeric Lydian error code identifying the failure.
Name
message
Type
string
Description
Human-readable description of the failure.

error response

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

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

PUT /accounts/{accountUUID}/merchants/{merchantUUID}

PUT

/accounts/{accountUUID}/merchants/{merchantUUID}

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, with the merchant's stored values.

List Merchants

GET /accounts/{accountUUID}/merchants

GET

/accounts/{accountUUID}/merchants

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 with the merchant's stored values.

Name
merchants
Type
array
Description
List of merchant objects associated with this account.
Name
metadata
Type
object
Description
Pagination metadata for the query.
Metadata Object
Name
totalCount
Type
number
Description
Total number of items available across all pages for the query.
Name
count
Type
number
Description
Number of items returned in the current page.
Name
page
Type
number
Description
Current page number (1-based).
Name
pageSize
Type
number
Description
Maximum number of items per page.

example response (merchant objects abbreviated)

{
    "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

GET /accounts/{accountUUID}/merchants/{MerchantUUID}

GET

/accounts/{accountUUID}/merchants/{MerchantUUID}

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 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.

GET /accounts/{accountUUID}/merchantsbyexternalmid/{externalMID}

GET

/accounts/{accountUUID}/merchantsbyexternalmid/{externalMID}

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, with inherited settings resolved the same way as 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`.

Name
errorCode
Type
number
Description
Numeric Lydian error code identifying the failure.
Name
message
Type
string
Description
Human-readable description of the failure.

error response

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

Archive Merchant

DELETE /accounts/{accountUUID}/merchants/{merchantUUID}

DELETE

/accounts/{accountUUID}/merchants/{merchantUUID}

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

POST /accounts/{accountUUID}/merchants/{merchantUUID}/uploadlogo

POST

/accounts/{accountUUID}/merchants/{merchantUUID}/uploadlogo

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:

{
    "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.

GET /merchant/config

GET

/merchant/config

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

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

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

example response

{
    "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"
    }
}

Configuration for a merchant can be updated using Update Merchant.