Single, Batch, and Multiple Issuance

Procivis One enables you to receive single credentials, credentials issued as part of a batch, and multiple credentials in one issuance flow. The wallet also groups credentials that represent the same underlying credential when it is issued in more than one format. This page explains how these types differ, and how the wallet decides whether credentials get grouped together.

Single credentials

A single credential is issued once. The wallet then reuses this credential across multiple presentations. In the list and detail credential endpoints, these credentials appear as "type": "SINGLE".

Batch credentials

Multiple credentials are issued at once. When you receive a batch credential the system creates a batch parent — a logical record that tracks and manages the batch — along with the individual batch items themselves, which are the credentials actually issued and presented. In the list and detail credential endpoints, these appear as "type": "BATCH_PARENT" and "type": "BATCH_ITEM". The wallet automatically generates a unique holder-binding key for each batch item.

A batch parent is created when either:

• the issuer offers more than one credential (a batch size greater than 1), or
• the issuer offers a single credential, or omits batch-size metadata, but the credential has an expiry date and a refresh token is available

The second condition exists because an expiry date plus a refresh token together mean the credential can be renewed later — the wallet groups it as a batch so future refreshes stay connected to it, rather than treating it as a one-off credential.

note

If you specify an identifier when accepting the offer instead of letting the system auto-generate one, the system will not bind multiple credentials from an offered batch. It binds a single credential to that identifier instead, since there's no benefit to holding multiple copies against the same identifier.

When you use the batch parent for submitting presentations, the Core automatically chooses the oldest (unused) batch item closest to expiration. Once presented, the system updates the credential's consumedAt field, found in the credential detail endpoint, and then never uses that credential again.

Batch check and refresh

Use:

• POST /api/credential/v1/revocation-check to check status and
• POST /api/interaction/v1/{interactionId}/issuance/refresh to request a new batch of credentials from the issuer

New batch items are automatically connected to the original batch parent.

Multiple credentials issuance

When an issuer offers multiple credentials in one issuance, the wallet works through several steps: it accepts whichever offered configurations it supports, works out how many distinct credential schemas are in the issuance, and decides which of the resulting credentials belong grouped together under a batch parent.

Accepting supported configurations

POST /api/interaction/v1/issuance-accept iterates through all offered configurations and accepts all supported configurations, returning the resulting credentials in the credentialIds array.

If any configuration is not supported it is skipped, a warning is logged, and partiallySuccessful is returned true. If no configuration is supported, the call fails. Configurations can be skipped for different reasons:

• No format provider enabled matching the format of the offer
• Format string is unknown
• Identifier or key offered does not match the configuration

Schema grouping

Once the wallet has accepted a set of credentials, it works out how many distinct schemas it's actually holding, comparing each candidate against anything it already knows — a sibling credential accepted in the same issuance, or a record from an earlier issuance. When a candidate shares a format with something already known, the ecosystem schema ID settles the comparison directly: a matching ID means the same schema, and the new credential must comply with the existing record or issuance fails. Otherwise — the normal case when comparing different formats, since each format uses its own ecosystem schema ID namespace — the wallet compares display name and claim-tree structure instead.

Two schemas are treated as different — whether the comparison is against an existing record or between two credentials accepted in the same issuance — when any of the following hold:

• The display names differ. If display.name in the credential metadata differs between two credentials, it's treated as two different schemas.
• The format is already taken. The schema already has a credential in this format, but under a different ecosystem schema ID — even if the display name and claims would otherwise match. For example, if a schema named "Drivers License" already has an mdoc credential with doctype: bar, a newly issued credential also named "Drivers License", also mdoc, but with doctype: bar2, is treated as a different schema; the format's identifier conflict settles it before claims are even considered.
• The claim trees are structurally incompatible. A claim is an array in one schema and not the other, a claim is a nested object in one and not the other, or a claim is a user claim in one and a metadata claim in the other.

If none of these hold, the wallet treats the credentials as the same schema. When grouping two schemas together, the wallet creates any necessary mappings between claim translations and technical keys, or updates any existing schema record with new translations or optional claims as needed.

Credential grouping

Once schema grouping has settled how many distinct schemas are involved, the wallet decides which of the resulting credentials to group together:

• credentials with different schemas are never grouped — each is accepted on its own, as a single or batch credential per the usual rules
• credentials with the same schema and the same trust verdict — both resolving to no ecosystem, or the same ecosystem — are grouped together
• credentials with the same schema, but a mismatch in claim values, are not grouped

Grouping is scoped to a single issuance: the wallet can recognize a schema it already knows from an earlier issuance (see Schema grouping above), but it never buckets credentials from separate issuances together into the same wallet entry.

Rejecting grouped credentials

After accepting an issuance, you can reject at a more granular level than rejecting the offer as a whole. With grouped or batch credentials, you can reject:

• a single, ungrouped credential — the issuer is notified, and the interaction cannot be continued (no further refresh)
• all items of a particular format — the issuer is notified, and no further action (refresh, presentation) is possible for that format within this offer going forward; other formats in the group are unaffected
• a single batch item — equivalent to marking that item consumed; only that item is removed