---
title: Payments
description: The API for interacting with the payment options.
api_version: 2025-10
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/payments
  md: https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/payments.md
---

# PaymentsAPI

The API for interacting with the payment options.

## StandardApi

The base API object provided to `purchase` extension targets.

* availablePaymentOptions

  SubscribableSignalLike\<PaymentOption\[]>

  required

  All available payment options.

* selectedPaymentOptions

  SubscribableSignalLike\<SelectedPaymentOption\[]>

  required

  Payment options selected by the buyer.

### SubscribableSignalLike

Represents a read-only value managed on the main thread that an extension can subscribe to. Example: Checkout uses this to manage the state of an object and communicate state changes to extensions running in a sandboxed web worker. This interface is compatible with \[Preact's ReadonlySignal]\(https://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709). Some fields are deprecated but still supported for backwards compatibility. In version 2025-10, \[\`StatefulRemoteSubscribable\`]\(https://github.com/Shopify/remote-dom/blob/03929aa8418a89d41d294005f219837582718df8/packages/async-subscription/src/types.ts#L17) was replaced with \`ReadonlySignalLike\`. Checkout will remove the old fields some time in the future.

* current

  ```ts
  T
  ```

* destroy

  ```ts
  () => Promise<void>
  ```

* subscribe

  ```ts
  (fn: (value: T) => void) => () => void
  ```

* value

  ```ts
  T
  ```

```ts
export interface SubscribableSignalLike<T> extends ReadonlySignalLike<T> {
  /**
   * @deprecated Use `.value` instead.
   */
  readonly current: T;
  /**
   * @deprecated No longer needed. Use Preact Signal management instead.
   */
  destroy(): Promise<void>;
}
```

### 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.

  ```ts
  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. |

  ```ts
  | 'creditCard'
      | 'deferred'
      | 'local'
      | 'manualPayment'
      | 'offsite'
      | 'other'
      | 'paymentOnDelivery'
      | 'redeemable'
      | 'wallet'
      | 'customOnsite'
  ```

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

* 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.

  ```ts
  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. |

  ```ts
  | 'creditCard'
      | 'deferred'
      | 'local'
      | 'manualPayment'
      | 'offsite'
      | 'other'
      | 'paymentOnDelivery'
      | 'redeemable'
      | 'wallet'
      | 'customOnsite'
  ```

```ts
PaymentOption
```

## use​Available​Payment​Options()

Returns all available payment options.

### Returns

* PaymentOption\[]

### 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.

  ```ts
  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. |

  ```ts
  | 'creditCard'
      | 'deferred'
      | 'local'
      | 'manualPayment'
      | 'offsite'
      | 'other'
      | 'paymentOnDelivery'
      | 'redeemable'
      | 'wallet'
      | 'customOnsite'
  ```

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

## use​Selected​Payment​Options()

Returns payment options selected by the buyer.

### Returns

* SelectedPaymentOption\[]

### 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.

  ```ts
  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. |

  ```ts
  | 'creditCard'
      | 'deferred'
      | 'local'
      | 'manualPayment'
      | 'offsite'
      | 'other'
      | 'paymentOnDelivery'
      | 'redeemable'
      | 'wallet'
      | 'customOnsite'
  ```

```ts
PaymentOption
```

### Examples

* #### Available payment options

  ##### Preact

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

Selected payment options

### Examples

* #### Selected payment options

  ##### Preact

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

## Related

[Reference - Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

[Reference - Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)

[Reference - Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

[Learn - Tutorials](https://shopify.dev/apps/checkout)