Build your first test payment

This guide takes you from an order on your server to a mounted test checkout. It uses TypeScript and the npm package, but the same server API works from any backend language. You need a Lynq Dashboard account and its test keys; see API keys. Test mode needs no payment-method setup: Lynq simulates card payments.

Store your test keys

Add the secret key to server-only configuration. The publishable key may be exposed to the browser.

.env

LYNQ_SECRET_KEY=sk_test_...

Do not commit the environment file. Expose the publishable key using the browser-safe configuration mechanism provided by your framework.

Create a Payment Intent on your server

Create one Payment Intent when the customer begins paying for an order. Build the amount and order ID from server-side order data instead of trusting values sent by the browser.

server/create-lynq-payment.ts

const response = await fetch("https://api.lynq.am/api/payment-intents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYNQ_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order:${order.id}`,
  },
  body: JSON.stringify({
    amount: order.totalMinor,
    currency: order.currency,
    orderId: order.id,
    customer: {
      id: order.customer.id,
      email: order.customer.email,
      name: order.customer.name,
    },
  }),
});

if (!response.ok) {
  throw new Error(`Lynq returned HTTP ${response.status}`);
}

const paymentIntent = await response.json() as {
  id: string;
  clientSecret: string;
};

return {
  id: paymentIntent.id,
  clientSecret: paymentIntent.clientSecret,
};

Amounts use minor currency units. For AMD 25,000.00, send 2500000. Reuse the same idempotency key only when retrying this exact create request.

Install Lynq.js

npm install @lynqpay/js

The package is ESM-only and includes TypeScript declarations. If your application does not use a bundler, see the script-tag installation.

Request the checkout session

From the browser, call your own backend route. Keep the secret key behind that route; return only the Payment Intent ID and client secret.

client/start-checkout.ts

const response = await fetch(`/api/orders/${orderId}/lynq-payment`, {
  method: "POST",
});

if (!response.ok) throw new Error("Could not start checkout");

const paymentIntent = await response.json() as {
  id: string;
  clientSecret: string;
};

Mount Checkout

Add an empty container to the page, register event handlers, and then mount Checkout.

<div id="lynq-checkout"></div>

client/mount-checkout.ts

import { Checkout, type PaymentResult } from "@lynqpay/js";

const checkout = new Checkout({
  publicKey: "pk_test_...",
  clientSecret: paymentIntent.clientSecret,
});

checkout
  .onReady(() => hideCheckoutLoadingState())
  .onPaymentResult((result: PaymentResult) => {
    if (result.status === "succeeded") {
      showOrderConfirmation(result.paymentIntentId);
      return;
    }

    if (result.status === "processing") {
      showPaymentPending(result.paymentIntentId);
      return;
    }

    showPaymentError(result.error.message);
  })
  .onCheckoutError((error) => showCheckoutError(error.message))
  .mount("#lynq-checkout");

Register handlers before mount(). Destroy the instance when the page is removed and create a new instance for a new Payment Intent.

Complete a test payment

Pay with a test card. Confirm the browser shows a useful result and the payment appears under Dashboard → Payments.

Add authoritative fulfilment

Configure a test webhook endpoint, verify its signature, and update the order only after payment_intent.succeeded. See Verify webhooks.

The integration is complete when Checkout accepts a test payment and your verified webhook updates the matching order exactly once.

Continue with the test plan before switching to live mode.

Start here

Payment methods

Build your integration

Test and go live

Reference

Build your first test payment