API reference, version 1

Lynentdeveloper docs

Create a payment with POST /v1/payments or share a payment link, send the buyer to Lynent's checkout, and fulfil the order when a signed payment.succeeded webhook reaches your server.

Base URL
https://lynent.com
Secret keys
lyn_test_ / lyn_live_
Amounts
Integer cents (USD)
Node SDK
@lynent/node

01Overview

  1. 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.
  2. Create an API key in Dashboard, API keys. The full key is shown once.
  3. From your server, create a payment with POST /v1/payments (or share a payment link). Send the buyer to the returned checkout_url, or embed the checkout with lynent.js.
  4. Fulfil the order when you receive the payment.succeeded webhook.
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
ResourceEndpoints
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.

Header
Authorization: Bearer lyn_test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  • lyn_test_ keys work only while the platform is in test mode, and lyn_live_ keys only in live mode. A key for the wrong mode returns 401 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.

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

Node SDK
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);
ResourceMethods
paymentscreate, retrieve, list, cancel, refund
refundscreate, retrieve, list
customerscreate, retrieve, update, del, list, listPayments
paymentLinkscreate, retrieve, update, list
balanceretrieve
payoutsretrieve, list
eventsretrieve, list
webhookEndpointscreate, retrieve, update, del, list, rotateSecret
Lynent.webhooksverify(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.
FieldTypeNotes
amountintegerSmallest 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).
currencystringThree-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_itemsarrayUp to 100 { name, quantity, unit_amount }. See Line items.
descriptionstringShown to the buyer at checkout. Up to 1000 characters.
metadataobjectUp to 20 string pairs (keys up to 40 characters, values up to 500). Keys starting with lynent_ are reserved.
customerstringAn existing customer id (cus_...).
customer_emailstringWithout customer, finds or creates the customer with this email. With it, the emails must match.
receipt_emailstringWhere the card receipt is emailed in live mode. Defaults to customer_email, else the email of customer.
statement_descriptor_suffixstringUp to 22 Latin characters, at least one letter, appended to the descriptor on the buyer's card statement.
success_urlstringWhere the buyer goes after paying. Must be https (http only for localhost). {PAYMENT_ID} is replaced with the payment id.
cancel_urlstringShown as a "Cancel and return" link at checkout.

Unknown fields are rejected with 400 validation_error.

curl
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"
  }'
Node SDK
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
Response 201
{
  "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.

client_secret

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.

FieldTypeNotes
namestring, required1 to 250 characters.
quantityinteger, required1 to 10,000.
unit_amountinteger, requiredCents, 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
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 }
    ]
  }'
Node SDK
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:

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

HTML
<div id="lynent-checkout"></div>
<script src="https://lynent.com/js/lynent.js"></script>
<script src="/your-checkout.js"></script>
your-checkout.js
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.mount renders an iframe of /pay/:id?embed=1&origin=<your page origin>. The iframe has allow="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:success and lynent:error messages only to your page's origin. Only lynent:resize (a height in pixels) is sent to any origin. Messages never contain secrets or customer data.
  • lynent.js accepts a message only when its origin is the Lynent origin taken from the script's own src, 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.com and frame-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_secret is null on reads.
  • GET/v1/payments

    Filters: status, customer, payment_link, plus pagination.
  • POST/v1/payments/:id/cancel

    Optional cancellation_reason: duplicate, fraudulent, requested_by_customer, abandoned.
curl
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" }'
Node SDK
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

    Omit amount for a full refund of what is left. Optional reason.
  • GET/v1/refunds

    Filter with payment=pay_... and created[...].
  • GET/v1/refunds/:id

    One refund.
