Your first sandbox test

Sandbox is a real integration against real registries, on the Peppol test network. It is honest about its limits, so you know what still needs proving before you go live.

Your customers are never involved and never contacted. Sandbox platform accounts are capped at 10 active test customers; archived ones no longer count.

1. 1. A console account — sign up at console.getpeppr.dev. Every account starts in sandbox.
2. 2. The platform sandbox trial — chosen at signup, or started later by an organisation admin from the console overview. Nothing below works before that.
3. 3. A master key — only once the trial is on, and starting it does not create the key for you: an organisation admin opens API Keys → Create master key in the console and picks sandbox. The secret is shown once, so copy it then. A standard key returns 403 master_key_required on the endpoints below.
4. 4. The SDK — Node.js 18+ and npm install @getpeppr/sdk (≥ 2.6.0).
5. 5. A test identity — scheme 9915 and a value you pick yourself. The Peppol code list publishes 9915 as having no entity behind it, so there is no registry to satisfy and no real company to borrow. That is the default route, and the next section explains it. Using a real registered company instead is supported, but it must still be active at its registry.

Verification runs against real business registries, in sandbox exactly as in production. That leaves you two honest options, and one that does not work.

Option A — scheme 9915 (recommended)

9915 is published in the Peppol code list with the note “No entity behind id”. Nothing is registered behind it by design, so there is no registry to query and no one else's tax number involved. It is what the ecosystem uses for test participants, DG DIGIT included. The value is yours to choose: an uppercase letter followed by uppercase letters and digits.

const customer = await peppol.legalEntities.create({
  // Same externalId used at Step 3 below.
  externalId: "customer_be_001",
  companyName: "Acme Test Ltd",
  country: "GB",
  address: { line1: "1 Test Street", city: "London", zip: "EC1A 1BB" },
  identifier: {
    scheme: "9915",
    // Uppercase letters and digits only, starting with a letter — so drop
    // the dash: account PEP-85848 becomes ACME85848TEST.
    value: "ACME85848TEST",
  },
});

// 202 straight away — verification is asynchronous.
// Once it settles: status "no_registry", and ready to send.

Verification settles on its own, usually within seconds — it runs in the background, and a five-minute sweep picks up anything that did not start. The status you will then read is no_registry, not verified: it is its own word on purpose, because nothing was proven about an entity, and calling it verified would make the sandbox promise something production will refuse. Both statuses send in sandbox.

Option B — a real registered company

Use this when what you want to exercise is registry verification itself — the name comparison, the failure modes, the timing. Pick a company that is still active: when a registry reports one as struck off, in liquidation, or not yet active, we refuse it, and re-sending the same details will not change that until the registry changes its own answer. Copy the company name from the registry entry rather than typing it from memory; it is compared against what the registry holds.

On scheme 9915, this is the call shown in Choosing a test identity and there is nothing else to prepare. The example below takes the other route, a real Belgian company — copy the company name from the registry entry rather than typing it from memory, since it is compared against what the registry holds.

import { Peppol } from "@getpeppr/sdk";

const peppol = new Peppol({ apiKey: "sk_sandbox_your_master_key" });

const customer = await peppol.legalEntities.create({
  // Your stable reference. Echoed as data.subTenantId on every
  // Legal Entity lifecycle webhook, so you can map it straight back.
  externalId: "customer_be_001",
  companyName: "Exact Registered Legal Name",
  country: "BE",
  address: { line1: "Rue de la Loi 16", city: "Brussels", zip: "1000" },
  identifier: { scheme: "0208", value: "0685660237" },
});

console.log(customer.id, customer.status); // "7c9a1b34-…", "pending"

You get 202 immediately; verification runs in the background.

Re-sending the same externalId: an identical name and normalized identifier returns the existing record (200) without another provider create. Reusing that identifier under a different externalId returns 409 identifier_already_in_use; use the owned reference in existingLegalEntity instead. Changing the scheme or number on the original reference is refused with 422 identifier_immutable — a different identifier is a different company, so archive the entity and create it again. The externalId is free to reuse once archived.

