[next-devin]

Hold: merge together with NextCommerceCo/docs#73, which adds the #smart-mode anchor this guide links to.

Changes

• Bankcard guide, 3D Secure: a gateway is 3DS2-enabled when three_ds_mode is smart or always. New Smart mode gateways section: always send payment_return_url to a smart gateway, and handle both a payment_complete_url (3DS used) and a directly created order (3DS skipped, nothing posted to payment_return_url).

The Admin API spec changes that were in this PR are gone: main now carries the regenerated specs, which already include three_ds_mode.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	developer-docs	7f2b333	Commit Preview URL Branch Preview URL	Oct 28 2026, 10:30 AM

[kilo-code-bot]

SUGGESTION: The two sentences in the callout are mashed together without a conjunction. Consider connecting them for readability, e.g. "Your store must have a 3DS2-enabled gateway to process 3DS2 transactions; a gateway is 3DS2-enabled when its three_ds_mode is smart or always."

[next-devin]

Leaving as two sentences: each states one fact, and joining them with a semicolon doesn't read more clearly.

🤖 Addressed by Claude Code

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (1 file)

• content/docs/admin-api/guides/payment-methods/bankcard.mdx

Notes

• Incremental scope: af776e48..7f2b333 changes one line of bankcard.mdx (line 478). The net PR diff against main (997ad43) still touches only this file; the Admin API spec edits live on main.
• The changed bullet no longer prescribes a retry. Retry eligibility (soft declines 2000 range "may potentially be successful if retried", hard declines 3000/4000 "not recommended to reattempt") and the payment_method.card_token reattempt affordance are documented in the linked ## Transaction response codes section, which the bullet points to, so the skipped-3DS branch no longer contradicts the section it links.
• Verified while reading: #transaction-response-codes resolves to the unique ## Transaction response codes heading (heading slugs collected with github-slugger and checked by scripts/validate-links.mjs), so the internal link passes CI; the check-markup rules hold for the ### Smart mode gateways heading (h2 → h3, no bold in heading) and both rewritten bullets; the three_ds_mode enum in the regenerated public/api/admin/2024-04-01.yaml (off/smart/always) matches the callout's definition of a 3DS2-enabled gateway, and the smart/skipped wording is consistent with payment_return_url being sent on every order (line 475) and with the "When 3DS is used" scoping of the POST (line 486).
• Out of scope, not counted as a finding: the regenerated spec on main has mixed enum quoting ('off' quoted, smart/always unquoted) at public/api/admin/2024-04-01.yaml:6623. The spec files are no longer in this PR's diff, so the quoting fix this PR originally carried is not part of the merge result.
• Not verified: the external #smart-mode anchor and the platform behavior for the skipped branch were not re-checked against docs.nextcommerce.com (outbound fetches are not permitted in this session), so this review rests on the guide's own text.
• Merge remains gated on the companion PR Document 3DS Mode and Smart 3DS docs#73 (which adds the #smart-mode anchor) and on the 3DS Mode release, as stated in the PR body.

Previous Review Summaries (5 snapshots, latest commit af776e4)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit af776e4)

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
content/docs/admin-api/guides/payment-methods/bankcard.mdx	478	The new retry instruction is unconditional, but the section it links to only makes soft declines (2000 range) retryable and states that hard declines (3000/4000 range) "are not recommended to reattempt", so an integrator that retries every failure re-charges cards that can never succeed (3012 Duplicate Transaction / Velocity Filter, 3016 3DS Authentication Failed, 3017 Blocked by Block List); the token is also returned at payment_method.card_token, not as a top-level card_token

Files Reviewed (1 file)

• content/docs/admin-api/guides/payment-methods/bankcard.mdx - 1 issue

Notes

