curl -X POST https://api.liddie.io/api/v1/widgets \
--cookie "<dashboard session>" \
-H 'Content-Type: application/json' \
-d '{
"type": "donation",
"name": "Homepage donate button",
"amountMode": "variable",
"allowedOrigins": ["example.com"]
}'
// Dashboard-session endpoint: send your dashboard JWT as a Bearer token
const res = await fetch('https://api.liddie.io/api/v1/widgets', {
method: 'POST',
headers: {
Authorization: `Bearer ${dashboardJwt}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
type: 'donation',
name: 'Homepage donate button',
amountMode: 'variable',
allowedOrigins: ['example.com'],
}),
})
const { data: widget } = await res.json()
{ "ok": true, "data": { ...widget... } }
Widgets
Create a widget
Create an embeddable Liddie payment or donation widget — a button or form that starts crypto checkouts with your publishable key, no backend required.
POST
/
api
/
v1
/
widgets
curl -X POST https://api.liddie.io/api/v1/widgets \
--cookie "<dashboard session>" \
-H 'Content-Type: application/json' \
-d '{
"type": "donation",
"name": "Homepage donate button",
"amountMode": "variable",
"allowedOrigins": ["example.com"]
}'
// Dashboard-session endpoint: send your dashboard JWT as a Bearer token
const res = await fetch('https://api.liddie.io/api/v1/widgets', {
method: 'POST',
headers: {
Authorization: `Bearer ${dashboardJwt}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
type: 'donation',
name: 'Homepage donate button',
amountMode: 'variable',
allowedOrigins: ['example.com'],
}),
})
const { data: widget } = await res.json()
{ "ok": true, "data": { ...widget... } }
Creates a widget — an embeddable Payment or Donation button/form. Visitors on your allowed origins start checkouts through the public checkout endpoint with your publishable key (
Returns
pk_live_*). The resulting payments appear in your normal payment list and webhook stream like any other.
Who can call this
Send your dashboard JWT (browser session) as a Bearer token, with team rolemerchant_admin or merchant_member plus the widgets:manage permission. Widget management is not accessible with an API key. Mutations are rate-limited to 20 requests per minute. See the Authentication guide.
Required fields
string
required
payment or donation. Donation widgets can collect donor fields.string
required
Internal label (1–80 characters).
string
required
fixed or variable. fixed needs fixedAmount; variable lets the visitor type an amount.Security boundary
string[]
Only pages on these origins can start a checkout through this widget (max 20 entries). Each entry is at most 253 characters, and entries are normalized to hostnames (
https://example.com is stored as example.com). Empty = any origin.Matching is host-equal or subdomain at any depth: listing
example.com also authorizes shop.example.com, evil.dev.example.com, and so on. For inline widgets, the embed CSP frame-ancestors is likewise expanded to the host and *.host. List the most specific host that embeds the widget — never a parent domain whose subdomains you do not fully control (shared hosting, delegated subdomains), or you silently authorize every subdomain to start checkouts and to frame the hosted checkout.Always set
allowedOrigins — it is the security boundary for the public checkout, and an empty list means any origin can start checkouts through this widget. List exactly the hostnames that embed it.Optional fields
Optional fields
string | number
Required with
amountMode: fixed. Fiat amount (same semantics as payment create).string[]
Restrict which cryptos the payer may choose (max 50 entries). Empty = all of yours.
string[]
Donation forms: subset of
name, email, phone, address, comment.string[]
Donation forms: subset of
name, email, phone, address, comment that the donor must fill in.string
redirect (hosted invoice redirect, the default) or inline (embedded iframe-in-modal flow). inline requires a non-empty allowedOrigins.string
Absolute
http(s) URL (max 2048 characters) the payer lands on after a successful payment — honored in both display modes. Its host must pass your callback-domain allowlist (merchant settings callbackDomains), otherwise the request is rejected with 400. Empty string clears it. Liddie appends a query contract to whatever query your URL already carries: ?status=paid&invoice_id=<slug>&source=widget&widget_id=<id>&widget_type=<type>.string
Same rules as
successUrl, but for a terminal non-success outcome (expired, failed, cancelled — delivered with status=expired|failed|cancelled). Omit to reuse successUrl for every outcome.object
The button designer options — see the Branding fields accordion below.
boolean
Set to
false to disable the widget without deleting it.Branding fields (branding.*)
Branding fields (branding.*)
string
Text on the button (max 40 characters).
string
Short line under the button label (max 48 characters).
string
Button accent color as a hex value, e.g.
#ff0080 (max 7 characters).string
Button layout:
badge, stacked, lightning, multicoin, coins or heart.string
Icon on the button:
auto, none, bitcoin, ethereum, usdt, lightning, heart, coins or multicoin.string
Button size:
sm, md or lg.boolean
Stretch the button to the container’s full width.
number
Corner radius in pixels, from 0 to 32.
curl -X POST https://api.liddie.io/api/v1/widgets \
--cookie "<dashboard session>" \
-H 'Content-Type: application/json' \
-d '{
"type": "donation",
"name": "Homepage donate button",
"amountMode": "variable",
"allowedOrigins": ["example.com"]
}'
// Dashboard-session endpoint: send your dashboard JWT as a Bearer token
const res = await fetch('https://api.liddie.io/api/v1/widgets', {
method: 'POST',
headers: {
Authorization: `Bearer ${dashboardJwt}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
type: 'donation',
name: 'Homepage donate button',
amountMode: 'variable',
allowedOrigins: ['example.com'],
}),
})
const { data: widget } = await res.json()
{ "ok": true, "data": { ...widget... } }
201 with the created widget object.
See also
- Widget checkout (public) — the public endpoint visitors hit through this widget.
- Update a widget — full update with this same body.
- Webhooks & IPN — widget payments emit the same events as any other payment.