PaymentSheetPrompt Class

A payment request shown by the payment sheet, given to UserAgentUIBackend.ShowPaymentSheetAsync (and to UserAgentUIBackend.RetryPaymentAsync and UserAgentUIBackend.CompletePaymentAsync for the same request): the supported payment methods, the details and the options of the request. The backend reports the interactions of the user with the change methods, which can be called from any thread while the sheet is shown: they fire the events of the page, and complete with the details updated by the page (updateWith()), or at once when the page does not update them. Only one change can be pending at a time.

public sealed class PaymentSheetPrompt : UserAgentPrompt

Remarks

A payment method whose payment handler shows its own user interface instead of the sheet (e.g. the transaction dialog of Secure Payment Confirmation) uses the same request, and the same response (PaymentSheetResponse).

Inheritance
UserAgentPrompt PaymentSheetPrompt

Properties

NameDescription
DetailsGets the current details of the request (updated by the page).
ErrorsGets the errors to show to the user (the last update of the page, or the errors of retry()), or null.
IsUpdatingGets whether the page is updating the details: the user cannot accept the payment until the update completes (see PaymentSheetPrompt.WaitForUpdateAsync).
MethodsGets the payment methods of the request that the user agent supports (UserAgentUIBackend.HasPaymentHandlerAsync), in the order of the request.
OptionsGets the information that the request collects (payer details, shipping address).
ResponseGets the response accepted by the user, or null before the payment is accepted (see UserAgentUIBackend.RetryPaymentAsync).
ShippingAddressGets the last full shipping address given to PaymentSheetPrompt.ChangeShippingAddressAsync, or null.
ShippingOptionGets the identifier of the selected shipping option, or null: the option selected by the page (PaymentShippingOption.Selected), or the last option given to PaymentSheetPrompt.ChangeShippingOptionAsync.

Gets the current details of the request (updated by the page).

public PaymentSheetDetails Details { get; }

Property value

PaymentSheetDetails

Gets the errors to show to the user (the last update of the page, or the errors of retry()), or null.

public PaymentSheetErrors? Errors { get; }

Property value

PaymentSheetErrors?

Gets whether the page is updating the details: the user cannot accept the payment until the update completes (see PaymentSheetPrompt.WaitForUpdateAsync).

public bool IsUpdating { get; }

Property value

bool

Gets the payment methods of the request that the user agent supports (UserAgentUIBackend.HasPaymentHandlerAsync), in the order of the request.

public IReadOnlyList<PaymentSheetMethod> Methods { get; }

Gets the information that the request collects (payer details, shipping address).

public PaymentOptions Options { get; }

Property value

PaymentOptions

Gets the response accepted by the user, or null before the payment is accepted (see UserAgentUIBackend.RetryPaymentAsync).

public PaymentSheetResponse? Response { get; }

Property value

PaymentSheetResponse?

ShippingAddress

PaymentSheetPrompt.cs

Gets the last full shipping address given to PaymentSheetPrompt.ChangeShippingAddressAsync, or null.

public ContactAddress? ShippingAddress { get; }

Property value

ContactAddress?

ShippingOption

PaymentSheetPrompt.cs

Gets the identifier of the selected shipping option, or null: the option selected by the page (PaymentShippingOption.Selected), or the last option given to PaymentSheetPrompt.ChangeShippingOptionAsync.

public string? ShippingOption { get; }

Property value

string?

Methods

