Merchant

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

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
    "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": {
            "hideNoWalletOption": {BOOL},
            "showApprovalPage": {BOOL},
            "skipConfirmationPage": {BOOL}
        }
    },
    "inherit": { // OPTIONAL — take these settings from the parent account
        "inheritCheckoutConfig": {BOOL},
        "inheritAllowedWallets": {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},
        "canSetCryptoNetworkConfigs": {BOOL},
        "canSetDefaultRecommendedNetwork": {BOOL},
        "canSetHighThreshold": {BOOL},
        "canSetKYCEnabled": {BOOL},
        "canSetKYCThreshold": {BOOL},
        "canSetRefundWindowHours": {BOOL},
        "canSetSettlement": {BOOL},
        "canSetTravelRulesRegionalThreshold": {BOOL}
    }
}'

Create Merchant Response

The response is the full merchant object. In addition to the fields below, it echoes the configuration submitted on create/update: allowedCrypto, allowedWallets, allowedWalletsConfig, checkoutConfig, cryptoNetworkConfigs, feeConfig, inherit, canSet, kycEnabled, kycThreshold, kycThresholdCustodial, highThreshold, refundWindowHours, travelRulesRegionalThreshold, travelRulesRegionalThresholdCustodial, and logoFilename.

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
name
Type
string
Description
Name of the merchant.
Name
dba
Type
string
Description
Doing business as name of the merchant.
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
status
Type
number
Description
Status of the merchant. Status as 0 means the merchant is under review, 1 means the merchant is enabled, and -1 means the merchant is disabled.
Name
descriptor
Type
string
Description
Descriptor of the merchant.
Name
accountID
Type
string
Description
Account ID of the merchant.
Name
externalMID
Type
string
Description
External merchant id of the merchant.
Name
merchantDiscountRate
Type
object
Description
Merchant discount rate applied per transaction.
Name
Percentage
Type
number
Description
Rate as a fraction — 0.025 is 2.5%.
Name
FlatRate
Type
number
Description
Flat fee in FlatRateCurrency units.
Name
FlatRateCurrency
Type
string
Description
ISO 4217 currency code for the flat fee.

example response

{
    "createdAt": "2025-08-12T03:20:02.769Z",
    "updatedAt": "2025-08-12T03:20:02.769Z",
    "UUID": "b9280199-ab1b-4545-a625-1728ba354abf",
    "name": "Brimspire",
    "dba": "Brimspire",
    "address1": "75831 Marvin Lodge",
    "address2": "",
    "city": "Janyport",
    "region": "VA",
    "country": "US",
    "status": 1,
    "descriptor": "",
    "accountID": "33c0dadc-bd86-45ae-b4d6-62f149313701",
    "externalMID": "1ecf316f-0821-46d4-820c-5d9313a5569c",
    "merchantDiscountRate": {
        "Percentage": 0.025,
        "FlatRate": 0,
        "FlatRateCurrency": ""
    }
}

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
    },
    "allowedCrypto": "{COMMA_SEPARATED_LIST_OF_ALLOWED_CRYPTO}", // OPTIONAL
    "allowedWallets": ["{WALLET_NAME}"], // OPTIONAL
    "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": {
            "hideNoWalletOption": {BOOL},
            "showApprovalPage": {BOOL},
            "skipConfirmationPage": {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} }
        }
    },
    "inherit": { // OPTIONAL — take these settings from the parent account
        "inheritCheckoutConfig": {BOOL},
        "inheritAllowedWallets": {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},
        "canSetCryptoNetworkConfigs": {BOOL},
        "canSetDefaultRecommendedNetwork": {BOOL},
        "canSetHighThreshold": {BOOL},
        "canSetKYCEnabled": {BOOL},
        "canSetKYCThreshold": {BOOL},
        "canSetRefundWindowHours": {BOOL},
        "canSetSettlement": {BOOL},
        "canSetTravelRulesRegionalThreshold": {BOOL}
    }
}'

Update Merchant Response

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
name
Type
string
Description
Name of the merchant.
Name
dba
Type
string
Description
Doing business as name of the merchant.
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
status
Type
number
Description
Status of the merchant. Status as 0 means the merchant is under review, 1 means the merchant is enabled, and -1 means the merchant is disabled.
Name
descriptor
Type
string
Description
Descriptor of the merchant.
Name
accountID
Type
string
Description
Account ID of the merchant.
Name
externalMID
Type
string
Description
External merchant id of the merchant.
Name
merchantDiscountRate
Type
object
Description
Merchant discount rate applied per transaction.
Name
Percentage
Type
number
Description
Rate as a fraction — 0.025 is 2.5%.
Name
FlatRate
Type
number
Description
Flat fee in FlatRateCurrency units.
Name
FlatRateCurrency
Type
string
Description
ISO 4217 currency code for the flat fee.

example response

{
    "createdAt": "2025-08-12T03:20:02.769Z",
    "updatedAt": "2025-08-12T03:20:02.769Z",
    "UUID": "b9280199-ab1b-4545-a625-1728ba354abf",
    "name": "Brimspire",
    "dba": "Brimspire",
    "address1": "75831 Marvin Lodge",
    "address2": "",
    "city": "Janyport",
    "region": "VA",
    "country": "US",
    "status": 1,
    "descriptor": "",
    "accountID": "33c0dadc-bd86-45ae-b4d6-62f149313701",
    "externalMID": "1ecf316f-0821-46d4-820c-5d9313a5569c",
    "merchantDiscountRate": {
        "Percentage": 0.025,
        "FlatRate": 0,
        "FlatRateCurrency": ""
    }
}

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

Name
merchants
Type
array
Description
List of merchants associated with this account.
Merchant Object
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
name
Type
string
Description
Name of the merchant.
Name
dba
Type
string
Description
Doing business as name of the merchant.
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
status
Type
number
Description
Status of the merchant. Status as 0 means the merchant is under review, 1 means the merchant is enabled, and -1 means the merchant is disabled.
Name
descriptor
Type
string
Description
Descriptor of the merchant.
Name
accountID
Type
string
Description
Account ID of the merchant.
Name
externalMID
Type
string
Description
External merchant id of the merchant.
Name
merchantDiscountRate
Type
object
Description
Merchant discount rate applied per transaction, with Percentage (fraction — 0.025 is 2.5%), FlatRate (flat fee in FlatRateCurrency units), and FlatRateCurrency (ISO 4217).
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

{
    "merchants": [
        {
            "createdAt": "2025-08-12T03:20:02.769Z",
            "updatedAt": "2025-08-12T03:20:02.769Z",
            "UUID": "b9280199-ab1b-4545-a625-1728ba354abf",
            "name": "Brimspire",
            "dba": "Brimspire",
            "address1": "75831 Marvin Lodge",
            "address2": "",
            "city": "Janyport",
            "region": "VA",
            "country": "US",
            "status": 1,
            "descriptor": "",
            "accountID": "33c0dadc-bd86-45ae-b4d6-62f149313701",
            "externalMID": "1ecf316f-0821-46d4-820c-5d9313a5569c",
            "merchantDiscountRate": {
                "Percentage": 0.025,
                "FlatRate": 0,
                "FlatRateCurrency": ""
            }
        }
    ],
    "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

The response is the same structure as the Create Merchant Response.

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

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, skipConfirmationPage.
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,
            "skipConfirmationPage": 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.