Configure payments extensions

A payments extension integrates a payment provider with Shopify checkout. When you generate a payments extension, Shopify CLI creates a shopify.extension.toml file that defines the session URLs, supported payment methods, and capabilities that your extension exposes to merchants and buyers.

Every payments extension uses the same type = "payments_extension". The target in [[extensions.targeting]] determines the kind of payment provider that your extension implements, and which additional properties apply.

Access scopes

The write_payment_gateways and write_payment_sessions scopes are automatically granted to your app through the payments extension. Omit them from your shopify.app.toml file on initial deployment. In later deployments, you can add these scopes to request merchant permission. For the full list of prerequisites, refer to Payments extension considerations.

Anchor to Payments extension targetsPayments extension targets

The target in [[extensions.targeting]] identifies the type of payment provider. Each target maps to a build tutorial that walks through the full configuration:

Target	Provider type	Build tutorial
`payments.offsite.render`	Offsite payments, where the buyer completes payment on the provider's hosted page.	Build an offsite payments extension
`payments.credit-card.render`	Credit card payments processed on Shopify checkout.	Build a credit card payments extension
`payments.custom-credit-card.render`	Custom credit card payments rendered with your own checkout UI extension.	Build a Shopify custom credit card payments extension
`payments.custom-onsite.render`	Alternative onsite payment methods rendered with your own checkout UI extension.	Build an alternative payments extension
`payments.redeemable.render`	Redeemable payment methods, such as gift cards.	Build a redeemables payments extension

Card-present payments

In-person payments processed through Shopify POS use the payments.card-present.render target. These extensions share the common properties below, along with a sync_terminal_transaction_result_url for terminal results.

Anchor to Common propertiesCommon properties

The following properties apply to most payments extension targets. Whether a property is required can vary by target — for example, redeemable extensions omit the card-specific properties and add balance_url.

Property	Description
`api_version` required	The version of the Payments Apps API that your extension receives.
`name` required	The name of the extension. Translatable if it starts with `t:` and uses a key defined in your translation data.
`handle` required	A unique reference name for the extension within your app.
`type` required	The extension type. For a payments extension, this value is always `payments_extension`.
`uid` required	An app-scoped identifier that `shopify app deploy` uses to determine whether the extension is being created, updated, or deleted. Shopify CLI generates this value for you — you don't need to set or edit it manually. Must be unique within the app.
`merchant_label` required	The name for your payment provider extension. This name is displayed to merchants in the Shopify admin when they search for payment methods to add to their store. Limited to 50 characters.
`buyer_label` optional	The name of the method displayed to buyers in checkout. It can match your merchant label or be customized. After a buyer label is set, provide translations for localization with `[[extensions.buyer_label_translations]]`.
`payment_session_url` required	The URL that receives payment and order details from the checkout.
`refund_session_url` required	The URL that refund session requests are sent to. Strictly enforced for the credit card, custom credit card, and card-present targets, and for any extension that sets `confirmation_callback_url`. Other targets should still support refunds unless their payment method genuinely can't.
`capture_session_url` conditional	The URL that capture session requests are sent to. Required for the credit card, custom credit card, and card-present targets. Optional for the offsite, alternative onsite, and redeemable targets, where it's only used if your payments app supports merchant manual capture.
`void_session_url` conditional	The URL that void session requests are sent to. Required for the credit card, custom credit card, and card-present targets. Optional for the offsite, alternative onsite, and redeemable targets, where it's only used if your payments app supports merchant manual capture or void payments.
`confirmation_callback_url` conditional	The URL that confirm session requests are sent to. If set, then the payments app can use the `paymentSessionConfirm` mutation to confirm with Shopify whether to proceed with the payment request. When this URL is required depends on the target: Offsite and alternative onsite: Required if your payments app supports inventory confirmation. Credit card and custom credit card: Required if your payments app supports 3-D Secure authentication. Redeemable and card-present: Not implemented.
`supported_countries` required	The countries where your payments app is available, as ISO 3166 (alpha-2) country codes. Ensure the countries match the geographic requirements in your app listing.
`supported_payment_methods` required	The payment methods (for example, `visa`) that are available with your payments app. Learn more. Redeemable extensions support only `gift-card`.
`supports_3ds` required	Whether the extension supports 3-D Secure. You must enable this field if you plan to support payments in countries that have mandated 3-D Secure.
`supports_installments` required	Whether the extension supports installments.
`supports_deferred_payments` required	Whether the extension supports deferred payments.
`test_mode_available` required	Enables merchants to test their setup by simulating transactions. To test on a dev store, set your payment provider in the Shopify admin to test mode.
`multiple_capture` optional	Enables merchants to partially capture an authorized payment multiple times, up to the full authorization amount. Only used if your payments app supports captures and voids.
`[[extensions.targeting]]` required	Contains the `target` that identifies the payment provider type.

