Handle checks, refusals and errors

Mandate responses answer two separate questions:

1. Could the API understand and process the request? The HTTP status answers this.
2. Does the authority permit the requested action? A result boolean and checks answer this.

A robust integration handles both layers. HTTP 200 alone is never proof that the user authorized a charge.

The control flow

For issue:

1. require HTTP 201,
2. save id and confirm_expires_at.

For confirm:

1. require HTTP 200,
2. require confirmed: true,
3. save token unchanged.

For verify:

1. require HTTP 200,
2. require valid: true,
3. require every returned check to have ok: true.

Settlement applies the same pattern to exercise with exercised: true.

HTTP status reference

Successful responses do not use a shared envelope. The list endpoint returns { "user_id", "mandates" }; other operations return their resource or result directly.

Confirmation refusals

Confirm returns HTTP 200 with confirmed: false and no token when the draft cannot become authority:

Concurrent confirmation requests are serialized by a database uniqueness rule. One wins; the other receives already confirmed.

Verification order

For a token that decodes successfully, checks follow this order:

Open responses also carry spent and remaining.

Invalid or expired tokens stop early:

{
  "valid": false,
  "checks": [
    {
      "check": "signature",
      "ok": false,
      "reason": "<JWT validation error>"
    }
  ]
}

An expired token returns an expiry failure instead. Neither case includes mandate_id, and neither records a verified event.

Read the whole check set

A refusal can contain successful checks alongside the one that matters:

{
  "valid": false,
  "mandate_id": "mdt_0123456789abcdef0123456789abcdef",
  "checks": [
    { "check": "signature", "ok": true, "reason": "valid ES256 signature" },
    { "check": "expiry", "ok": true, "reason": "not expired" },
    { "check": "known", "ok": true, "reason": "issued by this service" },
    { "check": "confirmed", "ok": true, "reason": "user confirmed" },
    { "check": "revocation", "ok": false, "reason": "revoked" },
    { "check": "single_use", "ok": true, "reason": "not yet exercised" }
  ]
}

Do not stop at the first ok: true, and do not infer validity from the presence of mandate_id. Require the top-level boolean and every check.

Recovery by failed check

Never “fix” a refusal by deleting a constraint, changing claims, or substituting a different charge after confirmation.

Retry and idempotency boundaries

• Issue is not idempotent. Repeating it creates another mandate ID.
• Confirm can succeed once. A repeat returns confirmed: false with already confirmed.
• Verify is repeatable, but not invisible. Every decodable token records a verified event, even if a later check fails.
• Revoke is idempotent. Repeats return already_revoked: true.
• Closed exercise succeeds once. If the client loses the response, retrieve status and reconcile before retrying.
• Open exercise may succeed many times. reference_id is stored for reconciliation but is not enforced as an idempotency key.

That last point matters: settlement must provide its own duplicate-protection strategy around network retries.

Audit trail

GET /v1/mandate/{id}/evidence returns:

• the draft or confirmed claims,
• the confirmed token when one exists,
• evidence supplied at issue, and
• ordered lifecycle events.

issued and revoked events may have detail: null. Non-null event details are returned as JSON-encoded strings, so consumers that need their structured contents must parse detail a second time.

A successful token decode records verified even when a later lifecycle or constraint check fails. Closed settlement records exercised; open settlement records charged. Together, these events show what the user approved, what callers attempted, and what settlement committed.

Continue

• Choose mandate constraints
• Issue your first closed mandate
• Use an open mandate
• Design choices and AP2