docs: clarify participant identifier in payment handler examples - #791
Open
prasad-stripe wants to merge 2 commits into
Open
docs: clarify participant identifier in payment handler examples#791prasad-stripe wants to merge 2 commits into
prasad-stripe wants to merge 2 commits into
Conversation
The three payment handler examples describe the participant identifier three different ways, and one of them teaches the wrong threat model. This aligns the examples with tokenization.md. 1. processor-tokenizer: "Merchant Secure Identifier" framed identity.access_token as a secret, contradicting tokenization.md Binding rule 4, which states that identity is a participant identifier, not a credential, and that a Tokenizer MUST NOT accept it as authentication. Replaced with participant identifier framing, plus a Security Considerations row stating the rule explicitly. 2. processor-tokenizer: a MUST required the credential provider to send the handler configuration's identity object, but no config table or example declaration in that document defines an identity member; the config publishes business_id. Reworded against the config field that exists, using the document's own PSP Mode and Direct Mode framing. 3. platform-tokenizer: the same value appeared as identity.access_token in Prerequisites and as business_id in the config table, with no stated mapping, while three normative statements referenced "the business's identity from the handler declaration". The mapping from config.business_id to identity.access_token is now stated once where the config is defined, and the three statements reference it. config remains handler-defined, per ucp.json#/$defs/entity. 4. encrypted-credential: Prerequisites listed identity.access_token and References pointed at payment_identity.json, but this handler implements neither /tokenize nor /detokenize, and its encrypted payload carries only credential and binding. Replaced with business_id, which the document's own next paragraph already uses, and with binding.json. No schema file is touched. The added Security Considerations row restates tokenization.md Binding rule 4, and item 2 repoints an existing MUST at the config member the examples actually publish.
17 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The three payment handler examples describe the same participant identifier in three different ways, and one of them teaches the wrong threat model. This aligns all three with
tokenization.md.Since #746 moved
identityout ofbinding,identity.access_tokenis a participant identifier, andtokenization.mdBinding rule 4 states that a Tokenizer MUST NOT accept it as authentication. The examples had not caught up.Four fixes:
processor-tokenizer: "Issueidentity.access_token(Merchant Secure Identifier) to merchants" framed the identifier as a secret, which contradicts Binding rule 4. Replaced with participant identifier framing, and added a Security Considerations row stating the rule explicitly.processor-tokenizer: a MUST required the credential provider to send the handler configuration'sidentityobject, but no config table or example declaration in that document defines anidentitymember. The config publishesbusiness_id. Reworded against the field that exists, split by the document's own PSP Mode and Direct Mode framing.platform-tokenizer: the same value appeared asidentity.access_tokenin Prerequisites Output and asbusiness_idin the config table, with no stated mapping, while three normative statements referenced "the business'sidentityfrom the handler declaration". The mapping is now stated once where the config is defined, and the three statements referenceconfig.business_id.encrypted-credential: Prerequisites Output listedidentity.access_tokenand References pointed atpayment_identity.json, but this handler implements neither/tokenizenor/detokenize, and its encrypted payload carries credential plus binding. Replaced withbusiness_id, which the next paragraph already uses, and repointed the reference tobinding.json.No schema file is touched, and no new normative requirement is introduced. The added Security Considerations row restates Binding rule 4, and fix 2 repoints an existing MUST at the config member the examples actually publish.
configdeliberately stays handler-defined. Anidentitymember was not added to the config tables, becauseconfiginherits fromucp.json#/$defs/entityasadditionalProperties: truewith "Structure defined by each entity's schema". The examples state the mapping instead of reserving a UCP member name inside a handler-defined object.Category (Required)
Related Issues
Follow-up to #746, which separated participant scope from resource scope. Related to #394, which raises the naming of
access_token; this PR does not change any field name.Checklist
!for breaking changes).Screenshots / Logs (if applicable)
Prose and table edits only, no rendering change. Verified locally with markdownlint (repo config
.github/linters/.markdownlint.json), cspell, andgit diff --check. Diff is 35 insertions and 26 deletions across three files.