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.

Docs_Standard_PaymentOptionsApi

availablePaymentOptions
All available payment options.
```
StatefulRemoteSubscribable<PaymentOption[]>
```
selectedPaymentOptions
Payment options selected by the buyer.
```
StatefulRemoteSubscribable<SelectedPaymentOption[]>
```

export interface Docs_Standard_PaymentOptionsApi
  extends Pick<
    StandardApi,
    'availablePaymentOptions' | 'selectedPaymentOptions'
  > {}

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

export interface PaymentOption {
  /**
   * 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. |
   */
  type:
    | 'creditCard'
    | 'deferred'
    | 'local'
    | 'manualPayment'
    | 'offsite'
    | 'other'
    | 'paymentOnDelivery'
    | 'redeemable'
    | 'wallet'
    | 'customOnsite';

  /**
   * 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.
   */
  handle: string;
}

SelectedPaymentOption

A payment option selected by the buyer.

handle
The unique handle referencing `PaymentOption.handle`. Refer to [availablePaymentOptions](/docs/api/checkout-ui-extensions/apis/payments#standardapi-propertydetail-availablepaymentoptions).
```
string
```

export interface SelectedPaymentOption {
  /**
   * The unique handle referencing `PaymentOption.handle`.
   *
   * Refer to [availablePaymentOptions](/docs/api/checkout-ui-extensions/apis/payments#standardapi-propertydetail-availablepaymentoptions).
   */
  handle: string;
}

Was this section helpful?

Anchor to useAvailablePaymentOptions
useAvailablePaymentOptions()

Returns all available payment options.

Anchor to useAvailablePaymentOptions-returnsReturns

[]

UseAvailablePaymentOptionsGeneratedType

Returns all available payment options.

PaymentOption[]

PaymentOption[]

export function useAvailablePaymentOptions<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(): PaymentOption[] {
  const api = useApi<Target>();

  if ('availablePaymentOptions' in api) {
    return useSubscription(api.availablePaymentOptions);
  }

  throw new ExtensionHasNoMethodError(
    'availablePaymentOptions',
    api.extension.target,
  );
}

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

export interface PaymentOption {
  /**
   * 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. |
   */
  type:
    | 'creditCard'
    | 'deferred'
    | 'local'
    | 'manualPayment'
    | 'offsite'
    | 'other'
    | 'paymentOnDelivery'
    | 'redeemable'
    | 'wallet'
    | 'customOnsite';

  /**
   * 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.
   */
  handle: string;
}

Was this section helpful?

Anchor to useSelectedPaymentOptions
useSelectedPaymentOptions()

Returns payment options selected by the buyer.

Anchor to useSelectedPaymentOptions-returnsReturns

[]

UseSelectedPaymentOptionsGeneratedType

Returns payment options selected by the buyer.

PaymentOption[]

PaymentOption[]

export function useSelectedPaymentOptions<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(): PaymentOption[] {
  const api = useApi<Target>();

  if (
    !('selectedPaymentOptions' in api) ||
    !('availablePaymentOptions' in api)
  ) {
    throw new ExtensionHasNoMethodError(
      'selectedPaymentOptions',
      api.extension.target,
    );
  }

  const selectedPaymentOptions = useSubscription(api.selectedPaymentOptions);
  const availablePaymentOptions = useSubscription(api.availablePaymentOptions);

  return useMemo(() => {
    const availablePaymentOptionsMap: Record<string, PaymentOption> = {};

    for (const option of availablePaymentOptions) {
      availablePaymentOptionsMap[option.handle] = option;
    }

    return selectedPaymentOptions.map((paymentOption) => {
      return {
        handle: paymentOption.handle,
        type: availablePaymentOptionsMap[paymentOption.handle]?.type,
      };
    });
  }, [availablePaymentOptions, selectedPaymentOptions]);
}

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

export interface PaymentOption {
  /**
   * 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. |
   */
  type:
    | 'creditCard'
    | 'deferred'
    | 'local'
    | 'manualPayment'
    | 'offsite'
    | 'other'
    | 'paymentOnDelivery'
    | 'redeemable'
    | 'wallet'
    | 'customOnsite';

  /**
   * 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.
   */
  handle: string;
}

Was this section helpful?

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 (

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

Anchor to examplesExamples

Anchor to example-selected-payment-optionsSelected payment options

Was this section helpful?

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 (

All credit card transactions are secure

</Banner>

);

}

return null;

}

examples

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