Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

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

[]

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'
```

Anchor to useSelectedPaymentOptions
useSelectedPaymentOptions()

Returns payment options selected by the buyer.

Anchor to useSelectedPaymentOptions-returnsReturns

[]

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'
```

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

Available payment options

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;
}

Selected payment options

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;
}