> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing and Sandbox

> Use the sandbox environment to run the full quote-to-revenue lifecycle with test payments before switching your integration to production.

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

| | Production | Sandbox |
| - | - | - |
| Dashboard | [app.alguna.io](https://app.alguna.io) | [app.sandbox.alguna.io](https://app.sandbox.alguna.io) |
| API base URL | `https://api.alguna.io` | `https://api.sandbox.alguna.io` |
| Payments | Real money | Your processor's test mode |
| Data | Live customers and revenue | Independent; created by you |

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](https://app.sandbox.alguna.io).
2. Create a sandbox key under **Settings → Connections → Developers → API keys**.
3. Point your integration at the sandbox base URL.

```bash cURL theme={null}
curl "https://api.sandbox.alguna.io/customers?limit=20&offset=0&sort=name:asc" \
  -H "Authorization: Bearer $ALGUNA_SANDBOX_API_KEY" \
  -H "Alguna-Version: 2026-04-01"
```

```python Python theme={null}
import os

import requests

response = requests.get(
    "https://api.sandbox.alguna.io/customers",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_SANDBOX_API_KEY']}",
        "Alguna-Version": "2026-04-01",
    },
    params={"limit": 20, "offset": 0, "sort": "name:asc"},
    timeout=10,
)
response.raise_for_status()
```

```typescript TypeScript SDK theme={null}
const alguna = new Alguna({
  apiKey: process.env.ALGUNA_SANDBOX_API_KEY,
  baseUrl: "https://api.sandbox.alguna.io",
});
```

> [!NOTE]
>
> Every SDK and the CLI take a base URL: set it to `https://api.sandbox.alguna.io`. See [SDKs and CLI](https://alguna.com/docs/api-reference/v2/sdks/overview.md#sandbox).

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](https://alguna.com/docs/hosted/checkout.md) or on a hosted invoice.

With [Stripe](https://alguna.com/docs/integrations/payments/stripe.md), that means connecting a Stripe test-mode account and using [Stripe's test cards](https://docs.stripe.com/testing) — including the numbers that force a decline, a 3-D Secure challenge, or a dispute, which are the cases worth exercising deliberately. [ACH](https://alguna.com/docs/integrations/payments/ach.md) 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](https://alguna.com/docs/hosted/emails.md) is emailed, and `payment.created` / `payment.updated` [webhooks](https://alguna.com/docs/api-reference/v2/webhooks.md) 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](https://alguna.com/docs/guides/webhooks-quickstart.md).

***

## A pass worth running before go-live

**1. Catalog**

Create the products, [prices](https://alguna.com/docs/pricing/pricing-models.md) and [plans](https://alguna.com/docs/pricing/plans.md) 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](https://alguna.com/docs/hosted/checkout.md) end to end, and a [quote](https://alguna.com/docs/quotes/create-quotes.md) through signature to an active subscription.

**3. Usage**

Send [events](https://alguna.com/docs/billable-metrics/send-usage.md) 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](https://alguna.com/docs/invoices/recurring-invoices.md) generate. Check the line items, the [proration](https://alguna.com/docs/subscriptions/proration.md), the [tax](https://alguna.com/docs/tax/overview.md) 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](https://alguna.com/docs/invoices/refunds.md) it and issue a [credit note](https://alguna.com/docs/invoices/credit-notes.md). Refunds and credit notes are where integrations most often turn out to be incomplete.

**6. Failure paths**

Force a declined payment and watch [dunning](https://alguna.com/docs/collections/dunning.md) 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](https://alguna.com/docs/quickstarts/developers.md)**
>
> Keys, base URLs and the first calls, end to end.

> **[API overview](https://alguna.com/docs/api-reference/v2/overview.md)**
>
> Authentication, versioning, pagination and errors.

> **[Webhooks quick start](https://alguna.com/docs/guides/webhooks-quickstart.md)**
>
> Receive and verify events from your sandbox.

> **[Migrations](https://alguna.com/docs/migrations/migrations.md)**
>
> Rehearse a move from another billing system in sandbox first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.