---
title: Payments API
description: >-
  Read the available and selected payment options during checkout. Display
  payment-specific messaging based on the buyer's choices.
api_version: 2026-04
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/payments-api
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/payments-api.md
---

# Payments API

The Payments API provides read-only access to the available and selected payment options during checkout. Use this API to detect specific payment types, display targeted messaging, and adjust your extension based on the buyer's payment selection.

Payment options are read-only. Extensions can't add, remove, or modify available payment methods.

### Use cases

* **Promote express payment methods**: Detect whether wallet-based payment options like Apple Pay or Google Pay are available and encourage the buyer to use them.
* **Display security messaging**: Show a trust badge or security message when the buyer selects a credit card payment method.
* **Adjust UI by payment type**: Render different content depending on which payment option the buyer has selected.

### Support Targets (31)

### Supported targets

* [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target)
* [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target)
* [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets)
* [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-)
* purchase.​checkout.​chat.​render
* [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target)
* [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-)
* [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets)
* [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target)
* [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target)
* [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-)
* [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets)
* [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-)
* [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets)
* [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target)
* [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-)
* [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets)
* [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-)
* [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets)
* [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets)
* [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-)
* [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-)
* [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets)
* [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-)
* [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target)
* [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets)
* [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-)
* purchase.​thank-you.​chat.​render
* [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target)
* [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target)
* [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target)

### Properties

The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides payment data for the current checkout. Access the following properties on `shopify` to read available and selected payment options. Available to `purchase` extension targets.

* **availablePaymentOptions**

  **SubscribableSignalLike\<PaymentOption\[]>**

  **required**

  All payment options available to the buyer for this checkout, such as credit cards, wallets, and local payment methods. The list depends on the shop's payment configuration and the buyer's region.

  The set of payment options can change when the buyer updates their address or cart, so subscribe to changes rather than reading once during initialization. Each option exposes `handle` and `type` only. Provider names, logos, fees, and installment terms aren't available.

* **selectedPaymentOptions**

  **SubscribableSignalLike\<SelectedPaymentOption\[]>**

  **required**

  The payment options the buyer has currently selected. This updates as the buyer changes their payment method. The array can contain multiple entries when the buyer splits payment across methods (for example, a gift card and a credit card).

  Each option exposes `handle` and `type` only. Provider names, logos, fees, and installment terms aren't available.

### SubscribableSignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends \`ReadonlySignalLike\` with deprecated fields that are still supported for backwards compatibility.

* current

  The current value of the signal. Equivalent to \`.value\`, accessing this property subscribes to changes when used in a reactive context.

  ```ts
  T
  ```

* destroy

  Cleans up the subscription and releases any resources held by this signal. After calling \`destroy()\`, the signal stops receiving updates from the main thread.

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

* subscribe

  Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.

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

* value

  The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.

  ```ts
  T
  ```

### PaymentOption

A payment option presented to the buyer.

* handle

  A session-scoped identifier for this payment option. This handle isn't globally unique; it's specific to the current checkout session or the shop.

  ```ts
  string
  ```

* type

  The type of the payment option. Shops can be configured to support many different payment options. Some options are available only 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 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, or Apple Pay. | | \`customOnsite\` | A custom payment option that's processed through a checkout extension with a payments app. |

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

### SelectedPaymentOption

A payment option that the buyer has actively selected. This is the same shape as \`PaymentOption\` and appears in \`selectedPaymentOptions\`.

* handle

  A session-scoped identifier for this payment option. This handle isn't globally unique; it's specific to the current checkout session or the shop.

  ```ts
  string
  ```

* type

  The type of the payment option. Shops can be configured to support many different payment options. Some options are available only 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 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, or Apple Pay. | | \`customOnsite\` | A custom payment option that's processed through a checkout extension with a payments app. |

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

Examples

### Examples

* ####

  ##### Description

  Encourage the buyer to use a faster checkout method when one is available. This example checks whether \`shopify.availablePaymentOptions\` includes a \`wallet\` type and shows a banner promoting express checkout.

  ##### jsx

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

* ####

  ##### Description

  Display a security message when the buyer selects a credit card. This example checks whether \`shopify.selectedPaymentOptions\` includes a \`creditCard\` type and renders a trust banner.

  ##### jsx

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

***

## Best practices

* **Don't assume specific payment types are available**: Payment options depend on the merchant's configuration and the buyer's region. Always check the list dynamically rather than hardcoding expectations.

***