Sandbox guide

What is the sandbox?

The sandbox is a completely isolated environment that mirrors the production API. Invoices created in sandbox mode are never submitted to ANAF. Instead, Billyou returns simulated SPV responses so you can test every scenario: confirmations, rejections, errors.

Each account gets 10,000 free test invoices per month in sandbox mode. Sandbox usage never counts toward your paid plan limits.

Initialize in sandbox mode

Use a key with the bly_test_ prefix and set env: 'sandbox'. The SDK will automatically route all requests to the sandbox environment.

import Billyou from 'billyou-sdk';

// Use bly_test_ prefix for sandbox mode
const billyou = Billyou.create({
  apiKey: process.env.BILLYOU_TEST_KEY,
  env: 'sandbox',
});

// All invoices in sandbox mode:
// - Are NOT sent to real ANAF
// - Return simulated SPV responses
// - Do not count toward your plan limits

Simulate SPV responses

Use the sandbox.simulateStatus field to force a specific outcome. Useful for testing error handling and edge cases in your integration.

// Simulate different SPV outcomes
const invoice = await billyou.invoices.create({
  // ... your invoice fields ...
  sandbox: {
    // Force a specific outcome:
    simulateStatus: 'confirmed',
    // or 'rejected', 'in_prelucrare'
  },
});

Common sandbox patterns