Get Started

Install the Amboss Payments SDK, construct a client, discover your wallets, receive a test payment, and verify the webhook in TypeScript.

This is the TypeScript-first path through the Payments quickstart. You'll install the SDK, construct a client, list your wallets, receive a test payment in sandbox, and verify the resulting webhook.

Account creation, sandbox environments, and API keys are set up once from the dashboard. Follow Payments → Get Started for those steps, then come back here with an API key in hand.

Using a coding agent? Paste the Prompt for Agents into it and let it wire the integration up for you.

Install

pnpm add @ambosstech/payments

@ambosstech/core is pulled in transitively. Requires Node.js 18.18 or newer.

Construct a client

Use the service API key you minted for your sandbox environment. It is sent as the x-api-key header on every request.

import { Payments } from "@ambosstech/payments";

const payments = new Payments({
  serviceApiKey: process.env.AMBOSS_API_KEY,
});

See Configuration for every option, including webhook secrets and custom base URLs.

Discover your wallets

List environments and the wallets inside them. This is also the quickest way to confirm your API key works.

const environments = await payments.environments.list();

for (const environment of environments) {
  console.log(`${environment.name} (${environment.type})`);
  const wallets = await payments.wallets.list({ environmentId: environment.id });
  for (const wallet of wallets) {
    console.log(`  ${wallet.name} [${wallet.asset.symbol}] ${wallet.id}`);
  }
}

Receive a test payment

Create an invoice on a sandbox wallet and force it to settle with the amb_sandbox_behavior metadata flag.

const transaction = await payments.transactions.createReceive({
  wallet_id: walletId,
  amount: "1000", // base units (sats for BTC)
  description: "Order #1234",
  metadata: { amb_sandbox_behavior: "complete" },
});

console.log(transaction.payment_request); // BOLT11 invoice

In sandbox the invoice auto-settles after a short delay and fires payment.completed. See Transactions for the full input reference.

Verify the webhook

Register a webhook endpoint (see Payments → Webhooks), then verify each delivery in your handler. The SDK checks the HMAC signature and returns a typed event.

const payments = new Payments({
  serviceApiKey: process.env.AMBOSS_API_KEY,
  webhookSecret: process.env.AMBOSS_WEBHOOK_SECRET,
});

const event = payments.webhooks.verify({
  payload: rawBody, // the RAW request body, not parsed JSON
  signature: headers["x-webhook-signature"],
  timestamp: headers["x-webhook-timestamp"],
});

console.log(event.event_type, event.data.id);

See Webhooks for framework-specific handlers (Express, NestJS, Fetch) and the full list of error codes.

Try sending

Once receive works, pay an outbound invoice or Lightning Address with send. In sandbox, drive the outcome with the same metadata flag.

const { transaction, payment } = await payments.transactions.send({
  walletId,
  password: process.env.TEAM_PASSWORD ?? "Password123", // placeholder works in sandbox
  destination: { bolt11: "lnbc1..." },
  metadata: { amb_sandbox_behavior: "complete" },
});

Every send requires a non-empty password, so test and production code use the same call shape. In sandbox, any non-empty value such as Password123 works because it is not used. Live wallets require the real team password and use it to decrypt the node macaroon locally. They also need an API key with WALLETS: READ + WALLET_CREDENTIALS: READ scoped to the wallet_id, plus outbound HTTPS from your server to the node. See Transactions → Sending for both paths and the full requirements.

Get Started

Install

Construct a client

Discover your wallets

Receive a test payment

Verify the webhook

Try sending

Next steps

Prompt for Agents

Configuration

Transactions

Webhooks

Errors

On this page