Ödeme yöntemlerini yeniden adlandırma ve sıralama

Ödeme sayfasında ödeme yöntemlerinin adını ve sırasını bir JSON metafield’dan değiştiren Shopify ödeme özelleştirme Function’ı; test edilmiş JavaScript.

Function API
Payment Customization
Hedef (target)
cart.payment-methods.transform.run
Plan
Herkese açık uygulamada her plan; özel uygulamada Shopify Plus
Uygulama yetkisi
write_payment_customizations
API sürümü
2026-10
Son kontrol

Kısaca

Bu ödeme özelleştirme Function’ı, ödeme sayfasındaki yöntemleri yeniden adlandırır ve seçtiğiniz sıraya koyar; örneğin havale için daha anlaşılır bir ad ve kartları en üste. İkisi de bir JSON metafield’dan gelir, kodda sabit değer yoktur. Payment Customization API’nin cart.payment-methods.transform.run hedefini (2026-10), paymentMethodRename ve paymentMethodMove işlemleriyle kullanır.

Nasıl kullanılır

  1. Shopify CLI ile bir uygulama oluşturun ve uzantıyı ekleyin: shopify app generate extension --template payment_customization, dil olarak JavaScript.
  2. Oluşturulan shopify.extension.toml dosyasını ve src/ içindeki iki dosyayı aşağıdakilerle değiştirin.
  3. Testleri çalıştırın: shopify app function run --input tests/rename-and-reorder.input.json.
  4. shopify app deploy ile deploy edin ve özelleştirmeyi paymentCustomizationCreate ile oluşturun.
  5. $app:function-configuration metafield’ını ayarlayın; örneğin {"renames": {"Bank Deposit": "Havale / EFT"}, "order": ["Credit card", "Bank Deposit"]}.

Kod

shopify.extension.toml
api_version = "2026-10"

[[extensions]]
name = "Rename and reorder payment methods"
handle = "rename-reorder-payment-methods"
type = "function"

  [[extensions.targeting]]
  target = "cart.payment-methods.transform.run"
  input_query = "src/cart_payment_methods_transform_run.graphql"
  export = "cart-payment-methods-transform-run"

  [extensions.build]
  command = ""
  path = "dist/function.wasm"
src/cart_payment_methods_transform_run.graphql
query CartPaymentMethodsTransformRunInput {
  paymentMethods {
    id
    name
  }
  paymentCustomization {
    metafield(namespace: "$app", key: "function-configuration") {
      jsonValue
    }
  }
}
src/cart_payment_methods_transform_run.js
// @ts-check

/**
 * @typedef {import("../generated/api").CartPaymentMethodsTransformRunInput} CartPaymentMethodsTransformRunInput
 * @typedef {import("../generated/api").CartPaymentMethodsTransformRunResult} CartPaymentMethodsTransformRunResult
 */

/**
 * Settings stored as JSON in the customization's metafield. Both are empty by
 * default, so checkout stays unchanged until the merchant configures them.
 */
const DEFAULT_CONFIG = {
  // Current name → name shown at checkout, matched case-insensitively.
  renames: /** @type {Record<string, string>} */ ({}),
  // Names in the order they should appear; unlisted methods keep their place after them.
  order: /** @type {string[]} */ ([]),
};

/**
 * @param {CartPaymentMethodsTransformRunInput} input
 * @returns {CartPaymentMethodsTransformRunResult}
 */
