Skip to content

Receipt documentation differs from verification code #264

Open

Description

@aeoess

I found two differences between the ACK-Pay receipt documentation and the verification code at 3db94d6. I'm mapping ACK's credentials for the Agent Governance Vocabulary and want to make sure I understand what a verified receipt proves.

1. Proof format

docs/ack-pay/receipt-verification.mdx shows an Ed25519Signature2020 proof with a proofValue.

But verifyProof in packages/vc/src/verification/verify-proof.ts accepts only JwtProof2020 and throws UnsupportedProofTypeError for other proof types.

Should the example use a JWT proof, or is support for the documented proof type intended?

2. Payment amount

The same page shows amount, currency, decimals, recipient and a settlement timestamp in credentialSubject.metadata. It tells the server to check those fields, but also describes metadata as non-normative.

The current verifyPaymentReceipt checks paymentOptionId and the signed request token. It does not check those metadata fields.

If the settled amount differs from the offered amount, what does a successfully verified receipt establish, which payment option the client selected or how much actually settled?

If these behaviors are intentional, could the docs clarify them? I can prepare a documentation PR once I know the intended behavior. A pointer to the v2 redesign would also help if it replaces these sections.

AI use. Claude helped compare the files and draft the findings, and ChatGPT helped revise the wording. I checked the reported differences against commit 3db94d6.

Activity

  1. hheskihoran commented on Nov 18, 2026

    @hheskihoran

    Independent confirmation of both points, read from the source at 3db94d6 (still the head of main today). Disclosure: I maintain INAM Protocol, another receipt format; I am not affiliated with ACK and I only read the two files below, I did not run the package.

    1. Proof format: confirmed. verifyProof in packages/vc/src/verification/verify-proof.ts has one case, JwtProof2020, and throws UnsupportedProofTypeError for everything else. The Ed25519Signature2020 / proofValue example in docs/ack-pay/receipt-verification.mdx (lines 50 to 54) would therefore be rejected by the code it documents.

    2. Amount: confirmed, and it is wider than the amount. After the credential checks, verifyPaymentReceipt (packages/ack-pay/src/verify-payment-receipt.ts) does two things with the payment itself: it verifies the embedded payment request token, and it checks that credentialSubject.paymentOptionId is the id of one of paymentRequest.paymentOptions. It never reads credentialSubject.metadata. Of the six questions listed under "Verify Payment Details" in the doc, the code answers the first two. These are left to the caller:

    • recipient matches the server;
    • amount, currency and decimals are sufficient;
    • the request id is the one the server issued (the function takes no expected id; it returns paymentRequest so the caller can compare);
    • recency of issuanceDate and the settlement timestamp. The request token is verified with verifyExpiry: false, so an expired request does not fail here either.

    So on your last question, as the code stands: a verified receipt establishes that a trusted issuer signed a receipt naming one option of a validly signed request. It does not establish how much settled, in what currency, or to whom, unless the caller checks metadata that the same page calls non-normative.

    That may be the intended split (the library checks signatures and binding, the application checks the money). If so, the doc step would be accurate with one sentence saying which of the six checks verifyPaymentReceipt performs and which are the caller's.

  2. aeoess commented on Nov 18, 2026

    @aeoess
    Author

    Thanks for catching the expiry check. I missed that in my original review.

    I've opened #267 to correct the documentation, including the proof type and the checks left to the application.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions