---
title: Frontend API reference
description: >-
  Reference documentation for the Shop Pay Wallet API frontend JavaScript types,
  interfaces, and events.
source_url:
  html: 'https://shopify.dev/docs/api/commerce-components/pay/frontend-api-reference'
  md: >-
    https://shopify.dev/docs/api/commerce-components/pay/frontend-api-reference.md
---

# Frontend API reference

***

## `ShopPayPaymentRequestSession`

Shopify emits these events as the user interacts with Shop Pay. Listen for the events, and respond accordingly. For examples of attaching event listeners, refer to the [sessions and events](https://shopify.dev/docs/api/commerce-components/pay/sessions-and-events#attach-event-listeners) documentation.

The following interface defines the events and completion methods available on a `ShopPayPaymentRequestSession`:

```javascript
interface ShopPayPaymentRequestSession {
  // Requires a server call
  sessionrequested: EventHandler<ShopPaySessionRequestedEvent>;
  completeSessionRequest(sessionRequestResponse: {token, checkoutUrl, sourceIdentifier} & ShopPayPaymentRequestUpdate): void;


  // Dispatched as the user changes various fields
  deliverymethodtypechanged: EventHandler<DeliveryMethodTypeChangedEvent>;
  completeDeliveryMethodTypeChange(update: ShopPayPaymentRequestUpdate): void;


  pickuplocationchanged: EventHandler<PickupLocationChangedEvent>;
  completePickupLocationChange(update: ShopPayPaymentRequestUpdate);


  pickuplocationfilterchanged: EventHandler<PickupLocationFilterChangedEvent>;
  completePickupLocationFilterChange(update: ShopPayPaymentRequestUpdate);


  shippingaddresschanged: EventHandler<ShopPayShippingAddressChangedEvent>;
  completeShippingAddressChange(update: ShopPayPaymentRequestUpdate): void;


  deliverymethodchanged: EventHandler<ShopPayDeliveryMethodChangedEvent>;
  completeDeliveryMethodChange(update: ShopPayPaymentRequestUpdate): void;


  discountcodechanged: EventHandler<ShopPayDiscountCodeChangedEvent>;
  completeDiscountCodeChange(update: ShopPayPaymentRequestUpdate): void;


  // Dispatched once a customer clicks the Pay button in order to confirm
  // the payment should be processed
  paymentconfirmationrequested: EventHandler<ShopPayPaymentConfirmationRequestedEvent>;
  completePaymentConfirmationRequest(update: ShopPayPaymentRequestUpdate): void;


  // Dispatched after a payment processing attempt
  paymentcomplete: EventHandler<ShopPayPaymentCompleteEvent>;


  // Dispatched when a payment attempt has failed
  paymentattemptfailed: EventHandler<ShopPayPaymentAttemptFailedEvent>;


  // Dispatched after the checkout window is closed
  windowclosed: EventHandler<WindowClosedEvent>;


  // Cancels the session
  close(): void;
}


interface ShopPayPaymentRequestUpdate {
  updatedPaymentRequest?: ShopPayPaymentRequest;
  errors?: ShopPayUserError[];
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `sessionrequested` | Event handler | This event handler is triggered when a new Shop Pay session is requested. The listener must make a server-to-server call from your backend to Shop Pay's servers, and then call `completeSessionRequest()` from your frontend with the response. |
| `completeSessionRequest` | `(args: {token: string, checkoutUrl: string, sourceIdentifier: string} & ShopPayPaymentRequestUpdate) => void` | This function completes the session request. It must be invoked with the `token`, `checkoutUrl`, and `sourceIdentifier` from response of the `ShopPayPaymentRequestSessionCreate` mutation. You can optionally include an updated payment request. |
| `deliverymethodtypechanged` | Event handler | This event handler is triggered when a customer changes their preferred delivery method. When this event is triggered, `completeDeliveryMethodTypeChange()` must be called with the updated payment request. |
| `completeDeliveryMethodTypeChange` | `(args: ShopPayPaymentRequestUpdate) => void` | This function must be called when the delivery method type changes. |
| `pickuplocationchanged` | Event handler | This event handler is triggered when a customer changes the selected pickup location. `completePickupLocationChange()` must be called with the updated payment request. |
| `completePickupLocationChange` | `(args: ShopPayPaymentRequestUpdate) => void)` | This function must be called when the selected pickup location changes. |
| `pickuplocationfilterchanged` | Event handler | This event handler is triggered when the pickup location filter changes. `completePickupLocationFilterChange()` must be called with an updated payment request containing a filtered set of pickup locations. |
| `completePickupLocationFilterChange` | `(args: ShopPayPaymentRequestUpdate) => void` | This function must be called when the pickup location filter changes. |
| `shippingaddresschanged` | Event handler | This event handler is triggered when a customer changes their preferred shipping address. When this event is triggered, `completeShippingAddressChange()` must be called with the updated payment request. |
| `completeShippingAddressChange` | `(args: ShopPayPaymentRequestUpdate) => void` | This function must be called when the shipping address changes. |
| `deliverymethodchanged` | Event handler | This event handler is triggered when a customer changes their preferred delivery method. When this event is triggered, `completeDeliveryMethodChange()` must be called with the updated payment request. |
| `completeDeliveryMethodChange` | `(args: ShopPayPaymentRequestUpdate) => void` | This function must be called with the updated payment request. |
| `discountcodechanged` | Event handler | This event handler is triggered when the discount code changes. When this event is triggered, `completeDiscountCodeChange()` must be called with the updated payment request. |
| `completeDiscountCodeChange` | `(args: ShopPayPaymentRequestUpdate) => void` | This function updates the payment request after discount codes are changed by providing an updated payment request. |
| `paymentconfirmationrequested` | Event handler | This event handler is triggered after a customer clicks the Pay button. The event includes the customer's `billingAddress` as a `ShopPayContactField` object. The `ShopPayPaymentRequestSessionSubmit` mutation must be invoked, then `completePaymentConfirmationRequest()` must be called afterwards. |
| `completePaymentConfirmationRequest` | `(args: ShopPayPaymentRequestUpdate) => void` | This function is used to confirm that Shopify must proceed with payment. If there are any errors, they must be provided in the `errors` field. If `updatedPaymentRequest` is given, `errors` must also be given. |
| `paymentcomplete` | Event handler | This event handler is triggered after Shopify successfully processes a payment. The event payload has a `.processingStatus` field of type `ShopPayPaymentRequestReceiptCompleted`. |
| `paymentattemptfailed` | Event handler | This event handler is triggered when a payment attempt has failed. The event payload has a `.error` field with details about why the payment attempt failed. |
| `close` | `() => void` | This function cancels the session and closes the popup. |
| `windowclosed` | Event handler | This event handler is triggered after the checkout window is closed. |

***

## `ShopPayPaymentRequest`

A payment request is the primary means of communication between your system and Shop Pay.

![Shop Pay Wallet properties](https://shopify.dev/assets/assets/images/api/commerce-components/pay/line-items-DDW_fO23.png)

**Note:**

The frontend `ShopPayPaymentRequest`, used to display the payment request in the Shop Pay popup, is different from the backend `ShopPayPaymentRequestInput`, used in [mutations](https://shopify.dev/docs/api/storefront/latest/input-objects/ShopPayPaymentRequestInput) as part of payment processing. Make sure to use the correct type for each context.

The following interface defines the properties of a `ShopPayPaymentRequest`:

```typescript
interface ShopPayPaymentRequest {
  supportedDeliveryMethodTypes?: ShopPayDeliveryMethodType[];
  selectedDeliveryMethodType?: ShopPayDeliveryMethodType;
  pickupLocations?: ShopPayPickupLocation[];
  paymentMethod?: string;
  discountCodes: string[];
  lineItems: ShopPayLineItem[];
  shippingLines: ShopPayShippingLine[];
  deliveryMethods: ShopPayDeliveryMethod[]
  locale: ShopPayLocale;
  presentmentCurrency: ShopPayCurrencyCode;
  subtotal: ShopPayMoney;
  discounts?: ShopPayDiscountLine[];
  totalShippingPrice?: ShopPayTotalShippingPrice;
  totalTax?: ShopPayMoney;
  total: ShopPayMoney;
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `supportedDeliveryMethodTypes` optional | `ShopPayDeliveryMethodType[]` | The supported delivery method types for this checkout. Defaults to `["SHIPPING"]`. |
| `selectedDeliveryMethodType` optional | `ShopPayDeliveryMethodType` | The selected delivery method type. |
| `pickupLocations` optional | `ShopPayPickupLocation[]` | The available pickup locations when the selected delivery method type is `PICKUP`. |
| `paymentMethod` optional | `string` | The one-time-use payment token, included only in the `paymentconfirmationrequested` event. |
| `discountCodes` required | `string[]` | All applied discount codes, displayed under the discount code field as tags. |
| `lineItems` required | `ShopPayLineItem[]` | The line items to display. |
| `shippingLines` required | `ShopPayShippingLine[]` | The shipping line items to display. |
| `deliveryMethods` required | `ShopPayDeliveryMethod[]` | The available delivery methods. |
| `locale` required | `ShopPayLocale` | An [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code, such as `en`, used to inform the display of instructions and amounts. |
| `presentmentCurrency` required | `ShopPayCurrencyCode` | An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code for the transaction, including legacy and non-standard codes. |
| `subtotal` required | `ShopPayMoney` | The subtotal of the line items, calculated as the sum of the `finalLinePrice` from all lines. |
| `discounts` optional | `ShopPayDiscountLine[]` | All discounts applied to the subtotal. These must be positive values. |
| `totalShippingPrice` optional | `ShopPayTotalShippingPrice` | The total shipping price after all applicable discounts, not including tax. |
| `totalTax` optional | `ShopPayMoney` | The total tax from all line items and shipping charges. |
| `total` required | `ShopPayMoney` | The grand total includes all applicable discounts, shipping charges, and taxes. The customer is charged this amount. |

***

## `ShopPayDeliveryMethodType`

The `ShopPayDeliveryMethodType` can be one of the following values:

* **`PICKUP`**: The customer buys online and picks up the order.
* **`SHIPPING`**: The customer's order is shipped.

***

## `ShopPayLineItem`

Represents line items in a payment request. Includes cart line items, order-level line items such as discounts and taxes, and the grand total.

![Shop Pay Wallet line item properties](https://shopify.dev/assets/assets/images/api/commerce-components/pay/line-item-B0pm43Kj.png)

```typescript
interface ShopPayLineItem {
  label: string;
  quantity: number;
  sku?: string;
  requiresShipping?: boolean;
  image?: ShopPayLineItemImage;
  originalItemPrice: ShopPayMoney;
  itemDiscounts?: ShopPayDiscountLine[];
  finalItemPrice: ShopPayMoney;
  originalLinePrice: ShopPayMoney;
  lineDiscounts?: ShopPayDiscountLine[];
  finalLinePrice: ShopPayMoney;
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `label` required | `string` | The label for the line item. |
| `quantity` required | `number` | The quantity of the line item. |
| `sku` optional | `string` | The merchandise SKU if needed for inventory tracking and reporting. |
| `requiresShipping` optional | `boolean` | Whether the line item requires shipping. Defaults to `true`. |
| `image` optional | `ShopPayLineItemImage` | The image associated with the line item. |
| `originalItemPrice` required | `ShopPayMoney` | The original price of the item before any applicable discounts. |
| `itemDiscounts` optional | `ShopPayDiscountLine[]` | All discounts applied to the item. These must be positive values. |
| `finalItemPrice` required | `ShopPayMoney` | The final price of the item after all applicable discounts. |
| `originalLinePrice` required | `ShopPayMoney` | The original line price before any applicable discounts, calculated as the original item price multiplied by quantity. |
| `lineDiscounts` optional | `ShopPayDiscountLine[]` | All discounts applied to the line item. |
| `finalLinePrice` required | `ShopPayMoney` | The final price of the line item based on quantity \* item price including all applicable discounts. |

***

## `ShopPayLineItemImage`

The image associated with the line item.

```typescript
interface ShopPayLineItemImage {
  url: string;
  alt?: string;
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `url` required | `string` | The URL of the image. Recommended: 128x128px, 1:1 ratio image. |
| `alt` optional | `string` | The alt text associated with the image. |

***

## `ShopPayTotalShippingPrice`

Represents the total shipping price in a payment request.

![Shop Pay Wallet total shipping price](https://shopify.dev/assets/assets/images/api/commerce-components/pay/total-shipping-price-BiIcefda.png)

```typescript
interface ShopPayTotalShippingPrice {
  discounts?: ShopPayDiscountLine[];
  originalTotal?: ShopPayMoney;
  finalTotal: ShopPayMoney;
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `discounts` optional | `ShopPayDiscountLine[]` | All discounts applied to the shipping price. These must be positive values. |
| `originalTotal` optional | `ShopPayMoney` | The original total shipping price. Used to show shipping price before any applicable discounts are applied, and must be included for all non-free shipping methods. |
| `finalTotal` required | `ShopPayMoney` | The final total shipping price. Price after all applicable discounts. |

***

## `ShopPayDiscountLine`

Represents discount lines in a payment request.

```typescript
interface ShopPayDiscountLine {
  label: string;
  amount: ShopPayMoney;
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `label` required | `string` | The label for the discount line. |
| `amount` required | `ShopPayMoney` | The amount of the discount as a positive value. |

***

## `ShopPayShippingLine`

Represents shipping line items in a payment request.

```typescript
interface ShopPayShippingLine {
  label: string;
  amount: ShopPayMoney;
  code: string;
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `label` required | `string` | The label for the shipping line item. |
| `amount` required | `ShopPayMoney` | The amount of the shipping line item. |
| `code` required | `string` | The service code of the shipping rate. Corresponds to `ShopPayDeliveryMethod#code`. |

***

## `ShopPayMoney`

Represents an amount and the associated currency.

| **Field name** | **Type** | **Description** |
| - | - | - |
| `amount` required | `number` | |
| `currencyCode` required | `ShopPayCurrencyCode` | |

***

## `ShopPayContactField`

Represents contact information for shipping or billing addresses. This interface is used to capture customer shipping and contact details during the checkout process.

| **Field name** | **Type** | **Description** |
| - | - | - |
| `countryCode` required | `string` | The country ISO-3166 code of the contact. |
| `postalCode` optional | `string` | The postal code of the contact. |
| `provinceCode` optional | `string` | The province (or state) ISO-3166 code of the contact. |
| `city` required | `string` | The city of the contact. |
| `firstName` optional | `string` | The first name of the contact. |
| `lastName` required | `string` | The last name of the contact. |
| `address1` required | `string` | The address of the contact. |
| `address2` optional | `string` | The address2 of the contact. |
| `phone` optional | `string` | The phone number of the contact. |
| `email` optional | `string` | The email address of the contact. |
| `companyName` optional | `string` | The company name of the contact. |

***

## `ShopPayPickupLocation`

Represents an available order pickup location. Pickup locations are displayed to a customer if they select `PICKUP` as the delivery method type.

```typescript
interface ShopPayPickupLocation {
  label: string;
  detail: string;
  code: string;
  amount: ShopPayMoney;
  readyExpectationLabel?: string;
  proximityLabel?: string;
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `label` required | `string` | The label for the pickup location. |
| `detail` required | `string` | The detail describing the pickup location. |
| `code` required | `string` | The code for the pickup location used to uniquely identify it. |
| `amount` required | `ShopPayMoney` | The amount of the pickup. |
| `readyExpectationLabel` optional | `string` | The description of when the order is ready for pickup. |
| `proximityLabel` optional | `string` | The description for the proximity of the pickup location relative to the customer. |

***

## `ShopPayDeliveryMethod`

![Shop Pay Wallet delivery methods](https://shopify.dev/assets/assets/images/api/commerce-components/pay/shipping-0CIVN95N.png)

```typescript
interface ShopPayDeliveryMethod {
  code: string;
  label: string;
  detail?: string;
  amount: ShopPayMoney;
  minDeliveryDate?: ISO8601Date;
  maxDeliveryDate?: ISO8601Date;
  deliveryExpectationLabel?: string;
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `code` required | `string` | The service code of the shipping rate. |
| `label` required | `string` | The service name of the shipping rate. |
| `detail` optional | `string` | The description of the shipping rate. |
| `amount` required | `ShopPayMoney` | The total price amount of the shipping rate. |
| `minDeliveryDate` optional | `ISO8601Date` | The minimum delivery date. ISO 8601-encoded date string. Required unless `deliveryExpectationLabel` is provided. |
| `maxDeliveryDate` optional | `ISO8601Date` | The maximum delivery date. ISO 8601-encoded date string. Required unless `deliveryExpectationLabel` is provided. |
| `deliveryExpectationLabel` optional | `string` | If provided, is displayed as further detail for expected delivery, replacing the calculated delivery estimate. |

***

## `ShopPayPaymentRequestUpdate`

Represents an updated state of the checkout. At least one of an updated payment request and an array of errors should be provided.

| **Field name** | **Type** | **Description** |
| - | - | - |
| `updatedPaymentRequest` optional | `ShopPayPaymentRequest` | The updated payment request. If not provided, the current payment request continues to be used. |
| `errors` optional | `ShopPayUserError[]` | An array of errors. |

***

## `PickupLocationChangedEvent`

Dispatched when a customer changes their pickup location.

```typescript
interface PickupLocationChangedEvent extends Event {
  pickupLocation: ShopPayPickupLocation;
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `pickupLocation` required | `ShopPayPickupLocation` | The customer's pick up location. |

***

## `PickupLocationFilterChangedEvent`

Dispatched when a customer changes their pickup location filter.

```typescript
interface PickupLocationFilterChangedEvent extends Event {
  buyerLocation: ShopPayBuyerLocation;
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `buyerLocation` required | `ShopPayBuyerLocation` | The customer's location used to filter pickup locations. |

***

## `DeliveryMethodTypeChangedEvent`

Dispatched when a customer changes their delivery method type.

```typescript
interface DeliveryMethodTypeChangedEvent extends Event {
  deliveryMethodType: ShopPayDeliveryMethodType;
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `deliveryMethodType` required | `ShopPayDeliveryMethodType` | The delivery method type selected by the user. |

***

## `ShopPayBuyerLocation`

Represents a customer's location. Use this to set the available pickup locations.

```typescript
interface ShopPayBuyerLocation {
  address1?: string;
  address2?: string;
  city?: string;
  provinceCode?: string;
  countryCode?: string;
  postalCode?: string;
  coordinates?: {
    latitude: number;
    longitude: number;
  };
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `address1` optional | `string` | The address of the contact. |
| `address2` optional | `string` | The address2 of the contact. |
| `city` optional | `string` | The city of the contact. |
| `provinceCode` optional | `string` | The province (or state) ISO-3166 code of the contact. |
| `countryCode` optional | `string` | The country ISO-3166 code of the contact. |
| `postalCode` optional | `string` | The postal code of the contact. |
| `coordinates.latitude` optional | `number` | The latitude of the customer's location. |
| `coordinates.longitude` optional | `number` | The longitude of the customer's location. |

***

## `ShopPayPaymentConfirmationRequestedEvent`

Dispatched when a customer clicks **Pay now** to confirm their payment. This event includes the customer's billing address.

```typescript
interface ShopPayPaymentConfirmationRequestedEvent extends Event {
  billingAddress: ShopPayContactField;
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `billingAddress` required | `ShopPayContactField` | The customer's billing address and contact info. |

***

## `ShopPayPaymentRequestReceiptCompleted`

A successful completed receipt. The status is `completed`. This event only occurs if the payment is successfully processed.

```typescript
interface ShopPayPaymentRequestReceiptCompleted {
  completedAt: ISO8601Date;
  billingAddress?: {
    countryCode: string;
    postalCode?: string;
    provinceCode?: string;
    city: string;
    firstName?: string;
    lastName: string;
    address1: string;
    address2?: string;
    phone?: string;
    email?: string;
    companyName?: string;
  };
  creditCardDetails?: {
    brand?: string;
    lastDigits?: string;
  };
  paymentType: "SHOP_PAY" | "SHOPIFY_INSTALLMENTS";
  accountUrl?: string;
  status: "completed";
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `completedAt` required | `ISO8601Date` | The date the receipt was completed. |
| `billingAddress` optional | `ShopPayContactField` | The billing address of the customer. When present, `countryCode`, `city`, `lastName`, and `address1` are required. |
| `creditCardDetails` optional | `{brand?: string, lastDigits?: string}` | The credit card details of the customer. |
| `paymentType` required | `"SHOP_PAY" or "SHOPIFY_INSTALLMENTS"` | The type of payment used. |
| `accountUrl` optional | `string` | The URL to the customer's account. |
| `status` required | `"completed"` | The status of the receipt. |

***

## `ShopPayPaymentAttemptFailedEvent`

Dispatched when a payment attempt has failed. This can happen due to various reasons such as insufficient funds, invalid payment details, or other payment processing errors.

**Caution:**

Buyers have the option to select a different payment method to retry their checkout after a failure. Don't call `session.close()` so that users can retry with a new payment method without disrupting their session.

```typescript
interface ShopPayPaymentAttemptFailedEvent extends Event {
  error: {
    errorCode: string;
    reason: string;
  };
}
```

| **Field name** | **Type** | **Description** |
| - | - | - |
| `error` required | `{errorCode: string, reason: string}` | The reason why the payment attempt failed. |

***

## `ShopPayUserError`

Represents an error that's surfaced to the user during checkout.

The following images show how each error type appears in the Shop Pay dialog:

**`generalError`**:

![generalError displayed at the top of the Shop Pay checkout](https://shopify.dev/assets/assets/images/api/commerce-components/pay/general-error-iuLcmLqg.png)

**`discountCodeError`**:

![discountCodeError displayed near the discount code field](https://shopify.dev/assets/assets/images/api/commerce-components/pay/discount-code-error-DziLeB4H.png)

**`shippingAddressError`**:

![shippingAddressError displayed near the shipping address selection](https://shopify.dev/assets/assets/images/api/commerce-components/pay/shipping-address-error-D35Tvu4j.png)

| **Field name** | **Type** | **Description** |
| - | - | - |
| `type` required | `'generalError'` or `'discountCodeError'` or `'shippingAddressError'` | The context of the error. |
| `message` optional | `string` | The localized message shown to the user. |

* **`generalError`**: These errors are shown at the top of the checkout. We recommend setting your own message. The default error text is "Something went wrong. Please close Shop Pay and try again".
* **`discountCodeError`**: These errors are shown near discount code entry, for example, to indicate that a discount code is expired. We recommend setting your own message. The default error text is "Enter a valid discount code".
* **`shippingAddressError`**: These errors are shown near shipping address selection, for example, to indicate that the selected shipping address can't be delivered to. We recommend setting your own message. The default error text is "Shipping not available for selected address".

**Note:**

A maximum of two errors can be displayed at any given time. If more than two errors are provided, only the first two are shown. Each error message has a character limit of 500; any message exceeding this limit is truncated. Only plain text is supported for error messages. Any HTML or other formatting is removed.

***

## Confirmation flow

After a customer clicks **Pay**, payment confirmation follows this sequence:

1. The `paymentconfirmationrequested` event is triggered on your frontend, containing the `paymentMethod` token.
2. Your server runs the [`ShopPayPaymentRequestSessionSubmit`](https://shopify.dev/docs/api/commerce-components/pay/graphql-pre-payment#example-shoppaypaymentrequestsessionsubmit) mutation to authorize payment processing.
3. Your system performs a final validation (for example, confirming the cart total and inventory) and your frontend calls `session.completePaymentConfirmationRequest()` to continue. If validation fails, call `completePaymentConfirmationRequest()` with an `errors` array to surface the error to the buyer in the Shop Pay popup. Refer to the [`paymentconfirmationrequested` listener example](https://shopify.dev/docs/api/commerce-components/pay/sessions-and-events#attach-event-listeners) for the error-handling pattern.
4. The `paymentcomplete` event is dispatched after Shopify finishes processing.

Based on the payment capture configuration in the Shopify admin's **Payments** settings, the payment is processed as `authorized` or `capture`. If manual capture is configured, you must call the GraphQL Admin API's [`orderCapture`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderCapture) mutation to finalize the payment.

When an order is created in Shopify, it might not be immediately available to query, and the [`orders/create`](https://shopify.dev/docs/api/webhooks) webhook might not fire immediately. Don't rely on either for real-time functionality. Refer to [Recovering from errors](https://shopify.dev/docs/api/commerce-components/pay/monitoring#recovering-from-errors) to make your app resilient to webhook delivery issues.

***