Skip to main content

Sandbox and test data

Card issuing is asynchronous and event-driven. Most of the events your system needs to handle come from outside it: a merchant authorizing a payment, a transaction settling, a refund being issued, or a dispute being raised.

In production, you don't control when those things happen. The sandbox gives you a way to trigger them yourself, so you can build and test those flows without waiting for a real transaction.

Cardholder verification in sandbox​

The sandbox verification flow works the same way as production. Your system is responsible for performing verification and reporting the result. A sandbox cardholder starts with a not_started KYC status until you submit an attestation.

curl -X POST "$ALETA_BASE_URL/v1/cardholders/chd_01HX8ZQ2K4M7P9RSTVWXYZAB/kyc" \
  -H "Authorization: Bearer $ALETA_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approved",
    "verified_at": "2026-07-29T11:04:00Z",
    "provider": "Sandbox Test Provider"
  }'

Try this flow when testing your issuing integration. An approved attestation emits cardholder.kyc_approved, which lets you test the webhook and any logic that depends on a verified cardholder.

Test card behavior​

Sandbox cards use a test BIN and can't be used at real merchants.

For normal authorization testing, set up the card and account state you want to test. A frozen card, an unfunded account, or a spend limit below the transaction amount will produce the corresponding decline.

The sandbox also supports a few amount-based decline scenarios. These are useful when you need to trigger a particular authorization response without changing the card or account first:

Authorization amount (minor units)Outcome
…13 (ends in 13)Declined, do_not_honor
…51Declined, insufficient_funds — regardless of actual balance
…57Declined, transaction_not_permitted
…62Declined, restricted_card
Any other valueApproved, subject to balance and controls

For example, 1013 declines while 1014 approves.

These amount-based rules only apply when Aleta Planet makes the authorization decision. Some programs use a processor that owns the balance and makes the decision instead. In those cases, the processor's response takes precedence and these sandbox amounts have no special meaning.

The decline reasons above are decline_reason values on the authorization. They aren't HTTP errors, so you won't find them in the error catalog. If the processor makes the authorization decision, these values aren't exposed to you either. See transactions for more about processor-managed transactions.

Last updated on