Payments API

Lightning payments, one mutation away.

Send, receive, and settle BTC, USDT, and USDC over Lightning through one GraphQL endpoint or a typed TypeScript SDK. No node to run, no custody, free sandbox.

Start in the sandbox Prompt for Agents

receive.ts

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

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

const invoice = await payments.transactions.createReceive({
  wallet_id: walletId,
  amount: "100000",            // base units
  description: "Order #42",
  idempotency_key: "order-42",
});

console.log(invoice.payment_request); // lnbc…

Sandbox keys are free. Swap to an amb_live_ key to go live.SDK quickstart

Endpoint

app.amboss.tech/graphql

Auth

x-api-key: amb_test_…

The whole flow

One call in. One webhook out.

01
Create an invoice
payment.transaction.create_receive
Returns a BOLT11 payment_request. Show it as a QR or link. Pass idempotency_key so retries return the same invoice.
02
The payer pays
any Lightning wallet or exchange
Cash App, Coinbase, Kraken, Strike, and the rest. Settlement is sub-second and final. In sandbox, force the outcome with amb_sandbox_behavior.
03
Handle the webhook
payment.completed · payment.failed · payment.expired
Verify the HMAC signature, dedupe on the envelope id, then fulfil. Delivery is at-least-once with retries.

webhook deliveryVerify the signature

POST /webhooks/amboss
x-webhook-event: payment.completed
x-webhook-timestamp: 1758556800
x-webhook-signature: 3b6e7d…   # HMAC-SHA256 of "<timestamp>.<body>"

{
  "id": "payment.completed:tx_01HX9YQK7P8MVZ3FN4G2RWS6CD",
  "event_type": "payment.completed",
  "environment": "sandbox",
  "wallet_id": "5e4b1e2a-9f3c-4a5b-8c7d-1234567890ab",
  "data": {
    "id": "tx_01HX9YQK7P8MVZ3FN4G2RWS6CD",
    "direction": "receive",
    "status": "completed",
    "payment_details": { "payment_type": "bolt11", "payment_hash": "3b6e7d…" },
    "amount":        { "amount": "100000", "asset_symbol": "USDT", "precision": 6 },
    "settle_amount": { "amount": "99995",  "asset_symbol": "USDT", "precision": 6 },
    "settled_at": "2026-06-02T12:31:42.000Z",
    "metadata": { "order_id": "42" }
  }
}

Metadata you send on the invoice comes back on the webhook, so you can route by order_id without a lookup.

Reference