Introduction

The Astrada sandbox is a separate environment for integration testing: its own hosts, its own credentials, and synthetic data everywhere. Nothing you do here reaches a card network, a bank, or production data. Cards enroll from reserved test-card pools, bank links complete against the providers' test banks, and transactions come from simulation endpoints.

You get sandbox credentials (an accountId and an OAuth2 client) during onboarding. They are separate from your production credentials and only work against the sandbox hosts.

📘

Sandbox environment vs sandbox mode

This section covers the standalone sandbox environment. There is also sandbox mode, a per-subaccount flag on the production API for deterministic 3DS testing with known test cards, documented in Test Cards & Sandbox Testing. If you are choosing where to start integration testing, start here.

Get a token

Authentication works exactly like production: an OAuth2 client-credentials grant against your account's realm, on the sandbox host.

curl -X POST "https://api.sandbox.astrada.co/auth/realms/{accountId}/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response (200 OK):

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300,
  "token_type": "Bearer"
}

The token carries your client's scopes. The read and write scopes match production; the simulation endpoints additionally require simulation:write, which sandbox clients have by default.

What works

Everything in the API reference works here, served from the sandbox base URL: subaccounts, cards, card subscriptions, single card enrollment (3DS verification, SDK or API), enrollment methods, BIN lookup, transactions, transaction messages, webhooks, network bulk feeds, and bank linking. Card enrollment accepts published test cards only.

Cleaning up test data

Every resource you create in the sandbox can be torn down over the API, so a test run leaves nothing behind. These deletes are sandbox-only (they do not exist on production), return 204 No Content, and are safe to retry — completed steps are no-ops on replay.

• Delete a whole subaccount: DELETE /subaccounts/{subaccountId} removes the subaccount and everything under it — its bank links (with their accounts, transactions, and matches), every card subscription (with its card, cardholder, stored token, and transactions), network bulk feed, and webhook. One call tears the whole subaccount down, so it is the fastest reset for a test run.
• Delete one card subscription: DELETE /card-subscriptions/{subscriptionId} removes the subscription and the data it owns; when it is the last subscription on its card, the card, cardholder, stored token, and transactions go with it.
• Delete one network bulk feed: DELETE /network-bulk-feeds/{networkBulkFeedId} removes the feed and the cards and transactions it created.
• Remove a whole bank connection: DELETE /bank-links/{bankLinkId} revokes the item with the provider and deletes its bank accounts and their transactions.
• Remove a single bank account: DELETE /bank-accounts/{bankAccountId} drops one bank account and its transactions while leaving the rest of the connection intact.

📘

Bank cleanup uses your token

The subaccount delete clears bank data by calling the banking service with your bearer token. If your sandbox client isn't authorized for banking, that step is skipped and the rest of the teardown still runs — remove any bank links explicitly in that case.

curl -X DELETE "https://api.sandbox.astrada.co/subaccounts/{subaccountId}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

In this section

• Testing Single Card Enrollment walks the card rail: enroll a test card with the SDK, watch it verify and activate, then simulate a transaction.
• Testing Bank Linking walks the bank rail end to end: create a link with the API or the SDK, complete it against a test bank, read the created resources, then watch bank postings settle a pending card authorization early and arrive as bank-only transactions on the unified feed.
• Testing Bulk Enrollment walks the bulk rail: create a network bulk feed, drive a synthetic ingestion, and watch cards and transactions appear.
• Sandbox API Reference is the endpoint reference for the simulation endpoints, with Test Card Pools underneath it.

Next steps

• Testing Single Card Enrollment: start with single-card enrollment.
• Testing Bank Linking: start with the bank rail.
• Testing Bulk Enrollment: start with the bulk rail.
• Webhook Event Types: the canonical event catalog.