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.

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,
  feeLimitSats: "50",
  destination: { bolt11: "lnbc1..." },
  metadata: { amb_sandbox_behavior: "complete" },
});

Live wallets also need a team password to decrypt the node macaroon locally. See Transactions → Sending for both paths.

Get Started

Install

Construct a client

Discover your wallets

Receive a test payment

Verify the webhook

Try sending

Next steps

Configuration

Transactions

Webhooks

Errors

On this page