ap2_mandate_verifier 1.6.0 → 1.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.ja.md +102 -180
- data/README.md +126 -207
- data/docs/DIAGNOSTICS.ja.md +83 -2
- data/docs/DIAGNOSTICS.md +98 -2
- data/docs/LONG_PAYMENT.md +3 -1
- data/docs/PAYMENT_ACCEPTANCE.md +5 -0
- data/docs/PUBLIC_API.md +12 -1
- data/docs/RECURRING_PAYMENT.md +4 -2
- data/docs/RELEASE_160_CANDIDATE.md +1 -1
- data/docs/RELEASE_161_CANDIDATE.md +33 -0
- data/docs/RUBY_INTEGRATION.ja.md +208 -0
- data/docs/RUBY_INTEGRATION.md +225 -0
- data/docs/SUPPORT_CONTRACT.md +16 -3
- data/examples/integration/inputs.rb +169 -0
- data/examples/integration/processor.rb +39 -0
- data/examples/ruby_integration.rb +161 -0
- data/lib/ap2_mandate_verifier/payment.rb +27 -21
- data/lib/ap2_mandate_verifier/payment_acceptance.rb +59 -10
- data/lib/ap2_mandate_verifier/payment_diagnostics.rb +78 -0
- data/lib/ap2_mandate_verifier/payment_receipt.rb +14 -9
- data/lib/ap2_mandate_verifier/selective_payment.rb +14 -10
- data/lib/ap2_mandate_verifier.rb +1 -0
- metadata +9 -2
data/README.md
CHANGED
|
@@ -1,153 +1,133 @@
|
|
|
1
1
|
# AP2 Mandate Verifier — Ruby SDK for Checkout and Payment
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[日本語](README.ja.md) · **Published stable: 1.6.1** · [Quick Start](docs/QUICK_START.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Issue, present and verify supported AP2 Checkout and Payment Mandates in plain Ruby.
|
|
6
|
+
Use this Gem when your app needs to check what a buyer approved, what an Agent may
|
|
7
|
+
choose, and whether signed Checkout/Payment data stays within those conditions.
|
|
8
|
+
No Rails dependency. **Verification success is not purchase or payment success; the SDK never executes payments.**
|
|
6
9
|
|
|
7
|
-
```ruby
|
|
8
|
-
# Protected enrollment + current authority synchronization are application duties.
|
|
9
|
-
accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
|
|
10
|
-
execution = service.start(ticket: accepted.ticket, verification_inputs: fresh_raw_inputs) if accepted.ticket
|
|
11
|
-
usage = store.usage(**trusted_series_scope) # reservations, not settlement
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
### Published1.5.0: transactional Payment acceptance
|
|
15
|
-
|
|
16
|
-
Reserve a protected business occurrence atomically, reverify before one fenced start, and recover the original Receipt after response loss without reopening an uncertain attempt. [Verified publication](docs/POST_RELEASE_150.md). [Integration/store/security contract](docs/PAYMENT_ACCEPTANCE.md), [plain Ruby recovery example](examples/payment_acceptance.rb), [release gates](docs/RELEASE_150_CANDIDATE.md).
|
|
17
|
-
|
|
18
|
-
```ruby
|
|
19
|
-
accepted = service.accept(**trusted_scope, mode: :conditional, verification_inputs: raw_inputs)
|
|
20
|
-
dispatch = service.start(ticket: accepted.ticket, verification_inputs: fresh_inputs) if accepted.ticket
|
|
21
|
-
# Application-owned processor call uses dispatch.processor_key; no SDK payment call.
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
Verification, durable reservation and settlement are separate. Use protected enrollment, one authoritative store and processor idempotency/lookup; no automatic timeout release. Existing1.x verifiers remain unchanged. The optional SQLite reference driver is installed separately.
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
### Published1.4.0: PISP and execution-date Payment conditions
|
|
28
|
-
|
|
29
|
-
Explicit Payment profiles now constrain approved PISPs and parsed inclusive execution windows, bound to independent application provider/time context. Existing1.x defaults remain unchanged. [Contract/API/official differences](docs/PAYMENT_POLICY.md), [plain Ruby three-mode example](examples/payment_policy.rb), [verified publication](docs/POST_RELEASE_140.md).
|
|
30
|
-
|
|
31
|
-
### Published 1.3.0: selective Checkout and Payment
|
|
32
|
-
|
|
33
|
-
Keep the complete approved Open confidential and disclose only the merchant/products needed for Checkout, then selected payee/instrument candidates for Payment. Every mandatory condition and quantity remains enforced. [Profile/API/privacy/Python limits](docs/SELECTIVE_CHECKOUT.md), [plain Ruby combined lifecycle](examples/selective_checkout_payment.rb), [verified publication](docs/POST_RELEASE_130.md).
|
|
34
|
-
|
|
35
|
-
### Published1.2.0: selective Payment
|
|
36
|
-
|
|
37
|
-
Published1.2.0 adds explicit `SelectivePayment` candidate-array disclosure: retain confidential full issuance, send selected payee/instrument disclosures only, and verify every mandatory condition and exact original-wire reference. [Profile/API/privacy/Python limits](docs/SELECTIVE_PAYMENT.md), [plain Ruby retained-vs-sent example](examples/selective_payment.rb), [verified publication](docs/POST_RELEASE_120.md). Existing `Payment` defaults remain unchanged.
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
### Payment lifecycle (since1.1.0)
|
|
41
|
-
|
|
42
|
-
1.1.0 adds Direct and conditional Payment Mandates plus signed Success/Error Payment Receipts. [Payment APIs and constraints](docs/PAYMENT.md), [plain Ruby lifecycle sample](examples/payment.rb), [verified publication](docs/POST_RELEASE_110.md), [GitHub Release](https://github.com/cuichangquan/ap2-mandate-verifier/releases/tag/v1.1.0). Verification does not grant execution permission; durable atomic one-use state and actual payment remain application responsibilities.
|
|
43
|
-
|
|
44
|
-
```sh
|
|
45
|
-
gem install ap2_mandate_verifier --version 1.5.0
|
|
46
|
-
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.5.0").full_gem_path')/examples/payment.rb"
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
[日本語](README.ja.md)
|
|
50
|
-
|
|
51
|
-
**Published stable: 1.5.0.**
|
|
52
|
-
|
|
53
|
-
1.0.0 establishes the stable public contract for the existing
|
|
54
|
-
Direct and conditional Checkout APIs. It preserves 0.8.0 signatures, defaults,
|
|
55
|
-
profiles, result meanings, saved formats and runtime implementation.
|
|
56
|
-
See [the public API contract](docs/PUBLIC_API.md),
|
|
57
|
-
[maintenance policy](docs/POST_RELEASE_MAINTENANCE.md) and
|
|
58
|
-
[1.0.0 release notes](docs/RELEASE_100.md). The official Gem matches the retained
|
|
59
|
-
candidate; [publication verification](docs/POST_RELEASE_100.md) records its exact
|
|
60
|
-
source, bytes and validation scope.
|
|
61
|
-
|
|
62
|
-
## Conditional purchase delegation
|
|
63
|
-
|
|
64
|
-
Available since 0.8.0, `ConditionalCheckout.issue_open`, `.issue_closed` and `.present`
|
|
65
|
-
support this flow:
|
|
66
|
-
approve A/B×1 plus C×2, issue Open for a registered Agent key, let that Agent close
|
|
67
|
-
a matching merchant-signed Checkout, then use existing `InputBuilder.verify` and
|
|
68
|
-
`CheckoutReceipt.sign/verify`. All candidates remain disclosed under the unchanged
|
|
69
|
-
multi-item profile. Provider private keys never enter Agent operations.
|
|
70
|
-
[API and trust contract](docs/CONDITIONAL_CHECKOUT.md), [conditional code sample](docs/RELEASE_080.md) and [1.0.0 publication verification](docs/POST_RELEASE_100.md).
|
|
71
|
-
|
|
72
|
-
Ruby-only Quick Start on MRI 3.4.12 or 4.0.9; no source checkout or Rails required:
|
|
73
|
-
|
|
74
|
-
```sh
|
|
75
|
-
gem install ap2_mandate_verifier --version 1.5.0
|
|
76
|
-
ruby "$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.5.0").full_gem_path')/examples/conditional_checkout.rb"
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
The [standalone Ruby example](examples/conditional_checkout.rb) uses only installed
|
|
80
|
-
public APIs, three rows, candidate choice, different requirement quantities and
|
|
81
|
-
repeated products through both Receipt outcomes. Success consumes the operation;
|
|
82
|
-
Error requires a new policy decision; missing Receipt or uncertain effect remains
|
|
83
|
-
pending. Authentication, consent, enrollment, durable replay prevention and actual
|
|
84
|
-
order/payment execution remain app-owned. Documented 0.8.0 API use needs no source
|
|
85
|
-
migration; update the dependency constraint as described below.
|
|
86
|
-
|
|
87
|
-
Direct and conditional workflows cover one merchant and 1–8 Checkout lines,
|
|
88
|
-
including multiple products and quantities. Existing Direct and both Open→Closed
|
|
89
|
-
profiles retain their contracts in 1.0.0.
|
|
90
|
-
|
|
91
|
-
## Multiple items and quantities
|
|
92
10
|
|
|
93
|
-
|
|
11
|
+
**Platforms:** MRI 3.4.12 / 4.0.9. Existing native published-Gem checks cover **1.6.0** on Linux ARM64/AMD64, macOS Intel/Apple Silicon and Windows Server 2022 X64, not the new CLI. See [platform evidence and reproduction](docs/PLATFORM_SUPPORT.md) and the separate [1.6.1 Linux publication checks](docs/POST_RELEASE_161.md). Rails demo compatibility is separate.
|
|
94
12
|
|
|
95
|
-
|
|
13
|
+
## Start here
|
|
96
14
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
`InputBuilder` converts business records into verification inputs: it creates the Gem-specific trust/selection/Host JSON, fingerprints and original-wire digests for you. You still choose whom to trust and supply the expected order, challenge state and clock. The Gem is Rails-independent and performs no network, database or payment operations.
|
|
100
|
-
|
|
101
|
-
## Try the local demo
|
|
102
|
-
|
|
103
|
-
The [Rails demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme) uses published 0.8.0 and InputBuilder by default. Its Docker instructions require no host Ruby installation. It retains the existing synthetic Open→Agent Closed verification, multi-item and Success/Error Receipt screens. It has no conditional approval/issuance UI; use the standalone Ruby example above for that lifecycle. It is local-only and performs no real challenge issuance, nonce consumption or purchase/payment.
|
|
104
|
-
|
|
105
|
-
## Install
|
|
106
|
-
|
|
107
|
-
Formal support is **MRI 3.4.12 and MRI 4.0.9**. In your chosen Gem environment:
|
|
15
|
+
This minimal SDK quick start uses **published 1.6.1**. For its integration CLI, use the [Gem-only integration instructions](docs/RUBY_INTEGRATION.md).
|
|
108
16
|
|
|
109
17
|
```sh
|
|
110
|
-
gem install ap2_mandate_verifier --version 1.
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
```ruby
|
|
116
|
-
gem "ap2_mandate_verifier", "~> 1.0"
|
|
18
|
+
gem install ap2_mandate_verifier --version 1.6.1
|
|
19
|
+
AP2_GEM_DIR="$(ruby -e 'puts Gem::Specification.find_by_name("ap2_mandate_verifier", "1.6.1").full_gem_path')"
|
|
20
|
+
ruby "$AP2_GEM_DIR/examples/conditional_checkout.rb"
|
|
21
|
+
ruby "$AP2_GEM_DIR/examples/payment.rb"
|
|
117
22
|
```
|
|
118
23
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
24
|
+
These installed examples create synthetic keys and approvals, issue/present/verify
|
|
25
|
+
Mandates, then authenticate alternative Success and Error Receipts. An authentic
|
|
26
|
+
Error Receipt reports failure. No account, credentials, database or Rails required.
|
|
27
|
+
Allow about ten minutes with a supported Ruby already installed; dependency builds
|
|
28
|
+
and Docker's first download can take longer.
|
|
29
|
+
|
|
30
|
+
**Next:** [step-by-step Quick Start and expected output (1.6.0 baseline)](docs/QUICK_START.md),
|
|
31
|
+
including twelve UTC months and a cumulative JPY budget rejection.
|
|
32
|
+
[Docker demo](https://github.com/cuichangquan/ap2-mandate-verifier-demo#readme)
|
|
33
|
+
uses published **1.6.0**, with local Checkout screens and Ruby Payment examples.
|
|
34
|
+
|
|
35
|
+
## Choose a workflow
|
|
36
|
+
|
|
37
|
+
**Integrating a real application?** Start with the [Ruby integration and restart
|
|
38
|
+
recovery guide](docs/RUBY_INTEGRATION.md): protected application inputs, persistent
|
|
39
|
+
mock results, separate-process recovery and safe retry decisions. Use this repository
|
|
40
|
+
with published 1.6.0, or install **published 1.6.1** for the bundled CLI without a
|
|
41
|
+
repository checkout. Public 1.6.0 does not include this CLI. See the
|
|
42
|
+
[exact 1.6.1 distribution and verification](docs/POST_RELEASE_161.md).
|
|
43
|
+
|
|
44
|
+
Checkout describes the order; a Checkout Mandate records approval/delegation for it.
|
|
45
|
+
A Payment Mandate adds payment conditions and references the Checkout approval.
|
|
46
|
+
Receipts authenticate an application's reported outcome for the original final Mandate;
|
|
47
|
+
they do not independently prove settlement.
|
|
48
|
+
|
|
49
|
+
| Workflow | Use when | API / guide |
|
|
50
|
+
| --- | --- | --- |
|
|
51
|
+
| Direct | Buyer approves an exact signed order/payment | `Buyer`, `Payment.issue_direct` · [Checkout](docs/BUYER_DIRECT_CHECKOUT.md) / [Payment](docs/PAYMENT.md) |
|
|
52
|
+
| Conditional delegation | Buyer approves candidates and limits; registered Agent chooses within them | `ConditionalCheckout`, `Payment.issue_open/issue_closed/present` · [Checkout](docs/CONDITIONAL_CHECKOUT.md) |
|
|
53
|
+
| Selective disclosure | Keep the full approved Open private and send selected merchant/product or payee/instrument candidates | `SelectiveCheckout`, `SelectivePayment` · [Checkout](docs/SELECTIVE_CHECKOUT.md) / [Payment](docs/SELECTIVE_PAYMENT.md) |
|
|
54
|
+
| Long Open | Reuse one approved Checkout/Payment Open pair across explicit UTC months, with finite count and cumulative JPY budget | `LongPayment`, `PaymentAcceptance::LongSQLiteStore` · [contract](docs/LONG_PAYMENT.md) |
|
|
55
|
+
|
|
56
|
+
Direct and conditional Checkout support one merchant and up to eight lines with
|
|
57
|
+
quantities under the explicit multi-item profile. The default single-SKU profile
|
|
58
|
+
retains its one-line contract. Selective profiles retain all mandatory conditions
|
|
59
|
+
and quantities; candidate count/order and issuer-JWT linkability are not hidden.
|
|
60
|
+
Long Open is a separate complete-disclosure profile (content up to 400 days,
|
|
61
|
+
short-lived proofs); it does not compose with selective or PISP/date profiles.
|
|
62
|
+
**Its UTC-monthly profile is not full compliance with generic AP2 MONTHLY semantics.**
|
|
63
|
+
|
|
64
|
+
Other explicit options: [PISP / execution-date constraints](docs/PAYMENT_POLICY.md),
|
|
65
|
+
[transactional acceptance and recovery](docs/PAYMENT_ACCEPTANCE.md), and bounded
|
|
66
|
+
[ON_DEMAND count / JPY budget profiles](docs/RECURRING_PAYMENT.md).
|
|
67
|
+
Existing 1.x API signatures, defaults, profiles and saved formats remain supported.
|
|
68
|
+
|
|
69
|
+
## Choose your API by role
|
|
70
|
+
|
|
71
|
+
| Your component | Start with |
|
|
72
|
+
| --- | --- |
|
|
73
|
+
| Merchant backend | `CheckoutJWT.sign`; `CheckoutReceipt.sign/verify` |
|
|
74
|
+
| Trusted approval backend | `CheckoutJWT.verify` before consent; `Buyer.issue_closed` or `ConditionalCheckout.issue_open`; corresponding Payment issuance |
|
|
75
|
+
| Registered Agent | `Buyer.present_closed`, or conditional `issue_closed/present`; selective variants for supported disclosure profiles. Provider private keys stay in the approval backend. |
|
|
76
|
+
| Merchant / payment verifier | `Buyer.verify` for Direct; `InputBuilder.prepare/restore/verify` for conditional Checkout; `Payment.verify` for Payment plus Checkout binding; explicit selective/long variants |
|
|
77
|
+
| Receipt consumer | `CheckoutReceipt.verify`, `PaymentReceipt.verify`; check authenticity **and** reported outcome |
|
|
78
|
+
| App managing durable Payment acceptance | `PaymentAcceptance::Service` and the appropriate protected store; [integration contract](docs/PAYMENT_ACCEPTANCE.md) |
|
|
79
|
+
|
|
80
|
+
`verify_checkout` (also `verify_research`) is the complete seven-input conditional
|
|
81
|
+
Checkout entry. `InputBuilder` is the recommended business-record adapter.
|
|
82
|
+
Legacy `verify(presentation_json:)` checks syntax only and never returns successful
|
|
83
|
+
Evidence. [Exact APIs and result/error conventions](docs/PUBLIC_API.md).
|
|
84
|
+
|
|
85
|
+
## Install and support
|
|
86
|
+
|
|
87
|
+
Formal support: **MRI 3.4.12 and 4.0.9**. For this walkthrough use
|
|
88
|
+
`gem "ap2_mandate_verifier", "= 1.6.0"` in a Gemfile. Applications following stable
|
|
89
|
+
1.x may use `"~> 1.0"` and review lockfile updates. `~> 0.8.0` excludes 1.x;
|
|
90
|
+
[upgrade notes](docs/RELEASE_100.md) retain the compatibility details.
|
|
91
|
+
|
|
92
|
+
Runtime pins: JSON 2.19.9, JWT 3.3.0, base64 0.3.0, OpenSSL gem 4.0.2,
|
|
93
|
+
Digest 3.2.1. Installation may download/build native dependencies. Do not loosen
|
|
94
|
+
pins to bypass a conflict. The resolution interval does not certify every Ruby,
|
|
95
|
+
OS or provider. [Support contract](docs/SUPPORT_CONTRACT.md).
|
|
96
|
+
|
|
97
|
+
## Responsibilities before using this in your app
|
|
98
|
+
|
|
99
|
+
The core verifier performs no network or payment operations. Optional acceptance
|
|
100
|
+
stores perform local database transactions; SQLite requires a separately installed
|
|
101
|
+
driver. **Verification, durable reservation, application authorization and settlement
|
|
102
|
+
are separate events.**
|
|
103
|
+
|
|
104
|
+
Your app owns authentication, consent, protected approval records, independently
|
|
105
|
+
trusted current keys/revocation/profile policy, order/challenge state and clock.
|
|
106
|
+
It must recheck current authority, durably consume one-use state atomically, handle
|
|
107
|
+
uncertain results, and decide whether to call a processor. SDK acceptance and
|
|
108
|
+
Receipt authentication do not establish real Issuer trust or processor exactly-once.
|
|
109
|
+
Missing/invalid Receipt or unknown effect stays pending for reconciliation; do not
|
|
110
|
+
automatically retry or refund allowance on timeout/Error.
|
|
111
|
+
|
|
112
|
+
Unknown/unsupported forms fail closed. Exceptions, unavailable results and missing
|
|
113
|
+
results never authorize an operation. Do not log private keys, raw Mandates/nonces
|
|
114
|
+
or treat serialized Evidence as an authenticated credential. General AP2/all-Schema
|
|
115
|
+
conformance, real-Issuer interoperability and production GO are not claimed.
|
|
116
|
+
[Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md),
|
|
117
|
+
[security policy](SECURITY.md), [acceptance boundaries](docs/PAYMENT_ACCEPTANCE.md).
|
|
118
|
+
|
|
119
|
+
## Reference and retained evidence
|
|
120
|
+
|
|
121
|
+
- [Public API](docs/PUBLIC_API.md), [InputBuilder guide](docs/INPUT_BUILDER.md), [diagnostics](docs/DIAGNOSTICS.md).
|
|
122
|
+
- [1.6.0 publication verification](docs/POST_RELEASE_160.md), [changelog](CHANGELOG.md), [project/publication history](docs/PROJECT_STATUS.md), [maintenance policy](docs/POST_RELEASE_MAINTENANCE.md).
|
|
123
|
+
- [Merchant signing](docs/MERCHANT_SIGNING.md), [multiple items](docs/MULTI_ITEM_CHECKOUT.md), [Python differences](docs/MULTI_ITEM_INTEROP.md).
|
|
124
|
+
|
|
125
|
+
Historical release and research documents remain evidence for their recorded
|
|
126
|
+
versions, not the current onboarding path. Repository documentation changes do
|
|
127
|
+
not rebuild or replace the already published 1.6.0 Gem.
|
|
128
|
+
|
|
129
|
+
<details>
|
|
130
|
+
<summary>Source-checkout InputBuilder walkthrough (advanced)</summary>
|
|
151
131
|
|
|
152
132
|
## A small InputBuilder example
|
|
153
133
|
|
|
@@ -197,74 +177,13 @@ Expected for these unchanged synthetic inputs: `verified_research/scoped_researc
|
|
|
197
177
|
|
|
198
178
|
Do not call `prepare` again during verification or update saved hashes/references to match current values. Changed orders, trust or signed bytes must remain detectable. Persisted trust JSON can be loaded with `restore_trust` without reserializing it. The [complete example](examples/input_builder.rb) includes normal/tampered/expired cases; the [input guide](docs/INPUT_BUILDER.md) explains the business fields, exact restoration and Rails model mapping.
|
|
199
179
|
|
|
200
|
-
## Results and responsibility boundaries
|
|
201
|
-
|
|
202
|
-
The following table applies to complete Open → Agent Closed verification through
|
|
203
|
-
InputBuilder or `verify_checkout`. Direct, Checkout and Receipt APIs retain their
|
|
204
|
-
own `verified?` or exception contracts; see [all result conventions](docs/PUBLIC_API.md#result-object-and-failure-contracts).
|
|
205
|
-
|
|
206
|
-
| Result | Meaning and next step |
|
|
207
|
-
| --- | --- |
|
|
208
|
-
| `:verified_research` / `:scoped_research_verified`, `success? == true` | Immutable Evidence contains checked facts for the fixed profile. The Host must still decide whether to authorize the purchase. |
|
|
209
|
-
| `:rejected`, `rejected? == true` | No Evidence. Stop and inspect `result.code`. |
|
|
210
|
-
| `:unavailable`, `unavailable? == true` | No Evidence. Stop; a dependency or processing failure is not proof of invalid business data. |
|
|
211
|
-
|
|
212
|
-
On failure, inspect supplemental check candidates. Successful results have no failure diagnostic.
|
|
213
180
|
|
|
214
|
-
|
|
215
|
-
if (diagnostic = result.diagnostic)
|
|
216
|
-
puts diagnostic.to_h(locale: :en) # :ja for Japanese
|
|
217
|
-
end
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
`stage / field / reason / hint` are guidance; they do not change status/code or the verdict. Unknown fields/causes are not asserted. See the [diagnostic guide](docs/DIAGNOSTICS.md).
|
|
181
|
+
</details>
|
|
221
182
|
|
|
222
|
-
|
|
183
|
+
### Next candidate: Payment diagnostics
|
|
223
184
|
|
|
224
|
-
The
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
Unknown/unsupported forms fail closed. General AP2/all-Schema support, real Issuer
|
|
230
|
-
interoperability, new selective-disclosure profiles, Rails adapters, DB/payment
|
|
231
|
-
execution and numeric performance guarantees remain outside scope. Real
|
|
232
|
-
Issuer/Host production GO and Phase 2-B remain separate HOLDs.
|
|
233
|
-
|
|
234
|
-
### Which API should I use?
|
|
235
|
-
|
|
236
|
-
| Entry | Role |
|
|
237
|
-
| --- | --- |
|
|
238
|
-
| `ConditionalCheckout.issue_open/issue_closed/present` | Conditional issuance and original-wire presentation; full merchant verification remains required. |
|
|
239
|
-
| `Buyer.issue_closed/present_closed/verify` | Direct exact-order issuance, structural presentation and full Direct verification. |
|
|
240
|
-
| `CheckoutJWT.sign/verify` | Merchant Checkout signing and authentication before approval. |
|
|
241
|
-
| `CheckoutReceipt.reference/sign/verify` | Original final-Mandate reference, explicit application outcome signing and Receipt authentication. |
|
|
242
|
-
| `InputBuilder.verify(**business_information)` | Recommended business-data path. Assembles inputs and runs complete verification; preparation and restoration are separate steps shown above. |
|
|
243
|
-
| `verify_checkout(**inputs)` | Complete Open → Agent Closed verification with the existing seven inputs, including caller-supplied trust/selection/Host JSON. |
|
|
244
|
-
| `verify_research(**inputs)` | Retained name for the same seven-input verification pipeline; no deprecation warning. |
|
|
245
|
-
| `verify(presentation_json:)` | Legacy JSON syntax check only. Never returns successful Evidence. |
|
|
246
|
-
|
|
247
|
-
Malformed assembly arguments, including missing keywords, to `InputBuilder.verify` return `:rejected / :invalid_host_context`. Assembly dependency/unexpected failures return `:unavailable / :research_verification_unavailable`; results from the complete core retain their codes. In contrast, missing/unknown keywords to the direct `verify_checkout` / `verify_research` entries return `:unavailable / :research_verification_unavailable`. Every such failure has `success? == false` and `evidence == nil`. See [the exact contract](docs/SUPPORT_CONTRACT.md#full-entry-and-required-inputs) for shapes, bounds and Ruby argument-binding caveats.
|
|
248
|
-
|
|
249
|
-
## More detail
|
|
250
|
-
|
|
251
|
-
- [1.x public API, errors, profiles and persistence contract](docs/PUBLIC_API.md). Existing partial-verification APIs remain supported and never return successful Evidence.
|
|
252
|
-
- [Business-data lifecycle and Rails mapping](docs/INPUT_BUILDER.md), [complete Ruby example](examples/input_builder.rb) and [before/after example](examples/input_builder_before.rb).
|
|
253
|
-
- [Supported inputs, limits and Result/Evidence contract](docs/SUPPORT_CONTRACT.md); [Issuer/Host responsibilities](docs/ISSUER_HOST_MINIMUM_CONTRACT.md).
|
|
254
|
-
- [1.0.0 Release notes](docs/RELEASE_100.md), [publication/withdrawal records](docs/PROJECT_STATUS.md) and [changelog](CHANGELOG.md). Repository README changes do not rebuild or replace published Gem bytes.
|
|
255
|
-
- [Pinned historical seven-input / saved FULL example](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.md#try-the-saved-synthetic-example), [older artifact/provider evidence](research/stable010_release_linux_package/README.md) and [historical conceptual diagrams](https://github.com/cuichangquan/ap2-mandate-verifier/blob/e0ab9fb21045e89fc58fb06145eeda4855b2dc54/README.md#illustrated-concepts-japanese-diagrams). These records are preserved, not current integration instructions or broader support claims.
|
|
256
|
-
- [Security reporting](SECURITY.md), [maintenance policy](docs/POST_RELEASE_MAINTENANCE.md) and [product direction](docs/PRODUCT_VISION.md). Do not include secrets, real Mandates or personal data in reports.
|
|
257
|
-
|
|
258
|
-
MIT. See [LICENSE](LICENSE).
|
|
259
|
-
|
|
260
|
-
### Buyer Direct checkout (published 0.7.0)
|
|
261
|
-
|
|
262
|
-
Trusted Surface backends can verify a merchant Checkout before approval, issue a
|
|
263
|
-
Provider-signed Closed Mandate, and let the Shopping Agent present it. The new
|
|
264
|
-
`AP2MandateVerifier::Buyer` module verifies Direct Closed-only presentations at
|
|
265
|
-
the merchant and uses `CheckoutReceipt` with `profile_ref: Buyer::PROFILE_REF`.
|
|
266
|
-
One merchant, 1–8 lines, multiple products and quantities are supported end to end.
|
|
267
|
-
Existing Open→Agent Closed APIs and both profiles retain their contracts.
|
|
268
|
-
See [API and responsibility contract](docs/BUYER_DIRECT_CHECKOUT.md) and the
|
|
269
|
-
[runnable approval-to-Receipt example](examples/direct_checkout.rb). Verification
|
|
270
|
-
is not purchasing authority or payment success. See the [short verified buyer-flow sample](docs/RELEASE_070.md).
|
|
185
|
+
The 1.7.0 candidate adds optional Payment/Receipt/acceptance diagnostics and a
|
|
186
|
+
call-local `start_with_diagnostic` API while preserving `start`'s Execution/nil
|
|
187
|
+
contract. It is not published by this change. See [diagnostics](docs/DIAGNOSTICS.md)
|
|
188
|
+
for English/Japanese hints, authentic Error Receipt semantics and unknown-result
|
|
189
|
+
limits. Diagnostics never authorize a payment retry or quota release.
|
data/docs/DIAGNOSTICS.ja.md
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 診断
|
|
2
|
+
|
|
3
|
+
Checkout・InputBuilderは0.4.0で導入。Payment以降は1.7.0候補で追加。
|
|
2
4
|
|
|
3
5
|
Gem内部を追わず、失敗した検査と次の確認候補を取得できます。診断は補助情報です。
|
|
4
6
|
既存呼び出し、status/code、固定profile、Fail Closed、非成功時のEvidenceなし契約は不変です。
|
|
5
|
-
|
|
7
|
+
Checkout・InputBuilderの成功時のdiagnosticはnilです。診断処理が失敗してもnilとなり、検証結果は変わりません。
|
|
6
8
|
ヒントから購入・決済の許可を判断しないでください。
|
|
7
9
|
|
|
8
10
|
## Before / After
|
|
@@ -74,3 +76,82 @@ ruby examples/input_builder.rb unsupported_saved_format
|
|
|
74
76
|
unknown_field、unsupported_saved_formatになります。合成fixtureの固定時刻を使います。
|
|
75
77
|
業務データの対応・保存責務は[InputBuilderガイド](INPUT_BUILDER.ja.md)を参照してください。
|
|
76
78
|
Gemの公開は、実Issuer接続、本番購入許可、Phase 2-B移行を意味しません。
|
|
79
|
+
|
|
80
|
+
## Payment以降の診断(1.7.0候補、この変更では未公開)
|
|
81
|
+
|
|
82
|
+
上記0.4.0の説明はCheckout・InputBuilderの導入時期と過去の検証記録です。
|
|
83
|
+
今回の追加は1.7.0候補です。Payment・Receiptのcode、述語、例外契約は維持します。
|
|
84
|
+
Direct・条件付き・Selective・Longの結果で`diagnostic`を取得できます。
|
|
85
|
+
成功したPaymentはnil。真正で参照が一致するError Receiptは**検証成功**であり、
|
|
86
|
+
`payment_rejected? == true`、`payment_succeeded? == false`、診断は`reported_error`です。
|
|
87
|
+
再決済や利用枠解放の許可ではありません。
|
|
88
|
+
|
|
89
|
+
```ruby
|
|
90
|
+
payment = AP2MandateVerifier::Payment.verify(**payment_inputs)
|
|
91
|
+
puts payment.code # 拒否時は従来どおり :payment_verification_failed
|
|
92
|
+
puts payment.diagnostic&.to_h(locale: :ja)
|
|
93
|
+
# stage: :payment_verification, field: nil,
|
|
94
|
+
# reason: :payment_time_mismatch, hint: "..."
|
|
95
|
+
|
|
96
|
+
# 1回の試行ではどちらか一方だけ。診断のためにstartを繰り返さない。
|
|
97
|
+
observation = service.start_with_diagnostic(ticket: ticket,
|
|
98
|
+
verification_inputs: fresh_inputs)
|
|
99
|
+
execution = observation.execution # Executionまたはnil
|
|
100
|
+
puts observation.diagnostic&.to_h(locale: :ja)
|
|
101
|
+
# 従来のservice.start(...)は今までどおりExecutionまたはnil。
|
|
102
|
+
# nilなら決済を開始しない。未実行や安全な再試行を意味しない。
|
|
103
|
+
|
|
104
|
+
receipt = AP2MandateVerifier::PaymentReceipt.verify(**receipt_inputs)
|
|
105
|
+
if receipt.verified?
|
|
106
|
+
puts receipt.payment_rejected? # 真正なErrorならtrue
|
|
107
|
+
else
|
|
108
|
+
puts receipt.code # :payment_receipt_verification_failed
|
|
109
|
+
end
|
|
110
|
+
puts receipt.diagnostic&.to_h(locale: :ja)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
引数・service・ticketの準備は[組み込み例](RUBY_INTEGRATION.ja.md)を参照してください。
|
|
114
|
+
この抜粋では独立した信頼情報、時刻、注文、保護された承認、永続保存先と決済処理を省略しています。
|
|
115
|
+
診断の取得で検証・予約・開始・決済・保存先の再読込は行いません。
|
|
116
|
+
旧版・成功・診断生成失敗で診断がnilでも、元の判定は変わりません。
|
|
117
|
+
|
|
118
|
+
### 段階・理由と確認できる事実
|
|
119
|
+
|
|
120
|
+
| stage | 代表reason | 確認できる事実 |
|
|
121
|
+
| --- | --- | --- |
|
|
122
|
+
| `payment_verification` | `checkout_not_verified` | 内部Checkout検証が成功していない。原因は断定しない |
|
|
123
|
+
| `payment_verification` | `checkout_binding_mismatch` | 既存のCheckoutとPaymentの照合が不一致 |
|
|
124
|
+
| `payment_verification` | `payment_time_mismatch` | 既存のPayment内容有効期間検査が不一致 |
|
|
125
|
+
| `payment_verification` | `payment_conditions_mismatch` | 完全開示profileの既存支払い条件検査が不一致 |
|
|
126
|
+
| `payment_verification` | `payment_binding_mismatch` | 期待Paymentまたは証明の結び付けが不一致 |
|
|
127
|
+
| `payment_receipt_verification` | `receipt_reference_mismatch` | 発行者・支払いID・原Payment参照の既存照合が不一致 |
|
|
128
|
+
| `payment_receipt_verification` | `receipt_time_mismatch` | Receipt発行時刻または独立した許容期間が不一致 |
|
|
129
|
+
| `payment_receipt_verification` | `reported_error` | 真正なError報告。決済成功・再試行許可ではない |
|
|
130
|
+
| `payment_acceptance` | `pending`・`unknown`・`receipt_error` | 既存の結果status。追加読込による推測はしない |
|
|
131
|
+
| `payment_acceptance` | `conflict`・`unavailable` | 保存先の例外区分のみ。具体的原因・保存確定状態は不明 |
|
|
132
|
+
| `payment_execution` | `saved_binding_mismatch` | 最新指示または署名原文が保存済み記録と不一致 |
|
|
133
|
+
| `payment_execution` | `undetermined` | 実行ハンドルなし。期限切れ・競合・不確実な保存の識別はできない |
|
|
134
|
+
|
|
135
|
+
`invalid_arguments`はPayment・Receipt・Selective検証のキーワード形状拒否です。
|
|
136
|
+
`signed_input_rejected`は署名入力に関する型付き拒否で、暗号署名の失敗とは限りません。
|
|
137
|
+
`verification_unavailable`は依存関係・検証処理の明示的な利用不可です。
|
|
138
|
+
それ以外の例外は`undetermined`とし、例外全文やシナリオ名から原因を推測しません。
|
|
139
|
+
Mandate・鍵・nonce・非開示候補・支払い情報・外部例外全文は診断へ含めません。
|
|
140
|
+
|
|
141
|
+
診断範囲は網羅的ではありません。Direct・条件付きからpolicy・継続・Longへ共通検査は届きますが、
|
|
142
|
+
不正な構造・Selective開示・詳細なPISPや日付制約・Long権限・期間管理は詳細不明の場合があります。
|
|
143
|
+
保存先の予約拒否だけでは、利用枠・回数超過と承認欠落・失効・その他の保護状態不正を区別できません。
|
|
144
|
+
保存先ガイドに従って保護された承認、現在の期間・利用枠、保存済み処理を確認し、特定の原因と断定しないでください。
|
|
145
|
+
Receipt検証は実決済の完了証明ではありません。不明・タイムアウト・真正なErrorは自動再決済や利用枠解放の根拠になりません。
|
|
146
|
+
|
|
147
|
+
### 保存と並行性
|
|
148
|
+
|
|
149
|
+
`StartResult`は呼び出しごとの変更不能オブジェクトです。serviceの`last_diagnostic`や
|
|
150
|
+
スレッド・Fiber共有の診断変数はありません。受理Resultの診断はfinish・reconcile・lookup・unknownも対象です。
|
|
151
|
+
保存形式とStoreの公開インターフェースは変更しません。独自アダプターの結果に診断がない場合は
|
|
152
|
+
`respond_to?(:diagnostic)`とnilで扱ってください。
|
|
153
|
+
|
|
154
|
+
保存するのはカタログ識別子だけとし、`Diagnostic.payment_flow(stage, reason)`で安全な定義へ戻せます。
|
|
155
|
+
未知の組合せはnil、fieldは常にnilです。保存済みstage・field・reasonの一致を検査し、
|
|
156
|
+
任意の保存済みhintを表示しないでください。未知値から原因を補完せず、表示時に復旧処理を始めないでください。
|
|
157
|
+
将来のminor版で詳細が追加され得るため未知・nilのfallbackを持ち、制御は従来のstatus・codeに従います。
|
data/docs/DIAGNOSTICS.md
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Diagnostics
|
|
2
|
+
|
|
3
|
+
Checkout/InputBuilder introduced in 0.4.0; Payment flow added in the 1.7.0 candidate.
|
|
2
4
|
|
|
3
5
|
Diagnostics help you inspect a failed check without reading gem internals. They
|
|
4
6
|
are supplemental: existing calls, status/code, fixed profile, Fail Closed and
|
|
5
|
-
non-success `evidence == nil` are unchanged. A successful result has
|
|
7
|
+
non-success `evidence == nil` are unchanged. A successful Checkout/InputBuilder result has
|
|
6
8
|
`diagnostic == nil`. A diagnostic failure also returns nil and cannot change a
|
|
7
9
|
verification result. Never make a payment/authorization decision from a hint.
|
|
8
10
|
|
|
@@ -86,3 +88,97 @@ reasons `missing_required_field`, `invalid_type`, `unknown_field` and
|
|
|
86
88
|
[InputBuilder](INPUT_BUILDER.md) for data mapping and storage responsibilities.
|
|
87
89
|
Gem availability does not imply real Issuer interoperability, production
|
|
88
90
|
authorization or Phase 2-B GO.
|
|
91
|
+
|
|
92
|
+
## Payment flow (1.7.0 candidate; not published by this change)
|
|
93
|
+
|
|
94
|
+
The original 0.4.0 sections above describe Checkout/InputBuilder diagnostics and
|
|
95
|
+
historical evidence, not the version to install for this addition. Payment and
|
|
96
|
+
Receipt `code`, predicates and exception contracts are unchanged. Direct,
|
|
97
|
+
conditional, selective and Long verification expose `result.diagnostic`;
|
|
98
|
+
successful Payment verification has nil. Authentic matching Error Receipts are
|
|
99
|
+
**verified**, with `payment_rejected? == true`, `payment_succeeded? == false`,
|
|
100
|
+
and an explanatory `reported_error` diagnostic. This is not retry permission.
|
|
101
|
+
|
|
102
|
+
```ruby
|
|
103
|
+
payment = AP2MandateVerifier::Payment.verify(**payment_inputs)
|
|
104
|
+
puts payment.code # still :payment_verification_failed on every failure
|
|
105
|
+
puts payment.diagnostic&.to_h(locale: :en)
|
|
106
|
+
# e.g. {stage: :payment_verification, field: nil,
|
|
107
|
+
# reason: :payment_time_mismatch, hint: "..."}
|
|
108
|
+
|
|
109
|
+
# Choose ONE start entry point per attempt, never both for diagnosis.
|
|
110
|
+
observation = service.start_with_diagnostic(ticket: ticket,
|
|
111
|
+
verification_inputs: fresh_inputs)
|
|
112
|
+
execution = observation.execution # Execution or nil
|
|
113
|
+
puts observation.diagnostic&.to_h(locale: :en)
|
|
114
|
+
# Existing service.start(...) still returns exactly Execution or nil.
|
|
115
|
+
# Do not dispatch when execution is nil. Nil proves neither non-execution
|
|
116
|
+
# nor that repeating start/payment is safe.
|
|
117
|
+
|
|
118
|
+
receipt = AP2MandateVerifier::PaymentReceipt.verify(**receipt_inputs)
|
|
119
|
+
if receipt.verified?
|
|
120
|
+
puts receipt.payment_rejected? # true for an authentic Error Receipt
|
|
121
|
+
else
|
|
122
|
+
puts receipt.code # :payment_receipt_verification_failed
|
|
123
|
+
end
|
|
124
|
+
puts receipt.diagnostic&.to_h(locale: :en)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`payment_inputs`, `fresh_inputs`, `receipt_inputs`, `service` and `ticket` above
|
|
128
|
+
come from the [Ruby integration example](RUBY_INTEGRATION.md), not received hints.
|
|
129
|
+
The application supplies independent trust, clock, order, protected approval and
|
|
130
|
+
persistent storage. The excerpt omits those inputs and all processor operations.
|
|
131
|
+
No diagnostic getter repeats verification, reservation, start, settlement or reads
|
|
132
|
+
additional storage. An absent diagnostic is supported (old versions, success or
|
|
133
|
+
failed diagnostic generation); it never turns failure into success.
|
|
134
|
+
|
|
135
|
+
### Stages, facts and limits
|
|
136
|
+
|
|
137
|
+
| Stage | Representative reason | Fact established |
|
|
138
|
+
| --- | --- | --- |
|
|
139
|
+
| `payment_verification` | `checkout_not_verified` | Nested Checkout verification did not succeed, not proof of its cause |
|
|
140
|
+
| `payment_verification` | `checkout_binding_mismatch` | An existing Checkout/payment binding comparison failed |
|
|
141
|
+
| `payment_verification` | `payment_time_mismatch` | Existing Payment content validity comparison failed |
|
|
142
|
+
| `payment_verification` | `payment_conditions_mismatch` | An existing complete-profile payment condition failed |
|
|
143
|
+
| `payment_verification` | `payment_binding_mismatch` | Expected payment or proof binding comparison failed |
|
|
144
|
+
| `payment_receipt_verification` | `receipt_reference_mismatch` | Existing issuer/payment-ID/original Payment reference comparison failed |
|
|
145
|
+
| `payment_receipt_verification` | `receipt_time_mismatch` | Existing Receipt or independent time window comparison failed |
|
|
146
|
+
| `payment_receipt_verification` | `reported_error` | Authentic matching Receipt reported Error, not verified settlement success |
|
|
147
|
+
| `payment_acceptance` | `pending`, `unknown`, `receipt_error` | Existing result status only, no extra state lookup |
|
|
148
|
+
| `payment_acceptance` | `conflict`, `unavailable` | Store reported that class of error, not a specific cause or commit state |
|
|
149
|
+
| `payment_execution` | `saved_binding_mismatch` | Fresh instruction or original signed wires differ from saved state |
|
|
150
|
+
| `payment_execution` | `undetermined` | No execution handle; cannot distinguish expiry, competing start or uncertain commit |
|
|
151
|
+
|
|
152
|
+
`invalid_arguments` identifies rejected keyword shape on Payment/Receipt/Selective
|
|
153
|
+
verify. `signed_input_rejected` describes a typed signed-input rejection, **not
|
|
154
|
+
necessarily a cryptographic signature failure**. `verification_unavailable`
|
|
155
|
+
describes an explicitly unavailable dependency/check. Other exceptions use
|
|
156
|
+
`undetermined`, never exception-message matching. Diagnostics do not disclose raw
|
|
157
|
+
Mandates, keys, nonce, candidate sets, payment data or exception text.
|
|
158
|
+
|
|
159
|
+
The same Payment checks feed Direct/conditional, policy, recurring and Long
|
|
160
|
+
profiles, but **coverage is deliberately not exhaustive**: malformed shapes,
|
|
161
|
+
selective disclosure checks, detailed PISP/date policies, Long authority and
|
|
162
|
+
period policies can remain `undetermined`. A store's rejected quota reservation
|
|
163
|
+
does not distinguish exhausted budget/count from missing/revoked approval or
|
|
164
|
+
other invalid protected state. Inspect protected approval, current period/quota
|
|
165
|
+
and stored attempts according to the store guide, without assuming any one cause.
|
|
166
|
+
Receipt validation does not establish real processor settlement. Unknown results,
|
|
167
|
+
timeouts and authentic Error never authorize automatic retries or quota release.
|
|
168
|
+
|
|
169
|
+
### Persistence and concurrency
|
|
170
|
+
|
|
171
|
+
`StartResult` is immutable and call-local; there is no `last_diagnostic` on a
|
|
172
|
+
service and no shared thread/fiber diagnostic slot. `Result#diagnostic` on
|
|
173
|
+
acceptance also covers finish, reconcile, lookup and unknown results. Existing
|
|
174
|
+
store interfaces and persisted formats are unchanged. Custom adapters returning
|
|
175
|
+
nonstandard result objects need not expose diagnostics; applications may use
|
|
176
|
+
`respond_to?(:diagnostic)` and handle nil.
|
|
177
|
+
|
|
178
|
+
Persist catalog identifiers only. `Diagnostic.payment_flow(stage, reason)`
|
|
179
|
+
returns a trusted immutable catalog entry or nil for an unknown pair. Its field
|
|
180
|
+
is always nil. Validate the stored triple against that result; do not render
|
|
181
|
+
arbitrary stored hints, translate unknown values into a cause, or automatically
|
|
182
|
+
start recovery while reading diagnostics. Identifiers may gain detail in later
|
|
183
|
+
minor versions; keep an unknown/nil fallback and use existing status/code for
|
|
184
|
+
control flow. Do not use hints or diagnostic presence as authorization.
|
data/docs/LONG_PAYMENT.md
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
# Long Open Payment: explicit JPY / UTC monthly profile (1.6.0
|
|
1
|
+
# Long Open Payment: explicit JPY / UTC monthly profile (1.6.0)
|
|
2
|
+
|
|
3
|
+
Published on RubyGems; [exact distribution and validation](POST_RELEASE_160.md). Packaged preparation notes retain their historical scope.
|
|
2
4
|
|
|
3
5
|
`LongPayment` supports one signed Open Checkout and one signed Open Payment reused across approved UTC calendar months. Every Closed preserves its own Open's content `iat`/`exp`; each outer KB proof is fresh, bound to audience/nonce/original presentation. Content validity and permission to start execution are separate. This is a framework-independent Ruby SDK; no Rails, scheduler or payment processor is required or invoked.
|
|
4
6
|
|
data/docs/PAYMENT_ACCEPTANCE.md
CHANGED
|
@@ -2,6 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
[Verified public distribution](POST_RELEASE_150.md).
|
|
4
4
|
|
|
5
|
+
For a runnable application walkthrough, see [Ruby integration and restart recovery](RUBY_INTEGRATION.md)
|
|
6
|
+
([日本語](RUBY_INTEGRATION.ja.md)). It keeps application and mock processor state across
|
|
7
|
+
actual Ruby process termination. The older `examples/payment_acceptance.rb` reopens
|
|
8
|
+
a Store in the same process with an in-memory mock result; it is not a process-restart example.
|
|
9
|
+
|
|
5
10
|
This opt-in application-side coordinator separates three events: cryptographic verification, durable reservation of an approved business occurrence, and an external payment processor’s outcome. Existing1.x verifiers and their result meanings remain unchanged. The SDK does not call a processor, transfer funds or promise distributed exactly-once execution.
|
|
6
11
|
|
|
7
12
|
## Stable identity and protected approval
|
data/docs/PUBLIC_API.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Ruby SDK public API — 1.x
|
|
2
2
|
|
|
3
|
-
**Status: published 1.
|
|
3
|
+
**Status: published 1.6.0; the original 1.0.0 Checkout contract below is preserved.**
|
|
4
4
|
This document defines the 1.x contract for the existing Checkout APIs.
|
|
5
5
|
The 1.0.0 release preserves the 0.8.0 runtime behavior, API names and accepted
|
|
6
6
|
formats. Exact distribution identity and validation are in
|
|
@@ -229,3 +229,14 @@ For the explicit selective Checkout profile, Evidence `original_root_graph_closu
|
|
|
229
229
|
## 1.6.0 candidate: explicit long content / short proof
|
|
230
230
|
|
|
231
231
|
`LongPayment` opts into separate long complete Checkout/Payment profiles while preserving existing defaults. `issue_checkout_open/issue_checkout_closed/present_checkout` and `details/issue_open/issue_closed/present/verify` follow existing role-separated inputs. `approved_pair!`, `current_authority!` and `authority!` are protected-backend helpers; none enrolls consent by itself. `PaymentAcceptance::LongSQLiteStore` adds explicit schema3 authority/period state, `authorize_series!`, CAS `update_authority!/invalidate_authority!/replace_root!/revoke_root!`, inherited permanent `revoke_series!` and current `usage`. `Execution.valid_until` exposes the checked short start deadline, including on existing acceptance results; it does not make an external processor call atomic or revoke an already returned handle. See [exact profile, UTC windows, trust duties, migration and SDK differences](LONG_PAYMENT.md).
|
|
232
|
+
|
|
233
|
+
### Payment diagnostics (1.7.0 candidate)
|
|
234
|
+
|
|
235
|
+
`Payment::Verification#diagnostic` (including Selective/Long results),
|
|
236
|
+
`PaymentReceipt::Verification#diagnostic`, and `PaymentAcceptance::Result#diagnostic`
|
|
237
|
+
are optional immutable `Diagnostic` objects. `PaymentAcceptance::Service#start_with_diagnostic`
|
|
238
|
+
accepts the same keywords as `start`, runs the same single attempt, and returns an
|
|
239
|
+
immutable `StartResult` with `execution` (Execution or nil) and `diagnostic`.
|
|
240
|
+
Existing `start` retains Execution/nil, with unchanged exception normalization.
|
|
241
|
+
`Diagnostic.payment_flow(stage, reason)` restores a known catalog pair or nil;
|
|
242
|
+
this is not evidence or permission to execute. See [diagnostic limits](DIAGNOSTICS.md#payment-flow-170-candidate-not-published-by-this-change).
|