Anchor to Additional properties by targetAdditional properties by target

Anchor to Credit card paymentsCredit card payments

The credit card (payments.credit-card.render) and custom credit card (payments.custom-credit-card.render) targets both process credit cards on Shopify checkout, and share the following additional properties:

Property	Description
`encryption_certificate_fingerprint` required	The certificate that Shopify uses to generate the ephemeral key and encrypt the customer's credit card information. Refer to Manage encryption certificates.
`supports_moto` optional	Enables Mail Order/Telephone Order (MOTO), which lets merchants manually process transactions using a customer's credit card information. The `moto` attribute in payment method data is available only in API version `2024-07` and later.

Custom credit card extensions render their payment method with your own checkout UI extension, so they also support the checkout UI extension properties.

Anchor to Checkout UI extension paymentsCheckout UI extension payments

The custom credit card (payments.custom-credit-card.render), alternative onsite (payments.custom-onsite.render), and redeemable (payments.redeemable.render) targets render your payment method with your own checkout UI extension, and support the following additional properties:

Property	Description
`ui_extension_handle` required	The UI extension that renders your payments app in checkout. This value can only be a UI extension linked to this specific payments app.
`checkout_payment_method_fields` required	The fields your payments app accepts from buyers in checkout (for example, installment details or payment plan). Each field is defined in a `[[extensions.checkout_payment_method_fields]]` entry with a `key`, a `type`, and whether it's `required`.
`checkout_hosted_fields` conditional	The hosted card fields your payments app accepts from buyers in checkout, as an array of strings. Required for the custom credit card target, which collects card data through Shopify's hosted fields. Supported values are `name`, `expiry`, `verification_value`, `issue_date`, and `issue_number`. The alternative onsite and redeemable targets don't collect card data, so they don't use this property.

Anchor to Redeemable paymentsRedeemable payments

The redeemable (payments.redeemable.render) target processes redeemable payment methods, such as gift cards. Redeemable extensions add balance_url, accept only gift-card in supported_payment_methods, and render with a checkout UI extension. Card-specific properties, such as supports_3ds, don't apply.

Property	Description
`balance_url` required	The URL that balance requests are sent to.

Anchor to Example configuration filesExample configuration files

api_version = "2026-01"

[[extensions]]

name = "Offsite Payments Extension"

handle = "offsite-payments"

type = "payments_extension"

uid = "1aafc25d-8448-218e-9373-b3d91ac2a0af75f73e12"

merchant_label = "Offsite Payments App Extension"

payment_session_url = "https://example.com/payment"

refund_session_url = "https://example.com/refund"

supported_countries = ["US"]

supported_payment_methods = ["visa"]

supports_3ds = false

supports_installments = false

supports_deferred_payments = false

test_mode_available = true

[[extensions.targeting]]

target = "payments.offsite.render"

api_version = "2026-01"

[[extensions]]

name = "Credit Card Payments Extension"

handle = "credit-card-payments"

type = "payments_extension"

uid = "3e9ce641-7624-b901-fdef-cc194f77a8720c5af6e5"

merchant_label = "Credit Card Payments App Extension"

payment_session_url = "https://example.com/payment"

refund_session_url = "https://example.com/refund"

capture_session_url = "https://example.com/capture"

void_session_url = "https://example.com/void"

supported_countries = ["US"]

supported_payment_methods = ["visa"]

supports_moto = true

supports_3ds = false

supports_installments = false

supports_deferred_payments = false

test_mode_available = true

encryption_certificate_fingerprint = ""

[[extensions.targeting]]

target = "payments.credit-card.render"

api_version = "2026-01"

[[extensions]]

name = "Custom Credit Card Payments Extension"

handle = "custom-credit-card-payments"

type = "payments_extension"

uid = "f62f100d-15e6-9866-eda9-23f99de4b5d26e347042"

merchant_label = "Custom Credit Card Payments App Extension"

payment_session_url = "https://example.com/payment"

refund_session_url = "https://example.com/refund"

capture_session_url = "https://example.com/capture"

void_session_url = "https://example.com/void"

supported_countries = ["US"]

supported_payment_methods = ["visa"]

supports_3ds = false

supports_installments = false

supports_deferred_payments = false

test_mode_available = true

encryption_certificate_fingerprint = ""

multiple_capture = false

ui_extension_handle = "my-checkout-ui-extension"