• Incremental scope: 3efa849..af776e48 changes two lines of bankcard.mdx (477, 478). The net PR diff against main still touches only this file; the Admin API spec edits are in main.
• Both previous findings are resolved: line 477 now names the discriminator ("the response has a payment_complete_url instead of an order"), and line 478 replaces "the response is the final result" with "the outcome comes back in the response" plus a link to the failure payload and its retry token. The remaining warning is new to this revision.
• Verified while reading: #transaction-response-codes resolves to the unique ## Transaction response codes heading (heading slugs are collected with github-slugger and checked by scripts/validate-links.mjs), so the new internal link passes CI; the check-markup rules hold for the added ### Smart mode gateways heading and the two rewritten bullets; the three_ds_mode enum in the regenerated public/api/admin/2024-04-01.yaml (off/smart/always) matches the callout's definition of a 3DS2-enabled gateway.
• Out of scope, not counted as a finding: the regenerated spec on main has mixed enum quoting ('off' quoted, smart/always unquoted) at public/api/admin/2024-04-01.yaml:6623. The spec files are no longer in this PR's diff, so the quoting fix this PR originally carried is not part of the merge result.
• Not verified: the external #smart-mode anchor and the platform behavior for the skipped branch were not re-checked against docs.nextcommerce.com (outbound fetches are not permitted in this session), so the warning above rests on the guide's own text.

Fix these issues in Kilo Cloud

Previous review (commit 3efa849)

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	2

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
content/docs/admin-api/guides/payment-methods/bankcard.mdx	475	"handle both responses" never names the discriminator between the 3DS response (reference_transaction_id + payment_complete_url, not an order) and the skipped response (the created order), so an integration that treats every create-order response as the order breaks on the 3DS path
content/docs/admin-api/guides/payment-methods/bankcard.mdx	478	"the response is the final result" contradicts the retry affordance documented for a failed payment (payment_method.card_token so the charge can be reattempted), and the skipped branch is the only place that failure is ever delivered because nothing is posted to payment_return_url

Files Reviewed (1 file)

• content/docs/admin-api/guides/payment-methods/bankcard.mdx - 2 issues

Notes

• Incremental scope: 7ff6f1b..3efa849 changes three lines of bankcard.mdx (475, 478, 486). The PR's cumulative diff against main now touches only this file; the Admin API spec edits were dropped because main carries the regenerated specs.
• Both previous findings are resolved: line 486 now scopes the POST to "When 3DS is used", and line 475 states the reason payment_return_url is still required ("You can't know in advance which"). The remaining unconditional POST statements are in the redirect-flow diagram and the shared RedirectPaymentStep3 snippet, which are reached only from the 3DS branch ("Continue with the redirect flow below").
• Verified while reading: the new #transaction-response-codes fragment resolves to the unique ## Transaction response codes heading and is checked by scripts/validate-links.mjs (heading slugs are collected with github-slugger), so the new internal link passes CI. The three_ds_mode enum in the regenerated public/api/admin/2024-04-01.yaml (off/smart/always) matches the callout's definition of a 3DS2-enabled gateway.
• Not verified: the external #smart-mode anchor and the platform behavior for the skipped branch were not re-checked against docs.nextcommerce.com (outbound fetches are not permitted in this session), so the two findings above rest on the guide's own text only.

Fix these issues in Kilo Cloud

Previous review (commit 7ff6f1b)

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	1

Issue Details (click to expand)

WARNING

File	Line	Issue
content/docs/admin-api/guides/payment-methods/bankcard.mdx	478	The new "Nothing is posted to payment_return_url" contradicts the rest of the 3DS section, which still promises the POST unconditionally ("Create the order" at line 486, the redirect-flow diagram, and the "Receive order data" step), and the bullet does not say where the order outcome comes from in the skipped branch

SUGGESTION

File	Line	Issue
content/docs/admin-api/guides/payment-methods/bankcard.mdx	478	The reason payment_return_url is still required when 3DS is skipped is not stated, so the bullet reads as contradicting "Always send payment_return_url" two lines above

Files Reviewed (4 files)

• content/docs/admin-api/guides/payment-methods/bankcard.mdx - 2 issues
• public/api/admin/2024-04-01.yaml - 0 issues
• public/api/admin/2023-02-10.yaml - 0 issues
• public/api/admin/unstable.yaml - 0 issues

