Upgrade to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use Polaris web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the upgrade guide to upgrade your extension and avoid being blocked from updating your extension after October 1st 2026.

Choose a version:

Payments API

The API for interacting with the payment options.

Anchor to StandardApiStandardApi

The base API object provided to purchase extension targets.

Anchor to availablePaymentOptions availablePaymentOptions StatefulRemoteSubscribable<[]> required: All available payment options.
Anchor to selectedPaymentOptions selectedPaymentOptions StatefulRemoteSubscribable<[]> required: Payment options selected by the buyer.

PaymentOption

A payment option presented to the buyer.

handle
The unique handle for the payment option. This is not a globally unique identifier. It may be an identifier specific to the given checkout session or the current shop.
```
string
```
type
The type of the payment option. Shops can be configured to support many different payment options. Some options are only available 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 that will be 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, Apple Pay, etc. | | `customOnsite` | A custom payment option that is processed through a checkout extension with a payments app. |
```
| 'creditCard'
    | 'deferred'
    | 'local'
    | 'manualPayment'
    | 'offsite'
    | 'other'
    | 'paymentOnDelivery'
    | 'redeemable'
    | 'wallet'
    | 'customOnsite'
```

SelectedPaymentOption

handle
The unique handle for the payment option. This is not a globally unique identifier. It may be an identifier specific to the given checkout session or the current shop.
```
string
```
type
The type of the payment option. Shops can be configured to support many different payment options. Some options are only available 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 that will be 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, Apple Pay, etc. | | `customOnsite` | A custom payment option that is processed through a checkout extension with a payments app. |
```
| 'creditCard'
    | 'deferred'
    | 'local'
    | 'manualPayment'
    | 'offsite'
    | 'other'
    | 'paymentOnDelivery'
    | 'redeemable'
    | 'wallet'
    | 'customOnsite'
```

Anchor to useAvailablePaymentOptions
useAvailablePaymentOptions()

Returns all available payment options.

Anchor to useAvailablePaymentOptions-returnsReturns

[]

Anchor to useSelectedPaymentOptions
useSelectedPaymentOptions()

Returns payment options selected by the buyer.

Anchor to useSelectedPaymentOptions-returnsReturns

[]

Examples

React

import {

reactExtension,

Banner,

useAvailablePaymentOptions,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.block.render',

() => <Extension />,

);

function Extension() {

const options = useAvailablePaymentOptions();

if (

options.some(

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

)

) {

return (

Select an express payment method for

faster checkout

</Banner>

);

}

return null;

}

Examples

React

import {
  reactExtension,
  Banner,
  useAvailablePaymentOptions,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const options = useAvailablePaymentOptions();

  if (
    options.some(
      (option) => option.type === 'wallet',
    )
  ) {
    return (
      <Banner>
        Select an express payment method for
        faster checkout
      </Banner>
    );
  }

  return null;
}

React

import {
  reactExtension,
  Banner,
  useSelectedPaymentOptions,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const options = useSelectedPaymentOptions();

  if (
    options.some(
      (option) => option.type === 'creditCard',
    )
  ) {
    return (
      <Banner>
        All credit card transactions are secure
      </Banner>
    );
  }

  return null;
}

Anchor to RelatedRelated

ReferenceTargets

ReferenceComponents

ReferenceConfiguration

LearnTutorials

Was this page helpful?

Anchor to StandardApiStandardApi

PaymentOption

SelectedPaymentOption

Anchor to useAvailablePaymentOptionsuseAvailablePaymentOptions()

Anchor to useAvailablePaymentOptions-returnsReturns

Anchor to useSelectedPaymentOptionsuseSelectedPaymentOptions()

Anchor to useSelectedPaymentOptions-returnsReturns

Anchor to RelatedRelated

Anchor to useAvailablePaymentOptions
useAvailablePaymentOptions()

Anchor to useSelectedPaymentOptions
useSelectedPaymentOptions()