checkout_hosted_fields = ["name", "expiry", "verification_value"]

[[extensions.checkout_payment_method_fields]]

key = "field1"

type = "string"

required = true

[[extensions.targeting]]

target = "payments.custom-credit-card.render"

api_version = "2026-01"

[[extensions]]

name = "Redeemable Payments Extension"

handle = "redeemable-payments"

type = "payments_extension"

uid = "8a8e0c98-1efb-7556-dfbb-04bdcfea1662b066ab00"

merchant_label = "Redeemable Payments App Extension"

payment_session_url = "https://example.com/payment"

refund_session_url = "https://example.com/refund"

balance_url = "https://example.com/balance"

supported_countries = ["US"]

supported_payment_methods = ["gift-card"]

test_mode_available = true

ui_extension_handle = "my-checkout-ui-extension"

[[extensions.checkout_payment_method_fields]]

key = "card_number"

type = "string"

required = true

[[extensions.checkout_payment_method_fields]]

key = "pin"

type = "string"

required = false

[[extensions.targeting]]

target = "payments.redeemable.render"

Offsite

api_version = "2026-01"

[[extensions]]
name = "Offsite Payments Extension"
handle = "offsite-payments"
type = "payments_extension"
uid = "1aafc25d-8448-218e-9373-b3d91ac2a0af75f73e12"

merchant_label = "Offsite Payments App Extension"
payment_session_url = "https://example.com/payment"
refund_session_url = "https://example.com/refund"
supported_countries = ["US"]
supported_payment_methods = ["visa"]
supports_3ds = false
supports_installments = false
supports_deferred_payments = false
test_mode_available = true

[[extensions.targeting]]
target = "payments.offsite.render"

Credit card

api_version = "2026-01"

[[extensions]]
name = "Credit Card Payments Extension"
handle = "credit-card-payments"
type = "payments_extension"
uid = "3e9ce641-7624-b901-fdef-cc194f77a8720c5af6e5"

merchant_label = "Credit Card Payments App Extension"
payment_session_url = "https://example.com/payment"
refund_session_url = "https://example.com/refund"
capture_session_url = "https://example.com/capture"
void_session_url = "https://example.com/void"
supported_countries = ["US"]
supported_payment_methods = ["visa"]
supports_moto = true
supports_3ds = false
supports_installments = false
supports_deferred_payments = false
test_mode_available = true
encryption_certificate_fingerprint = ""

[[extensions.targeting]]
target = "payments.credit-card.render"

Custom credit card

api_version = "2026-01"

[[extensions]]
name = "Custom Credit Card Payments Extension"
handle = "custom-credit-card-payments"
type = "payments_extension"
uid = "f62f100d-15e6-9866-eda9-23f99de4b5d26e347042"

merchant_label = "Custom Credit Card Payments App Extension"
payment_session_url = "https://example.com/payment"
refund_session_url = "https://example.com/refund"
capture_session_url = "https://example.com/capture"
void_session_url = "https://example.com/void"
supported_countries = ["US"]
supported_payment_methods = ["visa"]
supports_3ds = false
supports_installments = false
supports_deferred_payments = false
test_mode_available = true
encryption_certificate_fingerprint = ""
multiple_capture = false
ui_extension_handle = "my-checkout-ui-extension"
checkout_hosted_fields = ["name", "expiry", "verification_value"]

  [[extensions.checkout_payment_method_fields]]
  key = "field1"
  type = "string"
  required = true

[[extensions.targeting]]
target = "payments.custom-credit-card.render"

Redeemable

api_version = "2026-01"

[[extensions]]
name = "Redeemable Payments Extension"
handle = "redeemable-payments"
type = "payments_extension"
uid = "8a8e0c98-1efb-7556-dfbb-04bdcfea1662b066ab00"

merchant_label = "Redeemable Payments App Extension"
payment_session_url = "https://example.com/payment"
refund_session_url = "https://example.com/refund"
balance_url = "https://example.com/balance"
supported_countries = ["US"]
supported_payment_methods = ["gift-card"]
test_mode_available = true
ui_extension_handle = "my-checkout-ui-extension"

  [[extensions.checkout_payment_method_fields]]
  key = "card_number"
  type = "string"
  required = true

  [[extensions.checkout_payment_method_fields]]
  key = "pin"
  type = "string"
  required = false

[[extensions.targeting]]
target = "payments.redeemable.render"

Anchor to Next stepsNext steps

Build a payments extension: Choose a provider type and follow the end-to-end tutorial.
Requirements for payments extensions: Review what's required before you build.
Configure app extensions: Learn about the configuration that's common across extension types.

Was this page helpful?