Verifiable presentations

​

Overview

A credential is a fact about a participant. You do not send it by itself. You send a verifiable presentation: identity for this payment, in this environment — not a session on the client, and not implied by the payment signature alone. That object is not unique to Atum. It is a W3C Verifiable Credentials concept. An issuer signs a credential. The holder packages one or more credentials into a presentation and signs that wrapper. A verifier checks both signatures. Nobody has to look the holder up. Atum uses that same object. What Atum adds is what the presentation is bound to: this payment, in this environment. Inside the presentation: who signed, and the credentials. On the presentation: this payment and this environment — so it cannot be reused on another payment or copied from testnet to production. Outside: the payment request or quote, unchanged. Payment providers attach the presentation to the request. Settlement providers attach it to each price quote. A request with no presentation still flows.

​

Roles in a presentation

The holder is not the source account unless those are the same party.

​

Sending identity: cards, wallets, and Atum

​

Valid presentations

When a presentation is valid, Atum can check three things from what you sent. No lookup, no callback.

1. Who signed — the same account signed the payment (or quote) and the presentation. That account is the presentation holder.
2. This payment — the presentation cannot be copied onto a different payment.
3. This environment — a presentation made for testnet will not work in production. Use the one minted for the environment you are calling.

Credentials sit inside. For the current catalog that is typically Known to Atum about who signed. Fail any of those once your environment enforces strict checks, and the whole presentation fails — no partial pass. Earlier in the enforcement ladder, a failed check is recorded without blocking the request.

​

Originator vs source account

A credential is a fact about one participant. On a payment you must say which one. These two get mixed up:

• Originator — the payment provider that submitted the request
• Source account — the wallet the funds come from

Known to Atum as a payment provider is about the originator — the signing account Atum onboarded. It is not a credential about the source account. Third-party credentials are about whoever that issuer named; they do not automatically cover the other party. A payment can have an originator Atum already knows and a source account Atum has never seen. Attach the credential that matches the participant the policy is about.

​

What you attach

You attach one presentation. Credentials go inside that presentation. They are not a separate object. On a payment request, that is typically Known to Atum about the originator. On a quote, Known to Atum about the settlement provider. Identity is optional until your environment moves to strict enforcement. Settlement providers using the reference agent can emit a presentation with the quote.

​

If a check fails

Once your environment enforces strict checks, treat a failed presentation like any other request Atum does not accept. Do not retry with a new idempotency key until you know why it failed — a new key is a new payment. Confirm:

• You are calling the environment the presentation was made for
• The presentation holder is the same account that signed the payment or quote
• The Known to Atum credential is the one issued for that account and role
• The credential has not expired

​

What to read next