Skip to main content
Sandbox is a complete, separate copy of Alguna with its own dashboard, its own API keys and its own data. Nothing you do there touches production, and no money moves: payments run against your processor’s test mode. Use it to build an integration, rehearse a migration, or reproduce a customer problem without risk. Run the whole lifecycle there — create a customer, price and activate a subscription, meter usage, invoice, pay, refund, cancel — before you point anything at production.

​
The two environments

The environments share nothing. A key issued in one is rejected by the other, customers and subscriptions do not exist across both, and there is no promote or copy step — configuration you want in production is set up in production. Treat “it worked in sandbox” as a statement about your integration, not about your production data.

​
Getting set up

  1. Sign in at app.sandbox.alguna.io.
  2. Create a sandbox key under Settings → Connections → Developers → API keys.
  3. Point your integration at the sandbox base URL.
The SDK’s baseUrl carries the same path prefix as its production default, so the sandbox host is https://api.sandbox.alguna.io/beta. See TypeScript SDK.
Keep the two keys in separate environment variables. Reading ALGUNA_API_KEY in a script you meant to run against sandbox is the failure mode worth designing against.

​
Test payments

Alguna is not the payment processor — it decides what is owed, and your processor moves the money. Test cards therefore come from your processor, not from Alguna. Connect the processor’s test mode to your sandbox environment under Settings → Connections → Integrations, then use that processor’s published test numbers at checkout or on a hosted invoice. With Stripe, that means connecting a Stripe test-mode account and using Stripe’s test cards — including the numbers that force a decline, a 3-D Secure challenge, or a dispute, which are the cases worth exercising deliberately. ACH and other bank rails have their own test account numbers in the same reference. What runs end to end in sandbox: the payment succeeds or fails as the test instrument dictates, the invoice moves to paid, a receipt is emailed, and payment.created / payment.updated webhooks fire exactly as they would in production.

​
Testing webhooks

Webhook endpoints are configured per environment under Settings → Connections → Developers → Webhooks, so a sandbox endpoint never receives production events. Your endpoint must be publicly reachable — localhost will not work. During development, expose your local server with a tunnel (ngrok or similar) or point the sandbox endpoint at a request-capture service to inspect payloads. See the webhooks quick start.

​
A pass worth running before go-live

1

Catalog

Create the products, prices and plans you actually sell, including the awkward one — the tiered metric, the ramp, the annual with a mid-term add-on.
2

Acquisition

Run both motions that apply to you: a checkout session end to end, and a quote through signature to an active subscription.
3

Usage

Send events with the same shape your production code will send, and confirm they attribute to the right customer and metric.
4

Billing

Let a period close and an invoice generate. Check the line items, the proration, the tax and the total against what you expect — not just that an invoice exists.
5

Money out and back

Pay the invoice with a test instrument, then refund it and issue a credit note. Refunds and credit notes are where integrations most often turn out to be incomplete.
6

Failure paths

Force a declined payment and watch dunning and the retry schedule do their work. Confirm your webhook consumer handles a failed payment as well as a successful one.

​
Next steps

Developer quick start

Keys, base URLs and the first calls, end to end.

API overview

Authentication, versioning, pagination and errors.

Webhooks quick start

Receive and verify events from your sandbox.

Migrations

Rehearse a move from another billing system in sandbox first.