Skip to content

docs(ack-pay): align receipt verification guide with implementation - #267

Open
aeoess wants to merge 1 commit into
agentcommercekit:mainfrom
aeoess:docs/receipt-verification-checks
Open

aeoess wants to merge 1 commit into
agentcommercekit:mainfrom
aeoess:docs/receipt-verification-checks

Conversation

@aeoess

@aeoess aeoess commented Nov 18, 2026 •

Copy link
Copy Markdown

Updates the receipt verification guide to match the current implementation at 3db94d6.

  • Replaces the Ed25519 proof example with JwtProof2020, the proof type currently supported by verifyProof.
  • Clarifies what verifyPaymentReceipt checks and what the application must check separately. The verifier does not validate receipt metadata, enforce payment request expiration or accept an expected request ID.
  • Clarifies that applications must check the expected recipient, amount, request ID and freshness against their own requirements.

This follows the existing distinction between receipt verification and application-specific checks.

Fixes the documentation discrepancies reported in #264.

AI assistance: Claude Code helped compare the documentation with the implementation and prepare the edit. I reviewed the claims against verify-proof.ts and verify-payment-receipt.ts at 3db94d6.

Documentation only. No runtime behavior changes.

Summary by CodeRabbit

  • Documentation
    • Updated the payment receipt example to use a signed JWT proof and clarified that ACK verifies the proof and payment request token, including the selected payment option.
    • Clarified that callers are responsible for checking receipt metadata such as recipient, amount, request ID, and recency. The request token is verified without an expiry check because receipts may outlive requests.

The receipt example used an Ed25519Signature2020 proof, which verifyProof
rejects with UnsupportedProofTypeError. Use a JwtProof2020 proof instead.

The Verify Payment Details step listed six checks without saying which ones
verifyPaymentReceipt performs. State that it checks the request token and the
payment option, that the token is verified without its expiry, and that the
metadata, request id and recency checks are the caller's.

Refs agentcommercekit#264
@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The receipt verification documentation now uses a JWT proof example and describes which checks verifyPaymentReceipt performs and which checks callers must perform.

Changes

Receipt verification documentation

Layer / File(s) Summary
Receipt proof and verification scope
docs/ack-pay/receipt-verification.mdx
The example replaces the Ed25519 proof with a JwtProof2020 proof containing a signed JWT. The guidance describes the verification performed by verifyPaymentReceipt and identifies metadata, recipient, amount, request ID, and recency checks as caller responsibilities.

Estimated code review effort: 2 (Simple) | ~8 minutes

Change: Other

Possibly related issues

  • Issue 264 reports discrepancies in the receipt proof example and verification scope. This PR updates both in the documentation.
Merge Risk: Minimal · up to c8fba

This documentation update aligns the receipt verification guide with how verification actually works. It has no runtime effect and no merge-blocking risk.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the docs(ack-pay) scope and the core change: aligning the receipt verification guide with the implementation. The changeset replaces the Ed25519 proof example with JwtProof2020 and cla…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the docs(ack-pay) scope and the core change: aligning the receipt verification guide with the implementation. The changeset replaces the Ed25519 proof example with JwtProof2020 and clarifies what verifyPaymentReceipt checks versus what the caller must check. The title is specific and matches the main change. It does not mention the JwtProof2020 switch, but that detail is not required for the title to pass.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: d96402fa-2849-40f0-8492-b72c7d1e5e9d
Commits

Reviewing files that changed from the base of the PR and between 3db94d6 and c8fba7b.

Files selected for processing: 1

  • docs/ack-pay/receipt-verification.mdx

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

@mintlify

mintlify Bot commented Nov 18, 2026

Copy link
Copy Markdown

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit c8fba7b.

Approve preview

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant