01Overview
- Sign up, then finish onboarding in the dashboard. You connect the PayPal Business account that receives your money; PayPal collects any identity and tax details directly. Sellers can be based in the US, Canada, the UK and 14 other European countries (see supported countries). Buyers pay by card, and payments settle straight into your own PayPal account (or, for accounts processed by Stripe, your own connected account), so you are the merchant of record.
- Create an API key in Dashboard, API keys. The full key is shown once.
- From your server, create a payment with
POST /v1/payments(or share a payment link). Send the buyer to the returnedcheckout_url, or embed the checkout withlynent.js. - Fulfil the order when you receive the
payment.succeededwebhook.
- Base URL
https://lynent.com- Format
- JSON requests and responses, snake_case fields
- Amounts
- Integers in the smallest currency unit (cents for USD and EUR, pence for GBP, ore for DKK, SEK and NOK)
- Currency
- Your country's currency: USD, CAD, GBP, EUR, DKK, SEK or NOK
- Timestamps
- Unix seconds (
created,updated) - Spec
- OpenAPI 3.1 description of every endpoint and webhook event
| Resource | Endpoints |
|---|---|
| Payments | /v1/payments, /v1/payments/:id, /cancel, /refunds |
| Refunds | /v1/refunds, /v1/refunds/:id |
| Customers | /v1/customers, /v1/customers/:id, /payments |
| Payment links | /v1/payment_links, /v1/payment_links/:id |
| Balance and payouts | /v1/balance, /v1/payouts, /v1/payouts/:id |
| Events | /v1/events, /v1/events/:id |
| Webhook endpoints | /v1/webhook_endpoints and /:id, /rotate_secret |
02Authentication
Authenticate every /v1 request with a secret API key in the Authorization header.
Authorization: Bearer lyn_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
lyn_test_keys work only while the platform is in test mode, andlyn_live_keys only in live mode. A key for the wrong mode returns401 api_key_mode_mismatch. See Test mode.- Keys are secrets. Use them only from your server, never in browsers, mobile apps or public repositories. Revoke a leaked key in the dashboard right away.
- Your account must be fully onboarded (charges enabled) to create payments. Until then, payment creation returns
403 account_not_ready. Customers, payment links and webhook endpoints can be set up before that.
03Node SDK
@lynent/node is the official Node.js client: ESM, no dependencies, built on the fetch in Node 18 and later. It adds an Idempotency-Key to every POST, retries network errors, 429 and 5xx responses with the same key, throws typed errors, and pages through lists for you.
npm install @lynent/node
The package is not on the public npm registry yet. Until it is, every example on this page also shows the request with curl, which works from any HTTP client.
import Lynent from '@lynent/node';
const lynent = new Lynent(process.env.LYNENT_API_KEY, {
// baseUrl: 'http://localhost:3000', // defaults to https://lynent.com
// timeoutMs: 30000,
// maxNetworkRetries: 2,
});
const balance = await lynent.balance.retrieve();
console.log(balance.available, balance.lastResponse.requestId);
| Resource | Methods |
|---|---|
payments | create, retrieve, list, cancel, refund |
refunds | create, retrieve, list |
customers | create, retrieve, update, del, list, listPayments |
paymentLinks | create, retrieve, update, list |
balance | retrieve |
payouts | retrieve, list |
events | retrieve, list |
webhookEndpoints | create, retrieve, update, del, list, rotateSecret |
Lynent.webhooks | verify(rawBody, signatureHeader, secret, toleranceSec = 300) |
Every method takes an optional last argument { idempotencyKey, timeoutMs, maxNetworkRetries, signal }. Returned objects carry lastResponse (request id, status, whether the response was an idempotent replay), which is not enumerable and never appears in JSON.stringify.
04Create a payment
POST/v1/payments
Returns 201 and the payment.
| Field | Type | Notes |
|---|---|---|
amount | integer | Smallest currency unit. Minimum 100 ($1.00, €1.00, £1.00, CA$1.00), 500 for DKK and 1000 for SEK and NOK, and it must be greater than the Lynent fee. Required unless you send line_items; with both, they must match (400 amount_mismatch). |
currency | string | Three-letter ISO code. Optional: defaults to your account's currency (set by your country). Any other currency is refused with 400 unsupported_currency, so no conversion ever happens. |
line_items | array | Up to 100 { name, quantity, unit_amount }. See Line items. |
description | string | Shown to the buyer at checkout. Up to 1000 characters. |
metadata | object | Up to 20 string pairs (keys up to 40 characters, values up to 500). Keys starting with lynent_ are reserved. |
customer | string | An existing customer id (cus_...). |
customer_email | string | Without customer, finds or creates the customer with this email. With it, the emails must match. |
receipt_email | string | Where the card receipt is emailed in live mode. Defaults to customer_email, else the email of customer. |
statement_descriptor_suffix | string | Up to 22 Latin characters, at least one letter, appended to the descriptor on the buyer's card statement. |
success_url | string | Where the buyer goes after paying. Must be https (http only for localhost). {PAYMENT_ID} is replaced with the payment id. |
cancel_url | string | Shown as a "Cancel and return" link at checkout. |
Unknown fields are rejected with 400 validation_error.
curl https://lynent.com/v1/payments \
-H "Authorization: Bearer $LYNENT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_1234" \
-d '{
"amount": 2500,
"currency": "usd",
"description": "Pro plan, 1 month",
"metadata": { "order_id": "1234" },
"customer_email": "buyer@example.com",
"success_url": "https://shop.example.com/thanks?payment={PAYMENT_ID}",
"cancel_url": "https://shop.example.com/cart"
}'
const payment = await lynent.payments.create(
{
amount: 2500,
currency: 'usd',
description: 'Pro plan, 1 month',
metadata: { order_id: String(order.id) },
customer_email: order.email,
success_url: 'https://shop.example.com/thanks?payment={PAYMENT_ID}',
},
{ idempotencyKey: `order_${order.id}` },
);
// Save payment.id on your order, then send the buyer to payment.checkout_url
{
"id": "pay_3kJ8...",
"object": "payment",
"amount": 2500,
"currency": "usd",
"fee": 281,
"base_fee": 243,
"international_fee": null,
"card_country": null,
"net": 2219,
"amount_refunded": 0,
"status": "requires_payment",
"description": "Pro plan, 1 month",
"metadata": { "order_id": "1234" },
"customer_email": "buyer@example.com",
"customer": "cus_9Pd2...",
"line_items": [],
"receipt_email": "buyer@example.com",
"statement_descriptor_suffix": null,
"payment_link": null,
"success_url": "https://shop.example.com/thanks?payment={PAYMENT_ID}",
"cancel_url": "https://shop.example.com/cart",
"checkout_url": "https://lynent.com/pay/pay_3kJ8...",
"client_secret": "pi_..._secret_...",
"livemode": false,
"created": 1763251200,
"updated": 1763251200,
"canceled_at": null
}
Statuses: requires_payment, processing, succeeded, failed, canceled, refunded, partially_refunded.
It lets a browser complete this one payment, and it appears only in the create response. Do not log or store it. The hosted checkout and the widget handle it for you, so most integrations can ignore it.
05Line items
Send line_items instead of (or as well as) amount and the checkout shows an order summary: each item with its quantity, unit price and line total, then the total. Lynent stores each item with amount = quantity × unit_amount and charges the sum.
| Field | Type | Notes |
|---|---|---|
name | string, required | 1 to 250 characters. |
quantity | integer, required | 1 to 10,000. |
unit_amount | integer, required | Cents, 0 or more. A zero-price line is allowed, but the total must still be at least $1.00 and greater than the fee. |
curl https://lynent.com/v1/payments \
-H "Authorization: Bearer $LYNENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"currency": "usd",
"line_items": [
{ "name": "Ceramic mug", "quantity": 2, "unit_amount": 1200 },
{ "name": "Shipping", "quantity": 1, "unit_amount": 500 }
]
}'
const payment = await lynent.payments.create({
line_items: [
{ name: 'Ceramic mug', quantity: 2, unit_amount: 1200 },
{ name: 'Shipping', quantity: 1, unit_amount: 500 },
],
});
payment.amount; // 2900
payment.line_items; // [{ name: 'Ceramic mug', quantity: 2, unit_amount: 1200, amount: 2400 }, ...]
Errors: amount_required (neither field), amount_mismatch (both, different totals), too_many_line_items, invalid_line_item, amount_too_small. Payment links take the same line_items.
06Hosted checkout
Redirect the buyer to checkout_url. The page shows your name, logo and brand colour (set them in Dashboard, Branding), the order summary for line items, and an optional receipt email field. It takes the payment, then sends the buyer to success_url. Card numbers are typed into a secure payment field and never touch Lynent's servers or yours.
From the browser you can also use the widget helper:
<script src="https://lynent.com/js/lynent.js"></script>
<script>
Lynent.redirect('pay_3kJ8...');
</script>
Arriving at success_url does not prove the payment succeeded. Confirm it with a webhook or GET /v1/payments/:id.
07Embed the checkout
<div id="lynent-checkout"></div>
<script src="https://lynent.com/js/lynent.js"></script>
<script src="/your-checkout.js"></script>
const checkout = Lynent.mount('#lynent-checkout', {
payment: 'pay_3kJ8...', // from POST /v1/payments (create it on your server)
onSuccess: (e) => { // { paymentId, status: 'succeeded', confirmed }
window.location.href = '/orders/thanks';
},
onError: (e) => { // { paymentId, code, recoverable }
if (!e.recoverable) showMessage('Payment could not be completed.');
},
});
// checkout.destroy() removes the iframe and listeners.
How the embed works:
Lynent.mountrenders an iframe of/pay/:id?embed=1&origin=<your page origin>. The iframe hasallow="payment *"so Apple Pay and Google Pay can work.- Card details are typed into a secure payment field inside that iframe. Neither your page nor Lynent's servers ever see card numbers.
- The checkout sends
lynent:successandlynent:errormessages only to your page's origin. Onlylynent:resize(a height in pixels) is sent to any origin. Messages never contain secrets or customer data. lynent.jsaccepts a message only when its origin is the Lynent origin taken from the script's ownsrc, it comes from the iframe that call created, and it names the mounted payment id.- Your page must be https (or http://localhost during development).
- If your site sends a Content Security Policy, allow
script-src https://lynent.comandframe-src https://lynent.com. - Some payment methods and 3D Secure flows redirect. They complete inside the iframe and return to the embedded checkout. For the widest compatibility, use the hosted redirect.
onSuccess only updates your page. Fulfil orders after your server receives payment.succeeded or reads status: "succeeded" from the API.
08Retrieve, list and cancel payments
GET/v1/payments/:id
client_secretis null on reads.GET/v1/payments
Filters:status,customer,payment_link, plus pagination.POST/v1/payments/:id/cancel
Optionalcancellation_reason:duplicate,fraudulent,requested_by_customer,abandoned.
curl https://lynent.com/v1/payments/pay_3kJ8... \
-H "Authorization: Bearer $LYNENT_API_KEY"
curl "https://lynent.com/v1/payments?status=succeeded&limit=20" \
-H "Authorization: Bearer $LYNENT_API_KEY"
curl -X POST https://lynent.com/v1/payments/pay_3kJ8.../cancel \
-H "Authorization: Bearer $LYNENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "cancellation_reason": "abandoned" }'
const payment = await lynent.payments.retrieve('pay_3kJ8...');
for await (const p of lynent.payments.list({ status: 'succeeded', limit: 100 })) {
console.log(p.id, p.amount, p.net);
}
await lynent.payments.cancel('pay_3kJ8...', { cancellation_reason: 'abandoned' });
Only unpaid payments (requires_payment or failed) can be canceled. Canceling a canceled payment returns it unchanged; anything paid or processing returns 400 payment_not_cancelable. A payment.canceled webhook follows.
09Refunds
POST/v1/payments/:id/refunds
Omitamountfor a full refund of what is left. Optionalreason.GET/v1/refunds
Filter withpayment=pay_...andcreated[...].GET/v1/refunds/:id
One refund.
curl https://lynent.com/v1/payments/pay_3kJ8.../refunds \
-H "Authorization: Bearer $LYNENT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: refund_order_1234_1" \
-d '{ "amount": 1000, "reason": "requested_by_customer" }'
curl "https://lynent.com/v1/refunds?payment=pay_3kJ8..." \
-H "Authorization: Bearer $LYNENT_API_KEY"
const refund = await lynent.payments.refund('pay_3kJ8...', { amount: 1000 });
// or: await lynent.refunds.create({ payment: 'pay_3kJ8...', amount: 1000 });
const refunds = await lynent.refunds.list({ payment: 'pay_3kJ8...' });
{
"id": "re_7Lm2...",
"object": "refund",
"payment": "pay_3kJ8...",
"amount": 1000,
"status": "succeeded",
"created": 1763254800
}
Only succeeded and partially_refunded payments can be refunded. The buyer gets the full refunded amount back, paid from your balance. The payment's status becomes partially_refunded or refunded, and a payment.refunded webhook is sent. Refunds you make in the dashboard are synced too.
Refund a $50.00 payment in full and the buyer gets $50.00 back; the $4.55 fee stays with Lynent. The fee covers card processing, and the card processor does not return its processing cost when a payment is refunded.
10Customers
Customers group payments by buyer. A payment created with customer_email finds or creates the customer with that email, so most integrations never call these endpoints directly.
POST/v1/customers
email,name,phone,metadata, all optional. Returns 201.GET/v1/customers
Filters:email(exact, case-insensitive),created[...].GET/v1/customers/:id
One customer.POST/v1/customers/:id
Update.nullclears a field.metadatais merged; a key set to""is removed.DELETE/v1/customers/:id
Deletes the customer. Past payments keep theircustomerid.GET/v1/customers/:id/payments
The customer's payments; filter withstatus.
curl https://lynent.com/v1/customers \
-H "Authorization: Bearer $LYNENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "ada@example.com", "name": "Ada Lovelace", "metadata": { "crm_id": "42" } }'
curl "https://lynent.com/v1/customers?email=ada@example.com" \
-H "Authorization: Bearer $LYNENT_API_KEY"
const customer = await lynent.customers.create({ email: 'ada@example.com', name: 'Ada Lovelace' });
await lynent.customers.update(customer.id, { phone: '+1 555 0100', metadata: { crm_id: '' } });
const payment = await lynent.payments.create({ amount: 4900, customer: customer.id });
const history = await lynent.customers.listPayments(customer.id, { status: 'succeeded' });
await lynent.customers.del(customer.id); // { id, object: 'customer', deleted: true }
{
"id": "cus_9Pd2...",
"object": "customer",
"email": "ada@example.com",
"name": "Ada Lovelace",
"phone": null,
"metadata": { "crm_id": "42" },
"livemode": false,
"created": 1763251200,
"updated": 1763251200
}
11Payment links
A payment link is a URL you can share anywhere: in an email, a bio or a QR code. Opening url shows a short page that continues straight to Lynent's checkout with a new payment for the link. Opening the link alone creates nothing, so link previews and mail scanners never start payments. Links have a fixed amount or line_items, with the same rules as payments. You can also create and manage them in Dashboard, Payment links.
POST/v1/payment_links
title(required),description,amountorline_items,currency,collect_email(defaulttrue),success_url. Returns 201.GET/v1/payment_links
Filters:active=true|false,created[...].GET/v1/payment_links/:id
One link.POST/v1/payment_links/:id
Updatetitle,descriptionoractive. Price and items are fixed: create a new link to change them.
curl https://lynent.com/v1/payment_links \
-H "Authorization: Bearer $LYNENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Workshop ticket",
"line_items": [{ "name": "Ticket", "quantity": 1, "unit_amount": 4500 }],
"collect_email": true,
"success_url": "https://shop.example.com/thanks"
}'
const link = await lynent.paymentLinks.create({
title: 'Workshop ticket',
line_items: [{ name: 'Ticket', quantity: 1, unit_amount: 4500 }],
collect_email: true,
});
console.log(link.url); // https://lynent.com/l/plink_...
// Sold out: turn it off. Visitors then see a page saying the link is no longer active.
await lynent.paymentLinks.update(link.id, { active: false });
// Payments made through the link
const paid = await lynent.payments.list({ payment_link: link.id, status: 'succeeded' });
{
"id": "plink_4Hs8...",
"object": "payment_link",
"title": "Workshop ticket",
"description": null,
"amount": 4500,
"currency": "usd",
"line_items": [{ "name": "Ticket", "quantity": 1, "unit_amount": 4500, "amount": 4500 }],
"active": true,
"collect_email": true,
"success_url": "https://shop.example.com/thanks",
"url": "https://lynent.com/l/plink_4Hs8...",
"payment_count": 0,
"livemode": false,
"created": 1763251200,
"updated": 1763251200
}
payment_countcounts succeeded payments made through the link. Each payment carriespayment_link, so yourpayment.succeededhandler can tell link sales apart.- Visiting a link that is turned off returns
410; an unknown link404; a link whose account cannot take payments503. Visits are rate limited per IP, and each link starts at most 30 new payments per minute. A buyer who goes back and opens the link again within 30 minutes gets the same unpaid payment. - With
collect_email: true(the default) the checkout asks the buyer for a receipt email. Set it tofalseto skip that field.
12Balance and payouts
GET/v1/balance
Available and pending funds, per currency.GET/v1/payouts
Filters:status(paid,pending,in_transit,canceled,failed),created[...].GET/v1/payouts/:id
One payout (po_...).
curl https://lynent.com/v1/balance \
-H "Authorization: Bearer $LYNENT_API_KEY"
curl "https://lynent.com/v1/payouts?status=paid&limit=10" \
-H "Authorization: Bearer $LYNENT_API_KEY"
const { available, pending } = await lynent.balance.retrieve();
for await (const payout of lynent.payouts.list({ status: 'paid' })) {
console.log(payout.id, payout.amount, new Date(payout.arrival_date * 1000));
}
{
"object": "balance",
"connected": true,
"available": [{ "amount": 45450, "currency": "usd" }],
"pending": [{ "amount": 9120, "currency": "usd" }],
"livemode": false
}
{
"id": "po_1Qx...",
"object": "payout",
"amount": 45450,
"currency": "usd",
"status": "paid",
"arrival_date": 1763424000,
"method": "standard",
"failure_code": null,
"failure_message": null,
"created": 1763337600
}
Both are read live from your connected account. For accounts paid out to PayPal, the money is in your PayPal balance: the balance object says held_by: "paypal" and there are no Lynent payouts to list. Before onboarding, the balance has connected: false and empty lists, and payouts return 403 account_not_ready. Payout cursors are payout ids.
13Events
Every webhook event is also stored, whether or not an endpoint was subscribed. Use the events API to catch up after downtime or to reconcile.
GET/v1/events
Filters:type,created[...]. Newest first.pingtest events are not listed.GET/v1/events/:id
The event exactly as it was delivered, plus"object": "event".
curl "https://lynent.com/v1/events?type=payment.succeeded&created[gte]=1763251200" \
-H "Authorization: Bearer $LYNENT_API_KEY"
const since = new Date(Date.now() - 24 * 60 * 60 * 1000);
for await (const event of lynent.events.list({ type: 'payment.succeeded', created: { gte: since } })) {
await markOrderPaid(event.data.object.metadata.order_id, event.data.object.id);
}
14Webhook endpoints
Manage the URLs that receive webhooks from the API or in Dashboard, Webhooks. Up to 16 endpoints per account. The URL must be https (http only for localhost during development) and must point to a public address.
POST/v1/webhook_endpoints
url, optionalevents(default["*"]). Returns 201 withsecret.GET/v1/webhook_endpoints
All endpoints, newest first.GET/v1/webhook_endpoints/:id
One endpoint.POST/v1/webhook_endpoints/:id
Updateurl,eventsorenabled.DELETE/v1/webhook_endpoints/:id
Delete it and drop its pending deliveries.POST/v1/webhook_endpoints/:id/rotate_secret
New secret, returned once. The old one stops working right away.
curl https://lynent.com/v1/webhook_endpoints \
-H "Authorization: Bearer $LYNENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://shop.example.com/webhooks/lynent", "events": ["payment.succeeded", "payment.refunded"] }'
const endpoint = await lynent.webhookEndpoints.create({
url: 'https://shop.example.com/webhooks/lynent',
events: ['payment.succeeded', 'payment.refunded'],
});
await saveSecret(endpoint.secret); // whsec_lyn_..., shown only here
await lynent.webhookEndpoints.update(endpoint.id, { enabled: false });
const { secret } = await lynent.webhookEndpoints.rotateSecret(endpoint.id);
secret appears only in the create and rotate_secret responses. It is never stored for idempotent replays: replaying either call returns "secret": null, so store it before you retry anything else.
15Webhooks
| Event | When | data.object |
|---|---|---|
payment.succeeded | The payment completed. Fulfil the order. | payment |
payment.processing | An asynchronous payment method is still processing. | payment |
payment.failed | The attempt failed. The buyer may retry. | payment |
payment.canceled | The payment was canceled. | payment |
payment.refunded | A full or partial refund was made (see amount_refunded). | payment |
dispute.created | The buyer opened a chargeback. Respond in the dashboard. | dispute |
payout.paid / payout.failed | A payout to your bank account landed or failed. | payout |
account.updated | Your account status or requirements changed. | account |
ping | Sent by the "Send test" button. | ping |
The payment object in events has the same fields as in the API, except client_secret, which webhooks never carry.
{
"id": "evt_9Hq2...",
"type": "payment.succeeded",
"created": 1763251260,
"livemode": false,
"data": { "object": { "id": "pay_3kJ8...", "object": "payment", "status": "succeeded", ... } }
}
Every delivery carries these headers:
Lynent-Signature: t=1763251260,v1=5f2b...e9
Lynent-Event-Id: evt_9Hq2...
v1 is the hex HMAC-SHA256 of t + "." + rawBody, keyed with your endpoint's full secret string. Verify it against the raw request body, before any JSON parsing. Reject timestamps more than 5 minutes old. Compare in constant time. During a secret rotation a header can carry more than one v1; accept the request if any of them matches.
import express from 'express';
import Lynent from '@lynent/node';
const app = express();
// express.raw keeps the exact bytes so the signature can be checked
app.post('/webhooks/lynent', express.raw({ type: 'application/json' }), async (req, res) => {
let event;
try {
event = Lynent.webhooks.verify(req.body, req.get('Lynent-Signature'), process.env.LYNENT_WEBHOOK_SECRET);
} catch (err) {
return res.status(400).send(err.code); // invalid_signature, timestamp_outside_tolerance, ...
}
// Deliveries can repeat: dedupe on event.id
if (await alreadyProcessed(event.id)) return res.sendStatus(200);
switch (event.type) {
case 'payment.succeeded':
await markOrderPaid(event.data.object.metadata.order_id, event.data.object.id);
break;
case 'payment.refunded':
await recordRefund(event.data.object);
break;
}
await markProcessed(event.id);
res.sendStatus(200); // respond 2xx quickly; do slow work asynchronously
});
Without the SDK, the same check takes a few lines of node:crypto:
import crypto from 'node:crypto';
const TOLERANCE_SECONDS = 300;
function verifyLynentSignature(rawBody, header, secret) {
if (typeof header !== 'string') return false;
let t = null;
const signatures = [];
for (const part of header.split(',')) {
const i = part.indexOf('=');
if (i < 0) continue;
const k = part.slice(0, i).trim();
const v = part.slice(i + 1).trim();
if (k === 't') t = v;
else if (k === 'v1') signatures.push(v);
}
if (!t || !/^\d+$/.test(t) || signatures.length === 0) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > TOLERANCE_SECONDS) return false;
const expected = crypto.createHmac('sha256', secret)
.update(`${t}.`).update(rawBody).digest('hex');
const expectedBuf = Buffer.from(expected, 'utf8');
return signatures.some((sig) => {
const sigBuf = Buffer.from(sig, 'utf8');
return sigBuf.length === expectedBuf.length && crypto.timingSafeEqual(sigBuf, expectedBuf);
});
}
- Any 2xx response counts as delivered. Anything else, or no response within 10 seconds, is retried with exponential backoff for up to 8 attempts. Redirects are not followed. Every delivery is listed in the dashboard.
- Events can arrive out of order. Treat
data.object.statusas the current state, and re-fetch withGET /v1/payments/:idif in doubt. Missed some? List them withGET /v1/events.
16Pagination
Every list endpoint returns the newest items first, in one shape:
{
"object": "list",
"data": [ { "id": "cus_C", ... }, { "id": "cus_B", ... } ],
"has_more": true,
"next_cursor": "cus_B"
}
| Parameter | Notes |
|---|---|
limit | 1 to 100. Default 10 (16 for webhook endpoints). |
starting_after | An id from the previous page, usually next_cursor. Returns the older items after it. |
ending_before | An id from the previous page. Returns the newer items before it. Cannot be combined with starting_after. |
created[gte], created[gt], created[lte], created[lt] | Unix-second bounds on created, on every list including payments. Combine them for a range. |
next_cursor is present only when has_more is true. Paging forward, pass it as starting_after; paging backwards with ending_before, pass it as ending_before. A cursor that is not one of your own ids returns 400 invalid_cursor.
curl "https://lynent.com/v1/customers?limit=100&created[gte]=1761955200" \
-H "Authorization: Bearer $LYNENT_API_KEY"
curl "https://lynent.com/v1/customers?limit=100&starting_after=cus_B" \
-H "Authorization: Bearer $LYNENT_API_KEY"
// The SDK follows next_cursor for you
for await (const customer of lynent.customers.list({ limit: 100 })) {
await sync(customer);
}
// Or collect up to a cap
const links = await lynent.paymentLinks.list({ active: true }).autoPagingToArray({ limit: 500 });
// One page at a time
const page = await lynent.payments.list({ limit: 25 });
if (page.has_more) await lynent.payments.list({ limit: 25, starting_after: page.next_cursor });
17Idempotency
Send an Idempotency-Key header on any POST: 1 to 255 printable characters without spaces, such as your order id. A retry with the same key and the same body returns the original response with the header Idempotent-Replayed: true, and creates nothing new. Keys are scoped to your account and expire after 24 hours, so you can retry safely after timeouts and network errors.
| Situation | Result |
|---|---|
| Same key, same method, path and body | The stored response, with Idempotent-Replayed: true. |
| Same key, different request | 409 idempotency_key_reused. |
| Same key while the first request is still running | 409 idempotency_key_in_use. Retry shortly. |
| The first request failed with an error | Nothing is stored, so a retry runs again. |
curl https://lynent.com/v1/payments \
-H "Authorization: Bearer $LYNENT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_1234" \
-d '{ "amount": 2500 }'
// The SDK sends a fresh key on every POST and reuses it on its own retries.
// Pass your own key to make retries across processes and restarts safe too:
const payment = await lynent.payments.create({ amount: 2500 }, { idempotencyKey: `order_${order.id}` });
payment.lastResponse.idempotentReplayed; // true if this was a replay
Secrets are never kept with stored responses: a replayed payment gets a freshly fetched client_secret (or null once it is paid), and a replayed webhook endpoint create or rotation returns "secret": null.
18Errors
Errors use standard HTTP status codes and one body shape. Every response, including errors, carries a Lynent-Request-Id header with the same value as request_id. Include it when you contact support.
{
"error": {
"type": "invalid_request_error",
"code": "amount_too_small",
"message": "Amount must be at least 100 cents.",
"request_id": "req_8fJ2kQ1xZr0aBcDe"
}
}
| Status | type | Example codes | SDK class |
|---|---|---|---|
| 400 | invalid_request_error | validation_error, amount_too_small, amount_mismatch, payment_not_refundable, refund_amount_too_large, invalid_cursor, invalid_json | LynentInvalidRequestError |
| 401 | authentication_error | missing_api_key, invalid_api_key, api_key_revoked, api_key_mode_mismatch | LynentAuthenticationError |
| 402 | card_error | The card was declined. The message is safe to show the buyer. | LynentCardError |
| 403 | permission_error | account_not_ready, account_disabled | LynentPermissionError |
| 404 | not_found_error | payment_not_found, customer_not_found, payment_link_not_found, ... Also for an id that belongs to another account. | LynentNotFoundError |
| 409 | conflict_error | idempotency_key_reused, idempotency_key_in_use | LynentConflictError |
| 429 | rate_limit_error | rate_limited. Back off and retry. | LynentRateLimitError |
| 5xx | api_error | Retry with the same Idempotency-Key. | LynentAPIError |
import Lynent, { LynentError, LynentInvalidRequestError } from '@lynent/node';
try {
await lynent.payments.create({ amount: 50 });
} catch (err) {
if (err instanceof LynentInvalidRequestError) {
console.warn(err.code, err.message); // amount_too_small ...
} else if (err instanceof LynentError) {
console.error(err.status, err.type, err.code, err.requestId);
} else {
throw err;
}
}
With no response at all (DNS, TLS, timeout), the SDK throws LynentConnectionError with status: 0 after its retries.
19Fees and payouts
Lynent fee = round(amount × 8.5%) plus a fixed fee in your currency, per successful charge: USD 30 (30 cents), CAD 40, GBP 25, EUR 30, DKK 250, SEK 300, NOK 300 (smallest units). It is taken automatically when the payment succeeds. For accounts paid out to PayPal, PayPal charges its own processing fee on your PayPal account; for accounts processed by Stripe, card processing is included in the Lynent fee. There is no monthly fee and no setup fee.
International card fee. When the buyer's card was issued outside your country, the card networks charge more, and you pay that extra: 1.5% of the amount for US and Canadian sellers. For sellers in the EEA, nothing for a card from another EEA country and 1% for a card from the UK or Switzerland. For sellers in the UK or Switzerland, 1% for a card from another European country. For any European seller, 2% for a card from outside Europe. Wallets such as Apple Pay and Google Pay count as cards; a card whose country is not known gets the highest rate. You always charge in your own currency, so there is no conversion fee; if a charge is ever in a currency other than your payout currency, 1% is added.
Every payment shows base_fee, international_fee, the total as fee, the card's issuing country as card_country, and what you keep as net. Until the buyer pays, international_fee is null and fee holds the highest fee the payment can have. Every payment is charged with that fee, however it is confirmed. Right after it succeeds, Lynent reads the card that was charged and refunds the part of the fee you do not owe to your balance; fee, international_fee and card_country then show the final values.
The table below is for a USD sale paid with a US card.
| Sale | Lynent fee | After the Lynent fee |
|---|---|---|
| $1.00 (minimum) | $0.39 | $0.61 |
| $10.00 | $1.15 | $8.85 |
| $50.00 | $4.55 | $45.45 |
| $100.00 | $8.80 | $91.20 |
| $200.00 | $17.30 | $182.70 |
On a refund the buyer gets the full refunded amount back from your PayPal balance (or Stripe balance), and the Lynent fee is not returned, because the card processor does not return its processing cost on refunds either (see Refunds). The fee on a disputed charge is not returned either.
Buyers pay by card, and the money goes straight to your PayPal: each successful sale, minus the fees, lands in your PayPal balance in your currency, and you withdraw to your bank in PayPal. Lynent never holds your money. For accounts processed by Stripe, payouts go to the bank account added during onboarding.
20Test mode
Build against test mode first. With lyn_test_ keys no real money moves, and every object has "livemode": false. Test and live data are kept apart: a test key never sees live payments, customers, links or events, and the reverse.
Use these card numbers at checkout with any future expiry date, any CVC and any ZIP code:
| Card number | Result |
|---|---|
| 4242 4242 4242 4242 | Succeeds |
| 4000 0025 0000 3155 | Requires 3D Secure authentication |
| 4000 0000 0000 9995 | Declined (insufficient funds) |
- No receipt emails are sent in test mode.
- Use Send test on a webhook endpoint to receive a signed
ping. - For your own unit tests,
Lynent.webhooks.generateTestHeader({ payload, secret })builds a validLynent-Signature.
21Security checklist
- Keep API keys and webhook secrets server-side, in environment variables or a secrets manager.
- Create payments on your server with the amount from your own database. Never trust amounts sent by the browser.
- Verify webhook signatures and dedupe on
event.id. - Fulfil only on server-confirmed
succeeded. - Send
Idempotency-Keyon every create (the SDK does this for you). - Log
request_idwith failed calls, never the API key orclient_secret. - Rotate keys and secrets if you suspect exposure.
See also: Terms, Privacy, Prohibited businesses.