From c8fba7be733b9215b38329219b78949b4a7f71d7 Mon Sep 17 00:00:00 2001 From: Tymofii Pidlisnyi Date: Wed, 18 Nov 2026 10:42:50 -0800 Subject: [PATCH] docs(ack-pay): align receipt verification guide with implementation 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 #264 --- docs/ack-pay/receipt-verification.mdx | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/ack-pay/receipt-verification.mdx b/docs/ack-pay/receipt-verification.mdx index ec449e4c..d433cec8 100644 --- a/docs/ack-pay/receipt-verification.mdx +++ b/docs/ack-pay/receipt-verification.mdx @@ -46,12 +46,9 @@ _Example ACK Receipt Verifiable Credential:_ } }, "proof": { - // Standard VC proof (digital signature) - "type": "Ed25519Signature2020", - "created": "2025-04-04T14:22:18Z", - "verificationMethod": "did:web:receipts.example.com#key-1", - "proofPurpose": "assertionMethod", - "proofValue": "z3..." // Signature value + // ACK verifies JwtProof2020 proofs: the credential signed as a JWT by the issuer + "type": "JwtProof2020", + "jwt": "eyJhbGciOi..." // Signed JWT encoding this credential } } ``` @@ -130,6 +127,15 @@ When an ACK Receipt is presented by a Client Agent to a Server Agent (e.g., when - Are the credential `issuanceDate` and settlement `timestamp` values recent enough, or has the receipt potentially expired based on policy? + By default, `verifyPaymentReceipt` performs the first two checks. It + verifies the signed `paymentRequestToken` and confirms that `paymentOptionId` + names one of its payment options. It does not read + `credentialSubject.metadata`, so the recipient, amount, request `id` and + recency checks are left to the caller. To check the request `id`, compare the + returned `paymentRequest.id` with the one you issued. The request token is + verified without its expiry, because a receipt outlives the request, so apply + your own recency policy. + If all these checks pass, the Server can confidently treat the payment as valid