curl
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"
Node SDK
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...' });
Response 201
{
  "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.

The Lynent fee is not returned on refunds

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. null clears a field. metadata is merged; a key set to "" is removed.
  • DELETE/v1/customers/:id

    Deletes the customer. Past payments keep their customer id.
  • GET/v1/customers/:id/payments

    The customer's payments; filter with status.
curl
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"
Node SDK
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 }
Customer object
{
  "id": "cus_9Pd2...",
  "object": "customer",
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "phone": null,
  "metadata": { "crm_id": "42" },
  "livemode": false,
  "created": 1763251200,
  "updated": 1763251200
}

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
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"
Node SDK
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));
}
Balance and payout objects
{
  "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. ping test events are not listed.
  • GET/v1/events/:id

    The event exactly as it was delivered, plus "object": "event".
curl
curl "https://lynent.com/v1/events?type=payment.succeeded&created[gte]=1763251200" \
  -H "Authorization: Bearer $LYNENT_API_KEY"
Node SDK
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, optional events (default ["*"]). Returns 201 with secret.
  • GET/v1/webhook_endpoints

    All endpoints, newest first.
  • GET/v1/webhook_endpoints/:id

    One endpoint.
  • POST/v1/webhook_endpoints/:id

    Update url, events or enabled.
  • 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
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"] }'
Node SDK
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);
The secret is shown once

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

EventWhendata.object
payment.succeededThe payment completed. Fulfil the order.payment
payment.processingAn asynchronous payment method is still processing.payment
payment.failedThe attempt failed. The buyer may retry.payment
payment.canceledThe payment was canceled.payment
payment.refundedA full or partial refund was made (see amount_refunded).payment
dispute.createdThe buyer opened a chargeback. Respond in the dashboard.dispute
payout.paid / payout.failedA payout to your bank account landed or failed.payout
account.updatedYour account status or requirements changed.account
pingSent 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.

Event body
{
  "id": "evt_9Hq2...",
  "type": "payment.succeeded",
  "created": 1763251260,
  "livemode": false,
  "data": { "object": { "id": "pay_3kJ8...", "object": "payment", "status": "succeeded", ... } }
}

Every delivery carries these headers:

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.

Node SDK (Express)
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:

Node.js, no SDK
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.status as the current state, and re-fetch with GET /v1/payments/:id if in doubt. Missed some? List them with GET /v1/events.

16Pagination

Every list endpoint returns the newest items first, in one shape:

List body
{
  "object": "list",
  "data": [ { "id": "cus_C", ... }, { "id": "cus_B", ... } ],
  "has_more": true,
  "next_cursor": "cus_B"
}
ParameterNotes
limit1 to 100. Default 10 (16 for webhook endpoints).
starting_afterAn id from the previous page, usually next_cursor. Returns the older items after it.
ending_beforeAn 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
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"
Node SDK
// 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.

SituationResult
Same key, same method, path and bodyThe stored response, with Idempotent-Replayed: true.
Same key, different request409 idempotency_key_reused.
Same key while the first request is still running409 idempotency_key_in_use. Retry shortly.
The first request failed with an errorNothing is stored, so a retry runs again.
curl
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 }'
Node SDK
// 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 body
{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_too_small",
    "message": "Amount must be at least 100 cents.",
    "request_id": "req_8fJ2kQ1xZr0aBcDe"
  }
}
StatustypeExample codesSDK class
400invalid_request_errorvalidation_error, amount_too_small, amount_mismatch, payment_not_refundable, refund_amount_too_large, invalid_cursor, invalid_jsonLynentInvalidRequestError
401authentication_errormissing_api_key, invalid_api_key, api_key_revoked, api_key_mode_mismatchLynentAuthenticationError
402card_errorThe card was declined. The message is safe to show the buyer.LynentCardError
403permission_erroraccount_not_ready, account_disabledLynentPermissionError
404not_found_errorpayment_not_found, customer_not_found, payment_link_not_found, ... Also for an id that belongs to another account.LynentNotFoundError
409conflict_erroridempotency_key_reused, idempotency_key_in_useLynentConflictError
429rate_limit_errorrate_limited. Back off and retry.LynentRateLimitError
5xxapi_errorRetry with the same Idempotency-Key.LynentAPIError
Node SDK
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.

SaleLynent feeAfter 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 numberResult
4242 4242 4242 4242Succeeds
4000 0025 0000 3155Requires 3D Secure authentication
4000 0000 0000 9995Declined (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 valid Lynent-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-Key on every create (the SDK does this for you).
  • Log request_id with failed calls, never the API key or client_secret.
  • Rotate keys and secrets if you suspect exposure.

See also: Terms, Privacy, Prohibited businesses.