export function cartPaymentMethodsTransformRun(input) {
  const config = { ...DEFAULT_CONFIG, ...input.paymentCustomization?.metafield?.jsonValue };
  const renames = new Map(Object.entries(config.renames).map(([from, to]) => [from.toLowerCase(), to]));
  /** @param {string} name */
  const findMethod = (name) =>
    input.paymentMethods.find((method) => method.name.toLowerCase() === name.toLowerCase());

  // Rename operations refer to the method's ID, so they're independent of the order below.
  const renameOperations = input.paymentMethods
    .filter((method) => renames.has(method.name.toLowerCase()))
    .map((method) => ({
      paymentMethodRename: { paymentMethodId: method.id, name: renames.get(method.name.toLowerCase()) ?? method.name },
    }));

  // Index counts only methods present in this checkout, so a configured method
  // that isn't offered (another market, an inactive gateway) leaves no gap.
  const moveOperations = config.order
    .map(findMethod)
    .filter((method) => method != null)
    .map((method, index) => ({ paymentMethodMove: { paymentMethodId: method.id, index } }));

  return { operations: [...renameOperations, ...moveOperations] };
}
Test girdisi ve beklenen çıktı
tests/missing-method-skipped.input.json
{
  "paymentMethods": [
    { "id": "gid://shopify/PaymentCustomizationPaymentMethod/1", "name": "Credit card" },
    { "id": "gid://shopify/PaymentCustomizationPaymentMethod/2", "name": "PayPal" },
    { "id": "gid://shopify/PaymentCustomizationPaymentMethod/3", "name": "Bank Deposit" }
  ],
  "paymentCustomization": {
    "metafield": { "jsonValue": { "order": ["Cash on Delivery (COD)", "PayPal"] } }
  }
}
tests/missing-method-skipped.output.json
{
  "operations": [
    { "paymentMethodMove": { "paymentMethodId": "gid://shopify/PaymentCustomizationPaymentMethod/2", "index": 0 } }
  ]
}
tests/not-configured.input.json
{
  "paymentMethods": [
    { "id": "gid://shopify/PaymentCustomizationPaymentMethod/1", "name": "Credit card" },
    { "id": "gid://shopify/PaymentCustomizationPaymentMethod/2", "name": "PayPal" },
    { "id": "gid://shopify/PaymentCustomizationPaymentMethod/3", "name": "Bank Deposit" }
  ],
  "paymentCustomization": { "metafield": null }
}
tests/not-configured.output.json
{ "operations": [] }
tests/rename-and-reorder.input.json
{
  "paymentMethods": [
    { "id": "gid://shopify/PaymentCustomizationPaymentMethod/1", "name": "Credit card" },
    { "id": "gid://shopify/PaymentCustomizationPaymentMethod/2", "name": "PayPal" },
    { "id": "gid://shopify/PaymentCustomizationPaymentMethod/3", "name": "Bank Deposit" }
  ],
  "paymentCustomization": {
    "metafield": {
      "jsonValue": {
        "renames": { "bank deposit": "Bank transfer (2% off, ships after payment)" },
        "order": ["Bank Deposit", "Credit card"]
      }
    }
  }
}
tests/rename-and-reorder.output.json
{
  "operations": [
    {
      "paymentMethodRename": {
        "paymentMethodId": "gid://shopify/PaymentCustomizationPaymentMethod/3",
        "name": "Bank transfer (2% off, ships after payment)"
      }
    },
    { "paymentMethodMove": { "paymentMethodId": "gid://shopify/PaymentCustomizationPaymentMethod/3", "index": 0 } },
    { "paymentMethodMove": { "paymentMethodId": "gid://shopify/PaymentCustomizationPaymentMethod/1", "index": 1 } }
  ]
}

Lintel tarafından yazıldı. MIT lisansı: kendi mağazanızda da müşteri işlerinizde de ücretsiz kullanabilirsiniz.

Sınırlar ve özel durumlar

  • Adı logo olan yöntemler yeniden adlandırılamaz: Shop Pay, Apple Pay, Google Pay, diğer cüzdanlar ve hediye kartı alanı.
  • Cüzdanlar gizlenebilir ama yeniden sıralanamaz; onlar için gönderilen taşıma işlemlerinin etkisi olmaz.
  • Adlar, müşterinin ödeme sayfasında gördüğü haliyle ve büyük/küçük harf ayrımı olmadan eşleşir. Yapılandırmada olup bu ödemede sunulmayan bir yöntem atlanır.
  • Shop Pay içinde ödeme özelleştirmeleri yalnızca hediye kartı alanını etkiler.

Sık sorulan sorular

Shopify ödeme sayfasında ödeme yöntemlerinin sırasını nasıl değiştiririm?
Ödeme ayarlarında sıralama seçeneği yok. Bir ödeme özelleştirme Function’ı her yöntem için konumu belirten paymentMethodMove işlemleri döndürür; bu örnek de bunu yapıyor.
Kapıda ödeme ya da havale yönteminin adını değiştirebilir miyim?
Evet. Kapıda ödeme ve havale gibi manuel yöntemler paymentMethodRename ile yeniden adlandırılabilir. Cüzdanlar ve Shop Pay gibi logo adlı yöntemler adlandırılamaz.
Yeni ad dile göre değişebilir mi?
Bu örnek tek bir ad kullanıyor. Birden fazla dilde satıyorsanız input sorgusuna localization { language { isoCode } } ekleyin ve metafield’da her dil için ayrı bir renames listesi tutun.
  • Function API sürümü 2026-10 için yazıldı ve gösterilen tarihte Shopify’ın başvuru belgeleriyle karşılaştırıldı. Shopify her çeyrekte yeni bir sürüm yayımlar.
  • Function içeren özel (custom) uygulamalar yalnızca Shopify Plus mağazalarında çalışır. Aynı Function herkese açık bir uygulamada, sayfada aksi yazmıyorsa her planda çalışır.
  • Her örnek test verileriyle gelir ve yayımlamadan önce bu testleri çalıştırırız. Kodu değiştirdikten sonra testleri tekrar çalıştırın: shopify app function run.
  • MIT lisansı. Kodu kendi mağazanızda da müşteri işlerinizde de kullanabilirsiniz.

Mağazanız için kurulmasını, test edilmesini ve bakımını isterseniz: Shopify Functions geliştirme.

Geliştirmek istediğiniz bir şey mi var? Gelin, birlikte konuşalım.

Aynı anda sınırlı sayıda proje alıyoruz.

Gencer KarakayaShopify mühendisi

Proje özetinizi bir mühendis okur; size e-postayla yanıt veririz.