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

# PaymentsAPI

The API for interacting with the payment options.

## StandardApi

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

* availablePaymentOptions

  StatefulRemoteSubscribable\<PaymentOption\[]>

  required

  All available payment options.

* selectedPaymentOptions

  StatefulRemoteSubscribable\<SelectedPaymentOption\[]>

  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.

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

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

  ```ts
  string
  ```

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

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

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

### Examples

* #### Available payment options

  ##### React

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

## Examples

Selected payment options

### Examples

* #### Selected payment options

  ##### React

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

## Related

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

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

[![](https://shopify.dev/images/icons/32/apps.png)![](https://shopify.dev/images/icons/32/apps-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/components)

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

[![](https://shopify.dev/images/icons/32/gear.png)![](https://shopify.dev/images/icons/32/gear-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

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

[![](https://shopify.dev/images/icons/32/tutorial.png)![](https://shopify.dev/images/icons/32/tutorial-dark.png)](https://shopify.dev/apps/checkout)

[LearnTutorials](https://shopify.dev/apps/checkout)