Choose a version:

Payments API

The Payments API provides read-only access to the available and selected payment options during checkout. Use this API to detect specific payment types, display targeted messaging, and adjust your extension based on the buyer's payment selection.

Payment options are read-only. Extensions can't add, remove, or modify available payment methods.

Anchor to Use casesUse cases

Promote express payment methods: Detect whether wallet-based payment options like Apple Pay or Google Pay are available and encourage the buyer to use them.
Display security messaging: Show a trust badge or security message when the buyer selects a credit card payment method.
Adjust UI by payment type: Render different content depending on which payment option the buyer has selected.

Support

Targets (31)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides payment data for the current checkout. Access the following properties on shopify to read available and selected payment options. Available to purchase extension targets.

Anchor to availablePaymentOptions availablePaymentOptions <[]> required: All payment options available to the buyer for this checkout, such as credit cards, wallets, and local payment methods. The list depends on the shop's payment configuration and the buyer's region.

The set of payment options can change when the buyer updates their address or cart, so subscribe to changes rather than reading once during initialization. Each option exposes handle and type only. Provider names, logos, fees, and installment terms aren't available.
Anchor to selectedPaymentOptions selectedPaymentOptions <[]> required: The payment options the buyer has currently selected. This updates as the buyer changes their payment method. The array can contain multiple entries when the buyer splits payment across methods (for example, a gift card and a credit card).

Each option exposes handle and type only. Provider names, logos, fees, and installment terms aren't available.

SubscribableSignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends `ReadonlySignalLike` with deprecated fields that are still supported for backwards compatibility.

current
The current value of the signal. Equivalent to `.value`, accessing this property subscribes to changes when used in a reactive context.
```
T
```
destroy
Cleans up the subscription and releases any resources held by this signal. After calling `destroy()`, the signal stops receiving updates from the main thread.
```
() => Promise<void>
```
subscribe
Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.
```
(fn: (value: T) => void) => () => void
```
value
The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.
```
T
```

PaymentOption

A payment option presented to the buyer.

handle
A session-scoped identifier for this payment option. This handle isn't globally unique; it's specific to the current checkout session or the shop.
```
string
```
type
The type of the payment option. Shops can be configured to support many different payment options. Some options are available only to buyers in specific regions. | Type | Description | |---|---| | `creditCard` | A vaulted or manually entered credit card. | | `deferred` | A [deferred payment](https://help.shopify.com/en/manual/orders/deferred-payments), such as invoicing the buyer and collecting payment at a later time. | | `local` | A [local payment option](https://help.shopify.com/en/manual/payments/shopify-payments/local-payment-methods) specific to the current region or market | | `manualPayment` | A manual payment option such as an in-person retail transaction. | | `offsite` | A payment processed outside of Shopify's checkout, excluding integrated wallets. | | `other` | Another type of payment not defined here. | | `paymentOnDelivery` | A payment collected on delivery. | | `redeemable` | A redeemable payment option such as a gift card or store credit. | | `wallet` | An integrated wallet such as PayPal, Google Pay, or Apple Pay. | | `customOnsite` | A custom payment option that's processed through a checkout extension with a payments app. |
```
| 'creditCard'
    | 'deferred'
    | 'local'
    | 'manualPayment'
    | 'offsite'
    | 'other'
    | 'paymentOnDelivery'
    | 'redeemable'
    | 'wallet'
    | 'customOnsite'
```

SelectedPaymentOption

A payment option that the buyer has actively selected. This is the same shape as `PaymentOption` and appears in `selectedPaymentOptions`.

handle
A session-scoped identifier for this payment option. This handle isn't globally unique; it's specific to the current checkout session or the shop.
```
string
```
type
The type of the payment option. Shops can be configured to support many different payment options. Some options are available only to buyers in specific regions. | Type | Description | |---|---| | `creditCard` | A vaulted or manually entered credit card. | | `deferred` | A [deferred payment](https://help.shopify.com/en/manual/orders/deferred-payments), such as invoicing the buyer and collecting payment at a later time. | | `local` | A [local payment option](https://help.shopify.com/en/manual/payments/shopify-payments/local-payment-methods) specific to the current region or market | | `manualPayment` | A manual payment option such as an in-person retail transaction. | | `offsite` | A payment processed outside of Shopify's checkout, excluding integrated wallets. | | `other` | Another type of payment not defined here. | | `paymentOnDelivery` | A payment collected on delivery. | | `redeemable` | A redeemable payment option such as a gift card or store credit. | | `wallet` | An integrated wallet such as PayPal, Google Pay, or Apple Pay. | | `customOnsite` | A custom payment option that's processed through a checkout extension with a payments app. |
```
| 'creditCard'
    | 'deferred'
    | 'local'
    | 'manualPayment'
    | 'offsite'
    | 'other'
    | 'paymentOnDelivery'
    | 'redeemable'
    | 'wallet'
    | 'customOnsite'
```

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

if (

shopify.availablePaymentOptions.value.some(

(option) => option.type === 'wallet',

)

) {

return (

<s-banner>

Select an express payment method for

faster checkout

</s-banner>

);

}

return null;

}

Examples

Description

Encourage the buyer to use a faster checkout method when one is available. This example checks whether `shopify.availablePaymentOptions` includes a `wallet` type and shows a banner promoting express checkout.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  if (
    shopify.availablePaymentOptions.value.some(
      (option) => option.type === 'wallet',
    )
  ) {
    return (
      <s-banner>
        Select an express payment method for
        faster checkout
      </s-banner>
    );
  }

  return null;
}

Description

Display a security message when the buyer selects a credit card. This example checks whether `shopify.selectedPaymentOptions` includes a `creditCard` type and renders a trust banner.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  if (
    shopify.selectedPaymentOptions.value.some(
      (option) => option.type === 'creditCard',
    )
  ) {
    return (
      <s-banner>
        All credit card transactions are secure
      </s-banner>
    );
  }

  return null;
}

Anchor to Best practicesBest practices

Don't assume specific payment types are available: Payment options depend on the merchant's configuration and the buyer's region. Always check the list dynamically rather than hardcoding expectations.

Was this page helpful?