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