Skip to content

Allow payment handlers to report back errors via Payment Request API #1050

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcoscaceres merged 5 commits into from
Mar 3, 2026
Merged

Allow payment handlers to report back errors via Payment Request API #1050

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c43c83e
Allow payment handlers to report back errors via Payment Request API
stephenmcgruer Nov 13, 2025
22f0f1e
Address reviewer comments; map |error| to an appropriate DOMException
stephenmcgruer Jan 30, 2026
509454d
Variant where the DOMException comes directly from the payment handler
stephenmcgruer Jan 30, 2026
b8d1ff0
Variant where we use a generic JavaScript value
stephenmcgruer Jan 30, 2026
236c39b
use OperationError instead
marcoscaceres Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 78 additions & 9 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1318,10 +1318,11 @@ <h2>
</p>
</aside>
<p>
The |acceptPromise| will later be resolved or rejected by either
the <a>user accepts the payment request algorithm</a> or the
<a>user aborts the payment request algorithm</a>, which are
triggered through interaction with the user interface.
The |acceptPromise| will later be resolved or rejected by the
<a>user accepts the payment request algorithm</a>, or the <a>user
aborts the payment request algorithm</a> (which are triggered
through interaction with the user interface), or the <a>payment
handler indicates an internal error algorithm</a>.
</p>
<p data-tests="rejects_if_not_active.https.html">
If |document| stops being [=Document/fully active=] while the
Expand Down Expand Up @@ -2600,9 +2601,10 @@ <h2>
<li>Return |retryPromise|.
<p class="note">
The |retryPromise| will later be resolved by the <a>user accepts
the payment request algorithm</a>, or rejected by either the
<a>user aborts the payment request algorithm</a> or <a>abort the
update</a>.
the payment request algorithm</a>, or rejected by the <a>user
aborts the payment request algorithm</a>, or <a>abort the
update</a>, or the <a>payment handler indicates an internal error
algorithm</a>.
</p>
</li>
</ol>
Expand Down Expand Up @@ -3947,6 +3949,73 @@ <h2>
</li>
</ol>
</section>
<section>
<h2>
Payment handler indicates an internal error algorithm
</h2>
<p>
The <dfn>payment handler indicates an internal error algorithm</dfn>
runs when the <a>payment handler</a> that the user has selected
encounters an internal error that prevents it from completing the
payment. This can occur due to reasons such as the operating system
terminating the payment handler (e.g., due to memory pressure), or
the payment handler itself encountering an unrecoverable error.
</p>
<ol class="algorithm">
<li>
<a>Queue a task</a> on the <a>user interaction task source</a> to
perform the following steps:
<ol>
<li>Let |request:PaymentRequest| be the {{PaymentRequest}} object
that the user is interacting with.
</li>
<li>If |request|.{{PaymentRequest/[[state]]}} is not
"[=PaymentRequest/interactive=]", then terminate this algorithm
and take no further action.
</li>
<li>Let |error| be an {{"OperationError"}} {{DOMException}}.
</li>
<li>Set |request|.{{PaymentRequest/[[state]]}} to
"[=PaymentRequest/closed=]".
</li>
<li>Set |request|'s <a>payment-relevant browsing context</a>'s
<a>payment request is showing</a> boolean to false.
</li>
<li>Let |response:PaymentResponse| be
|request|.{{PaymentRequest/[[response]]}}.
</li>
<li>If |response| is not null:
<ol>
<li>Set |response|.{{PaymentResponse/[[complete]]}} to true.
</li>
<li>Assert: |response|.{{PaymentResponse/[[retryPromise]]}}
is not null.
</li>
<li>Reject |response|.{{PaymentResponse/[[retryPromise]]}}
with |error|.
</li>
</ol>
</li>
<li>Otherwise, reject
|request|.{{PaymentRequest/[[acceptPromise]]}} with |error|.
</li>
<li>Optionally, show a generic error message to the user
indicating that the payment could not be completed.
</li>
<li>Optionally, log detailed error information to the developer
console for debugging purposes.
</li>
<li>Abort the current user interaction and close down any
remaining user interface.
</li>
</ol>
</li>
</ol>
<p class="note">
The {{"OperationError"}} type allows merchants to distinguish payment
handler errors from user cancellation (which uses {{"AbortError"}}).
</p>
</section>
<section>
<h2>
Update a <code>PaymentRequest</code>'s details algorithm
Expand Down Expand Up @@ -4256,8 +4325,8 @@ <h2>
{{PaymentRequest}} |request| and <a>exception</a> |exception|:
</p>
<ol class="algorithm">
<li>Optionally, show an error message to the user when letting them
know an error has occurred.
<li>Optionally, inform the developer via the console that an error
occurred while updating the payment request.
</li>
<li>Abort the current user interaction and close down any remaining
user interface.
Expand Down