Conformance testing

Set up simulated issuer outcomes in sandbox to check that your integration handles every saga path correctly before you go live.

Who can arm outcomes

POST /api/v1/conformance/run needs a tenant JWT session with the runOwnConformancePack capability. In practice that means a tenant admin of a participant (role: admin with a participant attached). Nuvanté platform operators use a different route.

Machine API keys (nvt_sandbox_…) never have runOwnConformancePack, so you'll need to sign in to the portal or use a JWT session.

The route also checks that the transaction is yours, either because you initiated it or because you're its listed issuer, so you can only arm your own transactions. Nuvanté operations has a separate endpoint (PUT /api/v1/admin/sandbox/transactions/:id/simulated-issuer-outcome) with a wider set of outcomes. That one is for platform operators only.

Scenarios

Conformance scenarios

Value	Description
`rejected`	Issuer rejects the instruction.
`failed`	Instruction fails at the issuer.
`silence`	Issuer does not respond (silence until SLA timeout).

POST /api/v1/conformance/run accepts three scenarios:

rejected: the issuer rejects the instruction, and the transaction unwinds automatically.
failed: the issuer reports a failure, and the transaction parks.
silence: the issuer never answers, so approvalSlaSeconds runs out and the transaction parks.

You don't need to arm the happy path. The simulated adapter returns COMPLETED by default.

Mode 1 transactions don't have an issuer instruction step, so you can't arm them. To test Mode 2 or Mode 3 paths, use an issuer configured with an ON_INSTRUCTION profile.

What the harness does, step by step

When you arm a scenario, the engine stores an outcome override for that transaction in the simulated-outcome registry. The next time the saga's issuer poller checks in, the adapter reads the override and returns the matching normalised event:

Scenario armed

Adapter returns

Engine action

rejected

InstructionRejected

Auto-unwind: cancel earmark, return locked asset. Transaction reaches failed / cancelled.

failed

InstructionFailed

Park for operator remediation. Transaction reaches failed, parked: true.

silence

No event until SLA expiry

ParkedOnSilence after approvalSlaSeconds; then park.

Pass criteria per scenario

Scenario

Integration passes when…

rejected

Transaction is observed as terminal: true. Locked asset is back in the sender wallet. No balance discrepancy.

failed

Transaction is observed as parked: true, terminal: true. Integration does not retry or auto-resolve.

silence

Transaction remains in-flight during the SLA window, then reaches parked: true, terminal: true. Integration does not time out or error before the SLA budget.

API

Code sample

POST https://sandbox-api.nuvante.io/api/v1/conformance/run

Code sample

{
  "scenario": "rejected",
  "transactionId": "123e4567-e89b-42d3-a456-426614174000"
}

Code sample

{
  "data": {
    "scenario": "rejected",
    "transactionId": "123e4567-e89b-42d3-a456-426614174000"
  },
  "meta": { "commandId": "..." }
}

Once it's armed, poll GET /api/v1/transactions/{id} until terminal is true.

In the portal

Sign in at sandbox.nuvante.io/conformance. The page needs runOwnConformancePack. Paste in a transaction ID, pick a scenario, and the page shows you the outcome as it happens.