Configuration
Construct the Amboss Payments client: service API keys, webhook secrets, custom base URLs, timeouts, and a custom fetch implementation.
The Payments constructor takes a single config object. Every field is optional, so you can construct a client for API calls, for webhook verification, or for both.
import { Payments } from "@ambosstech/payments";
const payments = new Payments({
serviceApiKey: process.env.AMBOSS_API_KEY,
webhookSecret: process.env.AMBOSS_WEBHOOK_SECRET,
});Options
| Option | Type | Default | Description |
|---|---|---|---|
serviceApiKey | string | none | Scoped payments key, sent as the x-api-key header. Required for environments, wallets, and transactions. Omit for webhook-only use. |
webhookSecret | string | none | Endpoint secret used by the instance webhooks.verify. Omit if you only call the API. |
baseUrl | string | https://rails.amboss.tech/graphql | Override the GraphQL endpoint. |
fetch | typeof fetch | global fetch | Custom fetch implementation for tests or non-Node runtimes. |
timeoutMs | number | 30000 | Request timeout in milliseconds. |
Authentication
The SDK authenticates with a service API key, the same scoped key you use with the raw API. It is sent as the x-api-key header:
- Sandbox keys look like
amb_test_... - Live keys look like
amb_live_...
Mint and scope keys from the dashboard. See API Keys for permissions and rotation.
Accessing payments.environments, payments.wallets, or payments.transactions without a serviceApiKey throws a ConfigError. See Errors.
Webhook-only clients
Webhook verification needs the webhookSecret, not the API key. If your service only receives webhooks, construct a client with just the secret:
const payments = new Payments({
webhookSecret: process.env.AMBOSS_WEBHOOK_SECRET,
});
const event = payments.webhooks.verify({ payload, signature, timestamp });You can also verify statelessly, with no client at all, using the static API. See Webhooks.
Custom fetch and timeouts
Inject a fetch implementation to run in edge runtimes, or to stub network calls in tests. Tune timeoutMs for slower networks:
const payments = new Payments({
serviceApiKey: process.env.AMBOSS_API_KEY,
baseUrl: "https://rails.amboss.tech/graphql",
fetch: customFetch,
timeoutMs: 60_000,
});