The example is Belgian, the flow is not. For your own market, swap externalId, companyName, the legal address, country and identifier — then reuse that same externalId in sender.externalSubTenantId at Step 3. The name and address are registered as you send them, so they must match the register. The schemes we verify today, with the exact format each one accepts:

Two country specifics worth knowing before you start. Germany (9930): VIES confirms the VAT number is valid but masks the company name, so we cannot compare your declared name against the register — verification rests on the VAT number alone. United Kingdom (GB:VAT): the VAT number is the only UK identifier the Peppol network routes — a Companies House number is not a Peppol identifier and cannot receive anything. We cannot currently verify UK VAT numbers against HMRC automatically. Contact support to arrange identity verification before production sending.

A scheme we don't verify yet doesn't fail loudly — the customer simply sits at pending. If that happens, email us rather than waiting.

Subscribe a webhook endpoint, or poll. Webhooks are the cheaper path.

const check = await peppol.legalEntities.get(customer.id);

// Two terminal statuses are ready to send in sandbox:
//   "verified"    — a registry confirmed the company (option B)
//   "no_registry" — scheme 9915: there was no registry to ask (option A)
const ready = check.status === "verified" || check.status === "no_registry";

If you poll, poll no more often than once every 10 seconds and honour Retry-After on 429: sandbox allows 10 requests per minute per key and 50 per minute per account, and this GET spends that budget.

The webhook arrives as legal_entity.registered, with data.subTenantId set to your externalId — map it straight to your customer record, no lookup needed.

The same POST /v1/invoices as single-tenant sending — you just add sender.

await peppol.invoices.send({
  number: "INV-2026-001",
  // Required by network rule R003. Storecove has always injected one
  // when missing, but that is not contractual — set it yourself.
  buyerReference: "INV-2026-001",
  sender: { externalSubTenantId: "customer_be_001" },
  to: {
    // SPF Economie — the standard Peppol test receiver. Sandbox
    // delivers ONLY to test recipients: send to a real company and
    // the submission is accepted, then fails asynchronously.
    name: "SPF Economie",
    peppolId: "9925:BE0314595348",
    // Buyer VAT is read from this field — never derived from peppolId.
    vatNumber: "BE0314595348",
    street: "Rue du Progrès 50",
    city: "Brussels",
    postalCode: "1000",
    country: "BE",
  },
  lines: [
    // The registryless 9915 test identity has no VAT identifier, so this
    // diagnostic invoice is explicitly outside scope (O), not zero-rated (Z).
    // For a real transaction, use the category the invoice actually requires.
    { description: "Sandbox platform test", quantity: 1, unitPrice: 90, vatRate: 0, vatCategory: "O" },
  ],
});

The supplier identity — name, country, Peppol ID — is taken from the selected send-ready Legal Entity. Any from you pass is stripped, so you cannot mis-state the sender even by accident.

Stuck for more than ten minutes? Email hello@getpeppr.dev with your externalId and what you expected. You'll get the founder, not a ticket queue.

Same API, same SDK, same send call. What changes:

1. 1. A production master key, which requires an active platform contract — a sandbox key never reaches the live network.
2. 2. Attestation. Each customer confirms, on a getpeppr-signed page, that they authorise you to invoice on their behalf. You trigger it with POST /v1/legal-entities/:id/attestation; we email the co-branded link and keep the audit trail. It doesn't exist in sandbox.
3. 3. More statuses, around that authorisation flow. Don't hard-code a fixed sequence between them — read the current status and react to it. See Sub-tenant Lifecycle.
4. 4. Real recipients. Sandbox only delivers to the test receiver above; production reaches your customers' actual buyers.

Commercially, production platform access is set up with us directly — plan, country scope, customer cap. Email us and we'll size it with you.