Notes

• Incremental scope: 7ff6f1b..f4c4c1f changes one line, bankcard.mdx:478, which now states that nothing is posted to payment_return_url when Smart mode skips 3DS.
• The previous WARNING at line 478 (does the platform still POST the final order data to payment_return_url when 3DS is skipped, and which copy is authoritative) is answered by the new sentence; one delivery per order removes the double-processing risk. The remaining problem is that the answer now conflicts with the unchanged text further down the same section, which is reported above.
• The previous SUGGESTION at line 475 (the #smart-mode anchor on the merchant site is not validated by CI) is not carried forward: the author confirmed the heading is "### Smart Mode", which slugifies to smart-mode, in the companion docs PR (Document 3DS Mode and Smart 3DS docs#73). External anchors remain unvalidated by CI, which is a repo-wide limitation of scripts/validate-links.mjs rather than a defect in this PR.
• The three spec files are unchanged since the previous review and were re-verified rather than re-analyzed: enum values are single-quoted in every copy of three_ds_mode, readOnly: true remains only on the REST PaymentGateway.enable_3ds2, and the derived-field description matches the guide's callout.
• The spec edits are still hand-written against a platform release while public/api/admin/*.yaml is generated by tools/update_api_docs.py (see .claude/rules/admin-api-docs.md), so regeneration may overwrite them unless the platform output already matches.

Fix these issues in Kilo Cloud

Previous review (commit a37f5d8)

Status: No Issues Found | Recommendation: Merge

All five findings from the previous review at cf8e77b were verified as resolved in the current code:

• bankcard.mdx:477 now states payment_return_url is required on every order to a smart gateway, including orders that skip 3DS.
• Enum values are now single-quoted consistently ('off', 'smart', 'always') in all three specs and both webhook schema copies each.
• readOnly: true was dropped from the webhook schema copies of enable_3ds2 (which tools/webhooks.py strips) and retained only on the REST PaymentGateway schema.

Files Reviewed (4 files)

• content/docs/admin-api/guides/payment-methods/bankcard.mdx
• public/api/admin/2024-04-01.yaml
• public/api/admin/2023-02-10.yaml
• public/api/admin/unstable.yaml

Notes

• .claude/rules was not present in this repository, so no additional domain rules were applied.
• Merge remains gated on the 3DS Mode release being live in production, as stated in the PR body. If the specs are regenerated from the platform after deploy, prefer the generated output (which will include x-spec-enum-id) over these hand-written hunks.

Previous review (commit cf8e77b)

Status: 6 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	5
SUGGESTION	1

Issue Details (click to expand)

WARNING

File	Line	Issue
content/docs/admin-api/guides/payment-methods/bankcard.mdx	477	payment_return_url guidance on smart gateways is ambiguous about whether it is required when 3DS is skipped
public/api/admin/2024-04-01.yaml	6618	Enum values use inconsistent quoting ('off' quoted, smart and always unquoted)
public/api/admin/2024-04-01.yaml	6561	readOnly: true on enable_3ds2 in webhook schemas is meaningless and will be stripped by the spec generator on next regeneration
public/api/admin/2023-02-10.yaml	6295	Enum value quoting inconsistency (legacy spec)
public/api/admin/unstable.yaml	6568	Enum value quoting inconsistency (unstable spec)

SUGGESTION

File	Line	Issue
content/docs/admin-api/guides/payment-methods/bankcard.mdx	470	Two-sentence callout reads better with a connecting conjunction

Files Reviewed (4 files)

• content/docs/admin-api/guides/payment-methods/bankcard.mdx - 2 issues
• public/api/admin/2024-04-01.yaml - 2 issues
• public/api/admin/2023-02-10.yaml - 1 issue
• public/api/admin/unstable.yaml - 1 issue

Fix these issues in Kilo Cloud

---

_{Reviewed by minimax-m3.1-flash · Input: 152.5K · Output: 95.9K · Cached: 1.8M}