Skip to content

Allow web-based payment handlers to report back internal error #429

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

Draft
stephenmcgruer wants to merge 2 commits into
base: gh-pages
Choose a base branch
from
Draft

Allow web-based payment handlers to report back internal error #429

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
19de401
Allow web-based payment handlers to report back internal error
stephenmcgruer Mar 4, 2026
20f5584
Fixup
stephenmcgruer Mar 4, 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
112 changes: 71 additions & 41 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1334,8 +1334,21 @@ <h2>
"PaymentHandlerResponse">
<h2>
<dfn>PaymentHandlerResponse</dfn> dictionary
</h2>The PaymentHandlerResponse is conveyed using the following
dictionary:
</h2>
<p>
The user agent receives a successful response from the web-based
payment handler through resolution of the Promise provided to the
{{PaymentRequestEvent/respondWith}} function of the corresponding
{{PaymentRequestEvent}} interface. The application is expected to
resolve the Promise with a <a>PaymentHandlerResponse</a> instance
containing the payment response. In case of user cancellation or
error, the application may signal failure by rejecting the Promise.
</p>

<p>
The PaymentHandlerResponse is conveyed using the following dictionary:
</p>

<pre class="idl">
dictionary PaymentHandlerResponse {
DOMString methodName;
Expand Down Expand Up @@ -1365,29 +1378,6 @@ <h2>
method</a> specific message used by the merchant to process the
transaction and determine successful fund transfer.
</p>
<p>
The user agent receives a successful response from the web-based
payment handler through resolution of the Promise provided to the
{{PaymentRequestEvent/respondWith}} function of the corresponding
{{PaymentRequestEvent}} interface. The application is expected to
resolve the Promise with a <a>PaymentHandlerResponse</a> instance
containing the payment response. In case of user cancellation or
error, the application may signal failure by rejecting the Promise.
</p>
<p>
If the Promise is rejected, the user agent MUST run the
<dfn>payment app failure algorithm</dfn>. The exact details of this
algorithm are left to implementers. Acceptable behaviors include,
but are not limited to:
</p>
<ul>
<li>Letting the user try again, with the same web-based payment
handler or with a different one.
</li>
<li>Rejecting the Promise that was created by <a data-cite=
"payment-request#show-method">PaymentRequest.show()</a>.
</li>
</ul>
</section>
<section>
<h2>
Expand Down Expand Up @@ -1519,10 +1509,10 @@ <h2>
<li>Increment the |event|'s <a>pending promises count</a> by one.
</li>
<li>
<a>Upon rejection</a> of <var>handlerResponsePromise</var>:
<a>Upon rejection</a> of <var>handlerResponsePromise</var> with |reason|:
<ol>
<li>Run the <a>payment app failure algorithm</a> and terminate
these steps.
<li>Run the <a>payment app failure algorithm</a> with |reason|, and
terminate these steps.
</li>
</ol>
</li>
Expand All @@ -1531,8 +1521,8 @@ <h2>
<ol>
<li>Let <var>handlerResponse</var> be |value| <a>converted to an
IDL value</a> {{PaymentHandlerResponse}}. If this throws an
exception, run the <a>payment app failure algorithm</a> and
terminate these steps.
exception, run the <a>payment app failure algorithm</a> with an
{{"OperationError"}} {{DOMException}}, and terminate these steps.
</li>
<li>Validate that all required members exist in
<var>handlerResponse</var> and are well formed.
Expand All @@ -1542,7 +1532,8 @@ <h2>
present or not set to one of the values from
|event|.<a data-lt=
"PaymentRequestEvent.methodData">methodData</a>, run the <a>
payment app failure algorithm</a> and terminate these
payment app failure algorithm</a> with an
{{"OperationError"}} {{DOMException}}, and terminate these
steps.
</li>
<li>If <var>handlerResponse</var>.<a data-lt=
Expand All @@ -1557,43 +1548,48 @@ <h2>
<var>handlerResponse</var>.<a data-lt=
"PaymentHandlerResponse.shippingAddress">shippingAddress</a>
is not present, run the <a>payment app failure algorithm</a>
and terminate these steps.
with an {{"OperationError"}} {{DOMException}}, and terminate
these steps.
</li>
<li>If <var>shippingRequired</var> and
<var>handlerResponse</var>.<a data-lt=
"PaymentHandlerResponse.shippingOption">shippingOption</a> is
not present or not set to one of shipping options identifiers
from |event|.<a data-lt=
"PaymentRequestEvent.shippingOptions">shippingOptions</a>,
run the <a>payment app failure algorithm</a> and terminate
these steps.
run the <a>payment app failure algorithm</a> with an
{{"OperationError"}} {{DOMException}}, and terminate these
steps.
</li>
<li>Let <var>payerNameRequired</var> be the <a data-cite=
"payment-request#dom-paymentoptions-requestpayername">requestPayerName</a>
value of the associated PaymentRequest's
<a>paymentOptions</a>. If <var>payerNameRequired</var> and
<var>handlerResponse</var>.<a data-lt=
"PaymentHandlerResponse.payerName">payerName</a> is not
present, run the <a>payment app failure algorithm</a> and
terminate these steps.
present, run the <a>payment app failure algorithm</a> with an
{{"OperationError"}} {{DOMException}}, and terminate these
steps.
</li>
<li>Let <var>payerEmailRequired</var> be the <a data-cite=
"payment-request#dom-paymentoptions-requestpayeremail">requestPayerEmail</a>
value of the associated PaymentRequest's
<a>paymentOptions</a>. If <var>payerEmailRequired</var> and
<var>handlerResponse</var>.<a data-lt=
"PaymentHandlerResponse.payerEmail">payerEmail</a> is not
present, run the <a>payment app failure algorithm</a> and
terminate these steps.
present, run the <a>payment app failure algorithm</a> with an
{{"OperationError"}} {{DOMException}}, and terminate these
steps.
</li>
<li>Let <var>payerPhoneRequired</var> be the <a data-cite=
"payment-request#dom-paymentoptions-requestpayerphone">requestPayerPhone</a>
value of the associated PaymentRequest's
<a>paymentOptions</a>. If <var>payerPhoneRequired</var> and
<var>handlerResponse</var>.<a data-lt=
"PaymentHandlerResponse.payerPhone">payerPhone</a> is not
present, run the <a>payment app failure algorithm</a> and
terminate these steps.
present, run the <a>payment app failure algorithm</a> with an
{{"OperationError"}} {{DOMException}}, and terminate these
steps.
</li>
</ol>
</li>
Expand Down Expand Up @@ -1629,7 +1625,8 @@ <h2>
</ol>
</li>
<li>If any exception occurs in the above step, then run the
<a>payment app failure algorithm</a> and terminate these
<a>payment app failure algorithm</a> with an
{{"OperationError"}} {{DOMException}}, and terminate these
steps.
</li>
<li>Assign <var>methodName</var> to associated
Expand Down Expand Up @@ -1737,6 +1734,39 @@ <h2>
reconciliation after network or other failures.
</p>
</section>
<section>
<h2>
<dfn>Payment App Failure Algorithm</dfn>
</h2>
<p>
When this algorithm is invoked with |reason|, the user agent MUST run
the following steps:
</p>
<ol class="algorithm">
<li>
If |reason| is an {{"OperationError"}} {{DOMException}}, then run
the <a>Payment handler indicates an internal error algorithm</a> as
Copy link
Member

@romandev romandev Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: Might need a data-cite import here? The link doesn't seem to resolve in the preview.

defined in [[!payment-request]].
</li>
<li>
Otherwise, run the <a>user aborts the payment request algorithm</a>
Copy link
Member

@romandev romandev Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ditto

as defined in [[!payment-request]].

<p class="note">
Previous versions of this specification did not define what
happened when the <a>payment app failure algorithm</a> was
invoked. In practice, implementors acted as if the
<a>user aborts the payment request algorithm</a> was run.

To maintain as much backwards compatibility as possible, while
still introducing a way for web-based payment handlers to indicate
internal error, this specification now maps all reason values other
than a {{"OperationError"}} {{DOMException}} to user abort. Future
versions of this specification may add additional handled values.
</p>
</li>
</ol>
</section>
</section>
</section>
<section id="security">
Expand Down
Loading