NameDescription
ChangePayerDetailsAsync(string?, string?, string?, CancellationToken)Reports that the user changed the payer details while retrying a payment (https://w3c.github.io/payment-request/#payer-detail-changed-algorithm): the requested details of the PaymentResponse are updated and the page receives a payerdetailchange event. A null argument is a detail that did not change. Returns the details, once updated. The task fails with an InvalidOperationException when the payment was not accepted, is not being retried, or another change is pending, and is canceled when the sheet is closed.
ChangePaymentMethodAsync(string, string?, CancellationToken)Reports that the user changed the payment method in the payment handler (https://w3c.github.io/payment-request/#payment-method-changed-algorithm): the page receives a paymentmethodchange event (e.g. with the redacted billing address of the card, to compute the taxes), and can update the details. Returns the details, once updated. The task fails with an InvalidOperationException when the request is not interactive or another change is pending, and is canceled when the sheet is closed.
ChangeShippingAddressAsync(ContactAddress, CancellationToken)Reports that the user chose a shipping address (https://w3c.github.io/payment-request/#shipping-address-changed-algorithm): the page receives the address without the members that identify the recipient (organization, phone number, recipient, address line) in a shippingaddresschange event, and can update the details (e.g. the shipping options for the address). Returns the details, once updated. The task fails with an InvalidOperationException when the request does not request shipping, is not interactive, or another change is pending, and is canceled when the sheet is closed.
ChangeShippingOptionAsync(string, CancellationToken)Reports that the user chose a shipping option (https://w3c.github.io/payment-request/#shipping-option-changed-algorithm): the page receives a shippingoptionchange event, and can update the details (e.g. the total). Returns the details, once updated. The task fails with an InvalidOperationException when the request does not request shipping, the option is not one of the shipping options of the details, the request is not interactive, or another change is pending, and is canceled when the sheet is closed.
WaitForUpdateAsync(CancellationToken)Waits until the details are not being updated (e.g. the promise given to show() is settled), and returns them. The task is canceled when the sheet is closed.

ChangePayerDetailsAsync(string?, string?, string?, CancellationToken)

PaymentSheetPrompt.cs

Reports that the user changed the payer details while retrying a payment (https://w3c.github.io/payment-request/#payer-detail-changed-algorithm): the requested details of the PaymentResponse are updated and the page receives a payerdetailchange event. A null argument is a detail that did not change. Returns the details, once updated. The task fails with an InvalidOperationException when the payment was not accepted, is not being retried, or another change is pending, and is canceled when the sheet is closed.

public Task<PaymentSheetDetails> ChangePayerDetailsAsync(string? payerName, string? payerEmail, string? payerPhone, CancellationToken cancellationToken = default)

Parameters

payerName string?
The new name of the payer, or null.
payerEmail string?
The new email address of the payer, or null.
payerPhone string?
The new phone number of the payer, or null.
cancellationToken CancellationToken
A token to stop waiting.

Returns

Task<PaymentSheetDetails>

ChangePaymentMethodAsync(string, string?, CancellationToken)

PaymentSheetPrompt.cs

Reports that the user changed the payment method in the payment handler (https://w3c.github.io/payment-request/#payment-method-changed-algorithm): the page receives a paymentmethodchange event (e.g. with the redacted billing address of the card, to compute the taxes), and can update the details. Returns the details, once updated. The task fails with an InvalidOperationException when the request is not interactive or another change is pending, and is canceled when the sheet is closed.

public Task<PaymentSheetDetails> ChangePaymentMethodAsync(string methodName, string? methodDetails, CancellationToken cancellationToken = default)

Parameters

methodName string
The payment method identifier of the payment handler.
methodDetails string?
The data of the payment method serialized to JSON (an object), or null.
cancellationToken CancellationToken
A token to stop waiting.

Returns

Task<PaymentSheetDetails>

ChangeShippingAddressAsync(ContactAddress, CancellationToken)

PaymentSheetPrompt.cs

Reports that the user chose a shipping address (https://w3c.github.io/payment-request/#shipping-address-changed-algorithm): the page receives the address without the members that identify the recipient (organization, phone number, recipient, address line) in a shippingaddresschange event, and can update the details (e.g. the shipping options for the address). Returns the details, once updated. The task fails with an InvalidOperationException when the request does not request shipping, is not interactive, or another change is pending, and is canceled when the sheet is closed.

public Task<PaymentSheetDetails> ChangeShippingAddressAsync(ContactAddress address, CancellationToken cancellationToken = default)

Parameters

address ContactAddress
The full address chosen by the user.
cancellationToken CancellationToken
A token to stop waiting.

Returns

Task<PaymentSheetDetails>

ChangeShippingOptionAsync(string, CancellationToken)

PaymentSheetPrompt.cs

Reports that the user chose a shipping option (https://w3c.github.io/payment-request/#shipping-option-changed-algorithm): the page receives a shippingoptionchange event, and can update the details (e.g. the total). Returns the details, once updated. The task fails with an InvalidOperationException when the request does not request shipping, the option is not one of the shipping options of the details, the request is not interactive, or another change is pending, and is canceled when the sheet is closed.

public Task<PaymentSheetDetails> ChangeShippingOptionAsync(string shippingOptionId, CancellationToken cancellationToken = default)

Parameters

shippingOptionId string
The identifier of the option.
cancellationToken CancellationToken
A token to stop waiting.

Returns

Task<PaymentSheetDetails>

WaitForUpdateAsync(CancellationToken)

PaymentSheetPrompt.cs

Waits until the details are not being updated (e.g. the promise given to show() is settled), and returns them. The task is canceled when the sheet is closed.

public Task<PaymentSheetDetails> WaitForUpdateAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken
A token to stop waiting.

Returns

Task<PaymentSheetDetails>