Headless WooCommerce’de Özel Checkout Oluşturma

Checkout sayfası, gelirin gerçekleştiği veya öldüğü yerdir. Headless WooCommerce’de bunu sıfırdan oluşturuyorsunuz — varsayılan WooCommerce checkout şablonu yok, önceden oluşturulmuş ödeme formu yok, otomatik kargo hesaplama yok. Bu, headless’a geçmenin hem en büyük zorluğu hem de en büyük fırsatıdır.

Checkout Mimarisi

Headless checkout tipik olarak 3-4 adımdan oluşur ve tümü API aracılığıyla WooCommerce ile iletişim kurar:

Cart Review → Shipping Info → Payment → Confirmation

Store API    WC REST API    Stripe/     WC REST API
(cart)       (shipping)    PayPal JS    (create order)

WooCommerce Store API ile Sepet Yönetimi

WooCommerce Store API (WooCommerce 6.0+ ile dahil) headless kullanım için tasarlanmış sepet endpoint’leri sağlar:

// Cart state management (Next.js)
const STORE_API = ${process.env.WP_URL}/wp-json/wc/store/v1;

export async function getCart(nonce) {
const res = await fetch(${STORE_API}/cart, {
credentials: 'include',
headers: { 'Nonce': nonce }
});
return res.json();
}

export async function addToCart(productId, quantity, nonce) {
const res = await fetch(${STORE_API}/cart/add-item, {
method: 'POST',
credentials: 'include',
headers: {
'Content-Type': 'application/json',
'Nonce': nonce
},
body: JSON.stringify({ id: productId, quantity })
});
return res.json();
}

export async function applyCoupon(code, nonce) {
const res = await fetch(${STORE_API}/cart/apply-coupon, {
method: 'POST',
credentials: 'include',
headers: {
'Content-Type': 'application/json',
'Nonce': nonce
},
body: JSON.stringify({ code })
});
return res.json();
}

Önemli: Store API sepet oturumu yönetimi için nonce kullanır. Bunu wc/store/v1/cart yanıt başlığı Nonce‘den alın.

Kargo Hesaplama

WooCommerce, müşterinin adresine göre kargoyu sunucu tarafında hesaplar:

export async function updateShippingAddress(address, nonce) {
const res = await fetch(${STORE_API}/cart/update-customer, {
method: 'POST',
credentials: 'include',
headers: {
'Content-Type': 'application/json',
'Nonce': nonce
},
body: JSON.stringify({
shipping_address: {
first_name: address.firstName,
last_name: address.lastName,
address_1: address.address1,
city: address.city,
state: address.state,
postcode: address.postcode,
country: address.country
}
})
});

const cart = await res.json();
// cart.shipping_rates contains available methods with costs
return cart;
}

Yanıt, seçenek olarak gösterdiğiniz hesaplanmış kargo tarifelerini içerir.

Ödeme Entegrasyonu: Stripe

Stripe, headless WooCommerce için en yaygın ödeme gateway’idir. PCI uyumlu kart toplama için Stripe Elements kullanın:

import { loadStripe } from '@stripe/stripe-js';
import { Elements, CardElement, useStripe, useElements } from '@stripe/react-stripe-js';

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PK);

function CheckoutForm({ cart }) {
const stripe = useStripe();
const elements = useElements();

const handleSubmit = async (e) => {
e.preventDefault();

// 1. Create payment intent on your server
const { clientSecret } = await fetch('/api/create-payment-intent', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ amount: cart.totals.total_price })
}).then(r => r.json());

// 2. Confirm payment with Stripe
const { error, paymentIntent } = await stripe.confirmCardPayment(clientSecret, {
payment_method: {
card: elements.getElement(CardElement),
billing_details: { name: cart.billing_address.first_name }
}
});

if (error) {
setError(error.message);
return;
}

// 3. Create WooCommerce order
if (paymentIntent.status === 'succeeded') {
await createWooCommerceOrder(cart, paymentIntent.id);
}
};

return (
        

            
            Pay ${(cart.totals.total_price / 100).toFixed(2)}
        
);
}

WooCommerce Siparişi Oluşturma

Başarılı ödemeden sonra, WooCommerce REST API aracılığıyla sipariş oluşturun:

async function createWooCommerceOrder(cart, paymentIntentId) {
const orderData = {
payment_method: 'stripe',
payment_method_title: 'Credit Card (Stripe)',
set_paid: true,
transaction_id: paymentIntentId,
billing: cart.billing_address,
shipping: cart.shipping_address,
line_items: cart.items.map(item => ({
product_id: item.id,
variation_id: item.variation?.[0]?.attribute || undefined,
quantity: item.quantity
})),
shipping_lines: [{
method_id: cart.shipping_rates[0]?.rate_id,
method_title: cart.shipping_rates[0]?.name,
total: cart.shipping_rates[0]?.price
}],
coupon_lines: cart.coupons.map(c => ({ code: c.code })),
meta_data: [
{ key: '_stripe_payment_intent', value: paymentIntentId }
]
};

const response = await fetch(${WP_URL}/wp-json/wc/v3/orders, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': Basic ${btoa(${CK}:${CS})}
},
body: JSON.stringify(orderData)
});

return response.json();
}

Checkout UX En İyi Uygulamaları

• Tek sayfalık checkout çoğu mağaza için çok aşamalıdan daha iyi performans gösterir. Ayrı sayfalar yerine akordeon bölümleri kullanın.
• Adres otomatik tamamlama Google Places API aracılığıyla sürtünmeyi ve hataları azaltır.
• Gerçek zamanlı doğrulama — alanları gönderimde değil, blur’da doğrulayın.
• Varsayılan olarak misafir checkout — satın almadan önce hesap oluşturmayı zorlamayın.
• Sipariş özeti her zaman görünür — masaüstünde sepet özetini kenar çubuğunda gösterin.
• Hızlı checkout düğmeleri — Apple Pay, Google Pay ve PayPal’ı sayfa üstünde.

Hata Yönetimi

Checkout hataları müşteri kaybettirir. Her başarısızlığı zarif bir şekilde ele alın:

const ERROR_MESSAGES = {
'card_declined': 'Your card was declined. Please try another card.',
'insufficient_funds': 'Insufficient funds. Please try another payment method.',
'expired_card': 'Your card has expired. Please update your card details.',
'processing_error': 'A processing error occurred. Please try again.',
'stock_error': 'Some items in your cart are no longer available.',
'shipping_error': 'We cannot ship to this address. Please check your details.'
};

Sonuç

Headless checkout, headless WooCommerce yapısının en zor kısmıdır, ancak müşteri deneyimi üzerinde en fazla kontrole sahip olduğunuz yer de burası. Sepet yönetimi için WooCommerce Store API’sını, PCI uyumlu ödemeler için Stripe Elements’i kullanın ve sürtünmeyi azaltmaya amansızca odaklanın. Her ek alan, her gereksiz sayfa yüklemesi, her kafa karıştıran hata mesajı dönüşümlere mal olur. Yalın yapın, gerçek kullanıcılarla test edin ve yineleyin.