Test your integration

You can test an integration thoroughly before sending any real data.

Validate without storing

POST /v1/events/validate runs the same checks as ingest and stores nothing. It does not add to the hash chain, does not create agents or payees, and does not start any background job.

It takes the same body as POST /v1/events and returns the same per-item errors, with one difference: a good event is reported as valid instead of accepted.

curl https://api.sandbox.halvorai.com/v1/events/validate \
  -H "Authorization: Bearer $HALVOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @batch.json

{
  "results": [
    { "id": "evt_01JA8Q4K3T9V2C7M5N6P8R0S1W", "status": "valid" },
    { "id": "evt_01JA8Q4K3T9V2C7M5N6P8R0S1X", "status": "duplicate" },
    {
      "id": "evt_01JA8Q4K3T9V2C7M5N6P8R0S1Y",
      "status": "rejected",
      "error": {
        "code": "invalid_event",
        "message": "The event does not match APE v0.1",
        "details": [{ "path": "payment.amount.value", "message": "Invalid string: must match pattern" }]
      }
    }
  ]
}

duplicate means an event with that id is already stored, which is useful to check that your ids are unique.

Who can use it: an API key with events:write, or a signed-in developer, analyst, admin or owner. The dashboard’s Send test event button calls it.

Check the schema locally

The APE JSON Schema is public. Validate events in your own tests with any JSON Schema 2020-12 validator. See the APE schema reference. The schema cannot express the card-number check, so also rely on validate for that.

Test without a network

Pass a sink function to the SDK and it hands you the signed envelopes instead of sending them. Use it in unit tests and in self-hosted setups. See the TypeScript SDK.

const sent: unknown[] = [];
const halvor = new HalvorClient({
  sourceKey: process.env.HALVOR_SOURCE_KEY,
  environment: 'test',
  sink: async (envelopes) => void sent.push(...envelopes),
});

Test against the sandbox

Sandbox is a full copy of the system with test keys, and test data is deleted after 30 days. Run your integration there, then open Payments to see what a reviewer would see. The quickest end-to-end check is npx @halvorai/ingest init. It registers a source and sends a test event.

What to check before production

• Events are accepted, not rejected, and stats() on the client shows no dropped events.
• Every payment has an agent, an owner and an instruction. Check attribution coverage in the dashboard.
• Evidence verifies as valid where the rail supplies a signature.
• Your service keeps working when the API is unreachable. The SDK queues in memory and on disk, and emit never throws.