diff --git a/docs/specification/checkout.md b/docs/specification/checkout.md index 06a396bb..f7ff9da6 100644 --- a/docs/specification/checkout.md +++ b/docs/specification/checkout.md @@ -58,38 +58,36 @@ determines what action is required next. The business sets the status; the platform receives messages indicating what's needed to progress. ```text -┌────────────┐ ┌─────────────────────┐ -│ incomplete │◀──▶│ requires_escalation │ -└─────┬──────┘ │ │ - │ │ (buyer handoff │ - │ │ via continue_url) │ - │ └──────────┬──────────┘ - │ │ - │ all info collected │ continue_url - ▼ │ -┌──────────────────┐ │ -│ready_for_complete│ │ -│ │ │ -│ (platform can │ │ -│ call Complete │ │ -│ Checkout). │ │ -└────────┬─────────┘ │ - │ │ - │ Complete Checkout │ - ▼ │ -┌────────────────────┐ │ -│complete_in_progress│ │ -└─────────┬──────────┘ │ - │ │ - └────────┬─────────┘ - ▼ - ┌─────────────┐ - │ completed │ - └─────────────┘ - - ┌─────────────┐ - │ canceled │ (session invalid/expired - can occur from any state) - └─────────────┘ + +------------+ +---------------------+ + | incomplete |<----------------------->| requires_escalation | + +-----+------+ | (buyer handoff | + | | via continue_url) | + | all info collected +----------+----------+ + v | + +------------------+ | + |ready_for_complete| | + | | | + | (platform can | | continue_url + | call Complete | | + | Checkout) | | + +--------+---------+ | + | | + | Complete Checkout | + v | + +--------------------+ | + |complete_in_progress| | + +---------+----------+ | + | | + +-----------------------+-------------------+ + v + +-------------+ + | completed | + +-------------+ + + +-------------+ + | canceled | + +-------------+ + (session invalid/expired - can occur from any state) ``` ### Status Values diff --git a/docs/specification/examples/encrypted-credential-handler.md b/docs/specification/examples/encrypted-credential-handler.md index de2eb36d..9e2c6b3c 100644 --- a/docs/specification/examples/encrypted-credential-handler.md +++ b/docs/specification/examples/encrypted-credential-handler.md @@ -59,33 +59,33 @@ Compliance requirements vary by credential type. ### Pattern Flow ```text -┌─────────────────┐ ┌────────────┐ -│ Platform │ │ Business │ -│ │ │ │ -└────────┬────────┘ └──────┬─────┘ - │ │ - │ 1. Business registers public key (out-of-band) - │<─────────────────────────────────────────────│ - │ │ - │ 2. Confirmation │ - │─────────────────────────────────────────────>│ - │ │ - │ 3. GET ucp.payment_handlers │ - │─────────────────────────────────────────────>│ - │ │ - │ 4. Handler with business identity │ - │<─────────────────────────────────────────────│ - │ │ - │ 5. Platform's vaulting service encrypts │ - │ credential with business's key │ - │ │ - │ 6. POST checkout with EncryptedCredential │ - │─────────────────────────────────────────────>│ - │ │ - │ (Business decrypts locally) │ - │ │ - │ 7. Checkout complete │ - │<─────────────────────────────────────────────│ ++-----------------+ +------------+ +| Platform | | Business | +| | | | ++--------+--------+ +------+-----+ + | | + | 1. Business registers public key (out-of-band) + |<---------------------------------------------| + | | + | 2. Confirmation | + |--------------------------------------------->| + | | + | 3. GET ucp.payment_handlers | + |--------------------------------------------->| + | | + | 4. Handler with business identity | + |<---------------------------------------------| + | | + | 5. Platform's vaulting service encrypts | + | credential with business's key | + | | + | 6. POST checkout with EncryptedCredential | + |--------------------------------------------->| + | | + | (Business decrypts locally) | + | | + | 7. Checkout complete | + |<---------------------------------------------| ``` --- diff --git a/docs/specification/examples/platform-tokenizer-payment-handler.md b/docs/specification/examples/platform-tokenizer-payment-handler.md index b4ef6f62..376d6cdb 100644 --- a/docs/specification/examples/platform-tokenizer-payment-handler.md +++ b/docs/specification/examples/platform-tokenizer-payment-handler.md @@ -65,76 +65,77 @@ compliant credential storage. ### Pattern Flow: Business Detokenizes ```text -┌─────────────────┐ ┌────────────┐ -│ Platform │ │ Business │ -│ (Tokenizer) │ │ │ -└────────┬────────┘ └──────┬─────┘ - │ │ - │ 1. Business registers with Platform (out-of-band) - │<─────────────────────────────────────────────│ - │ │ - │ 2. API credentials │ - │─────────────────────────────────────────────>│ - │ │ - │ 3. GET ucp.payment_handlers │ - │─────────────────────────────────────────────>│ - │ │ - │ 4. Handler with business identity │ - │<─────────────────────────────────────────────│ - │ │ - │5. Platforms's Credential Provider generates token│ - │ │ - │ 6. POST checkout with TokenCredential │ - │─────────────────────────────────────────────>│ - │ │ - │ 7. POST /detokenize (to Credential Provider)│ - │<─────────────────────────────────────────────│ - │ │ - │ 8. Sensitive Data │ - │─────────────────────────────────────────────>│ - │ │ - │ 9. Checkout complete │ - │<─────────────────────────────────────────────│ ++-----------------+ +------------+ +| Platform | | Business | +| (Tokenizer) | | | ++--------+--------+ +------+-----+ + | | + | 1. Business registers with Platform (out-of-band) + |<---------------------------------------------| + | | + | 2. API credentials | + |--------------------------------------------->| + | | + | 3. GET ucp.payment_handlers | + |--------------------------------------------->| + | | + | 4. Handler with business identity | + |<---------------------------------------------| + | | + |5. Platforms's Credential Provider generates token + | | + | 6. POST checkout with TokenCredential | + |--------------------------------------------->| + | | + | 7. POST /detokenize (to Credential Provider)| + |<---------------------------------------------| + | | + | 8. Sensitive Data | + |--------------------------------------------->| + | | + | 9. Checkout complete | + |<---------------------------------------------| ``` ### Pattern Flow: PSP Detokenizes ```text -┌─────────────────┐ ┌────────────┐ ┌─────────┐ -│ Platform │ │ Business │ │ PSP │ -│ (Tokenizer) │ │ │ │ │ -└────────┬────────┘ └──────┬─────┘ └────┬────┘ - │ │ │ - │ 1. Business + PSP register with Platform (out-of-band) - │<────────────────────│ │ - │<──────────────────────────────────────│ - │ │ │ - │ 2. API credentials │ │ - │────────────────────>│ │ - │──────────────────────────────────────>│ - │ │ │ - │ 3. Payment Credential Provider │ - │ generates token │ - │ │ │ - │ 4. POST checkout with TokenCredential│ - │────────────────────>│ │ - │ │ │ - │ │ 5. Forward │ - │ │ token to PSP │ - │ │────────────────>│ - │ │ │ - │ 6. POST /detokenize (to Credential Provider, with business identity) - │<──────────────────────────────────────│ - │ │ │ - │ 7. Sensitive Data │ │ - │──────────────────────────────────────>│ - │ │ │ - │ │ 8. Payment │ - │ │ result │ - │ │<────────────────│ - │ │ │ - │ 9. Checkout complete │ - │<────────────────────│ │ ++-----------------+ +------------+ +---------+ +| Platform | | Business | | PSP | +| (Tokenizer) | | | | | ++--------+--------+ +------+-----+ +----+----+ + | | | + | 1. Business + PSP register with Platform (out-of-band) + |<--------------------| | + |<--------------------------------------| + | | | + | 2. API credentials | | + |-------------------->| | + |-------------------------------------->| + | | | + | 3. Payment Credential Provider | + | generates token | + | | | + | 4. POST checkout with TokenCredential| + |-------------------->| | + | | | + | | 5. Forward | + | | token to PSP | + | |---------------->| + | | | + | 6. POST /detokenize (to Credential Provider, with business identity) + |<--------------------------------------| + | | | + | 7. Sensitive Data | | + |-------------------------------------->| + | | | + | | 8. Payment | + | | result | + | | | + | |<----------------| + | | | + | 9. Checkout complete | + |<--------------------| | ``` --- diff --git a/docs/specification/examples/processor-tokenizer-payment-handler.md b/docs/specification/examples/processor-tokenizer-payment-handler.md index 6c76a8c5..7ec90fb8 100644 --- a/docs/specification/examples/processor-tokenizer-payment-handler.md +++ b/docs/specification/examples/processor-tokenizer-payment-handler.md @@ -60,30 +60,30 @@ happens internally within the Processor's secure environment. ### Pattern Flow ```text -┌────────────┐ ┌───────────────────────────────────┐ -│ Platform │ │ Tokenizer / Processor │ -│ (Collector)│ │ (Business or PSP) │ -└─────┬──────┘ └─────────────────┬─────────────────┘ - │ │ - │ 1. GET ucp.payment_handlers │ - │─────────────────────────────────────────────────>│ - │ │ - │ 2. Handler Config (URL + Identity) │ - │<─────────────────────────────────────────────────│ - │ │ - │ 3. POST /tokenize (Credential + Identity) │ - │─────────────────────────────────────────────────>│ - │ │ - │ 4. Token │ - │<─────────────────────────────────────────────────│ - │ │ - │ 5. POST checkout with TokenCredential │ - │─────────────────────────────────────────────────>│ - │ │ - │ (Internal Resolution: Token -> Info) │ - │ │ - │ 6. Payment Result │ - │<─────────────────────────────────────────────────│ ++------------+ +-----------------------------------+ +| Platform | | Tokenizer / Processor | +| (Collector)| | (Business or PSP) | ++-----+------+ +-----------------+-----------------+ + | | + | 1. GET ucp.payment_handlers | + |------------------------------------------------->| + | | + | 2. Handler Config (URL + Identity) | + |<-------------------------------------------------| + | | + | 3. POST /tokenize (Credential + Identity) | + |------------------------------------------------->| + | | + | 4. Token | + |<-------------------------------------------------| + | | + | 5. POST checkout with TokenCredential | + |------------------------------------------------->| + | | + | (Internal Resolution: Token -> Info) | + | | + | 6. Payment Result | + |<-------------------------------------------------| ``` --- diff --git a/docs/specification/payment-handler-guide.md b/docs/specification/payment-handler-guide.md index f62314d4..37263ea3 100644 --- a/docs/specification/payment-handler-guide.md +++ b/docs/specification/payment-handler-guide.md @@ -55,29 +55,29 @@ function calls. Spec authors must map these logical flows to the actual transport protocol used by their implementation. ```text -┌──────────────────────────────────────────────────────────────────────────────┐ -│ Payment Handler Framework │ -├──────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌──────────────┐ │ -│ │ PARTICIPANTS │ Who participates in this handler? │ -│ └──────┬───────┘ │ -│ │ │ -│ ▼ │ -│ ┌──────────────┐ │ -│ │PREREQUISITES │ How does each participant obtain identity & configs? │ -│ └──────┬───────┘ │ -│ │ │ -│ ├────────────────────┬──────────────────────┐ │ -│ ▼ ▼ ▼ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ HANDLER │ │ INSTRUMENT │ │ PROCESSING │ │ -│ │ DECLARATION │ │ ACQUISITION │ │ │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -│ Business advertises platform acquires Participant │ -│ handler config checkout instrument processes instrument │ -│ │ -└──────────────────────────────────────────────────────────────────────────────┘ ++------------------------------------------------------------------------------+ +| Payment Handler Framework | ++------------------------------------------------------------------------------+ +| | +| +--------------+ | +| | PARTICIPANTS | Who participates in this handler? | +| +------+-------+ | +| | | +| v | +| +--------------+ | +| |PREREQUISITES | How does each participant obtain identity & configs? | +| +------+-------+ | +| | | +| +--------------------+----------------------+ | +| v v v | +| +--------------+ +--------------+ +--------------+ | +| | HANDLER | | INSTRUMENT | | PROCESSING | | +| | DECLARATION | | ACQUISITION | | | | +| +--------------+ +--------------+ +--------------+ | +| Business advertises platform acquires Participant | +| handler config checkout instrument processes instrument | +| | ++------------------------------------------------------------------------------+ ``` ### Participants diff --git a/docs/specification/payment-handler-template.md b/docs/specification/payment-handler-template.md index 447054b9..32a706e7 100644 --- a/docs/specification/payment-handler-template.md +++ b/docs/specification/payment-handler-template.md @@ -57,18 +57,18 @@ supports.} {Optional: ASCII diagram showing participant relationships} ```text -┌─────────┐ ┌───────────────┐ ┌────────────┐ -│Platform │ │ {Provider} │ │ Business │ -└────┬────┘ └───────┬───────┘ └──────┬─────┘ - │ │ │ - │ {step 1} │ │ - │─────────────────>│ │ - │ │ │ - │ {step 2} │ │ - │<─────────────────│ │ - │ │ │ - │ {step 3} │ - │──────────────────────────────────────>│ ++---------+ +---------------+ +------------+ +|Platform | | {Provider} | | Business | ++----+----+ +-------+-------+ +------+-----+ + | | | + | {step 1} | | + |----------------->| | + | | | + | {step 2} | | + |<-----------------| | + | | | + | {step 3} | + |-------------------------------------->| ``` --- diff --git a/docs/specification/tokenization-guide.md b/docs/specification/tokenization-guide.md index 3274c1e1..9a4ec2e7 100644 --- a/docs/specification/tokenization-guide.md +++ b/docs/specification/tokenization-guide.md @@ -46,23 +46,23 @@ We offer a range of examples to utilize forms of tokenization in UCP: Tokenization handlers transform credentials between source and checkout forms: ```text -┌─────────────────────────────────────────────────────────────────────────┐ -│ Tokenization Payment Flow │ -├─────────────────────────────────────────────────────────────────────────┤ -│ │ -│ Platform has: Tokenizer Business receives: │ -│ Source Credential ──▶ /tokenize ──▶ TokenCredential │ -│ │ -│ ┌─────────────────┐ ┌─────────────────────────┐ │ -│ │ source_ │ │ checkout_ │ │ -│ │ credentials │ What goes IN │ credentials │ │ -│ │ │◀─────────────── │ │ │ -│ │ • card/fpan │ │ What comes OUT │ │ -│ │ • card/dpan │ ─────▶│ • token │ │ -│ │ │ │ │ │ -│ └─────────────────┘ └─────────────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ ++-------------------------------------------------------------------------+ +| Tokenization Payment Flow | ++-------------------------------------------------------------------------+ +| | +| Platform has: Tokenizer Business receives: | +| Source Credential --> /tokenize --> TokenCredential | +| | +| +-----------------+ +-------------------------+ | +| | source_ | | checkout_ | | +| | credentials | What goes IN | credentials | | +| | |<--------------- | | | +| | * card/fpan | | What comes OUT | | +| | * card/dpan | ----->| * token | | +| | | | | | +| +-----------------+ +-------------------------+ | +| | ++-------------------------------------------------------------------------+ ``` Tokenization handlers accept source credentials (e.g., card with FPAN) and @@ -74,13 +74,13 @@ Tokens move through distinct phases. Your handler specification must document which lifecycle policy you use: ```text -┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ -│ Generation │───▶│ Storage │───▶│ Detokenize │───▶│ Invalidation │ -│ │ │ │ │ │ │ │ -│Platform calls│ │ Tokenizer │ │ Business/PSP │ │ Token expires│ -│ /tokenize │ │ holds token │ │ calls │ │ or is used │ -│ │ │ → credential │ │ /detokenize │ │ │ -└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ ++--------------+ +--------------+ +--------------+ +--------------+ +| Generation |--->| Storage |--->| Detokenize |--->| Invalidation | +| | | | | | | | +|Platform calls| | Tokenizer | | Business/PSP | | Token expires| +| /tokenize | | holds token | | calls | | or is used | +| | | -> credential| | /detokenize | | | ++--------------+ +--------------+ +--------------+ +--------------+ ``` | Policy | Description | Use Case |